@bongos/core 1.23.21 → 1.24.1

package/clients/bongos-client/index.mjs

@@ -120,6 +120,32 @@ export function createClient(opts = {}) {
       // POST /agents/{name}/invoke — rank: any-builder — POST /agents/:name/invoke
       postAgentsNameInvoke: (args) => request("POST", "/agents/{name}/invoke", { hasBody: true }, args),
     },
+    "aiStudio": {
+      // GET /ai-studio/balance — rank: any-builder — GET /ai-studio/balance
+      getAiStudioBalance: (args) => request("GET", "/ai-studio/balance", { hasBody: false }, args),
+      // GET /ai-studio/files/{id} — rank: any-builder — GET /ai-studio/files/:id
+      getAiStudioFilesId: (args) => request("GET", "/ai-studio/files/{id}", { hasBody: false }, args),
+      // GET /ai-studio/keys — rank: any-builder — GET /ai-studio/keys
+      getAiStudioKeys: (args) => request("GET", "/ai-studio/keys", { hasBody: false }, args),
+      // DELETE /ai-studio/keys/{provider} — rank: any-builder — DELETE /ai-studio/keys/:provider
+      deleteAiStudioKeysProvider: (args) => request("DELETE", "/ai-studio/keys/{provider}", { hasBody: false }, args),
+      // PUT /ai-studio/keys/{provider} — rank: any-builder — PUT /ai-studio/keys/:provider
+      putAiStudioKeysProvider: (args) => request("PUT", "/ai-studio/keys/{provider}", { hasBody: true }, args),
+      // GET /ai-studio/requests — rank: any-builder — GET /ai-studio/requests
+      getAiStudioRequests: (args) => request("GET", "/ai-studio/requests", { hasBody: false }, args),
+      // POST /ai-studio/requests — rank: any-builder — POST /ai-studio/requests
+      postAiStudioRequests: (args) => request("POST", "/ai-studio/requests", { hasBody: true }, args),
+      // GET /ai-studio/requests/{id} — rank: any-builder — GET /ai-studio/requests/:id
+      getAiStudioRequestsId: (args) => request("GET", "/ai-studio/requests/{id}", { hasBody: false }, args),
+      // GET /ai-studio/status — rank: any-builder — GET /ai-studio/status
+      getAiStudioStatus: (args) => request("GET", "/ai-studio/status", { hasBody: false }, args),
+      // POST /ai-studio/topup — rank: any-builder — POST /ai-studio/topup
+      postAiStudioTopup: (args) => request("POST", "/ai-studio/topup", { hasBody: true }, args),
+      // GET /ai-studio/topup/quote — rank: any-builder — GET /ai-studio/topup/quote
+      getAiStudioTopupQuote: (args) => request("GET", "/ai-studio/topup/quote", { hasBody: false }, args),
+      // POST /ai-studio/uploads — rank: any-builder — POST /ai-studio/uploads
+      postAiStudioUploads: (args) => request("POST", "/ai-studio/uploads", { hasBody: true }, args),
+    },
     "analytics": {
       // GET /analytics/builder/{id} — rank: any-builder — GET /analytics/builder/:id
       getAnalyticsBuilderId: (args) => request("GET", "/analytics/builder/{id}", { hasBody: false }, args),
@@ -137,6 +163,10 @@ export function createClient(opts = {}) {
       postAuthBackchannelLogout: (args) => request("POST", "/auth/backchannel-logout", { hasBody: true }, args),
       // POST /auth/cli-token/issue — rank: any-builder — POST /auth/cli-token/issue
       postAuthCliTokenIssue: (args) => request("POST", "/auth/cli-token/issue", { hasBody: true }, args),
+      // GET /auth/device — rank: public — GET /auth/device
+      getAuthDevice: (args) => request("GET", "/auth/device", { hasBody: false }, args),
+      // POST /auth/device/approve — rank: any-builder — POST /auth/device/approve
+      postAuthDeviceApprove: (args) => request("POST", "/auth/device/approve", { hasBody: true }, args),
       // POST /auth/device/exchange — rank: public — POST /auth/device/exchange
       postAuthDeviceExchange: (args) => request("POST", "/auth/device/exchange", { hasBody: true }, args),
       // POST /auth/device/poll — rank: public — POST /auth/device/poll
@@ -149,6 +179,10 @@ export function createClient(opts = {}) {
       getAuthDiscordStart: (args) => request("GET", "/auth/discord/start", { hasBody: false }, args),
       // POST /auth/discord/unlink — rank: any-builder — POST /auth/discord/unlink
       postAuthDiscordUnlink: (args) => request("POST", "/auth/discord/unlink", { hasBody: true }, args),
+      // GET /auth/google/callback — rank: public — GET /auth/google/callback
+      getAuthGoogleCallback: (args) => request("GET", "/auth/google/callback", { hasBody: false }, args),
+      // GET /auth/google/start — rank: public — GET /auth/google/start
+      getAuthGoogleStart: (args) => request("GET", "/auth/google/start", { hasBody: false }, args),
       // POST /auth/logout — rank: any-builder — POST /auth/logout
       postAuthLogout: (args) => request("POST", "/auth/logout", { hasBody: true }, args),
       // POST /auth/revoke — rank: archon — POST /auth/revoke
@@ -225,6 +259,8 @@ export function createClient(opts = {}) {
       getBuildersIdActivity: (args) => request("GET", "/builders/{id}/activity", { hasBody: false }, args),
       // PATCH /builders/{id}/budget — rank: metic+archon — PATCH /builders/:id/budget
       patchBuildersIdBudget: (args) => request("PATCH", "/builders/{id}/budget", { hasBody: true }, args),
+      // PATCH /builders/{id}/capabilities — rank: archon — PATCH /builders/:id/capabilities
+      patchBuildersIdCapabilities: (args) => request("PATCH", "/builders/{id}/capabilities", { hasBody: true }, args),
       // GET /builders/{id}/onboarding — rank: public — GET /builders/:id/onboarding
       getBuildersIdOnboarding: (args) => request("GET", "/builders/{id}/onboarding", { hasBody: false }, args),
       // GET /builders/{id}/profile — rank: public — GET /builders/:id/profile
@@ -517,6 +553,10 @@ export function createClient(opts = {}) {
       postGovernmentAssignments: (args) => request("POST", "/government/assignments", { hasBody: true }, args),
       // DELETE /government/assignments/{builderId}/{rankKey} — rank: archon — DELETE /government/assignments/:builderId/:rankKey
       deleteGovernmentAssignmentsBuilderIdRankKey: (args) => request("DELETE", "/government/assignments/{builderId}/{rankKey}", { hasBody: false }, args),
+      // GET /government/blockers/for-me — rank: any-builder — GET /government/blockers/for-me
+      getGovernmentBlockersForMe: (args) => request("GET", "/government/blockers/for-me", { hasBody: false }, args),
+      // GET /government/blockers/people — rank: any-builder — GET /government/blockers/people
+      getGovernmentBlockersPeople: (args) => request("GET", "/government/blockers/people", { hasBody: false }, args),
       // POST /government/board/charter — rank: metic+archon — POST /government/board/charter
       postGovernmentBoardCharter: (args) => request("POST", "/government/board/charter", { hasBody: true }, args),
       // POST /government/board/decision-rules — rank: metic+archon — POST /government/board/decision-rules
@@ -737,6 +777,8 @@ export function createClient(opts = {}) {
       deleteMeFilterViewsId: (args) => request("DELETE", "/me/filter-views/{id}", { hasBody: false }, args),
       // PATCH /me/filter-views/{id} — rank: any-builder — PATCH /me/filter-views/:id
       patchMeFilterViewsId: (args) => request("PATCH", "/me/filter-views/{id}", { hasBody: true }, args),
+      // POST /me/guardian-cosigns — rank: any-builder — POST /me/guardian-cosigns
+      postMeGuardianCosigns: (args) => request("POST", "/me/guardian-cosigns", { hasBody: true }, args),
       // GET /me/guild-engagements — rank: any-builder — GET /me/guild-engagements
       getMeGuildEngagements: (args) => request("GET", "/me/guild-engagements", { hasBody: false }, args),
       // GET /me/guild-requests — rank: any-builder — GET /me/guild-requests
@@ -771,6 +813,12 @@ export function createClient(opts = {}) {
       postMePasskeysRemove: (args) => request("POST", "/me/passkeys/remove", { hasBody: true }, args),
       // POST /me/passkeys/rename — rank: any-builder — POST /me/passkeys/rename
       postMePasskeysRename: (args) => request("POST", "/me/passkeys/rename", { hasBody: true }, args),
+      // POST /me/payout-age — rank: any-builder — POST /me/payout-age
+      postMePayoutAge: (args) => request("POST", "/me/payout-age", { hasBody: true }, args),
+      // POST /me/payout-freezes/{id}/appeal — rank: any-builder — POST /me/payout-freezes/:id/appeal
+      postMePayoutFreezesIdAppeal: (args) => request("POST", "/me/payout-freezes/{id}/appeal", { hasBody: true }, args),
+      // GET /me/payouts — rank: any-builder — GET /me/payouts
+      getMePayouts: (args) => request("GET", "/me/payouts", { hasBody: false }, args),
       // PATCH /me/profile — rank: any-builder — PATCH /me/profile
       patchMeProfile: (args) => request("PATCH", "/me/profile", { hasBody: true }, args),
       // GET /me/profile-nudge — rank: any-builder — GET /me/profile-nudge
@@ -789,6 +837,8 @@ export function createClient(opts = {}) {
       postMeSessionsRevoke: (args) => request("POST", "/me/sessions/revoke", { hasBody: true }, args),
       // POST /me/sessions/revoke-all — rank: any-builder — POST /me/sessions/revoke-all
       postMeSessionsRevokeAll: (args) => request("POST", "/me/sessions/revoke-all", { hasBody: true }, args),
+      // GET /me/sign-in-methods — rank: any-builder — GET /me/sign-in-methods
+      getMeSignInMethods: (args) => request("GET", "/me/sign-in-methods", { hasBody: false }, args),
       // GET /me/skill-prefs — rank: any-builder — GET /me/skill-prefs
       getMeSkillPrefs: (args) => request("GET", "/me/skill-prefs", { hasBody: false }, args),
       // PATCH /me/skill-prefs — rank: any-builder — PATCH /me/skill-prefs
@@ -868,6 +918,16 @@ export function createClient(opts = {}) {
       // POST /my-projects/join — rank: any-builder — POST /my-projects/join
       postMyProjectsJoin: (args) => request("POST", "/my-projects/join", { hasBody: true }, args),
     },
+    "notes": {
+      // GET /notes — rank: any-builder — GET /notes
+      getNotes: (args) => request("GET", "/notes", { hasBody: false }, args),
+      // POST /notes — rank: any-builder — POST /notes
+      postNotes: (args) => request("POST", "/notes", { hasBody: true }, args),
+      // DELETE /notes/{id} — rank: any-builder — DELETE /notes/:id
+      deleteNotesId: (args) => request("DELETE", "/notes/{id}", { hasBody: false }, args),
+      // PATCH /notes/{id} — rank: any-builder — PATCH /notes/:id
+      patchNotesId: (args) => request("PATCH", "/notes/{id}", { hasBody: true }, args),
+    },
     "npmRelease": {
       // DELETE /npm-release/preview — rank: any-builder — DELETE /npm-release/preview
       deleteNpmReleasePreview: (args) => request("DELETE", "/npm-release/preview", { hasBody: false }, args),
@@ -914,6 +974,40 @@ export function createClient(opts = {}) {
       // GET /page-notes/site — rank: any-builder — GET /page-notes/site
       getPageNotesSite: (args) => request("GET", "/page-notes/site", { hasBody: false }, args),
     },
+    "payouts": {
+      // POST /payouts/age-records — rank: archon — POST /payouts/age-records
+      postPayoutsAgeRecords: (args) => request("POST", "/payouts/age-records", { hasBody: true }, args),
+      // GET /payouts/approvals — rank: archon — GET /payouts/approvals
+      getPayoutsApprovals: (args) => request("GET", "/payouts/approvals", { hasBody: false }, args),
+      // POST /payouts/approve — rank: archon — POST /payouts/approve
+      postPayoutsApprove: (args) => request("POST", "/payouts/approve", { hasBody: true }, args),
+      // POST /payouts/contracts — rank: archon — POST /payouts/contracts
+      postPayoutsContracts: (args) => request("POST", "/payouts/contracts", { hasBody: true }, args),
+      // POST /payouts/freezes — rank: archon — POST /payouts/freezes
+      postPayoutsFreezes: (args) => request("POST", "/payouts/freezes", { hasBody: true }, args),
+      // POST /payouts/freezes/{id}/decide — rank: archon — POST /payouts/freezes/:id/decide
+      postPayoutsFreezesIdDecide: (args) => request("POST", "/payouts/freezes/{id}/decide", { hasBody: true }, args),
+      // GET /payouts/gates/{builderId} — rank: archon — GET /payouts/gates/:builderId
+      getPayoutsGatesBuilderId: (args) => request("GET", "/payouts/gates/{builderId}", { hasBody: false }, args),
+      // POST /payouts/grants — rank: archon — POST /payouts/grants
+      postPayoutsGrants: (args) => request("POST", "/payouts/grants", { hasBody: true }, args),
+      // POST /payouts/guardians — rank: archon — POST /payouts/guardians
+      postPayoutsGuardians: (args) => request("POST", "/payouts/guardians", { hasBody: true }, args),
+      // GET /payouts/rules — rank: archon — GET /payouts/rules
+      getPayoutsRules: (args) => request("GET", "/payouts/rules", { hasBody: false }, args),
+      // POST /payouts/rules — rank: archon — POST /payouts/rules
+      postPayoutsRules: (args) => request("POST", "/payouts/rules", { hasBody: true }, args),
+      // POST /payouts/rules/{id}/narrow — rank: archon — POST /payouts/rules/:id/narrow
+      postPayoutsRulesIdNarrow: (args) => request("POST", "/payouts/rules/{id}/narrow", { hasBody: true }, args),
+      // POST /payouts/rules/{id}/revoke — rank: archon — POST /payouts/rules/:id/revoke
+      postPayoutsRulesIdRevoke: (args) => request("POST", "/payouts/rules/{id}/revoke", { hasBody: true }, args),
+      // POST /payouts/rules/{id}/runs — rank: archon — POST /payouts/rules/:id/runs
+      postPayoutsRulesIdRuns: (args) => request("POST", "/payouts/rules/{id}/runs", { hasBody: true }, args),
+      // POST /payouts/rules/{id}/runs/{runKey}/hold — rank: archon — POST /payouts/rules/:id/runs/:runKey/hold
+      postPayoutsRulesIdRunsRunKeyHold: (args) => request("POST", "/payouts/rules/{id}/runs/{runKey}/hold", { hasBody: true }, args),
+      // POST /payouts/screenings — rank: archon — POST /payouts/screenings
+      postPayoutsScreenings: (args) => request("POST", "/payouts/screenings", { hasBody: true }, args),
+    },
     "profiles": {
       // GET /profiles/{handle} — rank: public — GET /profiles/:handle
       getProfilesHandle: (args) => request("GET", "/profiles/{handle}", { hasBody: false }, args),

package/docs/adr/0054-session-token-reward-cost-plus.md

@@ -2,9 +2,11 @@
 
 **Date:** 2026-06-13
 **Context:** GDS-V4, task [#1005](https://example.com/builders#/task/1005). Builds on [ADR 0023](0023-kind-multipliers-and-idea-bonus.md) (per-task kind-multiplied credits), [ADR 0028](0028-honest-llm-spend-accounting.md) (the `llm-pricing.js` token→USD table + session-cost capture), and [ADR 0027](0027-bfg-session-inefficiency-evaluator.md) (the `session_records` upload-on-ship path this reward rides). Complements — does **not** replace — the per-task `credits_reward × kind_multiplier` path. Related future work: the full-transcript capture ADR (planned, task [#1004](https://example.com/builders#/task/1004)) will give this reward a more trustworthy raw-usage source, and the token-feed hardening scoped in task [#1005](https://example.com/builders#/task/1005) itself.
-**Status:** Accepted.
+**Status:** Accepted. Superseded in part by [ADR 0385](0385-money-lives-with-a-processor-credits-stay-a-project-meter.md) and [ADR 0387](0387-two-ledgers-credits-measure-work-money-stays-with-the-processor.md) (credits are a contribution meter, not equity or money).
 **Track:** `internal` (development system / methodology).
 
+> **Superseded in part (owner ruling, 2026-10-29; [ADR 0385](0385-money-lives-with-a-processor-credits-stay-a-project-meter.md) decision 2, [ADR 0387](0387-two-ledgers-credits-measure-work-money-stays-with-the-processor.md)).** The framing below that credits ("example") are **equity**, a stake or units of ownership, and the 2026-06-15 reading that **1 drachma = $1**, no longer hold. Credits are a project-scoped contribution meter: never money, never redeemable, never equity, and no dollar value is read off them. Equity, if a project offers any, is granted by that project separately. The formula itself is unchanged: the session reward is still *sized by* the session's cost in USD plus the margin. The waste mitigation in reason 2 below ("a builder who pads cost dilutes a pool they hold") rested on the equity framing and no longer applies. The rest of this ADR (server-side pricing, PASS gate, idempotency per session) stands.
+
 ## Problem
 
 We are about to onboard the first **incentivized** builders. Today the only payout is per-task `credits_reward` — a unitless number an author sets at task-creation time. It rewards declaring a big number, not doing expensive, real work. The owner's decision (2026-06-13) is to pay builders proportionally to the **true economic cost** of the work they did — the API token spend of the session — plus a margin, with example standing in as **equity** in the project. It must go live today, be idempotent and reversible, and be impossible to inflate with a client-sent dollar figure.

package/docs/adr/0055-server-mediated-branch-publish.md

@@ -62,4 +62,4 @@ A **fine-grained GitHub PAT** scoped to the single repo: `Contents: read/write`
   confirmed->shipped flip.
 
 - **Residual:** the server verifies the bundle tip == the claimed sha and that the caller holds the claim, but does not cheaply prove every commit in the bundle was authored under the claim — branch protection + required checks on `main` (which the credential cannot bypass) are the real gate, exactly as for any PR.
-- **Operator action — DONE (blocker 31, resolved 2026-06-13):** the GitHub App was created and `GITHUB_APP_ID` + `GITHUB_APP_INSTALLATION_ID` + `GITHUB_APP_PRIVATE_KEY` set on the droplet (task 1043); `GITHUB_PUSH_TOKEN` then removed. To rotate the key: generate a new private key in the App's settings, replace `GITHUB_APP_PRIVATE_KEY` (single-line, literal `\n`) in `/etc/example/web-source.env`, restart `example`. To roll back to the PAT: restore `web-source.env.bak-task1043` and set a fresh `GITHUB_PUSH_TOKEN` (with the App vars absent, `resolveToken()` falls back to the PAT).
+- **Operator action — DONE (blocker 31, resolved 2026-06-13):** the GitHub App was created and `GITHUB_APP_ID` + `GITHUB_APP_INSTALLATION_ID` + `GITHUB_APP_PRIVATE_KEY` set on the droplet (task 1043); `GITHUB_PUSH_TOKEN` then removed. To rotate the key: generate a new private key in the App's settings, replace `GITHUB_APP_PRIVATE_KEY` (single-line, literal `\n`, wrapped in double quotes — unquoted, systemd drops the backslashes and the key no longer decodes; task 1005009) in `/etc/example/web-source.env`, restart `example`. To roll back to the PAT: restore `web-source.env.bak-task1043` and set a fresh `GITHUB_PUSH_TOKEN` (with the App vars absent, `resolveToken()` falls back to the PAT).

package/docs/adr/0385-money-lives-with-a-processor-credits-stay-a-project-meter.md

@@ -0,0 +1,87 @@
+# 0385 — Money lives with a processor, credits stay a project meter, and the project sets the pay
+
+- **Status:** Accepted, except decision 4 (the signed payout rule), which is Proposed until counsel answers held item 1
+- **Date:** 2026-10-28
+- **Deciders:** The owner, who wrote the legal framework this applies and chose each point below in conversation: a licensed processor holds the money; projects set their own pay and funding rules; Cloud Bongos LLC takes 1% on top of module sales; the default credit system is Bongos's current one.
+- **Tasks:** [task 1004905](https://cloudbongos.com/builders#/task/1004905) (the legal map), [task 1003180](https://cloudbongos.com/builders#/task/1003180) (one credit, one meaning), [task 1003181](https://cloudbongos.com/builders#/task/1003181) (where the wall sits), [task 1004909](https://cloudbongos.com/builders#/task/1004909) (module revenue split). Goal 1000092.
+- **Interacts with:** [ADR 0054](0054-session-token-reward-cost-plus.md) (credit denomination), [ADR 0120](0120-pay-on-land-and-builder-owned-rebase-gate.md) (a claim-time refusal precedent).
+
+The owner's legal framework is a confidential draft. This record cites it by Article only and quotes none of it. It is a product constraint for building, not legal advice; counsel confirms the items under "Held for counsel".
+
+## Context
+
+Goal 1000092 pays real money for completed work: our own contractors first, then builders on projects and contributors to modules that sell. ADR 0054 left one credit meaning two things on one ledger, and the first design put a balance and a wallet inside Bongos. The legal framework forbids that shape: the platform may not hold user money (Art. II), nor build credits that redeem for cash, and it may not assign work or set rates (Art. IV).
+
+## Decision
+
+**1. A licensed payment processor holds all user and project money. Bongos holds none.** Bongos shows balances read from the processor, records every movement and its cause (append-only), and instructs transfers on a project's authorisation. No wallet, no netting between users, no float.
+
+**2. Credits are a project-scoped contribution meter, never money.** Credits belong to the project that issued them, are not transferable or purchasable, and are not redeemable for cash. The Bongos Standard Credit System is the default a project adopts; a project may change or replace it. Existing credit records keep their meaning and are not converted to dollars (this closes the double denomination in ADR 0054 by splitting the ledgers, not by re-denominating).
+
+**3. The project decides what its work pays and in what form.** Cash through the processor, equity granted by the project, a share of module sales, or non-monetary credit. The project also sets its funding rule: refuse claims when funds run out, hold the estimate at claim, or continue with the shortfall recorded as the project's own obligation. Bongos suggests no rate. The builder sees the pay terms before claiming.
+
+**4. Money moves under the project's signed instruction.** A person with the project's authority signs a payout rule once (caps, formula, schedule), and runs execute under it with a notice and a pause window before each. Equity grants and contracts keep one signature each. An AI never creates or widens an authorisation. The authorisations and runs sit in an append-only log. This is a proposal for counsel (item 1 below).
+
+**5. Three payment paths.** Bongos rails, self-managed (the project pays on its own systems and Bongos only records contribution), or both per pay type. Bongos shows no balance or guarantee for money it does not move.
+
+**6. Module sales carry a platform fee of the processor's cost plus 1 percent of the price** (amended by [ADR 0388](0388-a-module-sale-is-split-by-the-project-the-buyer-pays-the-platform-fee.md); first recorded here as a flat 1 percent). It is added on top of the price, paid by the buyer, collected for Cloud Bongos LLC through the processor, and is never deducted from a contributor or described as a share of pay. How a project prices and divides its modules is the project's choice. No percentage fee applies to wages, task pay or equity. Standard module licence and takedown contact must exist before the first sale.
+
+**7. Crypto stays out.** Processor-converted stablecoin payouts are reserved for a later board decision with counsel.
+
+**8. Each pay type clears its own legal gate before it can be switched on** (the table under "Pay-type gates" below). Age tiers and sanctions screening apply to every payout (Art. VII, X); a freeze notifies the person and offers an appeal.
+
+**9. Credit and model wording.** Nothing the product or an AI writes about credits or valuation models may call them an investment, a return, appreciation or passive income (Art. III). Models are calculation tools with every input visible to the people affected; they create no payment obligation and no redemption price.
+
+## Per-flow map
+
+Each flow names the processor primitive it maps to (a flow with none is redesigned, not custom-built), the legal actor, and the Article that limits it. The primitive names are generic processor terms; the processor is chosen in [task 1004906](https://cloudbongos.com/builders#/task/1004906), which confirms the exact product for each row.
+
+| Flow | Processor primitive | Legal actor | Limits |
+| --- | --- | --- | --- |
+| Project funding | Charge to the funder, settled into the project's processor-held account | The funder and the project | Art. II no custody, no float |
+| Balance view | Read of the processor-held balance | Nobody acts; display only | Art. II no wallet or internal ledger of user money |
+| User-to-user payment | Transfer between processor-held accounts on the payer's instruction | The payer | Art. II no netting; sanctions and age checks (Art. VII, X) |
+| Builder payout | Transfer from the project's account to the builder, under a signed rule | The project | Art. I signed authorisation and log; Art. IV no rate set by Bongos |
+| Contractor pay (our own) | Same transfer, Cloud Bongos acting as a project | Cloud Bongos as the project | Art. XI NDA and tax details first; Art. IV classification |
+| Cash-out | Payout from the processor-held account to the user's bank, on the user's instruction | The user | Art. II no custody; age and sanctions checks; a freeze notifies |
+| Module sale | Charge to the buyer with an application fee, then transfers to seller and contributors | Buyer, seller and project | Art. VI licence and takedown first; fee only the buyer-paid platform fee of ADR 0388 |
+
+The five gate questions (actor, custody, securities wording, control, advice) are answered per row above: the actor column is the actor test, "no custody" and "no wallet" are the custody test, decision 9 is the securities-wording test, decisions 3 and 4 are the control test, and models are tools, not advice (Art. V).
+
+## Pay-type gates
+
+A pay type becomes switchable only after its gate is cleared and recorded.
+
+| Pay type | Law that applies | Carried by | Must exist first |
+| --- | --- | --- | --- |
+| Cash for task work | Contractor classification, tax reporting, sanctions, age rules | Project; processor screens | Processor onboarding, tax details, age check, sanctions screening, signed rule |
+| Equity or profit interests | Securities law; Art. III | Project; Bongos records at a flat fee | The project's own counsel-approved structure, one signature per grant, no percentage fee, wording filter |
+| Module sales share | Marketplace venue, takedown, tax reporting | Seller and project; Cloud Bongos LLC as venue | Standard module licence, takedown contact, payee onboarding |
+| Credit-weighted pool | Cash rules plus Art. III | Project | Decision 9 in force, model inputs visible, signed rule |
+| Non-monetary tracks | Volunteer and learner rules; Art. VII | Project | Guardian consent for ages 13 to 15, no cash redemption of any credit |
+| Self-managed payout | The project's own obligations | Project alone | A label saying Bongos moves and guarantees nothing |
+| EU labour payments | EU Platform Work Directive | Project; Verro | Not enabled until the per-country analysis is complete (Art. IV) |
+
+## Held for counsel (these block building the money-moving tasks)
+
+1. Whether a standing signed payout rule satisfies the attributable-action requirement (Art. I).
+2. Whether a credit-weighted pool distribution creates stored value, a security, or a wage-style fee problem.
+3. Agent-of-payee versus full pass-through, and which processor (decided in [task 1004906](https://cloudbongos.com/builders#/task/1004906)).
+4. Which entity collects the fee and which is the payee's agent.
+5. Whether processor-converted stablecoin counts as touching crypto rails.
+6. Whether a sibling entity is needed for labour payouts.
+
+## Consequences
+
+- [task 1003182](https://cloudbongos.com/builders#/task/1003182) (the project account) becomes a processor-held account with a record of its movements; it holds nothing itself.
+- [task 1003183](https://cloudbongos.com/builders#/task/1003183) pays under a signed authorisation, once per builder and task.
+- [task 1003185](https://cloudbongos.com/builders#/task/1003185) builds the funding rule as a per-project setting, with claim-time hold as an option and no wall by default imposed by Bongos.
+- No task that moves real money ships before the processor is chosen and counsel clears items 1 to 4.
+- Decisions 4 and 8 are intent until built. The tasks that build them ([task 1004913](https://cloudbongos.com/builders#/task/1004913) and [task 1004914](https://cloudbongos.com/builders#/task/1004914)) must enforce them on the server, with the rank and ownership check in the database, not in the screen (ADR 0016).
+
+## Rejected
+
+- **A wallet inside Bongos.** Makes us the holder of user money (Art. II).
+- **Converting credits to cents.** Turns the meter into stored value.
+- **Bongos setting rates or a standard wall.** Breaks the contractor classification (Art. IV).
+- **A per-run approval click on every payout.** Safest reading, but unworkable for recurring pools; replaced by the signed rule in decision 4, pending counsel.

package/docs/adr/0386-the-funding-wall-is-a-per-project-rule-claim-time-hold-by-default.md

@@ -0,0 +1,37 @@
+# 0386 — The funding wall is a per-project rule, with a claim-time hold on offer
+
+- **Status:** Accepted
+- **Date:** 2026-10-28
+- **Deciders:** The owner, who first asked that a project not complete work without money in its account, was shown that a completion-only gate lands the loss on the builder, and then ruled that the rule belongs to each project: whether to halt, pay in another form, or carry on is the project's choice.
+- **Task:** [task 1003181](https://cloudbongos.com/builders#/task/1003181)
+- **Related:** [ADR 0385](0385-money-lives-with-a-processor-credits-stay-a-project-meter.md) (money lives with a processor; projects set pay), [ADR 0120](0120-pay-on-land-and-builder-owned-rebase-gate.md) (a claim-time refusal with a stated reason).
+
+## Context
+
+The owner's first design was a completion gate: a project should not be able to have work completed when it lacks the money. The concern recorded on the task is that cost is incurred during the work, so a completion-only gate lets a builder finish and only then learn the project cannot pay. A claim gate refuses before anyone has spent anything, and ADR 0120 already shows a claim refusal with a legible reason. A third shape holds the task's estimate against the balance so several simultaneous claims cannot overspend it.
+
+The owner then settled that Bongos does not impose any one of these. A project sets what its work pays and what happens when it runs short (ADR 0385), and the legal framework bars the platform from setting or capping builder rates (Art. IV).
+
+## Decision
+
+**The wall is a per-project setting with three options, and Bongos sets no wall of its own.**
+
+1. **Hold at claim.** A claim is refused, with the stated shortfall, when the project's available balance cannot cover the task's estimate. The estimate is held against the balance while the claim is open, so claims cannot over-commit it. The hold is released on ship or release.
+2. **Refuse at completion.** The task can be claimed and worked; completing it is refused while the balance is short. This is the owner's original design, kept as an option.
+3. **Carry on, record the shortfall.** Work continues and the unpaid amount is recorded as the project's own obligation. Bongos never funds it.
+
+A project that sets nothing gets option 1, because it is the only option that protects the builder before work is done. Setting it is the project's to change at any time; each builder sees the project's rule on the task before claiming.
+
+The balance the wall reads is the processor-held project balance (ADR 0385). A wall on a pay type that is not cash (equity, a share of module sales, non-monetary credit) reads the project's own terms for that pay type, not a dollar balance.
+
+## Consequences
+
+- [task 1003185](https://cloudbongos.com/builders#/task/1003185) builds the wall as this setting, with the three options and the claim-time hold. It must put the refusal at the claim route, the one place the server can stop a claim, and show the shortfall in plain words.
+- [task 1003182](https://cloudbongos.com/builders#/task/1003182) exposes the held amount alongside the balance so the owner can see what is reserved.
+- The check is server-side. A screen that hides the Claim button is not the wall (ADR 0016).
+- Option 3 creates an obligation on the project's side only. It must show as owed-but-unpaid in the outflow view ([task 1003184](https://cloudbongos.com/builders#/task/1003184)).
+
+## Rejected
+
+- **A completion gate for every project.** Leaves the loss with the builder, who cannot check beforehand.
+- **One wall chosen by Bongos.** Bongos would be setting terms of work, which the contractor classification depends on it not doing.

package/docs/adr/0387-two-ledgers-credits-measure-work-money-stays-with-the-processor.md

@@ -0,0 +1,39 @@
+# 0387 — Two ledgers: credits measure work, money stays with the processor
+
+- **Status:** Accepted
+- **Date:** 2026-10-28
+- **Deciders:** The owner, who asked how credits can measure contribution while pay is set by each project, and chose to keep credits as a project-scoped meter and put money on a separate record held by a licensed processor.
+- **Task:** [task 1003180](https://cloudbongos.com/builders#/task/1003180)
+- **Related:** [ADR 0385](0385-money-lives-with-a-processor-credits-stay-a-project-meter.md) (the money plan), [ADR 0054](0054-session-token-reward-cost-plus.md) (the double denomination this resolves), [ADR 0146](<redacted><redacted>.md) (reward mode per instance).
+
+This applies the owner's confidential legal framework by Article only: credits are a work meter, never redeemable for cash, never bought or transferred (Art. II, III). It is a product constraint, not legal advice.
+
+## Context
+
+ADR 0054 accepted a credit meaning two things on one ledger: a unitless author estimate (the per-task path) and a dollar-scale figure from real cost plus 20 percent (the session path). It named the way out: re-denominate per-task credits in cents, or split the ledgers, and said it must be settled before money moves. Paying cash against a number that means two things makes the first dispute unanswerable.
+
+## Decision
+
+**Split the ledgers. Do not re-denominate credits into cents.**
+
+1. **Credits stay a work meter.** `credit_log` keeps measuring contribution, scoped to its project, non-transferable, non-purchasable, never redeemable. It gets no money column and no dollar conversion.
+2. **Money gets its own record, in cents, tied to the processor.** The project-account work ([task 1003182](https://cloudbongos.com/builders#/task/1003182)) adds a separate movement record: integer cents, the processor's transfer reference (the Transfer primitive in the per-flow map of [ADR 0385](0385-money-lives-with-a-processor-credits-stay-a-project-meter.md)), and the cause (who, which task or module or pool run, why). It records money held elsewhere and holds none itself. It is append-only and never edited; a correction is a new movement. The database enforces this (updates and deletes refused by a trigger or revoked privilege), not only the code that writes it.
+3. **No dollar value is ever read off a credit.** A payout reads the money record and the project's signed rule, not a credit delta. Where a project pays by contribution, the payout is a pool run: the project's pool of cents is divided by credit share, and the run is recorded on the money ledger with the shares used. Only the project's authorised person, acting under the signed rule of ADR 0385 decision 4, may start a pool run, and the server checks that authority against the database on every run; a screen that hides the button is not the check (ADR 0016).
+4. **Historic `credit_log` rows are not rewritten and not retro-classified.** They carry both old meanings and cannot be told apart by inspection, so they keep both and are used only as relative weight inside a project, never as a dollar amount. A pool run that includes them says so in the shares it shows the affected people.
+5. **A pool run says which credit rows it counts.** The default reward mode (ADR 0146, `cost-plus-and-estimate`) still writes two kinds of new rows to the same total: a per-task estimate row and a session cost-plus row. A project's model must name the row kinds it counts as weight. The default model counts the session cost-plus rows only, and a project that adds estimate rows says so in the shares it shows. Where an instance runs cost-plus-only, only the session rows exist. Estimate rows are never a basis for paying money by themselves.
+
+## Migration path
+
+None for existing rows: no rewrite, no backfill, no new column on `credit_log`. The only schema change is the new money record, which lands with [task 1003182](https://cloudbongos.com/builders#/task/1003182) and its migration. Reading historic credits as weight needs no change. If a project later wants historic work weighed differently, it changes its model parameters; it does not edit the ledger.
+
+## Consequences
+
+- A payout dispute has one answer: the money record names the cents, the processor reference and the signed rule; the credit record names the work.
+- [task 1003182](https://cloudbongos.com/builders#/task/1003182) and [task 1004907](https://cloudbongos.com/builders#/task/1004907) build against the money record and never against `credit_log`.
+- [task 1003182](https://cloudbongos.com/builders#/task/1003182) also owns the guard: a test that fails the build if any money path reads a credit delta as dollars, and one that fails if the money record accepts an update or delete.
+- [task 1003186](https://cloudbongos.com/builders#/task/1003186), the end-to-end proof, must show a pool run that counts only the row kinds its model names.
+
+## Rejected
+
+- **Re-denominate credits into cents.** Credits would carry a dollar value and become stored value (Art. II, III), and the old rows still could not be classified.
+- **A conversion rate between credits and dollars.** The same problem with a rate on it; Bongos must not publish a redemption price for a credit.

package/docs/adr/0388-a-module-sale-is-split-by-the-project-the-buyer-pays-the-platform-fee.md

@@ -0,0 +1,42 @@
+# 0388 — A module sale is split by the project's own rule, and the buyer pays the platform fee on top
+
+- **Status:** Accepted
+- **Date:** 2026-10-28
+- **Deciders:** The owner, who set the platform's take at processing cost plus 1 percent on module sales, paid on top of the price, and ruled that each project decides how its modules are monetised and how the money is shared, including a project that is paid only through module sales.
+- **Task:** [task 1004909](https://cloudbongos.com/builders#/task/1004909)
+- **Amends:** [ADR 0385](0385-money-lives-with-a-processor-credits-stay-a-project-meter.md) decision 6 and its module-sale row: the fee is the processor's cost plus 1 percent, not a flat 1 percent. ADR 0385 is updated to point here.
+- **Related:** [ADR 0385](0385-money-lives-with-a-processor-credits-stay-a-project-meter.md) (the money plan and per-flow map), [ADR 0387](0387-two-ledgers-credits-measure-work-money-stays-with-the-processor.md) (pool runs by credit share).
+
+This applies the owner's confidential legal framework by Article only (Art. IV, VI, VIII). It is a product constraint, not legal advice.
+
+## Context
+
+A module that sells earns money for the people who built it and for whoever sells it. The question was how that money is divided between the contributors, the seller and the platform. The framework allows a venue and processing fee attached to a transaction and forbids describing any fee as a share of wages (Art. IV). Working area 5 owns module pricing and listing; this goal owns only how the money is divided and paid.
+
+## Decision
+
+**1. The buyer pays the price plus a platform fee.** The platform fee is the processor's cost for that sale plus 1 percent of the price, added on top, shown as its own line before purchase, and collected for Cloud Bongos LLC through the processor's application fee. Nothing is deducted from the price the seller and contributors share. The fee is called a platform fee and nothing else. Which entity collects it stays held for counsel (ADR 0385 held item 4); Cloud Bongos LLC is the owner's intended collector, not a settled fact.
+
+**2. The project that owns the module sets the split.** Before a paid listing goes live, the project records its rule: the seller's share and the contributors' pool, as percentages of the price. Only the project's authorised person may record or change the rule, and the server checks that authority against the database on every write (ADR 0016); a change is logged like a signed payout rule (ADR 0385 decision 4). Bongos suggests no percentage and does not list a paid module that has no rule. The project can change the rule for future sales; past sales keep the rule they sold under.
+
+**3. The contributors' pool is divided by recorded contribution.** By default the weight is the credit each contributor earned on the module's own tasks, counted as ADR 0387 says (session cost-plus rows by default). A project may choose another model. Either way every input and each person's share is visible to the people it affects before money moves (Art. VIII). Only shipped, graded tasks the project placed on the module count, so a builder cannot raise their share by creating tasks for themselves, and the project sees the shares before each payout run. This default is subject to ADR 0385 held item 2 (whether a credit-weighted pool raises a legal problem).
+
+**4. Module sales can be a project's only pay.** A project may choose module revenue as the pay form for its work (ADR 0385 decision 3). Builders see that before claiming.
+
+**5. The money path is the module-sale row of ADR 0385's per-flow map.** A charge to the buyer with the application fee, then transfers from the project's processor-held account to the seller and to each contributor, under the project's signed payout rule. Bongos holds none of it.
+
+**6. Refunds reverse the same way.** A refunded or charged-back sale reverses each transfer in the same proportion it was paid, and the reversal is recorded on the money record against the original sale.
+
+**7. Nothing sells before its prerequisites exist.** The standard module licence, a registered copyright takedown agent, processor onboarding (identity and tax details) for every person who will be paid (Art. VI), and counsel's answers to ADR 0385 held items 2 and 4. No task tracks the licence or the takedown agent yet; they belong with Working area 5, and [task 1004910](https://cloudbongos.com/builders#/task/1004910) must not ship until they exist.
+
+## Consequences
+
+- [task 1004910](https://cloudbongos.com/builders#/task/1004910) builds this: the split rule on the listing, the share calculation, and the transfers. Amounts are computed on the server from the recorded rule and the processor's reported sale, never taken from the buyer's or seller's screen.
+- Working area 5 shows the platform fee line at checkout and refuses a paid listing with no split rule.
+- [task 1004906](https://cloudbongos.com/builders#/task/1004906) confirms the processor supports an application fee and transfers to several recipients from one sale.
+
+## Rejected
+
+- **A fixed 50/50 split chosen by Bongos.** Offered as a placeholder; the owner ruled the split is each project's to set.
+- **Taking the platform fee out of the price.** It would be deducted from what contributors are paid, which the framework treats as a cut of wages (Art. IV).
+- **Crypto settlement for higher margin.** Excluded by ADR 0385 decision 7; the fee is the same either way.

package/docs/adr/0392-ai-generation-runs-on-a-processor-held-balance-and-the-builders-own-keys.md

@@ -0,0 +1,33 @@
+# 0392 — AI generation runs on a processor-held balance or the builder's own key
+
+- **Status:** Accepted
+- **Date:** 2026-10-28
+- **Task:** [task 1004916](https://cloudbongos.com/builders#/task/1004916) (goal 1000136)
+- **Deciders:** the owner (prepaid balance, multiplier 1.08 final, funds secured before a run); Claude designed
+- **Related:** ADR 0016 (trust boundary), 0022 (secrets), 0054 (credits), 0073 (BYOK Gemini key), 0083 (modules), **0385 (money lives with a processor)**
+
+## Context
+
+Artists in the Studio want to submit a sketch or image set with a prompt, get a Gemini reply, and get images generated (OpenRouter) with the project's context added. Two ways to pay: our provider key (we charge the builder) or the builder's own key (we charge nothing).
+
+There is no way to take money in the code today. Credits (ADR 0054) are what builders **earn**; `credit_log` is an earnings ledger, the wrong place for money a builder **pays**. And ADR 0385 rules that Bongos holds no user money: no wallet, no internal balance, no float. A balance table of our own is therefore not allowed.
+
+Card processors also charge about 2.9% plus a fixed $0.30 per payment, so charging a card for each few-cent generation loses money unless that fee is passed on.
+
+## Decision
+
+1. **A new `ai-studio` module** owns keys, the ledger, requests and routes. `default: false` (the hub first), like `raise`.
+2. **The balance lives with the processor, never with us (ADR 0385).** A builder tops up a processor-held balance; Bongos only **reads** it and **instructs holds and captures** against it. We keep no balance column. What we do keep is the append-only ledger of every movement and its cause, which ADR 0385 requires.
+3. **Price = provider cost x `AI_PRICE_MULTIPLIER`**, one named constant in `modules/ai-studio/pricing.js`, **1.08** (owner, final: an 8% markup on the actual provider cost of every call: OpenRouter, Gemini, anything). Nothing else spells the number.
+4. **The processor's cost is added to the top-up, not eaten.** A builder who wants N dollars of balance pays `(N + fixed) / (1 - percent)`, rounded up, so what we receive after the processor's fee covers N. Fixed and percent are named constants beside the multiplier.
+5. **Hold, then capture.** Before any provider call the full estimated price is **held** on the processor-held balance. A short balance refuses cleanly and nothing runs. After the call the hold is captured at the real price (the difference released); if the provider fails the whole hold is released. A hold is exactly the guarantee the owner asked for: the funds are secured before the run and never touch a Bongos balance.
+6. **One append-only ledger.** Every movement (top-up, hold, capture, release) is a row with amount, provider cost, markup and processor fee as separate columns, so a builder sees exactly what a generation cost. Money is integer micro-dollars (millionths), never floats.
+7. **A payments port with two backends.** `fake` (test mode, deterministic, in memory, the only one built now; it stands in for the processor's held balance) and a real processor adapter, added later when the owner supplies keys in Settings. Everything else is backend-independent.
+8. **Bring your own key.** A builder's own provider key is entered **only in Settings**, encrypted with the existing secret box (ADR 0073), shown as its last four characters, **never returned to the browser or logged**. When one is set for the provider a generation needs, the generation runs on it with no hold and the ledger records a zero charge, with the real provider cost noted for the builder's information.
+9. **Project context is assembled on the server** from the project context doc, the branding pack and DESIGN.md; the browser never supplies it.
+
+## Consequences
+
+- No parallel money system and no wallet: credits stay earnings, the ledger is an audit trail, the processor holds the money.
+- The tests pin the arithmetic (cost x 1.08, top-up gross-up), hold / refuse / capture / release, and that a key never leaves the server.
+- Real processor keys stay off until the owner adds them; going live waits for the owner.

package/docs/adr/0393-a-platform-account-is-a-person-and-github-is-one-way-in.md

@@ -0,0 +1,37 @@
+# 0393 — A platform account is a person, and GitHub is one way in
+
+- **Status:** Accepted
+- **Date:** 2026-10-29
+- **Task:** [task 1004992](https://cloudbongos.com/builders#/task/1004992) (goal 1000095, work area 6)
+- **Deciders:** the owner (Google as the only new way in, no email codes or passwords; GitHub and Google linkable both ways; never join accounts on a matching email); Claude designed
+- **Related:** ADR 0016 (trust boundary), **0141 (the hub is an identity provider)**, 0171 (profile consent), 0205 (the hub's own sign-in witness), 0213 (terms acceptance)
+
+## Context
+
+Every platform account on the hub was a GitHub account: `platform_identity_accounts` was keyed on GitHub's user id, and that column (`github_id`) is the join key of every other hub table and the identity every federated project receives at sign-in. A person without GitHub could not exist on the platform at all, so they could not ideate, do art or earn credits in any project, although none of that work touches GitHub.
+
+The owner wants people to sign up with Google, and GitHub and Google to be linkable to one account either way. GitHub stays necessary for two things only: creating a project (its code lives on GitHub) and engineering work.
+
+Renaming `github_id` everywhere was the obvious move and the wrong one: dozens of hub tables, every federated instance's `builders` table, and the wire format between them all carry it. A rename would be a breaking change across instances that upgrade on their own schedules.
+
+## Decision
+
+1. **An account is a person; its ways in are rows.** `platform_identity_account_logins` (migration 034) holds one row per provider identity: `(account, provider, subject)`, where `subject` is the provider's own stable user id (GitHub's numeric id, Google's `sub`). Never an email or a login: both can change hands.
+2. **The database enforces ownership.** `UNIQUE (provider, subject)`: a provider identity belongs to exactly one person. `UNIQUE (account, provider)`: a person holds at most one way in per provider. A `CHECK` lists the providers (`github`, `google`); a new one is a decision, not a string.
+3. **`github_id` keeps its name and becomes the person key.** Positive is the GitHub user id of a person who arrived through GitHub (every account before this change, unchanged). Negative is minted from `platform_identity_person_key_seq` for a person who arrived without GitHub. GitHub ids are positive, so a minted key can never collide with one, and a key never changes when a way in is linked or removed. No wire format changes.
+4. **`github_login` is NULL for a person with no GitHub linked.** Inventing a login would let a real GitHub user of that name be taken for this person by the invite-by-login path.
+5. **GitHub-born accounts need no writer change.** A trigger writes the `github` login row for every account inserted with a positive key, and the migration backfills every existing account. A non-GitHub account is born only through `createAccountForLogin`, which mints the key and writes the account and its way in in one transaction, and returns the existing person on a repeat or racing sign-up.
+6. **An email is shown, never looked up.** It is stored as the provider vouched for it, for the person's own settings. No lookup keys on it, so owning a matching address never reaches an account. Linking two ways in requires the person to be signed in to both (the owner: suggest a link on a matching email, never join one).
+7. **Identity, never authority.** Nothing here carries a rank, a credit or an admission (ADR 0016, ADR 0141).
+
+## Consequences
+
+- A person key no longer says which provider someone used. Code that needs to talk to GitHub must ask for the linked GitHub login, never assume the key is a GitHub id. The hub's numeric-key guard (`isNumericGithubId`) now admits a negative key and still refuses a `system:*` principal.
+- **Every sign-in must resolve the person through the logins table first** once linking exists. Until then the mapping is trivially exact (a GitHub-born key IS its GitHub id), but the moment GitHub can be linked to a Google-born account, a GitHub sign-in that keys straight on the GitHub id would create a second person. The linking task (task 1004995) must route GitHub sign-ins through `findPersonByLogin` before it lets anyone link.
+- Federated projects will start receiving negative keys when Google-born people sign in to them. An instance's `builders.github_id` is text, so it stores one, but any instance code that assumes a GitHub-shaped id must be found and fixed before those people are admitted (task 1004994), and an older core should not be sent one.
+- A minted key's fallback handle reads `builder--N`; the handle normally grows from the name the provider gave.
+- The own-scope read `GET /me/sign-in-methods` lists a person's ways in for account settings. The provider ids never cross.
+
+## What this does not do
+
+It adds no sign-in method by itself. Signing in with Google is task 1004993; halls admitting Google-born builders is task 1004994; linking both ways is task 1004995; the Link GitHub chip and the guided GitHub step are tasks 1004996 and 1004997.