@bongos/core 1.20.59 → 1.20.61

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 478 operations across 73 resource groups
+- 483 operations across 73 resource groups
 
 ## Use it from your project
 

package/clients/bongos-client/bongos-client.global.js

@@ -855,6 +855,14 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder — GET /provisioning/instances/:id/invite-suggestions
       getProvisioningInstancesIdInviteSuggestions: (args) => request("GET", "/provisioning/instances/{id}/invite-suggestions", { hasBody: false }, args),
+      // DELETE /provisioning/instances/{id}/logo — rank: any-builder — DELETE /provisioning/instances/:id/logo
+      deleteProvisioningInstancesIdLogo: (args) => request("DELETE", "/provisioning/instances/{id}/logo", { hasBody: true }, args),
+      // PUT /provisioning/instances/{id}/logo — rank: any-builder — PUT /provisioning/instances/:id/logo
+      putProvisioningInstancesIdLogo: (args) => request("PUT", "/provisioning/instances/{id}/logo", { hasBody: true }, args),
+      // GET /provisioning/instances/{id}/look — rank: any-builder — GET /provisioning/instances/:id/look
+      getProvisioningInstancesIdLook: (args) => request("GET", "/provisioning/instances/{id}/look", { hasBody: false }, args),
+      // PATCH /provisioning/instances/{id}/look — rank: any-builder — PATCH /provisioning/instances/:id/look
+      patchProvisioningInstancesIdLook: (args) => request("PATCH", "/provisioning/instances/{id}/look", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/render — rank: any-builder — GET /provisioning/instances/:id/render
       getProvisioningInstancesIdRender: (args) => request("GET", "/provisioning/instances/{id}/render", { hasBody: false }, args),
       // POST /provisioning/instances/{id}/render — rank: any-builder — POST /provisioning/instances/:id/render
@@ -871,6 +879,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/update-channel — rank: archon — POST /provisioning/instances/:id/update-channel
       postProvisioningInstancesIdUpdateChannel: (args) => request("POST", "/provisioning/instances/{id}/update-channel", { hasBody: true }, args),
+      // GET /provisioning/logos/{file} — rank: public — GET /provisioning/logos/:file
+      getProvisioningLogosFile: (args) => request("GET", "/provisioning/logos/{file}", { hasBody: false }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
       // GET /provisioning/recommendations — rank: public — GET /provisioning/recommendations

package/clients/bongos-client/index.cjs

@@ -854,6 +854,14 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder — GET /provisioning/instances/:id/invite-suggestions
       getProvisioningInstancesIdInviteSuggestions: (args) => request("GET", "/provisioning/instances/{id}/invite-suggestions", { hasBody: false }, args),
+      // DELETE /provisioning/instances/{id}/logo — rank: any-builder — DELETE /provisioning/instances/:id/logo
+      deleteProvisioningInstancesIdLogo: (args) => request("DELETE", "/provisioning/instances/{id}/logo", { hasBody: true }, args),
+      // PUT /provisioning/instances/{id}/logo — rank: any-builder — PUT /provisioning/instances/:id/logo
+      putProvisioningInstancesIdLogo: (args) => request("PUT", "/provisioning/instances/{id}/logo", { hasBody: true }, args),
+      // GET /provisioning/instances/{id}/look — rank: any-builder — GET /provisioning/instances/:id/look
+      getProvisioningInstancesIdLook: (args) => request("GET", "/provisioning/instances/{id}/look", { hasBody: false }, args),
+      // PATCH /provisioning/instances/{id}/look — rank: any-builder — PATCH /provisioning/instances/:id/look
+      patchProvisioningInstancesIdLook: (args) => request("PATCH", "/provisioning/instances/{id}/look", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/render — rank: any-builder — GET /provisioning/instances/:id/render
       getProvisioningInstancesIdRender: (args) => request("GET", "/provisioning/instances/{id}/render", { hasBody: false }, args),
       // POST /provisioning/instances/{id}/render — rank: any-builder — POST /provisioning/instances/:id/render
@@ -870,6 +878,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/update-channel — rank: archon — POST /provisioning/instances/:id/update-channel
       postProvisioningInstancesIdUpdateChannel: (args) => request("POST", "/provisioning/instances/{id}/update-channel", { hasBody: true }, args),
+      // GET /provisioning/logos/{file} — rank: public — GET /provisioning/logos/:file
+      getProvisioningLogosFile: (args) => request("GET", "/provisioning/logos/{file}", { hasBody: false }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
       // GET /provisioning/recommendations — rank: public — GET /provisioning/recommendations

package/clients/bongos-client/index.d.ts

@@ -124,6 +124,7 @@ export interface GetProvisioningGithubAppStatusResponse { ok: boolean; status: u
 export interface GetProvisioningHealthResponse { module: unknown; ok: boolean; coreVersion: unknown }
 export interface GetProvisioningInstancesIdEnvManifestResponse { instance: unknown; env_vars: unknown; environments: unknown; values_held: boolean; note: unknown }
 export interface GetProvisioningInstancesIdInviteSuggestionsResponse { suggested: unknown; seeking: unknown; reason: unknown; unavailable?: unknown }
+export interface GetProvisioningInstancesIdLookResponse { ok: boolean; look: unknown; options: unknown; logo_max_bytes: unknown }
 export interface GetProvisioningInstancesIdRenderResponse { ok: boolean; app: unknown; env_vars: unknown; values_held: boolean }
 export interface GetProvisioningInstancesIdResponse { instance: unknown; open_intent: unknown; github_app: unknown }
 export interface GetProvisioningInstancesIdSettingsResponse { ok: boolean; settings: unknown; planet: unknown; options: unknown }
@@ -224,6 +225,7 @@ export interface PatchProvisioningInstancesIdDetailRequest { description?: strin
 export interface PatchProvisioningInstancesIdDetailResponse { ok: boolean; description: unknown; detail: unknown; options: unknown; soft_limits: unknown; publish: unknown; modules: unknown; type: unknown }
 export interface PatchProvisioningInstancesIdEnvManifestVarIdRequest { name?: string; description?: string; environments?: unknown[]; required?: boolean }
 export interface PatchProvisioningInstancesIdEnvManifestVarIdResponse { ok: boolean; env_var: unknown; values_held: boolean }
+export interface PatchProvisioningInstancesIdLookRequest { look?: string; night_tint?: string; accent?: string }
 export interface PatchProvisioningInstancesIdSettingsResponse { ok: boolean; saved: unknown; planet: unknown; push: unknown }
 export interface PatchSpecialitiesIdRequest { name?: string; summary?: string; contract_md?: string; visibility?: string; sellable?: boolean; skills?: string[] }
 export interface PatchSpecialitiesIdResponse { speciality: unknown }
@@ -255,7 +257,7 @@ export interface PostAutonomyFenceGoalsRequest { goal_id: StringifiableId; note?
 export interface PostAutonomyFenceGoalsResponse { goal: unknown }
 export interface PostAutonomyFencePriorityRequest { goal_id?: StringifiableId }
 export interface PostAutonomyFenceRequest { enabled: boolean; reason?: string }
-export interface PostAutonomyHeartbeatRequest { host: string; pid?: number; started_at?: string; mode?: string; consecutive_failures?: number; last_event?: string; working_task_id?: number; working_goal_id?: number }
+export interface PostAutonomyHeartbeatRequest { host: string; pid?: number; started_at?: string; mode?: string; consecutive_failures?: number; last_event?: string; working_task_id?: number; working_goal_id?: number; head?: string; disk_head?: string; main_head?: string; claude_account?: string }
 export interface PostAutonomyHeartbeatResponse { ok: boolean; heartbeat: unknown }
 export interface PostBackupTriggerResponse { ok: boolean; message: unknown; started_at: unknown }
 export interface PostBlockersIdLinkRequest { task_id: StringifiableId }
@@ -503,6 +505,7 @@ export interface PutGovernmentRanksRankKeyPermissionsPermissionKeyResponse { ok:
 export interface PutMingleOptInRequest { opted_in: boolean }
 export interface PutMingleOptInResponse { opted_in: unknown; updated_at: unknown }
 export interface PutMingleProjectRequest { enabled: boolean }
+export interface PutProvisioningInstancesIdLogoRequest { image_b64: string; content_type: string }
 export interface PutRenderDeployAppRequest { ownerId?: string; serviceId?: string }
 export interface PutRenderDeployAppResponse { app: unknown }
 export interface PutSpecialitiesIdSkillsRequest { enabled_skills: string[] }
@@ -1294,6 +1297,14 @@ export interface BongosClient {
     postProvisioningInstancesIdGithubApp(args?: RequestArgs & { body?: PostProvisioningInstancesIdGithubAppRequest }): Promise<PostProvisioningInstancesIdGithubAppResponse>;
     /** GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder */
     getProvisioningInstancesIdInviteSuggestions(args?: RequestArgs): Promise<GetProvisioningInstancesIdInviteSuggestionsResponse>;
+    /** DELETE /provisioning/instances/{id}/logo — rank: any-builder */
+    deleteProvisioningInstancesIdLogo(args?: RequestArgs): Promise<ApiResponse>;
+    /** PUT /provisioning/instances/{id}/logo — rank: any-builder */
+    putProvisioningInstancesIdLogo(args: RequestArgs & { body: PutProvisioningInstancesIdLogoRequest }): Promise<ApiResponse>;
+    /** GET /provisioning/instances/{id}/look — rank: any-builder */
+    getProvisioningInstancesIdLook(args?: RequestArgs): Promise<GetProvisioningInstancesIdLookResponse>;
+    /** PATCH /provisioning/instances/{id}/look — rank: any-builder */
+    patchProvisioningInstancesIdLook(args?: RequestArgs & { body?: PatchProvisioningInstancesIdLookRequest }): Promise<ApiResponse>;
     /** GET /provisioning/instances/{id}/render — rank: any-builder */
     getProvisioningInstancesIdRender(args?: RequestArgs): Promise<GetProvisioningInstancesIdRenderResponse>;
     /** POST /provisioning/instances/{id}/render — rank: any-builder */
@@ -1310,6 +1321,8 @@ export interface BongosClient {
     postProvisioningInstancesIdTeardown(args?: RequestArgs): Promise<PostProvisioningInstancesIdTeardownResponse>;
     /** POST /provisioning/instances/{id}/update-channel — rank: archon */
     postProvisioningInstancesIdUpdateChannel(args?: RequestArgs): Promise<ApiResponse>;
+    /** GET /provisioning/logos/{file} — rank: public */
+    getProvisioningLogosFile(args?: RequestArgs): Promise<ApiResponse>;
     /** GET /provisioning/onboard-plan — rank: public */
     getProvisioningOnboardPlan(args?: RequestArgs): Promise<GetProvisioningOnboardPlanResponse>;
     /** GET /provisioning/recommendations — rank: public */

package/clients/bongos-client/index.mjs

@@ -851,6 +851,14 @@ export function createClient(opts = {}) {
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/invite-suggestions — rank: any-builder — GET /provisioning/instances/:id/invite-suggestions
       getProvisioningInstancesIdInviteSuggestions: (args) => request("GET", "/provisioning/instances/{id}/invite-suggestions", { hasBody: false }, args),
+      // DELETE /provisioning/instances/{id}/logo — rank: any-builder — DELETE /provisioning/instances/:id/logo
+      deleteProvisioningInstancesIdLogo: (args) => request("DELETE", "/provisioning/instances/{id}/logo", { hasBody: true }, args),
+      // PUT /provisioning/instances/{id}/logo — rank: any-builder — PUT /provisioning/instances/:id/logo
+      putProvisioningInstancesIdLogo: (args) => request("PUT", "/provisioning/instances/{id}/logo", { hasBody: true }, args),
+      // GET /provisioning/instances/{id}/look — rank: any-builder — GET /provisioning/instances/:id/look
+      getProvisioningInstancesIdLook: (args) => request("GET", "/provisioning/instances/{id}/look", { hasBody: false }, args),
+      // PATCH /provisioning/instances/{id}/look — rank: any-builder — PATCH /provisioning/instances/:id/look
+      patchProvisioningInstancesIdLook: (args) => request("PATCH", "/provisioning/instances/{id}/look", { hasBody: true }, args),
       // GET /provisioning/instances/{id}/render — rank: any-builder — GET /provisioning/instances/:id/render
       getProvisioningInstancesIdRender: (args) => request("GET", "/provisioning/instances/{id}/render", { hasBody: false }, args),
       // POST /provisioning/instances/{id}/render — rank: any-builder — POST /provisioning/instances/:id/render
@@ -867,6 +875,8 @@ export function createClient(opts = {}) {
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/update-channel — rank: archon — POST /provisioning/instances/:id/update-channel
       postProvisioningInstancesIdUpdateChannel: (args) => request("POST", "/provisioning/instances/{id}/update-channel", { hasBody: true }, args),
+      // GET /provisioning/logos/{file} — rank: public — GET /provisioning/logos/:file
+      getProvisioningLogosFile: (args) => request("GET", "/provisioning/logos/{file}", { hasBody: false }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
       // GET /provisioning/recommendations — rank: public — GET /provisioning/recommendations

package/docs/adr/0358-a-hall-wears-a-look-and-its-night-takes-a-tint.md

@@ -0,0 +1,52 @@
+# ADR 0358 — A hall wears a look, and its night takes a tint of it
+
+- **Status:** accepted
+- **Date:** 2026-09-30
+- **Task:** [task 1004421](https://cloudbongos.com/builders#/task/1004421) (BV2.PS06, goal 1000121 — project startup; spec `docs/specs/<redacted>.md` D2 and D8)
+- **Amends:** [ADR 0219](0219-a-look-is-a-branding-pack-the-style-library.md) Context §2 and the rejected "dark tier" alternative (a look could not carry a dark ground), and `DESIGN.md`'s "Pure black in dark" rule, for halls only
+- **Keeps:** [ADR 0204](0204-the-apex-is-dark-only.md) (the platform's own apex is dark-only, pure black), [ADR 0062 §3](0062-medusa-instance-model-decoupling.md) (the branding contract; still thirteen colours and two faces)
+- **Decided with:** the owner, 2026-09-30 — D2 in the planning session (the tint is allowed and on by default), and "a custom look is one accent used in both modes" the same day.
+
+## Context
+
+The project-startup flow lets a founder give a new project a look, so that a builder who works in several projects always knows which hall they are in. ADR 0219 already made a look a branding pack: thirteen colours and two font stacks, laid over the instance's pack. But it left two things out:
+
+1. **Nothing let the platform set a hall's look.** A look was a file an instance owner copied into `config/branding.json` by hand.
+2. **Every look's night was the same pure black.** The pack is one-mode, so in dark mode only the accent told one hall from another.
+
+The second is a world rule (`DESIGN.md`: "Pure black in dark"). It exists because the chrome sculpture's rendered plates composite into `#000000` with `lighten` and leave no seam. The owner decided (D2) that a hall may give that up: each look gets a subtle tinted night, on by default, and the founder can switch it off.
+
+## Decision
+
+**D1. The night tint is derived, never authored.** When a hall wears a look with the tint on, its four dark grounds take a small share of the look's own accent:
+
+| token | tinted night |
+|---|---|
+| `--bg`, `--bg-deep` | `color-mix(in srgb, var(--accent) 6%, #000000)` |
+| `--bg-frame` | `color-mix(in srgb, var(--accent) 6%, #08080a)` |
+| `--bg-card` | `color-mix(in srgb, var(--accent) 5%, #101012)` |
+
+The card's share is the smaller because the hall's info chip (`--info` on `--info-weak`, both mixed from the card) was the thinnest pair under a tint, and at 8% it fell to 4.37:1; 5% clears every look. No look carries a dark palette and no token is added: the tint is a formula over the thirteen, so the contract stays at fifteen and a custom accent gets its own night for free. The table lives once, in `src/night-tint.js`; `themeMarkup()` emits it after the hall's sheet as the two dark twins the sheet already writes (`html[data-theme="dark"]` and the `prefers-color-scheme` block), at equal specificity, so it wins on order. The inks, the status vocabulary and every derived recipe stay the sheet's.
+
+**D2. The tint is on by default, and only a look turns it on.** A hall that has never chosen a look renders exactly as it does today, pure black included, whatever the tint setting says. The founder's switch puts a looked hall back on pure black.
+
+**D3. The apex and the hub stay pure black.** This decision is about a project's hall. The platform's own surfaces (ADR 0204) keep the world rule, and `DESIGN.md` says so where it states the rule.
+
+**D4. A custom look is one accent, used in both modes, nudged until it reads.** The founder picks one colour. It is laid over the chrome world's palette as `accent`. If it fails any of the pairs the hall paints with it (dark ink on an accent fill; the accent as text on the black and tinted grounds; the light mode's derived accent ink on paper), its lightness moves, the hue staying put, to the nearest value that passes. The preview shows the adjusted colour. There is no separate dark accent and no sixteenth token. The nudge is one algorithm, `lookAdjustAccent`, in `modules/provisioning/look.js`; the create wizard carries a copy that a test pins to it.
+
+**D5. The look travels the settings road.** `look` (the four library looks, `custom`, or `own` = the instance's own pack) and `night_tint` (`on` | `off`) join the provisioning settings vocabulary, so they reach a running hall the way every other policy does: written to `web.env`, applied by a restart (the pack is memoised). The adjusted accent and the logo's address ride as companion variables. `src/branding.js` resolves the look from the style library on the instance itself, so the platform never sends a palette, only a name.
+
+**D6. A logo is an image the platform keeps.** PNG, JPEG or WebP only, at most 256 KB, checked by its magic bytes, never SVG (an SVG is a document that can carry script). The platform stores it and serves it at a content-addressed public address; the hall shows it in its mark and the browser tab uses it as the favicon. Without a logo, a looked hall's favicon is drawn in the look's own colours.
+
+## Consequences
+
+- A founder picks a look, a night and a logo at creation, and an existing project's owner picks the same three on its manage page (D8). Both save through the platform; the hall restarts once to wear it.
+- Contrast is measured, not hoped for: `tests/look_night_tint.mjs` runs the hall's own token suite under every look with the tint on, and under custom accents across the hue wheel.
+- A hall with a tinted night loses the seamless `lighten` composite for any rendered plate. The hall ships no plate today (`--plate: none`), so nothing shows a seam; a hall that adds one later must switch the tint off or re-shoot it.
+
+## Alternatives considered
+
+- **Each look authors its own dark palette** (the mocks' approach). Rejected: a dark tier in the pack is the contract change ADR 0219 refused, for every sheet and drift test, and a custom accent would have no night.
+- **Two custom accents, light and dark** (the canvas). Superseded by the owner: one accent the platform makes readable is less to get wrong.
+- **Refuse an unreadable custom accent.** Rejected by the task: adjust, do not refuse.
+- **Send the full palette from the platform.** Rejected: thirteen colours and two quoted font stacks in an env file is fragile to quote, and the instance already ships the library.

package/docs/adr/README.md

@@ -476,3 +476,4 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 0355 | [**A soft limit is a rule with a reason, and nobody enforces it** ([task 1004416](https://cloudbongos.com/builders#/task/1004416), goal 1000121 — BV2.PS02). The startup flow's seven planet-physics answers and what they rule out. **D1:** the answers are more provisioning `detail` keys under `team_shape`'s contract (no defaults, refused loudly, `null` un-answers), with two new kinds — a list (`many`) and a whole number (`count`); the country is a closed ISO list. **D2:** answers must agree only within one request, so a merge patch's edit order never matters. **D3:** one declarative soft-limit table (`soft-limits.js`) — data conditions, `hide`/`grey`/`note`, a reason on every rule — and every resolution says `enforced: false`. **D4:** screening is a seam (`screening.js`) with a deliberately small rule set; a stop is 422 `screened_out` before anything exists. **D5:** the edit route screens a new description too.](0355-a-soft-limit-is-a-rule-with-a-reason-and-nobody-enforces-it.md) | provisioning / project startup |
 | 0356 | [**A recruit invite expires 30 days after it is sent, decided at read time** ([task 1002969](https://cloudbongos.com/builders#/task/1002969), goal 1000110 — privacy spec D4, owner-signed). **D1:** one definition, `src/bongos/invite-expiry.js` (`INVITE_EXPIRY_DAYS` + the SQL), read by the sign-in gate, the waiting-page probe, the onboarding routes and, through the doorway's `inviteExpiry`, the hub. Nothing is stored and nothing sweeps. **D2:** only `kind='invite'` rows expire; approved applications and goal invites do not. **D3:** amends ADR 0335 D2.5: the gate reads `kind` only inside the expiry unit, which can close a door and never open one. **D4:** an expired invite is refused, marked `expired` + `expires_at` in the queues, reported `expired` by the status probe (the CLI stops), and replaced by a re-invite's fresh row. **D5:** the hub hides a `pending` notice past 30 days and a re-invite restamps it. Split out: `seen_at` (task 1004443), the decline relay (task 1004444).](0356-a-recruit-invite-expires-30-days-after-it-is-sent-read-time.md) | platform identity / admission / invites |
 | 0357 | [**The update rule set on /deploy is the one the sweep follows** ([task 1004468](https://cloudbongos.com/builders#/task/1004468), goal 1000090 — BONGOS-V2, owner's ruling 2026-09-30). Amends [ADR 0136](0136-update-channel-subscription-policy.md)'s rejected DB-column alternative. **D1:** for a roster entry whose slug matches a `provisioning_instances` row, the unattended sweep uses that row's `update_channel` (set on /deploy, task 1004445). **D2:** the roster's `channel` is only the fallback — no matching row, or the database unreadable; enrollment and topology stay in the roster. **D3:** the sweep logs each entry's channel and its source, naming an overridden roster value. **D4:** read over psql from the sweep's own `DATABASE_URL`/`PGDATABASE`, never an entry's `env`. **D5:** nothing is copied; a row never changed is `patch`. Delivery to cloudbongos.com waits on the frozen sweep checkout (task 1004307). Rejected: roster stays in charge; stricter-of-the-two; copying roster values into rows.](0357-the-update-rule-set-on-deploy-is-the-one-the-sweep-follows.md) | distribution / updates |
+| 0358 | [**A hall wears a look, and its night takes a tint of it** ([task 1004421](https://cloudbongos.com/builders#/task/1004421), goal 1000121 — BV2.PS06; owner D2 + D8, 2026-09-30). Amends [ADR 0219](0219-a-look-is-a-branding-pack-the-style-library.md) (a look could not carry a dark ground) and DESIGN.md's pure-black rule, for halls only. **D1:** the night tint is a formula over the thirteen — the four dark grounds take 5–6% of the look's accent (src/night-tint.js), emitted after the sheet as both dark twins; no token added. **D2:** on by default, and only a chosen look turns it on — a hall with no look is unchanged. **D3:** the apex and hub stay pure black (ADR 0204). **D4:** a custom look is ONE accent for both modes, its lightness nudged until every pair the hall paints with it reads (lookAdjustAccent, client copy test-pinned). **D5:** look + night_tint join the provisioning settings vocabulary; the accent and logo address ride as companion env; the instance resolves the look from the style library. **D6:** a logo is PNG/JPEG/WebP ≤256 KB, magic-sniffed, never SVG, served content-addressed; it is the hall mark and the favicon. Rejected: per-look dark palettes, two custom accents, refusing an unreadable accent, sending the palette over env.](0358-a-hall-wears-a-look-and-its-night-takes-a-tint.md) | hall / branding / design world |

package/docs/api/openapi.json

@@ -15681,6 +15681,223 @@
         ]
       }
     },
+    "/provisioning/instances/{id}/logo": {
+      "put": {
+        "operationId": "put_provisioning_instances_id_logo",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "PUT /provisioning/instances/:id/logo",
+        "description": "PUT …/logo — rank: any authenticated builder (own resource; archon may change any). The image is screened by its bytes, stored, and the hall told its new address.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/look.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutProvisioningInstancesIdLogoRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "delete": {
+        "operationId": "delete_provisioning_instances_id_logo",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "DELETE /provisioning/instances/:id/logo",
+        "description": "DELETE …/logo — rank: any authenticated builder (own resource; archon may change any).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/look.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/provisioning/instances/{id}/look": {
+      "get": {
+        "operationId": "get_provisioning_instances_id_look",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/instances/:id/look",
+        "description": "GET — rank: any authenticated builder (own resource; archon may read any).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/look.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningInstancesIdLookResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "patch": {
+        "operationId": "patch_provisioning_instances_id_look",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "PATCH /provisioning/instances/:id/look",
+        "description": "PATCH — rank: any authenticated builder (own resource; archon may change any). A custom look needs an accent, sent now or already stored; the stored one is the ADJUSTED colour, and `adjusted` in the reply says when it differs from what came in.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/look.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchProvisioningInstancesIdLookRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/provisioning/instances/{id}/render": {
       "get": {
         "operationId": "get_provisioning_instances_id_render",
@@ -16124,6 +16341,41 @@
         ]
       }
     },
+    "/provisioning/logos/{file}": {
+      "get": {
+        "operationId": "get_provisioning_logos_file",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/logos/:file",
+        "description": "a logo is shown on a public hall, and its address is its own sha256, so it names no project and cannot be guessed. Served as an image only: nosniff, a sandboxing CSP, and a cache that never goes stale because a new image is a new name.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/look.js",
+        "parameters": [
+          {
+            "name": "file",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `file`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": []
+      }
+    },
     "/provisioning/onboard-plan": {
       "get": {
         "operationId": "get_provisioning_onboard_plan",
@@ -23951,6 +24203,23 @@
           "reason"
         ]
       },
+      "GetProvisioningInstancesIdLookResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "look": {},
+          "options": {},
+          "logo_max_bytes": {}
+        },
+        "required": [
+          "ok",
+          "look",
+          "options",
+          "logo_max_bytes"
+        ]
+      },
       "GetProvisioningInstancesIdRenderResponse": {
         "type": "object",
         "properties": {
@@ -25260,6 +25529,22 @@
           "values_held"
         ]
       },
+      "PatchProvisioningInstancesIdLookRequest": {
+        "type": "object",
+        "properties": {
+          "look": {
+            "type": "string"
+          },
+          "night_tint": {
+            "type": "string"
+          },
+          "accent": {
+            "type": "string",
+            "maxLength": 16
+          }
+        },
+        "additionalProperties": false
+      },
       "PatchProvisioningInstancesIdSettingsResponse": {
         "type": "object",
         "properties": {
@@ -25775,6 +26060,22 @@
           },
           "working_goal_id": {
             "type": "number"
+          },
+          "head": {
+            "type": "string",
+            "maxLength": 40
+          },
+          "disk_head": {
+            "type": "string",
+            "maxLength": 40
+          },
+          "main_head": {
+            "type": "string",
+            "maxLength": 40
+          },
+          "claude_account": {
+            "type": "string",
+            "maxLength": 200
           }
         },
         "required": [
@@ -30278,6 +30579,26 @@
         ],
         "additionalProperties": false
       },
+      "PutProvisioningInstancesIdLogoRequest": {
+        "type": "object",
+        "properties": {
+          "image_b64": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 368640
+          },
+          "content_type": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          }
+        },
+        "required": [
+          "image_b64",
+          "content_type"
+        ],
+        "additionalProperties": false
+      },
       "PutRenderDeployAppRequest": {
         "type": "object",
         "properties": {
@@ -30476,9 +30797,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 478,
-  "x-schema-count": 506,
+  "x-endpoint-count": 483,
+  "x-schema-count": 509,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 340,
+  "x-response-schemas": 341,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 478 endpoints across 86 route files.
+> **Generated from the live route files** — the route file is authoritative. 483 endpoints across 87 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -90,7 +90,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/autonomy/fence/goals` | `archon` | `goal_id`, `note` | Add a goal to the allowlist. |
 | DELETE | `/api/bongos/autonomy/fence/goals/:goalId` | `archon` | — | Revoke one. |
 | POST | `/api/bongos/autonomy/fence/priority` | `archon` | `goal_id` | The priority goal (task 1004453): which allowlisted goal the runner works first. |
-| POST | `/api/bongos/autonomy/heartbeat` | `any-builder` | `host`, `pid`, `started_at`, `mode`, `consecutive_failures`, `last_event`, `working_task_id`, `working_goal_id` | The runner's check-in, once per loop. |
+| POST | `/api/bongos/autonomy/heartbeat` | `any-builder` | `host`, `pid`, `started_at`, `mode`, `consecutive_failures`, `last_event`, `working_task_id`, `working_goal_id`, `head`, `disk_head`, `main_head`, `claude_account` | The runner's check-in, once per loop. |
 | GET | `/api/bongos/autonomy/precheck` | `metic+archon` | — |  |
 | GET | `/api/bongos/autonomy/runners` | `any-builder` | — | What the hall renders: the CALLER'S OWN runners, with the pure verdict attached so the page and any future alert cannot disagree about wh… |
 | GET | `/api/bongos/autonomy/runs` | `metic+archon` | — | The gate's past decisions — did a routine fire, and what did it decide, and why (task 1002669). |
@@ -587,7 +587,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/projects/featured` | `public` | — | the public map of projects; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: where to invite a builder into a project, asked by a `project.curate` holder OR the project's OWN OWNER (task 100… |
 
-## `provisioning` (35)
+## `provisioning` (40)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -612,6 +612,10 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/provisioning/instances/:id/force-teardown` | `metic+archon` | — | POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. |
 | POST | `/api/bongos/provisioning/instances/:id/github-app` | `any-builder` | `account` | POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 01… |
 | GET | `/api/bongos/provisioning/instances/:id/invite-suggestions` | `any-builder` | — | ── Who is worth inviting (BV1.R28, task 1002347, goal 1000046 C6) ──────── GET /provisioning/instances/:id/invite-suggestions — turn the … |
+| PUT | `/api/bongos/provisioning/instances/:id/logo` | `any-builder` | `image_b64`, `content_type` | PUT …/logo — rank: any authenticated builder (own resource; archon may change any). |
+| DELETE | `/api/bongos/provisioning/instances/:id/logo` | `any-builder` | validated | DELETE …/logo — rank: any authenticated builder (own resource; archon may change any). |
+| GET | `/api/bongos/provisioning/instances/:id/look` | `any-builder` | — | GET — rank: any authenticated builder (own resource; archon may read any). |
+| PATCH | `/api/bongos/provisioning/instances/:id/look` | `any-builder` | `look`, `night_tint`, `accent` | PATCH — rank: any authenticated builder (own resource; archon may change any). |
 | GET | `/api/bongos/provisioning/instances/:id/render` | `any-builder` | — | GET /provisioning/instances/:id/render — rank: any authenticated builder, and OWNER ONLY, like the POST (task 1004353). |
 | POST | `/api/bongos/provisioning/instances/:id/render` | `any-builder` | `key`, `owner_id`, `mode`, `service_id`, `web_plan`, `db_plan`, `region`, `runtime`, `build_command`, `start_command`, `database` | POST /provisioning/instances/:id/render — rank: any authenticated builder, and OWNER ONLY: the key is the owner's and so is the account i… |
 | POST | `/api/bongos/provisioning/instances/:id/repo-private` | `any-builder` | validated | POST /provisioning/instances/:id/repo-private — rank: any authenticated builder, and OWNER ONLY: no archon override, because the runner f… |
@@ -620,6 +624,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/provisioning/instances/:id/settings` | `any-builder` | validated | PATCH /provisioning/instances/:id/settings — change a project's settings. |
 | POST | `/api/bongos/provisioning/instances/:id/teardown` | `any-builder` | — | POST /provisioning/instances/:id/teardown — request teardown of the caller's OWN instance. |
 | POST | `/api/bongos/provisioning/instances/:id/update-channel` | `archon` | — | POST /provisioning/instances/:id/update-channel — set the project's update rule (task 1004445). |
+| GET | `/api/bongos/provisioning/logos/:file` | `public` | — | a logo is shown on a public hall, and its address is its own sha256, so it names no project and cannot be guessed. |
 | GET | `/api/bongos/provisioning/onboard-plan` | `public` | — | GET /provisioning/onboard-plan?mode=greenfield\|adopt&domain=<host> — the CANONICAL onboarding step sequence (task 2085; goal 35 / criteri… |
 | GET | `/api/bongos/provisioning/recommendations` | `public` | — | GET /provisioning/recommendations?type=<project type>&team_shape=<interview answer> — the RULE-BASED recommendation for one set of creati… |
 | POST | `/api/bongos/provisioning/render/lookup` | `any-builder` | `key`, `owner_id` | POST /provisioning/render/lookup — rank: any authenticated builder. |