@bongos/core 1.25.11 → 1.25.13

package/docs/api/openapi.json

@@ -141,6 +141,10 @@
       "name": "founding",
       "description": "Endpoints under `/api/bongos/founding`."
     },
+    {
+      "name": "front-door-guide",
+      "description": "Endpoints under `/api/bongos/front-door-guide`."
+    },
     {
       "name": "github",
       "description": "Endpoints under `/api/bongos/github`."
@@ -7889,6 +7893,287 @@
         ]
       }
     },
+    "/front-door-guide/conversations": {
+      "post": {
+        "operationId": "post_front_door_guide_conversations",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "POST /front-door-guide/conversations",
+        "description": "start a chat. Answers the greeting and the conversation's token.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/front-door-guide/routes/front-door-guide.js",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostFrontDoorGuideConversationsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
+    "/front-door-guide/conversations/{id}": {
+      "get": {
+        "operationId": "get_front_door_guide_conversations_id",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "GET /front-door-guide/conversations/:id",
+        "description": "the transcript, for the plan and the sign-up hand-off.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/front-door-guide/routes/front-door-guide.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": []
+      }
+    },
+    "/front-door-guide/conversations/{id}/attach": {
+      "post": {
+        "operationId": "post_front_door_guide_conversations_id_attach",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "POST /front-door-guide/conversations/:id/attach",
+        "description": "the visitor has just signed in; the chat moves onto their account.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/front-door-guide/routes/front-door-guide-plan.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostFrontDoorGuideConversationsIdAttachRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostFrontDoorGuideConversationsIdAttachResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/front-door-guide/conversations/{id}/messages": {
+      "post": {
+        "operationId": "post_front_door_guide_conversations_id_messages",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "POST /front-door-guide/conversations/:id/messages",
+        "description": "one visitor message, one guide reply.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/front-door-guide/routes/front-door-guide.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostFrontDoorGuideConversationsIdMessagesRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": []
+      }
+    },
+    "/front-door-guide/conversations/{id}/plan": {
+      "post": {
+        "operationId": "post_front_door_guide_conversations_id_plan",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "POST /front-door-guide/conversations/:id/plan",
+        "description": "the visitor has no account yet.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/front-door-guide/routes/front-door-guide-plan.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostFrontDoorGuideConversationsIdPlanRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": []
+      }
+    },
+    "/front-door-guide/mine": {
+      "get": {
+        "operationId": "get_front_door_guide_mine",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "GET /front-door-guide/mine",
+        "description": "my newest chat and plan (the creation wizard's pre-fill reads it).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/front-door-guide/routes/front-door-guide-plan.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetFrontDoorGuideMineResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/front-door-guide/status": {
+      "get": {
+        "operationId": "get_front_door_guide_status",
+        "tags": [
+          "front-door-guide"
+        ],
+        "summary": "GET /front-door-guide/status",
+        "description": "the landing asks before it offers the chat.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/front-door-guide/routes/front-door-guide.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/github/orgs": {
       "get": {
         "operationId": "get_github_orgs",
@@ -33576,6 +33861,19 @@
           "count"
         ]
       },
+      "GetFrontDoorGuideMineResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "conversation": {}
+        },
+        "required": [
+          "ok",
+          "conversation"
+        ]
+      },
       "GetGithubOrgsOrgResponse": {
         "type": "object",
         "properties": {
@@ -38086,6 +38384,81 @@
         },
         "additionalProperties": false
       },
+      "PostFrontDoorGuideConversationsIdAttachRequest": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "maxLength": 64
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "additionalProperties": false
+      },
+      "PostFrontDoorGuideConversationsIdAttachResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "conversation": {}
+        },
+        "required": [
+          "ok",
+          "conversation"
+        ]
+      },
+      "PostFrontDoorGuideConversationsIdMessagesRequest": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "text": {
+            "type": "string",
+            "maxLength": 100000
+          },
+          "website": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "token",
+          "text"
+        ],
+        "additionalProperties": false
+      },
+      "PostFrontDoorGuideConversationsIdPlanRequest": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "website": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "additionalProperties": false
+      },
+      "PostFrontDoorGuideConversationsRequest": {
+        "type": "object",
+        "properties": {
+          "website": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        "additionalProperties": false
+      },
       "PostGithubRepoInviteRequest": {
         "type": "object",
         "properties": {
@@ -43973,9 +44346,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 702,
-  "x-schema-count": 739,
+  "x-endpoint-count": 709,
+  "x-schema-count": 745,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 466,
+  "x-response-schemas": 468,
   "x-generated-by": "scripts/bongos/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 702 endpoints across 118 route files.
+> **Generated from the live route files** — the route file is authoritative. 709 endpoints across 120 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -328,6 +328,18 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/founding/stages/:stage/close` | `any-builder` | — | task 1005121: one call. |
 | POST | `/api/bongos/founding/start` | `any-builder` | — |  |
 
+## `front-door-guide` (7)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/front-door-guide/conversations` | `public` | `website` | start a chat. |
+| GET | `/api/bongos/front-door-guide/conversations/:id` | `public` | — | the transcript, for the plan and the sign-up hand-off. |
+| POST | `/api/bongos/front-door-guide/conversations/:id/attach` | `any-builder` | `token` | the visitor has just signed in; the chat moves onto their account. |
+| POST | `/api/bongos/front-door-guide/conversations/:id/messages` | `public` | `token`, `text`, `website` | one visitor message, one guide reply. |
+| POST | `/api/bongos/front-door-guide/conversations/:id/plan` | `public` | `token`, `website` | the visitor has no account yet. |
+| GET | `/api/bongos/front-door-guide/mine` | `any-builder` | — | my newest chat and plan (the creation wizard's pre-fill reads it). |
+| GET | `/api/bongos/front-door-guide/status` | `public` | — | the landing asks before it offers the chat. |
+
 ## `github` (8)
 
 | Method | Path | Rank | Body | Description |

package/docs/file-map.md

@@ -116,6 +116,7 @@
 │   ├── copy-desk/               ← CORE-DOMAIN module (task 1003113 / R02 of goal 1000074, default-on): the COPY half of the design contract — ADR 0081 gave design TOKENS a repo-owned source of truth, text had none. Owns the FLAG (anyone in any role marks a string or a whole surface as needing an artist's attention, with a reason required in BOTH the route and a CHECK constraint) and the QUEUE an artist reads it from. READS R01's committed registry (docs/copy-registry.json, generated by scripts/bongos/copy-inventory.js) and never writes it. NO LIVE CMS is the hard non-goal: no column here could hold replacement text, and copy_no_cms.mjs pins that. Key is `copy-desk`, not `copy` — the branding contract already owns a `copy` block, so the bare word reds the "core carries no module code" fitness check. R03 (task 1003114, ADR 0233) added the PROPOSAL: an artist writes the replacement wording and it becomes a Bongos task carrying a fenced copy-proposal patch — no row, NO second migration (a proposals table is the forbidden column with extra steps), and scripts/bongos/copy-apply.js lands it as a real diff under a claim. BV2.TW05 (task 1004316, ADR 0341 D8) added Tweak Mode's three derived READS — GET /copy-desk/pages, /copy-desk/pages/:pageId, /copy-desk/tally: page status and count, changelog, drift, "N of M tweaked" per surface, and the artist's tally — over the page-tweak tasks (lifecycle port), docs/page-inventory.json and docs/page-readings.json (both now in the publish manifest), with no status table. BV2.TW06 (task 1004317, ADR 0341 D2, D5, D6) added its first two page WRITES: POST /copy-desk/pages/:pageId/claim (an artist-craft builder opens or takes the page's tweak round as a web-claimed task, through the lifecycle port's webClaimPageTweak, under an advisory lock on the page) and POST /copy-desk/pages/:pageId/asks (anyone files a page ask, a copy_desk_flags row with scope 'page', added by copy_desk_002_page_asks.sql). CLAUDE.md, module.json, registry.js, flags.js, proposals.js, pages.js (the page-tweak block format), page-status.js (the pure derivation), page-data.js (the page artifacts' read side), routes/copy-desk.js, migrations/copy_desk_001_flags.sql, migrations/copy_desk_002_page_asks.sql, tests/{copy_flags,copy_queue,copy_no_cms,copy_proposals,copy_page_status}.mjs + tests/fixtures/page-tweak.cjs. Its hall surface lives with hall-ui (public/copy-desk.{html,js,css}), per the one-key-per-web-surface precedent. skills/tweak/SKILL.md is the /tweak skill (contributes.skills; moved out of .claude/skills/ in task 1004471, hidden from the model listing, typed as /tweak).
 │   ├── page-notes/              ← the artist's page feedback docs (task 1004496, default-on): the Artistry palette button's store. A doc about one hall page, with up to eight reference images (stored in the DB, images only), turned into ideas by an AI split on submit and kept as the page's reference (?note=N). Apart from copy-desk, which may hold no wording. module.json, CLAUDE.md, notes.js (pure), split.js, db.js, routes/, migrations/.
 │   ├── ai-studio/               ← AI generation for artists (task 1004916, ADR 0392, default-off; hub first): a sketch or image set plus a prompt gets a Gemini reply and generated images on our key (processor-held balance, one named price multiplier, funds held first, released on failure) or the builder's own key (no charge). Keys entered only in Settings, never leave the server. module.json, CLAUDE.md, routes/.
+│   ├── front-door-guide/        ← the start-a-project guide (task 1005272, goal 1000106, default-off; hub first): a signed-out visitor talks with an AI guide for a few capped messages before signing up, on the platform's own Anthropic key from the environment. Every cap on the server (messages and spend per visitor, daily and monthly site budget, message length, rate limits, bot check); a spent budget or no key answers the plain form. The chat ends in a structured plan naming only modules the creation picker offers (the provisioning.moduleCatalog port), saved, attached to the account at sign-up, and swept after a set number of days if nobody signs up (task 1005273). module.json, CLAUDE.md (the response shape), settings.js, guide.js, plan.js, context.js, claude.js, limits.js, db.js, routes/, pollers/retention-sweep.js, migrations/.
 │   ├── market-watch/            ← Market Watch (task 1004935, goal 1000137, default-off): a weekly AI watch on a project's competitors, partners and topics. No routes yet; the manifest declares spend.requiresPayer. Kept out of the creation picker (HUB_ONLY_MODULES) until it does something. Data layer (task 1004936): migrations/ (market_watch_* tables), db.js (read queries), seed.js + seed/ (the 2026-10-28 research, hub only), pollers/hub-seed.js. module.json, CLAUDE.md.
 │   ├── raise/                   ← the /raise investor page (task 1004847, ADR 0384, default-off; hub only): password-gated for investors (signing in accepts the NDA, non-binding interest), edited in place by any active builder with every change logged. The copy in content/ is the owner's words — never reword it in code. module.json, CLAUDE.md, raise.js (pure), page.js, web.js (the GET-only raise.web port core mounts at /raise), db.js, routes/ (every write), migrations/, content/, views/, public/.
 │   ├── npm-release/             ← the deploy page for a project that publishes an npm package from GitHub (task 1002622, default-OFF — on only in the Bongos hall, which publishes @bongos/core). "Where the work is": every task finished in the last 14 days, placed in the stage it has actually reached (not merged · merged, no version yet · published, not running here · running here, not released · released · in no version), plus the version history — each version's tasks. The version↔task join reads the release-notes.json the package itself carries (scripts/bongos/release-notes.js writes it at pack time), streamed out of the NEWEST version's npm tarball in-process (no child process, no sync call) when the running core's own copy stops short. module.json, work.js (the reading + the stage placement — the packument, tarball stream and tar reader it uses are the core's src/bongos/package-registry.js, reached through the doorway's readPackageRegistry since task 1004296), routes/work.js (GET /npm-release/work, gated core.pin.move like the page), public/work.{js,css} (the two sections /deploy lends it: #nr-work, #nr-versions). Task 1004301 added the same line on a task's own page: routes/task-where.js (GET /npm-release/task/:id, any signed-in builder — it shows nothing not already public) + public/task-widget.js, injected into task.html by the loader's uiSections seam (hallWidgetScripts file task-widget.js) to fill #task-contrib on otb:task-shown. Tests sit at the repo root — tests/npm_release_{work,page}.mjs — because a default-off module's own tests/ is skipped by the unit runner.

package/docs/module-api-changelog.md

@@ -3462,5 +3462,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.25.9 with no explicit bump. run 43417745698. (task 1002620)
   1.25.11 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.25.10 with no explicit bump. run 43440873455. (task 1002620)
+  1.25.12 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.25.11 with no explicit bump. run 43489275620. (task 1002620)
+  1.25.13 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.25.12 with no explicit bump. run 43493844051. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/front-door-guide/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/front-door-guide/claude.js

@@ -0,0 +1,55 @@
+// modules/front-door-guide/claude.js — the one Claude Messages API call behind the
+// start-a-project guide (task 1005272), on the platform's own key.
+//
+// The SDK is required lazily, so an instance with the guide off never loads it, and the
+// client is injectable so the tests run a mocked one and never spend real money.
+// Thinking cannot be switched off on the default model; `effort` keeps a chat reply
+// short and cheap, and `max_tokens` bounds the bill of one reply (thinking included).
+
+'use strict';
+
+const CALL_TIMEOUT_MS = 30_000;
+
+// createClient(apiKey, { sdk }) — the live client. The key goes only to the SDK.
+function createClient(apiKey, { sdk = null } = {}) {
+  const mod = sdk || require('@anthropic-ai/sdk');
+  const Anthropic = mod.Anthropic || mod.default || mod;
+  return new Anthropic({ apiKey, timeout: CALL_TIMEOUT_MS, maxRetries: 1 });
+}
+
+// buildRequest — the request body, kept separate so a test can read it. With `schema`
+// it is the plan call: structured output (a JSON schema the reply must match) and the
+// plan's own token ceiling.
+function buildRequest({ settings, system, messages, schema = null }) {
+  const outputConfig = { effort: settings.effort };
+  if (schema) outputConfig.format = { type: 'json_schema', schema };
+  return {
+    model: settings.model,
+    max_tokens: schema ? settings.maxPlanTokens : settings.maxReplyTokens,
+    output_config: outputConfig,
+    system,
+    messages: messages.map((m) => ({ role: m.role, content: m.content })),
+  };
+}
+
+// askGuide({ client, settings, system, messages, schema? }) →
+//   { ok: true, stopReason, content, usage, model }
+//   { ok: false, error }   a thrown SDK error (network, 4xx, 5xx); nothing was billed.
+// Never throws.
+async function askGuide({ client, settings, system, messages, schema = null }) {
+  let res;
+  try {
+    res = await client.messages.create(buildRequest({ settings, system, messages, schema }));
+  } catch (e) {
+    return { ok: false, error: `api_error${e && e.status ? ` ${e.status}` : ''}` };
+  }
+  return {
+    ok: true,
+    stopReason: res && res.stop_reason,
+    content: (res && res.content) || [],
+    usage: (res && res.usage) || {},
+    model: (res && res.model) || settings.model,
+  };
+}
+
+module.exports = { createClient, buildRequest, askGuide, CALL_TIMEOUT_MS };

package/modules/front-door-guide/context.js

@@ -0,0 +1,54 @@
+// modules/front-door-guide/context.js — what both of the guide's routes files share (task
+// 1005273): the visitor-hash salt, the product name, the module catalog, the site budget
+// check, and ONE set of in-flight spend reservations. One set, because a chat reply and a
+// plan from the same visitor, or from the whole site, must count against the same money.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const db = require('./db');
+const L = require('./limits');
+
+const reservations = L.makeReservations();
+
+function salt() {
+  let s;
+  try { s = api.resolveEnv('FRONT_DOOR_GUIDE_SALT'); } catch (_) { s = null; }
+  if (s) return s;
+  let name = 'bongos';
+  try { name = api.instanceDbName() || name; } catch (_) { /* the default salt still separates visitors */ }
+  return `front-door-guide:${name}`;
+}
+
+function productName() {
+  try { return api.branding().identity.productName || 'Cloud Bongos'; } catch (_) { return 'Cloud Bongos'; }
+}
+
+// The modules a new project can opt into, from the provisioning module's port (the
+// project-creation picker's own list). No provider (provisioning off) → an empty
+// catalog, and the plan recommends nothing rather than guessing.
+async function moduleCatalog() {
+  const provider = api.resolveOptional('provisioning.moduleCatalog');
+  if (typeof provider !== 'function') return { core: [], optional: [] };
+  try {
+    const c = (await provider()) || {};
+    const optional = (Array.isArray(c.optional) ? c.optional : [])
+      .filter((m) => m && typeof m.key === 'string' && m.key)
+      .map((m) => ({ key: m.key, label: String(m.label || m.key), summary: String(m.summary || '') }));
+    return { core: Array.isArray(c.core) ? c.core.filter((k) => typeof k === 'string') : [], optional };
+  } catch (_) {
+    return { core: [], optional: [] };
+  }
+}
+
+// Can the site afford a call of `extraMicro` right now? → null, or the form reason.
+async function siteBudgetReason(settings, extraMicro) {
+  const pending = reservations.siteMicro();
+  // Spent is spent (>=), and a call must also fit in what is left (>).
+  const over = (spent, cap) => spent + pending >= cap || spent + pending + extraMicro > cap;
+  if (over(await db.siteSpendMicro('day'), settings.dailyBudgetMicro)) return 'daily_budget';
+  if (over(await db.siteSpendMicro('month'), settings.monthlyBudgetMicro)) return 'monthly_budget';
+  return null;
+}
+
+module.exports = { reservations, salt, productName, moduleCatalog, siteBudgetReason };