@bongos/core 1.20.45 → 1.20.46

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

@@ -97,6 +97,15 @@
     return `<span class="ov-fact">upkeep <b>${escapeHtml(status)}</b></span>`;
   }
 
+  // A module installed from the store links the how-to its version shipped with
+  // (task 1004366). The server sets store_howto only for a published key@version,
+  // and only to a /builders/modules?howto= path, so anything else is dropped.
+  function howtoFact(m) {
+    const href = m.store_howto;
+    if (typeof href !== 'string' || !href.startsWith('/builders/modules?howto=')) return '';
+    return `<a class="ov-fact mod-howto" href="${escapeHtml(href)}">how-to</a>`;
+  }
+
   // The lines the row's details disclosure opens onto: the facts the payload
   // carries that the card never rendered — what the module contributes, the
   // core it needs, who maintains it and what it hands off to.
@@ -143,7 +152,7 @@
         <div class="ov-row__main">
           <span class="ov-row__title">${escapeHtml(m.title || m.key)}<span class="ov-mono">${escapeHtml(m.key)}</span></span>
           ${desc ? `<p class="ov-row__sub mod-row__desc">${escapeHtml(desc)}</p>` : ''}
-          <div class="ov-row__facts">${provenancePill(m)}${attributionFacts(m)}${upkeepFact(m)}</div>
+          <div class="ov-row__facts">${provenancePill(m)}${attributionFacts(m)}${upkeepFact(m)}${howtoFact(m)}</div>
           ${lines ? `<details class="mod-more"${openKeys.has(m.key) ? ' open' : ''}><summary aria-label="Details for ${escapeHtml(m.title || m.key)}"></summary>${lines}</details>` : ''}
         </div>
         <div class="ov-row__right mod-row__right">${rightHtml(m)}</div>
@@ -320,5 +329,88 @@
     }
   }
 
-  load();
+  // ---- one store version's how-to (task 1004366, ADR 0347) ----
+  //
+  // ?howto=<key>&version=<X.Y.Z> opens the HOWTO.md that version shipped with in
+  // place of the catalog. A query, not a #/ route: the hall's hash namespace is
+  // frozen to the idea and blocker overlays.
+
+  // The author wrote this file, so a link in it may point anywhere. Only an absolute
+  // http(s) link, a mailto: or an in-page #anchor becomes an <a>; a relative path
+  // means nothing outside the author's repo, so it renders as its text.
+  function howtoLinkHref(href) {
+    return /^(https?:\/\/|mailto:|#)/i.test(String(href || '')) ? href : null;
+  }
+
+  // The same rule the manifest schema enforces on howto.artifactUrl (an https link on
+  // claude.ai), checked again here because this page writes it into an href.
+  function isClaudeArtifactUrl(u) {
+    try {
+      const url = new URL(String(u));
+      return url.protocol === 'https:' && (url.hostname === 'claude.ai' || url.hostname.endsWith('.claude.ai'));
+    } catch (_) { return false; }
+  }
+
+  function howtoFail(message) {
+    const doc = $('#howto-doc');
+    if (doc) { doc.removeAttribute('aria-busy'); doc.innerHTML = kit.emptyStateHtml(message); }
+    const print = $('#howto-print');
+    if (print) print.hidden = true;
+  }
+
+  async function loadHowto(key, version) {
+    const catalog = $('#core-scroll');
+    if (catalog) catalog.hidden = true;
+    const sub = $('#modules-sub');
+    if (sub) sub.hidden = true;
+    // A how-to is a document, so the page opts into the reading room (room.css
+    // scopes its column width and article sizes to body.room).
+    document.body.classList.add('room');
+    const view = $('#howto-view');
+    if (view) view.hidden = false;
+    const print = $('#howto-print');
+    if (print) print.addEventListener('click', () => window.print());
+
+    const res = await api.request('GET', `${API}/store/modules/${encodeURIComponent(key)}/versions/${encodeURIComponent(version)}/howto`);
+    if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); return; }
+    const body = res.data || {};
+    if (!res.ok) {
+      const err = body.error || {};
+      howtoFail((typeof err === 'object' && err.message) || body.message || `Could not load the how-to (${res.status}).`);
+      return;
+    }
+    const title = String(body.title || key);
+    document.title = `${title} ${body.version} — how-to`;
+    const h = $('#howto-h');
+    if (h) h.textContent = `${title} — how to use it`;
+    const meta = $('#howto-meta');
+    if (meta) {
+      meta.innerHTML = `<span class="ov-mono">${escapeHtml(key)}</span> · version <span class="ov-mono">${escapeHtml(String(body.version))}</span>`
+        + (body.delisted ? ' · <span class="fact-pill fact-pill--warn">delisted</span>' : '');
+    }
+    const extra = $('#howto-extra');
+    if (extra && body.artifact_url && isClaudeArtifactUrl(body.artifact_url)) {
+      extra.href = body.artifact_url;
+      extra.hidden = false;
+    }
+    const doc = $('#howto-doc');
+    if (doc) {
+      // HTML comments are the scaffold's writing prompts (ADR 0347 D2); they are
+      // not part of the how-to, so they are removed rather than shown as text.
+      const md = String(body.markdown || '').replace(/<!--[\s\S]*?-->/g, '');
+      doc.innerHTML = window.OTBMdReader.parseMarkdown(md, howtoLinkHref).html;
+      doc.removeAttribute('aria-busy');
+    }
+  }
+
+  const params = new URLSearchParams(window.location.search);
+  const howtoKey = params.get('howto');
+  if (howtoKey) {
+    loadHowto(howtoKey, params.get('version') || '').catch((err) => {
+      console.error('[modules] how-to failed to load', err);
+      howtoFail('Could not load the how-to. Return to the modules list and try again.');
+    });
+  } else {
+    load();
+  }
 })();

package/modules/hall-ui/records/catalog.md

@@ -8,3 +8,5 @@
 - **The island index is the map's keyboard and phone path.** The scene is a hover surface: SVG `<g>`s with mouse listeners, **no focusable element**, and at 390px thirty islands in 360px with nothing under them. `drawIndex` renders every node of the current view as a dense `.ov-row` under a `kit-collapse` (`#ab-index`) whose title is a disclosure button (`aria-expanded`/`aria-controls`) laying the SAME `detailHTML` inline; hovering a row lights the island, and **the index opens itself under 640px (`matchMedia`), where the list is the read.**
 
 Also gone, and the one rule in that list: `.ab-caption` takes the lede's `--measure`, never a fresh `90ch`. **Gotcha:** `gen-atlas.js` run from the MAIN checkout walks `.claude/worktrees/*` and emits thousands of context nodes — run it from a worktree, or copy a worktree's `atlas.json` over, before previewing the atlas there.
+
+**A store version's how-to is a view of the Modules page, not a new page (task 1004366).** `/builders/modules?howto=<key>&version=<X.Y.Z>` hides the catalog and shows that version's `HOWTO.md` in the reading room's article card: the page adds `body.room` so `room.css`'s sizes apply, and the markdown goes through `md-reader.js` (author-written, so every byte is escaped; only absolute http(s), mailto and #anchor links become links). A query, not a `#/` route — the hash namespace is frozen to the idea and blocker overlays. "Save as PDF" is `window.print()` with an `@media print` block in `modules.css` that keeps only the document and prints in the system ink (`CanvasText`), because a literal colour is the token tier's. Harness fixture: `store__modules__howto.json`.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.45",
+  "version": "1.20.46",
   "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

@@ -8383,5 +8383,11 @@
       "id": "1004473",
       "text": "The Builders Hall now has a Commands page listing every slash command and every terminal command, with what each does, when to use it and what it costs, including the ones hidden from Claude's menu."
     }
+  ],
+  "1.20.46": [
+    {
+      "id": "1004366",
+      "text": "Every store module version now has a readable how-to page in the hall, with a Save as PDF button and an optional link to a Claude page."
+    }
   ]
 }

package/scripts/gds/module-artifact.js

@@ -266,4 +266,24 @@ async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES, in
   return out;
 }
 
-module.exports = { MAX_TARBALL_BYTES, HOWTO_FILE, HOWTO_SECTIONS, packModule, verifyModuleArtifact, deniedFiles, checkHowto };
+// The how-to a published version shipped with (task 1004366): read from the version's
+// own tarball, after the same hash check install runs, so the page always shows the
+// exact file that version was published with. A version from before the gate may have
+// none (text null). Text only — nothing in the module is run or rendered here.
+// Returns { ok, text, artifactUrl, title, version, tarballSha256 } or verifyModuleArtifact's failure.
+async function readHowto(tgz, { key }) {
+  const v = await verifyModuleArtifact(tgz, { key, includeFiles: true });
+  if (!v.ok) return v;
+  const file = v.files.find((f) => f.path === HOWTO_FILE);
+  const extra = v.moduleJson.howto || {};
+  return {
+    ok: true,
+    text: file ? file.buf.toString('utf8') : null,
+    artifactUrl: extra.artifactUrl || null,
+    title: v.moduleJson.title || key,
+    version: v.version,
+    tarballSha256: v.tarballSha256,
+  };
+}
+
+module.exports = { MAX_TARBALL_BYTES, HOWTO_FILE, HOWTO_SECTIONS, packModule, verifyModuleArtifact, deniedFiles, checkHowto, readHowto };

package/scripts/gds/module.js

@@ -930,7 +930,7 @@ function storeRequest() {
   const { readSessionToken, dispatchedFetch, noKeepAliveDispatcher, CLI_USER_AGENT } = require('./cli-lib');
   const session = readSessionToken();
   if (!session) throw new Error('no Bongos session — run `bongos setup` first');
-  return async (method, urlPath, { json, binary = false } = {}) => {
+  const call = async (method, urlPath, { json, binary = false } = {}) => {
     const res = await dispatchedFetch(`${session.apiBase}/api/bongos${urlPath}`, {
       method,
       headers: {
@@ -946,6 +946,18 @@ function storeRequest() {
     try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
     return { ok: res.ok, status: res.status, data };
   };
+  // Where the store lives, so install can print a full link to the how-to page.
+  call.apiBase = session.apiBase;
+  return call;
+}
+
+// The hall page that shows a version's HOWTO.md (task 1004366) — the Modules tab,
+// opened on one version. null when the version shipped without one (published
+// before ADR 0347's gate), so install never prints a link that would 404.
+function howtoLink(key, version, files, apiBase) {
+  if (!files.some((f) => f.path === 'HOWTO.md')) return null;
+  const p = `/builders/modules?howto=${encodeURIComponent(key)}&version=${encodeURIComponent(version)}`;
+  return apiBase ? `${String(apiBase).replace(/\/+$/, '')}${p}` : p;
 }
 
 function storeError(res) {
@@ -1093,6 +1105,8 @@ async function cmdInstall(args, {
 
   if (!(await recordPlaced(key, got.described.version, { call, errlog, verb: 'install' }))) return 1;
   log(`\n✓ Installed "${key}" ${got.described.version}. It is not switched on: enable it from the hall's Modules tab when you want it.`);
+  const howto = howtoLink(key, got.described.version, got.verified.files, call.apiBase);
+  if (howto) log(`  How to use it: ${howto}`);
   return 0;
 }
 

package/scripts/hall-preview/server.js

@@ -144,6 +144,9 @@ const FIXTURE_FALLBACKS = [
   // the Approval queue's renders (task 1004323): a round's named visuals, one
   // fixture for any task id, as the editor read above serves any page.
   [/^tasks\/\d+\/visuals$/, 'tasks__visuals'],
+  // a store version's how-to page (task 1004366): one reading serves any key and
+  // version, since the Modules tab's how-to view shows one document.
+  [/^store\/modules\/[a-z0-9-]+\/versions\/[^/]+\/howto$/, 'store__modules__howto'],
 ];
 
 // CANNED WRITES (task 1004321). The tweak editor's whole flow is writes (the

package/src/bongos/module-store.js

@@ -179,6 +179,35 @@ async function resolveAcquirable(key, { version = null, db } = {}) {
   return { ok: true, module: mod, version: row, price: price || null, free: isFreePrice(price) };
 }
 
+// Resolve ONE exact version for reading its how-to (task 1004366). Unlike
+// resolveAcquirable this does not refuse a delisted module: ADR 0338 D2 keeps a
+// delisted module readable for the people who already hold it, so it hands the
+// caller the module's status and the route decides who may read on.
+// Returns { ok: true, module, version } or { ok: false, status, code, message }.
+async function resolveReadable(key, version, { db } = {}) {
+  const pool = db || require('./pool').pool;
+  const refuse = (status, code, message) => ({ ok: false, status, code, message });
+  const { rows: [mod] } = await pool.query(
+    'SELECT module_key, title, author_id, status FROM store_modules WHERE module_key = $1', [key]);
+  if (!mod) return refuse(404, 'module_not_found', `The store has no module "${key}".`);
+  const { rows: [row] } = await pool.query(
+    `SELECT id, module_key, version, tarball_sha256, artifact_path, published_at
+       FROM store_module_versions WHERE module_key = $1 AND version = $2`, [key, version]);
+  if (!row) return refuse(404, 'version_not_found', `"${key}" has no published version ${version}.`);
+  return { ok: true, module: mod, version: row };
+}
+
+// Which of these (key, version) pairs are published store versions, as a Set of
+// "key@version" — so the hall's Modules tab can link an installed module's how-to
+// (task 1004366). One query for the whole list.
+async function publishedVersionSet(keys, { db } = {}) {
+  if (!keys.length) return new Set();
+  const pool = db || require('./pool').pool;
+  const { rows } = await pool.query(
+    'SELECT module_key, version FROM store_module_versions WHERE module_key = ANY($1)', [keys]);
+  return new Set(rows.map((r) => `${r.module_key}@${r.version}`));
+}
+
 // The tarball on disk for a version row. artifact_path is relative to the store dir
 // (relativeArtifactPath), and artifactPath() re-validates key + version, so a row
 // can never point a read outside the store.
@@ -192,5 +221,5 @@ function versionArtifactFile(row, { dir = storeDir() } = {}) {
 
 module.exports = {
   stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
-  isFreePrice, resolveAcquirable, versionArtifactFile,
+  isFreePrice, resolveAcquirable, resolveReadable, publishedVersionSet, versionArtifactFile,
 };

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/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.45'; // 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');