@bongos/core 1.24.41 → 1.24.42

package/modules/hall-ui/public/shell.js

@@ -804,6 +804,16 @@
     }
     if (data && data.moved) renderCoreMoveNotice(data.moved); // task 1004731: loads core-move-notice.js, which draws it
   }
+  // task 1005076: a builder whose setup is not complete sees only the setup screen (setup-gate.js),
+  // loaded once: applyAccess runs again before the first load lands, and a second copy drew a second screen.
+  var setupGateLoading = false;
+  function holdForSetup(builder) {
+    if (access.authed !== true || !access.setup || access.setup.complete !== false) return false;
+    var go = function () { if (window.OTBSetupGate) window.OTBSetupGate.show(access.setup, { api: api, builder: builder }); };
+    if (window.OTBSetupGate) go();
+    else if (!setupGateLoading) { setupGateLoading = true; loadHallScript('setup-gate.js', go); }
+    return true;
+  }
   // One hall script on demand, stamped with the shell's own ?v= (task 1004996 made it one helper).
   function loadHallScript(file, onload, onerror) {
     var head = document.head, tag = head && head.appendChild && document.createElement ? document.createElement('script') : null;
@@ -1136,6 +1146,8 @@
       if ('founding' in state) {
         access.founding = (state.founding && typeof state.founding === 'object') ? state.founding : null;
       }
+      // task 1005076: /me's onboarding.setup; incomplete holds the hall behind setup-gate.js.
+      if ('setup' in state) access.setup = (state.setup && typeof state.setup === 'object') ? state.setup : null;
       if (state.builder) { renderUser(state.builder); applyCraftEmphasis(state.builder); }
       // task 1004713: which seats this builder holds — /me's server-resolved block.
       if (state.builder && access.authed === true) { loadPositions(state.builder, state.positions); loadGithubChip(state.builder); }
@@ -1162,7 +1174,8 @@
     // permission map, which the loop above is what the shell has just been told.
     maybeRenderCoreUpdate();
     // task 1004492: a builder with no mode yet this session is asked once — unless Home's welcome (task 1004785, welcome-boot.js) greets the day's first visit instead; it marks the picker asked.
-    if (!(window.OTBWelcome && window.OTBWelcome.onAccess(access, state && state.builder)) && CRAFT) CRAFT.onAccess(access, state && state.builder);
+    // task 1005076: neither is drawn over the setup screen; setup comes first.
+    if (!holdForSetup(state && state.builder) && !(window.OTBWelcome && window.OTBWelcome.onAccess(access, state && state.builder)) && CRAFT) CRAFT.onAccess(access, state && state.builder);
     var signin = document.getElementById('shell-signin');
     if (signin) signin.hidden = access.authed !== false;
     var user = document.getElementById('shell-user');
@@ -1406,6 +1419,8 @@
         founding: me.founding_mode || null,
         // task 1004713: the government positions this builder holds (server-resolved).
         positions: me.positions || null,
+        // task 1005076: whether setup is complete; incomplete shows setup-gate.js.
+        setup: (me.onboarding && me.onboarding.setup) || null,
         builder: me.builder,
       });
     }).catch(function () { /* cosmetic only */ });

package/modules/hall-ui/public/street.html

@@ -231,7 +231,7 @@
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-11-05-oversight"></script>
-<script src="/builders/shell.js?v=2026-11-05-oversight"></script>
+<script src="/builders/shell.js?v=2026-11-05-setup-gate"></script>
 <script src="/builders/palette.js" defer></script>
 <script src="/builders/gov-living.js?v=2026-10-09-positions1"></script>
 <script src="/builders/gov-feeds.js?v=2026-10-09-living3"></script>

package/modules/hall-ui/public/studio.html

@@ -225,7 +225,7 @@
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-11-05-oversight"></script>
-<script src="/builders/shell.js?v=2026-11-05-oversight"></script>
+<script src="/builders/shell.js?v=2026-11-05-setup-gate"></script>
 <script src="/builders/palette.js" defer></script>
 <!-- The kit, for its ONE renderer: the full-size ship-time visual figure
      (task 1003829), which the older reviews still show. -->

package/modules/hall-ui/public/style.css

@@ -1356,6 +1356,88 @@ html[data-fullscreen="on"][data-fullscreen-plain="on"] .app-content { padding-to
    "ask me again" box. Each door carries its scene from the approved prototype,
    which is night-dark in either theme because every scene is a night one. */
 html.craft-picker-open { overflow: hidden; }
+/* The setup flow (setup-gate.js, task 1005076): the one screen a new builder sees until set up. */
+html.setup-gate-open { overflow: hidden; }
+.setup-gate {
+  position: fixed;
+  inset: 0;
+  z-index: calc(var(--z-modal) + 1);
+  display: flex;
+  justify-content: center;
+  align-items: flex-start;
+  padding: max(24px, 6vh) 16px 24px;
+  overflow-y: auto;
+  background: var(--bg);
+}
+.setup-gate__panel {
+  width: min(640px, 100%);
+  box-sizing: border-box;
+  padding: 36px 40px 28px;
+  border-radius: 22px;
+  background: var(--bg-card);
+  color: var(--ink);
+}
+.setup-gate__count { margin: 0; font-size: 13px; color: var(--ink-faint); }
+.setup-gate__title { margin: 6px 0 8px; font-family: var(--font-display); font-size: clamp(26px, 4vw, 34px); font-weight: 300; letter-spacing: -0.02em; line-height: 1.2; }
+.setup-gate__lede { margin: 0 0 24px; font-size: 16px; line-height: 1.5; color: var(--ink-soft); }
+.setup-gate__steps { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 4px; }
+.setup-gate__step { display: flex; gap: 14px; padding: 12px 0; border-top: 1px solid var(--rule-soft); }
+.setup-gate__step:first-child { border-top: 0; }
+.setup-gate__mark {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border-radius: var(--radius-pill);
+  border: 1px solid var(--rule);
+  font-size: 13px;
+  color: var(--ink-soft);
+}
+.setup-gate__mark svg { width: 16px; height: 16px; }
+.setup-gate__step.is-done .setup-gate__mark { border-color: transparent; background: var(--ok-weak); color: var(--ok); }
+.setup-gate__step.is-current .setup-gate__mark { border-color: var(--accent); color: var(--ink); }
+.setup-gate__body { min-width: 0; flex: 1; }
+.setup-gate__label { margin: 4px 0 0; font-size: 16px; font-weight: 500; }
+.setup-gate__step.is-done .setup-gate__label { color: var(--ink-soft); font-weight: 400; }
+.setup-gate__hint { margin: 6px 0 0; font-size: 15px; line-height: 1.5; color: var(--ink-soft); }
+.setup-gate__how { margin: 10px 0 0; padding-left: 20px; font-size: 15px; line-height: 1.6; }
+/* The clone block is several commands, one per line: `pre` keeps the breaks on screen and in
+   copy-on-click (it copies innerText). Both axes named: the one-axis-strip rule. */
+.setup-gate__code {
+  display: block;
+  margin: 12px 0 0;
+  padding: 10px 14px;
+  border-radius: var(--radius-sm);
+  background: var(--glass);
+  font-family: var(--font-mono);
+  font-size: 13px;
+  white-space: pre;
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+.setup-gate code { font-family: var(--font-mono); font-size: 14px; padding: 1px 6px; border-radius: 6px; background: var(--glass); }
+.setup-gate__crafts { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
+.setup-gate__craft,
+.setup-gate__save {
+  min-height: 36px;
+  padding: 0 16px;
+  border-radius: var(--radius-pill);
+  border: 1px solid var(--rule);
+  background: none;
+  color: var(--ink);
+  font: inherit;
+  font-size: 14px;
+  cursor: pointer;
+}
+.setup-gate__craft[aria-pressed="true"] { border-color: var(--accent); background: var(--accent-tint); }
+.setup-gate__save { margin-top: 12px; background: var(--accent); border-color: var(--accent); color: var(--accent-on); }
+.setup-gate__save:disabled { opacity: .5; cursor: default; }
+.setup-gate__err { margin: 8px 0 0; font-size: 14px; color: var(--danger); }
+.setup-gate__foot { margin: 24px 0 0; font-size: 14px; }
+.setup-gate__foot a { color: var(--ink-soft); }
+@media (max-width: 640px) { .setup-gate__panel { padding: 28px 20px 20px; border-radius: 18px; } }
 .craft-picker {
   position: fixed;
   inset: 0;
@@ -2116,8 +2198,7 @@ html.pb-editing main { padding-bottom: 180px; }
   text-align: center;
 }
 
-.pill-link,
-#welcome-reopen a {
+.pill-link {
   display: inline-flex;
   align-items: center;
   min-height: 28px;
@@ -2129,7 +2210,6 @@ html.pb-editing main { padding-bottom: 180px; }
   border-radius: var(--radius-pill);
   padding: 0 12px;
 }
-#welcome-reopen { margin: 0; }
 .pill-link:hover { color: var(--ink); text-decoration: none; border-color: var(--ink-faint); }
 
 /* ---------- stat tiles (Home) ----------
@@ -3166,119 +3246,8 @@ main [id] { scroll-margin-top: calc(var(--topbar-h) + 16px); }
 
 .curve__kinds { display: flex; flex-direction: column; gap: 6px; margin-top: 16px; }
 
-/* ---------- onboarding checklist ---------- */
-
-.onboarding-list {
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  display: flex;
-  flex-direction: column;
-}
-.onboarding-item {
-  display: grid;
-  grid-template-columns: 26px minmax(0, 1fr) auto;
-  gap: 4px 12px;
-  align-items: start;
-  padding: 12px 4px;
-  border-bottom: 1px solid var(--rule-soft);
-}
-.onboarding-item:last-child { border-bottom: none; }
-.onboarding-item--placeholder { color: var(--ink-faint); }
-.onboarding-item__mark {
-  width: 22px; height: 22px;
-  border-radius: 50%;
-  border: 1.5px solid var(--border-strong);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: 12px;
-  color: var(--ink-faint);
-  background: var(--surface);
-}
-.onboarding-item--cleared .onboarding-item__mark {
-  background: var(--ok);
-  border-color: var(--ok);
-  color: #fff;
-}
-.onboarding-item--current .onboarding-item__mark { border-color: var(--accent); color: var(--accent-text); }
-.onboarding-item--current { background: var(--accent-weak); border-radius: var(--radius-sm); padding-left: 10px; padding-right: 10px; border-bottom-color: transparent; }
-.onboarding-item--locked { opacity: 0.6; }
-.onboarding-item__body { min-width: 0; }
-.onboarding-item__label { font-weight: 600; font-size: 13.5px; }
-.onboarding-item--cleared .onboarding-item__label { color: var(--ink-soft); font-weight: 500; }
-.onboarding-item__hint { font-size: 12.5px; color: var(--ink-soft); margin-top: 1px; }
-.onboarding-item__detail { font-size: 12.5px; color: var(--ink-soft); margin-top: 6px; }
-.onboarding-item__detail code { background: var(--surface-2); padding: 1px 5px; border-radius: 4px; }
-.onboarding-item__action { align-self: center; }
-.onboarding-item__disc-pick { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
-.onboarding-item__disc {
-  border: 1px solid var(--border-strong);
-  background: var(--surface);
-  color: var(--ink-soft);
-  border-radius: 999px;
-  font-size: 12.5px;
-  font-weight: 500;
-  padding: 4px 12px;
-  cursor: pointer;
-}
-.onboarding-item__disc:hover { background: var(--surface-2); }
-.onboarding-item__disc--on {
-  background: var(--accent-weak);
-  color: var(--accent-text);
-  border-color: color-mix(in srgb, var(--accent) 40%, transparent);
-}
-.onboarding-item__discord { font-weight: 600; }
-
-@media (max-width: 560px) {
-  .onboarding-item { grid-template-columns: 26px minmax(0, 1fr); }
-  .onboarding-item__action { grid-column: 2; justify-self: start; }
-}
-
-/* ---------- welcome panel + setup selector ---------- */
-
-.scroll--welcome {
-  position: relative;
-  border-left: 3px solid var(--accent);
-}
-.scroll--welcome--minimized .welcome { display: none; }
-.welcome__minimize {
-  position: absolute;
-  top: 12px; right: 12px;
-  width: 26px; height: 26px;
-  border: 1px solid var(--border);
-  border-radius: var(--radius-sm);
-  background: var(--surface);
-  color: var(--ink-soft);
-  font-size: 14px;
-  line-height: 1;
-  cursor: pointer;
-}
-.welcome__minimize:hover { background: var(--surface-2); }
-.welcome__lede { font-size: 13.5px; color: var(--ink-soft); max-width: 70ch; }
-.welcome__unlocks { margin: 8px 0; padding-left: 18px; font-size: 13px; color: var(--ink-soft); }
-.welcome__cmd, .welcome__paste {
-  font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
-  font-size: 12.5px;
-  background: var(--surface-2);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-sm);
-  padding: 8px 12px;
-  overflow-x: auto;
-}
-/* The get-the-code block is several commands, one per line. Without `pre` the
-   line breaks collapse on screen AND in copy-on-click (it copies innerText),
-   so a builder pasted every command onto one line. Both axes named: see the
-   one-axis-strip rule in this module's CLAUDE.md. */
-.setup__getcode .welcome__paste {
-  display: block;
-  white-space: pre;
-  overflow-y: hidden;
-}
+/* ---------- setup selector (the tab strip; .setup__tab is the kit's tab idiom) ---------- */
 
-.setup { margin-top: 12px; }
-.setup__intro { font-size: 13px; color: var(--ink-soft); }
-.setup__toggle { display: flex; border: 0; border-bottom: 1px solid var(--rule); margin: 8px 0 12px; flex-wrap: wrap; }
 /* An open tab is the live thing in the strip, so it is what the accent lights:
    a 2px underline sitting on the strip’s own hairline. */
 .setup__tab {
@@ -3366,8 +3335,7 @@ main [id] { scroll-margin-top: calc(var(--topbar-h) + 16px); }
 html[data-door="out"] .app-sidebar,
 html[data-door="out"] .app-scrim,
 html[data-door="out"] .app-topbar,
-html[data-door="out"] .app-foot,
-html[data-door="out"] #welcome-reopen { display: none; }
+html[data-door="out"] .app-foot { display: none; }
 html[data-door="out"] .app-body { margin-left: 0; }
 /* body in the selector outranks Home's own body[data-page="home"] .page-head--hall. */
 html[data-door="out"] body .page-head {

package/modules/hall-ui/public/task.html

@@ -59,7 +59,7 @@
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-11-05-oversight"></script>
-<script src="/builders/shell.js?v=2026-11-05-oversight"></script>
+<script src="/builders/shell.js?v=2026-11-05-setup-gate"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- task-detail.js still owns the #/idea/N and #/blocker/N deep-link overlay

package/modules/hall-ui/public/thinking.html

@@ -141,7 +141,7 @@
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-11-05-oversight"></script>
-<script src="/builders/shell.js?v=2026-11-05-oversight"></script>
+<script src="/builders/shell.js?v=2026-11-05-setup-gate"></script>
 <script src="/builders/palette.js" defer></script>
 
 <script src="/builders/idea-objects.js?v=2026-09-27-split"></script>

package/modules/hall-ui/public/tweak-editor.html

@@ -145,7 +145,7 @@
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-11-05-oversight"></script>
-<script src="/builders/shell.js?v=2026-11-05-oversight"></script>
+<script src="/builders/shell.js?v=2026-11-05-setup-gate"></script>
 <script src="/builders/palette.js" defer></script>
 <script src="/builders/brand-holes.js?v=2026-09-29-aqfix"></script>
 <script src="/builders/tweak-editor-lib.js?v=2026-09-29-tw27"></script>

package/modules/hall-ui/public/watch.html

@@ -271,7 +271,7 @@
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-11-05-oversight"></script>
-<script src="/builders/shell.js?v=2026-11-05-oversight"></script>
+<script src="/builders/shell.js?v=2026-11-05-setup-gate"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared component kit (window.OTBKit) — tabs, ledger, pager (task 2166). -->

package/modules/hall-ui/public/work.html

@@ -174,7 +174,7 @@
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
 <script src="/builders/craft-mode.js?v=2026-11-05-oversight"></script>
-<script src="/builders/shell.js?v=2026-11-05-oversight"></script>
+<script src="/builders/shell.js?v=2026-11-05-setup-gate"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- task 1004727: the ONE karma vote control every task/idea list renders -->

package/modules/hall-ui/records/setup-gate.md

@@ -0,0 +1,43 @@
+# The setup flow — one screen a new builder finishes once, and no setup banner on Home (task 1005076)
+
+The owner, 2026-11-05: Home's Welcome banner (the clone / `npx bongos setup` / download Claude steps) and the
+Getting started checklist below it stayed until a builder had shipped THREE tasks, so builders who were fully
+set up kept seeing a setup banner across the top of the hall. The decision: a new builder is held on a setup
+flow when they get in and goes through each step; once set up they are in for good, with no banner and no
+reminders.
+
+**What people see.** While `/me`'s `onboarding.setup.complete` is false, every hall page shows only
+`setup-gate.js`'s screen: "N of 4 done", the four steps in order, the current one open with what to do, a Sign
+out link. Each step ticks itself; the screen re-reads `/me` every 8 seconds and reloads into the hall the moment
+setup is complete.
+
+1. **Sign in** — always done by the time the screen can draw.
+2. **Get the project and Claude on your machine, and link it** — a CLI session exists (`npx bongos setup`).
+3. **Choose your role** — chosen on the screen itself, saved through `PATCH /me/disciplines`.
+4. **Run /builder-start in Claude** — the `first_start` stage, which `GET /tasks/claimable` now marks only for
+   a CLI session (the hall's own pages read that feed from the browser and used to tick it for everyone).
+
+**Who is never held.** Anyone graduated, anyone who has claimed a task, and any rank above xenos — every existing
+builder goes straight in. An older server that sends no `setup` holds nobody. The rule is
+`modules/onboarding/onboarding-state.js` `setupForApi`; the hall never re-derives it.
+
+**How it is wired.** `shell.js` `holdForSetup` loads `setup-gate.js` on demand (`loadHallScript`, the
+core-move-notice way), so a set-up builder never downloads it, and while it holds, neither the daily welcome
+(`welcome-boot.js`) nor the craft picker is asked. Both `applyAccess` callers pass `setup` (`shell.js`'s own
+`/me` probe and Home's `hall-render.js`). Its styles are `.setup-gate*` in `style.css`, on the hall tokens in
+both modes; the overlay sits one above `--z-modal`.
+
+**Removed.** The `welcome-scroll` and `onboarding-scroll` Home widgets, the "Show the setup guide again" link,
+and everything that drew them: `renderWelcomeCore` / `renderOnboarding` and their helpers in `hall-render.js`;
+`renderWelcome`, `reopenWelcomeFromNav`, `pickDiscipline`, the instance-repo loader and the checklist's /me poll
+in `builders.js`; the `.welcome*` / `.onboarding-item*` styles. The clone block (this project's own repository
+from `GET /instance`, never a hardcoded one) now lives on the setup screen's machine step, with Node and
+`npm install` named before `npx bongos setup`, as the welcome panel had them. The role step says "role", the
+word ADR 0174 fixed for that axis, through `OTB.roleAxisLabel` / `OTB.roleLabel`.
+
+**Loaded once.** `applyAccess` can run several times before the script lands; `holdForSetup` asks for it once
+(`setupGateLoading`), or two screens would stack.
+
+**Tests.** `tests/setup_flow.mjs` (the claimable guard run for a CLI and a web session, the screen drawn and
+driven, the shell loading it with nothing over it, Home with no banner), `tests/onboarding_state.mjs` (the
+rule), `tests/welcome_boot.mjs` (the shell's ask order). Each was mutation-checked against its half of the change.

package/modules/lifecycle/routes/tasks.js

@@ -237,8 +237,8 @@ module.exports = function buildTasksRouter() {
     // and forget — the response should never wait on or fail because of the
     // onboarding write. safeMarkStage swallows errors and handles the
     // graduation broadcast. Through the `onboarding` kernel port (BV1.R81 / ADR
-    // 0093 §1); ?. degrades to a no-op when the module is off.
-    seams.resolveOptional('onboarding')?.safeMarkStage(pool, req.builder.id, 'first_start', req.builder);
+    // 0093 §1); ?. degrades to a no-op when the module is off. CLI only (task 1005076: the hall reads this feed too).
+    if (req.gdsSession && req.gdsSession.source === 'cli') seams.resolveOptional('onboarding')?.safeMarkStage(pool, req.builder.id, 'first_start', req.builder);
     // `claimable_total` keeps the limit honest: the length of the sliced array, never a
     // second count query (ADR 0197).
     res.json({ claimable, claimable_total: feed.length, active_claims: active });

package/modules/onboarding/onboarding-state.js

@@ -79,23 +79,6 @@ const STAGES = [
 const GRADUATED = 'graduated';
 const ALL_STAGES = [...STAGES, GRADUATED];
 
-// The pre-auth, INFORMATIONAL step that sits AHEAD of auth_complete (task 470).
-// The state machine's first ENGINE stage is auth_complete, but the genuine
-// first action a newcomer takes is "obtain the repo" — clone it locally. That
-// step is manual/external
-// (there is no server event for it) and intentionally NOT a member of STAGES, so
-// it never gates graduation, never advances current_stage, and never appears in
-// shapeForApi's tracked checklist. It exists purely so the system's own model of
-// "the path into the city" begins where the path really begins. The hall renders
-// it as a static lead-in line on the displayed checklist; the auth_complete hint
-// above also surfaces the same clone instruction.
-const PRE_AUTH_STEP = {
-  id: 'obtain_repo',
-  label: 'Obtain the repo',
-  hint: 'Clone the project to thy machine and run npm install in it. The build commands live inside the repo, so this comes first.',
-  informational: true,
-};
-
 // How many shipped tasks the terminal 'ship_three' stage requires. Kept in
 // lockstep with db.THETES_GRADUATION_THRESHOLD (#692 / ADR 0034) so the
 // checklist's graduation coincides with the xenos→thetes promotion. Used only
@@ -124,7 +107,7 @@ const STAGE_LABELS = {
 // machine you'll build from — the /builder-* commands live INSIDE the repo, so
 // nothing (not even sign-in via the CLI) can happen before it exists. The
 // onboarding model never named that step, so the hint now points at it ahead of
-// the sign-in itself. See PRE_AUTH_STEP below for the standalone representation.
+// the sign-in itself. The setup flow's cli_setup step (task 1005076) carries it too.
 const STAGE_HINTS = {
   auth_complete:    'First obtain the repo — clone it — then sign in with npx bongos setup in that folder.',
   pick_disciplines: 'Pick the work that calls thee — engineer, artist, ideator, or any mix.',
@@ -189,6 +172,42 @@ const DISPLAY_HINTS = {
   ship_three:       'Carry three tasks through with /builder-ship — the third makes thee a Thetes.',
 };
 
+// ---- the setup flow (task 1005076) -------------------------------------------
+//
+// What a newcomer must finish before the hall opens to them (owner, 2026-11-05):
+// the hall holds them on one setup screen until every step below is cleared, and
+// after that they are in for good — no banner, no reminders. Each step ticks
+// itself from a signal the server already records:
+//
+//   signed_in        — they are reading /me, so always cleared.
+//   cli_setup        — a source='cli' session exists (ran `npx bongos setup`).
+//   pick_disciplines — the engine stage choosing a role marks (PATCH /me/disciplines).
+//   first_start      — the engine stage, which GET /tasks/claimable marks only for a
+//                      CLI session: proof /builder-start ran from Claude.
+//
+// Setup is also complete for anyone already past it: graduated, claimed a task
+// (first_claim cleared), or holding any rank above xenos. Existing builders go
+// straight in and are never held.
+const SETUP_STEPS = [
+  { id: 'signed_in',        label: 'Sign in', hint: 'Done — you are signed in.' },
+  { id: 'cli_setup',        label: 'Get the project and Claude on your machine, and link it', hint: 'Three things on your own computer. This ticks itself once your machine is linked.' },
+  { id: 'pick_disciplines', label: 'Choose your role', hint: 'Pick the work you want to do — engineer, artist, ideator, or any mix.' },
+  { id: 'first_start',      label: 'Run /builder-start in Claude', hint: 'Open the project in Claude and type /builder-start. This ticks itself the first time it runs, which proves everything works.' },
+];
+
+function setupForApi(state, { cliAuthed = false, rank = null } = {}) {
+  const completed = new Set((state && state.completed_stages) || []);
+  const current = (state && state.current_stage) || STAGES[0];
+  const cleared = (stage) => current === GRADUATED || completed.has(stage)
+    || (STAGES.indexOf(current) > STAGES.indexOf(stage) && STAGES.indexOf(stage) >= 0);
+  const steps = SETUP_STEPS.map((s) => ({
+    ...s,
+    cleared: s.id === 'signed_in' ? true : s.id === 'cli_setup' ? !!cliAuthed : cleared(s.id),
+  }));
+  const pastIt = current === GRADUATED || cleared('first_claim') || (!!rank && rank !== 'xenos');
+  return { complete: pastIt || steps.every((s) => s.cleared), steps };
+}
+
 // Pick the first uncompleted stage from STAGES (canonical order), or
 // GRADUATED if all six are done. Mirrors the migration 045 backfill CASE so
 // app-layer behaviour matches DB-layer reconstruction.
@@ -441,7 +460,9 @@ function stageDetail(stageId, shipCount) {
 //                      'join_discord' step (the OAuth flow sets the link).
 // opts.cliAuthed     — whether the builder has ever authenticated the GDS CLI
 //                      (db.hasCliSession). Clears the 'cli_setup' step.
-function shapeForApi(state, { shipCount = null, discordLinked = false, cliAuthed = false } = {}) {
+// opts.rank          — the builder's rank; any rank above xenos counts as set up
+//                      (the `setup` block, task 1005076).
+function shapeForApi(state, { shipCount = null, discordLinked = false, cliAuthed = false, rank = null } = {}) {
   const completed   = new Set((state && state.completed_stages) || []);
   const currentReal = (state && state.current_stage) || STAGES[0];
   const graduated   = currentReal === GRADUATED;
@@ -487,6 +508,7 @@ function shapeForApi(state, { shipCount = null, discordLinked = false, cliAuthed
     progress: { cleared: clearedCount, total: DISPLAY_STEPS.length },
     stages: display,
     graduated,
+    setup: setupForApi(state, { cliAuthed, rank }),
   };
 }
 
@@ -494,7 +516,6 @@ module.exports = {
   STAGES,
   GRADUATED,
   ALL_STAGES,
-  PRE_AUTH_STEP,
   STAGE_HINTS,
   DISPLAY_LABELS,
   isKnownStage,

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.41",
+  "version": "1.24.42",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.24.41",
+      "version": "1.24.42",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.41",
+  "version": "1.24.42",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -11209,5 +11209,11 @@
       "id": "1005049",
       "text": "Watch is now the one oversight page. Sessions and Autobongos moved off the sidebar and became two tabs on Watch, next to People, Operations and Security. Old links to /sessions and /gate open the right tab. Who can see and pre"
     }
+  ],
+  "1.24.42": [
+    {
+      "id": "1005076",
+      "text": "New builders now get one clear setup screen they finish once, and everyone already set up no longer sees a setup banner across the top of Home."
+    }
   ]
 }

package/src/bongos/routes/me.js

@@ -535,7 +535,7 @@ module.exports = function buildMeRouter() {
       // returns a stage-1 "nothing cleared" view so the client renders the
       // checklist either way. Through the `onboarding` port (BV1.R81); null when
       // the module is off.
-      onboarding: onboarding ? onboarding.shapeForApi(onboardingRow, { shipCount, discordLinked: !!discordLink, cliAuthed: !!cliAuthed }) : null,
+      onboarding: onboarding ? onboarding.shapeForApi(onboardingRow, { shipCount, discordLinked: !!discordLink, cliAuthed: !!cliAuthed, rank: req.builder.rank }) : null,
       // F7 (ADR 0033): Discord link state for the hall's Connect/Unlink UI.
       // `configured` tells the client whether the server even has Discord OAuth
       // creds — when false the hall renders nothing (the start route 503s).
@@ -714,7 +714,7 @@ module.exports = function buildMeRouter() {
         discordIsLinked(req.builder.id),
         db.hasCliSession(req.builder.id),
       ]);
-      const onboarding = onboardingPort ? onboardingPort.shapeForApi(state, { shipCount, discordLinked: !!discordLink, cliAuthed: !!cliAuthed }) : null;
+      const onboarding = onboardingPort ? onboardingPort.shapeForApi(state, { shipCount, discordLinked: !!discordLink, cliAuthed: !!cliAuthed, rank: req.builder.rank }) : null;
       res.json({ builder, onboarding });
     } catch (err) {
       if (err.code === 'invalid_discipline' || err.code === 'invalid_main_discipline') {

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.41'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.42'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/hall_board_world.mjs

@@ -350,7 +350,7 @@ function bootHallRender({ me, progress = null, leaderboard = [], ctxExtra = {} }
     curLabel: (caps) => (caps ? 'Credits' : 'credits'), emptyRow: () => '', fmtDate: (d) => String(d).slice(0, 10),
     mins: (m) => `${m}m`, normalizeRank: (r) => String(r || '').toLowerCase(), pct: (n) => `${n}%`, postJSON: async () => ({}),
     rankLabel: (r) => r, rankWeight: () => 0, signClasses: () => '', toast() {}, usd: (n) => `$${n}`,
-    instanceRepo: null, newcomerGated: false,
+    newcomerGated: false,
     get lastMeState() { return me; }, get lastCostState() { return me.cost || null; }, get lastKarmaState() { return me.karma || null; },
     get lastNeedsState() { return me.needs || null; }, get lastRebaseState() { return me.needs_rebase_tasks || null; },
     get lastProgressState() { return progress; },

package/tests/hall_landing_boot.mjs

@@ -92,15 +92,14 @@ async function boot({ meStatus, settle = false }) {
     },
     OTBHallRender: () => ({
       analyticsState: {}, lbState: {},
-      shipsPager: { page: 1 }, welcomeDismissalKey: () => 'k',
+      shipsPager: { page: 1 },
       // task 1004854: Home asks for this many ships; the ledger's full read lives in hall-render.js.
       HOME_SHIPS_LIMIT: 5, setRecentShips: spy('setRecentShips'), populateShipVersionFilter: spy('populateShipVersionFilter'),
       mountHallWidgets: spy('mountHallWidgets'),
       renderLanding: spy('renderLanding'),
       renderCurveBody: spy('renderCurveBody'), renderGreeting: spy('renderGreeting'),
-      renderNav: spy('renderNav'), renderOnboarding: spy('renderOnboarding'),
+      renderNav: spy('renderNav'),
       renderProfile: spy('renderProfile'), renderRecentShips: spy('renderRecentShips'),
-      renderWelcomeCore: spy('renderWelcomeCore'),
       // task 1003459 — wireEvents() calls this unconditionally now (the Home
       // Next-up Claim button), so an incomplete stub throws mid-wire.
       wireNextUpClaim: spy('wireNextUpClaim'),