@bongos/core 1.20.23 → 1.20.25

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.23",
-  "core_contract": "1.20.23",
-  "source_commit": "53e1513a015b5e684c3706c493675c2fd9f890b0",
+  "core_version": "1.20.25",
+  "core_contract": "1.20.25",
+  "source_commit": "c77a95cf8a90470fbccd7a49fe8cadeac1c3d623",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T16:54:47.028Z",
+  "built_at": "2026-09-30T18:59:50.459Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 558,
+    "docs_redacted": 560,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2643,
+    "functional_verbatim": 2645,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3227,
-  "tree_sha256": "be76bb6bac10f8f8e03cbc19031c0a0e2866729e3ee9cfce9bf0b9a0704a0c5d",
+  "file_count": 3231,
+  "tree_sha256": "be259f84dcf01e7c06053ca8c31f196c8f3084f86b1579f55ff9f6aac33e30ad",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2239,10 +2239,15 @@
       "mode": "0000644",
       "sha256": "4445d9c306a22fb3b7e72467bedad262f4653c092bf4866f8a39410248da2724"
     },
+    {
+      "path": "docs/adr/0354-a-builder-hosts-one-project-free-and-more-takes-the-fleet-permission.md",
+      "mode": "0000644",
+      "sha256": "962d868c0887244c53b53c58754f7232715a20df6feec694f30cbda707f9e17e"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "6be10fb1925fd406729e08b4d604569b1123b7c5f6091300559df8532831ab69"
+      "sha256": "850168519d3ef7eaf6d9658b9e2b19a80402147e9f3e8fc5318c53b7647fa9b0"
     },
     {
       "path": "docs/api-reference.md",
@@ -2252,7 +2257,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "f44cf9111baee003af84ab6c83503e97a4a723c4cb2ad59ad367cce75f8f717e"
+      "sha256": "787e1af5323f03257c136d5ef9e15eb58e2cdc6abf8b90ddbc94b479ba1659a4"
     },
     {
       "path": "docs/architecture.md",
@@ -2354,6 +2359,11 @@
       "mode": "0000644",
       "sha256": "dfa1ea2c45eddd5a9528487f3a0fe80398ba9018c5f73706629015ff6c2108e0"
     },
+    {
+      "path": "docs/design/project-startup-direction.md",
+      "mode": "0000644",
+      "sha256": "b7c67956a0fe3c38efc22701741b4e19ba383c942b864d2b37b195619594392f"
+    },
     {
       "path": "docs/design/projects-hub-direction-v2.md",
       "mode": "0000644",
@@ -2782,7 +2792,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "e4970a8a4af13ed70d73aafe8ec6b5c96999a8f23764dd32da86f96d538dfdc6"
+      "sha256": "76eb8564b3b574c106fe2d1616ac7830a4a30a3d0237bf3f4bad78c0d0ecd43c"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2872,7 +2882,7 @@
     {
       "path": "docs/page-readings.json",
       "mode": "0000644",
-      "sha256": "dd7227bb9daface49cfb1e2a8702cb81b95a5d19f0169038ddfd7a6c80e04225"
+      "sha256": "3b5310724bcecee35da76de11b3d6c1a9f3fe404b7c79713ee6d97f3dc09d739"
     },
     {
       "path": "docs/project-context.template.md",
@@ -7269,6 +7279,11 @@
       "mode": "0000644",
       "sha256": "f00a21da3c27933cd34cb66a7d99ef1104eac1180d0655e8fa59e96f9a366ace"
     },
+    {
+      "path": "modules/provisioning/free-place-lock.js",
+      "mode": "0000644",
+      "sha256": "82b9f7ee39820735ca4d0f55b12fd72903b9909d3c9f0abedb684dcc98ac77c6"
+    },
     {
       "path": "modules/provisioning/migrations/provisioning_001_tables.sql",
       "mode": "0000644",
@@ -7422,7 +7437,7 @@
     {
       "path": "modules/provisioning/paid-shape-gate.js",
       "mode": "0000644",
-      "sha256": "7f7f9b1a6ffcf2f58d3a3a7b5d5244a3474f0245274a7bd6777befba36c5fc9c"
+      "sha256": "aad8d8e8a641ebcbff9aeeed765e6c1657fa5896dc9cc3e84aa32f6d327b7db2"
     },
     {
       "path": "modules/provisioning/pollers/app-liveness.js",
@@ -7512,7 +7527,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "18a8a728c48070f99dfdaa1c21d738f8d6fcfe8dc8534574fc115cec77f8bf77"
+      "sha256": "d0a1e16b8ba6cb03bfadf95c7a3b688007309d173812e34b4e69d6e4dc33d21f"
     },
     {
       "path": "modules/provisioning/routes/render-standup.js",
@@ -8067,7 +8082,7 @@
     {
       "path": "modules/public-landing/public/projects.html",
       "mode": "0000644",
-      "sha256": "b2780277742b8f560dc431ce77498ffdefaf1a027ffde893caa472e59da512f3"
+      "sha256": "dc489131cceef3330ea6d3ee0d24c05a723076478496efb46ce8e509381aea03"
     },
     {
       "path": "modules/public-landing/public/projects.probes.json",
@@ -8912,12 +8927,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "417e99397bbe709aa8cd87385188a162f83ee135c12954f2cf92a23a499f7b3f"
+      "sha256": "d966dd1820b8e6c02522cc7b3e839e2b6d306b782417364cefd51641801f74b3"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2cdc66718b40d75fb0046f4b7dc17ae36ac4c18451ab90e86d5a32b93e34bb4c"
+      "sha256": "cbed81083b8dfa0c558b28d5567ff392c575544cfe562b316bc1ed4d533b0bd4"
     },
     {
       "path": "public-docs/index.html",
@@ -8937,7 +8952,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "a37f6b56d6237e71dbb1f2d70cb703acd869f8a0ac5ca8e1d27550b3f8fe1bc1"
+      "sha256": "306aa139c1c83d1276d29c20d9e7c7e26e3073f0175c610f89c27e6a2428ccee"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -11052,7 +11067,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a1d0a3dd719c8550dea1190993a548ea01cad01414e143b32055f18e2cb4e10d"
+      "sha256": "e200ecfa45721d0febc5e7700c7cd212a1d8c486b8c861b5ea6d228b5961275e"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -14467,7 +14482,7 @@
     {
       "path": "tests/project_catalog_routes.mjs",
       "mode": "0000644",
-      "sha256": "90a8283375de41b753c28096ef5c286146322857c10b83124c52748df9ba570d"
+      "sha256": "e19d61fb2734092104276d1f74f1cbdf691bfe4f920414c543a1c07e839725e6"
     },
     {
       "path": "tests/project_door_ui.mjs",
@@ -14552,7 +14567,7 @@
     {
       "path": "tests/projects_hub_pre_uat.mjs",
       "mode": "0000644",
-      "sha256": "c498363abc196c09cfc30b4e69b4cc943dd293ebecb9aa7b4319c92721a82f30"
+      "sha256": "5a2d7c53cf71d22dc7a7f4547c9dc59746002e35330a92c7047e4742c1977073"
     },
     {
       "path": "tests/projects_hub_render_connect.mjs",
@@ -14662,7 +14677,7 @@
     {
       "path": "tests/provisioning_capacity_gate.mjs",
       "mode": "0000644",
-      "sha256": "406ea4d32fe1bbb7aa1f69e0c4dc967feb2fc43c8bf0f70848547fdc6faf8762"
+      "sha256": "478f4e06bd11f64e69efd9482094f262ac29016d052117c6a866cc9f0d55c318"
     },
     {
       "path": "tests/provisioning_cost_ledger.mjs",
@@ -14687,7 +14702,7 @@
     {
       "path": "tests/provisioning_domain_attach.mjs",
       "mode": "0000644",
-      "sha256": "cd0f81de7dd909fb1db27f86be4f541e38ec36f6d76cf97f7e7c759565f9d392"
+      "sha256": "160acd275e3b466088ee5913186d430e974973a4e3eee51f3d62d8604a8fd64f"
     },
     {
       "path": "tests/provisioning_domain_lookup_index.mjs",
@@ -14727,7 +14742,7 @@
     {
       "path": "tests/provisioning_paid_shape_gate.mjs",
       "mode": "0000644",
-      "sha256": "f6f2a28ebadee97523019e3346f69f399864c6bf23b4e14029d6df81dee872cb"
+      "sha256": "c9fa4aa59e6e47c139277e3c57298ca441180c4d4752ca6994c72678219df8c8"
     },
     {
       "path": "tests/provisioning_public_refusal.mjs",
@@ -14787,13 +14802,18 @@
     {
       "path": "tests/provisioning_teardown_intent.mjs",
       "mode": "0000644",
-      "sha256": "08128da3c6b810df963cb167cf29608181627d6c6203efe57f27d1c29e22d54a"
+      "sha256": "4d06c5fd13f8cc81c050c2ed6940c91db5cdd95dea9f26ad7b8d6a8089c0254a"
     },
     {
       "path": "tests/provisioning_teardown_states.mjs",
       "mode": "0000644",
       "sha256": "1b5decd026e6487c9477b87f533852dd93821b6688c3c76e694041b3918ee420"
     },
+    {
+      "path": "tests/provisioning_wizard_create_xenos.mjs",
+      "mode": "0000644",
+      "sha256": "2b7048eb35f09fd40f93e301e7c7e999db1b12b04bd0855e616b8ae1d93006a8"
+    },
     {
       "path": "tests/pruned_lockfile_integrity.mjs",
       "mode": "0000644",

package/docs/adr/0354-a-builder-hosts-one-project-free-and-more-takes-the-fleet-permission.md

@@ -0,0 +1,46 @@
+# ADR 0354 — A builder hosts one project for free, and more takes the fleet permission
+
+- **Status:** accepted
+- **Date:** 2026-09-30
+- **Task:** [task 1004412](https://cloudbongos.com/builders#/task/1004412) (goal 1000106 — working area 1, Project creation)
+- **Amends:** the gate [task 1003370](https://cloudbongos.com/builders#/task/1003370) put on `cloud-host` (audit B4), for a builder's first hosted project only
+- **Builds on:** [ADR 0345](0345-we-host-every-projects-hall-and-its-app-deploys-where-the-owner-chooses.md) decision 1 (we host every project's hall, and creating a project needs no platform account, key or bill) · [ADR 0285](0285-a-shared-box-holds-about-twelve-projects-per-gb-and-memory-is-the-wall.md) (the shared box holds about fifteen projects)
+- **Decided with:** the owner chose D1 on 2026-09-30, from three options put to them in plain language.
+
+## Context
+
+The create wizard sends one request when the owner presses its last button, "Create my project", and that request always asks for `cloud-host`: the hall, hosted by us. Task 1003370 (2026-09-19) gated that shape behind `provisioning.fleet.manage` (floor: Metic), because a hosted hall runs code from its owner's repository on the platform's own box. A new hub signup is a Xenos. So from that day, every new user who pressed "Create my project" was refused with `permission_forbidden`. The wizard showed it as its generic "We couldn't file the request just now", with the permission name underneath. Task 1004412 confirmed this with a route-level test that uses the real permission gate and a Xenos's real grants.
+
+ADR 0345 came nine days later and made `cloud-host` the free front door. The two decisions contradicted each other, and no test covered the path they shared.
+
+## Decision
+
+### D1 — One live hosted project per builder needs no permission
+
+A builder may create a `cloud-host` project with no permission if they hold no other live `cloud-host` project. "Live" means any status except `torn_down`. A queued or failed project still holds its place, and its owner can retry it or take it offline. Asking again for your own project's slug (a retry or a revive) counts as that same project, not a second one. A further live hosted project needs `provisioning.fleet.manage`, and the refusal is the kernel gate's own `permission_forbidden`.
+
+What stops one person taking every place on the box is this limit, not rank. `byo-host` stays open without limit, and `control-plane` and `co-tenant` stay unrequestable. The gate is still an allow-list, so a shape added later is gated by omission.
+
+If the count cannot be read, the gate refuses with `request_failed`. It is an authority gate, so it fails closed (ADR 0016).
+
+### D2 — One first-free request per builder at a time
+
+The count and the insert are two separate steps, so two requests sent together would both count zero. The gate takes a Postgres advisory lock keyed on the builder (`free-place-lock.js`, a try-lock on its own connection) before it counts, and lets it go as soon as the route has inserted the row (or when the response closes, on any earlier exit). A second request sent in the meantime, from any web process, gets 409 `create_in_progress`. A lock that cannot be taken refuses, like an unreadable count. (The first version used a process-local mark; the grader flagged that it would not hold across processes, so it moved into the database before shipping.)
+
+### D3 — The wizard states both refusals in plain words
+
+- **`permission_forbidden` with a readable `held`:** "Each account can host one project for free, and yours already has one…". The sentence names the project page's own "Take it offline" control, and says that trusted builders can host more than one (the owner asked for that line when reviewing the wording).
+- **`box_full`:** "Our shared server is full right now…", instead of the operator's sentence.
+- **`permission_forbidden` with `held: null`:** authority could not be checked at all, so the wizard keeps its generic sentence.
+
+## Consequences
+
+- New users can create a project from the wizard again. Each project costs us about $0.80 a month (ADR 0285).
+- A stranger's code now runs on the shared box, on the same server as the hub. It runs in its own locked account (task 1003369), and the hub's sign-in cookie no longer reaches project halls (task 1004357). **Nothing caps a hosted project's memory or CPU**, so one misbehaving project can slow every hall and the hub. That was already true of every hosted project; this decision widens who can have one.
+- Each first-free request holds one database connection from its count to its insert. Creates are rare, so the pool can carry it.
+
+## Alternatives considered
+
+- **Open to everyone, limited only by the box's capacity.** The smallest change. But one person could take every free place, and the capacity gate would then refuse everyone else.
+- **Trusted builders only, with a plain refusal.** Keeps task 1003370's rule whole. But new users still could not start a project, which ADR 0345 decision 1 rules out.
+- **An approval queue for new users' projects.** Keeps the rule and admits new users. But it is new machinery, and it would collide with the owner's redesign of the creation flow (begun 2026-09-30).

package/docs/adr/README.md

@@ -472,3 +472,4 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 0351 | [**A criterion closes on a UAT, not on its linked tasks shipping** ([task 1004392](https://cloudbongos.com/builders#/task/1004392), goal 1000089 — working area 3). Supersedes ADR 0183's close rule. `wa7-government` had closed on six Board Room navigation tasks while nothing it describes was on the live site. **D1:** three checks — Code (linked tasks done, ≥1 shipped; automatic), Live, UAT — and the sweep closes a criterion only with a CURRENT sign-off (no older than the newest linked ship). **D2 (owner):** "Awaiting UAT" is a visible state. **D3 (owner):** one step; the signer is refused if they shipped linked work, the project owner excepted. **D4 (owner):** an mp4/webm up to 100 MB on the project's own server. **D5 (owner):** backend-only is set while a criterion is open and takes a recording-free sign-off. **D6 (owner):** Live is read via the `deploy.taskWhere` port where the site can tell, attested otherwise. **D7 (owner):** already-closed criteria stay closed ("Closed before UAT"). **D8:** `/satisfy` is a recorded override that needs a reason. **D9:** `/goal-uat` + `scripts/gds/uat.js`; the hall is task 1004402.](0351-a-criterion-closes-on-a-uat.md) | lifecycle / criteria / review |
 | 0352 | [**A rollup report carries its "as of" in a header, and the hub keeps the newest** ([task 1004268](https://cloudbongos.com/builders#/task/1004268), goal 1000110). `POST /sso/activity/rollup` was last-writer-wins with no report timestamp, so a sign-in push read earlier and a ship push read later could land the older totals last. **D1:** the instance's read time rides a `Bongos-Report-As-Of` HEADER, not a body field, because the hub validates the body strictly and hub and instances upgrade independently: a body field from a newer instance would 400 on an older hub and lose the report, while an unknown header is ignored. **D2:** missing or unparseable = unstamped = last-writer-wins, never a 400. **D3:** the guard is a WHERE on the upsert's conflict branch (migration 026, `reported_as_of`, no backfill); a skipped update keeps the row lock, so the task 1004244 snapshot stays in step. **D4:** the stamp is compared only with the same client's, and clamped to the hub's `now()`.](0352-a-rollup-report-carries-its-as-of-in-a-header.md) | platform identity / federation |
 | 0353 | [**A hub invite is a notice of the project's own invite, and signing in accepts it** ([task 1002818](https://cloudbongos.com/builders#/task/1002818), goal 1000110 — R6 of the admin console wave). The hub's own invite wrote a `pending` membership that no project reads, so an "accepted" invite met a locked door (new projects default to `apply`). **D1:** that row is now a NOTICE the PROJECT writes: its invite route calls `POST /sso/invites/notify` and a dismissal that leaves no invited row calls `/sso/invites/clear` (client credentials, pending rows only, always `{ ok: true }` so no account oracle); core's `notifyHubOfInvite` is fire-and-forget. **D2:** the hub-side accept route is deleted; signing in to the project accepts, and the hub's own sign-in witness turns the row into a membership. **D3 (owner):** `POST /projects/invite` writes nothing and answers `{ invited: false, invite_url }`, the project's hall invite link (`/builders/watch?invite=<login>`, which only pre-fills); the signed-assertion relay is deferred. **D4:** new routes, so an older hub 404s and only the notice is lost (ADR 0352).](0353-a-hub-invite-is-a-notice-of-the-projects-own-invite.md) | platform identity / federation |
+| 0354 | [**A builder hosts one project for free, and more takes the fleet permission** ([task 1004412](https://cloudbongos.com/builders#/task/1004412), goal 1000106 — working area 1, the owner's ruling of 2026-09-30). The create wizard always asks for `cloud-host`, which task 1003370 had gated behind `provisioning.fleet.manage`, so every new (Xenos) user was refused at "Create my project" — against ADR 0345 decision 1. **D1:** a builder's first live `cloud-host` project needs no permission; a further one needs the fleet permission (a retry of your own slug is the same project; only `torn_down` frees the place; an unreadable count refuses). **D2:** one first-free request per builder at a time (409 `create_in_progress`), held as a Postgres advisory lock so it holds across processes. **D3:** the wizard states `permission_forbidden` and `box_full` in plain words. Nothing yet caps a hosted project's memory.](0354-a-builder-hosts-one-project-free-and-more-takes-the-fleet-permission.md) | provisioning / security / project creation |

package/docs/api/openapi.json

@@ -14418,7 +14418,7 @@
           "provisioning"
         ],
         "summary": "POST /provisioning/instances",
-        "description": "POST /provisioning/instances — request a new instance. rank: any authenticated builder (own resource) for the free `co-tenant` shape. Every other shape also needs provisioning.fleet.manage — `dedicated` because it bills, `standalone` because it runs the caller's own repo on the platform's box — and `control-plane` is refused outright, since the platform enrolls its own row (../paid-shape-gate.js, task 1003370 / audit B4). A full shared box answers 409 box_full up front (../capacity-gate.js). ENQUEUES a 'provision' intent the runner (task P3) stands up. Idempotent on slug for the SAME owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409. Body: { slug (required), target_ref?, hosting_shape? (co-tenant free; others gated), domain?, tier?, onboard_mode? (greenfield|adopt) }. onboard_mode is LOAD-BEARING, not a label (task 1002562): the control-plane runner branches its repo scaffold on it. 'adopt' means target_ref is a repo the owner ALREADY has, so the runner must clone + layer onto its history instead of pushing a fresh tree at `main` (which an existing repo rejects as unrelated history). Absent → 'greenfield', the safe default.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "POST /provisioning/instances — request a new instance. rank: any authenticated builder (own resource) for `byo-host`, and for their FIRST live `cloud-host` (task 1004412, ADR 0354). A further cloud-host needs provisioning.fleet.manage, and `control-plane` / `co-tenant` are refused outright (../paid-shape-gate.js). A full shared box answers 409 box_full up front (../capacity-gate.js). ENQUEUES a 'provision' intent the runner (task P3) stands up. Idempotent on slug for the SAME owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409. Body: { slug (required), target_ref?, hosting_shape? (byo-host free; one cloud-host free), domain?, tier?, onboard_mode? (greenfield|adopt) }. onboard_mode is LOAD-BEARING, not a label (task 1002562): the control-plane runner branches its repo scaffold on it. 'adopt' means target_ref is a repo the owner ALREADY has, so the runner must clone + layer onto its history instead of pushing a fresh tree at `main` (which an existing repo rejects as unrelated history). Absent → 'greenfield', the safe default.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/provisioning/routes/provisioning.js",
         "requestBody": {

package/docs/design/project-startup-direction.md

@@ -0,0 +1,131 @@
+# Project startup — design direction (the design of record)
+
+> Goal 1000121 · task BV2.PS01 (1004415) · spec [`docs/specs/<redacted>.md`](../specs/<redacted>.md) (final) · idea 1001172.
+> Live prototype: the Claude Design canvas "Project Startup Onboarding" (https://claude.ai/artifact/<redacted>). It is private to the owner. Its sources are committed in [`mocks/project-startup/`](mocks/project-startup/README.md).
+
+This document is what every build task in goal 1000121 cites. Name a screen by its canvas file (for example "`Charter.dc.html`") and look it up here. It records:
+
+- **what each screen is**;
+- **what the live product KEEPS**;
+- **what the new design ADDS**;
+- the decisions that govern both.
+
+## The blend rule — read this first (owner, 2026-09-30)
+
+> *No UI battle between existing and new. Build the prototype's design, then blend it where needed with existing design. Don't hijack the builders hall.*
+
+Four consequences, applied in every row below:
+
+1. **Genesis is a MODE the existing hall wears, never a second hall.**
+   - It follows the social-mode precedent (`html[data-social]`): one attribute on the hall, off by default, and off whenever the founding state cannot be read.
+   - It keeps today's v3 glass hall: the shell, the 64px rail, the navigation groups, the panels, the tokens and both modes.
+2. **Founding mode adds exactly four things, and nothing else changes:**
+   - the founding band;
+   - the genesis home;
+   - the asleep state on existing navigation items;
+   - the founding mark.
+   
+   A test must pin that a hall that is not founding renders exactly as today.
+3. **Where the canvas's hall chrome differs from the live hall, the live hall wins.**
+   - The canvas drew a hall to show the idea: an expanded 232px rail, its own panel spacing, its own icons. Those are illustration, not instruction.
+   - Build the four additions *into* the real hall's components (`OTBKit`, the archetype sheets, `shell.js` NAV, the widget registry). Never port the canvas's markup.
+4. **The hub-side screens (front door, questions, look) are new surfaces in the apex world.**
+   - They extend the existing create wizard (`projects.html ?view=new`) and follow `DESIGN.md` exactly.
+   - Where the wizard already has a component, reuse it rather than the canvas's version: the lifecycle rail, hairline choice cells, one-hairline fields, doors and ledger rows.
+
+## The screens
+
+### Front door (hub, apex world)
+
+| Canvas screen | What it is | Keep | Add |
+|---|---|---|---|
+| `Main.dc.html` · Before you begin | A terms acknowledgement before creation. | Sign-in stays where it is today, before this screen. The terms version stamp (the platform's existing acceptance machinery) records what was accepted. | A new first screen: display headline, two lede paragraphs, one checkbox, a "read the terms" link, one primary door. |
+| `Fork.dc.html` · Demo or create | "You are now creating a digital planet." | The world's **door pill**, as specified in `DESIGN.md`: two equal doors joined into one glass object. | A full-bleed composition: the seed on the field plate, the headline, the door pill, and two route descriptions on a hairline band. |
+
+### Route 1 · the demo
+
+| Canvas screen | What it is | Keep | Add |
+|---|---|---|---|
+| `DemoSetup.dc.html` | People, hours each, an idea, and a fit check. | The wizard's steppers-as-fields grammar and hairline fields. | A fit-check panel in Bongos's voice, and a time-box ring on the planet. The copy says each person uses their own AI plan. |
+| `DemoReady.dc.html` | Defaults picked, plus invites. | Ledger rows for the defaults; the existing invite step's shape. | The demo defaults (D-list below) and two invite fields. |
+| `DemoKeep.dc.html` | "Keep your planet?" | — | Two cells: carry it over (pre-fills part 1) or keep it as a demo. |
+
+**Demo decisions:**
+- **D3 — the time box is soft.** A countdown shows; at zero the demo asks "keep your planet?". Work is never frozen.
+- **D9 — an unkept demo is archived after 30 days.** It goes offline and can be restored, and the owner is warned first.
+
+### Route 2 · part 1, planet physics (hub, apex world)
+
+Every question screen shares one layout. On the left are the rail of seven steps, the question, the choices and the doors. On the right is the **stage**: the field plate, with the planet forming.
+
+| Canvas screen | Question | Keep | Add |
+|---|---|---|---|
+| `Autofill.dc.html` | Start from your account, or from scratch? | Hairline cells. | The seven-step rail, shown up front. |
+| `State.dc.html` / `StateExisting.dc.html` | 1 · New or existing, the idea text, and existing work types. | Cells, a hairline textarea, and check rows. | The planet begins as a **seed** (new) or **already formed** (existing). |
+| `NotPossible.dc.html` | The screening stop. | — | A calm stop screen: nothing created, contact us, start over. No planet forms. |
+| `Geography.dc.html` | 2 · Home country and state, and where builders are. | Hairline selects and option rows. | The planet's **coordinates** (a mono line on the stage). |
+| `Ages.dc.html` | 3 · Anyone under 18? | Cells, and a ledger for the tiers. | A **protective ring**; the guardian tiers stated plainly. |
+| `Entity.dc.html` / `EntityExisting.dc.html` | 4 · Intent (new) or legal type (existing). | Option rows with group heads. | The planet's **core material**: frost for an individual, chrome for a group, gold for an organization, obsidian for a nonprofit. This is placeholder art direction. |
+| `Builders.dc.html` / `BuildersPro.dc.html` | 5 · One or many, how many, and a growth guess. | Cells and a stepper. | **Moons**, plus a dashed orbit for expected growth. Two voices (D5). |
+| `Rewards.dc.html` | 6 · Reward intents (hidden when solo). | Check rows. | **Rings**: currents of value. |
+| `Framing.dc.html` | 7 · A–D, plus the service checklist. | Option rows and a two-column check grid. | The planet's **orbit** around the Bongos pair: all managed is close, hybrid is middle, local is far, open source is its own system. |
+| `Physics.dc.html` | The summary. | Ledger rows with change links. | The full planet, with every addition. |
+
+**Decisions for part 1:**
+- **D5 — the voice follows the entity answer automatically.** Planet voice for individuals and groups; professional voice for organizations. It can be switched later in settings.
+- **D6 — soft limits only.** An option that does not apply is hidden or greyed, with a plain "why" line from one rule table that carries its reasons. Nothing claims to be enforced.
+
+### Coordinates, a look, then birth (hub, apex world)
+
+| Canvas screen | What it is | Keep | Add |
+|---|---|---|---|
+| `Coordinates.dc.html` | Name, handle and address; where the code lives; where the app runs. | **Today's wizard steps as they are.** This screen only shows them **pre-filled from part 1**, and skipped when they do not apply. | The planet named under the stage. |
+| `Look.dc.html` | Pick a look for light and dark mode, plus a logo. | **A look is a branding pack**: the style library's real looks (Chrome World, Expedition, Grove, Blueprint), with no sixteenth token. | A look picker with two mini-hall previews. A night-tint switch, **on by default** (D2 — its ADR is PS06's first job). A logo upload. |
+| `Birth.dc.html` | The planet forming while setup runs. | **Today's done panel**: the standup rail and the three owner-only steps. | The planet arriving on the stage. The primary door starts genesis while the machine setup finishes. |
+
+**D8 — existing projects get the look and the logo only**, from project settings. They never get genesis.
+
+### Part 2 · genesis, planet biology (the builders' hall, founding mode)
+
+**Every row here is governed by the blend rule.** The canvas shows Kestrel's chosen look (Grove, with the night tint) on purpose, to show that halls differ. The real hall renders the project's own branding pack, whatever it is.
+
+| Canvas screen | What it is | Keep (the live hall) | Add (founding mode only) |
+|---|---|---|---|
+| All four genesis screens | The frame. | The v3 glass hall: rail, topbar, panels, tokens, both modes, and the project's logo in the topbar. | **The founding band**: a 44px strip above the topbar reading "project founding mode", with the stage and day and a "what's this?" link. **Asleep navigation items**: today's items, dimmed, each naming the stage that wakes it. |
+| `GenesisDecide.dc.html` | Decide: stage lengths, what counts as done, the starting government, passes, advisors. | The hall's panels, ledger rows and pills. | **The genesis home** as the founding-mode landing page, including a solo fast-track (D4, about ten minutes). |
+| `GenesisHall.dc.html` | Mid-genesis. | The home widget registry and the roster rows. | A **life strip** (one rendered plate per stage; PS12 renders them), the stage list, and a founding builders panel. |
+| `Charter.dc.html` | Pick a form of government. | The charter library's real forms and trajectories. | Forms under their **real academic names** with plain explanations (D10). The founding builders' reviews are shown. |
+| `Legislation.dc.html` | Fine-tune the variables. | The Board Room constitution: franchise plus pass rule. | The variables under their academic names with plain explanations. The unbuilt variables are shown as coming later. "Limits from your answers" (D6). |
+| `Alive.dc.html` | The planet comes alive. | The hub sky: the planet joins it. | A moment screen: the founding builders credited, then enter the full hall. **Founding mode switches off.** |
+| `FoundingBuilders.dc.html` | The founding mark, after genesis. | The ranks page, profile and roster exactly as they are. | **The founding mark**: a numbered seed badge (D1 — badge only, it grants nothing), a column on ranks, and a founding wall on the home page. |
+
+**How rooms wake.** Each finished stage wakes today's navigation items:
+
+| Stage finished | Wakes |
+|---|---|
+| scope | goals & roadmap |
+| strategize | tasks |
+| charter | board room |
+| legalize | economy |
+| legislation | ranks |
+| alive | community, and the public sky |
+
+**D7 — a stage closes when the constitution in force decides it** (a Board Room item; PS04). Under a monarchy that is the founder's single confirmation.
+
+## The planet as a system
+
+The planet is built from the world's own rendered plates: `r2-*` and `r3-*`, the cutouts, and `r3-space-nebula` for the field. Nothing on the stage is drawn:
+
+- orbits are hairline circles;
+- moons are beads;
+- the Bongos pair is the platform's mark.
+
+Motion follows `DESIGN.md`: breathe (32s), sheen (40s), drift (90s), orbits of 160s or more, arrive (700ms). All of it is CSS on the objects only, and dead under the kill switch.
+
+**The planet the flow forms is the planet that appears in the sky.** Its shape, material and style come from the hub's existing template fields, and the look's accent tints it.
+
+## Copy
+
+- **The screen text is user-facing copy, drawn from the owner's scope doc.** Italic text and footnotes in that doc were internal; they live in the canvas's notes and in the spec.
+- **Voice:** the planet voice keeps the owner's energy (one ":)" on the fork). The professional voice drops the planet words but keeps the same flow.
+- **The sample data is sample.** Kestrel, Avery, Jordan, Sam and Rae, the counts, and the "[n]" placeholders are not product copy.

package/docs/module-api-changelog.md

@@ -2703,5 +2703,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.21 with no explicit bump. run 36743446010. (task 1002620)
   1.20.23 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.22 with no explicit bump. run 36747567551. (task 1002620)
+  1.20.24 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.23 with no explicit bump. run 36759918201. (task 1002620)
+  1.20.25 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.24 with no explicit bump. run 36762454104. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/page-readings.json

@@ -3606,7 +3606,7 @@
       "surface": "landing",
       "title": "{{productName}} — projects",
       "states_read": ["out-map","in-map","in-map-projects","in-map-profile","in-map-kbd","in-map-search","in-map-mine-on","in-table","in-table-by-builders","in-mine","in-manage","in-manage-address","in-manage-planet","in-manage-card","in-manage-kind","in-manage-invite","in-manage-invite-handoff","in-manage-app-live","in-manage-app-building","in-manage-app-failed","in-manage-app-retry","in-manage-app-offer","in-manage-app-connect","in-manage-snag","in-manage-gone","in-manage-missing","out-manage","in-new","out-new","in-new-type","in-new-about","in-new-modules","in-new-modules-search","in-new-home","in-new-address","in-new-app","in-new-app-render","in-new-review","in-new-done","in-new-resume-offer","out-map-projects","card","card-noart","card-self","in-mine-empty","card-floor","card-backdrop"],
-      "files_hash": "4d039ad9637045e2",
+      "files_hash": "0175af500182c5d2",
       "reading_hash": "1b2c6ce40c79925e",
       "counts": {"lines":517,"placed":182,"shared":20,"unplaced":315},
       "omitted": {"data":107},

package/modules/provisioning/free-place-lock.js

@@ -0,0 +1,52 @@
+// modules/provisioning/free-place-lock.js — one first-free hosted-project request per
+// builder at a time, across every web process (task 1004412, ADR 0354 D2).
+//
+// The shape gate counts a builder's live hosted projects and the route inserts the new
+// one a few awaits later. Two requests sent together would both count zero and both take
+// the free place. A process-local mark only closes that inside one process, so the guard
+// is a Postgres advisory lock keyed on the builder: whichever request holds it answers,
+// and any other request from that builder, from any process, is refused until it is let
+// go. It is taken with TRY, so nothing ever queues behind it.
+//
+// Session-level, on a client held from the gate's count to the route's insert, because the
+// count and the insert are not one transaction. Releasing unlocks and returns the client; if the
+// unlock itself fails the client is destroyed, which ends the session and frees the lock.
+//
+// Its own file so a test can re-point `holdFreePlace` through the module object, and
+// because provisioning.js and routes/provisioning.js sit at their size ratchets.
+'use strict';
+
+// The lock's first key: one namespace for this guard, so it can never collide with an
+// advisory lock another part of the platform takes on a builder id.
+const NAMESPACE_SQL = "hashtext('provisioning.one-free-hosted-project')";
+
+// holdFreePlace — try to hold the builder's free-place lock. Resolves to a release
+// function when it is held, or null when another request already holds it. Throws when
+// the database cannot be asked; the caller refuses then (it never admits on a guess).
+async function holdFreePlace(db, builderId) {
+  const key = Number(builderId);
+  if (!Number.isInteger(key)) throw new TypeError(`free-place lock: builder id ${builderId} is not an integer`);
+  const client = await db.connect();
+  let held;
+  try {
+    const { rows } = await client.query(`SELECT pg_try_advisory_lock(${NAMESPACE_SQL}, $1::int) AS held`, [key]);
+    held = !!(rows[0] && rows[0].held);
+  } catch (err) {
+    client.release(true);
+    throw err;
+  }
+  if (!held) { client.release(); return null; }
+  let released = false;
+  return async function release() {
+    if (released) return;
+    released = true;
+    try {
+      await client.query(`SELECT pg_advisory_unlock(${NAMESPACE_SQL}, $1::int)`, [key]);
+      client.release();
+    } catch {
+      client.release(true);
+    }
+  };
+}
+
+module.exports = { holdFreePlace };