@bongos/core 1.17.0 → 1.17.2

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)
@@ -47,6 +47,23 @@ npm pack ./clients/bongos-client --dry-run        # token-free content preview
 npm publish ./clients/bongos-client               # real (publishConfig makes it restricted; needs npm login)
 ```
 
+## Cutting a core release (the policy — [ADR 0137](../adr/<redacted>.md))
+
+Publishing is a **manual, owner-gated step** — merges to `main` do **not** auto-publish (no npm write-token lives in CI). The update subscription ([ADR 0136](../adr/<redacted>.md)) consumes whatever the owner has published, so a release is exactly: bump → publish → the subscription picks it up on its next sweep.
+
+1. **Bump `CORE_VERSION`** in [`src/module-api.js`](../../src/module-api.js) (semver; a **patch** for a fix, **minor** for additive surface — a **major** is a deliberate, human-only event) and add a one-line changelog entry in the same file. This bump is a normal claimed task, not a release-tool side effect — the version's provenance stays in the git history + changelog.
+2. **Publish** (owner, from a clean checkout of the released commit):
+   ```sh
+   node scripts/gds/package-core.js --publish        # DRY-RUN: runs the fail-closed no-leak gate, previews @bongos/core@<version>
+   npm login                                          # once per machine (+ 2FA), or use a Classic Automation token
+   node scripts/gds/package-core.js --publish --live  # permanent; the no-leak gate must pass or nothing is built/uploaded
+   ```
+   The no-leak / mirror-redact gate is **built into the build** — a leaking artifact is never produced, so `--publish` cannot upload one.
+3. **Tag the release** (optional but recommended — the deliberate, auditable marker): `git tag core-v<version> && git push origin core-v<version>`. The tag documents intent; it triggers no CI.
+4. **Done.** Subscribed instances on the `patch`/`minor` channel take it automatically on their next routine sweep; `pinned` instances wait for a manual `bongos upgrade`. A stale (un-bumped) version is rejected by npm as a duplicate — a natural guard.
+
+> **Automating this** (a tag-triggered CI publish) is deferred to the managed-fleet epic ([#1948](https://example.com/builders#/task/1948)); revisit when the manual step becomes a real bottleneck. See [ADR 0137](../adr/<redacted>.md) "When to revisit".
+
 ## Install a private package (any consumer machine or instance)
 
 Add a one-line `.npmrc` (repo-root or `~/.npmrc`) that reads the token from the environment:
@@ -58,13 +75,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 +99,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/staging-environment.md

@@ -65,7 +65,7 @@ If `*.example.com` is **not** in the output:
 The prod OAuth app points its callback at `example.com/api/gds/auth/web/callback`. Staging needs its own:
 
 1. github.com → Settings → Developer settings → OAuth Apps → New OAuth App.
-2. Application name: `Off the Boats — staging`.
+2. Application name: `Example — staging`.
 3. Homepage URL: `https://staging.example.com`.
 4. Authorization callback URL: `https://staging.example.com/api/gds/auth/web/callback`.
 5. Note the **Client ID** and **Client Secret** — they go into `/home/lars/example-staging/.env` (see step 4 of the provisioning script).

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

@@ -1,18 +1,19 @@
 # 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>"`.
 7. **verify** — installed version == target (+ optional `--health-url`).
+8. **auto-rollback on failure** (task [#2149](https://example.com/builders#/task/2149), default ON) — if `npm install`/`migrate` fails or the step-7 health check fails, revert the pin → reinstall the previous core → restart → re-verify → write a `rolled_back:` ledger row. Opt out with `--no-rollback-on-failure`. See the section below.
 
 Run bare (`bongos upgrade`, no `--to`) it stays the module-compat **pre-check** only.
 
@@ -21,8 +22,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 +34,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
@@ -50,6 +51,60 @@ The instance runs on the droplet (co-tenant): systemd `emersonian-circles.servic
 6. **Update the repo of record** — run the channel on the laptop clone (`--skip-migrate`, no DB there), commit the pin bump (drop the superseded tarball), `git push origin`.
 7. **Align the droplet checkout** — the droplet has no deploy key (`git pull` fails; idea 509), so `git bundle` the new commit on the laptop, `scp`, `git fetch <bundle> && git reset --hard FETCH_HEAD`. `node_modules` is already the new version, so no re-`npm ci`; a final restart makes `/version` report the new commit.
 
+## Auto-rollback on failure (task 2149)
+
+By default (`--rollback-on-failure`, ON unless `--no-rollback-on-failure`) the channel self-heals a failed bump. If **`npm install` fails**, **`npm run migrate` fails**, or the **post-restart health check fails**, `bongos upgrade` automatically:
+
+1. reverts the `@bongos/core` pin to the exact pre-upgrade dep string (snapshotted the instant the pin moved),
+2. `npm install`s the previous core back,
+3. restarts the service,
+4. re-verifies (installed == previous, health recovers),
+5. records a `rolled_back: <reason> (attempted N → N+1, restored N)` row in `core_upgrades`.
+
+**The DB is NOT rolled back — only the code pin.** Core migrations are additive + forward-safe (the core migration rule), so an already-applied migration is left in place; a *failed* migration is never recorded in `schema_migrations`, so a retry re-runs it cleanly. The reversal is recorded via the always-present `note` column (not a new `outcome` column) so it lands even in the failed-migrate path — where a newer column wouldn't yet exist on that instance.
+
+**Proven live on demo.cloudbongos.com** (task [#2157](https://example.com/builders#/task/2157)): demo, on rollback-capable 1.17.3, was upgraded to a canary carrying a deliberately-failing migration. Migrate raised → the channel auto-reverted the pin to 1.17.3, reinstalled + restarted it, `/healthz` stayed 200 (**zero downtime** — the failure was at migrate, before the restart), and a `rolled_back` ledger row was written. This is the safety gate the unattended patch-only auto-upgrade subscription (task [#2150](https://example.com/builders#/task/2150)) depends on.
+
+## Subscribing to updates — unattended patch-only auto-upgrade (task 2150 / ADR 0136)
+
+The sections above are the *manual* `bongos upgrade`. The **subscription** runs it for you, on a cadence, safely — the "subscribe to regular updates" experience. Policy: **patch-only by default, health-gated with auto-rollback, opt-in, autonomy-gated** (full rationale in [ADR 0136](../adr/<redacted>.md)).
+
+**Per-instance channel** bounds how far an unattended upgrade may jump:
+
+| channel | takes | example (from `1.17.1`) |
+|---|---|---|
+| `pinned` | nothing (manual only) | — |
+| `patch` *(default)* | higher patch, same `x.y` | `→ 1.17.4`, never `1.18.0` |
+| `minor` | higher minor, same major | `→ 1.18.0`, never `2.0.0` |
+
+A **major** is never automatic; prereleases are never auto-targeted.
+
+**Enrolling an instance** — add it to [`config/update-subscriptions.json`](../../config/update-subscriptions.json) (ships empty). `env` carries per-instance vars merged into the upgrade child — set `PGDATABASE` so `migrate` hits the right DB (see the Gotchas):
+
+```json
+{
+  "defaultChannel": "patch",
+  "instances": [
+    { "slug": "demo", "dir": "/srv/cloudbongos/demo", "service": "demo.service",
+      "healthUrl": "https://demo.cloudbongos.com/healthz", "channel": "patch",
+      "env": { "PGDATABASE": "demo" } }
+  ]
+}
+```
+
+**Preview vs run** — dry-run is the default; the scheduled step passes `--apply`:
+
+```bash
+node .claude/scheduled-tasks/core-update-subscription/subscribe.js            # plan only
+node .claude/scheduled-tasks/core-update-subscription/subscribe.js --apply    # upgrade
+```
+
+Each subscribed instance: read its installed core → ask the registry (`npm view`, needs `NPM_TOKEN`) → resolve the newest version its channel permits → if newer, `bongos upgrade --to <v> --registry` with **auto-rollback ON**. It prints one line per instance plus a tally; a non-zero exit means an upgrade failed (already auto-reverted).
+
+**Triple-gated, so nothing moves by accident:** the `core-update-subscription` routine is `requiresAutonomy: true` + **default OFF** in [`config/scheduled-routines.json`](../../config/scheduled-routines.json), the roster ships empty, and every upgrade is health-gated. Arm it by enabling the routine's timer on the control plane once autonomy is on.
+
+**Not covered:** multi-host / SSH orchestration across a real fleet (the deferred fleet-control-plane epic, task [#1948](https://example.com/builders#/task/1948)); and *publishing* new patches, which stays a gated owner step (ADR 0134) — a follow-up task decides whether merges auto-publish.
+
 ## Gotchas
 
 - **`PGDATABASE` is load-bearing on a co-tenant droplet.** `migrate.sh` defaults `PGDATABASE` to `example` — **production**. Always set `PGDATABASE=<instance-db>` explicitly, or you migrate the wrong database.

package/docs/research/cursor-competitive-analysis.md

@@ -1,6 +1,6 @@
 # Cursor (Anysphere) — Competitive-Threat Analysis for Cloud Bongos
 
-**A competitor-research document for Cloud Bongos / Off the Boats**
+**A competitor-research document for Cloud Bongos / Example**
 Prepared 2026-06-22 · the **first committed competitor doc** in this repo · companion to the (uncommitted) `component-based-dev-research.md` deep-research doc · task [#1403](https://example.com/builders#/task/1403)
 
 ---

package/docs/research/llm-model-agnostic-and-cheaper-grader.md

@@ -1,6 +1,6 @@
 # LLM Model-Agnostic Platform + Cheaper Grader — Tools Audit & Architecture Path
 
-**A research/architecture spike for Cloud Bongos / Off the Boats**
+**A research/architecture spike for Cloud Bongos / Example**
 Prepared 2026-06-28 · task [#1069](https://example.com/builders#/task/1069) · GDS-V4 · track `internal`
 
 ---

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/discord/module.json

@@ -10,5 +10,6 @@
     "uiSections": []
   },
   "provides": ["discord.isLinked"],
-  "consumes": ["ideas.capture"]
+  "consumes": ["ideas.capture"],
+  "dependencies": { "discord.js": "^14.26.4" }
 }