@bongos/core 1.20.44 → 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/public/primer.html

@@ -115,7 +115,7 @@
 
 <div id="toast" class="toast" role="status" aria-live="polite" data-visible="0"></div>
 
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- the shared markdown reader (window.OTBMdReader) — primer.js renders through

package/modules/hall-ui/public/profile.html

@@ -187,7 +187,7 @@
 
 <!-- The app shell (sidebar + top bar). Dependency-free; loaded FIRST so the
      chrome exists before the page script runs. -->
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB) — loaded before profile.js, which pulls from it. -->

package/modules/hall-ui/public/project-settings.html

@@ -58,7 +58,7 @@
 
 <div id="toast" class="toast" role="status" aria-live="polite" data-visible="0"></div>
 
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <script src="/builders/dom-utils.js?v=2026-06-16-gate"></script>

package/modules/hall-ui/public/ranks.html

@@ -68,7 +68,7 @@
 
 <!-- The app shell (sidebar + top bar). Dependency-free; loaded FIRST so the
      chrome exists before the page script runs. -->
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB) — loaded before ranks.js, which pulls from it. -->

package/modules/hall-ui/public/roadmap.html

@@ -41,7 +41,7 @@
 
 <div id="toast" class="toast" role="status" aria-live="polite" data-visible="0"></div>
 
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <script src="/builders/dom-utils.js?v=2026-06-14-domutils"></script>

package/modules/hall-ui/public/roster.html

@@ -50,7 +50,7 @@
 
 <!-- The app shell (sidebar + top bar). Dependency-free; loaded FIRST so the
      chrome exists before the page script runs. -->
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB — rank labels, number formats) + the

package/modules/hall-ui/public/sessions.html

@@ -99,7 +99,7 @@
 
 <!-- The app shell (sidebar + top bar). Dependency-free; loaded FIRST so the
      chrome exists before the page script runs. -->
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB) — loaded BEFORE sessions.js so it can pull from it. -->

package/modules/hall-ui/public/settings.html

@@ -400,7 +400,7 @@
 
 <!-- The app shell (sidebar + top bar). Dependency-free; loaded FIRST so the
      chrome exists before the page scripts run. -->
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB) — loaded before consuming IIFEs. -->

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

@@ -303,6 +303,9 @@
       // stays right whatever `branding.currency.label` is set to. Page is public
       // like /ranks — 'signed' is the same cosmetic "show it once you're in".
       { id: 'economy', label: 'Economy', icon: 'docs', href: '/drachmae', gate: 'signed' },
+      // task 1004473: every skill and every bongos CLI verb, read live. Its page and
+      // both reads behind it are sign-in gated, so 'signed' is the real floor here.
+      { id: 'commands', label: 'Commands', icon: 'docs', href: '/commands', gate: 'signed' },
       { id: 'diagrams', label: 'Diagrams', icon: 'docs', href: '/diagrams', gate: 'signed' },
       { id: 'atlas', label: 'Repo Atlas', icon: 'docs', href: '/atlas', gate: 'member' },
       { id: 'modules', label: 'Modules', icon: 'docs', href: '/modules', gate: 'member' },

package/modules/hall-ui/public/studio.html

@@ -176,7 +176,7 @@
 
 <div id="toast" class="toast" role="status" aria-live="polite" data-visible="0"></div>
 
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <script src="/builders/palette.js" defer></script>
 <script src="/builders/dom-utils.js?v=2026-06-23-contrib"></script>
 <!-- The kit, for its ONE renderer: the full-size ship-time visual figure

package/modules/hall-ui/public/task.html

@@ -57,7 +57,7 @@
 
 <!-- The app shell (sidebar + top bar + footer). Dependency-free; runs at parse
      time so the chrome exists before the deferred page scripts execute. -->
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB) — loaded FIRST so task.js can pull from it. -->

package/modules/hall-ui/public/thinking.html

@@ -138,7 +138,7 @@
   </div>
 </div>
 
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <script src="/builders/palette.js" defer></script>
 
 <script src="/builders/idea-objects.js?v=2026-09-27-split"></script>

package/modules/hall-ui/public/tweak-editor.html

@@ -140,7 +140,7 @@
 
 <div id="toast" class="toast" role="status" aria-live="polite" data-visible="0"></div>
 
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <script src="/builders/palette.js" defer></script>
 <script src="/builders/dom-utils.js?v=2026-06-23-contrib"></script>
 <script src="/builders/brand-holes.js?v=2026-09-29-aqfix"></script>

package/modules/hall-ui/public/watch.html

@@ -162,7 +162,7 @@
 
 <!-- The app shell (sidebar + top bar). Dependency-free; loaded FIRST so the
      chrome exists before the page script runs. -->
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB) — loaded before watch.js, which pulls from it. -->

package/modules/hall-ui/public/work.html

@@ -171,7 +171,7 @@
 
 <!-- The app shell (sidebar + top bar + footer). Dependency-free; runs at parse
      time so the chrome exists before the deferred page scripts execute. -->
-<script src="/builders/shell.js?v=2026-09-29-renderdeploy"></script>
+<script src="/builders/shell.js?v=2026-09-30-commands"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared frontend toolkit (window.OTB) — loaded FIRST so work.js can pull from it. -->

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/modules/hall-ui/records/commands.md

@@ -0,0 +1,11 @@
+# The Commands page, at /commands (task 1004473)
+
+**Every skill and every `bongos` CLI verb on one Docs page, read from the live sources so it cannot drift.** The owner asked for it once task 1004471 hid the rarely used skills from Claude's menu: a skill nobody can see in the menu needs somewhere to be discovered. Five things it settled:
+
+- **Two reads, no list in the page.** The skills come from `GET /specialities/installed-skills` (the specialities module's `installedSkills()`: core + instance + ENABLED-module skills, so a default-off module such as `pixel-art` or `design-styles` shows only where it is on); the verbs from the new core `GET /cli/commands`, which hands over `bin/bongos.js` `VERBS` grouped by its `GROUPS` — the order `bongos --help` prints. Core may not import a module, which is why the page asks for the two halves separately; each fails on its own, so a missing skills list does not take the CLI table down.
+- **The only hand-written thing is the skill GROUP.** `commands-lib.js` `SKILL_GROUPS` places a skill by name or by the module it came from; a skill no group names lands under "Everything else", so a new skill always gets a row. Rows follow the order the group names them (the daily loop reads start → claim → ship), then A–Z.
+- **"Shown to Claude" vs "Type it yourself" is `disable-model-invocation`.** `skills.js` now carries it (`typedOnly`), and `explainSkill()` reports `listed`. Only the literal `true` hides a skill, which is how Claude Code reads the key.
+- **Sign-in is the whole gate.** The page joins `SIGNEDIN_BUILDERS_PAGE_RE`, its nav item is `signed` in Docs, and both reads are `requireBuilder`. Reading the list grants nothing (ADR 0310 §1): every command still meets the server's own rank checks when it runs.
+- **At 760px and below each row is a small card.** Five columns cannot fit a phone and a sideways-scrolling table hides the costs, so `commands.css` stacks the cells under their column names (`data-label`). The CLI tables are `table-layout: fixed` with a 220px command column so the help lines align across the three groups.
+
+Tests: `tests/hall_commands.mjs` (every SKILL.md and every VERBS entry exactly once, against the real tree; the typed-only marker per skill; the default-off modules absent; the route's gate). `docs/onboarding/slash-commands.md` now points here for the project's own list instead of keeping a second, hand-typed one.

package/modules/specialities/skills.js

@@ -92,6 +92,10 @@ function collect(out, dir, source) {
     const entry = { name, description: typeof fm.description === 'string' ? fm.description : '', source };
     for (const [key, field] of Object.entries(PEOPLE_KEYS)) if (typeof fm[key] === 'string' && fm[key]) entry[field] = fm[key];
     if (Array.isArray(fm.requires) && fm.requires.length) entry.requires = fm.requires;
+    // `disable-model-invocation: true` (task 1004471) keeps a skill out of the
+    // menu Claude reads; a person still runs it by typing /name. Only the literal
+    // `true` hides it, which is how Claude Code reads the key (task 1004473).
+    if (fm['disable-model-invocation'] === 'true') entry.typedOnly = true;
     out.set(name, entry);
   }
 }
@@ -150,6 +154,8 @@ function explainSkill(entry) {
     commands,
     needs: Array.isArray(e.requires) ? e.requires : [],
     rank,
+    // Shown to Claude (it can start the skill from plain English) vs typed-only.
+    listed: e.typedOnly !== true,
     derived: { does: !e.plain, reachFor: !e.reachFor, cost: !e.cost },
   };
 }

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.44",
+  "version": "1.20.46",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.44",
+      "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.44",
+  "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

@@ -8377,5 +8377,17 @@
       "id": "1004365",
       "text": "Every store module now comes with a how-to page, and the store refuses to publish one without it."
     }
+  ],
+  "1.20.45": [
+    {
+      "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/cli-commands.js

@@ -0,0 +1,49 @@
+// src/bongos/routes/cli-commands.js — every `bongos <verb>` the CLI answers,
+// for the hall's Commands page (task 1004473).
+//
+// WHY A ROUTE. The page is the one place a builder sees every skill AND every
+// CLI command, and both halves must be read from their live source so the list
+// cannot drift from what the tools actually do. The verb table is bin/bongos.js
+// `VERBS` (grouped by its `GROUPS`, the order `bongos --help` prints); the
+// browser cannot read that file, so this hands it over as data. The skills half
+// comes from the specialities module's GET /specialities/installed-skills —
+// core must not import a module, so the page asks for the two halves separately.
+//
+// Reading the list grants nothing (ADR 0310 §1): every verb still runs against
+// the server's own rank checks. Sign-in is the floor only because the page it
+// feeds sits on the hall's signed-in tier.
+
+const express = require('express');
+const auth = require('../auth');
+// Side-effect-free: bin/bongos.js only dispatches when it is the main module.
+const cli = require('../../../bin/bongos.js');
+
+/** The CLI's verbs as `bongos --help` groups them: [{ key, label, commands: [{ verb, summary }] }]. */
+function cliCommands(source = cli) {
+  const verbs = Object.entries(source.VERBS || {});
+  const groups = (source.GROUPS || []).map(([key, label]) => ({
+    key,
+    label,
+    commands: verbs.filter(([, def]) => def.group === key).map(([verb, def]) => ({ verb, summary: def.summary })),
+  }));
+  // A verb whose group `GROUPS` does not name still exists, so it still gets a row.
+  const known = new Set(groups.map((g) => g.key));
+  const stray = verbs.filter(([, def]) => !known.has(def.group));
+  if (stray.length) groups.push({ key: 'other', label: 'Other', commands: stray.map(([verb, def]) => ({ verb, summary: def.summary })) });
+  return groups.filter((g) => g.commands.length);
+}
+
+function buildCliCommandsRouter() {
+  const router = express.Router();
+
+  // GET /cli/commands — the bongos CLI's verbs, grouped like `bongos --help`.
+  // rank: any builder — read-only reference; the hall's Commands page is sign-in gated.
+  router.get('/cli/commands', auth.requireBuilder, (_req, res) => {
+    res.json({ version: cli.VERSION, groups: cliCommands() });
+  });
+
+  return router;
+}
+
+module.exports = buildCliCommandsRouter;
+module.exports.cliCommands = cliCommands;