@bongos/core 1.24.41 → 1.24.42

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

@@ -287,17 +287,11 @@
       // task 1004713: the government positions this builder holds, server-resolved —
       // passed here too, or the index would keep the governing tabs for a seatless builder.
       positions: (ctx.lastMeState && ctx.lastMeState.positions) || null,
+      // task 1005076: incomplete setup holds the hall behind setup-gate.js.
+      setup: (onboarding && onboarding.setup) || null,
       builder,
     });
 
-    // Re-open affordance: pre-graduation, when the welcome banner is dismissed
-    // (hidden), a small link brings it back (reopenWelcomeFromNav).
-    const reopen = document.getElementById('welcome-reopen');
-    if (reopen) {
-      const welcomeEl = document.getElementById('welcome-scroll');
-      reopen.hidden = !(welcomeEl && welcomeEl.hidden && !graduated);
-    }
-
     // Standing section rail: one link per group with a visible member.
     const rail = document.getElementById('standing-rail');
     if (rail) {
@@ -755,245 +749,6 @@
       h1.textContent = `${greetingWord(new Date().getHours())}, ${builder.display_name || builder.github_login || 'builder'}`;
     }
   }
-  const ONBOARDING_STAGE_ORDER = [
-    'auth_complete',
-    'pick_disciplines',
-    'first_start',
-    'first_claim',
-    'ship_three',
-    'graduated',
-  ];
-
-  function stageIndex(stageId) {
-    const i = ONBOARDING_STAGE_ORDER.indexOf(stageId);
-    return i === -1 ? 0 : i;
-  }
-  function welcomeDismissalKey(builderId) {
-    return `builders:welcome-dismissed:${builderId}`;
-  }
-  function readDismissedStageIndex(builderId) {
-    try {
-      const raw = window.localStorage.getItem(welcomeDismissalKey(builderId));
-      if (raw === null) return null;
-      const n = Number(raw);
-      return Number.isInteger(n) ? n : null;
-    } catch (_) {
-      // localStorage can throw in private-browsing modes. Treat as "never
-      // dismissed" — the panel renders, which is the right fail-open
-      // behaviour for an onboarding affordance.
-      return null;
-    }
-  }
-  function renderWelcomeCore(builder, onboarding) {
-    const scroll = $('#welcome-scroll');
-    const body = $('#welcome-body');
-    if (!scroll || !body) return;
-
-    // No builder yet (unauth landing) → hide and exit.
-    if (!builder || !builder.id) { scroll.hidden = true; return; }
-
-    // Graduated → hide entirely. The checklist below will also hide itself.
-    if (onboarding && onboarding.graduated) { scroll.hidden = true; return; }
-
-    // Compute current stage index. When the /me payload didn't carry an
-    // onboarding object (legacy), default to the first stage so the panel
-    // still greets the builder rather than vanishing silently.
-    const currentStageId = (onboarding && onboarding.current_stage) || ONBOARDING_STAGE_ORDER[0];
-    const currentIdx = stageIndex(currentStageId);
-
-    // Dismissal check. Reappears on stage regression (currentIdx < dismissed).
-    const dismissedAt = readDismissedStageIndex(builder.id);
-    if (dismissedAt !== null && currentIdx >= dismissedAt) {
-      scroll.hidden = true;
-      return;
-    }
-
-    const rankBadge = renderRankBadge(normalizeRank(builder.rank), { tip: true });
-    const greeting = `Welcome, ${escapeHtml(builder.display_name || builder.github_login || 'builder')}.`;
-
-    // #777: the welcome panel shows ONLY setup — the steps that get a newcomer
-    // from "signed into the hall" to a working `claude` session on their own
-    // machine. The "what to do next" arc lives in the Path checklist below — not
-    // here.
-    // The #support pointer assumes the Discord module; drop it when discord is off.
-    const supportFoot = moduleOn('discord')
-      ? `Stuck on any step? <a href="${API}/auth/discord/start">Join our Discord</a> and ask in <strong>#support</strong>.`
-      : `Stuck on any step? See the project's README and docs.`;
-    const setupSteps = `
-        <p class="setup__intro">Build from your own machine — get a copy of the project, sign in once, then work in Claude.</p>
-        <ol class="setup__steps">
-          <li><strong>Clone the repository</strong> and install dependencies (<code>npm install</code>).</li>
-          <li><strong>Run <code>npx bongos setup</code></strong> in that folder to sign this machine in.</li>
-          <li><strong><a href="https://claude.com/download" target="_blank" rel="noopener noreferrer">Download Claude</a></strong> (or use the Claude Code CLI), open the project, and run <code>/builder-start</code> to claim your first task.</li>
-        </ol>
-    `;
-    // task 469: a "Set up your machine / get the code" door. The steps above
-    // get you a session running; this section answers the separate
-    // question a first-timer always has — "where does the code come from, and
-    // how do I get it onto my own laptop?". It's the hall mirror of the primer's
-    // "Step 0 — get the project onto your machine". Collapsed by default so it
-    // doesn't crowd the recommended path; the clone block is click-to-copy
-    // (copy-on-click.js picks up .welcome__paste). Sign-in is `npx bongos setup`
-    // (bin/bongos.js → scripts/bongos/setup.js), one line on every OS — bare
-    // `bongos` is not on a fresh clone's PATH, `npx` finds the repo's own bin.
-    // The clone commands come from the instance's own repo coords (loaded from
-    // GET /api/bongos/instance), not a hardcoded repo, so a fresh instance's newcomer
-    // clones ITS project (ADR 0062 §3, task 1705). Falls back to generic guidance
-    // until the coords load (or if they're unavailable).
-    const cloneBlock = ctx.instanceRepo
-      ? `git clone ${escapeHtml(ctx.instanceRepo.url)}.git\ncd ${escapeHtml(ctx.instanceRepo.repo)}\nnpm install\nnpx bongos setup`
-      : `# clone your instance's repository, cd into it, then run:\nnpm install\nnpx bongos setup`;
-    const getCode = `
-        <details class="setup__getcode">
-          <summary class="setup__getcode-summary">Set up your machine / get the code</summary>
-          <div class="setup__getcode-body">
-            <p class="setup__hint">First install <a href="https://git-scm.com/downloads" target="_blank" rel="noopener noreferrer">Git</a>,
-              <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">Node</a> (version 22 or newer)
-              and <a href="https://claude.com/download" target="_blank" rel="noopener noreferrer">Claude Code</a> — that's all the tooling you need up front.</p>
-            <p class="setup__getcode-lede">Then copy the project onto your machine, install its dependencies, and sign in:</p>
-            <code class="welcome__paste">${cloneBlock}</code>
-            <p class="setup__hint">The same commands work on Mac, Windows and Linux. New to the steps? The
-              <a href="/primer">primer</a> walks the whole path in plain language.</p>
-          </div>
-        </details>`;
-    body.innerHTML = `
-      <div class="welcome__lede">${greeting} Your standing is ${rankBadge}.</div>
-      <div class="setup">
-        ${setupSteps}
-        ${getCode}
-        <p class="setup__foot">${supportFoot}</p>
-      </div>
-    `;
-    // Remember the stage we rendered for, so the dismiss handler can record it.
-    scroll.dataset.stageIdx = String(currentIdx);
-    scroll.hidden = false;
-  }
-  function renderOnboarding(onboarding, discord) {
-    const scroll = $('#onboarding-scroll');
-    const list = $('#onboarding-list');
-    if (!scroll || !list) return;
-    if (!onboarding) {
-      scroll.hidden = true;
-      return;
-    }
-    // Hide the panel once the builder has graduated — no point lingering.
-    if (onboarding.graduated) {
-      scroll.hidden = true;
-      return;
-    }
-    // task 2169 (banner budget: one at a time): while the welcome panel is
-    // showing, the checklist waits its turn — it appears when the welcome is
-    // dismissed or outgrown. renderWelcome runs first in the same loadAll pass
-    // (and every SSE nudge re-runs both), so this stays current.
-    const welcomeEl = document.getElementById('welcome-scroll');
-    if (welcomeEl && !welcomeEl.hidden) {
-      scroll.hidden = true;
-      return;
-    }
-    scroll.hidden = false;
-
-    const discordConfigured = !!(discord && discord.configured);
-    const stages = Array.isArray(onboarding.stages) ? onboarding.stages : [];
-    if (stages.length === 0) {
-      list.innerHTML = `<li class="onboarding-item onboarding-item--placeholder">No onboarding steps recorded yet.</li>`;
-      return;
-    }
-
-    // task 470: a static, INFORMATIONAL lead-in step that sits AHEAD of the
-    // data-driven steps — the genuine first action into the city is "obtain the
-    // repo" (clone it onto your machine).
-    // It mirrors onboarding-state.js PRE_AUTH_STEP. It is NOT one of the tracked
-    // checklist steps (it carries no engine stage, never gates graduation, and
-    // isn't counted in the "N of M steps cleared" status line) — it just makes
-    // the checklist a newcomer sees acknowledge the very first real action,
-    // which the auto-ticking steps below silently assumed already happened.
-    const preAuthLead = `
-      <li class="onboarding-item onboarding-item--informational" data-stage="obtain_repo">
-        <span class="onboarding-item__mark" aria-hidden="true">›</span>
-        <div class="onboarding-item__body">
-          <p class="onboarding-item__label">First — obtain the repo</p>
-          <p class="onboarding-item__hint">Clone the project to your machine and run <code>npm install</code> in it. The build commands live inside the repo, so this comes first. The remaining steps below are tracked automatically.</p>
-        </div>
-      </li>`;
-
-    list.innerHTML = preAuthLead + stages.map((s) => {
-      const status = s.cleared ? 'cleared' : (s.is_current ? 'current' : 'locked');
-      const mark = s.cleared ? '✓' : (s.is_current ? '◆' : '○');
-      const hint = s.hint ? `<p class="onboarding-item__hint">${escapeHtml(s.hint)}</p>` : '';
-      // #766: the terminal 'ship_three' stage carries a live "N of 3" counter
-      // in its `detail` field — render it as a small progress line so the
-      // builder watches themselves climb toward Thetes with each ship.
-      const detail = s.detail
-        ? `<p class="onboarding-item__detail">${escapeHtml(s.detail)}</p>`
-        : '';
-      // Per-step affordance, shown ONLY while the step is the current, uncleared
-      // one — every step now behaves uniformly (Lars, #833): locked/future steps
-      // and cleared steps carry no control, so the path reads as one action at a
-      // time. (The Discord step already did this; the craft picker and the
-      // See-the-works link used to render on locked/cleared steps too.) Every
-      // step auto-detects its own completion server-side (#777): join_discord
-      // clears on the Discord link, cli_setup once the Bongos CLI is authenticated,
-      // ship_three at the third ship — no manual ticking.
-      let action = '';
-      if (s.is_current && !s.cleared) {
-        if (s.id === 'pick_disciplines') {
-          // V3 (2026-05-30): inline discipline picker → PATCH /me/disciplines.
-          // Multi-select: each button is a toggle reflecting the saved prefs, so
-          // a builder can pick engineer, artist, ideator, or any mix while the
-          // step is current. (Settings can revise crafts later for graduated citizens.)
-          const prefs = (ctx.lastMeState && ctx.lastMeState.builder && Array.isArray(ctx.lastMeState.builder.preferred_disciplines))
-            ? ctx.lastMeState.builder.preferred_disciplines : [];
-          const discBtn = (value, label) => {
-            const on = prefs.includes(value);
-            return `<button type="button" class="btn-ghost onboarding-item__disc${on ? ' onboarding-item__disc--on' : ''}" data-disc="${escapeHtml(value)}" aria-pressed="${on}">${escapeHtml(label)}</button>`;
-          };
-          // The offered crafts come from the server (task 1003487): window.__MODULES__
-          // .disciplines IS enabledDisciplines(), the same list the PATCH validates
-          // against, so this can never render a button the API would reject. Was a
-          // hardcoded triple with a moduleOn('art-pipeline') branch for 'artist', so
-          // a module-contributed craft (ui-design → ui) never appeared here at all.
-          action = `
-            <div class="onboarding-item__action onboarding-item__disc-pick">
-              ${OTB.disciplines().map((d) => discBtn(d, OTB.roleLabel(d))).join('')}
-            </div>`;
-        } else if (s.id === 'ship_three') {
-          action = `
-            <div class="onboarding-item__action">
-              <a class="btn-ghost" href="/work">See the work board →</a>
-            </div>`;
-        } else if (s.id === 'join_discord' && discordConfigured) {
-          // #777: the Connect button runs the existing OAuth flow (GET
-          // /auth/discord/start → auto-join + rank role). Full-page nav so the
-          // server can set the CSRF state cookie before redirecting to Discord.
-          // The step then clears itself once the link lands (discord.linked) —
-          // no manual mark. Same control as /builders/settings.
-          action = `
-            <div class="onboarding-item__action">
-              <a class="btn-ghost onboarding-item__discord" href="${API}/auth/discord/start">Connect Discord &amp; join the server</a>
-            </div>`;
-        }
-      }
-      return `
-        <li class="onboarding-item onboarding-item--${status}" data-stage="${escapeHtml(s.id)}">
-          <span class="onboarding-item__mark" aria-hidden="true">${mark}</span>
-          <div class="onboarding-item__body">
-            <p class="onboarding-item__label">${escapeHtml(s.label)}</p>
-            ${hint}
-            ${detail}
-          </div>
-          ${action}
-        </li>
-      `;
-    }).join('');
-
-    const cleared = onboarding.progress?.cleared ?? 0;
-    const total = onboarding.progress?.total ?? stages.length;
-    const status = $('#onboarding-status');
-    if (status) {
-      status.hidden = false;
-      status.textContent = `${cleared} of ${total} steps cleared.`;
-    }
-  }
   // task 1004854: Home shows the newest few ships and a count, so loadAll (on
   // every load AND every live refresh) asks for HOME_SHIPS_LIMIT rows plus the
   // server's `total`. Only the Accomplishments ledger — its window/version
@@ -1365,6 +1120,6 @@
   }
 
 
-    return { acclaimEvidenceHtml, analyticsState, lbState, mountHallWidgets, renderCurveBody, renderGreeting, renderLanding, renderSessionRefused, renderNav, renderOnboarding, renderProfile, renderRecentShips, renderWelcomeCore, HOME_SHIPS_LIMIT, loadShipLedger, populateShipVersionFilter, setRecentShips, shipState, shipsPager, welcomeDismissalKey };
+    return { acclaimEvidenceHtml, analyticsState, lbState, mountHallWidgets, renderCurveBody, renderGreeting, renderLanding, renderSessionRefused, renderNav, renderProfile, renderRecentShips, HOME_SHIPS_LIMIT, loadShipLedger, populateShipVersionFilter, setRecentShips, shipState, shipsPager };
   };
 })();

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

@@ -48,20 +48,9 @@
 
   /* ---------------- Home ---------------- */
 
-  // 0. First-visit welcome banner — V3.R77 (#296). Pre-graduation only; dismissable.
-  w('welcome-scroll', 'Welcome', 0,
-    '<button type="button" class="welcome__minimize" id="welcome-minimize" aria-label="Minimize the welcome panel" title="Minimize">−</button>' +
-    '<h2 id="welcome-h" class="scroll__h">Welcome</h2>' +
-    '<div class="welcome" id="welcome-body"><div class="hall-loading" role="status">Loading…</div></div>',
-    { view: 'home', zone: 'home-banner', welcomeChip: true, sectionClass: 'scroll scroll--welcome', labelledby: 'welcome-h', hiddenByDefault: true });
-
-  // 0b. Onboarding checklist — V3.R75 (#294).
-  w('onboarding-scroll', 'Getting started', 10,
-    '<h2 id="onboarding-h" class="scroll__h">Getting started</h2>' +
-    '<p class="scroll__lede">A short path to finding your feet. Tick the steps you’ve done; the rest are tracked for you.</p>' +
-    '<ol class="onboarding-list" id="onboarding-list"><li class="hall-loading" role="status">Loading…</li></ol>' +
-    '<p class="ledger__note" id="onboarding-status" hidden></p>',
-    { view: 'home', zone: 'home-banner', labelledby: 'onboarding-h', hiddenByDefault: true });
+  // (task 1005076: the Welcome setup banner and the Getting started checklist left Home.
+  //  Setup is a screen of its own that a new builder finishes once — setup-gate.js — and
+  //  a set-up builder is never shown a setup banner again; owner, 2026-11-05.)
 
   // (task 1005054: the quick-stats strip and the version tab left Home. The
   //  zone they held, home-stats, is the project city's — home-city.js.)

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

@@ -53,7 +53,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>
 <!-- task-detail.js still owns the #/idea/N and #/blocker/N overlay, so a ref
      written inside an idea's own prose keeps resolving from this page. -->

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

@@ -228,7 +228,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>
 <!-- task 1004727: the ONE karma vote control every task/idea list renders -->
 <script src="/builders/vote-control.js"></script>

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

@@ -74,10 +74,9 @@
           <!-- task 1005043: Home's loader, shown until a card mounts into a zone. -->
           <p class="hall-loading hall-loading--page hall-loading--zones" role="status">Loading…</p>
           <div class="view-zone" id="zone-home-banner">
-            <!-- Landing card for signed-out visitors (builders.js renderLanding)
-                 + the re-open affordance for a dismissed welcome banner. -->
+            <!-- Landing card for signed-out visitors (builders.js renderLanding).
+                 No setup banner: setup is a screen of its own (setup-gate.js, task 1005076). -->
             <div id="landing-root" hidden></div>
-            <p id="welcome-reopen" hidden><a href="#home" class="pill-link">Show the setup guide again</a></p>
           </div>
           <div class="view-zone" id="zone-home-stats"></div>
           <div class="view-zone view-zone--band" id="zone-home-band"></div>
@@ -123,7 +122,7 @@
 <script src="/builders/welcome-boot.js?v=2026-10-23-city1" defer></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab" defer></script>
 <script src="/builders/craft-mode.js?v=2026-11-05-oversight" defer></script>
-<script src="/builders/shell.js?v=2026-11-05-oversight" defer></script>
+<script src="/builders/shell.js?v=2026-11-05-setup-gate" defer></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 2166: the shared component kit (window.OTBKit) — pager/ledger/rail.

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

@@ -74,7 +74,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/hall-kit.js"></script>
 <script src="/builders/market-watch-lib.js"></script>

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

@@ -43,7 +43,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>
 <script src="/builders/hall-kit.js"></script>

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

@@ -188,7 +188,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/hall-kit.js"></script>
 <script src="/builders/market-watch-lib.js"></script>

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

@@ -128,7 +128,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>
 <script src="/builders/brand-apply.js"></script>

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

@@ -82,7 +82,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>
 <script src="/builders/hall-kit.js"></script>

package/modules/hall-ui/public/my-agents.html

@@ -84,7 +84,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>
 <script src="/builders/gov-living.js?v=2026-10-10-real1"></script>

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

@@ -113,7 +113,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>
 <!-- the shared markdown reader (window.OTBMdReader) — primer.js renders through

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

@@ -208,7 +208,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/public/project-settings.html

@@ -77,7 +77,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>
 <script src="/builders/hall-kit.js"></script>

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

@@ -44,7 +44,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>
 <!-- The chart kit and the timeline's series builders (task 1003447). Both MUST

package/modules/hall-ui/public/roster.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>
 <!-- the branding pack's currency label, loaded BEFORE roster.js. -->

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

@@ -394,7 +394,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) — section rail (task 2166). -->

package/modules/hall-ui/public/setup-gate.js

@@ -0,0 +1,156 @@
+// modules/hall-ui/public/setup-gate.js — the setup flow a new builder finishes once (task 1005076).
+//
+// THE SERVER DECIDES, THIS ONLY DRAWS. GET /me carries `onboarding.setup`
+// ({ complete, steps[] }, modules/onboarding/onboarding-state.js setupForApi). While
+// `complete` is false the hall is held behind this one screen on every page: the steps
+// in order, each ticking itself from a signal the server records (a linked machine, a
+// chosen role, /builder-start run from Claude). Once complete the builder is in for
+// good: the screen never draws again, and Home carries no setup banner (owner,
+// 2026-11-05: "once they're in, they're in").
+//
+// Its own file, loaded by shell.js only when setup is not complete (the core-move-notice.js
+// way): shell.js sits at the 1500-line ratchet, and a set-up builder never pays for it.
+// The role step saves through PATCH /me/disciplines, the route Settings' preferred roles use.
+
+(function () {
+  'use strict';
+
+  var POLL_MS = 8000;
+  var el = null, timer = null, api = null, state = null, picked = [], repo = null;
+
+  function esc(s) { return window.OTB.escapeHtml(s); }
+
+  var CHECK = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12.5l4.5 4.5L19 7.5" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/></svg>';
+
+  function stepDetail(step) {
+    if (step.id === 'cli_setup') {
+      // This project's own repository (GET /instance), never a hardcoded one (ADR 0062 §3).
+      var getCode = repo
+        ? '<pre class="setup-gate__code">git clone ' + esc(repo.url) + '.git\ncd ' + esc(repo.repo) + '\nnpm install\nnpx bongos setup</pre>'
+        : '';
+      return '<ol class="setup-gate__how">' +
+        '<li>Install <a href="https://nodejs.org" target="_blank" rel="noopener">Node</a> (version 22 or newer) and ' +
+          '<a href="https://claude.com/download" target="_blank" rel="noopener">Claude</a> (the desktop app, or Claude Code in a terminal).</li>' +
+        '<li>Clone the project to your machine and run <code>npm install</code> in it.' + (repo ? '' : ' The project’s README says where it lives.') + '</li>' +
+        '<li>In the project folder, run <code>npx bongos setup</code> and sign in when it asks.</li>' +
+        '</ol>' + getCode;
+    }
+    if (step.id === 'pick_disciplines') {
+      var crafts = window.OTB.disciplines();
+      return '<div class="setup-gate__crafts" role="group" aria-label="' + esc(window.OTB.roleAxisLabel()) + '">' +
+        crafts.map(function (c) {
+          var on = picked.indexOf(c) !== -1;
+          return '<button type="button" class="setup-gate__craft" data-craft="' + esc(c) + '" aria-pressed="' + on + '">' + esc(window.OTB.roleLabel(c)) + '</button>';
+        }).join('') +
+        '</div>' +
+        '<button type="button" class="setup-gate__save" data-save-crafts' + (picked.length ? '' : ' disabled') + '>Save my role</button>' +
+        '<p class="setup-gate__err" data-craft-err hidden></p>';
+    }
+    if (step.id === 'first_start') {
+      return '<p class="setup-gate__hint">In Claude, open the project folder and type <code>/builder-start</code>.</p>';
+    }
+    return '';
+  }
+
+  function render() {
+    if (!el || !state) return;
+    var steps = state.steps || [];
+    var current = steps.filter(function (s) { return !s.cleared; })[0] || null;
+    var done = steps.filter(function (s) { return s.cleared; }).length;
+    el.querySelector('.setup-gate__count').textContent = done + ' of ' + steps.length + ' done';
+    el.querySelector('.setup-gate__steps').innerHTML = steps.map(function (s, i) {
+      var isCurrent = current && s.id === current.id;
+      var cls = 'setup-gate__step' + (s.cleared ? ' is-done' : '') + (isCurrent ? ' is-current' : '');
+      return '<li class="' + cls + '"' + (isCurrent ? ' aria-current="step"' : '') + '>' +
+        '<span class="setup-gate__mark">' + (s.cleared ? CHECK : String(i + 1)) + '</span>' +
+        '<div class="setup-gate__body">' +
+          '<h3 class="setup-gate__label">' + esc(s.label) + '</h3>' +
+          (isCurrent ? '<p class="setup-gate__hint">' + esc(s.hint) + '</p>' + stepDetail(s) : '') +
+        '</div></li>';
+    }).join('');
+  }
+
+  function check() {
+    return api.request('GET', '/api/bongos/me').then(function (res) {
+      var setup = res && res.ok && res.data && res.data.onboarding && res.data.onboarding.setup;
+      if (!setup) return;
+      if (setup.complete) { finish(); return; }
+      state = setup;
+      if (!el.contains(document.activeElement) || !document.activeElement.closest('.setup-gate__step.is-current')) render();
+    }, function () { /* offline a moment: keep the screen, try again */ });
+  }
+
+  function saveCrafts(btn) {
+    var err = el.querySelector('[data-craft-err]');
+    btn.disabled = true;
+    api.request('PATCH', '/api/bongos/me/disciplines', { body: { preferred_disciplines: picked.slice() } }).then(function (res) {
+      if (res && res.ok) { check(); return; }
+      btn.disabled = false;
+      if (err) { err.textContent = 'That did not save. Try again.'; err.hidden = false; }
+    }, function () {
+      btn.disabled = false;
+      if (err) { err.textContent = 'That did not save. Check your connection and try again.'; err.hidden = false; }
+    });
+  }
+
+  function onClick(e) {
+    var craft = e.target.closest('[data-craft]');
+    if (craft) {
+      var id = craft.getAttribute('data-craft');
+      var at = picked.indexOf(id);
+      if (at === -1) picked.push(id); else picked.splice(at, 1);
+      craft.setAttribute('aria-pressed', String(at === -1));
+      var save = el.querySelector('[data-save-crafts]');
+      if (save) save.disabled = !picked.length;
+      return;
+    }
+    var save2 = e.target.closest('[data-save-crafts]');
+    if (save2) saveCrafts(save2);
+  }
+
+  function finish() {
+    if (timer) { clearInterval(timer); timer = null; }
+    if (el) el.remove();
+    el = null;
+    document.documentElement.classList.remove('setup-gate-open');
+    window.location.reload();
+  }
+
+  /** Hold the hall behind the setup screen. `setup` is /me's onboarding.setup; `opts.api` the shell's client. */
+  function show(setup, opts) {
+    if (!setup || setup.complete) return;
+    api = opts && opts.api;
+    state = setup;
+    if (el) { render(); return; }
+    var name = opts && opts.builder && (opts.builder.display_name || opts.builder.github_login);
+    el = document.createElement('div');
+    el.className = 'setup-gate';
+    el.id = 'setup-gate';
+    el.setAttribute('role', 'dialog');
+    el.setAttribute('aria-modal', 'true');
+    el.setAttribute('aria-labelledby', 'setup-gate-h');
+    el.innerHTML =
+      '<div class="setup-gate__panel">' +
+        '<p class="setup-gate__count" aria-live="polite"></p>' +
+        '<h2 class="setup-gate__title" id="setup-gate-h">' + (name ? 'Welcome, ' + esc(name) + '. ' : '') + 'Let’s get you set up</h2>' +
+        '<p class="setup-gate__lede">Finish these steps once and you’re in. Each one ticks itself as you go.</p>' +
+        '<ol class="setup-gate__steps"></ol>' +
+        '<p class="setup-gate__foot"><a href="/api/bongos/auth/logout" id="setup-gate-signout">Sign out</a></p>' +
+      '</div>';
+    el.addEventListener('click', onClick);
+    document.body.appendChild(el);
+    document.documentElement.classList.add('setup-gate-open');
+    render();
+    var h = document.getElementById('setup-gate-h');
+    if (h) { h.setAttribute('tabindex', '-1'); h.focus(); }
+    if (api) {
+      timer = setInterval(check, POLL_MS);
+      api.request('GET', '/api/bongos/instance').then(function (res) {
+        var r = res && res.ok && res.data && res.data.repo;
+        if (r && !r.error && r.url) { repo = r; render(); }
+      }, function () { /* no repo coords: the README line stands in */ });
+    }
+  }
+
+  window.OTBSetupGate = { show: show };
+})();