@bongos/core 1.17.0 → 1.17.1

package/CLAUDE.md

@@ -1,242 +1,15 @@
-# Off the Boats — Project Memory
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> **This file is descriptive. The source of truth for permissions, scope, and state is the Bongos database accessed via `/api/bongos/*`.**
-> CLAUDE.md is the index and durable *framing* for AI agents — not an authority. Where it describes live state (tasks, versions, claims, ranks, costs) the database wins; where it describes permissions, [`docs/canonical-permissions.md`](docs/canonical-permissions.md) + the server's `requireRank` checks win (see [ADR 0016](docs/adr/<redacted>.md)). If this file and a route/DB row disagree, the route/row is authoritative and the doc is the bug. Editing this file cannot grant any authority.
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
 
-This file is the **index and durable framing** for the project. Read it at the start of every session. When a section is relevant to your task, **drill into the linked detail files** rather than expecting all the depth here. Update this file (or a linked detail file) at the end of every session — see [§12 Session Update Protocol](#<redacted>). **Read docs on your instance's builders' hall (`domains.buildersOrigin` in [`config/branding.json`](config/branding.json)), not raw on github.com** — the hall is the canonical doc-reading surface (task refs render as working links there, §8's hall-link convention); github.com is the code host only, where a bare `#NNN` autolinks to a GitHub issue and 404s (tolerated, not supported). If the hall is down, your instance's status page (`domains.statusOrigin`) is the fallback for project state ([ADR 0029](docs/adr/<redacted>.md), off-box), though not full doc rendering. How an agent resolves these surfaces from config alone (with no hard-coded host) is the **docs-discovery contract** — [ADR 0114](docs/adr/<redacted>.md); `GET <publicOrigin>/api/bongos` re-advertises them for zero-config bootstrap.
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
 
-**AI-first norm — the foundational assumption.** Cloud Bongos is an **AI-first build platform: AI agents write the code.** A human owner sets scope, direction, and the hard gates (rank, approval, deploy); the day-to-day building — code, docs, migrations, reviews — is done by AI agents claiming tasks. **Every rule in this file is written for that reader.**
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
 
----
-
-## Working with this file (content charter)
-
-CLAUDE.md loads **in full, every session** — so every line spends context budget, and a bloated file makes agents *miss* real instructions ([ADR 0061](docs/adr/<redacted>.md); the context-rot literature). Two rules keep it lean:
-
-- **Per-line test:** *would removing this line cause an agent to make a mistake?* If not, cut it.
-- **What goes where:**
-
-| Content | Home |
-|---|---|
-| Portable methodology — working rules, session protocol, claim→ship lifecycle, this charter | **this file** (the core Cloud Bongos ships to any instance) |
-| Host instance identity — product/world/company, vision, visual style | [`docs/project-context.md`](docs/project-context.md) (prose) + [`config/branding.json`](config/branding.json) (the strings code reads) |
-| Live state — tasks, versions, ranks, costs, claims | the **Bongos DB** (`/builder-start`, `/status`) |
-| *Why* a non-obvious choice was made | an **ADR** ([`docs/adr/`](docs/adr/)) |
-| Multi-page how-to / ops guide | a **recipe** ([`docs/recipes/`](docs/recipes/)) |
-| One module's public surface + gotchas | that dir's **nested `CLAUDE.md`** (loads on demand) |
-| Short per-rule learning | the **`learnings`** table (`learning-capture.js`) |
-
-**Budget: ≤ ~200 lines.** Past that, relocate detail *down this table* — don't append here. Per-module maps live at [`src/bongos/`](src/bongos/CLAUDE.md), [`src/bongos/routes/`](src/bongos/routes/CLAUDE.md), and [`scripts/gds/`](scripts/gds/CLAUDE.md), and load only when an agent works in that folder.
-
----
-
-## Quick navigation
-
-| If you need… | Go to |
-|---|---|
-| **What I should claim right now** (parallel-safe tasks) | Run `/builder-start` |
-| **What's the status of a version / criterion** (what's left for C8?) | Run `/status` — rolls up each done-when criterion → gating tasks → what remains ([ADR 0025](docs/adr/<redacted>.md)) |
-| **Project identity** (product, world, visual style — host context) | [`docs/project-context.md`](docs/project-context.md) (prose) + [`config/branding.json`](config/branding.json) (strings code reads, [contract](docs/branding-contract.md)); split out per [ADR 0062](docs/adr/<redacted>.md) §7 |
-| **Live architecture detail** (infra, stack, DB schema, Bongos API) | [`docs/architecture.md`](docs/architecture.md) |
-| **API reference** (every endpoint, gate, params) | Generated **OpenAPI 3.1** at [`docs/api/openapi.json`](docs/api/openapi.json) + [`docs/api-reference.md`](docs/api-reference.md); rendered at **`/docs`** on the instance's own origin. Regenerate: `node scripts/gds/gen-api-docs.js` ([ADR 0109](docs/adr/<redacted>.md)). **External consumers**: typed client [`clients/bongos-client`](clients/bongos-client/README.md) + auth/hello-world on-ramp [`docs/api-onramp.md`](docs/api-onramp.md) |
-| **Module system** (plugin-API contract, manifest schema, seams, rank-gate rule, module-owned migrations, module-author recipe) | [`docs/modules-contract.md`](docs/modules-contract.md) · [ADR 0083](docs/adr/<redacted>.md) |
-| **Who can do what** (rank ladder, trust boundary — DB enforces) | [`docs/canonical-permissions.md`](docs/canonical-permissions.md) · [ADR 0016](docs/adr/<redacted>.md) |
-| **How builders earn the reward currency** (cost-plus token reward + per-task credits) | The **economy module** owns the reward policy as per-instance config — currency label + cost-plus margin + USD peg: [`modules/economy/CLAUDE.md`](modules/economy/CLAUDE.md) (`config/branding.json` `currency.label` + `reward.{marginPct,usdPeg}`) · [ADR 0054](docs/adr/<redacted>.md), [ADR 0023](docs/adr/<redacted>.md) |
-| **What do we already know about X** (search before re-solving) | Run `/recall <query>` — rank-scoped lexical search over every repo doc + indexed DB prose ([ADR 0060](docs/adr/0060-gds-retrieval-layer.md)) |
-| **Where does symbol/function X live** (code altitude map) | `docs/repo-map.md` — generated symbol skeleton (complements `/recall`), now also a **doc link-graph + staleness flags** (which docs a key doc links to; which docs carry unresolved links needing a touch-up — task 2013). **Gitignored + regenerated at deploy/box-fetch, not committed** ([ADR 0110](docs/adr/<redacted>.md)); if absent in your tree run `node scripts/gds/gen-repo-map.js` ([ADR 0063](docs/adr/<redacted>.md)) |
-| **What keeps the architecture boundary from rotting** (fitness functions) | `node scripts/gds/fitness.js` — CI gate (in the `unit` check): core↔host import boundary, CLAUDE.md budget + nested-doc presence, no route bypasses rank checks, repo-map freshness ([ADR 0061](docs/adr/<redacted>.md), [0062](docs/adr/<redacted>.md) §1; nested-doc discovery assumes core dirs sit at the instance root — [0108](docs/adr/<redacted>.md) moves them into the core package) |
-| **Docs/markdown entropy** (stale links, broken anchors, duplicate prose) | `node scripts/gds/docs-entropy.js [--verbose] [--file-ideas]` — parallel to knip dead-code scan; surfaces broken internal links and cross-file duplicate prose across all tracked `.md` files |
-| **Where files live** (full repo tree) | [`docs/file-map.md`](docs/file-map.md) |
-| **What a past version shipped / a version's scope** | Per-version scope archives are [`limitations/*-shipped.md`](limitations/) (each written only *after* a guided review — a fresh instance's core template ships with none). This instance's specific game + platform version history + roadmap framing lives in [`docs/project-context.md`](docs/project-context.md); live status via `/status`. |
-| **Dev Box desktop app** (mac menu-bar / Windows tray switch for the builder box: pairing auth, downloads, release flow) | [`devbox-app/README.md`](devbox-app/README.md) · [ADR 0045](docs/adr/<redacted>.md) · [`docs/recipes/devbox-app-release.md`](docs/recipes/devbox-app-release.md) |
-| **Future limitations to lift / next-version planning** | `limitations/backlog.md` (read-only archive — live tasks now in Bongos DB) |
-| **In-flight feature ideas captured during a session** | Capture to the live `idea_inbox` via `node scripts/gds/capture.js "…"`; triage with `/idea-triage`. (The old [`generative-ideas.md`](generative-ideas.md) is a frozen 2026-05-11 snapshot.) |
-| **Inbound team messages** (chat → `idea_inbox`, then `/idea-triage`) | The mechanism lives in the **discord module** → [`modules/discord/CLAUDE.md`](modules/discord/CLAUDE.md); this instance's server-specific inbound setup is [`docs/discord/inbound.md`](docs/discord/inbound.md). |
-| **Ops gotchas + recipes** (read before deploying) | [`docs/recipes/ops-gotchas.md`](docs/recipes/ops-gotchas.md) |
-| **Things stuck on the owner's input** | [`blockers/blockers.md`](blockers/blockers.md) |
-| **Why we chose what we chose** (architecture decisions — full ADR index) | [`docs/adr/README.md`](docs/adr/README.md) |
-| **Multi-agent system (MAS)** — agent hierarchy, grader, phased plan | [ADR 0024](docs/adr/<redacted>.md) (architecture + ship table) · [0026](docs/adr/<redacted>.md) (BFG) · [0027](docs/adr/<redacted>.md) (6D eval). **All four shipped** — Grader (4-worker adversarial panel + route-rank pre-pass), Conductor (`UserPromptSubmit` hook), Architect (`--scope` audits → [`docs/audits/`](docs/audits/)), BFG. Only Phase 4.5 (autonomous dispatch) is unbuilt. |
-| **Architecture audits — first-principles "what to delete" reviews feeding next-version scope** | [`docs/audits/`](docs/audits/) (produced by the Architect — MAS Phase 5; `node scripts/gds/architect-audit.js --scope … --paths …`) |
-| **Session-end handoff template** (use at every session end) | [`docs/handoff-template.md`](docs/handoff-template.md) |
-| **Discord integration** (build broadcast, channel layout, role sync — a one-way mirror, outside the trust boundary) | The **discord module** owns the mechanism → [`modules/discord/CLAUDE.md`](modules/discord/CLAUDE.md). This instance's server-specific channel config is [`docs/discord/channels.json`](docs/discord/channels.json). |
-| **Pixel-art design system** (pipeline, rubric, palette, skills) | The **art-pipeline module** owns the mechanism → [`modules/art-pipeline/CLAUDE.md`](modules/art-pipeline/CLAUDE.md) (operational ref: [`art/README.md`](art/README.md)). The pixel/Greek *style* choice itself is instance detail → [`docs/project-context.md`](docs/project-context.md). |
-| **Bongos** — the work-tracking system (formerly GDS/PMS): architecture, schema, slash commands | [ADR 0010](docs/adr/0010-pms-architecture.md); `src/bongos/` + `scripts/gds/`, API at `/api/bongos/*` (the prior `/api/gds/*` stays mounted **forever** as a permanent alias; `/api/pms/*` now 404). Read-side back-compat for the `pms_session` cookie, `PMS_GITHUB_*` env vars, and `~/.config/otb/pms-session.json` stays. |
-| **Deploying PMS-V1 + status subdomain end-to-end** | [`docs/pms-v1-deploy.md`](docs/pms-v1-deploy.md) |
-| **Public build-status dashboard (live)** | your instance's status page (`domains.statusOrigin`) — source in `modules/status-ui/public/` (carved to a module, BV1.R84) |
-
----
-
-## 1. Project Overview
-
-> **What this instance is** — the product, company, vision, world, and visual style — is host instance context, kept in [`docs/project-context.md`](docs/project-context.md) (prose) + [`config/branding.json`](config/branding.json) (the strings code reads), **not in this portable core**. Per [ADR 0062](docs/adr/<redacted>.md) §7, moving the project identity out of CLAUDE.md *is* the core ↔ host split: CLAUDE.md is the methodology Cloud Bongos ships to any instance; `docs/project-context.md` is what an instance authors on top of it.
-
-**Work-type axis.** A task's work type comes from its **role/discipline** (engineer / artist / ideator / ui), set per task — not from a version "track." (The former two-track `product`/`internal` model was deprecated in BONGOS-V1; versions are just named scope milestones now.)
-
----
-
-## 2. The Prompter (product owner)
-
-The product owner sets scope, direction, and the hard gates. But there is **no special "owner" entity** — an owner is just a builder with elevated permissions and an **interaction profile**. How to pitch replies to whoever you're working with — tone, technical level, local-toolchain familiarity — is *that builder's* profile, captured at onboarding and injected each session (the **builder-settings module**'s `interaction` knob, sibling of `wandering`; [`modules/builder-settings/CLAUDE.md`](modules/builder-settings/CLAUDE.md)). `/me` carries the resolved `interaction.contract`.
-
-**Portable defaults** (the fallback when a builder has set no profile — the `interaction-prefs.js` defaults): assume the reader may not be a software engineer (define jargon on first use; treat local toolchains — Homebrew, ports, env vars — as new, explained step by step); frame trade-offs as **cost, time, and what the user will see**, not framework taxonomy; ask about **outcomes and product behavior**, not implementation details (decide those yourself and present for confirmation); be concise. A builder's profile overrides these.
-
-**Turn-end sound** is builder-local ergonomics, owned by the builder-settings module (per-sound on/off + volume + per-event variant); `.claude/hooks/stop-sound.js` plays it by flag priority — raise the **triumph** flag only for genuine milestones.
-
-**Build broadcast.** On deploy, the shipped task's `--summary` is broadcast to the team chat (short, no jargon, business-owner audience); inbound flows back to `idea_inbox`. The mechanism + this instance's channels live in the **discord module** ([`modules/discord/CLAUDE.md`](modules/discord/CLAUDE.md)) — a one-way mirror, outside the trust boundary.
-
-**Subagent model routing — quality first, cost lever second.** Subagent spawns via the `Agent` tool MUST set the `model` parameter explicitly — never inherit silently — to the builder's resolved **model allocation**. The *shape* is stable methodology: the main interactive session runs the top tier (what the builder sits in front of); subagents default to the development tier; only mechanical known-path work (list claimable, fetch a row by id, log a cost entry, read a known file) drops to the cheap tier. *Why the tiers split by judgment-load, not by task:* research feeds code that ships, so a cheaper research tier degrades downstream quality more than it saves — when in doubt, pick the development tier.
-
-The tier **values** are settings-driven ([`modules/builder-settings/CLAUDE.md`](modules/builder-settings/CLAUDE.md), task 2011): instance default `config/branding.json` `models.{main,subagentDefault,subagentRoutine}` (this instance: `opus` / `opus` / `haiku`, i.e. "no Sonnet"), overridable per builder. The resolved allocation is on `/me` (`model_allocation.effective`); changing a tier is a config/settings edit, not a doc edit.
-
----
-
-## 3. Company Context
-
-> Instance identity — company, vision, world, and visual style (the former §§3/5/6/7) — is host context in [`docs/project-context.md`](docs/project-context.md); the machine-readable strings are the branding contract ([`config/branding.json`](config/branding.json) / [`docs/branding-contract.md`](docs/branding-contract.md)). Why this lives out of the core is the §1 note + the charter. §§3/5/6/7 stay as stub headings so existing anchors/cross-refs resolve.
-
----
-
-## 4. Financial Constraints
-
-**This instance's actual budget — the annual number and the spend target — is host context in [`docs/project-context.md`](docs/project-context.md).** The portable posture every instance inherits:
-
-- **Choose the cheapest viable option.** Bootstrapped mindset — avoid expensive architectures and premium SaaS unless there is no reasonable alternative.
-- **Document the trade-off in an ADR** ([`docs/adr/`](docs/adr/)) when a more expensive option is chosen, so the decision can be revisited.
-- **Optimize monthly recurring cost.** Any proposal that locks in a high fixed monthly cost (managed servers, large always-on databases, premium CDNs with per-GB egress at high volume) needs explicit justification and a cheaper fallback.
-- **The owner controls spend.** Nothing gets purchased without the owner's explicit go-ahead.
-
----
-
-## 5. Goal & Vision
-
-> Host identity → [`docs/project-context.md`](docs/project-context.md) (see the §3 note).
-
----
-
-## 6. World Design
-
-> Host identity → [`docs/project-context.md`](docs/project-context.md) — the world/setting + the trademark posture (the world name is a single config string, `identity.worldName`). See the §3 note.
-
----
-
-## 7. Visual Style
-
-> Host identity → [`docs/project-context.md`](docs/project-context.md) — the visual style, the self-improving `art/` pipeline (palette/rubric non-negotiables), and the art skills. See the §3 note; operational reference: [`art/README.md`](art/README.md).
-
----
-
-## 8. Versioning Methodology
-
-The project ships version-by-version. Each version is a named scope milestone — some user-facing (V1, V2, V3…), some improving *how* we build (the platform versions). There is no "track" taxonomy; a task's work type comes from its role/discipline.
-
-**Live version names, statuses, and ship dates are in the Bongos `versions` table (`/status`) — this instance's version history is host state, not portable core** (the product-roadmap framing + platform-version history are preserved in [`docs/project-context.md`](docs/project-context.md)). A key methodology rule (`feedback_new_version_review`): a new version's scope-truth archive isn't written — and the repo isn't "king" for that version — until a guided shipped-tasks + code review with a senior builder produces it. A builder claims whatever is claimable; versions ship independently.
-
-The durable artifacts of this method are folders + a database:
-
-- [`limitations/*-shipped.md`](limitations/) — the **mechanism**: one preserved scope archive per shipped version, each written only *after* a guided shipped-tasks + code review (a fresh instance ships with none). *This* instance's specific per-version archives + which versions still await their review are host state — [`docs/project-context.md`](docs/project-context.md).
-- **Bongos database** (Postgres `tasks` + `claims` + `versions`) — the live work-tracking layer; `/builder-start` shows what's claimable. `limitations/backlog.md` is a frozen pre-import archive.
-- [`docs/recipes/`](docs/recipes/) — long-form ops guides (read before similar work); short per-rule learnings go to the `learnings` table (`learning-capture.js`).
-- [`blockers/`](blockers/) — work needing the owner's input (resolve = delete). [`docs/adr/`](docs/adr/) ([index](docs/adr/README.md)) — Architecture Decision Records for any non-obvious choice.
-- [`generative-ideas.md`](generative-ideas.md) — frozen 2026-05-11 snapshot; live ideas go to `idea_inbox` via `capture.js`, triaged with `/idea-triage`.
-
-**Working rules while building:**
-
-- **Every change is backed by a claimed Bongos task. No exceptions.** This is the methodology's hard rule. If you find yourself about to commit code, edit a doc, run a DB migration, change a config, move a task between versions, or otherwise alter state — and you do not hold an active Bongos claim covering that work — stop. Create or find the task in Bongos, claim it, *then* make the change. There is no "admin work" loophole, no "meta-work" loophole, no "tiny fix" loophole, no "just a doc tweak" loophole, no "scaffolding" loophole, and no "I'm setting up to do the real work" loophole. The point of the rule is that Bongos is the complete ledger of what happened to this project — if a change isn't in it, the ledger lies. (See feedback memory: `feedback_follow_methodology.md`.)
-- **Direct DB writes are work too.** Updating `tasks`, `versions`, `blockers`, etc. via `psql` is a change to project state. It needs a claimed task just like a `git commit` does. The fact that the API doesn't yet expose an endpoint for the operation does NOT make it admin work — it just means the operation runs under a claim via SQL instead of via an HTTP call. Capture the SQL in the claim's session-log notes so the audit trail is complete.
-- **Start every session with `/builder-start`** to see claimable tasks. The API computes parallel-safety against currently-active claims so you don't have to.
-- **Claim before working.** `/builder-claim N` locks the task to your session. If the claim fails (already claimed, touches conflict, not ready, **dependencies not shipped**), pick another. If nothing exists for the work you're about to do, create the task first via `POST /api/bongos/tasks` or `node scripts/gds/capture.js`, then claim it.
-- **Dependencies gate everything.** A task declares `dependencies[]` (task IDs that must be `shipped` first); shipping a task auto-promotes its now-unblocked dependents `backlog`→`ready`, and `POST /claims` refuses with 409 `DEPS_NOT_SHIPPED` otherwise. The `V##.R##` rank prefix is decorative; deps are load-bearing. Full mechanics + CRUD endpoints in [ADR 0015](docs/adr/<redacted>.md).
-- **Ship or release at session end.** `/builder-ship` runs smoke tests, then chains `completed` → `confirmed` (**credits land here**) → `shipped` (merged + deployed). Anything left at `confirmed` is landed automatically by the server reconciler within ~5 min. `/builder-release` returns the task with no credits. `git merge` at land time is the authoritative collision detector (a wrong up-front touches[] prediction is not ship-blocking). See the `/builder-ship` skill doc.
-- **How readily you surface a tangent vs. silently capture it is your *wandering* level** — a per-builder, rank-defaulted knob (newcomers = Locked: never raise off-task tangents or investigations; file them with `capture.js` and stay on the claim). It tunes the three rules below; it does *not* limit in-task initiative. Resolved + clamped server-side, injected each session ([`modules/builder-settings/wandering-prefs.js`](modules/builder-settings/wandering-prefs.js)).
-- Idea that fits inside an existing claim → just ship it under that claim.
-- Idea that **does not** fit the active claim and is small + in current version → finish current claim first, then claim a new task for it.
-- Idea that's bigger or out of scope → create a new task via `POST /api/bongos/tasks` (status `backlog`) or capture via `node scripts/gds/capture.js` for `idea_inbox` triage.
-- Significant non-obvious decision made → write an ADR in [`docs/adr/`](docs/adr/) and link it from the shipping task's notes.
-- Discovery that took more than ~10 minutes to diagnose → capture as a learning via `node scripts/gds/learning-capture.js` (DB-backed; see `learnings` table). For longer multi-page recipes, write a file under `docs/recipes/`.
-- Stuck on something only the owner can decide/provide → write a [`blockers/`](blockers/) entry AND attach the blocker_ref to the relevant task.
-- Change touched anything the onboarding diagrams describe (ranks, task statuses, versions, currency-and-karma / architecture) → **all 5 diagrams are auto-generated** by `scripts/gds/gen-diagrams.js` (runs on deploy; `.svg`/`.png` + `assertions.json` in lockstep). **Never hand-edit a `.mmd` or `assertions.json`** — edit the template in `gen-diagrams.js`, run it, commit. Backstop in [`docs/handoff-template.md`](docs/handoff-template.md).
-- **Never write a bare `#NNN` for a Bongos record in prose you emit** (chat, reasoning, commits/PRs, docs) — a bare `#NNN` autolinks to GitHub issues and **404s** (our task/idea/blocker ids ≠ GitHub's). Write the hall link `[#NNN](<buildersOrigin>#/task/NNN)` — using your instance's hall origin (`domains.buildersOrigin`), which renders as a clean `#NNN`; plain `task NNN` is fine too. Enforced in committed Markdown by `scripts/gds/linkify-refs.js` and at turn-end by the `.claude/hooks/stop-refcheck.js` Stop hook (a genuine `PR #8` is left alone).
-
-**At end of session:** `/builder-ship` (or `/builder-release`) the active claim, then review [`generative-ideas.md`](generative-ideas.md) — promote actionable ideas into new tasks, deliver in-scope small ones, delete bad ones.
-
----
-
-## 9. Product versions (summary)
-
-> **Product-version scope is host context + live DB state — not portable core.** The named product versions, what each shipped, the carry-forward limits, and the roadmap framing are this instance's identity: see [`docs/project-context.md`](docs/project-context.md) for the human roadmap framing and [`limitations/`](limitations/) for the preserved per-version scope archives (e.g. [`limitations/v1-shipped.md`](limitations/v1-shipped.md)). The **live source of truth is the Bongos `versions` table** — run `/status`. This heading stays a stub so existing cross-references and anchors keep resolving (see the §3 note).
-
----
-
-## 10. Architecture — current state
-
-The full architecture detail — live infra (domain, host, TLS, hardening), application stack, networking + render model, code & deploy flow, the complete DB schema (game + Bongos tables, columns, views), and the Bongos API surface — lives in **[`docs/architecture.md`](docs/architecture.md)**, **not in this portable core**: it describes *this* instance's live system, and a fresh instance authors its own. Read the detail file for any specifics.
-
-Two anchors are always true and stay here: **the Bongos DB is the source of truth for all live work state** (this index only ever *describes* the schema), and the Bongos API is mounted at **`/api/bongos/*`**. The architecture *rules* that are portable are the trust-boundary ones below.
-
-> **Decision rationale (why we chose what):** full index at [`docs/adr/README.md`](docs/adr/README.md) — the load-bearing methodology decisions are 0010 (Bongos work-tracker), 0016 (trust boundary), 0024 (MAS), and 0061/0062 (context-layer decomposition + core↔host split); instance-specific stack and infra ADRs are indexed there too.
-
-> **Permissions / builder ranks: the DB enforces, markdown only describes.** Authority lives in `builders.rank` on the prod DB, checked server-side per request with **no caching**. A builder editing local files (CLAUDE.md, skills, `settings.json`, hooks) cannot grant themselves authority. The rank ladder, what's gated, the local-edit failure modes, and the **no-hardcoded-admin-identity rule** (enforced by `scripts/gds/audit-authorship.sh` — no rank or builder identity is ever baked into a file) are all in **[`docs/canonical-permissions.md`](docs/canonical-permissions.md)**; the decision is [ADR 0016](docs/adr/<redacted>.md).
-
-> **🔒 Product builders build the product, not the platform they stand on.** The permission/pipeline internals an instance runs on — the rank/authz machinery, the ship/grade/deploy pipeline, DB `migrations/`, `infra/`, and the trust-boundary docs — are vendored Cloud Bongos core, not instance product surface. Landing code is Bongos's job: claim a task and run `/builder-ship`, never a raw `git push`/`ssh`/deploy. **Who may modify that core, the rank floor that gates it, and the hard enforcement** (protected-path glob, pre-push hook, grader pre-pass, post-push main audit) live in [`docs/canonical-permissions.md`](docs/canonical-permissions.md) and [ADR 0043](docs/adr/<redacted>.md) — editing local files can't grant that authority.
-
----
-
-## 11. File Map — Where Things Live
-
-The full repo tree — project root, `migrations/`, `scripts/`, `src/`, `public*/`, `art/`, `tests/`, `.claude/skills/`, `.claude/scheduled-tasks/`, and the deploy-host layout — lives in **[`docs/file-map.md`](docs/file-map.md)**, the single source for the tree. Split out of this index to keep CLAUDE.md lean.
-
----
-
-## 12. Session Update Protocol
-
-**At the START of every session**, before doing anything else:
-
-1. **Run `/builder-start`** to see what's claimable. Confirm with the owner which task to claim.
-2. **Run `/builder-claim N`** before starting work. The claim is what makes parallel sessions safe.
-
-At the **end of every session**, before signing off:
-
-1. **Resolve your claim.** `/builder-ship` (with handoff notes + value summary) on success, `/builder-release` on abandonment. Bongos records the session log entry and awards credits.
-2. **Write a session log entry as its own file** at [`docs/session-logs/YYYY-MM-DD-<slug>.md`](docs/session-logs/) using [`docs/handoff-template.md`](docs/handoff-template.md). **Do not hand-edit the §13 index** — the recent-sessions snippet there and the full [`docs/session-log-index.md`](docs/session-log-index.md) are generated from the files and regenerate at ship (`scripts/gds/gen-session-index.js`); just drop your dated file. For single-task sessions, the Bongos `session_logs` row is sufficient and a separate file isn't needed.
-3. **Review the idea_inbox** via `GET /api/bongos/inbox` (or run the `/idea-triage` skill — recommended daily). Promote actionable ideas into new tasks; mark stale ones discarded.
-4. **Update detail files** if anything changed: new gotcha → long-form recipe under [`docs/recipes/`](docs/recipes/) OR short-form rule via `node scripts/gds/learning-capture.js`; new blocker → `POST /api/bongos/blockers` (the markdown file is frozen archive); decision made → new ADR. If a version has no king-doc yet, capture version-related notes in `idea_inbox` + that version's tasks until its guided review pass produces the scope archive.
-5. **Update [`docs/architecture.md`](docs/architecture.md)** if the live system changed (§10 here is only an orientation + link).
-6. **Update [`docs/file-map.md`](docs/file-map.md)** if files or folders were added/moved/deleted (§11 here is only an orientation + link).
-   - *These "remember to update the detail files" steps (4–6) are backstopped mechanically:* `docs/repo-map.md`'s **staleness flags** (task 2013) list docs whose internal links no longer resolve — a regenerated signal of what drifted, so the touch-up is prompted, not left to memory.
-7. **No session-log index chore.** The §13 snippet + [`docs/session-log-index.md`](docs/session-log-index.md) regenerate from the files at ship — never hand-edit them. (Compressing very old prose into [`docs/session-log-archive.md`](docs/session-log-archive.md) is optional housekeeping for the on-disk corpus, not a per-session context-budget step.)
-
-If nothing changed in a section, leave it alone — don't churn.
-
-### Daily cadence skills (run once per day, not per session)
-
-Two manual slash-commands exist to keep the methodology surfaces from accumulating drift. Run each once per day (any session can pick them up; doesn't matter which one, as long as it happens):
-
-- **`/idea-triage`** — walk the open `idea_inbox` rows. For each: promote (→ task), discard, merge with another, or defer. Keeps the inbox actionable; deferring is fine but the cadence is the discipline.
-- **`/blocker-review`** — walk the open `blockers` rows. For each: resolved (auto-promotes linked tasks via DB trigger), still blocked (with a note), or escalate (surface to the owner / external ask).
-
-Both are NOT scheduled cron tasks — they're invoked manually via slash command at the start or end of any session. If a day passes without either running, the queues quietly grow; running them is the structural cure for the markdown-graveyard pattern that Phases 0–3 dismantled.
-
-> **`/merge-mode` is *not* a daily chore — don't run it on a schedule or tell builders to.** The server lands merges itself: green PRs auto-merge, a 5-min reconciler flips `confirmed → shipped`, and the [ADR 0082](docs/adr/<redacted>.md) resolver self-heals generated-file conflicts. It's the **rare manual fallback** for a strand still stuck after the ~5-min sweep (e.g. a non-generated-file conflict the server can't resolve) — reach for it then, not before.
-
-In addition, ~17 scheduled routines under [`.claude/scheduled-tasks/`](.claude/scheduled-tasks/) run autonomously on cron (e.g. `overnight-code-review`, `idea-triage-nightly`, `overnight-builder`, `bfg`, `security-review-weekly`). They complement the manual cadence skills so every methodology surface keeps flowing without per-session tax. Each is **instance-wide** (one scheduled run per instance, not one cron per builder — per-builder effects come from iterating builders in the routine body); which are on by default, their cadence, and which need the autonomy flag armed is the portability contract [`config/scheduled-routines.json`](config/scheduled-routines.json) ([ADR 0115](docs/adr/<redacted>.md)).
-
----
-
-## 13. Session Log
-
-Session-log **prose** lives one file per session under [`docs/session-logs/`](docs/session-logs/) — `YYYY-MM-DD-<slug>.md`, written from [`docs/handoff-template.md`](docs/handoff-template.md) (older entries compressed into [`docs/session-log-archive.md`](docs/session-log-archive.md)); the DB session corpus (`session_logs` + the BFG `session_records`) is the structured record. The index is **generated**: full history in [`docs/session-log-index.md`](docs/session-log-index.md), and the recent slice below is regenerated at ship by `scripts/gds/gen-session-index.js` (the `gen-diagrams`/`gen-repo-map` pattern — [ADR 0062](docs/adr/<redacted>.md) §8). **Do not hand-edit the list below or the index** — write your dated file and both regenerate; generating from real files means a link can never dangle (retires the recurring §13 hand-maintenance drift).
-
-<!-- BEGIN GENERATED SESSION-LOG SNIPPET (scripts/gds/gen-session-index.js — do not hand-edit) -->
-**Recent sessions** (newest 10 — full history in [`docs/session-log-index.md`](docs/session-log-index.md)):
-
-- [2026-07-07 — Branded project-creation experience on cloudbongos.com (goal 35)](docs/session-logs/<redacted>.md)
-- [2026-07-04 — Planning session: "Robust, versioned, easy-to-call public API" (BONGOS-V1 goal 36)](docs/session-logs/<redacted>.md)
-- [2026-07-03 — Roadmap tab, batch-claim bug fixes, hall UI backlog seed](docs/session-logs/<redacted>.md)
-- [2026-07-03 — Hall UI redesign: dashboard shell, neutral voice, dark mode + the Goals page](docs/session-logs/<redacted>.md)
-- [2026-07-03 — Governance planning session: <redacted> roles & permissions (BONGOS-V1)](docs/session-logs/<redacted>.md)
-- [2026-07-03 — Cloud Bongos sky-whale — foundational multi-angle turnaround (task 1743)](docs/session-logs/<redacted>.md)
-- [2026-07-03 — Claude Bongos + Gemini Bongos vanity doors → cloudbongos.com orbs](docs/session-logs/<redacted>.md)
-- [2026-07-02 — Bongo Buddha tickle animation: land seeds (1699) + solve within-clip style-drift (1710)](docs/session-logs/<redacted>.md)
-- [2026-06-26 — Land Builder 25's world-building plan into V2 (task 1569)](docs/session-logs/<redacted>.md)
-- [2026-06-26 — Cloud Bongos ↔ Example separation: gap analysis + seed the foundation tasks](docs/session-logs/<redacted>.md)
-<!-- END GENERATED SESSION-LOG SNIPPET -->
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/bin/bongos.js

@@ -69,6 +69,7 @@ if (VERSION === '0.0.0') { try { VERSION = require('../package.json').version ||
 //                api.js caller (e.g. waking your box is just POST /box/ensure).
 const VERBS = {
   start:   { script: 'start.js',   group: 'work', summary: 'List tasks you can claim right now' },
+  task:    { script: 'task.js',    group: 'work', summary: 'Create or show a task  (bongos task new --title … --description …)' },
   claim:   { script: 'claim.js',   group: 'work', summary: 'Claim a task by id  (bongos claim 1246)' },
   ship:    { script: 'ship.js',    group: 'work', summary: 'Grade, merge, and deploy your claimed task' },
   release: { script: 'release.js', group: 'work', summary: 'Cancel a claim — task returns to ready (no credits)' },

package/clients/bongos-client/README.md

@@ -1,22 +1,22 @@
-# @cloudbongos/client
+# @bongos/client
 
 A **generated**, zero-dependency typed client for the Bongos API — produced from
 `docs/api/openapi.json` by `scripts/gds/gen-api-client.js` (ADR 0118). Do not edit
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 224 operations across 40 resource groups
+- 229 operations across 40 resource groups
 
 ## Install
 
 ```bash
-npm install @cloudbongos/client   # internal registry / workspace path
+npm install @bongos/client   # internal registry / workspace path
 ```
 
 ## Use
 
 ```js
-import { createClient, ApiError } from '@cloudbongos/client';
+import { createClient, ApiError } from '@bongos/client';
 
 const api = createClient({
   baseUrl: 'https://example.com/api/bongos/v1', // or omit for same-origin (browser)

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

@@ -1,8 +1,11 @@
-// @cloudbongos/client (browser-global build) — GENERATED from index.mjs by
+// @bongos/client (browser-global build) — GENERATED from index.mjs by
 // scripts/gds/gen-api-client.js. DO NOT EDIT BY HAND. Exposes window.BongosClient
 // for classic <script> pages. Same behavior as the ESM build.
 (function (global) {
 'use strict';
+// @bongos/client — GENERATED from the OpenAPI spec by
+// scripts/gds/gen-api-client.js (task 1995 / ADR 0118). DO NOT EDIT BY HAND —
+// regenerate on spec change. Zero deps; uses the platform fetch.
 
 const API_VERSION = "v1";
 const DEFAULT_BASE_URL = "/api/bongos/v1";
@@ -304,10 +307,14 @@ function createClient(opts = {}) {
       patchGoalsIdMembersBuilderId: (args) => request("PATCH", "/goals/{id}/members/{builderId}", { hasBody: true }, args),
       // POST /goals/{id}/reopen — rank: metic+archon — POST /goals/:id/reopen
       postGoalsIdReopen: (args) => request("POST", "/goals/{id}/reopen", { hasBody: true }, args),
+      // GET /goals/{id}/requests — rank: any-builder — GET /goals/:id/requests
+      getGoalsIdRequests: (args) => request("GET", "/goals/{id}/requests", { hasBody: false }, args),
       // POST /goals/{id}/requests — rank: any-builder — POST /goals/:id/requests
       postGoalsIdRequests: (args) => request("POST", "/goals/{id}/requests", { hasBody: true }, args),
       // POST /goals/{id}/requests/{reqId}/respond — rank: any-builder — POST /goals/:id/requests/:reqId/respond
       postGoalsIdRequestsReqIdRespond: (args) => request("POST", "/goals/{id}/requests/{reqId}/respond", { hasBody: true }, args),
+      // POST /goals/{id}/requests/{reqId}/withdraw — rank: any-builder — POST /goals/:id/requests/:reqId/withdraw
+      postGoalsIdRequestsReqIdWithdraw: (args) => request("POST", "/goals/{id}/requests/{reqId}/withdraw", { hasBody: true }, args),
       // POST /goals/{id}/scope — rank: metic+archon — POST /goals/:id/scope
       postGoalsIdScope: (args) => request("POST", "/goals/{id}/scope", { hasBody: true }, args),
       // POST /goals/{id}/tasks — rank: any-builder — POST /goals/:id/tasks
@@ -440,6 +447,8 @@ function createClient(opts = {}) {
       postModulesKeyEnable: (args) => request("POST", "/modules/{key}/enable", { hasBody: true }, args),
       // POST /modules/{key}/submit — rank: metic+archon — POST /modules/:key/submit
       postModulesKeySubmit: (args) => request("POST", "/modules/{key}/submit", { hasBody: true }, args),
+      // GET /modules/submissions — rank: metic+archon — GET /modules/submissions
+      getModulesSubmissions: (args) => request("GET", "/modules/submissions", { hasBody: false }, args),
     },
     "overrideRequests": {
       // GET /override-requests — rank: archon — GET /override-requests
@@ -454,6 +463,8 @@ function createClient(opts = {}) {
       getProvisioningFleetCostLedger: (args) => request("GET", "/provisioning/fleet/cost-ledger", { hasBody: false }, args),
       // GET /provisioning/github-app/callback — rank: public — GET /provisioning/github-app/callback
       getProvisioningGithubAppCallback: (args) => request("GET", "/provisioning/github-app/callback", { hasBody: false }, args),
+      // GET /provisioning/github-app/status — rank: public — GET /provisioning/github-app/status
+      getProvisioningGithubAppStatus: (args) => request("GET", "/provisioning/github-app/status", { hasBody: false }, args),
       // GET /provisioning/health — rank: public — GET /provisioning/health
       getProvisioningHealth: (args) => request("GET", "/provisioning/health", { hasBody: false }, args),
       // GET /provisioning/instances — rank: any-builder — GET /provisioning/instances
@@ -468,6 +479,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/teardown — rank: any-builder — POST /provisioning/instances/:id/teardown
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
+      // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
+      getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
       // GET /provisioning/tls-check — rank: public — GET /provisioning/tls-check
       getProvisioningTlsCheck: (args) => request("GET", "/provisioning/tls-check", { hasBody: false }, args),
     },

package/clients/bongos-client/index.cjs

@@ -1,6 +1,9 @@
-// @cloudbongos/client (CommonJS build) — GENERATED from index.mjs by
+// @bongos/client (CommonJS build) — GENERATED from index.mjs by
 // scripts/gds/gen-api-client.js. DO NOT EDIT BY HAND. Same behavior as the ESM
 // build; only the module bindings differ. For require()-based consumers.
+// @bongos/client — GENERATED from the OpenAPI spec by
+// scripts/gds/gen-api-client.js (task 1995 / ADR 0118). DO NOT EDIT BY HAND —
+// regenerate on spec change. Zero deps; uses the platform fetch.
 'use strict';
 
 const API_VERSION = "v1";
@@ -303,10 +306,14 @@ function createClient(opts = {}) {
       patchGoalsIdMembersBuilderId: (args) => request("PATCH", "/goals/{id}/members/{builderId}", { hasBody: true }, args),
       // POST /goals/{id}/reopen — rank: metic+archon — POST /goals/:id/reopen
       postGoalsIdReopen: (args) => request("POST", "/goals/{id}/reopen", { hasBody: true }, args),
+      // GET /goals/{id}/requests — rank: any-builder — GET /goals/:id/requests
+      getGoalsIdRequests: (args) => request("GET", "/goals/{id}/requests", { hasBody: false }, args),
       // POST /goals/{id}/requests — rank: any-builder — POST /goals/:id/requests
       postGoalsIdRequests: (args) => request("POST", "/goals/{id}/requests", { hasBody: true }, args),
       // POST /goals/{id}/requests/{reqId}/respond — rank: any-builder — POST /goals/:id/requests/:reqId/respond
       postGoalsIdRequestsReqIdRespond: (args) => request("POST", "/goals/{id}/requests/{reqId}/respond", { hasBody: true }, args),
+      // POST /goals/{id}/requests/{reqId}/withdraw — rank: any-builder — POST /goals/:id/requests/:reqId/withdraw
+      postGoalsIdRequestsReqIdWithdraw: (args) => request("POST", "/goals/{id}/requests/{reqId}/withdraw", { hasBody: true }, args),
       // POST /goals/{id}/scope — rank: metic+archon — POST /goals/:id/scope
       postGoalsIdScope: (args) => request("POST", "/goals/{id}/scope", { hasBody: true }, args),
       // POST /goals/{id}/tasks — rank: any-builder — POST /goals/:id/tasks
@@ -439,6 +446,8 @@ function createClient(opts = {}) {
       postModulesKeyEnable: (args) => request("POST", "/modules/{key}/enable", { hasBody: true }, args),
       // POST /modules/{key}/submit — rank: metic+archon — POST /modules/:key/submit
       postModulesKeySubmit: (args) => request("POST", "/modules/{key}/submit", { hasBody: true }, args),
+      // GET /modules/submissions — rank: metic+archon — GET /modules/submissions
+      getModulesSubmissions: (args) => request("GET", "/modules/submissions", { hasBody: false }, args),
     },
     "overrideRequests": {
       // GET /override-requests — rank: archon — GET /override-requests
@@ -453,6 +462,8 @@ function createClient(opts = {}) {
       getProvisioningFleetCostLedger: (args) => request("GET", "/provisioning/fleet/cost-ledger", { hasBody: false }, args),
       // GET /provisioning/github-app/callback — rank: public — GET /provisioning/github-app/callback
       getProvisioningGithubAppCallback: (args) => request("GET", "/provisioning/github-app/callback", { hasBody: false }, args),
+      // GET /provisioning/github-app/status — rank: public — GET /provisioning/github-app/status
+      getProvisioningGithubAppStatus: (args) => request("GET", "/provisioning/github-app/status", { hasBody: false }, args),
       // GET /provisioning/health — rank: public — GET /provisioning/health
       getProvisioningHealth: (args) => request("GET", "/provisioning/health", { hasBody: false }, args),
       // GET /provisioning/instances — rank: any-builder — GET /provisioning/instances
@@ -467,6 +478,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/teardown — rank: any-builder — POST /provisioning/instances/:id/teardown
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
+      // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
+      getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
       // GET /provisioning/tls-check — rank: public — GET /provisioning/tls-check
       getProvisioningTlsCheck: (args) => request("GET", "/provisioning/tls-check", { hasBody: false }, args),
     },

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

@@ -1,4 +1,4 @@
-// GENERATED — TypeScript types for @cloudbongos/client (task 1995; field-level
+// GENERATED — TypeScript types for @bongos/client (task 1995; field-level
 // request typing added in task 2050 / ADR 0118). DO NOT EDIT BY HAND.
 export declare const API_VERSION: string;
 export declare const DEFAULT_BASE_URL: string;
@@ -34,6 +34,7 @@ export interface GetDemoHealthResponse { module: unknown; ok: boolean; coreVersi
 export interface GetDiscordChannelsPlanResponse { ok: boolean; guild_id: unknown; op_count: unknown; ops: unknown; warnings: unknown }
 export interface GetDoneWhenPendingReviewResponse { criteria: unknown; count: unknown }
 export interface GetGoalsIdConflictsResponse { ok: boolean; goal_id: unknown; conflicts: unknown; cross_goals_considered: unknown }
+export interface GetGoalsIdRequestsResponse { requests: unknown }
 export interface GetGoalsIdResponse { goal: unknown; members: unknown; criteria: unknown; dependencies: unknown }
 export interface GetGoalsResponse { goals: unknown }
 export interface GetGradesByBuilderResponse { window_days: unknown; builders: unknown }
@@ -54,11 +55,14 @@ export interface GetMemoryBfgBuildersBuilderIdFilesResponse { builder_id: unknow
 export interface GetMemoryFileResponse { builder_id: unknown; path: unknown; content: unknown; sha256: unknown; byte_len: unknown; mtime: unknown; updated_at: unknown; created_at: unknown }
 export interface GetMemoryFilesResponse { builder_id: unknown; count: unknown; files: unknown }
 export interface GetModulesResponse { modules: unknown; own_built: unknown; core_loaded: unknown; submit_pipeline_live: boolean }
+export interface GetModulesSubmissionsResponse { submissions: unknown }
 export interface GetOverrideRequestsResponse { requests: unknown }
 export interface GetProvisioningFleetResponse { instances: unknown }
+export interface GetProvisioningGithubAppStatusResponse { ok: boolean; status: unknown; ready: unknown; terminal: unknown; domain: unknown; instance_status: unknown }
 export interface GetProvisioningHealthResponse { module: unknown; ok: boolean; coreVersion: unknown }
 export interface GetProvisioningInstancesIdResponse { instance: unknown; open_intent: unknown }
 export interface GetProvisioningInstancesResponse { instances: unknown }
+export interface GetProvisioningOnboardPlanResponse { mode: unknown; steps: unknown }
 export interface GetPublicBlockersIdResponse { blocker: unknown }
 export interface GetPublicBountyTableResponse { table: unknown; currency: unknown }
 export interface GetPublicGradesResponse { window_days: unknown; rolling: unknown; trend: unknown; threshold: unknown; grader_version: unknown }
@@ -177,6 +181,7 @@ export interface PostGoalsIdMembersResponse { ok: boolean; member: unknown }
 export interface PostGoalsIdReopenResponse { ok: boolean; goal: unknown }
 export interface PostGoalsIdRequestsReqIdRespondRequest { action: string }
 export interface PostGoalsIdRequestsReqIdRespondResponse { ok: boolean; action: unknown; request: unknown; member?: unknown }
+export interface PostGoalsIdRequestsReqIdWithdrawResponse { ok: boolean; request: unknown }
 export interface PostGoalsIdRequestsRequest { note?: string }
 export interface PostGoalsIdRequestsResponse { ok: boolean; request: unknown }
 export interface PostGoalsIdScopeRequest { add: string[] }
@@ -205,6 +210,8 @@ export interface PostMemoryBuildersBuilderIdBfgWriteResponse { ok: boolean; buil
 export interface PostMemorySyncRequest { files?: unknown[] }
 export interface PostModulesKeyEnableRequest { enabled?: unknown }
 export interface PostModulesKeyEnableResponse { ok: boolean; key: unknown; enabled: unknown; note: unknown }
+export interface PostModulesKeySubmitRequest { signed_by?: string }
+export interface PostModulesKeySubmitResponse { ok: boolean; submission: unknown }
 export interface PostOverrideRequestsIdDecideRequest { decision: string; note?: string }
 export interface PostProvisioningInstancesIdForceTeardownResponse { ok: boolean; queued: unknown; action: unknown; status: unknown; message: unknown }
 export interface PostProvisioningInstancesIdGithubAppRequest { account?: string }
@@ -483,10 +490,14 @@ export interface BongosClient {
     patchGoalsIdMembersBuilderId(args: RequestArgs & { body: PatchGoalsIdMembersBuilderIdRequest }): Promise<PatchGoalsIdMembersBuilderIdResponse>;
     /** POST /goals/{id}/reopen — rank: metic+archon */
     postGoalsIdReopen(args?: RequestArgs): Promise<PostGoalsIdReopenResponse>;
+    /** GET /goals/{id}/requests — rank: any-builder */
+    getGoalsIdRequests(args?: RequestArgs): Promise<GetGoalsIdRequestsResponse>;
     /** POST /goals/{id}/requests — rank: any-builder */
     postGoalsIdRequests(args?: RequestArgs & { body?: PostGoalsIdRequestsRequest }): Promise<PostGoalsIdRequestsResponse>;
     /** POST /goals/{id}/requests/{reqId}/respond — rank: any-builder */
     postGoalsIdRequestsReqIdRespond(args: RequestArgs & { body: PostGoalsIdRequestsReqIdRespondRequest }): Promise<PostGoalsIdRequestsReqIdRespondResponse>;
+    /** POST /goals/{id}/requests/{reqId}/withdraw — rank: any-builder */
+    postGoalsIdRequestsReqIdWithdraw(args?: RequestArgs): Promise<PostGoalsIdRequestsReqIdWithdrawResponse>;
     /** POST /goals/{id}/scope — rank: metic+archon */
     postGoalsIdScope(args: RequestArgs & { body: PostGoalsIdScopeRequest }): Promise<PostGoalsIdScopeResponse>;
     /** POST /goals/{id}/tasks — rank: any-builder */
@@ -618,7 +629,9 @@ export interface BongosClient {
     /** POST /modules/{key}/enable — rank: metic+archon */
     postModulesKeyEnable(args?: RequestArgs & { body?: PostModulesKeyEnableRequest }): Promise<PostModulesKeyEnableResponse>;
     /** POST /modules/{key}/submit — rank: metic+archon */
-    postModulesKeySubmit(args?: RequestArgs): Promise<ApiResponse>;
+    postModulesKeySubmit(args?: RequestArgs & { body?: PostModulesKeySubmitRequest }): Promise<PostModulesKeySubmitResponse>;
+    /** GET /modules/submissions — rank: metic+archon */
+    getModulesSubmissions(args?: RequestArgs): Promise<GetModulesSubmissionsResponse>;
   };
   "overrideRequests": {
     /** GET /override-requests — rank: archon */
@@ -633,6 +646,8 @@ export interface BongosClient {
     getProvisioningFleetCostLedger(args?: RequestArgs): Promise<ApiResponse>;
     /** GET /provisioning/github-app/callback — rank: public */
     getProvisioningGithubAppCallback(args?: RequestArgs): Promise<ApiResponse>;
+    /** GET /provisioning/github-app/status — rank: public */
+    getProvisioningGithubAppStatus(args?: RequestArgs): Promise<GetProvisioningGithubAppStatusResponse>;
     /** GET /provisioning/health — rank: public */
     getProvisioningHealth(args?: RequestArgs): Promise<GetProvisioningHealthResponse>;
     /** GET /provisioning/instances — rank: any-builder */
@@ -647,6 +662,8 @@ export interface BongosClient {
     postProvisioningInstancesIdGithubApp(args?: RequestArgs & { body?: PostProvisioningInstancesIdGithubAppRequest }): Promise<PostProvisioningInstancesIdGithubAppResponse>;
     /** POST /provisioning/instances/{id}/teardown — rank: any-builder */
     postProvisioningInstancesIdTeardown(args?: RequestArgs): Promise<PostProvisioningInstancesIdTeardownResponse>;
+    /** GET /provisioning/onboard-plan — rank: public */
+    getProvisioningOnboardPlan(args?: RequestArgs): Promise<GetProvisioningOnboardPlanResponse>;
     /** GET /provisioning/tls-check — rank: public */
     getProvisioningTlsCheck(args?: RequestArgs): Promise<ApiResponse>;
   };

package/clients/bongos-client/index.mjs

@@ -1,4 +1,4 @@
-// @cloudbongos/client — GENERATED from the OpenAPI spec by
+// @bongos/client — GENERATED from the OpenAPI spec by
 // scripts/gds/gen-api-client.js (task 1995 / ADR 0118). DO NOT EDIT BY HAND —
 // regenerate on spec change. Zero deps; uses the platform fetch.
 'use strict';
@@ -303,10 +303,14 @@ export function createClient(opts = {}) {
       patchGoalsIdMembersBuilderId: (args) => request("PATCH", "/goals/{id}/members/{builderId}", { hasBody: true }, args),
       // POST /goals/{id}/reopen — rank: metic+archon — POST /goals/:id/reopen
       postGoalsIdReopen: (args) => request("POST", "/goals/{id}/reopen", { hasBody: true }, args),
+      // GET /goals/{id}/requests — rank: any-builder — GET /goals/:id/requests
+      getGoalsIdRequests: (args) => request("GET", "/goals/{id}/requests", { hasBody: false }, args),
       // POST /goals/{id}/requests — rank: any-builder — POST /goals/:id/requests
       postGoalsIdRequests: (args) => request("POST", "/goals/{id}/requests", { hasBody: true }, args),
       // POST /goals/{id}/requests/{reqId}/respond — rank: any-builder — POST /goals/:id/requests/:reqId/respond
       postGoalsIdRequestsReqIdRespond: (args) => request("POST", "/goals/{id}/requests/{reqId}/respond", { hasBody: true }, args),
+      // POST /goals/{id}/requests/{reqId}/withdraw — rank: any-builder — POST /goals/:id/requests/:reqId/withdraw
+      postGoalsIdRequestsReqIdWithdraw: (args) => request("POST", "/goals/{id}/requests/{reqId}/withdraw", { hasBody: true }, args),
       // POST /goals/{id}/scope — rank: metic+archon — POST /goals/:id/scope
       postGoalsIdScope: (args) => request("POST", "/goals/{id}/scope", { hasBody: true }, args),
       // POST /goals/{id}/tasks — rank: any-builder — POST /goals/:id/tasks
@@ -439,6 +443,8 @@ export function createClient(opts = {}) {
       postModulesKeyEnable: (args) => request("POST", "/modules/{key}/enable", { hasBody: true }, args),
       // POST /modules/{key}/submit — rank: metic+archon — POST /modules/:key/submit
       postModulesKeySubmit: (args) => request("POST", "/modules/{key}/submit", { hasBody: true }, args),
+      // GET /modules/submissions — rank: metic+archon — GET /modules/submissions
+      getModulesSubmissions: (args) => request("GET", "/modules/submissions", { hasBody: false }, args),
     },
     "overrideRequests": {
       // GET /override-requests — rank: archon — GET /override-requests
@@ -453,6 +459,8 @@ export function createClient(opts = {}) {
       getProvisioningFleetCostLedger: (args) => request("GET", "/provisioning/fleet/cost-ledger", { hasBody: false }, args),
       // GET /provisioning/github-app/callback — rank: public — GET /provisioning/github-app/callback
       getProvisioningGithubAppCallback: (args) => request("GET", "/provisioning/github-app/callback", { hasBody: false }, args),
+      // GET /provisioning/github-app/status — rank: public — GET /provisioning/github-app/status
+      getProvisioningGithubAppStatus: (args) => request("GET", "/provisioning/github-app/status", { hasBody: false }, args),
       // GET /provisioning/health — rank: public — GET /provisioning/health
       getProvisioningHealth: (args) => request("GET", "/provisioning/health", { hasBody: false }, args),
       // GET /provisioning/instances — rank: any-builder — GET /provisioning/instances
@@ -467,6 +475,8 @@ export function createClient(opts = {}) {
       postProvisioningInstancesIdGithubApp: (args) => request("POST", "/provisioning/instances/{id}/github-app", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/teardown — rank: any-builder — POST /provisioning/instances/:id/teardown
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
+      // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
+      getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
       // GET /provisioning/tls-check — rank: public — GET /provisioning/tls-check
       getProvisioningTlsCheck: (args) => request("GET", "/provisioning/tls-check", { hasBody: false }, args),
     },

package/clients/bongos-client/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@cloudbongos/client",
+  "name": "@bongos/client",
   "version": "0.0.2",
   "description": "Generated typed client for the Bongos API (ADR 0118). Do not edit by hand.",
   "type": "module",

package/docs/adr/0133-github-app-manifest-onboarding-signin.md

@@ -33,6 +33,8 @@ The conversion endpoint is unauthenticated (the code is the auth), so the web ti
 
 `redirect_url` = the **mothership** callback (the instance can't do the exchange). `callback_urls` = the **instance's** own `/api/gds/auth/web/callback` (what `auth.js` actually builds) **and** the `/api/bongos/...` alias, so sign-in works regardless of which prefix a build emits. `default_permissions: {}` (sign-in needs none), `hook_attributes.active:false`, `public:false`. Personal vs org differs only in the POST URL (derived from the repo owner); the App works for sign-in either way.
 
+**App name (tasks 2093 → 2095).** GitHub App names are globally unique across all of GitHub, so a bare project slug (e.g. `demo`) is almost always already taken. The auto name is the **instance domain** (e.g. `demo.cloudbongos.com`): a domain is inherently unique (so it never collides) and it reads perfectly on GitHub's sign-in consent screen, where the name is shown as *"`<name>` by `<owner>` … will redirect to `https://<domain>`"* — the name IS the destination. GitHub keeps the dots in the display name (only the internal slug is transformed) and caps it at 34 chars. **Fallback** (no domain, or a domain over 34 chars): brand-qualify the project — `<mothership brand> - <project>`, e.g. `Cloud Bongos - demo`, from the mothership's own `branding().identity.productName` (portable, not hardcoded) — still far less collision-prone than a bare slug. Either way it is only a default the owner can rename on GitHub's confirmation screen.
+
 ## Consequences
 
 - **Back-compat preserved.** An instance already on an OAuth App keeps working untouched — `loadGithubCreds()` reads the same `<PREFIX>_GITHUB_CLIENT_ID/SECRET`. The manifest path is the new *default* for fresh instances; nothing about `auth.js` changed.