@bongos/core 1.17.0 → 1.17.1

package/docs/recipes/packaging-the-core.md

@@ -2,7 +2,7 @@
 
 > Implements [ADR 0100 §1](../adr/<redacted>.md) (the two-repo instance model). This is **R84**, the first step of the `R84 → R85 → R86` spine: package the core → stand a downstream instance up on a pinned core → make `bongos upgrade` a real update channel. Tooling: [`scripts/gds/package-core.js`](../../scripts/gds/package-core.js) (`bongos package-core`).
 >
-> **Real installable npm package ([ADR 0108](../adr/<redacted>.md) §2, task 1882/W2, shipped):** the artifact is `package/`-rooted (the npm convention `npm install ./x.tgz` requires) and carries a synthesized `package.json` — `name: "@cloudbongos/core"`, `version` = `CORE_VERSION`, `main: "src/platform-server.js"`, `exports` for the default entry (`buildPlatformApp`) plus `./serve-internal` (`mountInternalSurfaces`) and `./module-api`, `bin: "bongos"` — and a **pruned** `package-lock.json` (express + pg's own transitive closure only, resolved offline from the source lockfile — no colyseus/phaser/sharp/discord.js). Both files are synthesized fresh, never copied verbatim from the source repo's game-heavy `package.json`. `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js), W1/task 1881) are what a consumer's own code routes through once installed.
+> **Real installable npm package ([ADR 0108](../adr/<redacted>.md) §2, task 1882/W2, shipped):** the artifact is `package/`-rooted (the npm convention `npm install ./x.tgz` requires) and carries a synthesized `package.json` — `name: "@bongos/core"`, `version` = `CORE_VERSION`, `main: "src/platform-server.js"`, `exports` for the default entry (`buildPlatformApp`) plus `./serve-internal` (`mountInternalSurfaces`) and `./module-api`, `bin: "bongos"` — and a **pruned** `package-lock.json` (express + pg's own transitive closure only, resolved offline from the source lockfile — no colyseus/phaser/sharp/discord.js). Both files are synthesized fresh, never copied verbatim from the source repo's game-heavy `package.json`. `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js), W1/task 1881) are what a consumer's own code routes through once installed.
 
 ## What the artifact is
 
@@ -12,9 +12,9 @@ A Cloud Bongos *instance* can be its **own repository** that installs a **pinned
 
 | Output | What it is |
 |---|---|
-| `cloudbongos-core-<version>.tgz` | the installable unit — a gzip'd tar of the redacted core tree, rooted at `package/` (the npm convention `npm install ./x.tgz` requires), carrying a synthesized `@cloudbongos/core` `package.json` + pruned `package-lock.json` (task 1882) |
-| `cloudbongos-core-<version>.manifest.json` | the **pin** — version, source commit, per-file hashes, and the tree hash a consumer verifies against |
-| `cloudbongos-core-<version>/` | the same redacted tree unpacked, for inspection |
+| `bongos-core-<version>.tgz` | the installable unit — a gzip'd tar of the redacted core tree, rooted at `package/` (the npm convention `npm install ./x.tgz` requires), carrying a synthesized `@bongos/core` `package.json` + pruned `package-lock.json` (task 1882) |
+| `bongos-core-<version>.manifest.json` | the **pin** — version, source commit, per-file hashes, and the tree hash a consumer verifies against |
+| `bongos-core-<version>/` | the same redacted tree unpacked, for inspection |
 
 The version is the **platform version** — `CORE_VERSION` from [`src/module-api.js`](../../src/module-api.js), the same coordinate the module loader and `bongos upgrade` compare against ([#1203](https://example.com/builders#/task/1203)). That shared coordinate is what keeps the spine coherent: a module pinned to `^core_contract` is guaranteed to load against the packaged core.
 
@@ -36,7 +36,7 @@ If the no-leak gate fails, it names the file + the residual literal. Fix the red
 
 A downstream instance repo:
 
-1. **Installs** the `.tgz` — `npm install ./cloudbongos-core-<version>.tgz` (or a fetched-in-CI path) — which lands it at `node_modules/@cloudbongos/core/`, a directory the consumer does not hand-edit.
+1. **Installs** the `.tgz` — `npm install ./bongos-core-<version>.tgz` (or a fetched-in-CI path) — which lands it at `node_modules/@bongos/core/`, a directory the consumer does not hand-edit.
 2. **Pins** by recording `core_version` + `source_commit` + `tree_sha256` from the manifest.
 3. **Verifies** the install by recomputing `tree_sha256` from the unpacked tree — for each core file, `sha256(content)` with a canonical mode (`0000644`/`0000755`), then `sha256` over the sorted `"<path> <mode> <filesha>"` lines. It must equal the manifest's `tree_sha256`. The tree hash is **compression-independent**, so it is a stable pin even though `.tgz` bytes are an implementation detail (`tarball.sha256` separately verifies the exact download).
 

package/docs/recipes/private-npm-distribution.md

@@ -1,15 +1,15 @@
 # Recipe — private-first npm distribution (core + client)
 
-> Implements [ADR 0134](../adr/<redacted>.md). Pre-launch, `@cloudbongos/core` and `@cloudbongos/client` publish as **private, scoped** npm packages on a paid `cloudbongos` npm org; at launch they flip to public. The daily command is `bongos` regardless of package name.
+> Implements [ADR 0134](../adr/<redacted>.md). Pre-launch, `@bongos/core` and `@bongos/client` publish as **private, scoped** npm packages on the owner's paid `bongos` npm org (the canonical brand); at launch they flip to public. The daily command is `bongos` regardless of package name.
 >
-> **Why private must be scoped:** on npm, *unscoped* names (like `cloudbongos`) are always public — only *scoped* names (`@cloudbongos/…`) can be private, and only on a paid plan. The repo already uses the `@cloudbongos` scope, so no rename is needed now.
+> **Why private must be scoped:** on npm, *unscoped* names are always public — only *scoped* names (`@bongos/…`) can be private, and only on a paid plan. So the packages publish under the `@bongos` scope, which maps to the paid `bongos` org.
 
 ## The pieces
 
 | Package | What it is | Built by |
 |---|---|---|
-| `@cloudbongos/core` | the platform an instance installs + the `bongos` CLI (`bin`) | `bongos package-core` (`scripts/gds/package-core.js`) — synthesizes the package.json + a pruned lockfile, redacts, and packs a `.tgz` |
-| `@cloudbongos/client` | the generated typed API client | `node scripts/gds/gen-api-client.js` (regenerates `clients/bongos-client/`) |
+| `@bongos/core` | the platform an instance installs + the `bongos` CLI (`bin`) | `bongos package-core` (`scripts/gds/package-core.js`) — synthesizes the package.json + a pruned lockfile, redacts, and packs a `.tgz` |
+| `@bongos/client` | the generated typed API client | `node scripts/gds/gen-api-client.js` (regenerates `clients/bongos-client/`) |
 
 Both carry `publishConfig: { access: "restricted" }`, so **publishing them is private by default** — no public leak if a flag is forgotten.
 
@@ -17,8 +17,8 @@ Both carry `publishConfig: { access: "restricted" }`, so **publishing them is pr
 
 These involve payment and permanent, account-level actions. They are **not** done inside a build session.
 
-1. **Put the `cloudbongos` npm org on a paid plan.** Private scoped publishing requires it. On npmjs.com → your org → Billing → upgrade to a plan that allows private packages (npm Teams, ~$7/member/month). Add as members only the people who need to publish or install during pre-launch — each is a billed seat.
-2. **Create an access token.** npmjs.com → Access Tokens → *Generate New Token* → **Granular/Automation**, with **read-write** on the `@cloudbongos` packages (for publishing) — a **read-only** token is enough for machines that only install. Store it as an environment variable, never in a committed file:
+1. **Put the `bongos` npm org on a paid plan.** Private scoped publishing requires it. On npmjs.com → your org → Billing → upgrade to a plan that allows private packages (npm Teams, ~$7/member/month). Add as members only the people who need to publish or install during pre-launch — each is a billed seat.
+2. **Create an access token.** npmjs.com → Access Tokens → *Generate New Token* → **Classic → Automation** (bypasses 2FA, which npm requires to publish), with **read-write** on the `@bongos` packages — a **read-only** token is enough for machines that only install. Store it as an environment variable, never in a committed file:
    ```sh
    export NPM_TOKEN=<redacted>
    ```
@@ -32,7 +32,7 @@ Always preview with a dry-run first (no upload, no login needed):
 node scripts/gds/package-core.js --publish
 ```
 
-Look for `restricted access` and the `@cloudbongos/core@<version>` line. When it looks right, publish for real (this is **permanent** — npm can't delete a name after 72h):
+Look for `restricted access` and the `@bongos/core@<version>` line. When it looks right, publish for real (this is **permanent** — npm can't delete a name after 72h):
 
 ```sh
 npm login                                         # once per machine (+ 2FA)
@@ -58,13 +58,23 @@ Add a one-line `.npmrc` (repo-root or `~/.npmrc`) that reads the token from the
 Then, with `NPM_TOKEN` set in the environment:
 
 ```sh
-npm install -g @cloudbongos/core   # global → the `bongos` command, then `bongos init`
-npm install @cloudbongos/client    # in a project that calls the API
+npm install -g @bongos/core   # global → the `bongos` command, then `bongos init`
+npm install @bongos/client    # in a project that calls the API
 ```
 
 Without a valid token + org membership the install 404s — that is the private gate working.
 
-> Provisioning still installs the core from a **vendored tarball** committed into each instance repo (task 2053) — that path is unchanged and needs no token. Wiring provisioning to pull the pinned core from the private registry instead is a tracked follow-up.
+## Provisioning: registry pull vs vendored tarball (task 2090)
+
+Provisioning defaults to installing the core from a **vendored tarball** committed into each instance repo (task 2053) — offline, needs no token, and stays the default/fallback until the registry path is proven on a real greenfield standup. The registry pull is **opt-in and fail-soft**:
+
+- **Turn it on** by setting `PROVISION_CORE_FROM_REGISTRY=1` in the control-plane runner's environment (e.g. `/etc/cloudbongos/box.env`) **and** providing a read-only `NPM_TOKEN` (a Classic **Automation** token — read-only — from the paid `bongos` org). With both present, the standalone scaffold pins `@bongos/core@<version>` from the registry and writes an env-fed `.npmrc` (`_authToken=<redacted> instead of vendoring a tarball; `npm ci` then pulls the private package (the token is inherited from the runner env — never committed).
+- **Fail-soft**: if the flag is set but `NPM_TOKEN` is absent, provisioning logs a notice and **falls back to the vendored tarball**, so a tokenless standup still works.
+- **Directly**: `bongos init --registry-core` scaffolds the registry shape (caret pin + `.npmrc`; generates the lockfile when `NPM_TOKEN` is set). `bongos upgrade --to <v> --registry` bumps a consumer to a registry version. Both are mutually exclusive with the vendored `--vendor-core` / `--from` inputs.
+
+A tokenless registry `npm ci` 404s cleanly (`E404 … @bongos/core … could not be found or you do not have permission to access it`) — the expected pre-launch outcome.
+
+> **Proven end-to-end (2026-07-08, task 2118 / blocker 71).** A real `bongos init --registry-core` scaffold, with a valid read-only token in `NPM_TOKEN`, resolved `@bongos/core@1.17.0` straight from `registry.npmjs.org` and generated a reproducible `package-lock.json`. Both legs are confirmed: the registry pull works with a token and fails closed (404) without one. Provisioning still defaults to the vendored tarball until an owner explicitly sets `PROVISION_CORE_FROM_REGISTRY=1` on a live runner.
 
 ## Going public at launch
 
@@ -72,8 +82,8 @@ Pick either — both keep the daily `bongos` command working:
 
 - **Flip the same scoped packages public** (simplest):
   ```sh
-  npm access public @cloudbongos/core
-  npm access public @cloudbongos/client
+  npm access public @bongos/core
+  npm access public @bongos/client
   ```
   (Or change `publishConfig.access` to `"public"` and republish.) Public installs need no token; the paid seats can be dropped.
 - **Also publish the unscoped vanity name** for `npm install -g cloudbongos` — that is [task 2025](https://example.com/builders#/task/2025) (rename in `package-core.js`/`upgrade.js` + docs), done at launch.

package/docs/recipes/self-host.md

@@ -2,7 +2,7 @@
 
 Bring up a vanilla Cloud Bongos instance — the build platform + builders' hall + status dashboard, with no game — on any machine with Docker. Shipped by V4.R63 ([task #1202](https://example.com/builders#/task/1202), [ADR 0062](../adr/<redacted>.md)).
 
-> **Relation to configurable-root ([ADR 0108](../adr/<redacted>.md)):** this is the **single-checkout** self-host shape — the whole repo (core + config) is baked into one image, so `resolveCoreRoot()` and `resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js)) both resolve to `/app` inside the container. ADR 0108 does not deprecate this path — it stays the cheap, supported shape for a quick reskin (this is how `cloudbongos.com` runs). The *installed-as-a-dependency* shape (a consumer repo running `npm install @cloudbongos/core`) is the separate, heavier path ADR 0108 targets for a project that wants its own repo and its own upgrade cadence — see [`docs/recipes/packaging-the-core.md`](packaging-the-core.md).
+> **Relation to configurable-root ([ADR 0108](../adr/<redacted>.md)):** this is the **single-checkout** self-host shape — the whole repo (core + config) is baked into one image, so `resolveCoreRoot()` and `resolveInstanceRoot()` ([`src/instance-config.js`](../../src/instance-config.js)) both resolve to `/app` inside the container. ADR 0108 does not deprecate this path — it stays the cheap, supported shape for a quick reskin (this is how `cloudbongos.com` runs). The *installed-as-a-dependency* shape (a consumer repo running `npm install @bongos/core`) is the separate, heavier path ADR 0108 targets for a project that wants its own repo and its own upgrade cadence — see [`docs/recipes/packaging-the-core.md`](packaging-the-core.md).
 
 ## One command
 

package/docs/recipes/upgrading-the-core.md

@@ -1,14 +1,14 @@
 # Recipe — upgrading a consumer instance's Cloud Bongos core (`bongos upgrade`)
 
-> The R86 update-consumption channel ([ADR 0100](../adr/<redacted>.md) §2, [ADR 0103](../adr/<redacted>.md) §4, task [#1690](https://example.com/builders#/task/1690)). How a **two-repo consumer instance** — one that installs `@cloudbongos/core` as a vendored-tarball dependency — pulls the core from version N → N+1. Tooling: [`scripts/gds/upgrade.js`](../../scripts/gds/upgrade.js) (`bongos upgrade`). First proven live on emersonian-circles 1.15.0 → 1.16.0 (task [#1976](https://example.com/builders#/task/1976)).
+> The R86 update-consumption channel ([ADR 0100](../adr/<redacted>.md) §2, [ADR 0103](../adr/<redacted>.md) §4, task [#1690](https://example.com/builders#/task/1690)). How a **two-repo consumer instance** — one that installs `@bongos/core` as a vendored-tarball dependency — pulls the core from version N → N+1. Tooling: [`scripts/gds/upgrade.js`](../../scripts/gds/upgrade.js) (`bongos upgrade`). First proven live on emersonian-circles 1.15.0 → 1.16.0 (task [#1976](https://example.com/builders#/task/1976)).
 
 ## What the channel does
 
 `bongos upgrade --to <version> --from <tgz>` runs, from a consumer instance root:
 
 1. **pre-flight** — module-compat vs the target core + a clean git tree (skip with `--force`).
-2. **bump the pin** — vendor the new `cloudbongos-core-<version>.tgz` and rewrite the `"@cloudbongos/core": "file:vendor/…"` dependency.
-3. **`npm install`** — `node_modules/@cloudbongos/core` becomes the new version.
+2. **bump the pin** — vendor the new `bongos-core-<version>.tgz` and rewrite the `"@bongos/core": "file:vendor/…"` dependency.
+3. **`npm install`** — `node_modules/@bongos/core` becomes the new version.
 4. **`npm run migrate`** — the core's `migrate.sh` applies additive `core_*` migrations (merged three-root: core + instance + modules).
 5. **materialize `.claude/`** — refresh skills/settings/hooks from the new core (`materializeClaude`), rewriting invocations to the `bongos` bin.
 6. **restart** — `--service <unit>` or `--restart-cmd "<cmd>"`.
@@ -21,8 +21,8 @@ Run bare (`bongos upgrade`, no `--to`) it stays the module-compat **pre-check**
 The channel ships *in* the core. On the FIRST bump, the consumer's installed core is the OLD version (whose `bongos upgrade` may be the pre-check stub or lack a fix). So drive the first bump with the **new version's** `upgrade.js`, run out of its extracted package against `--instance <consumer>`:
 
 ```bash
-cd /tmp && rm -rf pkg && mkdir pkg && tar xzf cloudbongos-core-<version>.tgz -C pkg
-node /tmp/pkg/package/scripts/gds/upgrade.js --to <version> --from /tmp/cloudbongos-core-<version>.tgz --instance <consumer-root> …
+cd /tmp && rm -rf pkg && mkdir pkg && tar xzf bongos-core-<version>.tgz -C pkg
+node /tmp/pkg/package/scripts/gds/upgrade.js --to <version> --from /tmp/bongos-core-<version>.tgz --instance <consumer-root> …
 ```
 
 Once a consumer is on a core that carries the channel, its own `bongos upgrade` drives later bumps.
@@ -33,15 +33,15 @@ The instance runs on the droplet (co-tenant): systemd `emersonian-circles.servic
 
 1. **Cut the canonical tarball from `main`** (after the core change has merged, so the pin is a real release):
    ```bash
-   node scripts/gds/package-core.js --version <version>   # → dist/cloudbongos-core-<version>.tgz (+ manifest)
+   node scripts/gds/package-core.js --version <version>   # → dist/bongos-core-<version>.tgz (+ manifest)
    ```
-   `package-core` archives committed `HEAD`, **not the working tree** — commit + merge first, then verify the artifact (`ls dist/cloudbongos-core-<version>/…`).
+   `package-core` archives committed `HEAD`, **not the working tree** — commit + merge first, then verify the artifact (`ls dist/bongos-core-<version>/…`).
 2. **Back up the instance DB** — `pg_dump emersonian_circles | gzip > /tmp/…sql.gz`.
 3. **`scp` the tarball to the droplet**, verify `sha256sum` matches.
 4. **`--dry-run` first**, then the real run — extracted-package bootstrap, with the instance DB pinned:
    ```bash
    PGDATABASE=emersonian_circles CLOUDBONGOS_INSTANCE_ROOT=/home/lars/emersonian-circles \
-     node /tmp/pkg/package/scripts/gds/upgrade.js --to <version> --from /tmp/cloudbongos-core-<version>.tgz \
+     node /tmp/pkg/package/scripts/gds/upgrade.js --to <version> --from /tmp/bongos-core-<version>.tgz \
        --instance /home/lars/emersonian-circles \
        --restart-cmd "sudo systemctl restart emersonian-circles.service" \
        --health-url http://127.0.0.1:3004/healthz

package/migrations/core_191_module_submissions.sql

@@ -0,0 +1,45 @@
+-- core_191_module_submissions.sql — the ADR 0107 §1 upstreaming review queue.
+--
+-- task 1770: `bongos module submit <key>` packages a module (manifest +
+-- attribution + file contents) + its DCO-style sign-off and files it into a
+-- rank-gated review queue. Real cross-repo submission (an instance filing into
+-- the CORE repo's own review process) is not wired up yet — the extracted core
+-- (github.com/lars589/cloud-bongos, private) has no reachable submission API
+-- today, and R85 (the forcing-function second consumer) was abandoned in favor
+-- of the already-proven two-repo model (see task 1689's value_summary). So this
+-- table is the interim, buildable-now queue: it lives in THIS instance's own
+-- Bongos DB (the same DB the module was built against), rank-gated identically
+-- to the eventual core-side surface. Task 1771 (core-side review & accept flow)
+-- reviews rows here; if/when a live cross-repo core endpoint exists, filing
+-- becomes a network hop instead of a local INSERT with no schema change to the
+-- caller. See docs/adr/0135-module-upstream-submission-interim-queue.md.
+--
+-- files jsonb = [{ path, contentBase64, bytes }, ...] — a full snapshot of the
+-- module tree at submit time (ADR 0107 §1 "packages the module + ... into a
+-- ... queue"), so a reviewer (task 1771) can inspect the submitted code without
+-- needing network/filesystem access to the submitting instance's repo.
+--
+-- Idempotent: safe to re-run.
+
+CREATE TABLE IF NOT EXISTS module_submissions (
+  id                  bigserial PRIMARY KEY,
+  module_key          text NOT NULL,
+  submitted_by        bigint NOT NULL REFERENCES builders(id),
+  manifest            jsonb NOT NULL,
+  files               jsonb NOT NULL,
+  sign_off            jsonb NOT NULL,
+  precheck_passed_at  timestamptz NOT NULL,
+  source_repo         text,
+  status              text NOT NULL DEFAULT 'pending'
+                        CHECK (status IN ('pending', 'accepted', 'rejected')),
+  reviewed_by         bigint REFERENCES builders(id),
+  reviewed_at         timestamptz,
+  review_notes        text,
+  submitted_at        timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_module_submissions_status ON module_submissions (status, submitted_at DESC);
+CREATE INDEX IF NOT EXISTS idx_module_submissions_key ON module_submissions (module_key, submitted_at DESC);
+
+INSERT INTO schema_migrations (version) VALUES ('core_191_module_submissions')
+  ON CONFLICT (version) DO NOTHING;

package/modules/autonomy/CLAUDE.md

@@ -1,49 +1,15 @@
-# `autonomy` module — the Multi-Agent System (conductor · architect · gate · routine timers)
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> A CORE-domain carve (BV1.R83, [ADR 0093](../../docs/adr/<redacted>.md) §1) — the eighth tranche-2 domain extracted from the GDS core, after sessions (R82). `default: true` — the autonomy machinery + the durable in-process routine timer ship to every instance (both inert/no-op until armed or the pool is reachable), so it mounts unconditionally unless an instance disables it.
+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.
 
-Owns the **Multi-Agent System** surfaces ([ADR 0024](../../docs/adr/<redacted>.md)):
-- the **autonomy gate** (System 3, task 1351) — the $0 deterministic precheck that decides go/no-go before any model boots; a precheck HTTP route + the gate CLI, **inert until `OTB_AUTONOMY_ENABLED=1`**;
-- the **routine timers** (System 4 / [ADR 0078](../../docs/adr/<redacted>.md) amendment, task 1382) — the in-process weekly **peer-vote-tally** poller (no model, no external cron);
-- the **Conductor** mid-flight dispatch CLI (Phase 4, task 439) and the **Architect** bounded first-principles `--scope` audit CLI (Phase 5, task 459) — domain commands.
+**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.
 
-## The boundary (the one rule)
+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.
 
-The module's `src/`-scanned files (`db.js`, `pollers/`, `routes/`) reach core **only** through the published doorway `../../src/module-api.js` (`coreVersion ^1.11.0`). They must **never** `require()` a core internal (`../../src/bongos/db`, `../../src/bongos/auth`, …) directly, and **never** another module. Core, in turn, must never `require()` a file in here — the route mount + the timer-start both left `src/bongos/`/`server.js`; the loader (`mountModuleRoutes` + `startModulePollers`) wires them now. Both directions are enforced by the BV1.R44/R45 fitness checks.
-
-## Cross-cutting: it OBSERVES lifecycle (the seams)
-
-This is the cross-cutting domain the carve sequence flagged. Two inbound core→autonomy edges existed; each was inverted so the module is wired, not imported:
-
-1. **The routine timer** (was `routineTimers.start()` in `server.js`) → now a **POLLER** (`contributes.pollers:["routine-timers"]`). The loader's `startModulePollers` requires `pollers/routine-timers.js` and calls `start()` at boot / `stop()` at shutdown — the module-agnostic successor to the hardcoded block (the Discord-bot-poller pattern, BV1.R47). server.js is the only `startModulePollers` caller (not `src/platform-server.js`), so a second always-on instance can't double-run. The timer's work is the lifecycle **`tallyPeerVotes`** capability (the SAME transaction `POST /tasks/peer-votes/tally` runs — route + timer share ONE path), reached through the **doorway** (`api.tallyPeerVotes`, a tracked lifecycle leak — it writes karma_log/peer_votes/tasks, all core-owned; relocates behind a `lifecycle.*` port at R86), never a core require.
-2. **The autonomy precheck route** (was mounted in `src/bongos/routes.js`) → now a **module route** (`contributes.routes:["autonomy"]`, mounted by `mountModuleRoutes`). `GET /autonomy/precheck` (Archon-gated) calls the gate's `precheck`.
-
-## No port (the sessions/memory shape)
-
-Like `sessions`/`memory`, autonomy registers **no kernel port** (`provides: []`) — **core never calls back into it.** The timer is a loader-started poller, the precheck a module route, and the gate/conductor/architect are CLIs. There is nothing for a port to expose. (`consumes: []` too — `tallyPeerVotes` is a doorway export, not a seam port.)
-
-## Files
-
-| File | What |
-|---|---|
-| `db.js` | the `autonomy_runs` db slice — `recordAutonomyRun` (audit each precheck decision) + `lastAutonomyHead` (the stored last-`go` head the no-signal check compares origin/main against). Reaches Postgres through the doorway `pool`. |
-| `pollers/routine-timers.js` | the in-process weekly **peer-vote-tally** timer (the loader's poller entry — `start`/`stop`). `runPeerVoteTally` resolves the lifecycle `tallyPeerVotes` via the doorway; pure w.r.t. injected `deps` (tests pass `deps.db`). Kill-switch `ROUTINE_TIMERS_DISABLED`; unref'd, best-effort. |
-| `routes/autonomy.js` | `GET /autonomy/precheck` (Archon-gated) — the autonomy precheck over HTTP; wraps the gate CLI's `precheck`. Inert (always `go`) until `OTB_AUTONOMY_ENABLED=1`. |
-
-## NOT in this module (the domain CLIs travel with the domain but stay under `scripts/`)
-
-A command travels with its domain but stays a CLI (design 02§1; the sessions/memory precedent). These live under `scripts/gds/` — **outside** the kernel boundary (fitness scans `src/` + `modules/`, not `scripts/`), so they may still read the ideas/economy/lifecycle signals + the grader directly, which a `modules/` file may not:
-
-- **`scripts/gds/autonomy-gate.js`** — the gate CLI (Step 0 of the nightly routines). Its pure decision logic (`decide`, `autofixAllowed`) is `$0`; its `gatherSignals` reads claimable tasks (core db), open ideas (`modules/ideas`), autonomous MTD spend (`modules/economy`), and the autonomy_runs head/record (**this module's `db.js`**). The precheck route + scheduled tasks invoke it.
-- **`scripts/gds/conductor-dispatch.js`** — the Conductor mid-flight dispatch (runs grader specialists on the current diff; reuses `modules/grading/grader` + `src/bongos/sensitive-surfaces` + `src/bongos/path-match`).
-- **`scripts/gds/architect-audit.js`** — the Architect's bounded `--scope` audit → `docs/audits/` + seed ideas (reuses the grader + `src/bongos/llm-cache`).
-- **`scripts/gds/run-routine.js`** — the deterministic-first cron dispatcher (parses a routine's SKILL.md, runs steps at the cheapest sufficient tier).
-- **`.claude/scheduled-tasks/`** — the cron routine SKILL.md files that invoke these CLIs (re-pointed at the moved gate; the scripts they call are unchanged paths).
-
-## Tables (owned, not moved)
-
-`autonomy_runs` (migration 126) was created before the module system and stays in core `migrations/` (the shared-schema additive rule the sessions/onboarding carves established). The module owns the *queries*; any **new** autonomy migration belongs in `modules/autonomy/migrations/` namespaced `autonomy_*`.
-
-## Tests
-
-`tests/autonomy_gate.mjs` (the pure gate decision — DB-free), `tests/routine_timers.mjs` (the peer-vote timer — pure w.r.t. injected deps), `tests/conductor.mjs`, `tests/architect.mjs`, `tests/run_routine.mjs` exercise the CLIs (which import from `scripts/gds/…`). The carve discovery-key membership is asserted in `tests/fitness.mjs` / `tests/module_loader.mjs` / `tests/modules.mjs`; the doorway `tallyPeerVotes` export in `tests/module_api.mjs`.
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/builder-settings/CLAUDE.md

@@ -1,58 +1,15 @@
-# `builder-settings` module — per-builder prefs + builder-needs + the `builder-settings` kernel port
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> The **sixth CORE-domain** carved into a module (BV1.R80, [ADR 0093](../../docs/adr/<redacted>.md) §1) — after memory (R72), grading (R73), economy (R77), ideas (R78), and security (R79). A clean slice: the five pref libs + builder-needs were already standalone PURE files (zero core `require()`), so the carve is a git-move + a `db.js`-slice extraction + a route SPLIT + a port re-point — OTB byte-identical. `default: true` in `module.json` — every instance configures its own builders.
+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.
 
-Owns the **per-builder preference domain** and **builder-needs**:
+**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.
 
-- **wandering** ([`wandering-prefs.js`](wandering-prefs.js)) — how readily the agent opens a NEW THREAD of work (tangent / investigation / unsolicited suggestion) vs. staying on the claimed task. Rank-clamped server-side (Xenos → Locked, Thetes → Focused, Metic+ free). Stored in the `behavior_prefs` jsonb.
-- **interaction** ([`interaction-prefs.js`](interaction-prefs.js)) — the per-builder INTERACTION PROFILE (task 2010): tone / technical level / local-toolchain familiarity — the old CLAUDE.md §2 "The Prompter" owner-defaults, reframed as a per-builder profile (an owner is just a builder with a profile). Resolved over the portable defaults; the effective `contract` is surfaced on `/me` and injected each session (the wandering pattern). Stored in the `behavior_prefs` jsonb; `GET`/`PATCH /me/interaction`.
-- **skill** ([`skill-prefs.js`](skill-prefs.js)) — the per-skill model ceiling a spawn is clamped to (`skill_model_prefs` jsonb, migration 037).
-- **model-allocation** ([`model-alloc-prefs.js`](model-alloc-prefs.js)) — the subagent model-routing policy (task 2011): the tier for main / subagent-default / routine-plumbing slots. Resolved builder override → instance default (`branding.models`) → code default (`opus`/`opus`/`haiku`); surfaced on `/me` (`model_allocation.effective`) + `GET`/`PATCH /me/model-allocation`. Replaces the hardcoded CLAUDE.md §2 routing table. PURE lib (instance default passed in). Stored in `behavior_prefs`.
-- **sound** ([`sound-prefs.js`](sound-prefs.js)) + **event-sound** ([`event-sound-prefs.js`](event-sound-prefs.js)) — per-sound on/off + volume (`sound_prefs`, migration 075) and per-event sound-variant selection (`event_sound_prefs`, migration 164). The local `.claude/sounds/play.js` reads a mirror written by `scripts/gds/fetch-sound-prefs.js`.
-- **render** ([`render-prefs.js`](render-prefs.js)) — the "render the deterministic session cards as a rich HTML widget vs. plain text" toggle (shares `behavior_prefs`, migration 119).
-- **builder-needs** ([`builder-needs.js`](builder-needs.js)) — the consistent "the system needs an input from you" list (today: the image-generation key).
+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.
 
-## The boundary (the one rule)
-
-This module reaches core **only** through the published doorway [`../../src/module-api.js`](../../src/module-api.js) (`coreVersion ^1.8.0`). It must **never** `require()` a core internal directly, and never another module. Core, in turn, must never `require()` a file in here — it reaches the prefs/needs read surface only through the `builder-settings` port (below). Both directions are enforced by the BV1.R44/R45 fitness checks.
-
-## The `me`/`public` facade call (02-module-map §2)
-
-[02-module-map §2](../../docs/design/modular-architecture/02-module-map.md) flags `me` as a cross-domain read-aggregator that becomes a **thin facade** when its domains carve out. This carve realizes that for the prefs/needs slices:
-
-- **The five `/me/*-prefs` ROUTES moved here** ([`routes/settings.js`](routes/settings.js)) — `GET`/`PATCH` for `/me/skill-prefs`, `/me/sound-prefs`, `/me/event-sound-prefs`, `/me/wandering`, `/me/render`. They keep their **exact `/me/*` paths** (the loader mounts this router on the same `/api/gds` router, BEFORE the public catch-all), so the API is byte-identical — only the `require()` paths changed (auth/`getBuilderById` reach the doorway; the pref libs + the db slice are intra-module).
-- **The `GET /me` AGGREGATOR stayed in core `routes/me.js`** as a thin facade. It builds the `wandering` / `render` / `needs` slices of the profile payload inline (alongside the economy `reward`-port + discord/box/art seam slices it already resolves) by resolving the `builder-settings` port — never importing the module.
-- **`public.js` has NO builder-settings edge** — the §2 graph's `public → grader, security` is the real public coupling; prefs/needs are a `me`-only domain. `public.js` is untouched by this carve.
-
-## The `builder-settings` kernel PORT
-
-- **Provides — port `builder-settings`** → the read surface in [`settings.js`](settings.js): `{ getBuilderBehaviorPrefs, describeWandering, describeRender, computeNeeds, skillCeiling }`. Registered in [`routes/settings.js`](routes/settings.js)'s factory (the loader runs it at boot, and again whenever a test rebuilds the GDS router — `hasProvider`-guarded so re-instantiation never trips the single-provider guard). Mirrors `modules/economy/routes/reward.js`.
-- **The TWO core consumers resolve it WITHOUT importing this module:**
-  - `routes/me.js` — the `GET /me` aggregator (`getBuilderBehaviorPrefs` once, then `describeWandering`/`describeRender`/`computeNeeds` off the same blob).
-  - `src/bongos/cascade-dispatch.js` — the dormant System-3 cascade router clamps a spawn to the builder's model ceiling (`skillCeiling`, the former `skillPrefs.getForBuilder`).
-- Both degrade gracefully when the module is off (a vanilla instance): me.js's slices are best-effort; cascade's ceiling falls back to `'opus'` (its existing `|| 'opus'` default). No `CORE_VERSION` bump — the carve adds no doorway export (the port rides the already-exported seam registry, the security precedent).
-
-## Files
-
-| File | What |
-|---|---|
-| `db.js` | the builder-prefs db slice — the eight verbatim `get/set BuilderSkillPrefs / SoundPrefs / BehaviorPrefs / EventSoundPrefs` helpers carved out of core `db.js`. Reaches the shared pool through the doorway. |
-| `skill-prefs.js` · `sound-prefs.js` · `event-sound-prefs.js` · `wandering-prefs.js` · `render-prefs.js` | the pure shapers (`validatePatch`/`applyPatch`/`listEffective`/`describeForApi`/constants) that turn a raw jsonb blob into effective values. Moved verbatim (they were already core-`require()`-free). |
-| `builder-needs.js` | `computeNeeds(ctx)` — the "the system needs an input from you" list (the image-generation-key item). |
-| `settings.js` | the `builder-settings` port provider surface — DELEGATES (does not spread) to `db`/the pref libs so test stubs bite at call time. |
-| `routes/settings.js` | the five `/me/*-prefs` GET/PATCH endpoints (above) + the port registration. |
-
-## NOT in this module (deliberately left in core)
-
-- **The `GET /me` aggregator + every non-prefs `/me/*` route** — `routes/me.js` stays core (it's the cross-domain profile/identity surface; only the self-contained pref routes left). It resolves this module's port for its prefs/needs slices.
-- **The per-builder Gemini KEY** (`getBuilderGeminiKeyRow` / `setBuilderGeminiKey` / `clearBuilderGeminiKey`, `gemini_key_*` columns) — stays core `db.js` + the doorway (`api.getBuilderGeminiKeyRow`). It's art-pipeline credential infra (the `/me/art-key` delivery + the `art.sharedKeyConfigured` seam), read by `computeNeeds`'s caller as `ownKeySet`, not owned by builder-settings.
-- **`cascade-dispatch.js`** — the dormant System-3 cascade router stays a CORE lib (it belongs to the grading/autonomy plane, not builder-settings); it RESOLVES this module's `skillCeiling` port instead of importing `skill-prefs`.
-- **The pref-mirroring CLIs** — `scripts/gds/fetch-sound-prefs.js` + `scripts/gds/session-eval.js` (which reads `wandering-prefs`) travel with the domain but stay under `scripts/` and `require('../../modules/builder-settings/…')` directly (scripts are outside the kernel boundary — the memory/economy-carve precedent).
-
-## Tables
-
-None owned. The five jsonb columns (`skill_model_prefs` 037, `sound_prefs` 075, `behavior_prefs` 119, `event_sound_prefs` 164) live on the CORE `builders` table and stay in core `migrations/`. This module owns the *prefs queries*; any **new** builder-settings migration belongs in `modules/builder-settings/migrations/` namespaced `builder_settings_*` (the additive rule).
-
-## Tests
-
-`tests/skill_prefs.mjs`, `tests/sound_prefs.mjs`, `tests/wandering_prefs.mjs`, `tests/render_prefs.mjs`, and `tests/builder_needs.mjs` import the pure shapers from `modules/builder-settings/…`. The doorway/boundary checks (`tests/fitness.mjs`, `tests/module_loader.mjs`, `tests/modules.mjs`) discover `builder-settings` as a module. See [ADR 0093](../../docs/adr/<redacted>.md).
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/dev-box/CLAUDE.md

@@ -1,38 +1,15 @@
-# `dev-box` module — per-builder cloud dev environments
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> The **first** module extracted from core (BV1.R43, [ADR 0083](../../docs/adr/<redacted>.md)). It is the **template** every later module move copies — keep it clean.
+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.
 
-Optional feature module: per-builder DigitalOcean droplets + Cloudflare tunnels, the sandbox game preview, and server-mediated branch publish. Gated by `config/modules.json` (`dev-box: true` for the OTB instance; off on a vanilla Cloud Bongos boot). The loader (`src/module-loader/loader.js`) discovers this dir via `module.json` and mounts the route factory.
+**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.
 
-## The boundary (the one rule)
+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.
 
-This module reaches core **only** through the published doorway `../../src/module-api.js` (the semver'd contract; this module needs `coreVersion ^1.2.0`). It must **never** `require()` a core internal (`../../src/bongos/auth`, `../../src/bongos/db`, …) directly, and never another module. Core, in turn, must never `require()` a file in here — that's the forbidden core→module edge this extraction removed. (The fitness check that *enforces* this is BV1.R44/R45; until then it's WARN-mode, but the template models the right pattern.)
-
-## Files
-
-| File | What |
-|---|---|
-| `routes/box.js` | the HTTP surface — `/box/*` (own box; some `allowBoxScope`) + `/boxes/*` (Archon roster). The loader mounts this; its factory also **registers this module's seams** (idempotent). |
-| `boxes.js` | box lifecycle logic + cost ledger. Pure-ish: `pool` is passed in (DI), so it has no core require. |
-| `box-access.js` | source-access clawback (`flagBoxReconcileForBuilder`, `decideSourceAccess`). |
-| `box-credential.js` | per-box credential provider. |
-| `box-onboard.js` | SSH-key validation + connect/settings renderers. |
-| `db.js` | the module's data slice — owns `setBuilderBoxBlocked` (the box-blocked write), reached through the doorway `pool`. Lifted out of core `db.js` in BV1.R68 ([ADR 0091](../../docs/adr/<redacted>.md)); box-blocked is cleanly dev-box-owned (this module is its only writer + reader). |
-
-## Seams (how core and this module talk without importing each other)
-
-- **Provides — port `box.hasEverConnected`** `(builderId) → Promise<bool>`. Core (`routes/me.js`, `routes/builders.js`) reads it via `resolveOptional('box.hasEverConnected', async () => false)` so onboarding's `box_connect` step auto-clears when a box is on, and degrades to `false` on a box-less instance.
-- **Listens — event `builder.box-reconcile-needed`** `{ builderId, rank, status, actor }`. Core `db.js` emits it (via `emitAsync`) after a rank change / deactivate / auto-graduation; this module flags the droplet reconcile. Replaces the old `db.js → box-access` direct call.
-
-Registration happens in `routes/box.js`'s factory (the loader runs it at boot, already module-gated), guarded by `hasProvider` so re-instantiation in tests can't double-register.
-
-## NOT in this module
-
-- **The network clients** — `scripts/gds/do-api.js` (DigitalOcean), `scripts/gds/cf-tunnel.js` (Cloudflare tunnel), and their shared `scripts/gds/http-api-client.js`. They were operator-CLI-only (never the web process), so they moved OUT to the control-plane tier in BV1 task [#1943](https://example.com/builders#/task/1943) ([ADR 0111](../../docs/adr/<redacted>.md) §2) — the DO client is now shared by `box.js` AND the instance-provisioning runner `provision.js`, which a module→module import could never allow.
-- **`scripts/gds/box.js`** — the operator control-plane CLI (sole holder of `DO_API_TOKEN`/`CF_API_TOKEN`, ADR 0031 §9.4). It *requires* this module's `boxes`/`box-access`/`box-onboard` (module data/logic) plus the shared `scripts/gds/do-api`/`cf-tunnel` clients, but it is core ops tooling and stays in `scripts/gds/`.
-- **The hall UI** (`modules/hall-ui/public/`: `box-panel.js`, `harbor.js`, the `watch.js` cost section, gated mounts in `builders.js`/`settings.js`). Per-module UI sections are design **phase 6**, not this move; they stay in the hall-ui module (carved in BV1.R85), already gated by `window.__MODULES__.enabled['dev-box']`.
-- **`secret-box.js`** — unrelated per-builder secrets crypto; stays in core despite the name.
-
-## Tests
-
-`scripts/gds/smoke-box.sh` + `tests/box*.mjs` (boxes, box_access, box_onboard, box_host_keys, box_cost, box_code_staleness, box_terminal_ssrf, box_connect_e2e, cf_tunnel). They import from `modules/dev-box/…` — except the moved network clients (`tests/boxes.mjs`'s `do-api` import + `tests/cf_tunnel.mjs`) now import from `scripts/gds/…` ([#1943](https://example.com/builders#/task/1943)).
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/discord/CLAUDE.md

@@ -1,50 +1,15 @@
-# `discord` module — the Discord mirror (bot + broadcast + link/role)
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-Optional feature module: the outbound `#ship-news`/`#ship-feed` broadcast, the inbound `#ideas`/`#bugs` bot, ship-feed applause, role-sync, channel management, and the account-link state the hall reads. **Discord is a one-way mirror of the GDS — never authority** ([ADR 0033](../../docs/adr/<redacted>.md)). Gated by `config/modules.json` (`discord: true` for the OTB instance; off on a vanilla Cloud Bongos boot). The loader (`src/module-loader/loader.js`) discovers this dir via `module.json`, mounts the route factories, and starts the bot poller. Extracted from core in BV1.R47 ([task 1416](https://example.com/builders#/task/1416)).
+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.
 
-## The boundary (the one rule)
+**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.
 
-This module reaches core **only** through the published doorway `../../src/module-api.js` (the semver'd contract; this module needs `coreVersion ^1.4.0`). It must **never** `require()` a core internal (`../../src/bongos/db`, `../../src/bongos/auth`, `../../scripts/discord/lib`, …) directly, and never another module. Core, in turn, must never `require()` a file in here — that's the forbidden core→module edge this extraction removed (enforced by the BV1.R44/R45 fitness checks).
+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.
 
-## Files
-
-| File | What |
-|---|---|
-| `routes/discord.js` | Archon-only `/discord/channels/{plan,reconcile}` (ADR 0037). Its factory also **registers this module's seams** (port + listener; idempotent). |
-| `routes/bug-attachments.js` | serves `GET /bug-attachments/:name` (images attached to `#bugs` reports). Moved with the lib it reads. |
-| `discord-bot.js` | the gateway client (reactions, inbound, role-sync timer). Started/stopped via `pollers/discord-bot.js`. |
-| `discord-reaction.js` · `discord-inbound.js` · `discord-bugs.js` · `discord-approvals.js` | the passive bot features: 👍 applause, `#ideas` → idea_inbox, `#bugs` → task, member-approval reactions. |
-| `discord-role-sync.js` · `discord-channels.js` | rank→role badge reconcile + channel/topic/view management from `docs/discord/channels.json`. |
-| `discord-message-buffer.js` · `discord-audit.js` · `bug-attachments.js` | message-pair aggregator, bot-action audit helper, attachment persistence (pure). |
-| `ship-broadcast.js` | the server-side ship poster — fired by the `task.shipped` seam listener, not a core import. |
-| `db.js` | the module's data layer — owns the `discord_links`/`discord_applause` queries (via the doorway `pool`) + re-exports kernel db helpers. |
-| `auth.js` · `webhook.js` | **vendored twins** of core helpers (see below). |
-| `pollers/discord-bot.js` | the loader's web-process poller entry — `start()`/`stop()` over the bot. |
-
-## Seams (how core and this module talk without importing each other)
-
-- **Provides — port `discord.isLinked`** `(builderId) → Promise<bool>`. Core (`routes/me.js`, `routes/builders.js`) reads it via `resolveOptional('discord.isLinked', async () => false)` so the hall renders Connect/Unlink and onboarding's discord step auto-clears; degrades to `false` on a discord-less instance. (`discord.configured` — does the server hold OAuth creds — stays **core**: the account-LINK flow in `routes/auth.js` is not part of this module.)
-- **Listens — event `task.shipped`** `(shippedTaskRow)`. Core (`publish-reconciler.js`, `routes/tasks.js`) emits it on the confirmed→shipped transition; this module posts the `#ship-news`/`#ship-feed` broadcast. Replaces the old `require('./ship-broadcast')` core→discord import.
-- No consumed ports.
-
-Registration happens in `routes/discord.js`'s factory (the loader runs it at boot, already module-gated): the port is `hasProvider`-guarded; the `task.shipped` listener is off→on replaced so a test re-instantiating the router never accumulates duplicates.
-
-## Vendored twins (boundary-forced — keep in sync)
-
-The kernel doorway must stay module-agnostic (the "core carries no module code" fitness check forbids naming a module in `src/module-api.js`), and a module can't require core/scripts. So three small helpers are **copied** here, with their core originals kept for the parts of Discord that stay core:
-
-- **`auth.js`** — `isValidDiscordUserId` + `loadDiscordBotToken`. Core `src/bongos/auth.js` keeps its copies for the OAuth account-LINK flow (`routes/auth.js`).
-- **`webhook.js`** — `postWebhook`/`loadWebhooks`/`CHANNELS`, a twin of `scripts/discord/lib.js` (which stays for core `approval-broadcast.js` + the `scripts/discord/post.js` CLI).
-- **`db.js`** — `getDiscordLink`/`recordApplause` are also defined in core `src/bongos/db.js` (still used by the link flow / a seed); the others (`getBuilderByDiscordUserId`, `listDiscordLinks`, `countRecentDiscordBugFilings`) are owned here.
-
-## NOT in this module
-
-- **The OAuth account-link flow** — `routes/auth.js` + the Discord OAuth helpers in `src/bongos/auth.js` (`discordConfigured`, `addDiscordGuildMember`, …). Linking writes a core `builders`-adjacent row; it stays core. This module only surfaces the resulting *state* via the `discord.isLinked` port.
-- **`migrations/<redacted>.sql`** — stays in **core** `migrations/`. It also `ALTER`s core tables (`builders.system_role`, `audit_log.surface`) and seeds the `discord_bot` principal, so the module-migration namespacing rule (which forbids a module migration touching non-`discord_` objects) can't host it. Any *future* discord migration that touches only `discord_*` objects can live in `modules/discord/migrations/`.
-- **`ship-card.js`** — the CLI lifecycle card (claimed→shipped) used by `claim.js`/`ship.js` on every instance; not a Discord concern, stays in `src/bongos/`.
-- **`approval-broadcast.js` · `scripts/discord/{lib,post}.js`** — core/CLI Discord posters (see Vendored twins).
-- **The hall UI** (`modules/hall-ui/public/`, carved in BV1.R85) — per-module client UI is a later design phase; it stays gated by `window.__MODULES__.enabled['discord']`.
-
-## Tests
-
-`tests/discord_*.mjs` + `tests/bug_attachments.mjs` import from `modules/discord/…`. `scripts/discord/smoke*.sh` (if present) exercises the outbound poster.
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/economy/CLAUDE.md

@@ -1,48 +1,15 @@
-# `economy` module — credits, cost ledger, streaks, achievements, leaderboard + the `reward` kernel port
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> The **third CORE-domain** carved into a module (BV1.R77, [ADR 0093](../../docs/adr/<redacted>.md) §1-2) — after memory (R72) and grading (R73). Like grading, it follows ADR 0091 §4's load-bearing pattern: **keep the lifecycle state machine whole, extract the capability it invokes behind a kernel seam.** The lifecycle no longer imports the credit/achievement code directly; it resolves a `reward` PORT this module registers.
+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.
 
-Owns the **builder economy**: the cost-plus + kind-multiplier credit-allocation model (the real-money credit ledger), the idea-promotion bonus, the flat session-token reward, the net-negative (simplification) ship bonus, the cost ledger + dashboard rollups, builder streaks, achievements/gamification, and the leaderboard. `default: true` in `module.json` — every instance rewards its own builders, so it mounts unconditionally unless explicitly disabled.
+**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.
 
-## The boundary (the one rule)
+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.
 
-This module reaches core **only** through the published doorway `../../src/module-api.js` (`coreVersion ^1.7.0` — it needs the R77 doorway addition: `llmPricing`, the shared token→USD pricing lib). It must **never** `require()` a core internal directly, and never another module. Core, in turn, must never `require()` a file in here — it reaches economy only through the `reward` port (below). Both directions are enforced by the BV1.R44/R45 fitness checks; R70's `kernel-imports-no-domain` check keeps the kernel from reaching back in.
-
-## The `reward` kernel PORT (ADR 0093 §1-2 — the headline of this carve)
-
-- **Provides — port `reward`** → the economy module's reward surface (`modules/economy/reward.js`). Registered in `routes/reward.js`'s factory (the loader runs it at boot, and again whenever a test rebuilds the GDS router — `hasProvider`-guarded so re-instantiation never trips the single-provider duplicate guard).
-- **It is a TRANSACTION-PARTICIPANT port** (unlike the stateless `grade` port): the credit-allocation methods (`insertMultipliedConfirmCredit`, `maybeAwardIdeaPromotionBonus`, `awardNetNegativeBonus`, `awardSessionTokenReward`) and the claim/ship gamification hooks (`evaluateAfterClaim/Ship/CreditAward`) take the **caller's tx `client` as the first arg**. The core lifecycle opens the `withTx`, runs the state-machine SQL (FOR UPDATE, `task_grades` upsert, `UPDATE tasks status`, claim-holder lookup, `logGradeAttempt`) itself, and calls `reward.*(client, …)` inside that same transaction — so the credit write commits atomically with the status flip. Extract the capability; keep the state machine (ADR 0091 §4).
-- **Core consumes it WITHOUT importing this module:**
-  - the LIFECYCLE — `db.applyGrade` / `db.confirmTask` / `db.decideOverrideRequest` / `db.claimTask` / `db.upsertSessionRecordWithReward` resolve it via `seams.resolveOptional('reward')` and call the credit/achievement methods inside their own `withTx`.
-  - the READ routes — `routes/me.js` (achievement getters + streak preview + `getBuilderCostStatus`), `routes/public.js` (`costSummary` + `getLeaderboardWithAchievements`), `routes/builders.js` (`setBuilderMonthlyBudget`), `routes/sessions.js` (`sumCreditsForTasks`), and `publish-reconciler.js` (`reconcileSessionCosts`) resolve the same port and call its read surface. economy registers ONE port; its provider exposes both the lifecycle methods and the read surface (the grading precedent registers the whole module surface on its single port too).
-- This replaced the former `const achievements = require('./achievements')` / `cost` / `cost-summary-shape` core→domain requires in `db.js`, the `db.leaderboard`/`db.logCost`/etc. monolith helpers, and the `require('../streak')` core-route imports.
-
-## Files
-
-| File | What |
-|---|---|
-| `credits.js` | the credit-allocation model: `KIND_MULTIPLIERS`/`IDEA_BONUS_FRACTION`/`REWARD_MARGIN_PCT`, `applyKindMultiplier`, `computeSessionTokenReward`, `insertMultipliedConfirmCredit`, `maybeAwardIdeaPromotionBonus`, `awardSessionTokenReward`, `awardNetNegativeBonus` (+ `NET_NEGATIVE_BONUS`/`SUBTRACTOR_THRESHOLD`/`netNegativeBonusAmount`), the `leaderboard`, and `sumCreditsForTasks`. Writes `credit_log`. |
-| `cost.js` | the cost ledger: `logCost` (the one `cost_log` writer), `reconcileSessionCosts`, `costSummary`/`costCalibrationSummary`, `getBuilderCostStatus`, `setBuilderMonthlyBudget`, `autonomousApiSpendMtd`. |
-| `cost-classify.js` | pure cost-attribution audit + budget classification (`classifyCostStatus`, `auditCostAttribution`, `formatAuditReport`, `OWNERLESS_CATEGORIES`, `SOFT_CAP_FRACTION`). Moved from `src/bongos/cost.js` (renamed to avoid colliding with `cost.js`). |
-| `cost-summary-shape.js` | pure cost-summary dimension shapers (`shapeBySource`/`shapeByTier`/`shapeSavings`/`shapeCostCalibration`). |
-| `streak.js` | streak math + anti-gaming guards (`computeStreak`, `wouldExtendStreak`, …). Reaches the shared pool through the doorway. |
-| `achievements.js` | the achievement evaluators (`evaluateAfterClaim/Ship/CreditAward`, `alreadyUnlocked`, `unlockAchievement`, `filesForBadges`) PLUS the getter slice moved from `db.js` (`listAchievements`, `getBuilderAchievements`, `getLeaderboardWithAchievements`, `getLockedAchievementsProgress`, `renderProgressText`). `require('./streak')` is an intra-module sibling. |
-| `reward.js` | the `reward` port provider surface — DELEGATES (does not spread) to `credits`/`achievements`/`cost`/`streak` so test stubs bite at call time. |
-| `routes/reward.js` | registers the `reward` port (above); no HTTP endpoint. |
-| `routes/cost.js` | `POST /cost` — log a cost row (idempotent). Reaches auth/validators via the doorway; the writer via `../cost`. |
-| `routes/leaderboard.js` | `GET /leaderboard` — public drachmae-ordered leaderboard, via `../credits`. |
-
-## NOT in this module (deliberately left in core)
-
-- **`llm-pricing.js`** — the shared token→USD pricing lib stays core shared LLM-cost infra (consumed by BOTH this module's reward/cost paths AND core cost scripts `ship.js`/`session-cost.js`, so it can't be economy-owned). It is exposed to this module on the doorway as `api.llmPricing` (a tracked R73-style domain leak, like `api.llmCache`). It relocates behind a port if/when an llm-infra domain is carved (tranche 2). The economy scope-map glob lists `src/bongos/llm-pricing.js` for task-affinity even though the FILE stays in core.
-- **The recent-ships feed + estimation-drift + grade-trend reads** (`db.recentShippedTasks`, `<redacted>`, `getEstVsActualRatio`, `estimationDriftSummary`, `recentGradesForBuilder`, `builderRollingAvgGrade`, `rollingAvgGrade`, `gradeTrendByDay`) — these stay `db.*` (lifecycle/sessions reads, not economy ledger SQL); out of scope for this carve.
-- **The karma feed** (`recentKarmaForBuilder`, `karmaDelta30d`, `karma_log`) — stays in core `db.js` (a separate social-signal domain).
-- **The economy-owned CLIs** — a command travels with its domain but stays under `scripts/`: `backfill-cost.js` (requires `../../modules/economy/cost-classify`), `diagnose-achievements.js` (requires `../../modules/economy/streak`). (The memory/grading-carve precedent.)
-
-## Tables
-
-None owned. `credit_log`, `cost_log`, `cost_baseline`, `achievements`, `builder_achievements` (+ their migrations) were created before the module system and stay in core `migrations/` (the schema-migrations stem-key makes a later relocation a no-op). The module owns the *queries*; any **new** economy migration belongs in `modules/economy/migrations/` namespaced `economy_*` (the additive rule).
-
-## Tests
-
-`tests/credit_grant.mjs` (credits.js), `tests/cost.mjs`/`tests/cost_audit.mjs`/`tests/cost_budget_status.mjs` (cost-classify.js), `tests/cost_summary_shape.mjs`, `tests/streak.mjs`, and `tests/diff_derived_signals.mjs` import from `modules/economy/…`. The lifecycle-attribution tests (`tests/grade_attribution.mjs`, `tests/confirm_attribution.mjs`, `tests/grade_server_authoritative.mjs`, `tests/override_attribution.mjs`, `tests/override_request_ownership.mjs`) register the `reward` port (and stub `achievements` on the live module object) before driving `db.applyGrade`/`confirmTask`/`decideOverrideRequest`. See ADR 0093.
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._