@bongos/core 1.20.43 → 1.20.44

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.43",
-  "core_contract": "1.20.43",
-  "source_commit": "4d771a1a0917c29baeb888e981459cade4da163d",
+  "core_version": "1.20.44",
+  "core_contract": "1.20.44",
+  "source_commit": "a1a3b0419e36145a922de74f56ad59e7c6a862d4",
   "source_ref": "HEAD",
-  "built_at": "2026-10-01T01:43:09.317Z",
+  "built_at": "2026-10-01T02:04:05.728Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 566,
     "agent_docs_stubbed": 27,
-    "functional_verbatim": 2690,
+    "functional_verbatim": 2691,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3284,
-  "tree_sha256": "9619017af56fd7bd25e2825f3559277af091a1bf7d9e7b01d3fd23413efac6d9",
+  "file_count": 3285,
+  "tree_sha256": "b3a3d377b25ba92b3ee9a45c0a72813f65530c1dad3549a203339bebc6cf1b05",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2262,7 +2262,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "a1fe44960e8dad577eb2b85d5d2e60829f423458721f8bf6f94318cde07fcdef"
+      "sha256": "4307e66fffa57ef78f14d21899770273433716303ad7b2d4ac7f4b838f41aea2"
     },
     {
       "path": "docs/architecture.md",
@@ -2797,12 +2797,12 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "1d0dd6bacd73b8a4eceb9d7fbf6fd89fdfa0d8e6b1576605ef50a438f69a69be"
+      "sha256": "4af4f158a9e9c33bd72de0881331c5d7646fa237a36ecb81f6d88214ae4e0f0f"
     },
     {
       "path": "docs/modules-contract.md",
       "mode": "0000644",
-      "sha256": "c82d7e11d94d7303da1af813147522b347dc1292d633ba3787d555211dbe9802"
+      "sha256": "15148b0d5a175c6eaf24fcc54709500e2c036ef966011c8505ecc8988a904b97"
     },
     {
       "path": "docs/onboarding/diagrams/01-task-lifecycle.mmd",
@@ -2887,7 +2887,7 @@
     {
       "path": "docs/page-readings.json",
       "mode": "0000644",
-      "sha256": "430b53669889f1df1cfb99359ab3ae819dd8c7d37d716271dab516c39d11eb6d"
+      "sha256": "c68874a27eee3390e2cd64c01b3898f6f71f0fbaf851b51fcffcd1aff952299f"
     },
     {
       "path": "docs/project-context.template.md",
@@ -5202,7 +5202,7 @@
     {
       "path": "modules/hall-ui/public/collab.css",
       "mode": "0000644",
-      "sha256": "d39ea908838f1eae4e4f29b49f667d9e08cdd961c7441cb1fbc9090ac7bd4457"
+      "sha256": "4ee8e77a58b688c93d9d0588ec2a5e47ce7d751ae84101a8547f45f07a34b71f"
     },
     {
       "path": "modules/hall-ui/public/collab.html",
@@ -5557,7 +5557,7 @@
     {
       "path": "modules/hall-ui/public/oversight.css",
       "mode": "0000644",
-      "sha256": "f2a6313335a12520f83c77d03e571900465ae0e46136839ba9f92164043ec69a"
+      "sha256": "582ab7d5151e8125537f7a2d969485a446ed7b69b4c4dba1e6b43168afaf1a0e"
     },
     {
       "path": "modules/hall-ui/public/palette.js",
@@ -9052,12 +9052,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "61fb420fbe1a74df0fdc837237a1625c3c9e361f4473b66ea06b0a088eb52945"
+      "sha256": "69714e37e8d92416589c29c25fbf93105b5e74c1fb8a7b0c4e61135cdab04e36"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7dc8116ba9b3b0c97b8c1ad59f3f0679d21580a21b79175074d3be21d279023d"
+      "sha256": "83a632e6a1841013c7720d8202c493b98cdc191c8e51c0d5dfd3adca29a958fb"
     },
     {
       "path": "public-docs/index.html",
@@ -9077,7 +9077,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "8ec55f2c1db4d0116b89d222385131b63500893aa9f860e7eb563de7173ce02a"
+      "sha256": "8d4fd2a1e48f98f5110d0358262ea82c8622848376dc56f35581b54e2cbb3a97"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9922,7 +9922,7 @@
     {
       "path": "scripts/gds/module-artifact.js",
       "mode": "0000644",
-      "sha256": "a16e9cee3135bcd14ae99f58dfbd17657610c2fc5b5c126ed052ccca49297428"
+      "sha256": "f2d0770ca07105a0555190783cd37ff838babcec337a93a2ebd2a448efc37062"
     },
     {
       "path": "scripts/gds/module-assess-security.js",
@@ -9937,7 +9937,7 @@
     {
       "path": "scripts/gds/module.js",
       "mode": "0000644",
-      "sha256": "2bb8d87422e2b24db1ea9fa0c51556b09a7bea99da5af7ad3798c3b386809f4b"
+      "sha256": "8563b7fa47b7c3f00e6c070c496a924875ea49ca41b681c1209c5819d2551f97"
     },
     {
       "path": "scripts/gds/move-escalation.js",
@@ -11167,7 +11167,7 @@
     {
       "path": "src/bongos/routes/modules.js",
       "mode": "0000644",
-      "sha256": "bd4e80ff8712d0797a62bddb3577f52f4cf161ac2273028e8a8def0455118e63"
+      "sha256": "3acd1e40da2502d9c69f7260548585f31e35a102c6dcc5cd58a71965a6b8a42c"
     },
     {
       "path": "src/bongos/routes/my-sessions.js",
@@ -11237,7 +11237,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b0af63fbad35e7a1006c0e8326238add2ab9a6d9d0eaad89d08a0fe7286c7443"
+      "sha256": "38d5ae5c4d42fa6941f1e3ea4365b7dca33258e71cd723bfe9dafe1b74a844a2"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11252,7 +11252,7 @@
     {
       "path": "src/module-loader/manifest-schema.js",
       "mode": "0000644",
-      "sha256": "2af9174e0a2793c04c2abe7e90cf8ec4d995e5f386f866b3b557671dc7e602e1"
+      "sha256": "e1e05eb67795d78e014dd08363cd82df06c15117c1df2b0758209d093f9343ce"
     },
     {
       "path": "src/module-loader/provenance.js",
@@ -13384,6 +13384,11 @@
       "mode": "0000644",
       "sha256": "0156e00234c90316c63c65a48c779edd05a56262947241cbd06de7a32ea8a881"
     },
+    {
+      "path": "tests/hall_lead_row_home.mjs",
+      "mode": "0000644",
+      "sha256": "3c12b6045361c5d6830f5bc16ca70b0443a4e16b660b9018eb659d12c988b41b"
+    },
     {
       "path": "tests/hall_mine_lens.mjs",
       "mode": "0000644",
@@ -14272,7 +14277,7 @@
     {
       "path": "tests/module_manifest.mjs",
       "mode": "0000644",
-      "sha256": "fcc12c33fc39c4cbd887afd18bc62480da30f4f3ec7dd70eafe3b6eff72b1f08"
+      "sha256": "19903e912a86ac216c7e7bf06585d7b7faf6b5689d246955402fc972ce3845f1"
     },
     {
       "path": "tests/module_owned_tests.mjs",
@@ -14297,12 +14302,12 @@
     {
       "path": "tests/module_store_publish.mjs",
       "mode": "0000644",
-      "sha256": "87fac3ad4c8bbbe2e1d08b978235db93e747f58726edbd043a21f32f6044ff34"
+      "sha256": "6392bc2e1554cdef18145a0598f4d7fc22305c0744e864c0f2526848609fd13a"
     },
     {
       "path": "tests/module_store_publish_route.mjs",
       "mode": "0000644",
-      "sha256": "4c96e94c15ef2d2f6fa1192d0cb1918ec0ae8b5d3300753962bfe6c1abdd3260"
+      "sha256": "59d14575351c6b6529c6aff8e661ce915b8159988ad13585eea752c4bde4d9b6"
     },
     {
       "path": "tests/module_store_registry_migration.mjs",

package/docs/api/openapi.json

@@ -19282,7 +19282,7 @@
           "store"
         ],
         "summary": "POST /store/modules/:key/versions",
-        "description": "POST /api/bongos/store/modules/:key/versions — publish one module version to 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 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. rank: metic+archon — it puts code in a shared store other instances install from. Gate: requirePermission('module.submit') — the atom that already guards filing a module into a shared queue; a dedicated `module.publish` atom is a follow-up once who-may-sell is decided.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `module.submit` (all required).",
+        "description": "POST /api/bongos/store/modules/:key/versions — publish one module version to 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, 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. rank: metic+archon — it puts code in a shared store other instances install from. Gate: requirePermission('module.submit') — the atom that already guards filing a module into a shared queue; a dedicated `module.publish` atom is a follow-up once who-may-sell is decided.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `module.submit` (all required).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/modules.js",
         "x-permissions": [

package/docs/module-api-changelog.md

@@ -2743,5 +2743,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.41 with no explicit bump. run 36801585300. (task 1002620)
   1.20.43 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.42 with no explicit bump. run 36802367948. (task 1002620)
+  1.20.44 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.43 with no explicit bump. run 36804013644. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -113,6 +113,7 @@ Every module must have a `module.json` at its root (`modules/<key>/module.json`)
   "consumes": [],                       // OPTIONAL. Seam ports this module resolves (required caps).
   "prerequisites": { "modules": [] },   // OPTIONAL. Other modules that must be enabled first.
   "spend": { "requiresPayer": true },   // OPTIONAL. This module spends MONEY for whoever calls it.
+  "howto": { "artifactUrl": "https://claude.ai/…" }, // OPTIONAL. A Claude page beside HOWTO.md — never instead of it (ADR 0347 D3).
   "dependencies": { "discord.js": "^14.26.4" } // OPTIONAL. External npm deps this module needs at runtime.
 }
 ```
@@ -321,6 +322,7 @@ This creates `modules/<key>/` with:
 - `migrations/` — empty directory.
 - `ui/` — empty directory.
 - `CLAUDE.md` — per-module reference explaining the boundary, the seam pattern, and what to keep out of the module.
+- `HOWTO.md` — the how-to for the person who installs the module: the five required sections as headings, each with its prompt in an HTML comment (see §6).
 
 ### 2. Write the module
 
@@ -359,6 +361,7 @@ Run `bongos upgrade` to confirm coreVersion compatibility, then `node scripts/gd
 - Your first publish of a key makes you its author; only the author can publish later versions, and a delisted key takes none.
 - The publish denylist applies (ADR 0098), plus a refusal of credential-named files (`.env*`, `*.pem`, `*.key`, `id_rsa`, …) anywhere in the module. The store re-checks every hash and the denylist itself.
 - Gate: Metic+ (`module.submit`) for now. This is not `bongos module submit`, which proposes a module *into* core.
+- **A how-to is required** ([ADR 0347](adr/0347-every-store-module-ships-a-how-to.md)). `modules/<key>/HOWTO.md` is what a buyer reads — the store shows it as the module's page — so it is written for the person who installs the module, not for an AI working inside it (that is `CLAUDE.md`). It is plain Markdown: any AI or person can write it. Publish refuses the version unless it has these five level-2 headings, in any order and any case, each with some text under it: `## What it does`, `## Install and enable`, `## How to use it` (with one worked example), `## Configuration` ("None." is fine) and `## Limits and known issues` ("None known." is fine). HTML comments don't count as text, so the scaffold's prompts must be replaced. The refusal names each failing section. The check is one function, `checkHowto` in `scripts/gds/module-artifact.js`; the CLI runs it before uploading and the store runs it again on upload, so a hand-built upload can't skip it. `bongos module check` reports it as advice only — an upstream submit is not gated by it. Install and update don't re-check it, so a version published before the gate still installs. The file travels in the tarball, so its hash pins it to the version. An optional `howto.artifactUrl` in `module.json` (an `https://` link on `claude.ai`) is shown as an extra, never graded.
 
 ### 7. Install from the store
 

package/docs/page-readings.json

@@ -12,7 +12,7 @@
       "surface": "builders",
       "title": "Repo Atlas",
       "states_read": ["map","truth","detail","index","out"],
-      "files_hash": "dba137b09374d2e6",
+      "files_hash": "6ad36383395e3de3",
       "reading_hash": "411161b0a6167a1e",
       "counts": {"lines":13,"placed":8,"shared":5,"unplaced":0},
       "omitted": {"data":1},
@@ -38,7 +38,7 @@
       "surface": "builders",
       "title": "Blockers",
       "states_read": ["default"],
-      "files_hash": "afabc8607665ad52",
+      "files_hash": "632c93f4db32b846",
       "reading_hash": "c8c742437a2c76c2",
       "counts": {"lines":16,"placed":6,"shared":5,"unplaced":5},
       "omitted": {"data":4},
@@ -67,7 +67,7 @@
       "surface": "builders",
       "title": "Board Room",
       "states_read": ["room","out","sitting-meta","objection-form"],
-      "files_hash": "c1978638f2ef9558",
+      "files_hash": "2d1d695b800e13bc",
       "reading_hash": "202a0cbb6bc54aac",
       "counts": {"lines":56,"placed":26,"shared":5,"unplaced":25},
       "omitted": {"data":9},
@@ -136,7 +136,7 @@
       "surface": "builders",
       "title": "Collab",
       "states_read": ["board","out"],
-      "files_hash": "793b7af1446ab69e",
+      "files_hash": "2acb05affd061ce7",
       "reading_hash": "cedb8171693a308e",
       "counts": {"lines":68,"placed":23,"shared":4,"unplaced":41},
       "omitted": {"data":12},
@@ -145,7 +145,7 @@
         {"key":"L0001","section":"skip link","text":"Skip to content","placement":"shared","file":"modules/hall-ui/public/shell.js","line":767,"string_id":"87cee78ca134"},
         {"key":"L0002","section":"top bar","text":"Collab","placement":"shared"},
         {"key":"L0003","section":"top bar","text":"Jump to…","placement":"shared","file":"modules/hall-ui/public/shell.js","line":487,"string_id":"eba610d25523"},
-        {"key":"L0004","section":"top bar","text":"⌘K","placement":"shared"},
+        {"key":"L0004","section":"top bar","text":"Ctrl K","placement":"shared"},
         {"key":"L0005","section":"Collab","text":"Collab","placement":"unplaced"},
         {"key":"L0006","section":"Collab","text":"{…} and {…}","placement":"placed","file":"modules/hall-ui/public/profile-nudge.js","line":77,"string_id":"56b00d773232"},
         {"key":"L0007","section":"Collab","text":"Waiting on you","placement":"unplaced"},
@@ -217,7 +217,7 @@
       "surface": "builders",
       "title": "Copy desk",
       "states_read": ["queue","out","search","composer","closer","proposer"],
-      "files_hash": "d96a711bf72a38ae",
+      "files_hash": "8631e59378897edf",
       "reading_hash": "8d8433d27c7405a0",
       "counts": {"lines":106,"placed":71,"shared":5,"unplaced":30},
       "omitted": {"data":117},
@@ -260,7 +260,7 @@
         {"key":"L0035","section":"Flagged","text":"said, when flagged:","placement":"placed","file":"modules/hall-ui/public/copy-desk.js","line":124,"string_id":"2a42549b34ae"},
         {"key":"L0036","section":"Flagged","text":"{…} of {…}","placement":"placed","file":"modules/hall-ui/public/sky-panel.js","line":120,"string_id":"73c1372b43d9"},
         {"key":"L0037","section":"Flagged","text":"target {…}","placement":"unplaced"},
-        {"key":"L0038","section":"Flagged","text":"Restricted.","placement":"placed","file":"modules/hall-ui/public/board-room.js","line":521,"string_id":"0887725744f2"},
+        {"key":"L0038","section":"Flagged","text":"Restricted.","placement":"placed","file":"modules/hall-ui/public/board-room.js","line":526,"string_id":"0887725744f2"},
         {"key":"L0039","section":"Flagged","text":"off voice","placement":"unplaced"},
         {"key":"L0040","section":"Flagged","text":"moved","placement":"unplaced"},
         {"key":"L0041","section":"Flagged","text":"whole {…}","placement":"unplaced"},
@@ -278,7 +278,7 @@
         {"key":"L0053","section":"Said more than once","text":"Available from the {…} rank up.","placement":"placed","file":"modules/hall-ui/public/gate.js","line":237,"string_id":"1de02052abf2"},
         {"key":"L0054","section":"Said more than once","text":"Could not save. Try again.","placement":"placed","file":"modules/hall-ui/public/settings-interaction.js","line":96,"string_id":"8c234d5c8bd4"},
         {"key":"L0055","section":"Said more than once","text":"already flagged","placement":"unplaced","occurrences":2},
-        {"key":"L0056","section":"Said more than once","text":"Restricted.","placement":"placed","file":"modules/hall-ui/public/board-room.js","line":521,"string_id":"0887725744f2"},
+        {"key":"L0056","section":"Said more than once","text":"Restricted.","placement":"placed","file":"modules/hall-ui/public/board-room.js","line":526,"string_id":"0887725744f2"},
         {"key":"L0057","section":"Said more than once","text":"looked at","placement":"unplaced"},
         {"key":"L0058","section":"Find something to flag","text":"Find something to flag","placement":"placed","file":"modules/hall-ui/public/copy-desk.html","line":64,"string_id":"1def0e7c716e"},
         {"key":"L0059","section":"Find something to flag","text":"Search every string the product shows a person, by what it says or the file it lives in.","placement":"placed","file":"modules/hall-ui/public/copy-desk.html","line":65,"string_id":"46711f7bc3df"},
@@ -336,7 +336,7 @@
       "surface": "builders",
       "title": "Deploy",
       "states_read": ["work","out"],
-      "files_hash": "786235bca48a981a",
+      "files_hash": "d06badab7642ea93",
       "reading_hash": "eb5acd9bd5fc73e9",
       "counts": {"lines":7,"placed":0,"shared":5,"unplaced":2},
       "omitted": {"data":1},
@@ -838,7 +838,7 @@
       "surface": "builders",
       "title": "Fleet costs",
       "states_read": ["ledger","out"],
-      "files_hash": "23ae0ec03adc9b80",
+      "files_hash": "5056fa71f75d5c6d",
       "reading_hash": "9493385a64bb0e9f",
       "counts": {"lines":22,"placed":6,"shared":5,"unplaced":11},
       "omitted": {"data":11},
@@ -873,7 +873,7 @@
       "surface": "builders",
       "title": "Gate",
       "states_read": ["queue","out","approve"],
-      "files_hash": "14ac6944f79fb3cb",
+      "files_hash": "ec25d2c025db0abd",
       "reading_hash": "08d3e5d3657e5afb",
       "counts": {"lines":41,"placed":17,"shared":5,"unplaced":19},
       "omitted": {"data":34},
@@ -884,7 +884,7 @@
         {"key":"L0003","section":"top bar","text":"Jump to…","placement":"shared","file":"modules/hall-ui/public/shell.js","line":487,"string_id":"eba610d25523"},
         {"key":"L0004","section":"top bar","text":"Ctrl K","placement":"shared"},
         {"key":"L0005","section":"Gate","text":"Gate","placement":"unplaced"},
-        {"key":"L0006","section":"Gate","text":"Changes touching protected build surfaces, held for your approval.","placement":"placed","file":"modules/hall-ui/public/gate.js","line":431,"string_id":"4b714191b423"},
+        {"key":"L0006","section":"Gate","text":"Changes touching protected build surfaces, held for your approval.","placement":"placed","file":"modules/hall-ui/public/gate.js","line":432,"string_id":"4b714191b423"},
         {"key":"L0007","section":"Gate","text":"Awaiting your approval","placement":"unplaced"},
         {"key":"L0008","section":"Gate","text":"held at the gate check","placement":"unplaced"},
         {"key":"L0009","section":"Gate","text":"Hard-floor holds","placement":"unplaced"},
@@ -997,7 +997,7 @@
       "surface": "builders",
       "title": "Goals",
       "states_read": ["list","filters","cards","detail","out"],
-      "files_hash": "c0cc109370ca958c",
+      "files_hash": "968230876b9152ba",
       "reading_hash": "cf7f8688bcae4dd5",
       "counts": {"lines":146,"placed":36,"shared":5,"unplaced":105},
       "omitted": {"data":250},
@@ -1008,14 +1008,14 @@
         {"key":"L0003","section":"top bar","text":"Jump to…","placement":"shared","file":"modules/hall-ui/public/shell.js","line":487,"string_id":"eba610d25523"},
         {"key":"L0004","section":"top bar","text":"Ctrl K","placement":"shared"},
         {"key":"L0005","section":"Goals","text":"Goals","placement":"unplaced"},
-        {"key":"L0006","section":"Goals","text":"Goal {…}","placement":"placed","file":"modules/hall-ui/public/gate.js","line":280,"string_id":"ec88b946ad16","state":"detail"},
+        {"key":"L0006","section":"Goals","text":"Goal {…}","placement":"placed","file":"modules/hall-ui/public/gate.js","line":288,"string_id":"ec88b946ad16","state":"detail"},
         {"key":"L0007","section":"Goals","text":"{…} and {…}","placement":"placed","file":"modules/hall-ui/public/profile-nudge.js","line":77,"string_id":"56b00d773232","occurrences":8},
         {"key":"L0008","section":"Goals","text":"See which goals wait on each other →","placement":"placed","file":"modules/hall-ui/public/goals.html","line":47,"string_id":"292761c89fae"},
         {"key":"L0009","section":"Goals","text":"← All goals","placement":"placed","file":"modules/hall-ui/public/goals.html","line":83,"string_id":"d4b84b7fbdeb","state":"detail"},
         {"key":"L0010","section":"#1000081 {…}","text":"Claude's notes on this goal","placement":"placed","file":"modules/hall-ui/public/goals.html","line":94,"string_id":"5b3b75ee0596","state":"detail"},
         {"key":"L0011","section":"Completion3","text":"Completion","placement":"unplaced","state":"detail"},
         {"key":"L0012","section":"Completion3","text":"{…} of {…} criteria satisfied","placement":"placed","file":"modules/hall-ui/public/goals-lib.js","line":32,"string_id":"cc5106af4b35","state":"detail"},
-        {"key":"L0013","section":"Completion3","text":"Goal {…}","placement":"placed","file":"modules/hall-ui/public/gate.js","line":280,"string_id":"ec88b946ad16","state":"detail"},
+        {"key":"L0013","section":"Completion3","text":"Goal {…}","placement":"placed","file":"modules/hall-ui/public/gate.js","line":288,"string_id":"ec88b946ad16","state":"detail"},
         {"key":"L0014","section":"Completion3","text":"{…} — harness fixture text","placement":"unplaced","state":"detail","occurrences":3},
         {"key":"L0015","section":"Members0","text":"Members","placement":"unplaced","state":"detail"},
         {"key":"L0016","section":"Members0","text":"No {…} assigned yet — an Archon can appoint one.","placement":"unplaced","state":"detail"},
@@ -1156,7 +1156,7 @@
       "surface": "builders",
       "title": "Government",
       "states_read": ["constitution","out","permissions","board","constitution-tab"],
-      "files_hash": "5181c9903bdea83f",
+      "files_hash": "c1c4058d40d669d2",
       "reading_hash": "f7f7466cabdf5569",
       "counts": {"lines":71,"placed":24,"shared":5,"unplaced":42},
       "omitted": {"data":10},
@@ -1185,7 +1185,7 @@
         {"key":"L0021","section":"Constitution","text":"Every {…} builder at","placement":"unplaced"},
         {"key":"L0022","section":"Constitution","text":"or above","placement":"placed","file":"modules/hall-ui/public/government.js","line":564,"string_id":"c38db02adb61"},
         {"key":"L0023","section":"Constitution","text":"sits on the board — that is","placement":"unplaced"},
-        {"key":"L0024","section":"Constitution","text":"and","placement":"placed","file":"modules/hall-ui/public/deploy.js","line":375,"string_id":"084748fd85b4"},
+        {"key":"L0024","section":"Constitution","text":"and","placement":"placed","file":"modules/hall-ui/public/deploy.js","line":541,"string_id":"084748fd85b4"},
         {"key":"L0025","section":"Constitution","text":". Membership follows the rank, live.","placement":"unplaced"},
         {"key":"L0026","section":"Constitution","text":"What counts as passing","placement":"unplaced"},
         {"key":"L0027","section":"Constitution","text":"Items pass by","placement":"unplaced"},
@@ -1584,7 +1584,7 @@
       "surface": "builders",
       "title": "Modules",
       "states_read": ["browse","search-empty","lens","details","out"],
-      "files_hash": "38f79e90abc42a25",
+      "files_hash": "e02acc87a87fbb67",
       "reading_hash": "165201cda2af2264",
       "counts": {"lines":42,"placed":14,"shared":5,"unplaced":23},
       "omitted": {"data":77},
@@ -2222,7 +2222,7 @@
       "surface": "builders",
       "title": "Project settings",
       "states_read": ["default"],
-      "files_hash": "f3007d41f4f59d9f",
+      "files_hash": "01c19996a012a0d3",
       "reading_hash": "940a00917a01cd2e",
       "counts": {"lines":10,"placed":5,"shared":5,"unplaced":0},
       "omitted": {"data":1},
@@ -2388,7 +2388,7 @@
       "surface": "builders",
       "title": "Sessions",
       "states_read": ["ledger","out"],
-      "files_hash": "794fdcbab2e44337",
+      "files_hash": "ad46927c48018cef",
       "reading_hash": "b8315ec3484a1431",
       "counts": {"lines":54,"placed":15,"shared":5,"unplaced":34},
       "omitted": {"data":16},
@@ -2980,7 +2980,7 @@
       "surface": "builders",
       "title": "Watch",
       "states_read": ["board","out","operations","security"],
-      "files_hash": "4b89e8960b706953",
+      "files_hash": "3acbd4398dd35520",
       "reading_hash": "de49e347cca76e41",
       "counts": {"lines":156,"placed":44,"shared":5,"unplaced":107},
       "omitted": {"data":123},

package/modules/hall-ui/public/collab.css

@@ -4,7 +4,7 @@
    feel collaborative" — asked of you left, your asks right, every open ask
    below, each condensed to the newest three with a show-all). The panel is the
    shell's .scroll, the two-up is the shell's .view-zone--band, the row is
-   oversight.css's .ov-row--lead (a face, then the words, then the state), the
+   the .ov-row--lead below (a face, then the words, then the state), the
    age is a .fact-pill, the context a .fact-chip, the expander the shell's
    .btn-ghost. This sheet holds only what Collab has and no other page does: the
    colour of each age band, the faces, the block head, the lit personal call, and
@@ -168,6 +168,13 @@
    entirely (task 1004041): the age pill says how long in words and carries the
    exact timestamp on its title, so a date beside it was the same fact twice —
    which is what the "All open asks" rows were doing at full width. */
+/* The --lead row: a face, then the words, then the state. Only Collab renders it,
+   so the rule lives here (it was in oversight.css, unused by any oversight page). */
+.ov-row--lead { grid-template-columns: auto minmax(0, 1fr) auto; }
+@media (max-width: 640px) {
+  .ov-row--lead { grid-template-columns: auto minmax(0, 1fr); }
+  .ov-row--lead > .ov-row__right { grid-column: 2; }
+}
 .cb-band .ov-row--lead { grid-template-columns: auto minmax(0, 1fr); row-gap: 8px; }
 .cb-band .ov-row--lead > .ov-row__right {
   grid-column: 2;

package/modules/hall-ui/public/oversight.css

@@ -94,7 +94,6 @@
   border-top: var(--line) solid var(--rule-soft);
 }
 .ov-rows > .ov-row:first-child, .ov-group__head + .ov-rows > .ov-row:first-child, .ov-group__head + .ov-row { border-top: 0; }
-.ov-row--lead { grid-template-columns: auto minmax(0, 1fr) auto; }
 /* A dense row: a permission, a voter, a machine principal — sixty of them in
    one panel is the ordinary case, so the air tightens. */
 .ov-row--dense { padding: 10px 0; }
@@ -131,8 +130,6 @@ a.ov-row__title:hover { color: var(--accent-ink); text-decoration: underline; te
 .ov-row__when { font-size: 12.5px; color: var(--ink-faint); font-variant-numeric: tabular-nums; white-space: nowrap; }
 @media (max-width: 640px) {
   .ov-row { grid-template-columns: minmax(0, 1fr); }
-  .ov-row--lead { grid-template-columns: auto minmax(0, 1fr); }
-  .ov-row--lead > .ov-row__right { grid-column: 2; }
   .ov-row__right { align-items: flex-start; text-align: left; }
   .ov-row__actions { justify-content: flex-start; }
 }

package/package-lock.json

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

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/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.43'; // 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')));
+});