@bongos/core 1.20.43 → 1.20.45

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/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.43",
+  "version": "1.20.45",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.43",
+      "version": "1.20.45",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

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

@@ -8367,5 +8367,21 @@
       "id": "1004471",
       "text": "Claude's list of project commands is now short enough to read in full every session: the rarely used admin commands still work when you type them but no longer take up room, and one new /owner-review walks the backlog, bugs, i"
     }
+  ],
+  "1.20.44": [
+    {
+      "id": "1003637",
+      "text": "The collab page's row layout rule now lives in the collab stylesheet instead of the shared oversight one."
+    },
+    {
+      "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."
+    }
   ]
 }

package/scripts/gds/module-artifact.js

@@ -22,6 +22,13 @@
 // secrets), plus credential-named files anywhere in the module (SECRET_FILE_RE). Anything the denylist catches refuses the whole publish rather than being
 // silently dropped: a module that ships without a file it expected is a broken module.
 //
+// THE HOW-TO GATE (ADR 0347 D4, task 1004365). A store version must carry HOWTO.md
+// with the five required sections, each with some text. checkHowto is the ONE checker:
+// `bongos module publish` runs it before uploading and the store's upload route runs
+// it again through verifyModuleArtifact({ requireHowto: true }), so a hand-built upload
+// can't skip it. It is opt-in there because install and update verify with the same
+// function, and a version published before the gate existed must still install.
+//
 // Both halves live here so the CLI (packModule) and the store route
 // (verifyModuleArtifact) cannot disagree about the format. Pure apart from reading the
 // module directory in packModule; never touches the network or the database.
@@ -47,6 +54,42 @@ const NEVER_PACKED = new Set(['.upstream-signoff.json', INNER_MANIFEST_PATH]);
 const MAX_TARBALL_BYTES = 5 * 1024 * 1024;
 const READ_LIMITS = { maxUnpackedBytes: 16 * 1024 * 1024, maxFiles: 2000 };
 
+const HOWTO_FILE = 'HOWTO.md';
+// ADR 0347 D2 — level-2 headings, matched case-insensitively, in any order.
+const HOWTO_SECTIONS = ['What it does', 'Install and enable', 'How to use it', 'Configuration', 'Limits and known issues'];
+
+// Judge HOWTO.md's text (null = the file is absent). Reads headings only, never the
+// writing: a section counts as filled when it holds any text once HTML comments (the
+// scaffold's prompts) are removed. A heading inside a fenced code block doesn't count.
+// Returns { ok, problems: [a plain sentence naming the file or the section] }.
+function checkHowto(text) {
+  if (text == null) return { ok: false, problems: [`${HOWTO_FILE} is missing — every store module ships one (ADR 0347)`] };
+  const bodies = new Map();
+  let current = null;
+  let fence = null;
+  for (const line of String(text).replace(/<!--[\s\S]*?-->/g, '').split(/\r?\n/)) {
+    const f = line.match(/^\s*(```|~~~)/);
+    if (f) fence = fence === f[1] ? null : (fence || f[1]);
+    const h = !fence && !f && line.match(/^(#{1,6})\s+(.*?)\s*#*\s*$/);
+    if (h) {
+      // A level-1/2 heading starts a new section; a deeper one is structure, not text.
+      if (h[1].length <= 2) {
+        current = h[1].length === 2 ? h[2].toLowerCase() : null;
+        if (current !== null && !bodies.has(current)) bodies.set(current, '');
+      }
+      continue;
+    }
+    if (current !== null) bodies.set(current, bodies.get(current) + line.trim());
+  }
+  const problems = [];
+  for (const name of HOWTO_SECTIONS) {
+    const body = bodies.get(name.toLowerCase());
+    if (body === undefined) problems.push(`${HOWTO_FILE}: section "${name}" is missing`);
+    else if (!body) problems.push(`${HOWTO_FILE}: section "${name}" is empty`);
+  }
+  return { ok: problems.length === 0, problems };
+}
+
 function tarballName(key, version) { return `${ARTIFACT_NAME}-${key}-${version}.tgz`; }
 
 // Every file under dir, as module-relative forward-slash paths, sorted. Skips
@@ -144,7 +187,9 @@ function packModule(key, { modulesDir, now = () => new Date(), modeOf } = {}) {
 // `includeFiles: true` (install, task 1003785) also returns `files`: the module's own
 // files — [{ path, mode, buf }], the inner manifest left out — from the SAME parse the
 // hashes were checked against, so a caller that places them never re-reads the bytes.
-async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES, includeFiles = false } = {}) {
+// `requireHowto: true` (the store's upload route, ADR 0347 D4) also refuses a version
+// whose HOWTO.md fails checkHowto.
+async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES, includeFiles = false, requireHowto = false } = {}) {
   const fail = (code, message) => ({ ok: false, code, message });
   if (!Buffer.isBuffer(tgz) || tgz.length === 0) return fail('empty_artifact', 'the upload is empty');
   if (tgz.length > maxBytes) return fail('artifact_too_large', `the tarball is over ${maxBytes} bytes`);
@@ -204,6 +249,11 @@ async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES, in
   if (manifest.module_version !== moduleJson.version || manifest.core_version !== moduleJson.coreVersion) {
     return fail('bad_manifest', 'the manifest version does not match module.json');
   }
+  if (requireHowto) {
+    const howto = byName.get(HOWTO_FILE);
+    const h = checkHowto(howto ? howto.buf.toString('utf8') : null);
+    if (!h.ok) return fail('howto_incomplete', h.problems.join('; '));
+  }
 
   const out = {
     ok: true, manifest, moduleJson,
@@ -216,4 +266,4 @@ async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES, in
   return out;
 }
 
-module.exports = { MAX_TARBALL_BYTES, packModule, verifyModuleArtifact, deniedFiles };
+module.exports = { MAX_TARBALL_BYTES, HOWTO_FILE, HOWTO_SECTIONS, packModule, verifyModuleArtifact, deniedFiles, checkHowto };

package/scripts/gds/module.js

@@ -8,8 +8,8 @@
 //
 //   bongos module new <key>
 //     Scaffolds modules/<key>/ — a VALID, loader-discoverable module.json (M03),
-//     the dir skeleton (routes/, migrations/, ui/), a sample route factory, and a
-//     nested CLAUDE.md — with NO edit to any core file. The loader
+//     the dir skeleton (routes/, migrations/, ui/), a sample route factory, a
+//     HOWTO.md template for the store page (ADR 0347), and a nested CLAUDE.md — with NO edit to any core file. The loader
 //     (src/module-loader/loader.js) discovers it; enabling it (config/modules.json
 //     or env) mounts its routes behind the kernel's auth — the strangler endgame
 //     where adding a feature is "drop a directory," not "edit routes.js + modules.js".
@@ -94,6 +94,12 @@ function readJson(p) {
   catch (e) { if (e.code === 'ENOENT') return null; throw e; }
 }
 
+// A text file's contents, or null when it does not exist.
+function readText(p) {
+  try { return fs.readFileSync(p, 'utf8'); }
+  catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+}
+
 function envPrefix() {
   const { FALLBACK_ENV_PREFIX } = require('../../src/instance-config');
   try { return require('../../src/branding').branding().envPrefix || FALLBACK_ENV_PREFIX; }
@@ -213,9 +219,39 @@ Put \`NNN_*.sql\` under \`migrations/\` and set \`contributes.migrations: true\`
 \`require('../../../src/module-api')\` — the doorway — is the ONLY core import
 allowed. No deep core imports, no sibling-module imports; cooperate through
 kernel seams (\`api.registerProvider\` / \`api.resolve\` / \`api.on\` / \`api.emit\`).
+
+## The how-to (\`HOWTO.md\`)
+This CLAUDE.md is for AI sessions working *inside* the module. \`HOWTO.md\` is for the
+person who installs it — the store shows it as the module's page (ADR 0347). It is
+plain Markdown, so any AI or person can write it. \`bongos module publish\` refuses
+the module until each of its five sections has some text; replace the prompts in
+\`<!-- -->\` with real answers. An optional \`howto.artifactUrl\` in module.json can
+link a Claude page as an extra — never instead of the file.
 `;
 }
 
+// The HOWTO.md a fresh module starts from (ADR 0347 D2): every required section as a
+// heading, with its prompt in an HTML comment. checkHowto strips comments, so an
+// untouched scaffold fails the publish gate until the author writes each section.
+function howtoTemplate(key, manifest) {
+  const { HOWTO_SECTIONS } = require('./module-artifact');
+  const prompts = {
+    'What it does': 'A few sentences: what this module adds, and who it is for.',
+    'Install and enable': `How to get it (\`bongos module install ${key}\`) and switch it on (hall Modules tab).`,
+    'How to use it': 'Its commands, routes and hall surfaces, with one worked example.',
+    'Configuration': 'Env vars and settings, with their defaults. "None." is a fine answer.',
+    'Limits and known issues': 'What it does not do, and anything known to go wrong. "None known." is a fine answer.',
+  };
+  const sections = HOWTO_SECTIONS.map((name) => `## ${name}\n\n<!-- ${prompts[name]} -->\n`).join('\n');
+  return `# ${manifest.title} — how to use it
+
+<!-- Written for the person who installs this module, or for any AI helping them.
+     The store shows this file as the module's page. Every section below must have
+     some text before \`bongos module publish\` will accept the module (ADR 0347). -->
+
+${sections}`;
+}
+
 // Has the core advanced past a deprecated module's declared removal version?
 // `removeAfter: "1.12.0"` means "may be deleted once core is ABOVE 1.12.0".
 function isPastRemoveAfter(maintenance, core) {
@@ -283,6 +319,7 @@ function scaffoldModule({ key, modulesDir = MODULES_DIR, core = coreVersion(), f
     'module.json': JSON.stringify(manifest, null, 2) + '\n',
     [`routes/${key}.js`]: routeTemplate(key),
     'CLAUDE.md': claudeMdTemplate(key, manifest),
+    'HOWTO.md': howtoTemplate(key, manifest),
     // git does not track empty dirs — keep the rest of the skeleton with placeholders.
     'migrations/.gitkeep': '',
     'ui/.gitkeep': '',
@@ -621,6 +658,7 @@ function cmdNew(args, { log = console.log, errlog = console.error } = {}) {
   log(`  • credit it     — fill in author/origin/maintainer in module.json (license defaults to AGPL-3.0)`);
   log(`  • enable it     — add "${key}": true to config/modules.json (or set <PREFIX>_MODULE_${ENVKEY}=1)`);
   log(`  • build it      — fill routes/${key}.js; add migrations/ + ui/ (see modules/${key}/CLAUDE.md)`);
+  log(`  • explain it    — fill in every section of modules/${key}/HOWTO.md (publish refuses it until you do)`);
   log('  • verify        — bongos upgrade  (checks coreVersion compatibility)');
   return 0;
 }
@@ -672,7 +710,7 @@ function cmdUpgrade(_args, { log = console.log, errlog = console.error, gather =
   return 0;
 }
 
-function cmdCheck(args, { log = console.log, errlog = console.error, check = checkModulePublishability, sign = recordSignOff } = {}) {
+function cmdCheck(args, { log = console.log, errlog = console.error, check = checkModulePublishability, sign = recordSignOff, howtoCheck } = {}) {
   const key = args.find((a) => !a.startsWith('-'));
   if (!key) {
     errlog('usage: bongos module check <key> [--sign-off "Name <email>"]');
@@ -692,6 +730,13 @@ function cmdCheck(args, { log = console.log, errlog = console.error, check = che
     for (const f of result.findings) errlog(`  ✗ ${f.kind}: ${f.detail}`);
   }
 
+  // The store's how-to gate (ADR 0347 D4), reported here so an author learns early.
+  // Advisory only: it gates `bongos module publish`, never an upstream submit.
+  const { checkHowto, HOWTO_FILE } = require('./module-artifact');
+  const howto = (howtoCheck || ((k) => checkHowto(readText(path.join(MODULES_DIR, k, HOWTO_FILE)))))(key);
+  if (howto.ok) log(`  ✓ ${HOWTO_FILE} has every required section — ready for \`bongos module publish\`.`);
+  else for (const p of howto.problems) log(`  ! ${p} — needed before \`bongos module publish\` (not for an upstream submit)`);
+
   if (!result.ok) {
     errlog(`\nREFUSING: "${key}" is not clear to submit upstream. Fix the finding(s) above and re-run.`);
     return 1;
@@ -814,6 +859,14 @@ async function cmdPublish(args, {
   catch (e) { errlog(`REFUSING: ${e.message}`); return 1; }
   const { tgz, sidecar } = packed;
   log(`bongos module publish — "${key}" ${sidecar.module_version} (needs core ${sidecar.core_version})`);
+  // The how-to gate (ADR 0347 D4) — the same checker the store re-runs on upload.
+  const howto = artifact.checkHowto(readText(path.join(modulesDir, key, artifact.HOWTO_FILE)));
+  if (!howto.ok) {
+    for (const p of howto.problems) errlog(`  ✗ ${p}`);
+    errlog(`REFUSING: "${key}" needs a complete ${artifact.HOWTO_FILE} before it can be published — fill in the section(s) above.`);
+    return 1;
+  }
+  log(`  ✓ ${artifact.HOWTO_FILE} has all ${artifact.HOWTO_SECTIONS.length} required sections`);
   log(`  ✓ packed ${sidecar.file_count} file(s), ${tgz.length} bytes — tree ${sidecar.tree_sha256.slice(0, 12)}…`);
   if (tgz.length > artifact.MAX_TARBALL_BYTES) {
     errlog(`REFUSING: the tarball is ${tgz.length} bytes, over the store's ${artifact.MAX_TARBALL_BYTES}-byte cap.`);
@@ -1130,7 +1183,7 @@ async function cmdUpdate(args, {
 function printHelp(out = console.log) {
   out('bongos module — scaffold + manage Cloud Bongos modules\n');
   out('Usage:');
-  out('  bongos module new <key>     Scaffold modules/<key>/ (manifest + skeleton + sample route + CLAUDE.md)');
+  out('  bongos module new <key>     Scaffold modules/<key>/ (manifest + skeleton + sample route + HOWTO.md + CLAUDE.md)');
   out('  bongos module list [--catalog] [--search <text>] [--json]');
   out('                              Browse the module catalog — what you can enable, with author + origin credit');
   out('  bongos upgrade              Pre-check enabled modules against the core version (fail-closed)');

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;

package/src/bongos/routes/modules.js

@@ -308,9 +308,10 @@ module.exports = function buildModulesRouter() {
   // the store (task 1004271, ADR 0338 D1). Body: the gzip tarball
   // `bongos module publish` builds (scripts/gds/module-artifact.js), sent as
   // application/gzip. The route trusts nothing but the bytes: it recomputes every
-  // hash, re-runs the publish denylist and validates module.json itself
-  // (verifyModuleArtifact), then keeps the tarball on the control plane's disk and
-  // INSERTs the version row in one transaction (module-store.js). A key's first
+  // hash, re-runs the publish denylist, validates module.json and checks that
+  // HOWTO.md has its required sections (ADR 0347 D4) itself (verifyModuleArtifact),
+  // then keeps the tarball on the control plane's disk and INSERTs the version row
+  // in one transaction (module-store.js). A key's first
   // publish makes the caller its author; after that only the author may publish,
   // a delisted key takes nothing new, and a version is published once and never
   // changed.
@@ -333,7 +334,7 @@ module.exports = function buildModulesRouter() {
         return res.fail('empty_artifact', { status: 400, message: 'Send the tarball as the body, Content-Type: application/gzip.' });
       }
 
-      const v = await moduleArtifact.verifyModuleArtifact(tgz, { key });
+      const v = await moduleArtifact.verifyModuleArtifact(tgz, { key, requireHowto: true });
       if (!v.ok) {
         return res.fail(v.code, { status: v.code === 'artifact_too_large' ? 413 : 422, message: v.message });
       }

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.43'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.45'; // 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/src/module-loader/manifest-schema.js

@@ -53,6 +53,9 @@
 //                                       //   actually declares in `contributes`, and every entry must be
 //                                       //   one it actually lists there — a typo'd exemption is an error,
 //                                       //   never a silent pass.
+//     "howto": {                        // OPTIONAL. Extras beside the module's HOWTO.md (ADR 0347 D3).
+//       "artifactUrl": "https://claude.ai/…" //   A Claude page with the same how-to, shown as an extra,
+//     },                                //   never graded and never required — the file is the how-to.
 //     "provides":      ["reward"],      // OPTIONAL. seam PORTS this module registers a provider for.
 //     "consumes":      ["grade"],       // OPTIONAL. seam ports this module resolves (required capabilities).
 //     "prerequisites": { "modules": ["economy"] },  // OPTIONAL. other modules that must be enabled.
@@ -100,6 +103,17 @@ const ATTRIBUTION_KEYS = ['author', 'origin', 'license', 'maintainer'];
 // Deliberately NOT exported: the validator and its own error message are the only
 // readers, and an export nothing imports is dead weight the knip ratchet counts.
 const SPEND_KEYS = ['requiresPayer'];
+// The `howto` block (ADR 0347 D3) — closed for the same reason; not exported either.
+const HOWTO_KEYS = ['artifactUrl'];
+
+// An https link on claude.ai (or a subdomain). Shape only: the store never fetches it.
+function isClaudeArtifactUrl(v) {
+  if (!isStr(v)) return false;
+  let u;
+  try { u = new URL(v); } catch { return false; }
+  const host = u.hostname.toLowerCase();
+  return u.protocol === 'https:' && !u.username && !u.password && (host === 'claude.ai' || host.endsWith('.claude.ai'));
+}
 
 const MAINTENANCE_STATUSES = ['core-maintained', 'maintained', 'deprecated', 'orphaned'];
 const MAINTENANCE_KEYS = ['status', 'since', 'removeAfter', 'successor', 'note'];
@@ -306,6 +320,20 @@ function validateManifest(obj) {
     }
   }
 
+  // --- optional how-to extras (ADR 0347 D3) ---
+  if ('howto' in obj) {
+    const h = obj.howto;
+    if (!isObj(h)) E('howto: must be an object (e.g. { "artifactUrl": "https://claude.ai/…" })');
+    else {
+      for (const k of Object.keys(h)) {
+        if (!HOWTO_KEYS.includes(k)) E(`howto.${k}: unknown key (allowed: ${HOWTO_KEYS.join(', ')})`);
+      }
+      if ('artifactUrl' in h && !isClaudeArtifactUrl(h.artifactUrl)) {
+        E('howto.artifactUrl: must be an https:// link on claude.ai when present');
+      }
+    }
+  }
+
   // --- optional seam declarations ---
   if ('provides' in obj && !isStrArray(obj.provides)) E('provides: must be an array of non-empty strings (port names)');
   if ('consumes' in obj && !isStrArray(obj.consumes)) E('consumes: must be an array of non-empty strings (port names)');