@bongos/core 1.20.44 → 1.20.46

package/src/bongos/routes/modules.js

@@ -32,6 +32,9 @@
 //                               the server end of `bongos module install` (task
 //                               1003785): take the entitlement, download the
 //                               checked tarball, record the version placed.
+//   GET  /store/modules/:key/versions/:version/howto
+//                               the HOWTO.md that version shipped with, as text for
+//                               the hall's how-to page (task 1004366, ADR 0347).
 //
 // Read is open to any signed-in builder (same gate as the atlas/primer pages);
 // every write (enable/disable, submit) is metic+archon, same rank as
@@ -78,7 +81,7 @@ const moduleArtifact = require('../../../scripts/gds/module-artifact');
 const { checkEntitlement, listEntitlements, grantEntitlement, recordAcquired } = require('../module-entitlements');
 const {
   stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
-  resolveAcquirable, versionArtifactFile,
+  resolveAcquirable, resolveReadable, publishedVersionSet, versionArtifactFile,
 } = require('../module-store');
 const { KEY_RE } = require('../../module-loader/manifest-schema');
 const { parseVersion } = require('../../module-loader/semver');
@@ -146,8 +149,20 @@ function listModules() {
   });
 }
 
+// How many checked how-tos one router keeps in memory (task 1004366). Each is one
+// module's HOWTO.md text, so a few hundred is well under a megabyte; past the cap
+// the oldest entry is dropped.
+const HOWTO_CACHE_MAX = 200;
+
 module.exports = function buildModulesRouter() {
   const router = express.Router();
+  // Checked how-tos by "key@version:tarball_sha256". Per router, so a test's fresh
+  // router starts empty.
+  const howtoCache = new Map();
+  const rememberHowto = (k, v) => {
+    howtoCache.set(k, v);
+    if (howtoCache.size > HOWTO_CACHE_MAX) howtoCache.delete(howtoCache.keys().next().value);
+  };
 
   // rank: any-builder — list every on-disk module with attribution + provenance (same read gate as the atlas/primer pages).
   router.get('/modules', auth.requireBuilder, asyncHandler('GET /modules', async (_req, res) => {
@@ -160,11 +175,22 @@ module.exports = function buildModulesRouter() {
     const sources = (resolvedSet && resolvedSet.sources) || {};
     const overrideRows = await listOverrides();
     const byKey = new Map(overrideRows.map((r) => [r.module_key, r]));
+    // Which on-disk modules are a published store version, so the row can link that
+    // version's how-to page (task 1004366). Failure-tolerant like the override read:
+    // a store that cannot be read costs the link, never the tab.
+    let published = new Set();
+    try { published = await publishedVersionSet(all.map((m) => m.key)); }
+    catch (e) { log.warn({ err: e.message }, 'store versions unreadable for the modules list'); }
     for (const m of all) {
       m.enabled_source = sources[m.key] || 'default';
       m.override = byKey.has(m.key)
         ? { enabled: byKey.get(m.key).enabled, set_by: byKey.get(m.key).set_by_login || null, set_at: byKey.get(m.key).set_at }
         : null;
+      // Only a module in THIS instance's tree: install places store modules there, so
+      // a core-shipped module that happens to share a store key@version never links.
+      m.store_howto = m.source === 'instance' && m.version && published.has(`${m.key}@${m.version}`)
+        ? `/builders/modules?howto=${encodeURIComponent(m.key)}&version=${encodeURIComponent(String(m.version))}`
+        : null;
     }
     res.json({
       modules: all,
@@ -475,6 +501,70 @@ module.exports = function buildModulesRouter() {
       res.send(buf);
     }));
 
+  // GET /api/bongos/store/modules/:key/versions/:version/howto — the how-to a version
+  // shipped with (task 1004366, ADR 0347 D1/D3), read from that version's own stored
+  // tarball after the install hash check, so it always matches the version and cannot
+  // change after publishing. Returns the markdown as TEXT, never HTML: the hall's
+  // Modules tab renders it through its one escaping markdown reader (md-reader.js),
+  // because the file is author-written and must be treated as untrusted input.
+  //
+  // rank: any-builder — no entitlement needed, since a buyer reads the how-to before
+  // deciding. The one exception is a delisted module: ADR 0338 D2 keeps it readable
+  // only for the people who already hold it, so there the caller's own entitlement
+  // is checked (own-scoped, like the reads above).
+  router.get('/store/modules/:key/versions/:version/howto', auth.requireBuilder,
+    asyncHandler('GET /store/modules/:key/versions/:version/howto', async (req, res) => {
+      const { key, version } = req.params;
+      if (!KEY_RE.test(key) || !parseVersion(version)) {
+        return res.fail('bad_request', { status: 400, message: 'A module key is lowercase kebab-case and a version is exact X.Y.Z.' });
+      }
+      const r = await resolveReadable(key, version);
+      if (!r.ok) return res.fail(r.code, { status: r.status, message: r.message });
+      const delisted = r.module.status === 'delisted';
+      if (delisted) {
+        const held = await checkEntitlement({ moduleKey: key, holderKind: 'builder', holderRef: String(req.builder.id) });
+        if (!held.entitled) {
+          return res.fail('module_delisted', { status: 409, message: `"${key}" is delisted: its how-to stays readable only for people who already hold it (ADR 0338 D2).` });
+        }
+      }
+      // A published version never changes, so its checked how-to is cached by the
+      // tarball hash the registry holds: the inflate + hash check runs once per
+      // version per process, not on every page view.
+      const cacheKey = `${key}@${version}:${r.version.tarball_sha256}`;
+      let h = howtoCache.get(cacheKey);
+      if (!h) {
+        let buf;
+        try { buf = await fs.promises.readFile(versionArtifactFile(r.version)); }
+        catch (e) {
+          log.error({ key, version, err: e.message }, 'store tarball missing');
+          return res.fail('artifact_missing', { status: 500, message: `The store has no file for ${key} ${version}.` });
+        }
+        h = await moduleArtifact.readHowto(buf, { key });
+        if (!h.ok) {
+          log.error({ key, version, code: h.code }, 'stored tarball failed verification');
+          return res.fail('artifact_invalid', { status: 500, message: `The stored file for ${key} ${version} did not pass its hash check.` });
+        }
+        if (h.tarballSha256 !== r.version.tarball_sha256) {
+          log.error({ key, version }, 'stored tarball is not the one the registry recorded');
+          return res.fail('artifact_invalid', { status: 500, message: `The stored file for ${key} ${version} is not the one that was published.` });
+        }
+        rememberHowto(cacheKey, h);
+      }
+      if (h.text == null) {
+        return res.fail('howto_missing', { status: 404, message: `${key} ${version} was published before every module shipped a how-to, so it has none.` });
+      }
+      res.set('Cache-Control', 'no-store');
+      res.json({
+        module_key: key,
+        title: h.title,
+        version: h.version,
+        published_at: r.version.published_at,
+        delisted,
+        markdown: h.text,
+        artifact_url: h.artifactUrl,
+      });
+    }));
+
   router.post('/store/modules/:key/acquired', auth.requireBuilder,
     asyncHandler('POST /store/modules/:key/acquired', async (req, res) => {
       const { key } = req.params;

package/src/bongos/routes.js

@@ -56,6 +56,8 @@ const buildSecurityRouter = require('./routes/security');
 // the submit-for-review front door. Core (not module-owned): it manages
 // EVERY module's enablement, including modules it must not import.
 const buildModulesRouter = require('./routes/modules');
+// The hall Commands page's CLI half (task 1004473): bin/bongos.js VERBS as data.
+const buildCliCommandsRouter = require('./routes/cli-commands');
 // The access-request ADMISSION routes carved to modules/onboarding/ (BV1.R81 /
 // ADR 0093 §1); moduleLoader.mountModuleRoutes (below) mounts them via the
 // onboarding module's route factory — no core require.
@@ -159,6 +161,7 @@ function buildGdsRouter() {
   router.use(buildAuditLogRouter());
   router.use(buildSecurityRouter());
   router.use(buildModulesRouter());
+  router.use(buildCliCommandsRouter());
   // access-requests (admission) is now mounted by the onboarding module via
   // moduleLoader.mountModuleRoutes below (BV1.R81) — still BEFORE the public
   // router, so its paths are byte-identical. The /sessions data plane is

package/src/bongos/serve-internal.js

@@ -1210,8 +1210,11 @@ function mountInternalSurfaces(app) {
   // own room beside the studio, on the studio's tier. Its read (GET
   // /copy-desk/pages/:pageId/draft) is any-builder like the .docx download, and
   // every write is the page claim's holder only, checked server-side.
+  // task 1004473: `commands`, the Commands page — every skill and every bongos CLI
+  // verb. Both reads behind it are requireBuilder, so it sits on this tier;
+  // reading the list grants nothing (ADR 0310 §1).
   const SIGNEDIN_BUILDERS_PAGE_RE =
-    /^\/builders\/(?:work|settings|atlas|modules|goals|goal-map|roadmap|copy-desk|studio|tweak-editor|ideas|thinking|collab|task|idea|primer(?:\.md)?|diagrams)(?:\.html)?\/?$/;
+    /^\/builders\/(?:work|settings|atlas|modules|goals|goal-map|roadmap|copy-desk|studio|tweak-editor|ideas|thinking|collab|task|idea|primer(?:\.md)?|diagrams|commands)(?:\.html)?\/?$/;
   // The diagram image assets under /builders/diagrams/ ride the same tier as the
   // page that embeds them.
   const SIGNEDIN_BUILDERS_PREFIX_RE = /^\/builders\/diagrams\//;

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.44'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.46'; // 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');

package/tests/hall_catalog_world.mjs

@@ -58,7 +58,7 @@ test('modules: the row is the oversight row — title with the mono key, clamped
   assert.match(js, /<span class="ov-row__title">\$\{escapeHtml\(m\.title \|\| m\.key\)\}<span class="ov-mono">\$\{escapeHtml\(m\.key\)\}<\/span>/, 'the key rides inside the title in mono');
   assert.match(js, /class="ov-row__sub mod-row__desc"/, 'the description is the sub line');
   assert.match(js, /<details class="mod-more"/, 'a details disclosure opens the rest');
-  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}<\/div>/, 'provenance, credit and upkeep are the facts line');
+  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}\$\{howtoFact\(m\)\}<\/div>/, 'provenance, credit, upkeep and (for a store version, task 1004366) the how-to link are the facts line');
   assert.match(js, /<div class="ov-row__right mod-row__right">\$\{rightHtml\(m\)\}<\/div>/, 'the right column is one function');
   const css = read('modules.css');
   assert.match(css, /\.mod-row__desc \{[^}]*-webkit-line-clamp: 2/, 'the description clamps to two lines');

package/tests/hall_commands.mjs

@@ -0,0 +1,162 @@
+// tests/hall_commands.mjs — the hall's Commands page (task 1004473): one table
+// of every skill and one of every bongos CLI verb, read from live sources.
+//
+// The done-when pins: every SKILL.md the instance has, and every bin/bongos.js
+// VERBS entry, appears on the page EXACTLY once. They are checked against the
+// real tree — the same installedSkills()+explainSkill() the
+// /specialities/installed-skills route serves, and the same cliCommands() the
+// /cli/commands route serves — rendered through the page's own lib.
+//
+// Run:  node --test tests/hall_commands.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const lib = require('../modules/hall-ui/public/commands-lib.js');
+const kit = require('../modules/hall-ui/public/hall-kit.js');
+const skills = require('../modules/specialities/skills.js');
+const { VERBS, GROUPS } = require('../bin/bongos.js');
+const esc = kit.esc;
+
+// Every SKILL.md on disk, by name: core .claude/skills/ plus every module's skills/.
+function skillDirsOnDisk({ modules = () => true } = {}) {
+  const out = [];
+  const scan = (dir) => {
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { return; }
+    for (const n of names) if (fs.existsSync(path.join(dir, n, 'SKILL.md'))) out.push({ name: n, md: path.join(dir, n, 'SKILL.md') });
+  };
+  scan(path.join(ROOT, '.claude', 'skills'));
+  for (const key of fs.readdirSync(path.join(ROOT, 'modules'))) if (modules(key)) scan(path.join(ROOT, 'modules', key, 'skills'));
+  return out;
+}
+
+// What the route hands the page: installedSkills() explained, exactly as
+// GET /specialities/installed-skills builds it.
+function servedSkills(isModuleEnabled) {
+  return [...skills.installedSkills({ coreRoot: ROOT, isModuleEnabled })]
+    .map(([name, entry]) => skills.explainSkill({ name, ...entry }));
+}
+
+const count = (html, attr, value) => html.split(`${attr}="${value}"`).length - 1;
+
+test('every SKILL.md in the tree appears on the page exactly once (every module on)', () => {
+  const html = lib.skillsTableHtml(lib.groupSkills(servedSkills(() => true)), { esc });
+  const onDisk = skillDirsOnDisk();
+  assert.ok(onDisk.length >= 48, `expected the real skill tree, found ${onDisk.length}`);
+  for (const { name } of onDisk) assert.equal(count(html, 'data-skill', name), 1, `/${name} should appear exactly once`);
+  assert.equal(count(html, 'data-skill', ''), 0, 'no nameless row');
+  assert.equal(html.split('data-skill="').length - 1, new Set(onDisk.map((s) => s.name)).size, 'no row that is not a SKILL.md');
+});
+
+test('a default instance shows its enabled modules\' skills and NOT a disabled module\'s', () => {
+  const defaults = (key) => {
+    try { return JSON.parse(fs.readFileSync(path.join(ROOT, 'modules', key, 'module.json'), 'utf8')).default === true; } catch { return false; }
+  };
+  const html = lib.skillsTableHtml(lib.groupSkills(servedSkills(defaults)), { esc });
+  for (const { name } of skillDirsOnDisk({ modules: defaults })) assert.equal(count(html, 'data-skill', name), 1, `/${name} should appear exactly once`);
+  for (const { name } of skillDirsOnDisk({ modules: (k) => k === 'pixel-art' || k === 'design-styles' })) {
+    if (fs.existsSync(path.join(ROOT, '.claude', 'skills', name, 'SKILL.md'))) continue;
+    assert.equal(count(html, 'data-skill', name), 0, `/${name} ships in a default-off module, so it must not be listed`);
+  }
+});
+
+test('each row carries the SKILL.md plain / reach-for / cost words', () => {
+  const served = servedSkills(() => true);
+  const html = lib.skillsTableHtml(lib.groupSkills(served), { esc });
+  const ship = served.find((s) => s.name === 'builder-ship');
+  const fm = skills.parseFrontmatter(fs.readFileSync(path.join(ROOT, '.claude/skills/builder-ship/SKILL.md'), 'utf8'));
+  assert.equal(ship.does, fm.plain);
+  assert.equal(ship.reachFor, fm['reach-for']);
+  assert.equal(ship.cost, fm.cost);
+  for (const v of [fm.plain, fm['reach-for'], fm.cost]) assert.ok(html.includes(esc(v)), `page shows: ${v}`);
+});
+
+test('the "type it yourself" marker follows disable-model-invocation, skill by skill', () => {
+  const served = servedSkills(() => true);
+  const html = lib.skillsTableHtml(lib.groupSkills(served), { esc });
+  let typed = 0;
+  for (const { name, md } of skillDirsOnDisk()) {
+    const hidden = skills.parseFrontmatter(fs.readFileSync(md, 'utf8'))['disable-model-invocation'] === 'true';
+    if (hidden) typed++;
+    const row = html.slice(html.indexOf(`data-skill="${name}"`)).split('</tr>')[0];
+    assert.match(row, hidden ? /cmd-how--typed/ : /cmd-how--listed/, `/${name}: ${hidden ? 'typed-only' : 'shown to Claude'}`);
+  }
+  assert.ok(typed > 0, 'the tree has typed-only skills (task 1004471), so the marker is exercised');
+});
+
+test('a skill no group names still gets a row, under Everything else', () => {
+  const groups = lib.groupSkills([{ name: 'brand-new-skill', source: 'core', does: 'x' }, { name: 'builder-ship', source: 'core' }]);
+  assert.deepEqual(groups.map((g) => g.key), ['loop', 'other']);
+  assert.equal(lib.groupKeyOf({ name: 'otb-tile-generate', source: 'module:pixel-art' }), 'design', 'a module\'s skills land in its group');
+  const loop = lib.groupSkills([{ name: 'builder-ship' }, { name: 'builder-claim' }, { name: 'builder-start' }].map((x) => ({ ...x, source: 'core' })));
+  assert.deepEqual(loop[0].skills.map((x) => x.name), ['builder-start', 'builder-claim', 'builder-ship'], 'the loop reads in the order you work it');
+});
+
+test('row text is escaped — a skill cannot inject markup into the hall', () => {
+  const html = lib.skillsTableHtml(lib.groupSkills([{ name: 'x', source: 'core', does: '<img src=x onerror=alert(1)>' }]), { esc });
+  assert.ok(!html.includes('<img'), html);
+});
+
+const { cliCommands } = require('../src/bongos/routes/cli-commands.js');
+
+test('every bin/bongos.js VERBS entry appears exactly once, grouped like `bongos --help`', () => {
+  const groups = cliCommands();
+  const html = lib.cliTableHtml(groups, { esc });
+  for (const verb of Object.keys(VERBS)) assert.equal(count(html, 'data-verb', verb), 1, `bongos ${verb} should appear exactly once`);
+  assert.equal(html.split('data-verb="').length - 1, Object.keys(VERBS).length, 'no row that is not a verb');
+  assert.deepEqual(groups.map((g) => g.label), GROUPS.map(([, label]) => label), 'the help\'s group order');
+  for (const g of groups) for (const c of g.commands) assert.equal(c.summary, VERBS[c.verb].summary, `${c.verb}: the help line, verbatim`);
+});
+
+test('a verb in a group GROUPS does not name is still listed', () => {
+  const groups = cliCommands({ GROUPS: [['work', 'Work']], VERBS: { a: { group: 'work', summary: 'A' }, b: { group: 'new', summary: 'B' } } });
+  assert.deepEqual(groups.map((g) => [g.key, g.commands.map((c) => c.verb)]), [['work', ['a']], ['other', ['b']]]);
+});
+
+test('GET /cli/commands serves the verbs to a signed-in builder and refuses a stranger', async () => {
+  const auth = require('../src/bongos/auth.js');
+  const express = require('express');
+  const build = require('../src/bongos/routes/cli-commands.js');
+  const serve = async (app, fn) => {
+    const server = http.createServer(app);
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
+    try { return await fn(`http://127.0.0.1:${server.address().port}`); } finally { server.close(); }
+  };
+
+  const saved = auth.requireBuilder;
+  auth.requireBuilder = (req, _res, next) => { req.builder = { id: 1, rank: 'xenos' }; next(); };
+  let signedIn;
+  try {
+    const app = express();
+    app.use(build());
+    signedIn = await serve(app, async (base) => { const r = await fetch(`${base}/cli/commands`); return { status: r.status, body: await r.json() }; });
+  } finally { auth.requireBuilder = saved; }
+  assert.equal(signedIn.status, 200);
+  assert.deepEqual(signedIn.body.groups.flatMap((g) => g.commands.map((c) => c.verb)).sort(), Object.keys(VERBS).sort());
+
+  const gated = express();
+  gated.use((req, res, next) => { res.fail = (code, st) => res.status(typeof st === 'number' ? st : 401).json({ error: code }); next(); });
+  gated.use(build());
+  const stranger = await serve(gated, async (base) => (await fetch(`${base}/cli/commands`)).status);
+  assert.ok(stranger === 401 || stranger === 403, `no session → refused (got ${stranger})`);
+});
+
+test('the page is wired: nav entry in Docs, sign-in gated, both reads, no hand-typed command', () => {
+  const page = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/commands.html'), 'utf8');
+  const js = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/commands.js'), 'utf8');
+  assert.match(js, /\/api\/bongos\/specialities\/installed-skills/);
+  assert.match(js, /\/api\/bongos\/cli\/commands/);
+  assert.ok(!/data-skill=|data-verb=|\/builder-ship|bongos claim/.test(page), 'the HTML names no command — the rows are generated');
+  const shell = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/shell.js'), 'utf8');
+  assert.match(shell, /id: 'commands', label: 'Commands', icon: 'docs', href: '\/commands', gate: 'signed'/);
+  const serveInternal = fs.readFileSync(path.join(ROOT, 'src/bongos/serve-internal.js'), 'utf8');
+  assert.match(serveInternal.match(/const SIGNEDIN_BUILDERS_PAGE_RE =\s*(\/.*\/);/)[1], /\|commands\)/);
+});

package/tests/hall_nav.mjs

@@ -285,8 +285,10 @@ test('sidebar groups read by audience, in order', () => {
   // what made this group read as one real page plus a link into the home page.
   assert.deepEqual(nav[2].items.map((i) => i.id), ['collab', 'roster'], 'Community = everyone else, in this project');
   assert.ok(!nav.flatMap((g) => g.items).some((i) => /^\/people\b/.test(i.href)), 'no nav item points at the deleted /people');
+  // task 1004473: 'commands' — every skill and CLI verb, read live — is reference
+  // material that reads the same for every builder, so it joins Docs.
   assert.deepEqual(nav[3].items.map((i) => i.id),
-    ['primer', 'ranks', 'economy', 'diagrams', 'atlas', 'modules', 'apidocs'], 'Docs = reference material');
+    ['primer', 'ranks', 'economy', 'commands', 'diagrams', 'atlas', 'modules', 'apidocs'], 'Docs = reference material');
   // 'government' (the Permissions tab, BV1.R113) is the group's one archon-gated item.
   // 'project-settings' joins the Government group at the metic floor (task 1003280,
   // goal 1000072) — it sits before 'government', which is the one archon-only item.

package/tests/hall_page_gate_map.mjs

@@ -46,6 +46,9 @@ const ORACLE = {
   '/builders/settings': 'requireBuilderPage',
   '/builders/atlas': 'requireBuilderPage',
   '/builders/modules': 'requireBuilderPage',
+  // task 1004473: the Commands page — its two reads (installed skills, CLI verbs)
+  // are requireBuilder, so sign-in is the whole gate.
+  '/builders/commands': 'requireBuilderPage',
   '/builders/goals': 'requireBuilderPage',
   // task 1003479: the goal map, on the goal board's tier. task 1004232 (sky part 4):
   // the URL now serves THE PROJECT SKY (the same page as /thinking, in its whole-project

package/tests/hall_tweak_editor.mjs

@@ -635,7 +635,7 @@ try {
     assert.match(HTML, /<body data-page="tweak-editor"[^>]*data-fullscreen-switch/);
     assert.equal((HTML.match(/<h1\b/g) || []).length, 1);
     assert.ok(HTML.indexOf('tweak-editor-lib.js') < HTML.indexOf('tweak-editor.js?'), 'the lib loads first');
-    assert.match(HTML, /shell\.js\?v=2026-09-29-renderdeploy/);
+    assert.match(HTML, /shell\.js\?v=2026-09-30-commands/);
     assert.equal(/fonts\.googleapis\.com\/css/.test(HTML), false);
     for (const id of ['tw-bar', 'tw-counter', 'tw-open', 'tw-open-more', 'tw-divider', 'tw-openwrap', 'tw-open-menu', 'tw-open-tab', 'tw-open-split', 'tw-frame', 'tw-frame-view', 'tw-split-close', 'tw-download', 'tw-upload', 'tw-file', 'tw-submit', 'tw-paper', 'tw-doc', 'tw-notice', 'tw-done', 'tw-take', 'tw-pick', 'tw-picks', 'tw-refused', 'tw-refused-title', 'tw-refused-list', 'tw-refused-next', 'tw-refused-download', 'tw-refused-close']) {
       assert.ok(new RegExp(`id="${id}"`).test(HTML), `#${id} is in the markup`);

package/tests/module_store_howto.mjs

@@ -0,0 +1,244 @@
+// tests/module_store_howto.mjs — the store shows each version's how-to as a page
+// (task 1004366, ADR 0347 D1/D3). Drives the real GET
+// /store/modules/:key/versions/:version/howto handler off the real router against
+// REAL packed tarballs in a temp store dir (no port, no real DB — pool.js is replaced
+// in the require cache, the module_store_publish_route.mjs harness). Then the page
+// half: the author's markdown renders through the hall's one escaping reader, the
+// install message links the page, and the Modules list links an installed version.
+//
+// Run:  node tests/module_store_howto.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const STORE = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-store-howto-'));
+process.env.MODULE_STORE_DIR = STORE;
+
+// The registry and the entitlements, as the fake pool sees them.
+const state = { modules: {}, versions: [], held: new Set() };
+const pool = {
+  async query(sql, params = []) {
+    if (/FROM store_modules WHERE module_key = \$1/.test(sql)) {
+      const m = state.modules[params[0]]; return { rows: m ? [m] : [] };
+    }
+    if (/FROM store_module_versions WHERE module_key = \$1 AND version = \$2/.test(sql)) {
+      return { rows: state.versions.filter((v) => v.module_key === params[0] && v.version === params[1]) };
+    }
+    if (/FROM store_module_versions WHERE module_key = ANY/.test(sql)) {
+      return { rows: state.versions.filter((v) => params[0].includes(v.module_key)) };
+    }
+    if (/FROM module_entitlements/.test(sql)) {
+      const k = `${params[0]}|${params[2]}`;
+      return { rows: state.held.has(k) ? [{ module_key: params[0], holder_kind: params[1], holder_ref: params[2], revoked_at: null }] : [] };
+    }
+    return { rows: [] };
+  },
+};
+const poolPath = require.resolve('../src/bongos/pool.js');
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: { connect: async () => ({ ...pool, release() {} }), query: pool.query } } };
+
+const buildModulesRouter = require('../src/bongos/routes/modules.js');
+const artifact = require('../scripts/gds/module-artifact.js');
+const { cmdInstall } = require('../scripts/gds/module.js');
+
+const sections = (tag) => artifact.HOWTO_SECTIONS.map((h) => `## ${h}\n${tag} — ${h}.\n`).join('\n');
+
+// Pack a real version of "weather" and put it in the store the way publish does.
+function publish(version, { howto, manifest = {}, status = 'listed' } = {}) {
+  const src = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-howto-src-'));
+  const dir = path.join(src, 'weather');
+  fs.mkdirSync(dir);
+  fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify({
+    key: 'weather', title: 'Weather', description: 'd', version, coreVersion: '^1.0.0', contributes: {}, ...manifest,
+  }));
+  if (howto != null) fs.writeFileSync(path.join(dir, 'HOWTO.md'), howto);
+  const { tgz } = artifact.packModule('weather', { modulesDir: src, modeOf: () => '644' });
+  fs.mkdirSync(path.join(STORE, 'weather'), { recursive: true });
+  fs.writeFileSync(path.join(STORE, 'weather', `weather-${version}.tgz`), tgz);
+  state.modules.weather = { module_key: 'weather', title: 'Weather', author_id: 42, status };
+  state.versions.push({ id: state.versions.length + 1, module_key: 'weather', version, tarball_sha256: require('node:crypto').createHash('sha256').update(tgz).digest('hex'), artifact_path: `weather/weather-${version}.tgz`, published_at: '2026-09-30T00:00:00Z' });
+  return tgz;
+}
+
+function handlerFor(router, method, p) {
+  const layer = router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]);
+  assert.ok(layer, `no ${method.toUpperCase()} ${p} on the router`);
+  const stack = layer.route.stack;
+  return { handle: stack[stack.length - 1].handle, names: stack.map((s) => s.name) };
+}
+
+async function invoke(handle, req) {
+  const res = {
+    statusCode: 200, body: undefined, headers: {},
+    json(b) { this.body = b; return this; },
+    status(c) { this.statusCode = c; return this; },
+    set(k, v) { this.headers[k] = v; return this; },
+    fail(code, opts) { this.statusCode = opts.status; this.body = { error: code, ...opts }; return this; },
+  };
+  let nextErr = null;
+  await handle(req, res, (err) => { nextErr = err; });
+  if (nextErr) throw nextErr;
+  return res;
+}
+
+const router = buildModulesRouter();
+const howtoRoute = handlerFor(router, 'get', '/store/modules/:key/versions/:version/howto');
+const read = (version, builderId = 7) => invoke(howtoRoute.handle, { params: { key: 'weather', version }, builder: { id: builderId } });
+
+publish('0.9.0', { howto: null }); // published before the gate: no how-to
+publish('1.0.0', { howto: sections('one') });
+publish('2.0.0', { howto: sections('two'), manifest: { howto: { artifactUrl: 'https://claude.ai/artifact/abc' } } });
+
+test('the route is open to any signed-in builder: requireBuilder and no permission gate', () => {
+  assert.deepEqual(howtoRoute.names.slice(0, 1), ['requireBuilder']);
+  assert.equal(howtoRoute.names.length, 2, 'builder gate, then the handler — no entitlement or rank gate for a listed module');
+});
+
+test('the page shows the version asked for, from its own tarball — not the latest', async () => {
+  const one = await read('1.0.0');
+  assert.equal(one.statusCode, 200, JSON.stringify(one.body));
+  assert.match(one.body.markdown, /one — What it does/);
+  assert.doesNotMatch(one.body.markdown, /two —/);
+  assert.equal(one.body.version, '1.0.0');
+  assert.equal(one.body.artifact_url, null);
+  const two = await read('2.0.0');
+  assert.match(two.body.markdown, /two — What it does/);
+  assert.equal(two.body.artifact_url, 'https://claude.ai/artifact/abc', 'the optional Claude page travels with its version');
+  assert.equal(one.headers['Cache-Control'], 'no-store');
+});
+
+test('a version published before the gate answers 404 howto_missing, not an empty page', async () => {
+  const r = await read('0.9.0');
+  assert.equal(r.statusCode, 404);
+  assert.equal(r.body.error, 'howto_missing');
+});
+
+test('an unknown version, a bad key and a loose version are refused', async () => {
+  assert.equal((await read('3.0.0')).body.error, 'version_not_found');
+  assert.equal((await invoke(howtoRoute.handle, { params: { key: 'Bad_Key', version: '1.0.0' }, builder: { id: 7 } })).statusCode, 400);
+  assert.equal((await read('^1.0.0')).statusCode, 400);
+});
+
+test('a checked how-to is cached: the second view reads no file', async () => {
+  const fresh = handlerFor(buildModulesRouter(), 'get', '/store/modules/:key/versions/:version/howto');
+  const view = () => invoke(fresh.handle, { params: { key: 'weather', version: '2.0.0' }, builder: { id: 7 } });
+  assert.equal((await view()).statusCode, 200);
+  const file = path.join(STORE, 'weather', 'weather-2.0.0.tgz');
+  fs.renameSync(file, file + '.away');
+  try {
+    const again = await view();
+    assert.equal(again.statusCode, 200, 'served from the cache, so the moved file is never read');
+    assert.match(again.body.markdown, /two — What it does/);
+  } finally { fs.renameSync(file + '.away', file); }
+});
+
+test('a stored tarball that no longer matches its hashes is never shown', async () => {
+  const file = path.join(STORE, 'weather', 'weather-1.0.0.tgz');
+  const good = fs.readFileSync(file);
+  const { readTar, buildTar } = require('../scripts/gds/artifact-format.js');
+  const entries = readTar(good);
+  entries.find((e) => e.name.endsWith('HOWTO.md')).buf = Buffer.from('## What it does\nswapped\n');
+  fs.writeFileSync(file, buildTar(entries));
+  try {
+    // A fresh router, so nothing is cached yet: the first read of a version checks it.
+    const fresh = handlerFor(buildModulesRouter(), 'get', '/store/modules/:key/versions/:version/howto');
+    const r = await invoke(fresh.handle, { params: { key: 'weather', version: '1.0.0' }, builder: { id: 7 } });
+    assert.equal(r.statusCode, 500);
+    assert.equal(r.body.error, 'artifact_invalid');
+  } finally { fs.writeFileSync(file, good); }
+});
+
+test('a delisted module\'s how-to still reads for people who hold it, and only for them (ADR 0338 D2)', async () => {
+  state.modules.weather.status = 'delisted';
+  try {
+    const stranger = await read('1.0.0', 7);
+    assert.equal(stranger.statusCode, 409);
+    assert.equal(stranger.body.error, 'module_delisted');
+    state.held.add('weather|8');
+    const holder = await read('1.0.0', 8);
+    assert.equal(holder.statusCode, 200, JSON.stringify(holder.body));
+    assert.equal(holder.body.delisted, true);
+    assert.match(holder.body.markdown, /one — What it does/);
+  } finally { state.modules.weather.status = 'listed'; state.held.clear(); }
+});
+
+// ---- the page: the author's markdown is untrusted input ----
+
+function loadReader() {
+  const ctx = { window: {}, location: { href: 'https://builders.example.com/builders/modules', hostname: 'builders.example.com' }, URL };
+  vm.createContext(ctx);
+  vm.runInContext(fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/md-reader.js'), 'utf8'), ctx);
+  return ctx.window.OTBMdReader;
+}
+const MODULES_JS = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/modules.js'), 'utf8');
+// The page's own link rule, lifted out of modules.js so the test runs the real one.
+const linkRule = MODULES_JS.match(/function howtoLinkHref\(href\) \{\n\s*return (.+);\n\s*\}/);
+const howtoLinkHref = new Function('href', `return ${linkRule[1]};`);
+
+test('author HTML renders as text: no tag, no handler and no script link survives', () => {
+  const MD = loadReader();
+  const evil = [
+    '## What it does',
+    '<script>alert(1)</script> <img src=x onerror=alert(2)>',
+    '[click](javascript:alert(3)) [rel](../secrets.md) [ok](https://example.org/a)',
+    '```', '</code><script>alert(4)</script>', '```',
+  ].join('\n');
+  const html = MD.parseMarkdown(evil, howtoLinkHref).html;
+  // Every tag in the output is one the reader writes itself; the author's are text.
+  const tags = html.match(/<\/?([a-z0-9]+)/gi).map((t) => t.replace(/[</]/g, '').toLowerCase());
+  assert.deepEqual([...new Set(tags)].sort(), ['a', 'code', 'h2', 'p', 'pre']);
+  assert.doesNotMatch(html, /href="javascript:/i);
+  assert.match(html, /&lt;script&gt;alert\(1\)&lt;\/script&gt;/);
+  assert.match(html, /<a href="https:\/\/example\.org\/a"/, 'an absolute https link still works');
+  assert.doesNotMatch(html, /href="\.\.\/secrets\.md"/, 'a relative repo path is text, not a link');
+});
+
+test('modules.js renders the how-to only through the escaping reader, and checks the Claude link', () => {
+  assert.match(MODULES_JS, /OTBMdReader\.parseMarkdown\(md, howtoLinkHref\)/);
+  assert.doesNotMatch(MODULES_JS, /innerHTML\s*=\s*[^;]*body\.markdown/, 'the raw markdown is never assigned as HTML');
+  assert.match(MODULES_JS, /isClaudeArtifactUrl\(body\.artifact_url\)/);
+  assert.match(MODULES_JS, /window\.print\(\)/, 'Save as PDF is the browser\'s own print');
+  const html = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/modules.html'), 'utf8');
+  assert.match(html, /md-reader\.js/);
+  assert.match(html, /Also available as a Claude page/);
+  assert.match(fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/modules.css'), 'utf8'), /@media print/);
+});
+
+// ---- the two links to the page ----
+
+test('the Modules list links an on-disk module that is a published store version', async () => {
+  const list = handlerFor(router, 'get', '/modules');
+  const res = await invoke(list.handle, { builder: { id: 7 } });
+  assert.equal(res.statusCode, 200);
+  for (const m of res.body.modules) {
+    assert.equal(m.store_howto, null, `${m.key} is not a store version, so it carries no how-to link`);
+  }
+});
+
+test('install prints the how-to page link when the version ships one, and not otherwise', async () => {
+  const describe = (v) => ({ ok: true, module_key: 'weather', version: v.version, core_version: v.coreVersion, tarball_sha256: v.tarballSha256, tree_sha256: v.treeSha256, tarball_bytes: v.bytes });
+  async function run(version) {
+    const tgz = fs.readFileSync(path.join(STORE, 'weather', `weather-${version}.tgz`));
+    const v = await artifact.verifyModuleArtifact(tgz, { key: 'weather' });
+    const request = async (method, urlPath) => {
+      if (urlPath.endsWith('/acquire')) return { ok: true, status: 200, data: describe(v) };
+      if (urlPath.endsWith('/tarball')) return { ok: true, status: 200, buf: tgz };
+      return { ok: true, status: 200, data: { ok: true } };
+    };
+    request.apiBase = 'https://example.com/';
+    const out = [];
+    const code = await cmdInstall(['weather'], { log: (m) => out.push(m), errlog: (m) => out.push(m), modulesDir: fs.mkdtempSync(path.join(os.tmpdir(), 'mod-howto-dest-')), roots: [], request, core: '1.19.0' });
+    assert.equal(code, 0, out.join('\n'));
+    return out.join('\n');
+  }
+  assert.match(await run('1.0.0'), /How to use it: https:\/\/example\.com\/builders\/modules\?howto=weather&version=1\.0\.0/);
+  assert.doesNotMatch(await run('0.9.0'), /How to use it/);
+});

package/tests/nav_permission_atoms.mjs

@@ -87,7 +87,7 @@ test('the hall-preview fixture carries every atom /me resolves', () => {
 // the file and left the query alone, so a returning browser kept the cached copy —
 // a fix that reaches nobody looks identical to a fix that does not work.
 
-const SHELL_SHA = 'dd33737d54dccbb4';
+const SHELL_SHA = '4e14115a3737db9a';
 
 test('shell.js has not changed without its cache-bust being bumped', () => {
   const actual = crypto.createHash('sha256').update(SHELL).digest('hex').slice(0, 16);