@bongos/core 1.19.1080 → 1.20.1

package/docs/adr/0347-every-store-module-ships-a-how-to.md

@@ -0,0 +1,135 @@
+# ADR 0347 — Every store module ships a how-to: a file in the module, a publish gate, and a Docs score shown on its own
+
+- **Status:** accepted
+- **Date:** 2026-09-29
+- **Task:** [task 1004364](https://cloudbongos.com/builders#/task/1004364) (goal 1000091 — working area 5, Module distribution & economy)
+- **Deciders:** Will (owner of working area 5) decided the how-to is a file, the "gate plus score" grader, that the Docs score is shown separately rather than averaged in, and the grader's model and cost ceiling; Claude wrote the record.
+- **Related:** [ADR 0343](0343-a-module-score-is-a-security-gate-then-an-average-of-visible-parts.md) (the score; D1's parts table is amended here) · [ADR 0338](0338-modules-travel-through-a-bongos-hosted-store.md) (the store, the tarball and its hashes) · [ADR 0098](0098-public-mirror-publish-manifest.md) (`isPublishable()`) · [`docs/modules-contract.md`](../modules-contract.md) §6 (publish) and §7 (install) · follow-on tasks 1004365 (the file and the publish check), 1004366 (the store page and PDF), 1004367 (the AI grader)
+
+## Context
+
+A buyer browsing the store (ADR 0338) sees a module's name, category and score (ADR 0343),
+but nothing tells them how to use what they are getting. Today a module carries a
+`CLAUDE.md` written for AI sessions working *inside* the module, not for the person who
+installs it. There is no rule that an author explains their module at all.
+
+The owner wants every store module to come with a how-to that works for a person or for any
+AI, that the buyer can read before acquiring, and that is judged so good explanations are
+visible.
+
+## Decision
+
+### D1 — The how-to is a file: `HOWTO.md` at the module root (owner)
+
+The how-to is `modules/<key>/HOWTO.md`, plain Markdown. It is a **file in the module**, not a
+hosted page, because:
+
+- it travels inside the tarball, so it is covered by the manifest hashes and **cannot change
+  after a version is published** — the how-to a buyer read is the one they get;
+- any AI or person can read and write Markdown, so the module does not depend on one vendor;
+- it goes wherever the module goes, including instances that are offline.
+
+The packaging allowlist (`isPublishable()`, ADR 0098) must include `HOWTO.md`; task 1004365
+checks it is in the tarball.
+
+### D2 — Five required sections, kept short
+
+`HOWTO.md` must contain these five level-2 headings, matched case-insensitively and in any
+order, each with some text under it:
+
+| Heading | What goes in it |
+|---|---|
+| `## What it does` | A few sentences: what the module adds and who it is for. |
+| `## Install and enable` | How to get it (`bongos module install <key>`) and switch it on (hall Modules tab). |
+| `## How to use it` | Its commands, routes and hall surfaces, with **one worked example**. |
+| `## Configuration` | Env vars and settings, with defaults. "None." is a valid answer. |
+| `## Limits and known issues` | What it doesn't do, and anything known to go wrong. "None known." is a valid answer. |
+
+Other headings and sections are welcome. The list is short on purpose, so an author can meet
+it in minutes; quality above that bar is what the Docs score (D5) rewards.
+
+### D3 — An optional Claude artifact link, shown as an extra and never graded (owner)
+
+An author may set `howto.artifactUrl` in `module.json` to a Claude artifact (an `https://`
+link on `claude.ai`). The store page shows it as **"Also available as a Claude page"**, next
+to the file, never instead of it.
+
+It is **never graded and never required**, because a hosted page can change after publish;
+only the file is frozen with the version. The store validates the field's shape only.
+
+### D4 — The gate: no how-to, no publish
+
+`bongos module publish` **refuses** a version when `HOWTO.md` is missing, or when any required
+section (D2) is missing or empty. The refusal names the file or each failing section, e.g.
+`HOWTO.md: section "Configuration" is empty`.
+
+- It is a free, deterministic check: it reads headings, it does not judge writing.
+- The CLI runs it before uploading, and the store runs it again on upload (as it already
+  re-checks hashes and the denylist, `modules-contract.md` §6), so a hand-built upload can't
+  skip it.
+- It applies **only to store versions**. Core-bundled modules and `bongos module submit`
+  (proposing a module into core, ADR 0135) are not gated by it.
+- Versions published before the gate existed are not delisted or re-checked; the gate applies
+  from the next version.
+
+### D5 — The Docs part: scored, visible, and **not** in the overall score (owner)
+
+This amends ADR 0343 D1's parts table with one row:
+
+| Part | What it measures | Available |
+|---|---|---|
+| **Docs** | clarity and completeness of the version's `HOWTO.md`, scored by an AI grader (task 1004367) | day one |
+
+- **Scored 0–100 per version**, like every other part, because each version ships its own
+  how-to.
+- **Shown separately, not averaged in (owner).** Docs is displayed with the other parts
+  (ADR 0343 D4), labelled as not counting toward the overall score. It does **not** join the
+  plain average in ADR 0343 D3, and so does not move the floor, ranking or cap
+  (tasks 1003807–1003809). The overall score stays a measure of how the module *works*; Docs
+  tells the buyer how well it is *explained*. A superseding ADR can fold it in later if the
+  owner wants.
+- **The grader gives a short reason** with the number (a sentence on what is clear and what is
+  missing, such as "no worked example"), so an author knows what to fix.
+- **"No score yet" is never a zero** (ADR 0343 D5). While grading is under way the part shows
+  **"Docs: pending"**; if grading could not run, **"Docs: not scored"**. A version is listed
+  as soon as it passes the gate; it never waits for the grader.
+- **Price is never an input** (ADR 0343 D6). Free and paid modules are graded by the same
+  call, and the Metic+ override applies to Docs like any part, with an audit entry.
+
+### D6 — Cost: one Sonnet 5 call per version, capped at 5¢ (owner)
+
+- **One grader call per published version**, made by the store after the version is accepted.
+  A failed call is retried once; if both fail, the part stays "not scored" until Metic+
+  re-runs it. Nothing re-grades a version automatically after that.
+- **Model: Claude Sonnet 5** (`claude-sonnet-5`), the rung the task grader already uses
+  (`modules/grading/grader-rubric.json`). Changing the rung needs the area owner's nod.
+- **Ceiling: 5¢ per call** at list price (Sonnet 5 is $2 in / $10 out per million tokens,
+  `src/bongos/llm-pricing.js`). The grader caps its output and its input to fit: a how-to too
+  long to read in full is cut to fit, and the reason says the score covers only the part read.
+  A typical how-to costs about 1–2¢.
+- The platform pays, and each call is recorded in the cost log like any other API spend
+  (CLAUDE.md §4). At 5¢ a version, a thousand published versions is $50.
+
+## Consequences
+
+- **Task 1004365** adds the scaffolded `HOWTO.md` (with the five headings) to
+  `bongos module new`, the section check in `bongos module publish`, the same check on the
+  store's upload route, and `HOWTO.md` in the packaging allowlist.
+- **Task 1004366** renders the file as the module's store page, with a PDF download of the
+  same content, and shows the D3 link when present.
+- **Task 1004367** builds the grader to D5 and D6, and stores its score and reason as the
+  Docs part.
+- **Authors of existing store modules** must add a `HOWTO.md` before their next version.
+- **The overall score and ranking are unchanged** by this ADR (D5).
+
+## Rejected
+
+- **A hosted Claude artifact as the how-to.** It can change after publish, isn't covered by
+  the hashes, and ties the module to one vendor. Kept only as the optional extra (D3).
+- **Gate only, no score.** It proves the sections exist, not that they are any good.
+- **AI grader only, no gate.** It costs money for modules with no how-to at all, and an
+  outage would leave nothing enforcing the basics.
+- **Docs in the plain average.** Considered; the owner chose to keep the overall score about
+  how the module works and show Docs beside it.
+- **Grading core-bundled modules.** They reach instances through the core, not the store; the
+  store page is where the how-to is read.

package/docs/adr/0348-the-web-tier-may-look-read-only-at-what-an-owners-render-key-can-see.md

@@ -0,0 +1,53 @@
+# ADR 0348 — The web tier may look, read-only, at what an owner's Render key can see
+
+- **Status:** accepted
+- **Date:** 2026-09-29
+- **Task:** [task 1004352](https://cloudbongos.com/builders#/task/1004352) (goal 1000106 — working area 1, Project creation)
+- **Deciders:** Lars (Archon) chose both decisions in chat on 2026-09-29, from options Claude laid out. Claude wrote the record.
+- **Amends:** [ADR 0111](0111-instance-hosting-provisioning-module.md) §2 ("the internet-facing web process never calls a cloud API") — one narrow, read-only exception
+- **Keeps:** [ADR 0327](0327-a-cloud-host-runs-on-the-owners-account-and-the-key-is-borrowed.md) §2 (the key is borrowed, never stored) and §3 (we never destroy an owner's infrastructure) · [ADR 0345](0345-we-host-every-projects-hall-and-its-app-deploys-where-the-owner-chooses.md) (we host the hall; the app goes where the owner chooses)
+
+## Context
+
+The setup wizard's app step lets an owner put their app on their own Render account ([task 1004351](https://cloudbongos.com/builders#/task/1004351), [task 1004352](https://cloudbongos.com/builders#/task/1004352)). Two things the owner must see before Create can only come from Render itself:
+
+- **Whether the key works.** A refused key discovered after Create is a project with a broken promise on its done screen.
+- **Which workspaces the key reaches.** A Render key belongs to a *user*, and reaches every workspace that user is in — measured on 2026-09-22 at three, one of them another builder's (ADR 0327). The owner has to choose one. Picking the first would be exactly the mistake ADR 0327 exists to prevent.
+
+ADR 0111 §2 says the web process never calls a cloud API; the runner does, from the intent queue. The runner can't answer an owner who is still on the page, and keeping the key between a check and a Create would break ADR 0327 §2.
+
+There was a second, related problem. Create queues the project's own `provision` run, and a project has one open-intent slot, so a separate `render-standup` request made a moment later collides with it.
+
+## Decision
+
+### 1. One read-only look, on the owner's own key
+
+`POST /provisioning/render/lookup` (`modules/provisioning/render-lookup.js`) may call Render from the web tier, and nothing else may. Its limits are the whole exception:
+
+- **GET only, two calls:** the workspace list, and the web services in one named workspace. Nothing in it can create, change or delete anything.
+- **The key is the owner's own, held for that one request.** It travels in a POST body, never a URL; it is never stored, logged or sent back. Nothing encrypts it, because nothing keeps it.
+- **Every service in the answer is checked to carry the workspace asked about.** One that doesn't voids the whole answer. This is the runner client's guard (`scripts/gds/render-api.js`), carried here as two GETs because a module may not require that file (ADR 0083).
+- **It is capped per builder** (20 a minute): a wizard needs a handful.
+
+What this does *not* change: every write to an owner's Render account still happens in the runner, from the queue, on a key borrowed for one run.
+
+### 2. The key rides the project's own setup run
+
+When the wizard sends the key right after Create, and the project's `provision` run holds the open slot, the key is attached to **that** run (`attachToProvision`). It goes in one statement, only onto a run that holds no key yet, and the table's CHECK still refuses a key on a resolved run. After the project is up, the runner sets the app up on Render in the same drain (`afterProvision`) and clears the key whatever happens:
+
+- **Project up, app set up:** done.
+- **Project up, app failed:** the run is still a success, since the project is live. The app's failure is recorded on `app_host` and in the run's note.
+- **Project failed:** Render is never called. The key is cleared at once, so a provision retry never carries it into a later run, and the owner connects Render again once the project is live.
+
+## Consequences
+
+- The web tier now makes outbound calls to one third party, on user-supplied credentials. That is a new egress path, and the reason decision 1 is drawn so narrowly: read-only, one host, capped, key never kept.
+- A compromised web tier could read keys from lookup requests. It could already read them from the setup request (ADR 0327 §2 says so plainly), so this adds no new exposure of the key.
+- The key waits on the provision run for as long as the project takes to stand up: minutes, and at most the leg's 30-minute limit, after which it is refused and cleared.
+- A resumed wizard draft asks for the key again, because the key never enters the draft.
+
+## Alternatives considered
+
+- **Keep the rule strict: no check before Create.** The owner types a workspace id, and a refused key surfaces after Create. The owner rejected this: it fails the task's done-when and leaves the workspace choice to guesswork.
+- **Let the browser call Render directly.** It depends on Render allowing cross-origin calls from our page, which we can't rely on. It would also move the workspace guard somewhere we can't test on the server.
+- **Ask for the key on the project page once the project is live.** Simpler, but not one wizard pass. It stays available as the fallback when an app fails to set up ([task 1004184](https://cloudbongos.com/builders#/task/1004184)).

package/docs/adr/0349-a-version-preview-is-a-sandboxed-child-the-web-tier-launches.md

@@ -0,0 +1,106 @@
+# ADR 0349 — A version preview is a sandboxed child the web tier launches, reached by a cookie
+
+- **Status:** accepted
+- **Date:** 2026-09-29
+- **Task:** [task 1004300](https://cloudbongos.com/builders#/task/1004300) (goal 1000090 — BONGOS-V2); split out of [task 1002622](https://cloudbongos.com/builders#/task/1002622)
+- **Deciders:** Lars (owner, Archon) approved both decisions below on 2026-09-29, in chat with the orchestrator: "Yes to cookie routing and web tier, build 1004300." Claude wrote the record.
+- **Amends:** [ADR 0293](0293-the-owners-deploy-door-is-an-intent-the-control-plane-drains.md) D1, for this one feature only.
+- **Related:** [ADR 0016](0016-trust-boundary-server-enforced-permissions.md) (authority is resolved per request) · [ADR 0043](0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md) (the control plane is a separate privilege domain) · [ADR 0151](0151-governance-permissions-as-atom-ranks-as-roles.md) (`requirePermission`) · [`docs/modules-contract.md`](../modules-contract.md) (the `request.divert` seam)
+
+## Context
+
+The owner asked for the version history on `/deploy` to open the hall **as it was at that
+version**, with a banner saying which version it is. A release-notes page was rejected: the
+point is to see, and to run a version's migrations against real data before that version goes
+live. So a preview is a second Bongos process, running an installed copy of that core against
+a copy of the live database.
+
+Two questions had no safe default.
+
+**How does a browser reach it?** The hall's pages call absolute `/api/bongos/...` URLs about
+133 times across `modules/*/public`, and the hall is routed on the Host header
+(`src/bongos/serve-internal.js`, `isBuildersHost`). Serving a preview under a `/preview/<v>/`
+path would break both. A second origin would need its own GitHub OAuth app, an owner step.
+
+**Who launches it?** ADR 0293 D1 keeps the web tier shell-less: it asks, and the control-plane
+runner acts. That fits a privileged act like moving a pin. A preview is unprivileged by
+design, and routing every start and stop through the intent queue would add a timer's latency
+to something a person is waiting on.
+
+## Decision
+
+### D1 — Route by cookie, through an optional `request.divert` seam (owner)
+
+`GET /api/bongos/npm-release/preview/enter?v=X` sets `bongos_preview=X` (HttpOnly, SameSite=Lax,
+Path=/). A kernel middleware, mounted before any surface, asks an **optional** provider of the
+`request.divert` seam whether to take the request. With no provider it is one map lookup and
+`next()`: an instance without the npm-release module is served exactly as before. A provider
+that throws is treated as absent for that request.
+
+The npm-release provider forwards a request to the preview only when **all** hold:
+
+- the cookie names the version now running;
+- the path is not sign-in (`/api/bongos/auth/*`) and not the module's own preview routes, so
+  signing in and **leaving** a preview always reach the live hall;
+- there is no `Authorization` header (a CLI or API call is never a preview);
+- the caller is signed in and holds `core.pin.move`, resolved by the kernel's own
+  `requireBuilder` and `requirePermission` gates on **every** forwarded request, uncached
+  (ADR 0016). A refusal clears the cookie and serves the live hall.
+
+The proxy keeps the Host header, passes server-sent-events streams through unbuffered, strips
+the steering cookie from what the preview sees, and injects the banner after `<body>` on HTML
+responses, so a version older than any banner code still shows it.
+
+The session cookie is forwarded: the preview's database is a copy, so the same session rows
+exist in it and no second sign-in is needed. Anything done there stays in the copy.
+
+**Rejected:** a `/preview/<v>/` path (breaks 133 absolute URLs and Host routing); a second
+origin (an OAuth app per preview host, and cookies that no longer carry).
+
+### D2 — The web tier launches the preview, as a sandboxed child (owner; amends ADR 0293 D1)
+
+The npm-release module's supervisor installs the version, copies the database, migrates the
+copy and spawns the child itself. This is the exception ADR 0293 D1 refuses for the deploy
+door, granted here because a preview is not the deploy door: it changes nothing live.
+
+What keeps that exception narrow:
+
+- **The child's environment is built from nothing.** An allow-list of `PATH`, `NODE_ENV`,
+  `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, plus its own `PORT`/`HOST` on 127.0.0.1. `HOME`
+  is an empty scratch directory, so the Discord webhook file is not found. Every `GITHUB_*`,
+  `DISCORD_*` and AI key is absent because nothing carries it, not because it was removed.
+  `CHAT_DRY_RUN=1`; nine pollers off (`PUBLISH_RECONCILER_DISABLED`, `ROUTINE_TIMERS_DISABLED`,
+  `BOARD_EXPIRY_DISABLED`, `SEARCH_INDEX_SWEEP_DISABLED`, `SESSION_UPLOAD_HEALTH_DISABLED`,
+  `SESSION_REWARD_RECONCILE_DISABLED`, `PROVISIONING_LIVENESS_DISABLED`,
+  `PROVISIONING_CATALOG_BACKFILL_DISABLED`, `CONFLICT_RESOLVE_DISABLED`); modules `discord`,
+  `agents`, `provisioning` and `npm-release` off.
+- **The copy is a dump and a restore, never a template copy.** `pg_dump -Fc` then `pg_restore
+  --no-owner` into `bongos_preview`. A template copy needs no other connection on the source,
+  and the live pool holds some. `PGDATABASE` is pinned to the copy and `DATABASE_URL` blanked
+  for the migration, so nothing can be applied to the live database.
+- **Commands run without a shell.** A version is `^\d+\.\d+\.\d+$` before it reaches any
+  command line.
+- **One preview at a time; 20 minutes idle stops it** and drops the copy.
+- **Only published versions**, no older than the running version minus 30 published versions.
+- **Nothing here holds a control-plane credential.** The web tier already cannot read
+  `/etc/cloudbongos/box.env` (ADR 0327 §5); the child gets less than the web tier has.
+
+### D3 — Accepted residual risks, for now
+
+- The child connects to Postgres as the same role as the live hall (`PGUSER`), so a hostile
+  published core could open the live database. It is our own published package, built from
+  this repository by CI, and a preview is limited to `core.pin.move` holders; a per-preview
+  database role is the next step, not built here.
+- **No egress firewall yet** (owner default). The env allow-list means the child holds no
+  outward credentials; it can still make anonymous outbound requests. `systemd-run
+  IPAddressDeny` is the follow-up and needs the droplet.
+- A preview started by the live process is stopped when that process exits, but the copy is
+  dropped only by the next start or stop. It is one fixed name, so it cannot pile up.
+
+## Consequences
+
+- One new optional seam, `request.divert`, listed in `docs/modules-contract.md`.
+- No migration. No schema. The provider is registered only where npm-release is on.
+- **Part B is unverified until run on the droplet:** the `lars` role has CREATEDB, the unit's
+  `MemoryMax` fits a second Node process plus a restore, the dump time, one preview end to end,
+  and live row counts before and after. Until then the code is implemented, not verified.

package/docs/adr/0350-the-hub-holds-a-per-project-write-deploy-key-so-a-hosted-upgrade-reaches-github.md

@@ -0,0 +1,103 @@
+# ADR 0350 — The hub holds a per-project WRITE deploy key, so a hosted project's upgraded pin always reaches its GitHub repo
+
+- **Status:** accepted
+- **Date:** 2026-09-29
+- **Task:** [task 1004291](https://cloudbongos.com/builders#/task/1004291) (follow-up to task 1004065)
+- **Deciders:** the owner chose this option on 2026-09-25 (a per-project write key, over keeping the owner's GitHub access longer, or leaving it as is); the shared-account default below was stated in the task and is the safe default, not a new ruling; Claude wrote the record.
+- **Amends:** [ADR 0176](0176-private-repo-deploy-keys.md) (which said the deploy key is read-only and that pushes ride the owner's token) · **Related:** [ADR 0281](0281-an-instance-identity-is-its-own-unix-account-and-pg-role.md) (a project's own account and database) · [ADR 0155](0155-adopt-private-repo-widen-oauth-scope.md) (the owner's token)
+
+## Context
+
+When a hosted project's core is upgraded, the pin is committed in the project's checkout and
+the hub's runner pushes it to the owner's GitHub repo (task 1004065, `pushUpgradePin`). That
+push needs a credential that can WRITE. There were two, and neither lasts:
+
+- the owner's token is stored for one hour after they sign in with repository access
+  (`GITHUB_TOKEN_TTL_MS`), and the scaffold path deletes it after use, so an upgrade days later
+  normally finds none;
+- the checkout's own `origin` is the read-only pull key of ADR 0176 (or the shared alias key),
+  which cannot write the owner's repo.
+
+So most upgrades still ended "GitHub was not updated". The box and the repo split, and the
+box's local commit stopped its fast-forward pull from taking the owner's new work (the
+hermeslines-marketing shape).
+
+## Decision
+
+**D1. A second deploy key per hosted repo, registered writable.** Minted with
+`ssh-keygen -t ed25519`, registered with `read_only: false` under its own title
+`cloudbongos-pin-<slug>`, distinct from the ADR 0176 pull key `cloudbongos-deploy-<slug>`. The pull key
+stays exactly as it was and stays read-only. Registering a deploy key needs repository admin
+for the owner, the same requirement the pull key already has. Public repos get one too (they
+have no per-repo key today).
+
+**D2. Where it lives and who can read it.** Outside every project checkout, in a directory of
+the runner's own account: `PROVISION_PIN_KEY_DIR`, default `~/.config/cloudbongos/pin-keys/`,
+directory mode 0700, key mode 0600, born under `umask 077`, and the modes are read back and
+the key deleted if they are not exactly 700/600. It is never written into the project's
+`.git`, its unix home (`/var/lib/bongos-<slug>`) or anywhere the project's account
+(ADR 0281) can read.
+
+**D3. When it is minted.** At standup (scaffold and adopt), right after the ADR 0176 wiring, and
+on any later pass that holds a fresh owner token and finds no key: `pushUpgradePin` mints it
+before pushing. So an existing project needs the owner to reconnect GitHub with repository
+access once; the next upgrade then sets up lasting access. Minting is best effort and never
+fails a standup or an upgrade.
+
+**D4. How it is used.** `pushUpgradePin` tries, in order: the write key, then the owner's token
+(when fresh), then the checkout's own `origin`. The write key is passed for that one push only
+(`-c core.sshCommand="ssh -F /dev/null -i <key> -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new"`
+against `git@github.com:<owner>/<repo>.git`), with hooks off, no prompt, never forced. A push the
+key made that GitHub rejects as non-fast-forward is reported as "behind" and nothing else is
+tried, because the credential worked and the history is what stopped it.
+
+**D5. Revoked when the project leaves.** Teardown, and therefore disconnect (which runs the
+teardown first), deletes the `cloudbongos-pin-<slug>` registration by title next to the pull
+key's, and removes the local key whatever else happened. With no usable owner token the
+registration cannot be removed by us; the log names it so the owner can remove it in their repo
+settings.
+
+**D6. A project with no account of its own is refused a key (the recorded default).** A project
+still running as the shared app user (the `resolveRunAs` fallback, no `bongos-<slug>`
+account) has the SAME uid as the runner and could read the runner's key, so no write key is
+minted for it, and the deploy page reports "needs its own account first" (repo note code
+`needs_account`) instead of offering a reconnect that could not help. The check is fail-closed:
+only a positive `id -u bongos-<slug>` counts; an inconclusive probe refuses. If the owner wants a
+shared-uid project to hold a write key anyway, that is a new decision recorded here, not a
+silent one.
+
+**D7. The deploy page.** The `no_access` note and the reconnect link now say that reconnecting
+sets up lasting access, no longer "about an hour".
+
+## What a compromise can and cannot do
+
+- **The runner account** (the hub's app user) already holds the database, the owner tokens and the
+  process manager, so it can already do everything the write key can. The key adds, for that
+  one account, the ability to push to each hosted owner repo without a live token — one repo per
+  key, revocable individually from the owner's repo settings.
+- **A project's own process** (its `bongos-<slug>` account, ADR 0281) can read the read-only pull
+  key, exactly as before, and can NOT read the write key: wrong owner, directory 0700. It
+  therefore cannot push code into the owner's repo, which is the point of keeping the key
+  outside the checkout. A project on the shared account can, which is why D6 refuses it a key.
+- **GitHub or the network** learn only the public half. A leaked write key can push to that one
+  repository until the owner deletes it in their settings; it cannot read other repos, and it
+  is a per-repo deploy key, not an account token.
+
+## Alternatives rejected
+
+- **Keep the owner's token longer.** A long-lived account-wide token in the hub is a bigger
+  prize than a per-repo key, and it still lapses when the owner revokes the OAuth grant.
+- **Leave it as is.** Most upgrades keep ending in a split that blocks the owner's own pushes.
+- **Make the pull key writable.** It lives in the checkout, readable by the project's own
+  account, so a compromised project could push code to the owner's repo.
+
+## Consequences
+
+- Existing projects get the key on the next runner pass after the owner reconnects GitHub with
+  repository access; until then the deploy page still reports "GitHub was not updated" with the
+  corrected copy.
+- Reconciling an already-split repo (hermeslines-marketing) and auto-rebasing a pin onto newer
+  GitHub commits stay out of scope; both are still reported, not resolved.
+- Code: `scripts/gds/provision-pin-key.js`, `pushUpgradePin` in
+  `scripts/gds/provision-core-upgrade.js`, the revoke in `scripts/gds/provision-teardown.js`,
+  the copy in `modules/hall-ui/public/deploy.js`; tests in `tests/pin_write_key.mjs`.

package/docs/adr/README.md

@@ -438,3 +438,7 @@ This keeps the decision history honest and traceable.
 | 0344 | [**A tester is a project that opts in once; an untested version reaches everyone after seven days** ([task 1003801](https://cloudbongos.com/builders#/task/1003801), goal 1000091 — working area 5, owner Will). Settles "willing user" for criterion `wa5-staged-rollout`. **D1 (owner):** a project's own admin switches on "tester" once and gets tester versions of every module it has, with a per-module "general only" override; never on by default; a builder cannot opt in someone else's project. **D2:** first releases and updates alike go to testers first. **D3 (owner):** a version moves to general after seven days if it still passes the security gate and tests, tested or not; the promotion gate may promote earlier or hold on evidence, never forever. **D4:** testers pay the normal price; any tester discount is area 8's call, named not decided. **D5:** tester installs, errors and crashes feed the score (ADR 0343). Rejected: per-module-only opt-in, one all-or-nothing switch, waiting for a tester, releasing at once.](0344-a-tester-is-a-project-that-opts-in-once.md) | modules / store / rollout |
 | 0345 | [**We host every project's hall, and its app deploys where the owner chooses** ([task 1004349](https://cloudbongos.com/builders#/task/1004349), goal 1000106 — working area 1, owner Lars). Reverses ADR 0323 §2 and the hall half of ADR 0327. **D1 (owner):** every project's Builders Hall runs on our shared server; `cloud-host` now means "hosted by us". **D2 (owner):** the hall's address is ours or the owner's own domain. **D3 (owner):** the setup wizard asks where the APP deploys; Render only at launch; choosing it creates the app on the owner's own Render account with ADR 0327's borrowed key. **D4 (owner):** "decide later" is allowed. **D5 (owner):** no project is moved. **D6 (measured):** ADR 0145 Finding 1 is live — the hub cookie is `Domain=.cloudbongos.com` and a hall loads modules from its own repo — so our-address halls need task 1004357; an owner domain is safe. **D7 (measured):** at the ceiling the create route refuses `box_full` up front, and the resize is not a prerequisite. Task 1004184 re-scoped, task 1004185 on hold.](0345-we-host-every-projects-hall-and-its-app-deploys-where-the-owner-chooses.md) | hosting / provisioning / security |
 | 0346 | [**Dev boxes are retired; a builder builds from their own checkout** ([task 1003898](https://cloudbongos.com/builders#/task/1003898), goal 1000120 — owner Lars). Records the whole removal, link by link, the owner's three rulings of 2026-09-13 (drop the data, delete `.devcontainer/`, remove `bongos box`/`shell`/`code`), what was kept on purpose (server-mediated publish, the CLI downloads, `secret-box`, `do-api`, the declared-source rule), and the retirement guards that still name the box. Supersedes 0031, 0044, 0045, 0053, 0057, 0059, 0071, 0072 (code staleness), 0123, 0144, 0145 (desktop-app branding), 0148, 0193, 0277; supersedes in part 0035, 0046, 0052, 0055, 0072 (Bongos app), 0151 §3.](0346-dev-boxes-are-retired.md) | builder environment / removal |
+| 0347 | [**Every store module ships a how-to: a file in the module, a publish gate, and a Docs score shown on its own** ([task 1004364](https://cloudbongos.com/builders#/task/1004364), goal 1000091 — working area 5, owner Will). Amends ADR 0343 D1. **D1-D2 (owner):** the how-to is `HOWTO.md` at the module root, frozen with the version by the tarball hashes, with five required sections (what it does; install and enable; how to use it, with one worked example; configuration; limits and known issues). **D3:** an optional `howto.artifactUrl` Claude artifact shown as "also available as", never graded. **D4:** `bongos module publish` and the store refuse a version with a missing file or empty section, naming it; store versions only. **D5 (owner):** a Docs part scored 0–100 per version, day one, shown beside the parts but NOT in the D3 average, floor or ranking; "pending"/"not scored" never zero; price never an input. **D6 (owner):** one Sonnet 5 call per version, 5¢ ceiling.](0347-every-store-module-ships-a-how-to.md) | modules / store / quality |
+| 0348 | [**The web tier may look, read-only, at what an owner's Render key can see** ([task 1004352](https://cloudbongos.com/builders#/task/1004352), goal 1000106 — working area 1, owner Lars). Amends ADR 0111 §2. **D1 (owner):** one route, `POST /provisioning/render/lookup`, may call Render from the web tier — GET only (workspaces; web services in one named workspace), the owner's key held for that request and never stored, logged or returned, every service checked to carry the workspace asked about, capped per builder. Every write stays in the runner. **D2 (owner):** a key sent during a Create rides the project's own `provision` run; the runner sets the app up on Render straight after the project is up and clears the key either way.](0348-the-web-tier-may-look-read-only-at-what-an-owners-render-key-can-see.md) | provisioning / security / render |
+| 0349 | [**A version preview is a sandboxed child the web tier launches, reached by a cookie** ([task 1004300](https://cloudbongos.com/builders#/task/1004300), goal 1000090 — BONGOS-V2, owner Lars, approved 2026-09-29). Amends ADR 0293 D1 for this feature only. **D1 (owner):** route by a `bongos_preview` cookie through an optional `request.divert` seam, not a path; forward only with the cookie, off the sign-in and preview paths, with no Bearer, and with `core.pin.move` re-checked on every request. **D2 (owner):** the npm-release module launches the preview itself, with a deny-by-default environment, a dump-and-restore copy of the database (never a template copy), one at a time, 20-minute idle stop, published versions within 30 of the running one. **D3:** the same database role and no egress firewall are accepted for now.](0349-a-version-preview-is-a-sandboxed-child-the-web-tier-launches.md) | modules / npm-release / deploy |
+| 0350 | [**The hub holds a per-project WRITE deploy key, so a hosted project's upgraded pin always reaches its GitHub repo** ([task 1004291](https://cloudbongos.com/builders#/task/1004291), follow-up to task 1004065). Amends ADR 0176. The owner's token lasts one hour and the checkout's own key is read-only, so most hosted upgrades ended "GitHub was not updated". **D1:** a second deploy key per repo, registered `read_only: false` as `cloudbongos-pin-<slug>`, the pull key untouched. **D2:** kept outside every checkout in the runner's own directory (0700 dir, 0600 key, modes verified), unreadable by the project's account. **D3:** minted at standup and whenever a fresh owner token finds none, so reconnecting GitHub once is enough. **D4:** `pushUpgradePin` tries write key, then owner token, then origin, never forced. **D5:** revoked on teardown and disconnect. **D6:** a project on the shared app user is refused a key: "needs its own account first". **D7:** /deploy says reconnecting sets up lasting access.](0350-the-hub-holds-a-per-project-write-deploy-key-so-a-hosted-upgrade-reaches-github.md) | provisioning / security |