@bongos/core 1.19.1080 → 1.19.1081

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1080",
-  "core_contract": "1.19.1080",
-  "source_commit": "266542d6d4b7b351e1b5e52e624d6429f20e4a3e",
+  "core_version": "1.19.1081",
+  "core_contract": "1.19.1081",
+  "source_commit": "4c16627cb7cf5c157bc8f62ad568bba7392ab994",
   "source_ref": "HEAD",
-  "built_at": "2026-09-29T22:14:01.252Z",
+  "built_at": "2026-09-29T22:26:53.648Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 550,
+    "docs_redacted": 551,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2535,
+    "functional_verbatim": 2544,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3111,
-  "tree_sha256": "05cc1fdd03c698fc64c21d2c5b4c72150f293acda99233129517b7954d4dfda8",
+  "file_count": 3121,
+  "tree_sha256": "522f4882eb02038ac8ec418b2ce059e889a48c0f20dcd91a32ea13ed45eac6aa",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -322,12 +322,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "8aa624b247e99bb0a7e3a97745ecd4aa64d7fdddc89d92f47cb20d433d2ad5b0"
+      "sha256": "313943caf3bc117539688dafeecb7a3bc1746c3038d68e471e652e303bad53d7"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "510df3006216f3a54f88d90e802d565cc52753ab723061787229ee3d65bd5c83"
+      "sha256": "4fff2b043649f142e270d01f844e6fcd2f41466f12a0897f64fe745a8dec9685"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -337,17 +337,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "3e76df3485bb6fb4555e2b85b6637104718eee1fd325f9a951641dc971833295"
+      "sha256": "3faf82efd3a0b620552cf75d430d7c750e9c1c74b59825774618e265ee2d0b0a"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "129e807451025dd8346054523b1829db460319c04c640b9e78af39ba012c73bc"
+      "sha256": "896ad373b22d96a0be3d404f665fea630dd2cd064e33148908ab1d2ceb64ab3e"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "de3ceb5761e334327e7e6367acc8dc4daea75561c1b17c967bb0b7fc43aa7dc1"
+      "sha256": "b9d2c891e25c7da32829290b458491ceb6a0ae6461a976801d7b9976d6448473"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -2182,7 +2182,7 @@
     {
       "path": "docs/adr/0343-a-module-score-is-a-security-gate-then-an-average-of-visible-parts.md",
       "mode": "0000644",
-      "sha256": "821f3c073de063aa9f3df9622a5b138cc5060754bb986cd5c747494150ec59db"
+      "sha256": "668d76cffbfaeb9662fc84b4d2c185bc7cd0109a403e6b9bf3032ebe3b569457"
     },
     {
       "path": "docs/adr/0344-a-tester-is-a-project-that-opts-in-once.md",
@@ -2199,20 +2199,25 @@
       "mode": "0000644",
       "sha256": "2ac7140de42599e7ab20785a3fc9265be60fbcd2c4438b2bdc65238c25657c17"
     },
+    {
+      "path": "docs/adr/0347-every-store-module-ships-a-how-to.md",
+      "mode": "0000644",
+      "sha256": "c662705a72d4f7a11e71b0ad5d7ceb6f9c8a4c252925e3c0b4f1584bb1b40a04"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "835128e78686d49a23125ab8cc09ca90714c6706beb171114ebb34de4aaf548a"
+      "sha256": "72757774554d673f85d7f881f45d12bf5ee3f9b8c1797b50d3de2001dcdaf2de"
     },
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "db6392644382a35358daedffe8289ba644ee4d005e842110271702966a8e7cd3"
+      "sha256": "933700d35f098a683e10b72c606ccbdbde79baeed24d860ca3c65edcce38486e"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "b3795bc67242cfbebf5cd0023327dfc768293fbe09b5998b3c0c2a8f26754ea0"
+      "sha256": "92eb5b8ca11812ff15b26b89971b0565a2c379ca0db68f4f11177d6e485cf6bc"
     },
     {
       "path": "docs/architecture.md",
@@ -2742,7 +2747,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f6df65117a87e0af4721f2872bba4ee9f7ab4a01a8ae8b76d38206cad08bf712"
+      "sha256": "b9efde41756d37bae682d8147229faa46bc7b07a0426563ae6712ea55d7f6e2a"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7209,10 +7214,15 @@
       "mode": "0000644",
       "sha256": "0640a034263db802ba64a960f8f71001ecd69b1dffbf54497efc9df6cc778ab0"
     },
+    {
+      "path": "modules/provisioning/migrations/provisioning_028_render_standup.sql",
+      "mode": "0000644",
+      "sha256": "9726682ff47916ca8ef999fe70ed5995c3bad7680b0821b87e4cab8a74d9f867"
+    },
     {
       "path": "modules/provisioning/module.json",
       "mode": "0000644",
-      "sha256": "6a6f0aeefd43d68a877a987787a82b02838c8f8f7d3caf53233e68743c425a57"
+      "sha256": "e67258d932d180476a4662df53ee7b39efd865651755f2627855a248f3138266"
     },
     {
       "path": "modules/provisioning/onboard-plan.js",
@@ -7247,7 +7257,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "fcd72068122a7f829fe892da120442edb8042a5dc361e112e82115fd655606ea"
+      "sha256": "92e9a12c0d07d87a16f0d036369967a60c2dfaca3fb1bce78fab97ad54dac0bf"
     },
     {
       "path": "modules/provisioning/public-refusal.js",
@@ -7264,6 +7274,11 @@
       "mode": "0000644",
       "sha256": "4c933aad1307378496d47960e24c9d797a1f122f28aefa27b769f336e4cf2e75"
     },
+    {
+      "path": "modules/provisioning/render-standup.js",
+      "mode": "0000644",
+      "sha256": "69142ba889a008b78ef2222c5acfe7c8c2552bc21df3264ce698e9101f3dee8e"
+    },
     {
       "path": "modules/provisioning/repo-private.js",
       "mode": "0000644",
@@ -7299,6 +7314,11 @@
       "mode": "0000644",
       "sha256": "18a8a728c48070f99dfdaa1c21d738f8d6fcfe8dc8534574fc115cec77f8bf77"
     },
+    {
+      "path": "modules/provisioning/routes/render-standup.js",
+      "mode": "0000644",
+      "sha256": "a1ff9877e727da483946a69dade72a74d0baedd4deb565c8a4c43b43812a4186"
+    },
     {
       "path": "modules/provisioning/routes/repo-private.js",
       "mode": "0000644",
@@ -8602,12 +8622,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "4187718df5a94313b87e2871b5c296229ea1a92dabe2c75275f05e3174539c74"
+      "sha256": "946d21b8b8e584a4e4e6a3a89d11b1e2dc2ba8de5490db77969eab7f4abd474b"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4307d22a2cadfdbbd821db8058f22dc4b74f47864b5d405a8b6efca3fd842158"
+      "sha256": "0c96fbccafa2dc7ecce6142620055231ed84dfaebaa15c3d43bda539e2498750"
     },
     {
       "path": "public-docs/index.html",
@@ -8627,7 +8647,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "e987059aae853c4e12e0890a050c9d8b1f81d2254060d5ea714378ec60b2193e"
+      "sha256": "4b2fec4975e2080384ad450a2b89d86ff3d700bd3c1805392fdb89a8744a2ebf"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9594,6 +9614,11 @@
       "mode": "0000644",
       "sha256": "6a784f63078e5cb2c0f85475672b02b18ded67a36a8041b1ba3643b227a465d0"
     },
+    {
+      "path": "scripts/gds/provision-render.js",
+      "mode": "0000644",
+      "sha256": "33c1c71cdd367305ae57849511f4bb1965a7cb74b4751303fcbb74b8a6ecc040"
+    },
     {
       "path": "scripts/gds/provision-repo-auth.js",
       "mode": "0000644",
@@ -9612,7 +9637,7 @@
     {
       "path": "scripts/gds/provision-teardown.js",
       "mode": "0000644",
-      "sha256": "e4ed73f42e4e9c6d9903f8a4d64bc125c09ba42f996b8741b125a972c3afcfb4"
+      "sha256": "60ee12f5ebfa74d4ed8224e93fbd632ef5df750c3842221546de9682bdb31170"
     },
     {
       "path": "scripts/gds/provision-units.js",
@@ -9622,7 +9647,7 @@
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "563eb4001dba94c4f83ba31e0a004f946e2124bfebb581c73d1c6dc43602766a"
+      "sha256": "d70a94e7dd757b6f57b644ba839117d6624574c25105853048b0e5c6ee6c6320"
     },
     {
       "path": "scripts/gds/publish-credential-check.js",
@@ -9709,6 +9734,11 @@
       "mode": "0000644",
       "sha256": "f73e495ab63fbca755e652d284e378d9b2afef67fe43c4c5a66e2962c92cef1d"
     },
+    {
+      "path": "scripts/gds/render-api.js",
+      "mode": "0000644",
+      "sha256": "1ed4918bf4c615bd4d5ef5b38c2f221df1d1aa80c232f5fe5e056299b6414d08"
+    },
     {
       "path": "scripts/gds/render-check.js",
       "mode": "0000644",
@@ -9719,6 +9749,11 @@
       "mode": "0000644",
       "sha256": "07c4fa6c1c3a9e7502e44abf6ed4d82125bccfd81d1bea8f4b5095c710d07f94"
     },
+    {
+      "path": "scripts/gds/render-payload.js",
+      "mode": "0000644",
+      "sha256": "30de1bc73ee0af4d60577bad0744ff07ba165965b0d24459ce0d85dfcc92a27e"
+    },
     {
       "path": "scripts/gds/repo-metrics.js",
       "mode": "0000644",
@@ -10702,7 +10737,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "5f4628ecd7603c1275a4ea0efcdef38540130eb9dfdb6eb0d37dbd28fe675663"
+      "sha256": "0cff8622b007399191c9acb9f2b8d0e502a88dd028d6a9243c05425029b4ffb6"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -14099,6 +14134,11 @@
       "mode": "0000644",
       "sha256": "20de6ef694e176459b690aac55351f97a77bf91a3076870ba43972a6b8b6e54c"
     },
+    {
+      "path": "tests/provision_render.mjs",
+      "mode": "0000644",
+      "sha256": "775438e10325d1dd38f4f14ebc620b4d01bf1546d94382825be8fc4b658e2801"
+    },
     {
       "path": "tests/provision_repo_private.mjs",
       "mode": "0000644",
@@ -14209,6 +14249,11 @@
       "mode": "0000644",
       "sha256": "641d4ba5fd4de4034e7059b835e98e5a386917d76935555e43c3eb436cbaeb20"
     },
+    {
+      "path": "tests/provisioning_render_route.mjs",
+      "mode": "0000644",
+      "sha256": "e904608ab90777976be12bbfe6d18bb8bbab9b60200d05625b1381ef4f4e6aa9"
+    },
     {
       "path": "tests/provisioning_repo_private_route.mjs",
       "mode": "0000644",
@@ -14232,7 +14277,7 @@
     {
       "path": "tests/provisioning_settings_apply.mjs",
       "mode": "0000644",
-      "sha256": "550f67b56dd92d413a1bafc70d76375df9c02d84f9d3e4dfd5789697ae0164f0"
+      "sha256": "92d004e056d55d3b24083e5eb31da64ac5466e34a89f1fb205377882cdcb493c"
     },
     {
       "path": "tests/provisioning_settings_env.mjs",
@@ -14252,7 +14297,7 @@
     {
       "path": "tests/provisioning_teardown_intent.mjs",
       "mode": "0000644",
-      "sha256": "51cbc39169b50eae3e88a2d435bfe1d2f25474c12125898040715b0c35aedbf9"
+      "sha256": "08128da3c6b810df963cb167cf29608181627d6c6203efe57f27d1c29e22d54a"
     },
     {
       "path": "tests/provisioning_teardown_states.mjs",
@@ -14439,6 +14484,11 @@
       "mode": "0000644",
       "sha256": "39eaa32121eae07fa7f508d60324e896e4c1b98c53ff390bb8bdca4b952c874f"
     },
+    {
+      "path": "tests/render_api.mjs",
+      "mode": "0000644",
+      "sha256": "8a210e13b8fe1d65c73c3d5a59fada131297a1875b57807cee91534f3b2741c0"
+    },
     {
       "path": "tests/render_check.mjs",
       "mode": "0000644",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 439 operations across 67 resource groups
+- 440 operations across 67 resource groups
 
 ## Use it from your project
 

package/clients/bongos-client/bongos-client.global.js

@@ -797,6 +797,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder — GET /provisioning/instances/:id/invite-suggestions
       getProvisioningInstancesIdInviteSuggestions: (args) => request("GET", "/provisioning/instances/{id}/invite-suggestions", { hasBody: false }, args),
+      // POST /provisioning/instances/{id}/render — rank: any-builder — POST /provisioning/instances/:id/render
+      postProvisioningInstancesIdRender: (args) => request("POST", "/provisioning/instances/{id}/render", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/repo-private — rank: any-builder — POST /provisioning/instances/:id/repo-private
       postProvisioningInstancesIdRepoPrivate: (args) => request("POST", "/provisioning/instances/{id}/repo-private", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/restart — rank: any-builder — POST /provisioning/instances/:id/restart

package/clients/bongos-client/index.cjs

@@ -796,6 +796,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder — GET /provisioning/instances/:id/invite-suggestions
       getProvisioningInstancesIdInviteSuggestions: (args) => request("GET", "/provisioning/instances/{id}/invite-suggestions", { hasBody: false }, args),
+      // POST /provisioning/instances/{id}/render — rank: any-builder — POST /provisioning/instances/:id/render
+      postProvisioningInstancesIdRender: (args) => request("POST", "/provisioning/instances/{id}/render", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/repo-private — rank: any-builder — POST /provisioning/instances/:id/repo-private
       postProvisioningInstancesIdRepoPrivate: (args) => request("POST", "/provisioning/instances/{id}/repo-private", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/restart — rank: any-builder — POST /provisioning/instances/:id/restart

package/clients/bongos-client/index.d.ts

@@ -389,6 +389,8 @@ export interface PostProvisioningInstancesIdEnvManifestRequest { name: string; d
 export interface PostProvisioningInstancesIdForceTeardownResponse { ok: boolean; queued: unknown; action: unknown; status: unknown; superseded: unknown; message: unknown }
 export interface PostProvisioningInstancesIdGithubAppRequest { account?: string }
 export interface PostProvisioningInstancesIdGithubAppResponse { state: unknown; account: unknown; post_url: unknown; personal_url: unknown; org_url: unknown; org_login: unknown; manifest: unknown; redirect_url: unknown; expires_at: unknown }
+export interface PostProvisioningInstancesIdRenderRequest { key: string; owner_id: string; mode: string; service_id?: string; web_plan?: string; db_plan?: string; region?: string }
+export interface PostProvisioningInstancesIdRenderResponse { ok: boolean; queued: boolean; action: unknown; mode: unknown; message: unknown }
 export interface PostProvisioningInstancesIdRepoPrivateResponse { ok: boolean; queued: unknown; action: unknown; status: unknown; message: unknown }
 export interface PostProvisioningInstancesIdRestartResponse { ok: boolean; queued: unknown; action: unknown; status: unknown; message: unknown }
 export interface PostProvisioningInstancesIdTeardownResponse { ok: boolean; queued: unknown; action: unknown; status: unknown; superseded: unknown; message: unknown }
@@ -1201,6 +1203,8 @@ export interface BongosClient {
     postProvisioningInstancesIdGithubApp(args?: RequestArgs & { body?: PostProvisioningInstancesIdGithubAppRequest }): Promise<PostProvisioningInstancesIdGithubAppResponse>;
     /** GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder */
     getProvisioningInstancesIdInviteSuggestions(args?: RequestArgs): Promise<GetProvisioningInstancesIdInviteSuggestionsResponse>;
+    /** POST /provisioning/instances/{id}/render — rank: any-builder */
+    postProvisioningInstancesIdRender(args: RequestArgs & { body: PostProvisioningInstancesIdRenderRequest }): Promise<PostProvisioningInstancesIdRenderResponse>;
     /** POST /provisioning/instances/{id}/repo-private — rank: any-builder */
     postProvisioningInstancesIdRepoPrivate(args?: RequestArgs): Promise<PostProvisioningInstancesIdRepoPrivateResponse>;
     /** POST /provisioning/instances/{id}/restart — rank: any-builder */

package/clients/bongos-client/index.mjs

@@ -793,6 +793,8 @@ export function createClient(opts = {}) {
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder — GET /provisioning/instances/:id/invite-suggestions
       getProvisioningInstancesIdInviteSuggestions: (args) => request("GET", "/provisioning/instances/{id}/invite-suggestions", { hasBody: false }, args),
+      // POST /provisioning/instances/{id}/render — rank: any-builder — POST /provisioning/instances/:id/render
+      postProvisioningInstancesIdRender: (args) => request("POST", "/provisioning/instances/{id}/render", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/repo-private — rank: any-builder — POST /provisioning/instances/:id/repo-private
       postProvisioningInstancesIdRepoPrivate: (args) => request("POST", "/provisioning/instances/{id}/repo-private", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/restart — rank: any-builder — POST /provisioning/instances/:id/restart

package/docs/adr/0343-a-module-score-is-a-security-gate-then-an-average-of-visible-parts.md

@@ -30,6 +30,8 @@ explainable in a sentence.
 Each part is scored 0–100 per module **version**, because a new version can be better or worse
 than the last.
 
+> **Amended by [ADR 0347](0347-every-store-module-ships-a-how-to.md):** adds a **Docs** part (the how-to, scored day one), shown with the parts but not in the D3 average.
+
 ### D2 — Security is a gate, not an ingredient
 
 A version that **fails the security check is not listed**, whatever else it scores. Security is

package/docs/adr/0347-every-store-module-ships-a-how-to.md

@@ -0,0 +1,135 @@
+# ADR 0347 — Every store module ships a how-to: a file in the module, a publish gate, and a Docs score shown on its own
+
+- **Status:** accepted
+- **Date:** 2026-09-29
+- **Task:** [task 1004364](https://cloudbongos.com/builders#/task/1004364) (goal 1000091 — working area 5, Module distribution & economy)
+- **Deciders:** Will (owner of working area 5) decided the how-to is a file, the "gate plus score" grader, that the Docs score is shown separately rather than averaged in, and the grader's model and cost ceiling; Claude wrote the record.
+- **Related:** [ADR 0343](0343-a-module-score-is-a-security-gate-then-an-average-of-visible-parts.md) (the score; D1's parts table is amended here) · [ADR 0338](0338-modules-travel-through-a-bongos-hosted-store.md) (the store, the tarball and its hashes) · [ADR 0098](0098-public-mirror-publish-manifest.md) (`isPublishable()`) · [`docs/modules-contract.md`](../modules-contract.md) §6 (publish) and §7 (install) · follow-on tasks 1004365 (the file and the publish check), 1004366 (the store page and PDF), 1004367 (the AI grader)
+
+## Context
+
+A buyer browsing the store (ADR 0338) sees a module's name, category and score (ADR 0343),
+but nothing tells them how to use what they are getting. Today a module carries a
+`CLAUDE.md` written for AI sessions working *inside* the module, not for the person who
+installs it. There is no rule that an author explains their module at all.
+
+The owner wants every store module to come with a how-to that works for a person or for any
+AI, that the buyer can read before acquiring, and that is judged so good explanations are
+visible.
+
+## Decision
+
+### D1 — The how-to is a file: `HOWTO.md` at the module root (owner)
+
+The how-to is `modules/<key>/HOWTO.md`, plain Markdown. It is a **file in the module**, not a
+hosted page, because:
+
+- it travels inside the tarball, so it is covered by the manifest hashes and **cannot change
+  after a version is published** — the how-to a buyer read is the one they get;
+- any AI or person can read and write Markdown, so the module does not depend on one vendor;
+- it goes wherever the module goes, including instances that are offline.
+
+The packaging allowlist (`isPublishable()`, ADR 0098) must include `HOWTO.md`; task 1004365
+checks it is in the tarball.
+
+### D2 — Five required sections, kept short
+
+`HOWTO.md` must contain these five level-2 headings, matched case-insensitively and in any
+order, each with some text under it:
+
+| Heading | What goes in it |
+|---|---|
+| `## What it does` | A few sentences: what the 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 defaults. "None." is a valid answer. |
+| `## Limits and known issues` | What it doesn't do, and anything known to go wrong. "None known." is a valid answer. |
+
+Other headings and sections are welcome. The list is short on purpose, so an author can meet
+it in minutes; quality above that bar is what the Docs score (D5) rewards.
+
+### D3 — An optional Claude artifact link, shown as an extra and never graded (owner)
+
+An author may set `howto.artifactUrl` in `module.json` to a Claude artifact (an `https://`
+link on `claude.ai`). The store page shows it as **"Also available as a Claude page"**, next
+to the file, never instead of it.
+
+It is **never graded and never required**, because a hosted page can change after publish;
+only the file is frozen with the version. The store validates the field's shape only.
+
+### D4 — The gate: no how-to, no publish
+
+`bongos module publish` **refuses** a version when `HOWTO.md` is missing, or when any required
+section (D2) is missing or empty. The refusal names the file or each failing section, e.g.
+`HOWTO.md: section "Configuration" is empty`.
+
+- It is a free, deterministic check: it reads headings, it does not judge writing.
+- The CLI runs it before uploading, and the store runs it again on upload (as it already
+  re-checks hashes and the denylist, `modules-contract.md` §6), so a hand-built upload can't
+  skip it.
+- It applies **only to store versions**. Core-bundled modules and `bongos module submit`
+  (proposing a module into core, ADR 0135) are not gated by it.
+- Versions published before the gate existed are not delisted or re-checked; the gate applies
+  from the next version.
+
+### D5 — The Docs part: scored, visible, and **not** in the overall score (owner)
+
+This amends ADR 0343 D1's parts table with one row:
+
+| Part | What it measures | Available |
+|---|---|---|
+| **Docs** | clarity and completeness of the version's `HOWTO.md`, scored by an AI grader (task 1004367) | day one |
+
+- **Scored 0–100 per version**, like every other part, because each version ships its own
+  how-to.
+- **Shown separately, not averaged in (owner).** Docs is displayed with the other parts
+  (ADR 0343 D4), labelled as not counting toward the overall score. It does **not** join the
+  plain average in ADR 0343 D3, and so does not move the floor, ranking or cap
+  (tasks 1003807–1003809). The overall score stays a measure of how the module *works*; Docs
+  tells the buyer how well it is *explained*. A superseding ADR can fold it in later if the
+  owner wants.
+- **The grader gives a short reason** with the number (a sentence on what is clear and what is
+  missing, such as "no worked example"), so an author knows what to fix.
+- **"No score yet" is never a zero** (ADR 0343 D5). While grading is under way the part shows
+  **"Docs: pending"**; if grading could not run, **"Docs: not scored"**. A version is listed
+  as soon as it passes the gate; it never waits for the grader.
+- **Price is never an input** (ADR 0343 D6). Free and paid modules are graded by the same
+  call, and the Metic+ override applies to Docs like any part, with an audit entry.
+
+### D6 — Cost: one Sonnet 5 call per version, capped at 5¢ (owner)
+
+- **One grader call per published version**, made by the store after the version is accepted.
+  A failed call is retried once; if both fail, the part stays "not scored" until Metic+
+  re-runs it. Nothing re-grades a version automatically after that.
+- **Model: Claude Sonnet 5** (`claude-sonnet-5`), the rung the task grader already uses
+  (`modules/grading/grader-rubric.json`). Changing the rung needs the area owner's nod.
+- **Ceiling: 5¢ per call** at list price (Sonnet 5 is $2 in / $10 out per million tokens,
+  `src/bongos/llm-pricing.js`). The grader caps its output and its input to fit: a how-to too
+  long to read in full is cut to fit, and the reason says the score covers only the part read.
+  A typical how-to costs about 1–2¢.
+- The platform pays, and each call is recorded in the cost log like any other API spend
+  (CLAUDE.md §4). At 5¢ a version, a thousand published versions is $50.
+
+## Consequences
+
+- **Task 1004365** adds the scaffolded `HOWTO.md` (with the five headings) to
+  `bongos module new`, the section check in `bongos module publish`, the same check on the
+  store's upload route, and `HOWTO.md` in the packaging allowlist.
+- **Task 1004366** renders the file as the module's store page, with a PDF download of the
+  same content, and shows the D3 link when present.
+- **Task 1004367** builds the grader to D5 and D6, and stores its score and reason as the
+  Docs part.
+- **Authors of existing store modules** must add a `HOWTO.md` before their next version.
+- **The overall score and ranking are unchanged** by this ADR (D5).
+
+## Rejected
+
+- **A hosted Claude artifact as the how-to.** It can change after publish, isn't covered by
+  the hashes, and ties the module to one vendor. Kept only as the optional extra (D3).
+- **Gate only, no score.** It proves the sections exist, not that they are any good.
+- **AI grader only, no gate.** It costs money for modules with no how-to at all, and an
+  outage would leave nothing enforcing the basics.
+- **Docs in the plain average.** Considered; the owner chose to keep the overall score about
+  how the module works and show Docs beside it.
+- **Grading core-bundled modules.** They reach instances through the core, not the store; the
+  store page is where the how-to is read.

package/docs/adr/README.md

@@ -438,3 +438,4 @@ This keeps the decision history honest and traceable.
 | 0344 | [**A tester is a project that opts in once; an untested version reaches everyone after seven days** ([task 1003801](https://cloudbongos.com/builders#/task/1003801), goal 1000091 — working area 5, owner Will). Settles "willing user" for criterion `wa5-staged-rollout`. **D1 (owner):** a project's own admin switches on "tester" once and gets tester versions of every module it has, with a per-module "general only" override; never on by default; a builder cannot opt in someone else's project. **D2:** first releases and updates alike go to testers first. **D3 (owner):** a version moves to general after seven days if it still passes the security gate and tests, tested or not; the promotion gate may promote earlier or hold on evidence, never forever. **D4:** testers pay the normal price; any tester discount is area 8's call, named not decided. **D5:** tester installs, errors and crashes feed the score (ADR 0343). Rejected: per-module-only opt-in, one all-or-nothing switch, waiting for a tester, releasing at once.](0344-a-tester-is-a-project-that-opts-in-once.md) | modules / store / rollout |
 | 0345 | [**We host every project's hall, and its app deploys where the owner chooses** ([task 1004349](https://cloudbongos.com/builders#/task/1004349), goal 1000106 — working area 1, owner Lars). Reverses ADR 0323 §2 and the hall half of ADR 0327. **D1 (owner):** every project's Builders Hall runs on our shared server; `cloud-host` now means "hosted by us". **D2 (owner):** the hall's address is ours or the owner's own domain. **D3 (owner):** the setup wizard asks where the APP deploys; Render only at launch; choosing it creates the app on the owner's own Render account with ADR 0327's borrowed key. **D4 (owner):** "decide later" is allowed. **D5 (owner):** no project is moved. **D6 (measured):** ADR 0145 Finding 1 is live — the hub cookie is `Domain=.cloudbongos.com` and a hall loads modules from its own repo — so our-address halls need task 1004357; an owner domain is safe. **D7 (measured):** at the ceiling the create route refuses `box_full` up front, and the resize is not a prerequisite. Task 1004184 re-scoped, task 1004185 on hold.](0345-we-host-every-projects-hall-and-its-app-deploys-where-the-owner-chooses.md) | hosting / provisioning / security |
 | 0346 | [**Dev boxes are retired; a builder builds from their own checkout** ([task 1003898](https://cloudbongos.com/builders#/task/1003898), goal 1000120 — owner Lars). Records the whole removal, link by link, the owner's three rulings of 2026-09-13 (drop the data, delete `.devcontainer/`, remove `bongos box`/`shell`/`code`), what was kept on purpose (server-mediated publish, the CLI downloads, `secret-box`, `do-api`, the declared-source rule), and the retirement guards that still name the box. Supersedes 0031, 0044, 0045, 0053, 0057, 0059, 0071, 0072 (code staleness), 0123, 0144, 0145 (desktop-app branding), 0148, 0193, 0277; supersedes in part 0035, 0046, 0052, 0055, 0072 (Bongos app), 0151 §3.](0346-dev-boxes-are-retired.md) | builder environment / removal |
+| 0347 | [**Every store module ships a how-to: a file in the module, a publish gate, and a Docs score shown on its own** ([task 1004364](https://cloudbongos.com/builders#/task/1004364), goal 1000091 — working area 5, owner Will). Amends ADR 0343 D1. **D1-D2 (owner):** the how-to is `HOWTO.md` at the module root, frozen with the version by the tarball hashes, with five required sections (what it does; install and enable; how to use it, with one worked example; configuration; limits and known issues). **D3:** an optional `howto.artifactUrl` Claude artifact shown as "also available as", never graded. **D4:** `bongos module publish` and the store refuse a version with a missing file or empty section, naming it; store versions only. **D5 (owner):** a Docs part scored 0–100 per version, day one, shown beside the parts but NOT in the D3 average, floor or ranking; "pending"/"not scored" never zero; price never an input. **D6 (owner):** one Sonnet 5 call per version, 5¢ ceiling.](0347-every-store-module-ships-a-how-to.md) | modules / store / quality |