@bongos/core 1.19.101 → 1.19.103

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.101",
-  "core_contract": "1.19.101",
-  "source_commit": "62f06ee2e5d24c140a5dbdbb77c4ecf0b38b51b7",
+  "core_version": "1.19.103",
+  "core_contract": "1.19.103",
+  "source_commit": "4c26152f4ffe43100617e89d904852639f51a9dc",
   "source_ref": "HEAD",
-  "built_at": "2026-08-13T22:58:10.766Z",
+  "built_at": "2026-08-13T23:41:03.246Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 299,
+    "docs_redacted": 301,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1232,
+    "functional_verbatim": 1234,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1552,
-  "tree_sha256": "762cf136042ed2b0ba4bb1ff247411839f0b80cac914bb21d1edf24e8de053b7",
+  "file_count": 1556,
+  "tree_sha256": "b559bea5c153dfcb5b4007dee090a97532674449005645ee1953761712bcf02a",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -342,7 +342,7 @@
     {
       "path": "bin/bongos.js",
       "mode": "0000644",
-      "sha256": "b976a94f0879fd4fe0cdc1eb82209b446cdc7a39186ea1300f4b535bec8f1d00"
+      "sha256": "36208a41a60e3a21356ca9f81abdff9203837ff024b3d15c88a26bee9cce371c"
     },
     {
       "path": "clients/bongos-client/README.md",
@@ -1319,10 +1319,15 @@
       "mode": "0000644",
       "sha256": "8bdad4b4333cbb7b38f66e4dddab08675dfc0a431d21c0be6a31ca4afd8c498f"
     },
+    {
+      "path": "docs/adr/0169-bongos-serve-server-bring-up.md",
+      "mode": "0000644",
+      "sha256": "fe1c4b38b9b3eef60ecd00ecc35eb6086690350a022d2c376d1432c95c9452f7"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "fad8c85a5e99cb222616afcdc2efaa139f3795e1a71f13f9f6fac2cf0bacddef"
+      "sha256": "529d997cf39669fe80bf0fb9a02c546adbb6ba139d4f8dad8de4f59932c47a95"
     },
     {
       "path": "docs/api-reference.md",
@@ -1597,7 +1602,7 @@
     {
       "path": "docs/recipes/instance-deploy.md",
       "mode": "0000644",
-      "sha256": "207d05ae2b1c7ecc78de3f55e4cc7b46d69c99f3ecc39c53708a2d214de95c19"
+      "sha256": "92a10c52ddbda73541b4f5cdad6b3b564d2e3dd9905c9b9fc0a22c3e56aea7b9"
     },
     {
       "path": "docs/recipes/instance-first-run.md",
@@ -1607,7 +1612,7 @@
     {
       "path": "docs/recipes/local-dev.md",
       "mode": "0000644",
-      "sha256": "ae824e62522122efc200ba4fc82bef3baa2ee461c4113798491f1d895567fb69"
+      "sha256": "ac7b71a9dfd550d78355de9e8b758173a5917ecdb1567599a33b16e9d112bc62"
     },
     {
       "path": "docs/recipes/managed-settings-remote-control.md",
@@ -1664,6 +1669,11 @@
       "mode": "0000644",
       "sha256": "a44bb6dcf12bac7e104eab82862e8c0a690376652466c898cd1ab6f8e0e9c270"
     },
+    {
+      "path": "docs/recipes/server-bring-up.md",
+      "mode": "0000644",
+      "sha256": "e5f9e1a9f2337e80ed4ff94d60c96941f50ff30339a35585458dfd8de6e66c5f"
+    },
     {
       "path": "docs/recipes/ship-and-regrade.md",
       "mode": "0000644",
@@ -3744,6 +3754,11 @@
       "mode": "0000644",
       "sha256": "b6eea95dbe66a3126fc2c73d93237cf38dd648a803e910eb88fbd5c780ccef62"
     },
+    {
+      "path": "modules/platform-identity/project-stats.js",
+      "mode": "0000644",
+      "sha256": "6ce71a9bd387a2b79d4c57a6669f028a807ef88ff205f65c20c55ce3d9889214"
+    },
     {
       "path": "modules/platform-identity/routes/my-projects.js",
       "mode": "0000644",
@@ -3752,7 +3767,7 @@
     {
       "path": "modules/platform-identity/routes/projects.js",
       "mode": "0000644",
-      "sha256": "33acce5b2f0c9ea9aef4a0d38f5245e56be4cd2756bc1d49129d5fadeb56a4a1"
+      "sha256": "188583ffb979d305c57a8f0958806ee0bd813007df158d74e45a0d415a3ff6aa"
     },
     {
       "path": "modules/platform-identity/routes/scouting.js",
@@ -4132,12 +4147,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "7aff3b60525970c3f3ec5885ab9ae86e16b6c6077fd391b07cf51e158deb0d3d"
+      "sha256": "b3854f65fe8ad4aead3d08a87f9f2200d87e2b049aed77f7849d51f9aa6f6e5b"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "04d5102541482cca6a1778c951322202056ca81771075fcf0c87d5eeda27c122"
+      "sha256": "7467e0451b4fd162c287c7a5eceee8da746785a3da989bda154830ead5728f3d"
     },
     {
       "path": "public-docs/index.html",
@@ -4377,7 +4392,7 @@
     {
       "path": "public-landing/assets/cosmos.css",
       "mode": "0000644",
-      "sha256": "1fdc2c4e3d58ae089a71bade6aa3f5f3259447b243eacdc75b8a91797ea065e7"
+      "sha256": "3ae9d1edc18eef49ebdf90d0c20c00defda76bfb393936c4a615720314a2886e"
     },
     {
       "path": "public-landing/buddha.png",
@@ -4397,7 +4412,7 @@
     {
       "path": "public-landing/projects.html",
       "mode": "0000644",
-      "sha256": "081e903fcb943e4facda8e83c9247a31602bf7750d5d7740353c97a4ccbcf1e2"
+      "sha256": "f70211d0d2bfe21fa7000ab82d0adcaa97df1f28763e366965da2b92847b31b6"
     },
     {
       "path": "public-landing/world/assets/clouds/cloud-island-large.png",
@@ -4697,12 +4712,12 @@
     {
       "path": "scripts/gds/dev-lib.js",
       "mode": "0000644",
-      "sha256": "b0978faa2f77b123eee002f649b11f139cea948ce8189d20b07d9cf73011ce37"
+      "sha256": "b6c3cf99b050644088507fd5365ced7db5a1c05178ce850e3d28ac7fab9d9476"
     },
     {
       "path": "scripts/gds/dev.js",
       "mode": "0000644",
-      "sha256": "7600e581106b99535b055898f965693554813e8112eb701c4a018627fa867925"
+      "sha256": "79effdf07519d26153f6fe846fd052cd4a37fa1e25b6b1a278146c9d8bcf6766"
     },
     {
       "path": "scripts/gds/diagnose-achievements.js",
@@ -5707,7 +5722,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "6ef2c5bf4063d7d8511e9bd14e83cfd36057a4c01fe1f77f31bd159f9ea08e8a"
+      "sha256": "18be8d4886ea03a65a0cd5d817c811ca0496ea509df5716f416d985a5d682b84"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -5972,7 +5987,7 @@
     {
       "path": "tests/bongos_cli.mjs",
       "mode": "0000644",
-      "sha256": "e017ee497f5aaf041cf18d8bc2b12faed4e3cd71418e14d55eee630ebb4282d3"
+      "sha256": "20d7d86da8e03ede2004bdc3dda589670977fca0240d56cd3677fc08fbb2de03"
     },
     {
       "path": "tests/bongos_dispatch.mjs",
@@ -6302,7 +6317,7 @@
     {
       "path": "tests/dev_lib.mjs",
       "mode": "0000644",
-      "sha256": "eaa112b0b6765a01ec18dfee3bad7c6f6d16e59c0b8c497b82fab0de3a2f2d20"
+      "sha256": "a4611e9a8aa7ff2e1dbd1c91e84496e55cd6b07ece2f73bd62e152c118b94348"
     },
     {
       "path": "tests/devbox_artifact_gate.mjs",
@@ -7224,10 +7239,15 @@
       "mode": "0000644",
       "sha256": "dc354f082204073409aea90df9b91f149d474c6930b761ed5c9928bb76e1358f"
     },
+    {
+      "path": "tests/project_stats.mjs",
+      "mode": "0000644",
+      "sha256": "21bd2a2d0ebb234cd3b9770d126e77ce48f5c630fe7deee2585706d4eb072b53"
+    },
     {
       "path": "tests/projects_hub.mjs",
       "mode": "0000644",
-      "sha256": "6a59da0cfbf5d2be741ed26f3350a39d49a64b6f1dffb89f69666af7ba938dd1"
+      "sha256": "d8fd9759b99b2136f8b438727b74b15346db7cbd8f0ef8b67aec3049f059df2b"
     },
     {
       "path": "tests/provision.mjs",

package/bin/bongos.js

@@ -91,6 +91,9 @@ const VERBS = {
 
   init:    { script: 'init.js', group: 'instance', summary: 'Scaffold a new instance (config + first version + kickoff tasks)' },
   dev:     { script: 'dev.js', group: 'instance', summary: 'Run THIS instance locally in one command (Postgres + migrate + server + sign-in)', selfHelp: true },
+  // Same script, same boot path, --server pinned on: a real host supervises with
+  // systemd, binds per the public origin, and never opens a browser (task 1002398).
+  serve:   { script: 'dev.js', prefixArgs: ['--server'], group: 'instance', summary: 'Run THIS instance on a REAL HOST (systemd service + health check)', selfHelp: true },
   onboard: { script: 'onboard.js', group: 'instance', summary: 'Guided zero-to-live walkthrough: init → scaffold → provision → OAuth → verify → brand' },
   module:  { script: 'module.js', group: 'instance', summary: 'Scaffold a new module  (bongos module new <key>)', selfHelp: true },
   upgrade: { script: 'upgrade.js', group: 'instance', summary: 'Pull the core to a new version (bump pin→install→migrate→materialize→restart); bare = module-compat pre-check', selfHelp: true },

package/docs/adr/0169-bongos-serve-server-bring-up.md

@@ -0,0 +1,52 @@
+# 0169 — `bongos serve`: the `bongos dev` boot path, on a real host
+
+- **Status:** Accepted
+- **Date:** 2026-08-13
+- **Task:** [#1002398](https://cloudbongos.com/builders#/task/1002398) (goal 1000052 — first-run onboarding), depends on [#1002397](https://cloudbongos.com/builders#/task/1002397).
+- **Extends:** [ADR 0149](<redacted>.md) (`bongos dev`, the local launcher). Sibling of [ADR 0108 §4](<redacted>.md) / [`instance-deploy.md`](../recipes/instance-deploy.md) (the *pinned-core consumer* deploy) and `provision.js` (the *control-plane* cloud path).
+
+## Context
+
+ADR 0149 shipped `bongos dev`: one idempotent command that stands an instance up **on the owner's laptop**. The obvious next question — "great, now put it on a server" — had no equally good answer:
+
+| Path to a real host | Why it didn't close the gap |
+|---|---|
+| Docker ([`self-host.md`](../recipes/self-host.md)) | serves the **vanilla** brand on `:3000`; matching the repo's brand + port needs a compose override |
+| `bongos onboard` → `provision.js` | provisions a **whole droplet** through the control plane — needs a public domain plus DigitalOcean/Cloudflare tokens |
+| [`instance-deploy.md`](../recipes/instance-deploy.md) | describes the right shape, but the systemd unit is a **hand-written prose step** ("create a systemd unit for the instance…") — no script in the core writes one |
+
+So an owner with a plain VPS — the most ordinary hosting story there is — was back to hand-assembly, and hand-assembly is where ADR 0149's three silent mismatches (port, DB name, socket) came from in the first place.
+
+The boot path itself is *already right* for a server: deps → Postgres → createdb → migrate → env → server → health is exactly what a host needs. Only four **decisions inside it** are laptop-shaped.
+
+## Decision
+
+Ship **`bongos serve`** — the same script, the same six steps, with `--server` pinned on (`bongos dev --server` is the same thing). Not a second boot path: a **mode** on the existing one, so the two can't drift.
+
+Four decisions change, each derived rather than asked:
+
+1. **Supervision — a systemd unit, not a pid file.** The laptop's detached-with-a-pid-file process is right for a laptop and wrong for a host: it dies on reboot, has no restart policy, and logs to `/tmp`. Server mode writes `/etc/systemd/system/bongos-<db>.service` (`Restart=always`, `WantedBy=multi-user.target`), `daemon-reload`s, and `enable --now`s it — so the host's own supervisor owns the process. Where systemd is absent (a container, a BSD, an operator without root) it **falls back** to the pid-managed process with a loud warning rather than refusing.
+2. **Bind address — derived from the origin.** `https://…` means something already terminates TLS in front of us, so bind `127.0.0.1`; plain `http://` on a public hostname means nothing is in front yet, so bind `0.0.0.0`. `--bind` (or `HOST`) still wins. An operator never has to reason about it, and the common misconfiguration — an app bound to `0.0.0.0` behind a proxy, publicly reachable on its raw port — can't happen by default.
+3. **A fresh Postgres cluster gets bootstrapped.** `apt-get install postgresql` creates exactly one role — `postgres`, peer-auth only — so a deploy user's `createdb` fails with `role "deploy" does not exist`. That reads like a broken install and is really an unbootstrapped cluster. On that specific error we create the login role + its database as the postgres superuser (`sudo -u postgres`, or `su postgres -c` for root on a sudo-less image). This is the fresh-Debian wall, and it is the one step most likely to end a first server run.
+4. **Health means the *public* origin, not loopback.** The loopback probe proves the app; on a host the interesting failures are DNS, the proxy, and TLS — all of which sit outside it. Server mode probes `publicOrigin/healthz` too and, when it can't be reached, says which layer is missing. It is **advisory**: DNS legitimately may not be wired yet, so this warns and still exits 0.
+
+Plus: no auto-login (a host has no browser — it prints `bongos login <origin>` instead).
+
+**Secrets go to an `EnvironmentFile`, never `Environment=`.** The unit carries only the eight keys the boot path resolves; `PGPASSWORD` and the GitHub OAuth creds go to a root-owned `0600` `/etc/bongos/<service>.env`, created once and never overwritten. Two reasons: `systemctl show` exposes `Environment=` to any user on the box, and the laptop path's `buildEnv()` spreads the *caller's whole environment* — baking a builder's shell (tokens included) into a root-owned file. `unitEnvironment()` is a deliberately separate, allowlisted function for exactly that reason.
+
+As with ADR 0149, every decision above is a **pure, injectable function** in `dev-lib.js` (`deriveBindHost`, `systemdPlan`, `pgStartPlan`, `pgBootstrapPlan`, `renderSystemdUnit`, `unitEnvironment`, `parseSub`); `dev.js` only executes them. `tests/dev_lib.mjs` proves all of it with no host, no spawn, and no network.
+
+## Alternatives considered
+
+- **A separate `deploy.sh`** — would have duplicated the boot path, which is precisely how the laptop and server paths would drift. Rejected: the whole value is that it's the *same* six steps.
+- **Docker on the host** — real, and still the right answer for a container platform, but it makes the instance's own brand/port a compose-override exercise and puts a container runtime between an owner and a $5 VPS. Kept as the parallel path.
+- **Always bind `0.0.0.0`** — simpler to explain, but publishes the raw app port on every host that has a proxy in front. Rejected on that alone.
+- **Refuse without systemd** — cleaner contract, but would fail on containers and BSDs where the pid-managed fallback works fine. Rejected in favour of a warning.
+
+## Consequences
+
+- A plain VPS goes from `git clone` to a supervised, reboot-surviving instance with `npm install` then `bongos serve` — the same two commands as the laptop.
+- `bongos serve stop` **stops and disables** the unit, so "stopped" survives a reboot; `bongos serve` re-enables it. Asymmetric with `bongos dev stop` (which only kills a process) because on a host the two verbs mean different things.
+- The unit is a *starting point*, not a hardened production profile — no `ProtectSystem`, no resource limits, no log shipping. An operator with opinions should edit it; a re-run rewrites it, so persistent customisation belongs in a systemd drop-in (`/etc/systemd/system/bongos-<db>.service.d/`).
+- TLS/proxy/DNS stay **out of scope** — deliberately. Those are the host's business and vary per operator; `bongos serve` tells you when they're the missing piece and points at [`server-bring-up.md`](../recipes/server-bring-up.md).
+- Windows is still not a native path (migrations need `bash`), unchanged from ADR 0149.

package/docs/adr/README.md

@@ -242,5 +242,6 @@ This keeps the decision history honest and traceable.
 | 0167 | [**The module catalog: `source` (which tree ships it) and `provenance` (who built it) are two axes** ([task 1001772](https://cloudbongos.com/builders#/task/1001772) — the last task of goal 1000029). Closes [ADR 0107](<redacted>.md) §2/§3: a browsable catalog of enable-able core modules, each with author + origin credit, in the hall AND via `bongos module list --catalog`. The bug it fixes: the Modules tab derived its own/core-loaded split from the manifest's `origin` alone, but attribution is OPTIONAL and core's own modules declare none (nothing upstreamed them) — so on a split instance every core module read as *built here* and the catalog you could opt into read as empty. One field was answering two questions. Fix: a shared model (`src/module-loader/catalog.js`) that both the hall route and the CLI build from, carrying `source` — read STRUCTURALLY from the loader's discovery root ([ADR 0108](<redacted>.md) §1: core package vs instance tree), falling back on coincident roots to whether `package.json` names the core — beside the unchanged `provenance` credit axis. Plus `credit: {author, origin, inferred}`, which fills a core module's blank attribution with the platform name and MARKS it inferred (`*` in the CLI, a hoverable `<abbr>` in the hall) so it never reads as a claim the author typed. The tab now sections by `source` ("Module catalog" / "Built by this project"), gains a search box, and draws "Submit for review" from instance-source modules only. Rejected: stamping author/origin into 15 core manifests (repetitive, and module 16 forgets), overloading `origin` (destroys the credit axis), inferring from `default:true` (§6 makes accepted catalog modules default-OFF — exactly backwards), a DB catalog table (premature; the manifests already are the catalog).](<redacted>.md) | modules / upstreaming |
 | 0168 | [**The scaffold vendors the hub's RUNNING core (`npm pack` of the installed package); registry-default deferred to the go-public step** ([task 1002706](https://cloudbongos.com/builders#/task/1002706); gap 13 of the project-creation audit). Two collided facts: children were born pinned to a frozen `file:vendor/bongos-core-1.19.2.tgz` (installedCoreTarball reuses the hub's own file: pin — task 1002275 — and the hub's pin sat at 1.19.2), and the task-1002621 registry cutover (hub pin now `"@bongos/core": "1.19.56"`, verified on the box) made installedCoreTarball return null — dropping the scaffold into the package-core.js source rebuild that ABORTS on a consumer instance (empty core set → empty child repo, the 1002275 failure resurrected). Fix: a three-rung ladder — file:-pin reuse → NEW `installedCorePackDir()` + `npm pack` of the hub's installed core (child pins the SAME, CURRENT core, stays file:-pinned, owner needs no token) → source rebuild. The brief's "make registry the default now that the package is public" was verified FALSE (both npm scopes 404 anonymously; ADR 0134 keeps them private until go-public) — a registry-default child would be born UNINSTALLABLE for a tokenless owner. Registry-default is deferred to the go-public step (idea 1000700); the gap-13 "flip the box env" ops leg is explicitly a no-op until then; child freshness rides this ladder + the hub-pin lane (task 1002708). Rejected: registry-default now, dropping NPM_TOKEN, vendoring from the npm cacache.](<redacted>.md) | provisioning / distribution |
 | 0167 | [**The /create gate trust link defaults to the AGPL-3.0 license text, not the npm package page** ([task 1002705](https://cloudbongos.com/builders#/task/1002705); gap 1 of the project-creation audit). The gate's "open source" link pointed at a nonexistent repo (404); the task brief's suggested default — the npm package page — is ALSO dead for the gate's actual audience (signed-out visitors): `@cloudbongos/core` and `@bongos/core` both 404 anonymously (private scopes, ADR 0134), and the ADR 0099 public mirror stays dormant until ~2026-11. The license text is the one live, instance-neutral artifact behind the claim today. The browsable-code upgrade is the owner's filed choice (idea 1000700): public repo now (forfeits the ADR 0065 §4 redaction window) / public npm package / wait for the mirror. Rejected: the npm link (verified dead), flipping the repo public (not a builder's call), plain unlinked text (less information, same cost).](<redacted>.md) | public landing / governance |
+| 0169 | [**`bongos serve`: the `bongos dev` boot path, on a real host** ([task 1002398](https://cloudbongos.com/builders#/task/1002398), goal 1000052). [ADR 0149](<redacted>.md) gave an owner one command to stand an instance up on their laptop; "now put it on a server" had no equally good answer — Docker serves the *vanilla* brand on `:3000`, `bongos onboard` provisions a whole droplet through the control plane, and [`instance-deploy.md`](../recipes/instance-deploy.md) left the systemd unit as a hand-written prose step. The six steps (deps → Postgres → createdb → migrate → env → server → health) were already right for a host; only four *decisions inside them* were laptop-shaped. So: a `--server` **mode** on the same script (`bongos serve`), never a second boot path, so the two can't drift. (1) **Supervision** — a systemd unit (`Restart=always`, `WantedBy=multi-user.target`) instead of a pid file that dies on reboot, falling back to the pid-managed process where systemd is absent rather than refusing. (2) **Bind address, derived from the origin** — `https://…` means a proxy terminates TLS, so bind `127.0.0.1`; plain `http://` on a public host means nothing is in front, so bind `0.0.0.0`. The common misconfiguration (app publicly reachable on its raw port behind a proxy) becomes impossible by default. (3) **Peer-auth bootstrap** — a fresh `apt-get install postgresql` cluster has only the `postgres` role, so a deploy user's `createdb` fails with `role "deploy" does not exist`; that reads like a broken install and is really an unbootstrapped cluster, so we create the login role as the superuser. (4) **Health means the PUBLIC origin** — the loopback probe proves the app; DNS/proxy/TLS are where a host actually fails, so it probes the advertised origin too and names the missing layer (advisory — DNS may legitimately not be wired). Secrets go to a root-owned `0600` `EnvironmentFile`, never `Environment=` (`systemctl show` leaks those, and the laptop path's `buildEnv()` spreads the caller's whole shell). Every decision is a pure injectable in `dev-lib.js`, proved in `tests/dev_lib.mjs` with no host. Rejected: a separate `deploy.sh` (drift — the point is the *same* six steps), Docker-on-the-host (makes brand+port a compose override), always binding `0.0.0.0` (exposes the raw port), refusing without systemd (breaks containers/BSD).](<redacted>.md) | onboarding / deploy |
 
 > ⚠️ **Numbering collision (known):** two ADRs share `0008`. The numbers were assigned in parallel sessions before the lock could be enforced. The files are kept under their existing filenames to preserve git history, but the table disambiguates them as `0008-a` / `0008-b`. New ADRs should resume at `0040` to avoid further collisions. (`0024` is also a real on-disk duplicate: the cloneable-repo/local-first-memory ADR and the multi-agent-system-architecture ADR were both numbered `0024` in parallel; both keep their filenames, disambiguated as `0024-a` / `0024-b` like `0008`. Likewise `0025` ended up with two on-disk files — the offsite-backup ADR and the structured-criterion↔task-link ADR — both kept under their existing filenames and disambiguated as `0025-a` / `0025-b`; separately, the BFG ADR had also claimed `0025` on 2026-05-30 and yielded to `0026`. A third happened 2026-06-06: `0036` was claimed in parallel by the builders-subdomain ADR ([#726](https://example.com/builders#/task/726)) and this Discord-channels ADR ([#727](https://example.com/builders#/task/727)); the Discord-channels ADR yielded to `0037`. A fourth landed 2026-06-10: `0044` was claimed in parallel by the palette-replacement ADR and the per-box game-preview ADR ([#897](https://example.com/builders#/task/897)); both keep their filenames, disambiguated as `0044-a` / `0044-b` like `0008`. A fifth was caught pre-land 2026-06-13: `0050` was claimed in parallel by the device-flow-admission ADR ([#1000](https://example.com/builders#/task/1000)) and the sandbox-for-everyone ADR ([#1001](https://example.com/builders#/task/1001)); the latter yielded to `0052` before merging, so there is no `0050` duplicate. A sixth was caught pre-land 2026-06-21: the tool-agnostic-design-layer ADR ([#1375](https://example.com/builders#/task/1375)) first collided at `0079` with the value-gated-autonomous-engagement ADR, then at `0080` with the llm-cache-api-transport ADR (both part of the 0075–0080 LLM-cost-reduction series, landed on `main` in parallel); it yielded to `0081` before merging, so there is no `0079`/`0080` design-layer duplicate. A seventh landed 2026-06-23: `0084` was claimed in parallel by the auto-derived-per-task-rank-floor ADR and the remove-default-spend-cap ADR (task 1499); the rank-floor ADR landed on `main` first, so the spend-cap ADR yielded to `0085`, leaving no `0084` duplicate. An eighth landed 2026-06-27: `0095` was claimed in parallel by the borrowed-memory-and-retrieval-concepts ADR (PR #459, landed first) and the cross-agent-context-management ADR ([#1651](https://example.com/builders#/task/1651), PR #460); both keep their filenames, disambiguated as `0095-a` / `0095-b` like `0008`. These two are companions — `0095-a` adopts the memory/retrieval concepts and explicitly defers the grep-vs-semantic question to `0095-b`.)

package/docs/recipes/instance-deploy.md

@@ -33,5 +33,6 @@
 
 1. Install the script as the droplet's `~/deploy.sh` (the CI deploy key is forced-command-locked to `~/deploy.sh` — ADR 0043 — so it stays hand-installed, like `deploy-prod.sh`).
 2. Create a systemd unit for the instance: `ExecStart=/usr/bin/node <instanceRoot>/node_modules/@bongos/core/src/platform-server.js`, `WorkingDirectory=<instanceRoot>`, `Environment=PORT=… HOST=127.0.0.1 <PREFIX>_INSTANCE_ROOT=<instanceRoot>`.
+   **`bongos serve` now writes exactly this unit for you** (plus the DB/migrate/health legs) — see [`server-bring-up.md`](server-bring-up.md) / [ADR 0169](../adr/<redacted>.md). Step 4 of the flow above ("restart the platform") is `systemctl restart bongos-<db>` once it has.
 3. Set `INSTANCE_SERVICE=<unit>` + `PORT=<port>` in the deploy environment.
 4. Front it with TLS and point the origins at the real domain (see [self-host.md](self-host.md)).

package/docs/recipes/local-dev.md

@@ -79,3 +79,6 @@ the Client ID + secret to `~/.config/<configDir>/gds-github.json` as
   servers don't collide.
 - **Prefer the cloud?** `bongos box` + `bongos code` give you a remote dev box instead — no
   local database or server to run.
+- **Ready for a real host?** `bongos serve` runs this *same* boot path on a server —
+  systemd-supervised, bind address derived from your public origin, no browser needed. See
+  [`server-bring-up.md`](server-bring-up.md) ([ADR 0169](../adr/<redacted>.md)).

package/docs/recipes/server-bring-up.md

@@ -0,0 +1,112 @@
+# Recipe — putting your instance on a real host (`bongos serve`)
+
+> [ADR 0169](../adr/<redacted>.md), task [#1002398](https://cloudbongos.com/builders#/task/1002398). The server half of [`local-dev.md`](local-dev.md) / [ADR 0149](../adr/<redacted>.md): the **same** boot path `bongos dev` runs on your laptop, on a VPS.
+
+## The short version
+
+On the host, in your instance's checkout:
+
+```bash
+npm install
+bongos serve
+```
+
+That's it. It is idempotent — re-run it after every `git pull`.
+
+## What you need first
+
+- A Linux host (Debian/Ubuntu assumed below) with **Node ≥ 22**, **Postgres**, and **bash**.
+- Your instance repo cloned on it, with `config/branding.json` pointing `domains.publicOrigin` at the origin you'll actually serve.
+- Either root, or a user with **passwordless sudo** — `bongos serve` uses `sudo -n` so it fails fast instead of hanging a deploy on a hidden password prompt. Without it, run `sudo bongos serve`.
+
+```bash
+sudo apt-get install -y postgresql   # provides psql/createdb/pg_isready too
+```
+
+## What it does
+
+The six steps from `bongos dev`, with the four host-shaped decisions made for you (ADR 0169):
+
+1. **Dependencies** — `npm ci` (or `npm install`) if this checkout has none.
+2. **Postgres running** — `systemctl start postgresql`, falling back to `service` then `pg_ctl`, then polls until it accepts connections.
+3. **Database + role** — creates the DB, and on a fresh cluster creates your **login role** first. See the peer-auth note below; this is the step most first server runs die on.
+4. **Migrations** — the core `migrate.sh`, with `PGDATABASE` exported for both it and the server (the ADR 0149 mismatch).
+5. **The server, supervised by systemd** — writes `/etc/systemd/system/bongos-<db>.service`, enables it (survives reboot) and starts it (`Restart=always`).
+6. **Health** — on the bind address, *and* on your public origin.
+
+## Where things land
+
+| Thing | Path |
+|---|---|
+| systemd unit | `/etc/systemd/system/bongos-<db>.service` |
+| secrets (0600, root-owned) | `/etc/bongos/bongos-<db>.env` |
+| logs | `journalctl -u bongos-<db> -f` |
+
+```bash
+bongos serve status    # service state, health, and whether the public origin answers
+bongos serve stop      # stop AND disable (stays down across a reboot)
+bongos serve           # re-enables and restarts
+```
+
+## The bind address is derived — don't fight it
+
+`bongos serve` reads `domains.publicOrigin` and picks:
+
+| Your `publicOrigin` | It binds | Because |
+|---|---|---|
+| `https://app.example.com` | `127.0.0.1` | something terminates TLS in front — the proxy reaches you on loopback |
+| `http://app.example.com:3006` | `0.0.0.0` | nothing is in front yet — you're serving it directly |
+| `http://localhost:3006` | `127.0.0.1` | a local-shaped origin |
+
+Override with `--bind <addr>` if your topology is unusual. **The `https` case is the one to get right**: set your origin to `https://…` *before* the first `bongos serve`, and the app is never publicly exposed on its raw port.
+
+## The fresh-Postgres wall (peer auth)
+
+A brand-new `apt-get install postgresql` cluster has exactly **one** role — `postgres` — reachable only by peer auth as the `postgres` OS user. So your deploy user's `createdb` fails with:
+
+```
+createdb: error: ... role "deploy" does not exist
+```
+
+That reads like a broken Postgres and is really an unbootstrapped one. `bongos serve` detects this specific failure and fixes it — `CREATE ROLE "deploy" LOGIN CREATEDB` plus the database, run as the postgres superuser. If it can't (no root, no sudo), it says so; the manual equivalent is:
+
+```bash
+sudo -u postgres psql -c 'CREATE ROLE "deploy" LOGIN CREATEDB'
+sudo -u postgres createdb -O deploy <dbname>
+```
+
+## Sign-in on a host
+
+There's no browser on a server, so `bongos serve` never auto-signs-in. It prints the command to run **from your own machine**:
+
+```bash
+bongos login https://app.example.com
+```
+
+If sign-in isn't configured yet, it walks you through the GitHub OAuth app and tells you to put the credentials in `/etc/bongos/bongos-<db>.env` (not `~/.config` — the service runs as its own user, often with an empty home), then `systemctl restart bongos-<db>`.
+
+## "The app is healthy but my origin isn't answering"
+
+Expected, and `bongos serve` says which layer is missing. It proves the app on the bind address; DNS, the reverse proxy, and TLS are yours:
+
+- **Bound to `127.0.0.1`** — you need a proxy forwarding your origin to `127.0.0.1:<port>`. Any of Caddy (easiest — automatic TLS), nginx + certbot, or Cloudflare Tunnel.
+- **Bound to `0.0.0.0`** — you need DNS pointing at this host and the port open in the firewall (`ufw allow <port>`).
+
+## Customising the unit
+
+A re-run **rewrites** the unit, so don't hand-edit it. Use a systemd drop-in, which survives:
+
+```bash
+sudo systemctl edit bongos-<db>      # writes /etc/systemd/system/bongos-<db>.service.d/override.conf
+```
+
+The shipped unit is a sound starting point, not a hardened production profile — no `ProtectSystem`, no resource limits, no log shipping. Add what your threat model wants there.
+
+## Relation to the other deploy paths
+
+| Path | When |
+|---|---|
+| **`bongos serve`** (this) | you have a host and want your instance on it |
+| [`instance-deploy.md`](instance-deploy.md) | a consumer instance on a **pinned core** — `git pull` → `npm ci` → migrate → restart (this is the restart it's describing) |
+| [`self-host.md`](self-host.md) | Docker/container platforms |
+| `bongos onboard` | you have **no** host yet and want the control plane to provision one |

package/modules/platform-identity/project-stats.js

@@ -0,0 +1,207 @@
+// modules/platform-identity/project-stats.js — real Builders + Tags for the hub
+// catalog, read from each project's OWN public API (task 1002771).
+//
+// WHY THE DATA IS NOT HERE. The apex catalog stores four fields (origin, name,
+// tagline, art_url) and nothing else; the membership and activity tables that
+// would know a builder count are written only by the federated check-in a hosted
+// instance posts on sign-in, so they hold one row across the whole platform and
+// would report ZERO for every hand-wired project (task 1002760 documents why).
+// Zero is not an absence — it is the claim "nobody builds here" — so task 1002764
+// removed the columns rather than show a wrong number.
+//
+// But every Cloud Bongos instance already serves an unauthenticated
+// /api/bongos/public/* surface, and the hub's server can read it instance-to-
+// instance with no CORS involved. The project itself is the authority on its own
+// builder count, which is a better source than anything the apex could infer.
+//
+// SCALE, recorded so it is not rediscovered: this PULL model is right for a
+// handful and fine for a few dozen behind the cache. It does not scale to
+// hundreds — at that point instances should PUSH these stats on check-in, which
+// is the shape platform_identity_builder_project_activity already has. Swapping
+// pull for push must not change the column, which is why the route depends on
+// getProjectStats() and not on fetch().
+
+const fs = require('node:fs');
+const path = require('node:path');
+const dns = require('node:dns').promises;
+const net = require('node:net');
+
+const TTL_MS = 10 * 60 * 1000;   // owner's choice, 2026-08-13
+const FETCH_TIMEOUT_MS = 2500;   // per request
+const COLD_DEADLINE_MS = 3000;   // total wait a COLD cache may cost a page load
+
+const _cache = new Map();        // origin → { at, stats }
+const _inflight = new Map();     // origin → Promise (collapses concurrent refreshes)
+
+// The core's own modules/ directory IS the canonical core set — so a module the
+// core adds later is excluded automatically and nobody maintains a list. Anything
+// an instance runs beyond it is project-specific, and that is what a tag is.
+let _coreModules = null;
+function coreModules() {
+  if (_coreModules) return _coreModules;
+  try {
+    _coreModules = new Set(
+      fs.readdirSync(path.join(__dirname, '..'), { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name),
+    );
+  } catch {
+    _coreModules = new Set();
+  }
+  return _coreModules;
+}
+
+// Machine identities, not people. Counting them inflates every project: the raw
+// leaderboards read 13/3/3 against real 11/1/1, so this filter is the difference
+// between a true number and a wrong one.
+function isSystemAccount(login) {
+  return /-system$/.test(String(login || ''));
+}
+
+// ── SSRF GUARD ──
+// This is the one place the server makes an outbound request to an address that
+// came out of the database, so it is the one place that has to assume the address
+// is hostile. "The catalog is Archon-curated" is a real mitigation but not a
+// sufficient one, for a specific reason: a curated origin is trusted, and a
+// REDIRECT TARGET is not. Following redirects hands the choice of final address
+// back to the remote server, which is the whole SSRF primitive — a listed project
+// could 302 us at 169.254.169.254 (cloud metadata) or a loopback admin port.
+//
+// So: redirects are refused outright rather than followed (a public JSON endpoint
+// has no reason to redirect), and the hostname must resolve to a PUBLIC address.
+//
+// Known and accepted limit: resolving here and connecting in fetch() is a
+// TOCTOU window — a DNS record could change between the two. Closing it properly
+// means pinning the resolved IP into the connection, which needs a custom agent.
+// Refusing redirects removes the attacker-steerable half, which is the half that
+// matters; the residual requires control of DNS for a curated origin.
+const BLOCKED_V4 = [
+  [/^10\./, 'private'], [/^127\./, 'loopback'], [/^0\./, 'unspecified'],
+  [/^169\.254\./, 'link-local / cloud metadata'], [/^192\.168\./, 'private'],
+  [/^172\.(1[6-9]|2\d|3[01])\./, 'private'], [/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./, 'CGNAT'],
+  [/^(22[4-9]|23\d)\./, 'multicast'], [/^(24\d|25[0-5])\./, 'reserved'],
+];
+function blockedReason(addr) {
+  const ip = String(addr).replace(/^::ffff:/i, '');   // unwrap IPv4-mapped IPv6
+  if (net.isIPv4(ip)) {
+    for (const [re, why] of BLOCKED_V4) if (re.test(ip)) return why;
+    return null;
+  }
+  const v6 = ip.toLowerCase();
+  if (v6 === '::1' || v6 === '::') return 'loopback';
+  if (/^f[cd]/.test(v6)) return 'unique-local';
+  if (/^fe[89ab]/.test(v6)) return 'link-local';
+  return null;
+}
+
+async function assertPublicHost(hostname) {
+  // a literal IP needs no lookup — check it directly
+  if (net.isIP(hostname)) {
+    const why = blockedReason(hostname);
+    if (why) throw new Error(`refused ${hostname} (${why})`);
+    return;
+  }
+  const addrs = await dns.lookup(hostname, { all: true });
+  if (!addrs.length) throw new Error(`no address for ${hostname}`);
+  for (const { address } of addrs) {
+    const why = blockedReason(address);
+    if (why) throw new Error(`refused ${hostname} → ${address} (${why})`);
+  }
+}
+
+function publicUrl(origin, route) {
+  const u = new URL(origin);
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') throw new Error('bad scheme');
+  return new URL(`/api/bongos/public/${route}`, u).href;
+}
+
+async function getJson(url) {
+  await assertPublicHost(new URL(url).hostname);
+  const res = await fetch(url, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    headers: { accept: 'application/json' },
+    redirect: 'error',   // never let the remote choose our final address
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.json();
+}
+
+// One project's stats. Either half may fail on its own — a project whose
+// leaderboard is down can still report its modules — so they settle independently
+// and a missing half is null (an em dash) rather than a discarded pair.
+async function fetchStats(origin) {
+  const [lb, mods] = await Promise.allSettled([
+    getJson(publicUrl(origin, 'leaderboard')),
+    getJson(publicUrl(origin, 'modules')),
+  ]);
+
+  let builders = null;
+  if (lb.status === 'fulfilled' && Array.isArray(lb.value?.leaderboard)) {
+    builders = lb.value.leaderboard.filter((b) => !isSystemAccount(b?.github_login)).length;
+  }
+
+  let tags = null;
+  if (mods.status === 'fulfilled' && mods.value?.enabled && typeof mods.value.enabled === 'object') {
+    const core = coreModules();
+    tags = Object.entries(mods.value.enabled)
+      .filter(([key, on]) => on === true && !core.has(key))
+      .map(([key]) => key)
+      .sort();
+  }
+
+  return { builders, tags };
+}
+
+function refresh(origin) {
+  if (_inflight.has(origin)) return _inflight.get(origin);
+  const p = fetchStats(origin)
+    .then((stats) => {
+      _cache.set(origin, { at: Date.now(), stats });
+      return stats;
+    })
+    .catch(() => {
+      // Remember the FAILURE for a full TTL too. Without this a permanently
+      // unreachable project is re-fetched on every request and pays the timeout
+      // every time — the exact way one dead project slows the whole page.
+      const stats = { builders: null, tags: null };
+      _cache.set(origin, { at: Date.now(), stats });
+      return stats;
+    })
+    .finally(() => _inflight.delete(origin));
+  _inflight.set(origin, p);
+  return p;
+}
+
+// Stale-while-revalidate: a warm cache answers instantly, a STALE cache answers
+// instantly and refreshes behind the request, and only a COLD cache waits — and
+// then only until COLD_DEADLINE_MS, after which whatever has not arrived renders
+// as a dash and fills itself in on the next load. The hub's speed must never
+// become hostage to the slowest project's uptime.
+async function getProjectStats(origins = []) {
+  const now = Date.now();
+  const cold = [];
+
+  for (const origin of origins) {
+    const hit = _cache.get(origin);
+    if (!hit) cold.push(origin);
+    else if (now - hit.at > TTL_MS) refresh(origin);   // stale: revalidate, do not await
+  }
+
+  if (cold.length) {
+    await Promise.race([
+      Promise.allSettled(cold.map((o) => refresh(o))),
+      new Promise((r) => setTimeout(r, COLD_DEADLINE_MS)),
+    ]);
+  }
+
+  // null-prototype: an origin literally equal to '__proto__' would otherwise
+  // retarget the object's prototype instead of adding a key
+  const out = Object.create(null);
+  for (const origin of origins) out[origin] = _cache.get(origin)?.stats || { builders: null, tags: null };
+  return out;
+}
+
+// tests
+function _reset() { _cache.clear(); _inflight.clear(); _coreModules = null; }
+
+module.exports = { getProjectStats, isSystemAccount, coreModules, blockedReason, assertPublicHost, _reset, TTL_MS };