@bongos/core 1.21.151 → 1.21.153

package/docs/module-api-changelog.md

@@ -3139,5 +3139,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.149 with no explicit bump. run 39331860470. (task 1002620)
   1.21.151 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.150 with no explicit bump. run 39667670641. (task 1002620)
+  1.21.152 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.151 with no explicit bump. run 39671625798. (task 1002620)
+  1.21.153 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.152 with no explicit bump. run 39675693737. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -83,6 +83,8 @@ Every module must have a `module.json` at its root (`modules/<key>/module.json`)
                                       //   what update, rollout channels and re-assessment name (task 1003781).
   "coreVersion": "^1.4.0",           // REQUIRED. semver range of CORE_VERSION this module supports.
   "default":     false,               // OPTIONAL (default false). Fail-safe when no config names it.
+  "category":    { "parent": "communication", "sub": "team-chat" }, // OPTIONAL. Where it is browsed (ADR 0342):
+                                      //   parent is one of the eight; sub is an approved sub-category, absent while pending.
   "author":      "…",                 // OPTIONAL. Attribution (ADR 0107 §2) — portable, not a cross-Bongos FK.
   "origin":      "…",                 // OPTIONAL. Origin instance/project this module was built in.
   "license":     "AGPL-3.0",          // OPTIONAL. License this module is offered under.
@@ -120,6 +122,33 @@ Every module must have a `module.json` at its root (`modules/<key>/module.json`)
 
 An unknown key throws at validate time — typos fail loud (top-level attribution fields have no closed allowlist; only `contributes` sub-keys do).
 
+### `category` — where a module is browsed and compared ([ADR 0342](adr/0342-module-categories-are-eight-parents-with-approved-sub-categories.md))
+
+`"category": { "parent": "<key>", "sub": "<key>" }`. `parent` is one of eight fixed keys, and any
+other value fails validation:
+
+| `parent` | Shown as |
+|---|---|
+| `work` | Work & planning |
+| `people` | Team & people |
+| `quality` | Quality & review |
+| `money` | Money |
+| `communication` | Communication |
+| `pages` | Pages & design |
+| `hosting` | Hosting & deploy |
+| `knowledge` | Knowledge |
+
+`sub` is the module's one sub-category: the narrow set of modules it actually competes with, which
+is where the store's ranking and its cap of ten apply. It must be a kebab-case key. Leave it out
+while a new sub-category waits for a Metic+ approval; the module is then listed under its parent
+only. The schema checks the sub-category's shape, not whether it has been approved. The block has
+just these two keys, so a second sub-category is an error.
+
+Every bundled module declares a parent (pinned by `tests/module_manifest.mjs`), and none declares a
+sub-category yet. `GET /modules`, `bongos module list` (the CATEGORY column) and the hall Modules tab
+all read the row's `category` (`{ parent, parentTitle, sub }`, or `null`) from
+`src/module-loader/catalog.js`, and the search on both surfaces matches it.
+
 ### `spend` — "my surfaces spend real money for whoever calls them" ([ADR 0282](adr/0282-a-module-that-spends-for-its-callers-declares-a-payer-and-the-core-refuses-it-without-one.md))
 
 Declare `"spend": { "requiresPayer": true }` when a route of yours can spend money on behalf of the
@@ -363,6 +392,7 @@ Run `bongos upgrade` to confirm coreVersion compatibility, then `node scripts/gd
 - 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.
 - **Getting listed** (task 1003807, [ADR 0343](adr/0343-a-module-score-is-a-security-gate-then-an-average-of-visible-parts.md)). Publishing a version does not by itself put it in the store's catalog, `GET /store/modules`. The catalog shows each module's newest version, judged by its current score. It must pass the Security gate first; a version that failed it, or has not been checked yet, is not listed. A new version with no install or reliability data yet is listed with a **New** label and is not ranked; the floor does not apply to it until it has a real score. Every other version is listed only if its overall score is **at least 50 out of 100**. Below that it is not listed at all. The floor is fixed in Bongos itself (`QUALITY_FLOOR` in `src/bongos/module-listing.js`) and returned in the catalog response; no author or instance setting moves it, and changing it is an owner-approved, reviewed task.
+- **What a module is strong and weak at** (task 1003799, ADR 0343 D4). Each catalog entry also carries `parts` (the current result of Tests, Clean installs, Reliability, Tester feedback and How-to) and a reading of them: `strengths` (a part scored **80 or more**), `weaknesses` (a part scored **below the floor**) and `unmeasured` (a part with no score yet, which is never counted as weak). Each strength and weakness has a one-sentence `detail` saying what the number rests on. Security is not among them: every listed version has passed it. The reading is `readParts` in `src/bongos/module-listing.js`; the hall's Modules tab shows it in its "In the store" group, so two modules with the same overall score can be told apart.
 
 ### 7. Install from the store