@bongos/core 1.20.42 → 1.20.44

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/scripts/gds/skill-lint.js

@@ -14,6 +14,12 @@
 // context window, and a description is resident in EVERY session, so long ones
 // crowd the others out and get truncated (skill routing degrades).
 //
+// A HIDDEN skill — frontmatter `disable-model-invocation: true` — is not in that
+// listing at all: Claude Code keeps its description out of the model's context and
+// loads it only when a person types /name (the model cannot invoke it). So the
+// budget counts LISTED skills only, and hidden ones are reported on their own line
+// (task 1004471, owner ruling on blocker 1000139).
+//
 // NOT A YAML PARSER, on purpose. These are targeted regex checks for the hazards that
 // actually bit us (a plain scalar carrying ": " or " #", an unclosed quote or flow
 // collection, a tab, a continuation line), so the repo gains a CI gate with no new
@@ -95,11 +101,19 @@ function lintFrontmatter(lines) {
   return { errors, warnings, fields };
 }
 
+// Whether a skill is HIDDEN from the model's listing: `disable-model-invocation: true`
+// (Claude Code: "description not in context"; typeable as /name, never model-invoked).
+// Anything but a literal true — absent, false, a typo — leaves it listed, so a mistake
+// can only ever over-count the budget, never hide a skill nobody meant to hide.
+function isHidden(fields) {
+  return String((fields && fields['disable-model-invocation']) || '').trim().toLowerCase() === 'true';
+}
+
 // Lint one SKILL.md file's text. `file` is used for the name check and messages.
 function lintSkillFile(text, { file = 'SKILL.md' } = {}) {
   const dirName = path.basename(path.dirname(file));
   const fm = splitFrontmatter(text);
-  const res = { file, errors: [], warnings: [], name: null, description: '', listingChars: 0 };
+  const res = { file, errors: [], warnings: [], name: null, description: '', listingChars: 0, hidden: false };
   if (!fm) { res.errors.push('no YAML frontmatter (the file must start with --- and carry name + description)'); return res; }
   const { errors, warnings, fields } = lintFrontmatter(fm.lines);
   res.errors.push(...errors); res.warnings.push(...warnings);
@@ -107,8 +121,10 @@ function lintSkillFile(text, { file = 'SKILL.md' } = {}) {
   if (!name) res.errors.push('missing "name"');
   else if (name !== dirName && dirName !== 'SKILL.md') res.warnings.push(`name "${name}" differs from its folder "${dirName}" — the folder name wins in listings`);
   if (!desc) res.errors.push('missing or empty "description" — the skill would match on its body text');
+  res.hidden = isHidden(fields);
   if (desc.length > DESC_HARD_CHARS) res.errors.push(`description is ${desc.length} chars — over Claude Code's ${DESC_HARD_CHARS}-char cap`);
-  else if (desc.length > DESC_WARN_CHARS) res.warnings.push(`description is ${desc.length} chars — over the ~${DESC_WARN_CHARS} we aim for; every char is resident in every session`);
+  else if (desc.length > DESC_WARN_CHARS && !res.hidden) res.warnings.push(`description is ${desc.length} chars — over the ~${DESC_WARN_CHARS} we aim for; every char is resident in every session`);
+  // listingChars is what the entry WOULD cost if listed; lintSkills leaves hidden ones out of the total.
   res.name = name || dirName; res.description = desc; res.listingChars = res.name.length + desc.length;
   return res;
 }
@@ -164,13 +180,18 @@ function residentSkillFiles(root = REPO_ROOT, { instanceDir = root, files = list
 }
 
 // Lint a set of files; returns per-file results plus the listing total vs budget. The
-// listing counts `resident` (a list of paths) when given, else every linted file.
+// listing counts `resident` (a list of paths) when given, else every linted file — and of
+// those, only the LISTED ones: a hidden skill (isHidden) is resident but costs the model
+// nothing, so it is tallied separately as hiddenSkills / hiddenChars (task 1004471).
 function lintSkills(files, { resident } = {}) {
   const results = files.map((f) => lintSkillFile(fs.readFileSync(f, 'utf8'), { file: f }));
   const counted = resident ? new Set(resident.map((f) => path.resolve(f))) : null;
-  const listed = counted ? results.filter((r) => counted.has(path.resolve(r.file))) : results;
+  const here = counted ? results.filter((r) => counted.has(path.resolve(r.file))) : results;
+  const listed = here.filter((r) => !r.hidden);
+  const hidden = here.filter((r) => r.hidden);
   const listingChars = listed.reduce((a, r) => a + r.listingChars, 0);
-  return { results, listingChars, listedSkills: listed.length, budgetChars: LISTING_BUDGET_CHARS, overBudget: listingChars > LISTING_BUDGET_CHARS };
+  const hiddenChars = hidden.reduce((a, r) => a + r.listingChars, 0);
+  return { results, listingChars, listedSkills: listed.length, residentSkills: here.length, hiddenSkills: hidden.length, hiddenChars, hiddenNames: hidden.map((r) => r.name), budgetChars: LISTING_BUDGET_CHARS, overBudget: listingChars > LISTING_BUDGET_CHARS };
 }
 
 // The PostToolUse hook's gate. It must match a module-owned SKILL.md too — that is the
@@ -190,8 +211,10 @@ function format(report, { relTo = REPO_ROOT } = {}) {
   }
   const errs = report.results.reduce((a, r) => a + r.errors.length, 0);
   const warns = report.results.reduce((a, r) => a + r.warnings.length, 0);
-  const resident = report.listedSkills !== undefined && report.listedSkills !== report.results.length ? ` (the ${report.listedSkills} resident here; the rest belong to modules this instance leaves off)` : '';
-  out.push(`skill-lint: ${report.results.length} skill(s), ${errs} error(s), ${warns} warning(s); listing ${report.listingChars} chars${resident} (~${Math.round(report.listingChars / 4)} tokens) vs ~${report.budgetChars}-char budget${report.overBudget ? ' — OVER: entries get truncated and routing degrades' : ''}`);
+  const residentN = report.residentSkills !== undefined ? report.residentSkills : report.listedSkills;
+  const resident = residentN !== undefined && residentN !== report.results.length ? ` ${residentN} resident here (the rest belong to modules this instance leaves off);` : '';
+  out.push(`skill-lint: ${report.results.length} skill(s), ${errs} error(s), ${warns} warning(s);${resident} listing ${report.listingChars} chars over ${report.listedSkills} listed skill(s) (~${Math.round(report.listingChars / 4)} tokens) vs ~${report.budgetChars}-char budget${report.overBudget ? ' — OVER: entries get truncated and routing degrades' : ''}`);
+  if (report.hiddenSkills) out.push(`skill-lint: ${report.hiddenSkills} hidden skill(s) (disable-model-invocation — typeable as /name, not in the model's listing, not counted): ${report.hiddenChars} chars — ${report.hiddenNames.join(', ')}`);
   return out.join('\n');
 }
 
@@ -210,7 +233,7 @@ function main() {
         if (!isSkillMd(fp) || !fs.existsSync(fp)) return;
         const report = lintSkills([fp]);
         const r = report.results[0];
-        if (r.errors.length || r.warnings.length) console.log('[skill-lint] ' + format(report).split('\n').slice(0, -1).join('\n[skill-lint] '));
+        if (r.errors.length || r.warnings.length) console.log('[skill-lint] ' + format(report).split('\n').filter((l) => !l.startsWith('skill-lint:')).join('\n[skill-lint] '));
       } catch (_) { /* a hook never breaks the edit */ }
       process.exitCode = 0;
     });
@@ -223,5 +246,5 @@ function main() {
   process.exitCode = report.results.some((r) => r.errors.length) ? 1 : 0;
 }
 
-module.exports = { lintFrontmatter, lintSkillFile, lintSkills, listSkillFiles, residentSkillFiles, splitFrontmatter, isSkillMd, format, DESC_WARN_CHARS, DESC_HARD_CHARS, LISTING_BUDGET_CHARS };
+module.exports = { lintFrontmatter, lintSkillFile, lintSkills, listSkillFiles, residentSkillFiles, splitFrontmatter, isSkillMd, isHidden, format, DESC_WARN_CHARS, DESC_HARD_CHARS, LISTING_BUDGET_CHARS };
 if (require.main === module) main();

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/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.42'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.44'; // 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)');

package/tests/hall_lead_row_home.mjs

@@ -0,0 +1,21 @@
+// .ov-row--lead is rendered only by the Collab page, so its grid rule lives in
+// collab.css, not oversight.css (task 1003637).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+
+const read = (f) => readFileSync(new URL(`../modules/hall-ui/public/${f}`, import.meta.url), 'utf8');
+
+test('oversight.css no longer defines .ov-row--lead', () => {
+  assert.doesNotMatch(read('oversight.css'), /\.ov-row--lead/);
+});
+
+test('collab.css owns the base rule and its 640px companion', () => {
+  const css = read('collab.css');
+  assert.match(css, /^\.ov-row--lead \{ grid-template-columns: auto minmax\(0, 1fr\) auto; \}/m);
+  assert.match(css, /@media \(max-width: 640px\) \{\s*\.ov-row--lead \{[^}]*\}\s*\.ov-row--lead > \.ov-row__right \{ grid-column: 2; \}/);
+});
+
+test('collab.js still renders the class, so the rule is not dead', () => {
+  assert.match(read('collab.js'), /ov-row--lead/);
+});

package/tests/module_manifest.mjs

@@ -370,3 +370,25 @@ test('every bundled module with a declarativeSeams block validates against its o
   }
   assert.deepEqual(bad, [], bad.join('\n'));
 });
+
+// --- howto.artifactUrl (ADR 0347 D3, task 1004365) ---
+
+test('howto.artifactUrl: optional, and an https claude.ai link is accepted', () => {
+  assert.equal(validateManifest(baseManifest()).valid, true);
+  for (const url of ['https://claude.ai/artifact/abc123', 'https://claude.ai/code/artifact/0b1c']) {
+    const r = validateManifest({ ...baseManifest(), howto: { artifactUrl: url } });
+    assert.equal(r.valid, true, `${url}: ${r.errors.join('; ')}`);
+  }
+});
+
+test('howto.artifactUrl: anything but an https claude.ai link is refused, as is an unknown key', () => {
+  for (const url of ['http://claude.ai/artifact/x', 'https://evil.example/claude.ai', 'https://claude.ai.evil.example/x',
+    'https://user:pw@claude.ai/x', 'javascript:alert(1)', '', 42]) {
+    const r = validateManifest({ ...baseManifest(), howto: { artifactUrl: url } });
+    assert.equal(r.valid, false, String(url));
+    assert.ok(r.errors.some((e) => e.startsWith('howto.artifactUrl')), r.errors.join('; '));
+  }
+  assert.ok(validateManifest({ ...baseManifest(), howto: { artifactURL: 'https://claude.ai/x' } }).errors
+    .some((e) => e.startsWith('howto.artifactURL: unknown key')));
+  assert.equal(validateManifest({ ...baseManifest(), howto: 'https://claude.ai/x' }).valid, false);
+});

package/tests/module_store_publish.mjs

@@ -27,12 +27,21 @@ function moduleJson(over = {}) {
   };
 }
 
-// A temp modules/ root holding one module. files: { relPath: content }.
+// A how-to with all five required sections (ADR 0347 D2).
+const HOWTO = [
+  '# Weather', '', '## What it does', 'Shows the weather.', '', '## Install and enable',
+  '`bongos module install weather`, then switch it on.', '', '## How to use it', 'Open /weather.', '',
+  '## Configuration', 'None.', '', '## Limits and known issues', 'None known.', '',
+].join('\n');
+
+// A temp modules/ root holding one module. files: { relPath: content }; a null
+// content leaves that file out.
 function fixture(files = {}, mj = moduleJson()) {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-publish-'));
   const dir = path.join(root, mj.key);
-  const all = { 'module.json': JSON.stringify(mj, null, 2), 'routes/weather.js': 'module.exports = () => null;\n', ...files };
+  const all = { 'module.json': JSON.stringify(mj, null, 2), 'routes/weather.js': 'module.exports = () => null;\n', 'HOWTO.md': HOWTO, ...files };
   for (const [rel, body] of Object.entries(all)) {
+    if (body === null) continue;
     fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true });
     fs.writeFileSync(path.join(dir, rel), body);
   }
@@ -54,12 +63,12 @@ function retar(tgz, edit) {
 test('pack: the tarball is the core release format — package/ root, inner manifest, a tree pin', async () => {
   const { tgz, manifest, sidecar } = pack(fixture());
   const names = format.readTar(tgz).map((e) => e.name).sort();
-  assert.deepEqual(names, ['package/.bongos-module.json', 'package/module.json', 'package/routes/weather.js']);
+  assert.deepEqual(names, ['package/.bongos-module.json', 'package/HOWTO.md', 'package/module.json', 'package/routes/weather.js']);
   assert.equal(manifest.artifact, 'bongos-module');
   assert.equal(manifest.module_key, 'weather');
   assert.equal(manifest.module_version, '1.2.0');
   assert.equal(manifest.core_version, '^1.0.0');
-  assert.equal(manifest.file_count, 2);
+  assert.equal(manifest.file_count, 3);
   assert.equal(manifest.tree_sha256, format.canonicalTreeHash(manifest.files));
   assert.equal(sidecar.tarball.sha256, format.sha256hex(tgz));
   assert.equal(sidecar.tarball.name, 'bongos-module-weather-1.2.0.tgz');
@@ -302,6 +311,81 @@ test('cli: uploads the packed bytes, and a store refusal is a failure exit with
   assert.ok(out.lines.some((l) => /HTTP 409/.test(l) && /already published/.test(l)));
 });
 
+// ---- the how-to gate (ADR 0347, task 1004365) -----------------------------------
+
+test('howto: a complete how-to passes, headings in any order and any case', () => {
+  assert.deepEqual(artifact.checkHowto(HOWTO), { ok: true, problems: [] });
+  const reordered = HOWTO.replace('## Configuration\nNone.\n', '').replace('# Weather', '# Weather\n## CONFIGURATION\nNone.');
+  assert.equal(artifact.checkHowto(reordered).ok, true);
+});
+
+test('howto: a missing file, a missing section and an empty section are each refused by name', () => {
+  assert.deepEqual(artifact.checkHowto(null).problems, ['HOWTO.md is missing — every store module ships one (ADR 0347)']);
+  assert.deepEqual(artifact.checkHowto(HOWTO.replace('## Configuration\nNone.\n', '')).problems,
+    ['HOWTO.md: section "Configuration" is missing']);
+  assert.deepEqual(artifact.checkHowto(HOWTO.replace('Open /weather.', '')).problems,
+    ['HOWTO.md: section "How to use it" is empty']);
+});
+
+test('howto: a prompt in a comment, a sub-heading alone, or a heading inside a code fence does not count', () => {
+  assert.deepEqual(artifact.checkHowto(HOWTO.replace('None known.', '<!-- say what goes wrong -->')).problems,
+    ['HOWTO.md: section "Limits and known issues" is empty']);
+  assert.deepEqual(artifact.checkHowto(HOWTO.replace('None known.', '### Later')).problems,
+    ['HOWTO.md: section "Limits and known issues" is empty']);
+  const fenced = HOWTO.replace('## Configuration\nNone.\n', '').replace('Open /weather.', 'Open /weather.\n```\n## Configuration\n```');
+  assert.deepEqual(artifact.checkHowto(fenced).problems, ['HOWTO.md: section "Configuration" is missing']);
+});
+
+test('howto: the scaffold\'s template has every section but fails the gate until it is written', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-howto-'));
+  moduleCli.scaffoldModule({ key: 'weather', modulesDir: root, core: '1.0.0' });
+  const text = fs.readFileSync(path.join(root, 'weather', 'HOWTO.md'), 'utf8');
+  const res = artifact.checkHowto(text);
+  assert.deepEqual(res.problems, artifact.HOWTO_SECTIONS.map((s) => `HOWTO.md: section "${s}" is empty`));
+});
+
+test('howto: the file is packed into the tarball, so its hash pins it to the version', async () => {
+  const v = await artifact.verifyModuleArtifact(pack(fixture()).tgz, { key: 'weather', requireHowto: true });
+  assert.equal(v.ok, true, v.message);
+  assert.ok(v.manifest.files.some((f) => f.path === 'HOWTO.md'));
+});
+
+test('howto: verify refuses an incomplete how-to only when asked, so older versions still install', async () => {
+  const tgz = pack(fixture({ 'HOWTO.md': null })).tgz;
+  assert.equal((await artifact.verifyModuleArtifact(tgz, { key: 'weather' })).ok, true, 'install/update verify is unchanged');
+  const v = await artifact.verifyModuleArtifact(tgz, { key: 'weather', requireHowto: true });
+  assert.equal(v.code, 'howto_incomplete');
+  assert.match(v.message, /HOWTO\.md is missing/);
+});
+
+test('cli: publish refuses a missing or incomplete how-to by name, before anything is uploaded', async () => {
+  for (const [files, re] of [
+    [{ 'HOWTO.md': null }, /HOWTO\.md is missing/],
+    [{ 'HOWTO.md': HOWTO.replace('## Configuration\nNone.\n', '') }, /section "Configuration" is missing/],
+    [{ 'HOWTO.md': HOWTO.replace('Shows the weather.', '') }, /section "What it does" is empty/],
+  ]) {
+    const out = sink();
+    let uploaded = false;
+    const code = await moduleCli.cmdPublish(['weather'], {
+      log: out.log, errlog: out.log, modulesDir: fixture(files), upload: async () => { uploaded = true; },
+    });
+    assert.equal(code, 1);
+    assert.equal(uploaded, false);
+    assert.ok(out.lines.some((l) => re.test(l)), out.lines.join('\n'));
+  }
+});
+
+test('cli: module check reports the how-to as advice and never fails an upstream check on it', () => {
+  const out = sink();
+  const code = moduleCli.cmdCheck(['weather'], {
+    log: out.log, errlog: out.log,
+    check: () => ({ ok: true, findings: [] }),
+    howtoCheck: () => artifact.checkHowto(null),
+  });
+  assert.equal(code, 0);
+  assert.ok(out.lines.some((l) => /HOWTO\.md is missing/.test(l) && /bongos module publish/.test(l)));
+});
+
 test('cli: no key is a usage error', async () => {
   assert.equal(await moduleCli.cmdPublish([], { log: () => {}, errlog: () => {} }), 2);
 });

package/tests/module_store_publish_route.mjs

@@ -66,13 +66,17 @@ async function invoke(handle, req) {
   return res;
 }
 
-function packed(version = '1.0.0') {
+// A how-to with all five required sections (ADR 0347 D2).
+const HOWTO = artifact.HOWTO_SECTIONS.map((h) => `## ${h}\nSome text.\n`).join('\n');
+
+function packed(version = '1.0.0', { howto = HOWTO } = {}) {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-src-'));
   const dir = path.join(root, '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: {},
   }));
+  if (howto !== null) fs.writeFileSync(path.join(dir, 'HOWTO.md'), howto);
   return artifact.packModule('weather', { modulesDir: root, modeOf: () => '644' }).tgz;
 }
 
@@ -119,3 +123,18 @@ test('a tarball for another key, garbage, or no body is refused before the regis
   assert.equal((await invoke(route.handle, { params: { key: 'Bad_Key' }, body: packed(), builder: { id: 42 } })).body.error, 'bad_module_key');
   assert.equal(state.versions.length, before);
 });
+
+test('an upload that skipped the CLI\'s how-to check is refused by the store, and nothing is kept', async () => {
+  const before = state.versions.length;
+  const missing = await invoke(route.handle, { params: { key: 'weather' }, body: packed('3.0.0', { howto: null }), builder: { id: 42 } });
+  assert.equal(missing.statusCode, 422);
+  assert.equal(missing.body.error, 'howto_incomplete');
+  assert.match(missing.body.message, /HOWTO\.md is missing/);
+  const empty = await invoke(route.handle, {
+    params: { key: 'weather' }, body: packed('3.0.0', { howto: HOWTO.replace('## Configuration\nSome text.', '## Configuration\n') }), builder: { id: 42 },
+  });
+  assert.equal(empty.body.error, 'howto_incomplete');
+  assert.match(empty.body.message, /section "Configuration" is empty/);
+  assert.equal(state.versions.length, before);
+  assert.ok(!fs.existsSync(path.join(STORE, 'weather', 'weather-3.0.0.tgz')));
+});

package/tests/skill_grade_audit.mjs

@@ -1,9 +1,10 @@
-// tests/skill_grade_audit.mjs — the /grade-audit skill exists and covers the
-// accountability sweep from the grader-hardening evaluation §6 (task 1002657):
-// the override ledger, dropped blocker/major findings on passing grades (with
-// the advisory-Narc attribution filter), the false-pass spot-check, and the
-// outage roll-up handoff — describing and queueing ONLY (ADR 0158 §2: it
-// never confirms a task or flips status; ADR 0162: it adds no approval step to a ship).
+// tests/skill_grade_audit.mjs — the grade AUDIT (once /grade-audit, now Part B of the
+// merged /grade-sweep — task 1004471) covers the accountability sweep from the
+// grader-hardening evaluation §6 (task 1002657): the override ledger, dropped
+// blocker/major findings on passing grades (with the advisory-Narc attribution
+// filter), the false-pass spot-check, and the outage roll-up handoff — describing and
+// queueing ONLY (ADR 0158 §2: it never confirms a task or flips status; ADR 0162: it
+// adds no approval step to a ship). /grade-audit stays typeable as a hidden alias.
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { readFileSync, existsSync } from 'node:fs';
@@ -11,16 +12,22 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const SKILL = path.join(ROOT, '.claude', 'skills', 'grade-audit', 'SKILL.md');
+const SKILL = path.join(ROOT, '.claude', 'skills', 'grade-sweep', 'SKILL.md');
+const ALIAS = path.join(ROOT, '.claude', 'skills', 'grade-audit', 'SKILL.md');
 
 // .claude/skills is INSTANCE-materialized; a neutral core checkout carries none
 // (task 1002470) — skip there, same guard shape as file_map.mjs.
 const skillsDirExists = existsSync(path.join(ROOT, '.claude', 'skills'));
 
-test('/grade-audit exists, covers the sweep legs, and stays describe-and-queue only', (t) => {
+// Part B of the merged file: from its heading to the shared report section.
+const partB = (md) => md.slice(md.indexOf('## Part B'), md.indexOf('## Report shape'));
+
+test('the grade audit (grade-sweep Part B) covers the sweep legs, and stays describe-and-queue only', (t) => {
   if (!skillsDirExists) return t.skip('.claude/skills not materialized in this checkout');
-  assert.ok(existsSync(SKILL), '.claude/skills/grade-audit/SKILL.md must exist (task 1002657)');
-  const md = readFileSync(SKILL, 'utf8');
+  assert.ok(existsSync(SKILL), '.claude/skills/grade-sweep/SKILL.md must exist (task 1004471, was grade-audit — task 1002657)');
+  const whole = readFileSync(SKILL, 'utf8');
+  const md = partB(whole);
+  assert.ok(md.length > 1000, 'Part B is present');
 
   // Data surfaces.
   assert.match(md, /\/api\/bongos\/public\/recent-shipped/, 'sweeps the recent-shipped window');
@@ -35,16 +42,26 @@ test('/grade-audit exists, covers the sweep legs, and stays describe-and-queue o
   assert.match(md, /blocker|major/, 'targets blocker/major findings on passing grades');
   assert.match(md, /Narc/i, 'carries the advisory-Narc attribution filter');
   assert.match(md, /capture\.js/, 'queues findings via capture.js');
-  assert.match(md, /\[grade-audit\]/, 'uses the deterministic title marker for idempotency');
+  assert.match(md, /\[grade-audit\]/, 'keeps the deterministic title marker for idempotency (old rows carry it)');
 
   // Leg 3 — false-pass spot-check (the 2/8 runtime-blindness classes).
   assert.match(md, /runtime/i, 'spot-checks for runtime-behavior blindness');
 
-  // Leg 4 — outage roll-up handoff.
-  assert.match(md, /\/grader-health/, 'hands outage windows to /grader-health');
+  // Leg 4 — outage roll-up hands a streak to the health half, now in the same file.
+  assert.match(md, /Part A/, 'hands outage streaks to Part A (was /grader-health)');
+
+  // The hard constraint — stated once for the whole merged skill.
+  assert.match(whole, /never confirm/i, 'states it never confirms');
+  assert.match(whole, /ADR 0162/, 'anchors the no-approval-step-on-a-ship constraint');
+  assert.ok(!/curl[^\n]*\/confirm/.test(whole), 'carries no ready-to-paste confirm curl');
+});
 
-  // The hard constraint.
-  assert.match(md, /never confirm/i, 'states it never confirms');
-  assert.match(md, /ADR 0162/, 'anchors the no-approval-step-on-a-ship constraint');
-  assert.ok(!/curl[^\n]*\/confirm/.test(md), 'carries no ready-to-paste confirm curl');
+test('/grade-audit still works when typed: a hidden alias that runs grade-sweep Part B (task 1004471)', (t) => {
+  if (!skillsDirExists) return t.skip('.claude/skills not materialized in this checkout');
+  const md = readFileSync(ALIAS, 'utf8');
+  assert.match(md, /^name: grade-audit$/m);
+  assert.match(md, /^disable-model-invocation: true$/m, 'hidden from the model\'s listing, typeable as /grade-audit');
+  assert.match(md, /grade-sweep\/SKILL\.md/, 'points at the merged skill by path');
+  assert.match(md, /Part B/, 'runs the audit half only');
+  assert.match(readFileSync(SKILL, 'utf8'), /^disable-model-invocation: true$/m, 'the merged grade skill is hidden too (owner ruling)');
 });