@bongos/core 1.24.2 → 1.24.4

package/docs/api/openapi.json

@@ -197,6 +197,10 @@
       "name": "llm-cache",
       "description": "Endpoints under `/api/bongos/llm-cache`."
     },
+    {
+      "name": "market-watch",
+      "description": "Endpoints under `/api/bongos/market-watch`."
+    },
     {
       "name": "me",
       "description": "Endpoints under `/api/bongos/me`."
@@ -13952,6 +13956,86 @@
         ]
       }
     },
+    "/market-watch/ask": {
+      "get": {
+        "operationId": "get_market_watch_ask",
+        "tags": [
+          "market-watch"
+        ],
+        "summary": "GET /market-watch/ask",
+        "description": "every member reads their own card; nobody else's (isMember in gate()).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/market-watch/routes/ask.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetMarketWatchAskResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/market-watch/ask/answer": {
+      "post": {
+        "operationId": "post_market_watch_ask_answer",
+        "tags": [
+          "market-watch"
+        ],
+        "summary": "POST /market-watch/ask/answer",
+        "description": "a member answers for themselves only (isMember in gate()).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/market-watch/routes/ask.js",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostMarketWatchAskAnswerRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/me": {
       "get": {
         "operationId": "get_me",
@@ -19493,7 +19577,7 @@
           "project-settings"
         ],
         "summary": "GET /project-settings",
-        "description": "GET /project-settings — all five rows in ONE read. rank: project.settings.manage (metic+, government_010), the SAME floor as the page it serves (requireGovernmentPage). The first cut gated this any-builder on the reasoning that it is \"the project's own published terms\" — but the payload also carries reward-policy internals (marginPct, usdPeg, mode), a raw rejected project_settings value, and internal file/migration paths, and a xenos who cannot even load the page could still curl those. Matching the read floor to the page's (task 1003280 grade, hacker lens) closes that asymmetry; the two WRITES already gate on this same atom, so the whole surface is now one floor. One read, not five: the page draws five rows, so it asks for five rows. Fetching per-row would put the hall's own settings page in the shape goal 1000072's criterion names (hall-ui/CLAUDE.md, \"a card asks the server for the rows it draws\").\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.settings.manage` (all required).",
+        "description": "GET /project-settings — all five rows in ONE read. rank: project.settings.manage (metic+, government_010), the SAME floor as the page it serves (requireGovernmentPage). The first cut gated this any-builder on the reasoning that it is \"the project's own published terms\" — but the payload also carries reward-policy internals (marginPct, costScale, mode), a raw rejected project_settings value, and internal file/migration paths, and a xenos who cannot even load the page could still curl those. Matching the read floor to the page's (task 1003280 grade, hacker lens) closes that asymmetry; the two WRITES already gate on this same atom, so the whole surface is now one floor. One read, not five: the page draws five rows, so it asks for five rows. Fetching per-row would put the hall's own settings page in the shape goal 1000072's criterion names (hall-ui/CLAUDE.md, \"a card asks the server for the rows it draws\").\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.settings.manage` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/project-settings.js",
         "x-permissions": [
@@ -31051,6 +31135,15 @@
           "learnings"
         ]
       },
+      "GetMarketWatchAskResponse": {
+        "type": "object",
+        "properties": {
+          "card": {}
+        },
+        "required": [
+          "card"
+        ]
+      },
       "GetMeAchievementsResponse": {
         "type": "object",
         "properties": {
@@ -36533,6 +36626,30 @@
           "stored"
         ]
       },
+      "PostMarketWatchAskAnswerRequest": {
+        "type": "object",
+        "properties": {
+          "week_of": {
+            "type": "string",
+            "maxLength": 10
+          },
+          "picks": {
+            "type": "array",
+            "maxItems": 20
+          },
+          "names": {
+            "type": "array",
+            "maxItems": 6
+          },
+          "nothing": {
+            "type": "boolean"
+          },
+          "builder_id": {
+            "type": "integer"
+          }
+        },
+        "additionalProperties": false
+      },
       "PostMeAnthropicLinkRequest": {
         "type": "object",
         "properties": {
@@ -40319,9 +40436,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 634,
-  "x-schema-count": 684,
+  "x-endpoint-count": 636,
+  "x-schema-count": 686,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 440,
+  "x-response-schemas": 441,
   "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. 634 endpoints across 104 route files.
+> **Generated from the live route files** — the route file is authoritative. 636 endpoints across 105 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`.
@@ -518,6 +518,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/llm-cache/lookup` | `metic+archon` | `cache_key`, `tokens_saved_est` | POST /llm-cache/lookup — hit/miss + atomic hit_count bump. |
 | POST | `/api/bongos/llm-cache/store` | `metic+archon` | `spec`, `result_stdout`, `result_cost_usd` | POST /llm-cache/store — upsert a freshly-produced result. |
 
+## `market-watch` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/market-watch/ask` | `any-builder` | — | every member reads their own card; nobody else's (isMember in gate()). |
+| POST | `/api/bongos/market-watch/ask/answer` | `any-builder` | `week_of`, `picks`, `names`, `nothing`, `builder_id` | a member answers for themselves only (isMember in gate()). |
+
 ## `me` (54)
 
 | Method | Path | Rank | Body | Description |

package/docs/branding-contract.md

@@ -33,7 +33,7 @@ env override   →   instance config (config/branding.json)   →   neutral star
 | `repo` | `{ owner, name }` GitHub binding. |
 | `db.database` | DB name Bongos pool connects to when neither `DATABASE_URL` nor `PGHOST`/`PGDATABASE` is set (`src/bongos/pool.js`, ADR 0062 §5). `null` in the neutral starter = **fail loud** rather than silently target a host DB. |
 | `currency` | `{ label, symbol }` — the reward unit label (e.g. "example"). Display only. |
-| `reward` | `{ marginPct, usdPeg, mode }` — the per-instance reward POLICY the economy module reads ([ADR 0054](adr/0054-session-token-reward-cost-plus.md) + ADR 0146, tasks 2009/1002270): the cost-plus margin percent (default `20`), the example-per-USD peg (default `1`), and `mode` — `"cost-plus-and-estimate"` (default; pay both the per-task author estimate AND the cost-plus session reward) or `"cost-plus-only"` (suppress the per-task estimate payout; the cost-plus session reward is the sole equity reward). Two per-craft lanes sit beside `mode` and are not derived from it: `ideatorCredit` ([ADR 0172](adr/0172-per-craft-compensation-ideator-credit-lane.md)) and `artistCredit` ([ADR 0341](adr/0341-the-page-is-the-unit-of-tweak-mode.md) D10, an approved page tweak pays its artist), each default on and withheld only by an explicit `false`. A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, 1:1 peg, pay both streams, both lanes on). |
+| `reward` | `{ marginPct, costScale, mode }` — the per-instance reward POLICY the economy module reads ([ADR 0054](adr/0054-session-token-reward-cost-plus.md) + ADR 0146, tasks 2009/1002270): the cost-plus margin percent (default `20`), the sizing factor `costScale` (default `1`; it sizes credits from cost and is not an exchange rate — a credit has no price, [ADR 0387](adr/0387-two-ledgers-credits-measure-work-money-stays-with-the-processor.md)), and `mode` — `"cost-plus-and-estimate"` (default; pay both the per-task author estimate AND the cost-plus session reward) or `"cost-plus-only"` (suppress the per-task estimate payout; the cost-plus session reward is the sole equity reward). Two per-craft lanes sit beside `mode` and are not derived from it: `ideatorCredit` ([ADR 0172](adr/0172-per-craft-compensation-ideator-credit-lane.md)) and `artistCredit` ([ADR 0341](adr/0341-the-page-is-the-unit-of-tweak-mode.md) D10, an approved page tweak pays its artist), each default on and withheld only by an explicit `false`. A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, scale 1, pay both streams, both lanes on). **`usdPeg` is the deprecated old name of `costScale`** (task 1004968): it is still read, with a one-line deprecation note in the server log, so no host pack breaks; when both are set `costScale` wins. The neutral pack sets neither key (the default `1` lives in code), so a host pack's old `usdPeg` is never shadowed by the deep-merge. Rename it at your next pack edit — support for the old key goes in a later release. |
 | `models` | `{ main, subagentDefault, subagentRoutine }` — the per-instance subagent model-allocation DEFAULT the builder-settings module reads (task 2011): the tier for the main session, subagent-default work, and routine plumbing (tiers: `haiku`/`sonnet`/`opus`/`fable`). A per-builder override resolves over this. Omit ⇒ code defaults (`opus`/`opus`/`haiku`). |
 | `tracks` | The configurable version-track set (replaces the hardcoded `product\|internal`). |
 | `theme` | `{ palette, mode, ui }` — palette file ref + theme mode, plus `ui`, the WEB look `themeMarkup()` splices into every served page as a plain `:root` after the page's stylesheet: `colors` (the thirteen contract tokens — **light-mode values**; each stylesheet derives its own dark tier from them at `:root[data-mode="dark"]` + its `prefers-color-scheme` twin, which outrank the pack), `fonts` (`display`, `body`, `links`), `favicon`, and `backdrop` — a `body{background:…}` rule that outranks every sheet in **both** modes, so a dual-mode world sets it to `var(--bg)` (the neutral pack does since [task 1003298](https://cloudbongos.com/builders#/task/1003298), ADR 0196) rather than a literal. The neutral values are the chrome world's; `config/design-tokens.neutral.json` must mirror `colors` + `fonts` key for key (`tests/design_tokens_sync.mjs`), and the world's derived recipes are recorded in `DESIGN.md`. The ui-design module's **style library** (`modules/ui-design/styles/`, [ADR 0219](adr/0219-a-look-is-a-branding-pack-the-style-library.md)) ships ready-made `theme.ui` blocks (looks) an instance copies into this field; every served sheet reads only these fifteen, so a look re-themes every surface with no page edit. |

package/docs/module-api-changelog.md

@@ -3266,5 +3266,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.24.0 with no explicit bump. run 40985289858. (task 1002620)
   1.24.2 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.24.1 with no explicit bump. run 41000649913. (task 1002620)
+  1.24.4 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.24.2 with no explicit bump. run 41004393103. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/page-readings.json

@@ -5,7 +5,7 @@
   "adr": "0341 D3",
   "reread": "node scripts/bongos/page-reader.js --stale",
   "how": ["Generated by node scripts/bongos/page-reader.js (BV2.TW04, task 1004315; ADR 0341 D3). Do not hand-edit.","One entry per page of docs/page-inventory.json. Lines are in page order: the default state first, and a line only another state shows sits where that state shows it, with its state named.","placement: placed = a docs/copy-registry.json row renders it (file, line, string_id); shared = shell text every page of the surface carries (top bar, sidebar, footer), with its row when the registry has one; unplaced = the registry cannot place it (a rewrite becomes an engineer task, ADR 0341 D4).","text keeps {…} where the registry row has a hole, or where a value the page read from its API was filled in. A string that is only such data is counted under omitted.data, not listed.","reading_hash is over the non-shared lines (key, section, text); files_hash is over the page's inventory files. --check compares files_hash only and never opens a browser.","Rendered through the hall-preview harness (hall) and the ui-design kit stub (landing, status), at 1280x800 with the clock pinned, so a reading is the fixture world's page."],
-  "counts": {"pages":48,"lines":5456,"placed":1683,"shared":427,"unplaced":3346,"omitted_data":3730},
+  "counts": {"pages":48,"lines":5456,"placed":1683,"shared":427,"unplaced":3346,"omitted_data":3731},
   "pages": [
     {
       "id": "builders:ai-studio",
@@ -271,7 +271,7 @@
       "surface": "builders",
       "title": "The city",
       "states_read": ["city","fullscreen","switched","focus","pins","living","card","card-ask"],
-      "files_hash": "a3b905698a39c7bc",
+      "files_hash": "6a8a96e1f9f6084a",
       "reading_hash": "77470c4eb3047a05",
       "counts": {"lines":43,"placed":10,"shared":8,"unplaced":25},
       "omitted": {"data":17},
@@ -3370,10 +3370,10 @@
       "surface": "builders",
       "title": "The street",
       "states_read": ["street","fullscreen","card","switched","focus","here","inside-rules","inside-disputes","inside-people","inside-planning","inside-automation","inside-review","inside-release","inside-treasury","floor","amend","district","desk","desk-facts","desk-quiet","desk-people-builders","desk-people-tier","desk-disputes","desk-automation-goals","desk-release-core","desk-rules","desk-rules-category","desk-planning-priorities","desk-planning-ideas","desk-planning-blockers","pins","pins-pager","living","deck","deck-treasury","sitting","object","voted","admission","settled","blocker","blocker-more","report","report-more","core","core-more","recheck","recheck-more","idea","idea-more","queue","queue-more","automation","automation-more"],
-      "files_hash": "5c081c34c9e70e53",
-      "reading_hash": "f9a1c5189c877bb0",
+      "files_hash": "6180e15ad9dcf4d6",
+      "reading_hash": "b5cd1724efa21f28",
       "counts": {"lines":650,"placed":75,"shared":8,"unplaced":567},
-      "omitted": {"data":552},
+      "omitted": {"data":553},
       "notes": ["sitting: an action failed (page.click: Timeout 6000ms exceeded.); read as it stood","object: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"board:47\"]); read as it stood","voted: an action failed (page.click: Timeout 6000ms exceeded.); read as it stood","admission: an action failed (page.click: Timeout 6000ms exceeded.); read as it stood","settled: an action failed (page.click: Timeout 6000ms exceeded.); read as it stood","blocker: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"blockers:11\"]); read as it stood","blocker-more: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"blockers:11\"]); read as it stood","report: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"redteam_reports:4\"]); read as it stood","report-more: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"redteam_reports:4\"]); read as it stood","core: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"core_update:1.21.20\"]); read as it stood","core-more: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"core_update:1.21.20\"]); read as it stood","recheck: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"module_rechecks:7\"]); read as it stood","recheck-more: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"module_rechecks:7\"]); read as it stood","idea: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"board:41\"]); read as it stood","idea-more: an action failed (page.evaluate: Error: dispatchClick: nothing matches .street-pin[data-matter=\"board:41\"]); read as it stood"],
       "lines": [
         {"key":"L0001","section":"skip link","text":"Skip to content","placement":"shared","file":"modules/hall-ui/public/shell.js","line":868,"string_id":"87cee78ca134"},
@@ -3597,7 +3597,7 @@
         {"key":"L0219","section":"Spending matters","text":"{…} of {…}","placement":"placed","file":"modules/hall-ui/public/sky-panel.js","line":120,"string_id":"73c1372b43d9","state":"inside-treasury"},
         {"key":"L0220","section":"Spending matters","text":"{…} from the reserve?","placement":"unplaced","state":"inside-treasury"},
         {"key":"L0221","section":"Spending matters","text":"{…} · today","placement":"unplaced","state":"inside-treasury"},
-        {"key":"L0222","section":"Spending matters","text":"Paid $5,549 to 7 buil… · today","placement":"unplaced","state":"inside-treasury"},
+        {"key":"L0222","section":"Spending matters","text":"7 builders earned 5,5… · today","placement":"unplaced","state":"inside-treasury"},
         {"key":"L0223","section":"Spending matters","text":"{…} · 4w","placement":"unplaced","state":"inside-treasury","occurrences":2},
         {"key":"L0224","section":"Spending matters","text":"the record","placement":"placed","file":"modules/hall-ui/public/street.html","line":192,"string_id":"4bde7b562cf4","state":"inside-treasury"},
         {"key":"L0225","section":"Spending matters","text":"1 matter on the docket · 16 on the {…}","placement":"unplaced","state":"inside-treasury"},
@@ -3832,7 +3832,7 @@
         {"key":"L0454","section":"Priorities","text":"standing law","placement":"unplaced","state":"desk-planning-priorities"},
         {"key":"L0455","section":"Waiting on {…}","text":"Waiting on {…}","placement":"placed","file":"modules/hall-ui/public/goals-lib.js","line":91,"string_id":"b18832e219dc","state":"inside-planning"},
         {"key":"L0456","section":"Waiting on {…}","text":"9 waiting · oldest 3 weeks","placement":"unplaced","state":"inside-planning"},
-        {"key":"L0457","section":"Waiting on {…}","text":"waiting","placement":"placed","file":"modules/hall-ui/public/work.js","line":431,"string_id":"8186b562553a","state":"inside-planning"},
+        {"key":"L0457","section":"Waiting on {…}","text":"waiting","placement":"placed","file":"modules/hall-ui/public/work.js","line":438,"string_id":"8186b562553a","state":"inside-planning"},
         {"key":"L0458","section":"Waiting on {…}","text":"on {…}","placement":"unplaced","state":"inside-planning"},
         {"key":"L0459","section":"Waiting on {…}","text":"WA","placement":"unplaced","state":"inside-planning"},
         {"key":"L0460","section":"Waiting on {…}","text":"Working area 2…","placement":"unplaced","state":"inside-planning"},

package/modules/discord/ship-broadcast.js

@@ -96,6 +96,13 @@ async function postShipBroadcast(task, deps = {}) {
 
   const postWebhook = deps.postWebhook || require('./webhook').postWebhook;
   const log = deps.log || console.log;
+  // task 1004969 (ADR 0385 decision 9): an AI-written summary that calls credits
+  // or models an investment is FLAGGED in the log and posted unchanged — recorded,
+  // never blocked or rewritten. No economy module, no check.
+  const reward = deps.reward !== undefined ? deps.reward : require('../../src/module-api').resolveOptional('reward');
+  if (reward && typeof reward.flagInvestmentWording === 'function') {
+    result.wording_flags = reward.flagInvestmentWording(summary, { where: 'ship summary', ref: `task ${task.id}`, log }).length;
+  }
   const pageTweak = task.source === PAGE_TWEAK_SOURCE;
   const pageArtist = pageTweak && sec === false ? await pageArtistName(task, deps) : null;
   const targets = chooseBroadcastTargets({ securitySensitive: sec, taskId: task.id, summary, kind: task.kind, pageTweak, pageArtist });

package/modules/economy/credit-wording.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// modules/economy/credit-wording.js — finds investment wording next to credits
+// or models (task 1004969; ADR 0385 decision 9).
+//
+// WHY. Credits are a contribution meter, not money and not a stake (ADR 0385,
+// ADR 0387), and a module or a model is not something a builder invests in.
+// Wording that says otherwise keeps coming back — in code comments, onboarding
+// docs and AI-written ship summaries — and every time it does the project reads
+// as if it were selling a security. This is the one check for it.
+//
+// THE RULE. A sentence is flagged when an investment word (investment, return,
+// appreciation, passive income, equity, ownership) sits within NEAR_WORDS words
+// of a credit word or a model word. A sentence that DENIES it ("credits are not
+// an investment", "never equity") is the wording we want, so a negation shortly
+// before the investment word clears it.
+//
+// It only FINDS. Callers decide what to do: the wording test fails on a hit, and
+// the server publish paths log a flag and publish the text unchanged — never a
+// silent rewrite, never a block. PURE: no I/O, so it is safe on any path.
+
+const NEAR_WORDS = 12;
+const NEGATION_WORDS = 4;
+
+const ANCHOR_RE = /^(credits?|drachmae|models?)$/i;
+const NEGATION_RE = /^(not|never|no|nor|isn't|aren't|without|neither)$/i;
+
+// One entry per investment idea; `words` is the phrase as lower-case tokens.
+// "return" is the noun only: "returns" alone, or "return on"/"a return" — the
+// verb ("the task returns to ready") is everywhere and says nothing about money.
+const TERMS = [
+  { term: 'investment', match: (w) => /^invest(ment|ments|ing|or|ors|ed|s)?$/.test(w[0]) && 1 },
+  { term: 'return', match: (w, prev) => {
+    if (w[0] === 'return' && w[1] === 'on') return 2;
+    if (/^returns?$/.test(w[0]) && /^(a|any|financial|guaranteed|expected|your|their|high|higher)$/.test(prev || '')) return 1;
+    return 0;
+  } },
+  { term: 'appreciation', match: (w) => (w[0] === 'appreciation' ? 1 : (/^appreciat(e|es|ing)$/.test(w[0]) && w[1] === 'in' && w[2] === 'value' ? 3 : 0)) },
+  { term: 'passive income', match: (w) => (w[0] === 'passive' && w[1] === 'income' ? 2 : 0) },
+  { term: 'equity', match: (w) => (w[0] === 'equity' ? 1 : 0) },
+  { term: 'ownership', match: (w) => (w[0] === 'ownership' ? 1 : 0) },
+];
+
+function sentences(text) {
+  return String(text == null ? '' : text).split(/(?<=[.!?;])\s+|\n\s*\n|\n(?=\s*[-*|#>])/);
+}
+
+function tokens(sentence) {
+  return (sentence.toLowerCase().match(/[a-z][a-z']*/g) || []).map((t) => t.replace(/'s$/, ''));
+}
+
+// Every offending sentence in `text`: [{ term, phrase, anchor, sentence }]. Pure.
+function findInvestmentWording(text) {
+  const out = [];
+  for (const raw of sentences(text)) {
+    const sentence = raw.replace(/\s+/g, ' ').trim();
+    if (!sentence) continue;
+    const w = tokens(sentence);
+    const anchors = [];
+    w.forEach((t, i) => { if (ANCHOR_RE.test(t)) anchors.push(i); });
+    if (!anchors.length) continue;
+    for (let i = 0; i < w.length; i++) {
+      for (const T of TERMS) {
+        const len = T.match(w.slice(i, i + 3), w[i - 1]);
+        if (!len) continue;
+        const near = anchors.find((a) => Math.abs(a - i) <= NEAR_WORDS);
+        if (near === undefined) continue;
+        const negated = w.slice(Math.max(0, i - NEGATION_WORDS), i).some((t) => NEGATION_RE.test(t));
+        if (negated) continue;
+        out.push({ term: T.term, phrase: w.slice(i, i + len).join(' '), anchor: w[near], sentence });
+      }
+    }
+  }
+  return out;
+}
+
+// The server publish paths' half: find, write one log line per hit, return the
+// hits. The text is published unchanged whatever this finds, and it never
+// throws — a wording check must not be the reason a summary or an idea is lost.
+function flagInvestmentWording(text, { where = 'text', ref = null, log = console.warn } = {}) {
+  try {
+    const hits = findInvestmentWording(text);
+    for (const h of hits) {
+      log(`[credit-wording] flagged ${where}${ref == null ? '' : ` ${ref}`}: "${h.phrase}" near "${h.anchor}" in "${h.sentence.slice(0, 200)}" `
+        + '(ADR 0385 decision 9; published unchanged)');
+    }
+    return hits;
+  } catch (_) {
+    return [];
+  }
+}
+
+module.exports = { findInvestmentWording, flagInvestmentWording, NEAR_WORDS, NEGATION_WORDS };

package/modules/economy/credits.js

@@ -9,7 +9,7 @@
 // (db.applyGrade/confirmTask/upsertSessionRecordWithReward) resolves these
 // through the `reward` kernel PORT rather than importing this module.
 
-const { pool, branding, resolveOptional } = require('../../src/module-api');
+const { pool, branding, resolveOptional, logger } = require('../../src/module-api');
 const { priceModelUsage, PRICES } = require('../../src/module-api').llmPricing; // cost-plus session reward (task 1005)
 const achievements = require('./achievements');
 
@@ -143,12 +143,13 @@ const IDEA_GOVERNANCE_PASS_FLOOR = 30;  // owner: floor ~30 — see the note on
 // Both accrue to builders.total_credits (the contribution meter); ADR 0054 (+ its
 // 2026-06-15 amendment) records the scale and why the cents form existed.
 //
-// REWARD_MARGIN_PCT (and the 1:1 cost-to-drachma scale, `usdPeg`) are the code-default reward
+// REWARD_MARGIN_PCT (and the 1:1 sizing factor, `costScale` — formerly `usdPeg`,
+// task 1004968) are the code-default reward
 // POLICY. They stay a code-reviewed default — not a live UI knob — for the same
 // reasons KIND_MULTIPLIERS does: a policy decision deserves a commit trail and
 // the grader reads it deterministically. But the reward policy is also
 // PER-INSTANCE config (task 2009 / BONGOS-V1): an instance overrides the margin
-// + the drachmae:USD peg in `config/branding.json` `reward.{marginPct,usdPeg}`
+// + the sizing factor in `config/branding.json` `reward.{marginPct,costScale}`
 // (still a committed, code-reviewed change — just in the instance's config, not
 // the vendored core module). `rewardConfig()` resolves the instance value over
 // these defaults; the pure helper keeps its code defaults so tests stay
@@ -161,8 +162,13 @@ const IDEA_GOVERNANCE_PASS_FLOOR = 30;  // owner: floor ~30 — see the note on
 // (ADR 0146) and every existing caller is unchanged.
 const {
   REWARD_MARGIN_PCT, REWARD_MODE_DEFAULT, REWARD_MODE_COST_PLUS_ONLY, IDEA_DESCENT_DECAY, rewardPolicy,
+  rewardPolicyDeprecation,
 } = require('./reward-policy');
 
+// The usdPeg deprecation note prints ONCE per process, not once per award: this
+// resolver runs on every ship, and a line per ship would bury the logs.
+let usdPegNoteShown = false;
+
 // Per-instance reward policy, resolved over the code defaults. Stays HERE, not in
 // reward-policy.js: the branding read must go through the module port (ADR 0083),
 // and a file the CLI can share may not import the port. Best-effort — a branding
@@ -170,6 +176,11 @@ const {
 function rewardConfig() {
   let r = {};
   try { r = (branding().reward) || {}; } catch { r = {}; }
+  const note = rewardPolicyDeprecation(r);
+  if (note && !usdPegNoteShown) {
+    usdPegNoteShown = true;
+    logger('economy').warn(note);
+  }
   return rewardPolicy(r);
 }
 
@@ -205,22 +216,25 @@ function rewardConfig() {
 // absent/any-non-false → the default TRUE (a pre-ADR-0172 config keeps paying).
 
 // Pure helper — exported for tests. Returns { trueCostUsd, marginPct, drachmae,
-// description }. drachmae = round(cost × (1+margin) × usdPeg); at the 1:1 scale
+// description }. drachmae = round(cost × (1+margin) × costScale); at the 1:1 scale
 // one drachma is earned per dollar of cost-plus (task 1138) — sized by USD, not
 // worth USD (ADR 0387), e.g.
 //   "$15.00 true cost × 1.20 = 18 drachmae (token reward)"
-// NOTE a sub-$0.42 session (at the 1:1 peg) rounds to 0 drachmae — intended:
+// NOTE a sub-$0.42 session (at the 1:1 scale) rounds to 0 drachmae — intended:
 // sub-dollar sessions earn nothing. Kept pure (code-default params); the call
 // site resolves per-instance policy via rewardConfig() and passes it in.
-function computeSessionTokenReward(trueCostUsd, marginPct = REWARD_MARGIN_PCT, usdPeg = 1) {
+// A non-1 factor is written into the description as "× N scale" (it said
+// "× N peg" before task 1004968; only NEW rows carry the new word — no existing
+// credit_log row is rewritten). At the default 1 the description is unchanged.
+function computeSessionTokenReward(trueCostUsd, marginPct = REWARD_MARGIN_PCT, costScale = 1) {
   const cost = Number(trueCostUsd) || 0;
   const pct = Number(marginPct) || 0;
-  const peg = Number.isFinite(Number(usdPeg)) && Number(usdPeg) > 0 ? Number(usdPeg) : 1;
+  const scale = Number.isFinite(Number(costScale)) && Number(costScale) > 0 ? Number(costScale) : 1;
   const mult = 1 + pct / 100;
-  const drachmae = Math.round(cost * mult * peg);
-  const pegNote = peg !== 1 ? ` × ${peg} peg` : '';
+  const drachmae = Math.round(cost * mult * scale);
+  const scaleNote = scale !== 1 ? ` × ${scale} scale` : '';
   const description =
-    `$${cost.toFixed(2)} true cost × ${mult.toFixed(2)}${pegNote} = ${drachmae} drachmae (token reward)`;
+    `$${cost.toFixed(2)} true cost × ${mult.toFixed(2)}${scaleNote} = ${drachmae} drachmae (token reward)`;
   return { trueCostUsd: cost, marginPct: pct, drachmae, description };
 }
 
@@ -1026,8 +1040,8 @@ async function awardSessionTokenReward(
   const extraRaw = Number(extraCostUsd);
   const extra = Number.isFinite(extraRaw) ? Math.max(0, extraRaw) : 0;
   const trueCostUsd = Math.round((pricedCostUsd + extra) * 10000) / 10000;
-  const { marginPct, usdPeg } = rewardConfig();
-  const { drachmae, description } = computeSessionTokenReward(trueCostUsd, marginPct, usdPeg);
+  const { marginPct, costScale } = rewardConfig();
+  const { drachmae, description } = computeSessionTokenReward(trueCostUsd, marginPct, costScale);
 
   // Nothing priced (no real tokens) — record nothing, report cleanly.
   if (!(drachmae > 0)) {

package/modules/economy/governor-docket.js

@@ -5,7 +5,7 @@
 // modules/government/docket.js).
 //
 // WHY. Inside the Treasury building three floors are the project's real
-// spending lines — rewards paid for shipped work, the AI grader, and hosting —
+// lines — credits earned for shipped work, the AI grader, and hosting —
 // and its record drawers are those same lines month by month. They come from
 // the two ledgers this module owns (credit_log, cost_log) through ONE bounded
 // read, cost.treasuryMonths. The ledgers are already published unauthenticated
@@ -28,22 +28,28 @@ function usd(n) {
   const v = Math.round(Number(n) || 0);
   return `$${v.toLocaleString('en-US')}`;
 }
+// Credits are a contribution meter, not money (ADR 0385, ADR 0387): the rewards
+// line counts them and never wears a $ sign (task 1005006).
+function credits(n) {
+  const v = Math.round(Number(n) || 0);
+  return `${v.toLocaleString('en-US')} ${v === 1 ? 'credit' : 'credits'}`;
+}
 function monthKey(now) { const d = new Date(now); return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`; }
 function monthWord(key) { const m = Number(String(key).slice(5, 7)); return MONTHS[m - 1] || String(key); }
 
 // One spending line's floor from the month rows. Pure.
-function lineFloor(months, now, field, { what, meta }) {
+function lineFloor(months, now, field, { what, meta, fmt = usd }) {
   const rows = Array.isArray(months) ? months : [];
   const cur = rows.find((r) => r.month === monthKey(now));
   const prev = rows.find((r) => r.month < monthKey(now));
   const v = cur ? Number(cur[field]) || 0 : 0;
   const lines = [[what, meta]];
-  if (prev) lines.push([`${usd(prev[field])} in ${monthWord(prev.month)}.`, 'last month']);
-  return { count: usd(v), line: `${usd(v)} this month`, lines, hot: false };
+  if (prev) lines.push([`${fmt(prev[field])} in ${monthWord(prev.month)}.`, 'last month']);
+  return { count: fmt(v), line: `${fmt(v)} this month`, lines, hot: false };
 }
 
 function rewardsFloor(months, now) {
-  const f = lineFloor(months, now, 'rewards_credits', { what: 'Paid to builders for shipped work, one credit to the dollar.', meta: 'each ship' });
+  const f = lineFloor(months, now, 'rewards_credits', { what: 'Credits earned for shipped work. They count contribution; they are not money.', meta: 'each ship', fmt: credits });
   const cur = (months || []).find((r) => r.month === monthKey(now));
   const n = cur ? cur.rewarded_builders : 0;
   return { ...f, line: `${f.count} this month · ${n} ${n === 1 ? 'builder' : 'builders'}` };
@@ -56,7 +62,7 @@ function treasuryHistory(months) {
   const out = [];
   for (const r of months || []) {
     const at = `${r.month}-01T00:00:00.000Z`;
-    if (r.rewards_credits > 0) out.push({ id: `rewards:${r.month}`, title: `Paid ${usd(r.rewards_credits)} to ${r.rewarded_builders} ${r.rewarded_builders === 1 ? 'builder' : 'builders'}`, at, outcome: 'rewards' });
+    if (r.rewards_credits > 0) out.push({ id: `rewards:${r.month}`, title: `${r.rewarded_builders} ${r.rewarded_builders === 1 ? 'builder' : 'builders'} earned ${credits(r.rewards_credits)}`, at, outcome: 'rewards' });
     if (r.grading_usd > 0) out.push({ id: `grading:${r.month}`, title: `AI grading cost ${usd(r.grading_usd)}`, at, outcome: 'grading' });
     if (r.hosting_usd > 0) out.push({ id: `hosting:${r.month}`, title: `Hosting cost ${usd(r.hosting_usd)}`, at, outcome: 'hosting' });
   }

package/modules/economy/reward-policy.js

@@ -2,7 +2,7 @@
 // (task 1003676).
 //
 // What it is: the reward defaults and the PURE function that resolves a branding
-// pack's `reward` block over them — margin, USD peg, mode, whether the per-task
+// pack's `reward` block over them — margin, cost scale, mode, whether the per-task
 // credit and the ideator lane are on.
 //
 // Why it is its own file, and why it imports NOTHING: this is the one piece of
@@ -50,13 +50,56 @@ const REWARD_MODE_COST_PLUS_ONLY = 'cost-plus-only';
 // code path to disable separately.
 const IDEA_DESCENT_DECAY = 0.5;
 
+// THE SIZING FACTOR IS `costScale` (task 1004968). It multiplies a session's
+// cost-plus figure into credits and is 1 by default. It used to be called
+// `usdPeg`, which read as an exchange rate between a credit and a dollar —
+// exactly what ADR 0387 rules out (a credit has no redemption price). The OLD
+// key is still accepted so no host pack breaks before every hosted pin has moved
+// past this release (ADR 0161); when both are set, `costScale` wins. Removing
+// `usdPeg` support is a later task. The formula itself does not change, and no
+// existing credit_log row is touched — this only renames how a pack spells it.
+// config/branding.neutral.json carries NEITHER key, on purpose: a host pack
+// deep-merges over neutral, so a neutral `costScale: 1` would beat a host's old
+// `usdPeg` and silently reset its awards. The default 1 lives here instead.
+const LEGACY_SCALE_KEY = 'usdPeg';
+const USD_PEG_DEPRECATION =
+  'branding reward.usdPeg is deprecated: rename it to reward.costScale (same value, same awards; ADR 0387).';
+
+function validScale(v) {
+  if (v == null) return NaN;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : NaN;
+}
+
+// PURE. Which sizing factor a raw block carries: costScale if it is valid, else
+// the legacy usdPeg, else the default 1. An INVALID costScale falls through to
+// usdPeg rather than to 1, so a typo in the new key cannot silently change the
+// awards of a pack that still carries a working old one.
+function resolveCostScale(rawReward) {
+  const r = rawReward || {};
+  const fromNew = validScale(r.costScale);
+  if (Number.isFinite(fromNew)) return fromNew;
+  const fromOld = validScale(r[LEGACY_SCALE_KEY]);
+  if (Number.isFinite(fromOld)) return fromOld;
+  return 1;
+}
+
+// PURE. The one-line deprecation note for a pack that still spells the factor the
+// old way, or null. Only when costScale is absent: a pack that has moved and kept
+// the old key beside it is not using it, because costScale wins.
+function rewardPolicyDeprecation(rawReward) {
+  const r = rawReward || {};
+  if (r[LEGACY_SCALE_KEY] != null && r.costScale == null) return USD_PEG_DEPRECATION;
+  return null;
+}
+
 // PURE. Resolves a raw branding `reward` block over the code defaults. Every field
 // is validated rather than trusted: a malformed pack degrades to the defaults
 // instead of poisoning an award.
 function rewardPolicy(rawReward) {
   const r = rawReward || {};
   const marginPct = Number.isFinite(Number(r.marginPct)) ? Number(r.marginPct) : REWARD_MARGIN_PCT;
-  const usdPeg = Number.isFinite(Number(r.usdPeg)) && Number(r.usdPeg) > 0 ? Number(r.usdPeg) : 1;
+  const costScale = resolveCostScale(r);
   const mode = r.mode === REWARD_MODE_COST_PLUS_ONLY ? REWARD_MODE_COST_PLUS_ONLY : REWARD_MODE_DEFAULT;
   const perTaskCredit = mode !== REWARD_MODE_COST_PLUS_ONLY;
   // Default-on, opt-out-only: only an explicit `false` withholds the ideator lane.
@@ -77,7 +120,7 @@ function rewardPolicy(rawReward) {
   const ideaDescentDecay = Number.isFinite(rawDecay) && rawDecay >= 0 && rawDecay < 1
     ? rawDecay
     : IDEA_DESCENT_DECAY;
-  return { marginPct, usdPeg, mode, perTaskCredit, ideatorCredit, artistCredit, ideaDescentDecay };
+  return { marginPct, costScale, mode, perTaskCredit, ideatorCredit, artistCredit, ideaDescentDecay };
 }
 
 module.exports = {
@@ -85,5 +128,8 @@ module.exports = {
   REWARD_MODE_DEFAULT,
   REWARD_MODE_COST_PLUS_ONLY,
   IDEA_DESCENT_DECAY,
+  USD_PEG_DEPRECATION,
+  resolveCostScale,
+  rewardPolicyDeprecation,
   rewardPolicy,
 };

package/modules/economy/reward.js

@@ -24,6 +24,7 @@ const ideaSizeHistorical = require('./idea-size-historical');
 const ideaBrightnessLib = require('./idea-brightness');
 const creditsByCraftLib = require('./credits-by-craft');
 const goalReward = require('./goal-reward');
+const creditWording = require('./credit-wording');
 
 module.exports = {
   // credit allocation — transaction-participant: caller passes its tx `client`
@@ -147,4 +148,8 @@ module.exports = {
   wouldExtendStreak: (...a) => streak.wouldExtendStreak(...a),
   // task 1004853: /me's batched form — one streak + one task query per request.
   streakPreviewsForTasks: (...a) => streak.streakPreviewsForTasks(...a),
+  // task 1004969 (ADR 0385 decision 9): investment wording next to credits or
+  // models. The publish paths flag and log it; they never block or rewrite.
+  findInvestmentWording: (...a) => creditWording.findInvestmentWording(...a),
+  flagInvestmentWording: (...a) => creditWording.flagInvestmentWording(...a),
 };