@bongos/core 1.24.32 → 1.24.34

package/docs/recipes/hall-sitemap.md

@@ -0,0 +1,52 @@
+# The builders hall sitemap — reading, regenerating and auditing it
+
+[`docs/hall-sitemap.md`](../hall-sitemap.md) is the whole hall on one page: every page, where the sidebar lists it, who may open it, which crafts show it, which crafts can click their way to it, and what links in and out. It is **generated** (task 1005068), so it is never edited by hand and never goes stale quietly.
+
+## Where it comes from
+
+`node scripts/bongos/gen-hall-sitemap.js` reads the real sources and nothing hand-kept:
+
+| What | Read from |
+|---|---|
+| The pages | every `modules/hall-ui/public/*.html` (`index.html` is Home, at `/`) |
+| The sidebar | `shell.js` `NAV` — group, label, link, and the cosmetic nav gate |
+| The crafts | `craft-mode.js`, **run**, asked `tabsFor(craft)` — the same answer the hall uses |
+| Who may open a page | `src/bongos/serve-internal.js` page gates (the parse `tests/hall_page_gate_map.mjs` uses) |
+| The links | every in-hall link in a page's HTML and in each script it loads |
+
+Scripts nearly every page loads (the shell, the palette, the craft switch) are the *chrome*: their links are the sidebar, so they are not counted against each page.
+
+## When to regenerate
+
+Whenever you add, remove or rename a hall page, a nav item, a craft's tabs, or a link between pages:
+
+```bash
+node scripts/bongos/gen-hall-sitemap.js
+```
+
+Commit the changed `docs/hall-sitemap.md` with your change. `tests/hall_sitemap.mjs` fails until you do.
+
+## Auditing it
+
+```bash
+node scripts/bongos/gen-hall-sitemap.js --audit
+```
+
+prints one line per finding and exits 1 if any link is broken. What each finding asks of you:
+
+| Finding | Means | Do |
+|---|---|---|
+| **broken** | a link to a URL the hall does not serve | fix the link; if the server really does serve it (a redirect, a `/x/:id` route), add it to `ROUTES` in the generator with where it is served |
+| **orphan** | a page with no nav item that no page links to | link it from where a reader would look for it, or retire the page |
+| **unclickable** | no craft reaches the page by clicking from its sidebar | it is only found by typing its URL — usually an orphan's cousin |
+| **hidden** | a nav item no craft lists | only the hall with no craft chosen shows it; add it to a craft in `craft-mode.js` `MODE_TABS`, or to `ALWAYS_TABS` |
+| **dangling** | a craft lists a tab id with no nav item | the craft's list has drifted from `shell.js` `NAV`; fix the id |
+
+Broken and dangling fail the test. The other three are judgement calls, which is why they are reported rather than enforced: read them on each regenerate and decide.
+
+## Reading it for "does this make sense?"
+
+- **The crafts table** is each craft's slice of the hall and its Home. Choosing a craft on a page only other crafts show goes to that craft's Home (task 1005067).
+- **Shown in vs reach** on a page row: *shown in* is the crafts whose sidebar lists it; *reach* adds the crafts that get there through a link. A page reached by every craft but shown by one is a page the others find only by accident.
+- **Nav gate vs server gate**: the nav gate only hides the item; the server gate is the wall. A page whose nav gate is narrower than its server gate is visible to more people than the sidebar suggests; `null` on the server means the shell is served to anyone and the data behind it holds the line.
+- **In 0** beside a nav item means the sidebar is the only way there.

package/modules/hall-ui/public/craft-mode.js

@@ -209,6 +209,55 @@
       else head.removeAttribute('data-craft-off');
     }
   }
+  // ---------- each craft's home (task 1005067) ----------
+  // Choosing a craft used to re-skin the page you were on and leave you there, so a
+  // governor on the city who picked Building stayed in the governor's city under the
+  // builder's nav (owner, 2026-11-04). Now a page that belongs ONLY to other crafts —
+  // in their tabs and not the chosen one's — is left for Home, which draws each
+  // craft's own dashboard (home-city.js: the city, the gallery, the sky, and the
+  // street for Governing, its dashboard for now). A shared page (ALWAYS_TABS, or one
+  // in both crafts' lists) and a page no craft owns (a task, an idea) stay put; so
+  // does Home, which redraws itself in place. The street has no nav item, so it is
+  // named here as Governing's. Tests swap the hop for a recorder (OTBCraftHop).
+  var OWN_PAGES = { governing: ['street'] };
+  function pageKeys() {
+    var keys = [];
+    var nav = document.getElementById('app-sidebar');
+    var active = nav && nav.querySelector ? nav.querySelector('.nav-item--active') : null;
+    if (active && active.id) keys.push(String(active.id).replace(/^nav-/, ''));
+    var b = document.body;
+    var page = b && b.getAttribute ? b.getAttribute('data-page') : null;
+    if (page) keys.push(page);
+    return keys;
+  }
+  function ownersOf(key) {
+    if (ALWAYS_TABS.indexOf(key) !== -1) return null;
+    var owners = [];
+    IDS.forEach(function (m) {
+      if ((MODE_TABS[m] || []).indexOf(key) !== -1 || (OWN_PAGES[m] || []).indexOf(key) !== -1) owners.push(m);
+    });
+    return owners.length ? owners : null;
+  }
+  // Does choosing `mode` strand the reader on another craft's page?
+  function strandedBy(mode) {
+    var keys = pageKeys();
+    if (keys.indexOf('home') !== -1) return false;
+    for (var i = 0; i < keys.length; i++) {
+      var owners = ownersOf(keys[i]);
+      if (owners) return owners.indexOf(mode) === -1;
+    }
+    return false;
+  }
+  function homeHref(mode) {
+    var street = mode === 'governing' && window.GovCity && window.GovCity.STREET_HREF;
+    return street || '/';
+  }
+  function goHome(mode) {
+    if (!strandedBy(mode)) return false;
+    (window.OTBCraftHop || function (h) { if (window.location) window.location.assign(h); })(homeHref(mode));
+    return true;
+  }
+
   // ---------- each mode's look (task 1004495) ----------
   // Artistry, Ideating and Governing each wear a look: the colour tokens in
   // style.css (keyed on html[data-craft]), plus two things only this script can
@@ -216,20 +265,29 @@
   // under the brand (artHtml, the picker's own art, so the two never drift).
   // Building and no mode have no entry here and wear nothing.
   var LOOKS = { artistry: 'the studio · night', ideating: 'the sky', governing: 'the city' };
+  // The plate is the Home button in every mode (owner, 2026-11-04, task 1005065): the
+  // mode's scene with a home mark over it. Building wears no look, so its plate shows
+  // the city, the scene its Home is.
+  var PLATE_ART = { building: 'governing', artistry: 'artistry', ideating: 'ideating', governing: 'governing' };
+  var HOME_MARK = '<span class="craft-plate__home" aria-hidden="true"><svg viewBox="0 0 18 18" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linejoin="round">' +
+    '<path d="M3 8.5 9 3l6 5.5V15a1 1 0 0 1-1 1h-3.5v-4h-3v4H4a1 1 0 0 1-1-1V8.5Z"/></svg></span>';
   function remove(el) { if (el && el.parentNode) el.parentNode.removeChild(el); }
   function applyLook(mode) {
     var look = Object.prototype.hasOwnProperty.call(LOOKS, mode) ? LOOKS[mode] : null;
+    var art = Object.prototype.hasOwnProperty.call(PLATE_ART, mode) ? PLATE_ART[mode] : null;
     var plate = document.getElementById('craft-plate');
-    if (plate && plate.getAttribute('data-plate') !== (look ? mode : null)) { remove(plate); plate = null; }
+    if (plate && plate.getAttribute('data-plate') !== (art ? mode : null)) { remove(plate); plate = null; }
     var nav = document.getElementById('app-sidebar');
-    var brand = look && nav && nav.querySelector ? nav.querySelector('.app-sidebar__brand') : null;
+    var brand = art && nav && nav.querySelector ? nav.querySelector('.app-sidebar__brand') : null;
     if (!plate && brand && brand.parentNode) {
-      plate = document.createElement('div');
+      plate = document.createElement('a');
       plate.id = 'craft-plate';
       plate.className = 'craft-plate';
+      plate.setAttribute('href', '/');
+      plate.setAttribute('aria-label', 'Home');
+      plate.setAttribute('title', 'Home');
       plate.setAttribute('data-plate', mode);
-      plate.setAttribute('aria-hidden', 'true');
-      plate.innerHTML = artHtml(mode);
+      plate.innerHTML = artHtml(art) + HOME_MARK;
       brand.parentNode.insertBefore(plate, brand.nextSibling);
     }
     var mark = document.getElementById('craft-eyebrow');
@@ -570,6 +628,7 @@
     else if (keep === false) drop('localStorage', KEEP_KEY);
     else if (get('localStorage', KEEP_KEY)) set('localStorage', KEEP_KEY, mode);
     apply(mode);
+    goHome(mode);
   }
 
   // ---------- the header switch ----------
@@ -790,6 +849,9 @@
     ALWAYS_TABS: ALWAYS_TABS.slice(),
     tabsFor: tabsFor,
     applyNav: applyNav,
+    // task 1005067: whether choosing a craft leaves this page for its Home, and where Home is.
+    strandedBy: strandedBy,
+    homeHref: homeHref,
     LOOKS: LOOKS,
     artHtml: artHtml,
     tallyHtml: tallyHtml,

package/modules/hall-ui/public/style.css

@@ -1614,6 +1614,9 @@ html:is([data-craft="artistry"], [data-craft="ideating"], [data-craft="governing
    never redrawn: each scene's pieces are placed from its edges or its centre. */
 .craft-plate {
   position: relative;
+  display: block;
+  color: inherit;
+  text-decoration: none;
   height: 40px;
   margin: 10px 8px 0;
   border-radius: var(--radius-sm);
@@ -1631,6 +1634,26 @@ html:is([data-craft="artistry"], [data-craft="ideating"], [data-craft="governing
   transform-origin: 0 0;
 }
 .craft-plate .craft-art__city { top: 0; }
+/* At the plate's size the studio's houses vanished into the night (owner, 2026-11-04):
+   lift them off the sky so the scene reads. The picker's larger door is unchanged. */
+.craft-plate .craft-art__house { background: #232b4d; }
+/* The plate is the Home button (task 1005065): a home mark sits over the scene. */
+.craft-plate__home {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  width: 24px;
+  height: 24px;
+  margin: -12px 0 0 -12px;
+  display: grid;
+  place-items: center;
+  border-radius: 999px;
+  color: #fff;
+  background: var(--scrim);
+}
+.craft-plate__home svg { width: 14px; height: 14px; }
+.craft-plate:hover .craft-plate__home { background: rgba(0, 0, 0, .8); }
+.craft-plate:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
 .app-sidebar:hover .craft-plate,
 .app-sidebar:focus-within .craft-plate { height: 64px; margin: 10px 16px 0; }
 .app-sidebar:hover .craft-plate .craft-art,

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.32",
+  "version": "1.24.34",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.24.32",
+      "version": "1.24.34",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.32",
+  "version": "1.24.34",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -11151,5 +11151,21 @@
       "id": "1005064",
       "text": "The governor's Home is now the street: choosing Owner on Home takes you straight to it, so each of the four crafts has its own Home."
     }
+  ],
+  "1.24.33": [
+    {
+      "id": "1005065",
+      "text": "The small picture at the top of the sidebar is now the Home button in every mode, with a home icon on it."
+    }
+  ],
+  "1.24.34": [
+    {
+      "id": "1005067",
+      "text": "Switching mode now takes you to that mode's own home page instead of leaving you stuck on the governor's city."
+    },
+    {
+      "id": "1005068",
+      "text": "The builders hall now has a generated map of every page and link, with a check that flags broken links and pages nobody can reach."
+    }
   ]
 }

package/scripts/bongos/gen-hall-sitemap.js

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+'use strict';
+// gen-hall-sitemap.js — the builders hall's sitemap, generated, and the audit of its links
+// (task 1005068, goal 1000095).
+//
+// WHY. The hall is ~70 pages, a nav grouped by audience (shell.js NAV), four crafts that each
+// show a slice of that nav (craft-mode.js), and links written into every page's markup and
+// script. Each of those is tested on its own (hall_nav: every nav href is a real page;
+// hall_page_gate_map: every page has a server gate), but nothing drew the whole picture, so
+// "how does everything link, and does it make sense?" had no answer short of reading 300 files.
+// The owner asked for one on 2026-11-04.
+//
+// WHAT IT READS — the real sources, never a hand-kept list:
+//   • the pages: every modules/hall-ui/public/*.html (index.html is Home, at /);
+//   • the nav: shell.js NAV, parsed statically (group, id, label, href, gate);
+//   • the crafts: craft-mode.js RUN in a vm, asked tabsFor(mode) — the same answer the hall uses;
+//   • the server's page gates: serve-internal.js's *_PAGE_RE literals and their gdsAuth
+//     dispatch, the static parse tests/hall_page_gate_map.mjs established;
+//   • the links: every in-hall href in a page's HTML and in each script the page loads.
+// Scripts nearly every page loads (the shell, the palette, the craft switch) are the CHROME: their
+// links are the nav, reported once, never charged to every page.
+//
+// WHAT IT WRITES — docs/hall-sitemap.md: the crafts and their homes, the findings, one row per
+// page (nav place, gates, crafts that show it, crafts that can click their way to it, links in and
+// out), and the server routes that are not page files. Deterministic (sorted, no timestamps), so
+// --check is a clean freshness gate; tests/hall_sitemap.mjs runs it and fails on a broken link.
+//
+// THE FINDINGS, and what each one asks of you (docs/recipes/hall-sitemap.md has the long form):
+//   broken      a link to a URL the hall does not serve — fix the link, or add the route to ROUTES.
+//   orphan      a page nothing links to and no nav item shows — link it, or retire it.
+//   unclickable a page no craft can reach by clicking — a page only a typed URL finds.
+//   hidden      a nav item no craft shows — only the no-craft hall sees it.
+//   dangling    a craft tab id with no nav item — the craft lists a tab that does not exist.
+//
+// Usage:
+//   node scripts/bongos/gen-hall-sitemap.js           # regenerate docs/hall-sitemap.md
+//   node scripts/bongos/gen-hall-sitemap.js --check   # write nothing; exit 2 if it WOULD change
+//   node scripts/bongos/gen-hall-sitemap.js --audit   # print the findings; exit 1 on a broken link
+//   node scripts/bongos/gen-hall-sitemap.js --json    # print the model (debug)
+
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const HALL = 'modules/hall-ui/public';
+const OUT = 'docs/hall-sitemap.md';
+const CRAFTS = ['building', 'artistry', 'ideating', 'governing'];
+
+// URLs the server answers that are not a page file in the hall. A link to one is not broken.
+// A NEW route a page links to belongs here, with where the server serves it; the audit fails
+// until it is named, which is the point: an unknown target is a broken link until proven not.
+const ROUTES = {
+  '/task': { to: 'task.html', why: '/task/:id, the task page (serve-internal.js)' },
+  '/idea': { to: 'idea.html', why: '/idea/:id, the idea page (serve-internal.js)' },
+  '/people': { to: '/roster', why: 'retired directory, redirects (task 1003444)' },
+  '/scouting': { to: '/roster', why: 'retired directory, redirects (task 1003440)' },
+  '/board': { to: '/work', why: 'old name of the Work board, redirects' },
+  '/sky': { to: '/thinking', why: 'old name, redirects' },
+  '/market-watch-settings': { to: '/market-watch', why: 'now a Settings tab, redirects (task 1005045)' },
+};
+// Targets that leave the hall on purpose: sign-in, the hub's /account (platform-server.js;
+// settings.js points the link at the hub), the API, module assets, and any file with an extension.
+const EXTERNAL = [/^\/api\//, /^\/auth\b/, /^\/login\b/, /^\/logout\b/, /^\/signin\b/, /^\/status\b/,
+  /^\/account\b/, /^\/modules\//, /^\/docs\b/, /^\/diagrams\//, /^\/healthz\b/, /^\/version\b/, /\.[a-z0-9]{2,5}$/i];
+
+function read(rel) { return fs.readFileSync(path.join(ROOT, rel), 'utf8'); }
+
+// ---- the pages ----
+function readPages() {
+  return fs.readdirSync(path.join(ROOT, HALL)).filter((f) => f.endsWith('.html')).sort().map((f) => {
+    const name = f.replace(/\.html$/, '');
+    const html = read(`${HALL}/${f}`);
+    const title = (/<title>([^<]*)<\/title>/.exec(html) || [])[1] || '';
+    const scripts = [...html.matchAll(/<script[^>]*\ssrc="\/builders\/([a-z0-9-]+\.js)/g)].map((m) => m[1]);
+    return {
+      name, file: f, url: name === 'index' ? '/' : `/${name}`, html,
+      title: title.replace(/\s*[—-]\s*\{\{worldName\}\}\s*$/, '').trim(),
+      scripts: [...new Set(scripts)],
+    };
+  });
+}
+
+// ---- the nav (shell.js NAV, read statically) ----
+function readNav() {
+  const src = read(`${HALL}/shell.js`);
+  const start = src.indexOf('var NAV = [');
+  const body = src.slice(start, src.indexOf('\n  ];', start));
+  const items = [];
+  let group = '';
+  for (const line of body.split('\n')) {
+    const g = /\{ group: '([^']*)'/.exec(line);
+    if (g) group = g[1];
+    const it = /\{ id: '([a-z0-9-]+)', label: '((?:\\'|[^'])*)'[^}]*?href: '([^']*)'[^}]*?gate: '([^']*)'/.exec(line);
+    if (it) items.push({ id: it[1], label: it[2].replace(/\\'/g, "'"), href: it[3], gate: it[4], group: group || '(project)', module: (/module: '([^']*)'/.exec(line) || [])[1] || null });
+  }
+  return items;
+}
+
+// ---- the crafts (craft-mode.js, run) ----
+function readCrafts() {
+  const noop = () => {};
+  const el = () => ({ setAttribute: noop, getAttribute: () => null, removeAttribute: noop, hasAttribute: () => false, appendChild: noop, querySelector: () => null, querySelectorAll: () => [], classList: { toggle: noop, add: noop, remove: noop }, dataset: {} });
+  const window = { OTB: { escapeHtml: String }, matchMedia: () => ({ matches: false }), location: { search: '' } };
+  window.window = window;
+  const document = { body: el(), head: el(), documentElement: el(), getElementById: () => null, querySelector: () => null, querySelectorAll: () => [], createElement: el, addEventListener: noop };
+  vm.runInNewContext(read(`${HALL}/craft-mode.js`), { window, document, CustomEvent: noop, Promise, console });
+  const CM = window.OTBCraftMode;
+  const tabs = {};
+  for (const c of CRAFTS) tabs[c] = CM.tabsFor(c);
+  return { tabs, always: CM.ALWAYS_TABS };
+}
+
+// ---- the server's page gates (the hall_page_gate_map.mjs parse) ----
+function readGates() {
+  const src = read('src/bongos/serve-internal.js');
+  const rx = new Map();
+  const re = /const\s+([A-Z0-9_]+_RE)\s*=\s*(\/(?:\\.|\[(?:\\.|[^\]])*\]|[^/\\])+\/[gimsuy]*)\s*;/g;
+  // Its only input is this repo's own serve-internal.js, read from a fixed path: never a
+  // caller's string. Keep it that way (the same note hall_page_gate_map.mjs carries).
+  for (const m of src.matchAll(re)) rx.set(m[1], eval(m[2])); // eslint-disable-line no-eval
+  const dispatch = [];
+  for (const m of src.matchAll(/if\s*\(([^{};]*?)\)\s*\{\s*return\s+gdsAuth\.(\w+)\(req,\s*res,\s*next\);/g)) {
+    const names = [...m[1].matchAll(/([A-Z0-9_]+_RE)/g)].map((x) => x[1]);
+    if (names.length) dispatch.push({ names, gate: m[2] });
+  }
+  return (url) => {
+    const full = url === '/' ? '/builders/' : `/builders${url}`;
+    for (const { names, gate } of dispatch) for (const n of names) if (rx.get(n) && rx.get(n).test(full)) return gate;
+    return null;
+  };
+}
+
+// ---- the links ----
+// An in-hall link, written any of the ways the hall writes one. Root-relative only; a link
+// built from a variable is not a fact this file can read, so it is not guessed at.
+const LINK_RES = [
+  /href=\\?["'](\/[^"'\\\s$`{]*)/g,                         // markup, in HTML or in a script's strings
+  // href="${hallBase()}/x", the base resolved at run time; a ${hub…} base is the hub's page, not ours
+  /href=\\?["']\$\{(?![^}]*\bhub)[^}]*\}(\/[a-z0-9-][^"'\\\s$`{]*)/g,
+  /Href\([^)]*\)\s*\{\s*return\s+'(\/[^'\s$]*)'/g,               // function itemHref(id) { return '/x?id=' + … }
+  /\bhref\s*:\s*'(\/[^'\s$]*)'/g,                            // { href: '/x' }
+  /\.href\s*=\s*'(\/[^'\s$]*)'/g,                            // a.href = '/x'
+  /setAttribute\(\s*'href'\s*,\s*'(\/[^'\s$]*)'/g,          // setAttribute('href', '/x')
+  /location\.(?:assign|replace)\(\s*'(\/[^'\s$]*)'/g,       // location.assign('/x')
+  /\b[A-Z_]*HREF\s*=\s*'(\/[^'\s$]*)'/g,                     // const STREET_HREF = '/x'
+  /'(\/builders\/[a-z0-9-]+(?:[/?#][^'\s$]*)?)'/g,           // any '/builders/<page>' literal
+];
+function linksIn(src) {
+  const out = new Set();
+  for (const re of LINK_RES) for (const m of src.matchAll(re)) out.add(m[1]);
+  return [...out];
+}
+// '/builders/goals?x#y' → '/goals'; '/task/12' → '/task'; '/#standing' → '/'
+function normalise(href) {
+  let p = href.replace(/[?#].*$/, '').replace(/^\/builders(?=\/|$)/, '') || '/';
+  p = p.replace(/\.html$/, '');
+  if (p.length > 1) p = p.replace(/\/+$/, '');
+  const seg = p.split('/').filter(Boolean);
+  return seg.length ? '/' + seg[0] : '/';
+}
+
+// Where a link lands: the page's URL, null when it leaves the hall on purpose, false when broken.
+function classify(href, pageUrls) {
+  const t = normalise(href);
+  if (pageUrls.has(t)) return t;
+  if (ROUTES[t]) return ROUTES[t].to.endsWith('.html') ? '/' + ROUTES[t].to.replace(/\.html$/, '') : ROUTES[t].to;
+  if (EXTERNAL.some((re) => re.test(href.replace(/[?#].*$/, '').replace(/^\/builders/, '')))) return null;
+  return false;
+}
+
+function build() {
+  const pages = readPages();
+  const nav = readNav();
+  const crafts = readCrafts();
+  const gateOf = readGates();
+  const byUrl = new Map(pages.map((p) => [p.url, p]));
+
+  // the chrome: scripts at least three quarters of the pages load
+  const loads = {};
+  for (const p of pages) for (const s of p.scripts) loads[s] = (loads[s] || 0) + 1;
+  const chrome = Object.keys(loads).filter((s) => loads[s] >= pages.length * 0.75).sort();
+
+  const scriptLinks = {};
+  const linksOf = (s) => {
+    if (!(s in scriptLinks)) {
+      const f = path.join(ROOT, HALL, s);
+      scriptLinks[s] = fs.existsSync(f) ? linksIn(fs.readFileSync(f, 'utf8')) : [];
+    }
+    return scriptLinks[s];
+  };
+
+  const broken = [];
+  const resolve = (href, from, via) => {
+    const t = classify(href, byUrl);
+    if (t === false) broken.push({ from, via, href });
+    return t || null;
+  };
+
+  // links each page makes itself (its HTML and its own scripts), chrome left out
+  const out = new Map(pages.map((p) => [p.url, new Map()]));
+  for (const p of pages) {
+    const add = (href, via) => {
+      const t = resolve(href, p.url, via);
+      if (t && t !== p.url) {
+        const vias = out.get(p.url).get(t) || new Set();
+        vias.add(via);
+        out.get(p.url).set(t, vias);
+      }
+    };
+    for (const h of linksIn(p.html)) add(h, p.file);
+    for (const s of p.scripts) if (!chrome.includes(s)) for (const h of linksOf(s)) add(h, s);
+  }
+  // the chrome's own links that are not nav items are checked too (the palette, the shell)
+  for (const s of chrome) for (const h of linksOf(s)) resolve(h, '(every page)', s);
+
+  const navById = new Map(nav.map((n) => [n.id, n]));
+  const navByUrl = new Map();
+  for (const n of nav) {
+    const t = resolve(n.href, '(nav)', 'shell.js NAV');
+    if (t) navByUrl.set(t, [...(navByUrl.get(t) || []), n]);
+  }
+
+  // what each craft's nav shows, and what it can click its way to from there
+  const shows = {}, reach = {};
+  for (const c of CRAFTS) {
+    const ids = crafts.tabs[c];
+    shows[c] = new Set(ids.filter((id) => navById.has(id)).map((id) => normalise(navById.get(id).href)));
+    shows[c].add('/'); // the Home plate, in every craft
+    const seen = new Set(shows[c]);
+    const queue = [...seen];
+    while (queue.length) {
+      const u = queue.shift();
+      for (const t of (out.get(u) || new Map()).keys()) if (!seen.has(t)) { seen.add(t); queue.push(t); }
+    }
+    reach[c] = seen;
+  }
+
+  const inbound = new Map(pages.map((p) => [p.url, new Set()]));
+  for (const [from, ts] of out) for (const t of ts.keys()) if (inbound.has(t)) inbound.get(t).add(from);
+
+  const rows = pages.map((p) => {
+    const items = navByUrl.get(p.url) || [];
+    return {
+      url: p.url, file: p.file, title: p.title,
+      nav: items.map((n) => `${n.group} › ${n.label}`),
+      navGate: [...new Set(items.map((n) => n.gate))],
+      serverGate: gateOf(p.url),
+      shownIn: CRAFTS.filter((c) => shows[c].has(p.url)),
+      reachIn: CRAFTS.filter((c) => reach[c].has(p.url)),
+      out: [...out.get(p.url).keys()].sort(),
+      in: [...inbound.get(p.url)].sort(),
+    };
+  });
+
+  const inAnyCraft = new Set(CRAFTS.flatMap((c) => crafts.tabs[c]));
+  const findings = {
+    broken: dedupe(broken).sort((a, b) => (a.from + a.href).localeCompare(b.from + b.href)),
+    orphan: rows.filter((r) => r.url !== '/' && !r.nav.length && !r.in.length).map((r) => r.url),
+    unclickable: rows.filter((r) => !r.reachIn.length).map((r) => r.url),
+    hidden: nav.filter((n) => !inAnyCraft.has(n.id)).map((n) => n.id),
+    dangling: [...inAnyCraft].filter((id) => !navById.has(id)).sort(),
+  };
+  return { pages: rows, nav, crafts, chrome, findings };
+}
+
+function dedupe(list) {
+  const seen = new Set();
+  return list.filter((b) => { const k = `${b.from}|${b.via}|${b.href}`; if (seen.has(k)) return false; seen.add(k); return true; });
+}
+
+// ---- the document ----
+const CRAFT_NAME = { building: 'Building', artistry: 'Artistry', ideating: 'Ideating', governing: 'Governing' };
+const CRAFT_HOME = {
+  building: '/ — the project city',
+  artistry: '/ — the gallery',
+  ideating: '/ — the sky over the city',
+  governing: '/street — the governor\'s street (Home hops there)',
+};
+function list(xs) { return xs.length ? xs.map((x) => '`' + x + '`').join(', ') : '—'; }
+function render(m) {
+  const L = [];
+  const f = m.findings;
+  L.push('# Builders hall sitemap');
+  L.push('');
+  L.push('> **Generated** by `node scripts/bongos/gen-hall-sitemap.js` — do not hand-edit; regenerate. How to read it and what to do about a finding: [`docs/recipes/hall-sitemap.md`](recipes/hall-sitemap.md). `tests/hall_sitemap.mjs` fails when this file is stale or a link is broken.');
+  L.push('');
+  L.push(`${m.pages.length} pages · ${m.nav.length} nav items · ${m.pages.reduce((n, p) => n + p.out.length, 0)} page-to-page links · chrome on every page: ${list(m.chrome)}`);
+  L.push('');
+  L.push('## The crafts');
+  L.push('');
+  L.push('Choosing a craft from the top-bar switch shows its tabs; on a page only other crafts show, it goes to the craft\'s Home (task 1005067).');
+  L.push('');
+  L.push('| Craft | Home (its dashboard) | Tabs in the nav | Pages it can click to |');
+  L.push('|---|---|---|---|');
+  for (const c of CRAFTS) {
+    const own = m.crafts.tabs[c].filter((id) => !m.crafts.always.includes(id));
+    L.push(`| ${CRAFT_NAME[c]} | ${CRAFT_HOME[c]} | ${list(own)} | ${m.pages.filter((p) => p.reachIn.includes(c)).length} |`);
+  }
+  L.push(`| *every craft* | | ${list(m.crafts.always)} | |`);
+  L.push('');
+  L.push('## Findings');
+  L.push('');
+  L.push(`- **Broken links (${f.broken.length})** — a link to a URL the hall does not serve.`);
+  for (const b of f.broken) L.push(`  - \`${b.href}\` in \`${b.via}\` (${b.from})`);
+  L.push(`- **Orphan pages (${f.orphan.length})** — no nav item and no page links to them: ${list(f.orphan)}`);
+  L.push(`- **Unclickable pages (${f.unclickable.length})** — no craft reaches them by clicking from its nav: ${list(f.unclickable)}`);
+  L.push(`- **Nav items no craft shows (${f.hidden.length})** — only the hall with no craft chosen sees them: ${list(f.hidden)}`);
+  L.push(`- **Craft tabs with no nav item (${f.dangling.length}):** ${list(f.dangling)}`);
+  L.push('');
+  L.push('## Pages');
+  L.push('');
+  L.push('*Nav* is where the sidebar lists it; *nav gate* who the sidebar shows it to (cosmetic); *server gate* the wall the server holds (`null` = the shell is served to anyone). *Shown in* is the crafts whose nav lists it; *reach* the crafts that can click their way to it.');
+  L.push('');
+  L.push('| Page | File | Nav | Nav gate | Server gate | Shown in | Reach | In | Out |');
+  L.push('|---|---|---|---|---|---|---|---|---|');
+  for (const p of m.pages) {
+    L.push(`| \`${p.url}\` ${p.title ? '<br>' + p.title.replace(/\|/g, '\\|') : ''} | ${p.file} | ${p.nav.join('<br>') || '—'} | ${p.navGate.join(', ') || '—'} | ${p.serverGate || 'null'} | ${p.shownIn.map((c) => CRAFT_NAME[c]).join(', ') || '—'} | ${p.reachIn.map((c) => CRAFT_NAME[c]).join(', ') || '—'} | ${p.in.length} | ${p.out.length} |`);
+  }
+  L.push('');
+  L.push('## Links');
+  L.push('');
+  L.push('Each page\'s own links (its markup and the scripts it loads, the chrome left out), then the pages that link to it.');
+  L.push('');
+  for (const p of m.pages) {
+    L.push(`### \`${p.url}\``);
+    L.push('');
+    L.push(`- → ${list(p.out)}`);
+    L.push(`- ← ${list(p.in)}`);
+    L.push('');
+  }
+  L.push('## Server routes that are not page files');
+  L.push('');
+  L.push('| URL | Serves | Why |');
+  L.push('|---|---|---|');
+  for (const [u, r] of Object.entries(ROUTES).sort()) L.push(`| \`${u}\` | \`${r.to}\` | ${r.why} |`);
+  L.push('');
+  return L.join('\n');
+}
+
+function main(argv) {
+  const m = build();
+  const text = render(m);
+  const dest = path.join(ROOT, OUT);
+  if (argv.includes('--json')) { process.stdout.write(JSON.stringify(m, null, 2) + '\n'); return 0; }
+  if (argv.includes('--audit')) {
+    const f = m.findings;
+    for (const b of f.broken) console.log(`broken      ${b.href}  in ${b.via} (${b.from})`);
+    for (const u of f.orphan) console.log(`orphan      ${u}`);
+    for (const u of f.unclickable) console.log(`unclickable ${u}`);
+    for (const id of f.hidden) console.log(`hidden      nav item '${id}'`);
+    for (const id of f.dangling) console.log(`dangling    craft tab '${id}'`);
+    console.log(`${f.broken.length} broken · ${f.orphan.length} orphan · ${f.unclickable.length} unclickable · ${f.hidden.length} hidden · ${f.dangling.length} dangling`);
+    return f.broken.length ? 1 : 0;
+  }
+  const cur = fs.existsSync(dest) ? fs.readFileSync(dest, 'utf8') : null;
+  if (argv.includes('--check')) {
+    if (cur === text) return 0;
+    console.error(`${OUT} is stale — run: node scripts/bongos/gen-hall-sitemap.js`);
+    return 2;
+  }
+  if (cur !== text) fs.writeFileSync(dest, text);
+  console.log(`${OUT}: ${m.pages.length} pages, ${m.findings.broken.length} broken links`);
+  return 0;
+}
+
+module.exports = { build, render, normalise, linksIn, classify, ROUTES, OUT };
+if (require.main === module) process.exit(main(process.argv.slice(2)));

package/scripts/gds/gen-hall-sitemap.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// scripts/gds/gen-hall-sitemap.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/gen-hall-sitemap.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'gen-hall-sitemap.js');

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.32'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.34'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');