@bongos/core 1.19.538 → 1.19.540

package/docs/module-api-changelog.md

@@ -1525,5 +1525,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.536 with no explicit bump. run 33888812605. (task 1002620)
   1.19.538 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.537 with no explicit bump. run 33890191596. (task 1002620)
+  1.19.539 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.538 with no explicit bump. run 33892948885. (task 1002620)
+  1.19.540 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.539 with no explicit bump. run 33895602533. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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

@@ -1,12 +1,15 @@
 // modules/hall-ui/public/hall-kit.js — the hall's shared UI component kit
 // (task 2166, the hall UX-coherence program's foundation).
 //
-// One dependency-free IIFE exposing `window.OTBKit`: the SIX primitives every
-// page redesign (tasks 2169–2176) adopts instead of re-implementing — pager,
-// ledger, filter bar, tabs, section rail, empty/skeleton/collapsible. Before
-// this file, the ledger+pager block existed in ~10 drifted copies across
-// work.js / goals-page.js / builders.js; the section rail existed twice with
-// different mechanics (Standing scrollspy vs Settings panel-switch).
+// One dependency-free IIFE exposing `window.OTBKit`: the SIX layout primitives
+// every page redesign (tasks 2169–2176) adopts instead of re-implementing —
+// pager, ledger, filter bar, tabs, section rail, empty/skeleton/collapsible —
+// plus, since task 1003445, the hall's CHART families: a horizontal bar series
+// and a sparkline, the plotted time-axis charts, and (task 1003572) the
+// year-grid contribution calendar. Before this file, the ledger+pager block
+// existed in ~10 drifted copies across work.js / goals-page.js / builders.js;
+// the section rail existed twice with different mechanics (Standing scrollspy vs
+// Settings panel-switch), and the same bar series was hand-drawn three times.
 //
 // Contract:
 // - Dependency-free like shell.js (own esc(), no window.OTB use) so load order
@@ -1030,6 +1033,100 @@
       + '</div>';
   }
 
+  // calendarGridHtml(days, opts) — a year of ship-days as a contribution calendar:
+  // one cell per calendar day, BANDED by count rather than scaled, its reading a
+  // per-cell title (plus an aria summary on the whole grid), not a crosshair. The
+  // hall's THIRD chart family (task 1003572, criterion legibility-series-are-drawn):
+  // OTBKit's other two shapes are a horizontal bar series and a plot on a time axis;
+  // a 2-D year grid is neither, so it earns its own primitive rather than a hand-roll
+  // at the page (modules/hall-ui/CLAUDE.md; tests/hall_audit.mjs section 6b).
+  //
+  // THE READING, decided and written down (the task asked which): a NON-picture reader
+  // gets the exact figure two ways — each cell carries a `title` ("2026-09-03 · 3
+  // ships" / "… · no ships"), and the grid carries an aria-label summarising the
+  // window (active days + total ships). No table twin: unlike a line, a calendar's
+  // value IS its position, so a per-cell title reads the same fact the picture shows,
+  // and a 366-row table beneath would be longer than the thing it explains.
+  //
+  // `days`: [{ local_date:'YYYY-MM-DD', count }] — SPARSE (only days that had ships),
+  // already resolved in the BUILDER's timezone server-side (GET /me). Empty → '' so
+  // the caller renders its own empty state, never an empty grid.
+  //
+  // THE TIMEZONE TRAP the task names: local_date is already the builder's own day, so
+  // the grid is built by ORDINAL arithmetic on the 'YYYY-MM-DD' parts (Date.UTC on the
+  // parsed integers, floored to an epoch day) — never `new Date('2026-09-03')`, which
+  // is UTC-midnight and would shift a cell a day west of Greenwich. Same epoch-day
+  // floor cumulateByDay uses, so no cell moves relative to the other charts.
+  function calendarGridHtml(days, opts = {}) {
+    const list = (days || []).filter((d) => d && typeof d.local_date === 'string');
+    const ymdToOrd = (ymd) => {
+      const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(ymd);
+      if (!m) return null;
+      return Math.floor(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])) / 86400000);
+    };
+    const ordToYmd = (ord) => {
+      const dt = new Date(ord * 86400000);
+      return `${dt.getUTCFullYear()}-${String(dt.getUTCMonth() + 1).padStart(2, '0')}-${String(dt.getUTCDate()).padStart(2, '0')}`;
+    };
+    const counts = new Map();
+    let maxOrd = null;
+    let activeDays = 0;
+    let totalShips = 0;
+    for (const d of list) {
+      const o = ymdToOrd(d.local_date);
+      if (o == null) continue;
+      const c = Math.max(0, Math.round(Number(d.count) || 0));
+      if (c <= 0) continue;
+      counts.set(o, (counts.get(o) || 0) + c);
+      if (maxOrd == null || o > maxOrd) maxOrd = o;
+    }
+    if (maxOrd == null) return ''; // nothing real to draw → caller's empty state
+    for (const [, c] of counts) { activeDays += 1; totalShips += c; }
+
+    // The grid ENDS at `today` (the builder's, when given) so a quiet recent week still
+    // reads as time that passed, not a truncated chart; falls back to the last ship day.
+    const todayOrd = (opts.today && ymdToOrd(opts.today)) || maxOrd;
+    const endOrd = Math.max(todayOrd, maxOrd);
+    const weeks = Math.max(1, Math.min(53, Math.round(Number(opts.weeks)) || 53));
+
+    // Columns are weeks, rows Sun..Sat. Epoch day 0 (1970-01-01) is a Thursday, so the
+    // Sunday-indexed weekday is (ord + 4) mod 7. The last column is the week holding
+    // endOrd; walk back `weeks` Sundays to the first cell.
+    const dow = (o) => (((o + 4) % 7) + 7) % 7;
+    const endSun = endOrd - dow(endOrd);
+    const startSun = endSun - (weeks - 1) * 7;
+
+    // level 0 = empty; 1..5 map to the anti-gaming daily cap (streak.js caps a day at
+    // 5), so the darkest band means "hit the day's max", not "over some threshold".
+    const level = (c) => (c <= 0 ? 0 : Math.min(5, c));
+
+    let cells = '';
+    for (let col = 0; col < weeks; col++) {
+      for (let row = 0; row < 7; row++) {
+        const o = startSun + col * 7 + row;
+        if (o > endOrd) { cells += '<span class="kit-cal__cell kit-cal__cell--void" aria-hidden="true"></span>'; continue; }
+        const c = counts.get(o) || 0;
+        const ymd = ordToYmd(o);
+        const title = c > 0 ? `${ymd} · ${c} ship${c === 1 ? '' : 's'}` : `${ymd} · no ships`;
+        cells += `<span class="kit-cal__cell" data-level="${level(c)}" title="${esc(title)}"></span>`;
+      }
+    }
+
+    const summary = opts.ariaLabel
+      || `Ships per day over the last year: ${totalShips} ship${totalShips === 1 ? '' : 's'} across ${activeDays} day${activeDays === 1 ? '' : 's'}.`;
+    // The legend is aria-hidden: it decorates the bands, it carries no fact the cell
+    // titles and the summary do not already state in words.
+    const legend = '<div class="kit-cal__key" aria-hidden="true"><span class="kit-cal__key-label">less</span>'
+      + [0, 1, 2, 3, 5].map((lv) => `<span class="kit-cal__cell" data-level="${lv}"></span>`).join('')
+      + '<span class="kit-cal__key-label">more</span></div>';
+    // The grid is wide, so it gets its OWN horizontal strip (the section-rail idiom) —
+    // it never widens the document (modules/hall-ui/CLAUDE.md "no sideways scroll").
+    return `<div class="kit-cal" role="img" aria-label="${esc(summary)}">`
+      + `<div class="kit-cal__scroll"><div class="kit-cal__grid">${cells}</div></div>`
+      + legend
+      + '</div>';
+  }
+
   const api = {
     esc,
     // pager (low-level exports so pages can adopt incrementally)
@@ -1042,6 +1139,8 @@
     // linePoints/cumulate are the maths on their own, for a chart that wants
     // the geometry without this SVG (the profile's timeChart).
     sparklineHtml, barSeriesHtml, chartCardHtml, linePoints, cumulate, cumulateByDay,
+    // the year-grid contribution calendar (task 1003572) — the hall's third chart family
+    calendarGridHtml,
     // plotted charts: the axis frame + the two series shapes that ride it
     plotSvgHtml, plotValueLabelHtml, timeStepSeriesHtml, timeStepGeometry, columnSeriesHtml,
     // plotBox is exported so a caller mapping pointer x back into viewBox

package/modules/hall-ui/public/profile-charts.js

@@ -258,6 +258,35 @@
     };
   }
 
+  // The contribution calendar (task 1003572, criterion legibility-series-are-drawn):
+  // a year of qualifying ship-days as OTBKit's third chart family, with the streak
+  // scalars read beside it. SELF-ONLY and range-INDEPENDENT — the data is streak.
+  // ship_days off the viewer's own /me (task added it there), and a calendar is a
+  // year by definition, so it ignores the lookback the other figures clip to. Returns
+  // null on an empty history so draw() simply omits it — never an empty grid (the
+  // module doc's honest-exit rule; DONE WHEN #4).
+  function calendarChart({ id, streak }) {
+    const days = (streak && Array.isArray(streak.ship_days)) ? streak.ship_days : [];
+    const grid = window.OTBKit.calendarGridHtml(days, { today: streak && streak.today });
+    if (!grid) return null;
+    const active = days.filter((d) => Number(d.count) > 0).length;
+    const cur = Number(streak && streak.current) || 0;
+    const lng = Number(streak && streak.longest) || 0;
+    // The scalars in words, in the .pchart__read slot the other figures use for their
+    // crosshair readout — here it is static because the calendar's reading is per-cell.
+    const read = `Current streak ${cur} day${cur === 1 ? '' : 's'} \u00b7 longest ${lng} \u00b7 `
+      + `${active} day${active === 1 ? '' : 's'} shipped this year`;
+    const html = `<figure class="pchart" id="${esc(id)}">
+      <figcaption class="pchart__title">Your shipping year</figcaption>
+      <p class="pchart__read">${esc(read)}</p>
+      ${grid}
+      <p class="pchart__foot">a year of qualifying ships, in your timezone \u00b7 only you see this one</p>
+    </figure>`;
+    // No wire: the reading is the per-cell title + the grid's aria summary, not a
+    // crosshair, so there is no pointer handler to attach.
+    return { id, html, wire() {} };
+  }
+
   // Weekly columns: at most 24px thick, a 4px rounded cap on a square base, a
   // 2px surface gap between neighbours, the tallest column labelled.
   function columnChart({ id, title, buckets, footer }) {
@@ -400,7 +429,7 @@
 
   // Draw every figure for one lookback window into #charts-grid. Split from
   // render() so the range buttons can re-draw without re-fetching the record.
-  async function draw({ api, API, builderId, isOwn, rows, paidFull, estimated, now, rangeId }) {
+  async function draw({ api, API, builderId, isOwn, rows, paidFull, estimated, now, rangeId, selfStreak }) {
     const grid = $('#charts-grid');
     if (!grid) return;
     const range = RANGES.find((r) => r.id === rangeId) || RANGES[RANGES.length - 1];
@@ -431,6 +460,12 @@
         footer: `${fmtNum(inWindow.length)} work${inWindow.length === 1 ? '' : 's'} · ${span}`,
       }),
     ];
+    if (isOwn && selfStreak) {
+      // The calendar leads the viewer's own overview — the year-at-a-glance the goal's
+      // thesis is about. Null (no qualifying ships yet) → simply not shown.
+      const cal = calendarChart({ id: 'chart-calendar', streak: selfStreak });
+      if (cal) figs.unshift(cal);
+    }
     if (isOwn) {
       const paceDays = Math.min(range.days || PACE_MAX_DAYS, PACE_MAX_DAYS);
       const own = await fetchOwnRate(api, API, builderId, paceDays);
@@ -448,7 +483,7 @@
     figs.forEach((f) => { const el = grid.querySelector(`#${f.id}`); if (el) f.wire(el); });
   }
 
-  async function render({ api, API, builderId, selfId, signedIn, now = Date.now() }) {
+  async function render({ api, API, builderId, selfId, signedIn, selfStreak = null, now = Date.now() }) {
     const mount = $('#charts-grid');
     const controls = $('#charts-controls');
     if (!mount) return;
@@ -500,10 +535,10 @@
           b.classList.toggle('is-active', on);
           b.setAttribute('aria-pressed', String(on));
         });
-        draw({ api, API, builderId, isOwn, rows, paidFull, estimated, now, rangeId });
+        draw({ api, API, builderId, isOwn, rows, paidFull, estimated, now, rangeId, selfStreak });
       });
     }
-    await draw({ api, API, builderId, isOwn, rows, paidFull, estimated, now, rangeId });
+    await draw({ api, API, builderId, isOwn, rows, paidFull, estimated, now, rangeId, selfStreak });
   }
 
   window.OTBProfileCharts = { render, cumulativeByDay, craftMix, weeklyBuckets, estimateOf, clipToWindow };

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

@@ -208,7 +208,7 @@
 <!-- The charts (task 1003489). Loaded BEFORE profile.js so window.OTBProfileCharts
      exists when renderProfile runs; profile.js guards on it, so a page that
      omits this script simply has no charts section content. -->
-<script src="/builders/profile-charts.js?v=2026-09-02-charts"></script>
+<script src="/builders/profile-charts.js?v=2026-09-04-calendar"></script>
 <script src="/builders/profile.js?v=2026-09-02-rail"></script>
 </body>
 </html>

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

@@ -25,6 +25,11 @@
   // ({ status, ok, data }) preserves control flow 1:1. throwOnError:false so a
   // 401/404 is a value to branch on, not an exception.
   const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+  // The viewer's own /me payload, captured wherever it is fetched so the Overview's
+  // contribution calendar (task 1003572) can read streak.ship_days without a second
+  // /me round-trip. Null until /me resolves; only ever the VIEWER's own, never a
+  // profile being viewed by id.
+  let selfMe = null;
 
   const { escapeHtml, $, fmtNum, fmtDate } = window.OTB;
   const rankLabel = (rank) => window.OTB.rankLabel(rank);
@@ -656,7 +661,7 @@
     // The charts (task 1003489) read the activity route and the credits ledger
     // (task 1003491), so they need the same session the ledgers do; on the
     // viewer's own profile they add the pace.
-    if (window.OTBProfileCharts) window.OTBProfileCharts.render({ api, API, builderId: builder.id, selfId, signedIn: selfId != null });
+    if (window.OTBProfileCharts) window.OTBProfileCharts.render({ api, API, builderId: builder.id, selfId, signedIn: selfId != null, selfStreak: (selfMe && selfMe.streak) || null });
     renderCrossProject(data, selfId);
     renderAchievements(data.achievements);
     buildWorksLedger(builder.id, selfId != null, data.recent_ships);
@@ -722,6 +727,7 @@
     try {
       const me = await api.request('GET', `${API}/me`);
       if (!me.ok) return null;
+      selfMe = me.data || null;
       const builder = (me.data && me.data.builder) ? me.data.builder : me.data;
       return (builder && builder.id) || null;
     } catch (err) {
@@ -746,6 +752,7 @@
         return;
       }
       if (!me.ok) throw new Error(`me → ${me.status}`);
+      selfMe = me.data || null;
       const builder = (me.data && me.data.builder) ? me.data.builder : me.data;
       const selfId = builder && builder.id;
       if (!selfId) {

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

@@ -1988,6 +1988,37 @@ main [id] { scroll-margin-top: calc(var(--topbar-h) + 16px); }
 .kit-chart__empty { font-size: 12px; color: var(--ink-faint); }
 .kit-chart__foot { font-size: 11.5px; color: var(--ink-faint); margin-top: 4px; }
 
+/* The contribution calendar — OTBKit.calendarGridHtml (task 1003572), the hall's
+   THIRD chart family. A year grid of small cells, banded by ship count 0..5. Theme-
+   aware by construction: every band is a color-mix off --accent and --surface-2, both
+   theme tokens, so light and dark read without a second palette and level 5 is the
+   full accent in either. The grid is wide, so .kit-cal__scroll holds it in its OWN
+   horizontal strip — the document never scrolls sideways (hall-ui/CLAUDE.md). */
+.kit-cal { display: flex; flex-direction: column; gap: 6px; --kit-cal-cell: 11px; }
+.kit-cal__scroll { overflow-x: auto; padding-bottom: 2px; }
+.kit-cal__grid {
+  display: grid;
+  grid-template-rows: repeat(7, var(--kit-cal-cell));
+  grid-auto-flow: column;
+  grid-auto-columns: var(--kit-cal-cell);
+  gap: 3px;
+  width: max-content; /* intrinsic width; the scroll strip, not the document, holds it */
+}
+.kit-cal__cell {
+  width: var(--kit-cal-cell); height: var(--kit-cal-cell);
+  border-radius: 2px;
+  background: var(--surface-2);
+}
+.kit-cal__cell[data-level="1"] { background: color-mix(in srgb, var(--accent) 25%, var(--surface-2)); }
+.kit-cal__cell[data-level="2"] { background: color-mix(in srgb, var(--accent) 45%, var(--surface-2)); }
+.kit-cal__cell[data-level="3"] { background: color-mix(in srgb, var(--accent) 65%, var(--surface-2)); }
+.kit-cal__cell[data-level="4"] { background: color-mix(in srgb, var(--accent) 82%, var(--surface-2)); }
+.kit-cal__cell[data-level="5"] { background: var(--accent); }
+.kit-cal__cell--void { background: transparent; }
+.kit-cal__key { display: flex; align-items: center; gap: 3px; font-family: var(--label-face); font-size: var(--label-size); letter-spacing: var(--label-space); text-transform: var(--label-case); color: var(--ink-faint); }
+.kit-cal__key .kit-cal__cell { --kit-cal-cell: 10px; }
+.kit-cal__key-label { margin: 0 2px; }
+
 .kit-spark { width: 100%; height: 44px; display: block; }
 /* The stroke/fill here are the FALLBACK: sparklineHtml writes the caller's
    colour inline, because the Curve spends a different accent per chart. */

package/modules/public-landing/public/assets/cosmos.css

@@ -411,6 +411,16 @@ h1{font-family:var(--font-display);font-weight:700;font-size:clamp(24px,3.4vw,32
    task 1003355 moved it to the project's own page, where the section's heading
    is the disclosure and the row it left carries only its two doors. */
 .attachNote{margin:8px 0 0;font-size:13px;line-height:1.45;color:var(--ink-faint);}
+/* invites filed in this session (task 1002346): a hairline ledger under the pair
+   above — one line per person, the name in the body voice, what happened next to
+   it in the faint ink. Shared by the wizard's step and the project's own page. */
+.inviteList{list-style:none;display:grid;margin:12px 0 0;padding:0;}
+.inviteList:empty{display:none;}
+.inviteList>li{display:grid;grid-template-columns:auto 1fr;gap:2px 10px;padding:10px 0 11px;border-top:1px solid var(--rule-soft);}
+.inviteList>li:first-child{border-top:0;}
+.inviteList>li::before{content:"";grid-column:1;grid-row:1;width:7px;height:7px;margin-top:7px;border-radius:50%;border:1px solid var(--accent);background:var(--bg);}
+.inviteList b{grid-column:2;font-family:var(--font-body);font-weight:500;font-size:15px;color:var(--ink);}
+.inviteList small{grid-column:2;font-family:var(--font-body);font-size:13px;font-weight:400;line-height:1.45;color:var(--ink-faint);}
 .attachNote code{font-family:var(--font-mono);}
 .projMsg{font-size:13.5px;font-weight:600;margin-top:10px;min-height:18px;color:var(--ink-soft);line-height:1.5;}
 .projMsg.ok{color:var(--ok);}
@@ -1516,6 +1526,14 @@ p.sec-p{font-size:var(--fs-lede);font-weight:500;color:var(--ink-soft);line-heig
 #view-new #wizSignin:hover{background:color-mix(in srgb,var(--ink) 88%,var(--bg));}
 /* the error alert: the error ink between two hairlines, no plate */
 #view-new .alert{background:none;border:0;border-top:1px solid var(--err);border-bottom:1px solid var(--err);border-radius:0;padding:12px 0;font-weight:400;}
+/* the invite step (task 1002346): the page's own input+button pair, wearing the
+   wizard's hairline field rather than the plated one — the .attach width has to
+   give way to the row's flex, or #view-new's own width:100% overflows it */
+#view-new .attach{gap:10px 14px;margin-top:14px;align-items:center;}
+#view-new .attach input[type=text]{width:auto;flex:1;min-width:220px;}
+#view-new .inviteBox{margin-top:34px;}
+#view-new .inviteBox .finePrint{margin-top:10px;}
+#view-new #wizInviteLater{margin-top:14px;}
 /* one fold for the whole wizard: 840 is where the page's bands and ledger stack
    (cosmos's createSplit collapse), so the rail folds with them, not before them */
 @media (max-width:840px){

package/modules/public-landing/public/projects.html

@@ -849,6 +849,27 @@ summary{min-height:24px;padding:3px 0;}
         </details>
       </div>
 
+      <!-- live since task 1002346 (BV1.R27): the way to invite a builder AFTER
+           creation. The wizard's invite step is skippable, and — the mModules
+           argument beside it — an optional step is a default rather than a dead end
+           only if there is a way back. The SAME widget on the SAME route
+           (POST /projects/invite), admitted here by the project's own ownership
+           (ADR 0248); like its neighbour above, nothing is pushed to the project and
+           nothing restarts, so there is no "what your project runs" read-back line. -->
+      <div class="card mSec" id="mInvite">
+        <h2>Invite a builder</h2>
+        <div id="mInv">
+          <p class="finePrint">By GitHub username. They get an invitation to accept from their own projects page, and they need to have signed in here at least once.</p>
+          <div class="attach">
+            <label class="vh" for="mInviteWho">GitHub username</label>
+            <input type="text" id="mInviteWho" placeholder="GitHub username" autocomplete="off" autocapitalize="off" spellcheck="false" maxlength="200">
+            <button type="button" class="btn small" data-invite-send="mInvite">Invite</button>
+          </div>
+          <ul class="inviteList" id="mInviteList"></ul>
+          <div class="projMsg" id="mInviteMsg" role="status" aria-live="polite"></div>
+        </div>
+      </div>
+
       <!-- the planet picker (task 1003347; direction record §16, v1 the bands): the
            owner's own choice of how the platform draws this project — the sky,
            the list, this page's head and the card read the same row. The pick is
@@ -1203,7 +1224,29 @@ summary{min-height:24px;padding:3px 0;}
             <!-- the STABLE live region: the strip inside is rebuilt every 5s tick,
                  and a live region that is itself replaced never announces -->
             <div id="liveProgress" role="status" aria-live="polite"></div>
-            <h2 class="stepsHead">Your steps — the parts only you can play</h2>
+            <!-- the invite step (task 1002346, BV1.R27) — OPTIONAL, and it stands HERE
+                 rather than in the numbered rail because an invite needs a project that
+                 already exists: the catalog row a client_id resolves is projected at
+                 create (ADR 0246), so before the Create step there is nothing to invite
+                 anyone TO. The whole reasoning is ADR 0249. Hidden until the created
+                 record carries an id and a slug; the script is the only thing that
+                 shows it. -->
+            <div class="inviteBox" id="wizInvite" hidden>
+              <h2 class="stepsHead">Invite builders</h2>
+              <p class="finePrint">Optional — invite people by GitHub username. Each one gets an invitation to accept from their own projects page, and they need to have signed in here at least once. Skip this and invite anyone later; nothing about your project waits on it.</p>
+              <div class="attach">
+                <label class="vh" for="wizInviteWho">GitHub username</label>
+                <input type="text" id="wizInviteWho" placeholder="GitHub username" autocomplete="off" autocapitalize="off" spellcheck="false" maxlength="200">
+                <button type="button" class="btn small" data-invite-send="wizInvite">Invite</button>
+                <button type="button" class="btn small ghost" data-invite-skip="wizInvite">Skip</button>
+              </div>
+              <ul class="inviteList" id="wizInviteList"></ul>
+              <div class="projMsg" id="wizInviteMsg" role="status" aria-live="polite"></div>
+            </div>
+            <!-- the way back, the doneModules idiom: an optional step is a default
+                 rather than a dead end only if the panel names where it lives after -->
+            <p class="samePath" id="wizInviteLater"></p>
+            <h2 class="stepsHead" id="doneStepsHead">Your steps — the parts only you can play</h2>
             <ol class="humanSteps" id="humanSteps"></ol>
             <!-- the modules step was optional (task 1002342, BV1.R23) — one line
                  saying where it lives afterwards, so a skip is never a dead end -->
@@ -4098,6 +4141,14 @@ summary{min-height:24px;padding:3px 0;}
          skippable, so this panel names where it lives afterwards rather than
          leaving an owner to go looking for it. */
       $('doneModules').innerHTML = 'Add or remove modules later in ' + projectPageLink('the project’s settings') + '.';
+      /* the invite step (task 1002346, BV1.R27). The CREATED RECORD is the proof
+         the widget needs and the only one this panel has: no signed-in identity,
+         no filed instance or no slug ⇒ nothing to invite to, and the step stays
+         hidden. It is deliberately NOT keyed on instanceId, which startProgress
+         sets only AFTER this runs. */
+      var created = createdRecord();
+      setInviteSlug('wizInvite', (me && created && created.id && created.slug) ? created.slug : '');
+      $('wizInviteLater').innerHTML = 'You can invite builders any time from ' + projectPageLink('the project’s own page') + '.';
       renderSteps();
     }
 
@@ -5280,6 +5331,11 @@ summary{min-height:24px;padding:3px 0;}
        progress survives the tick because only a different project re-renders it */
     renderPick(inst);
     renderCardPick(inst);
+    /* invite a builder (task 1002346): fetch-free too — the widget needs only the
+       slug, and the API is the wall. This read is own-scoped and 404s for anyone
+       who is not the owner, so reaching renderManage at all IS the ownership
+       answer the widget does not ask for itself. */
+    setInviteSlug('mInvite', inst.slug || '');
     /* the page names its project — the heading holds #mName; and in the tab */
     document.title = (inst.slug ? inst.slug + ' — ' : '') + BASE_TITLE;
     /* the card's own story, on the project's own page (task 1003232): the
@@ -6692,6 +6748,169 @@ summary{min-height:24px;padding:3px 0;}
     goToManage(m.getAttribute('data-manage'));
   });
 
+  /* ══ invite a builder (task 1002346, BV1.R27; goal 1000046 criterion C6, ADR 0249)
+     ONE widget, mounted twice: the creation wizard's optional invite step (on the
+     done panel — an invite needs a project that already exists) and the project's
+     own page, so a skipped step is a default rather than a dead end.
+
+     THE ROUTE IS USED AS IT STANDS: POST /projects/invite { client_id, github_login },
+     where client_id IS the project's slug — ADR 0246 projects a control-plane project
+     onto the catalog under its slug — and the project's owner is admitted by ADR 0248's
+     ownership arm. Nothing here is a second gate; the server owns the answer.
+
+     TWO QUESTIONS THIS WIDGET DELIBERATELY DOES NOT ASK: "is anyone signed in" and
+     "is this their project". Each caller already knows, and hands over a slug or
+     nothing — which is the ONE door in (setInviteSlug). A widget that re-derived
+     ownership on the page would be a second, weaker copy of a server rule.
+
+     THE REFUSALS ARE SAID IN THE ROUTE'S OWN VOCABULARY, and the 403 is said
+     CAREFULLY: it is byte-identical whether the project is real, stealth, or absent
+     (ADR 0248), so this page may never word it as "it exists but you may not" — that
+     would hand back the membership oracle the route equalised away.
+
+     IT NEVER BLOCKS CREATION. The project is filed before the step is shown at all;
+     a refusal leaves the box exactly as it was, ready to try again.
+
+     WHAT IT PUBLISHES OF AN INVITEE is the 201 row's own membership_kind and the
+     login the inviter typed — never the github_id the row carries, which belongs to
+     someone who has accepted nothing yet.
+     Proof: ../../../tests/project_invite_ui.mjs ══ */
+
+  var INVITE_MOUNTS = {
+    wizInvite: { who: 'wizInviteWho', list: 'wizInviteList', msg: 'wizInviteMsg', after: 'doneStepsHead' },
+    mInvite: { who: 'mInviteWho', list: 'mInviteList', msg: 'mInviteMsg', after: null }
+  };
+  var inviteSlug = {};   /* mount id → the slug it invites to; '' means no step at all */
+  var inviteRows = {};   /* mount id → the invites filed on THIS project this session */
+  var inviteBusy = {};   /* a send is in flight — the mount is inert until it answers */
+
+  /* setInviteSlug(id, slug) — the only door in. A falsy slug closes the mount, which
+     is how "signed out", "not the owner" and "no project yet" all reach this widget.
+     A DIFFERENT slug starts clean: the pending lines belonged to the project they
+     were filed on, and following them to another one would be a lie. */
+  function setInviteSlug(id, slug) {
+    var m = INVITE_MOUNTS[id];
+    if (!m) return;
+    var next = slug || '';
+    if (inviteSlug[id] !== next) {
+      inviteSlug[id] = next;
+      inviteRows[id] = [];
+      inviteSay(id, '', '');
+    }
+    var box = $(id);
+    if (box) box.hidden = !next;
+    renderInviteRows(id);
+  }
+
+  /* One line per invite this session filed: the login the inviter typed, and the
+     WORD THE ROW ITSELF CARRIES — so a membership_kind other than 'pending' shows
+     up here rather than being papered over as one. */
+  function renderInviteRows(id) {
+    var m = INVITE_MOUNTS[id];
+    var list = m && $(m.list);
+    if (!list) return;
+    list.innerHTML = (inviteRows[id] || []).map(function (r) {
+      var said = r.kind === 'pending' ? 'invited — waiting for them to accept.' : r.kind;
+      return '<li><b>' + esc(r.login) + '</b><small>' + esc(said) + '</small></li>';
+    }).join('');
+  }
+
+  function inviteSay(id, text, cls, isHtml) {
+    var m = INVITE_MOUNTS[id];
+    var el = m && $(m.msg);
+    if (!el) return;
+    el.className = 'projMsg' + (cls ? ' ' + cls : '');
+    if (isHtml) el.innerHTML = text; else el.textContent = text;
+  }
+
+  /* inviteRefusal(code, status, message) — the route's refusals as one sentence
+     each. PURE, so the harness reads it directly. A code this page does not know
+     falls through to the SERVER'S own words rather than an invented reason. */
+  function inviteRefusal(code, status, message) {
+    if (status === 404 && code === 'account_not_found') return 'That builder hasn’t signed in here yet — ask them to sign in once, then invite them.';
+    if (status === 404 && code === 'unknown_project') return 'This project isn’t on the map yet — give it a moment and try again.';
+    /* deliberately says nothing about the project: see the header */
+    if (status === 403) return 'This account can’t invite people here.';
+    return message || 'The invitation couldn’t be sent — try again in a moment.';
+  }
+
+  /* doInvite(id) — one builder, one request. */
+  function doInvite(id) {
+    var m = INVITE_MOUNTS[id];
+    var slug = inviteSlug[id] || '';
+    if (!m || !slug || inviteBusy[id]) return;
+    var field = $(m.who);
+    var login = String((field && field.value) || '').replace(/^\s+|\s+$/g, '');
+    if (!login) {
+      inviteSay(id, 'Type the GitHub username of the person you want to invite.', 'err');
+      if (field && field.focus) field.focus();
+      return;
+    }
+    inviteBusy[id] = true;
+    inviteSay(id, 'Sending the invitation…', '');
+    fetch(API + '/projects/invite', {
+      method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ client_id: slug, github_login: login })
+    }).then(function (res) {
+      return jsonOrEmpty(res).then(function (data) {
+        inviteBusy[id] = false;
+        if (res.ok) {
+          if (data && data.invited && data.row) {
+            inviteRows[id] = (inviteRows[id] || []).concat([{ login: login, kind: String(data.row.membership_kind || 'pending') }]);
+            renderInviteRows(id);
+            if (field) { field.value = ''; if (field.focus) field.focus(); }
+            inviteSay(id, login + ' is invited — they accept it from their own projects page.', 'ok');
+            return;
+          }
+          /* 200 { invited: false, alreadyMember: true } — not a failure, and not a
+             pending invite either: they are already on the project */
+          if (field) field.value = '';
+          inviteSay(id, login + ' is already on this project.', 'ok');
+          return;
+        }
+        if (res.status === 401) { inviteSay(id, signInAgain(), 'err', true); return; }
+        var e = apiError(data, res.status);
+        inviteSay(id, inviteRefusal(e.code, res.status, e.message), 'err');
+      });
+    }).catch(function () {
+      inviteBusy[id] = false;
+      inviteSay(id, 'Couldn’t reach the platform — check your connection and try again.', 'err');
+    });
+  }
+
+  /* skipInvite(id) — the step steps aside having sent NOTHING. Focus moves on
+     rather than being stranded inside the box that just went away. */
+  function skipInvite(id) {
+    var m = INVITE_MOUNTS[id];
+    if (!m || inviteBusy[id]) return;
+    var box = $(id);
+    if (box) box.hidden = true;
+    inviteSay(id, '', '');
+    var after = m.after && $(m.after);
+    if (after && after.focus) { after.setAttribute('tabindex', '-1'); after.focus(); }
+  }
+
+  /* One delegated pair per mount: the buttons name their own mount, so the two
+     surfaces share every line of behaviour above without sharing state. */
+  Object.keys(INVITE_MOUNTS).forEach(function (id) {
+    var box = $(id);
+    if (box) {
+      box.addEventListener('click', function (ev) {
+        var t = ev.target.closest && ev.target.closest('[data-invite-send],[data-invite-skip]');
+        if (!t) return;
+        if (t.hasAttribute('data-invite-skip')) skipInvite(id); else doInvite(id);
+      });
+    }
+    var field = $(INVITE_MOUNTS[id].who);
+    if (field) {
+      field.addEventListener('keydown', function (ev) {
+        if (ev.key !== 'Enter') return;
+        ev.preventDefault();
+        doInvite(id);
+      });
+    }
+  });
+
   /* ── boot: who am I → my instances ────────────────────────────────────── */
 
   function renderWho() {

package/modules/public-landing/public/projects.states.json

@@ -22,6 +22,7 @@
     "in-manage-address": { "auth": true, "url": "/projects?view=manage&id=101", "expect": { "visible": ["#mAddress", "#mAddress h2", "#mDom .plain", "#mDomName", "#mDom [data-m-attach]", "#mDomWhat summary"], "count": [["#mDom .attach input[type=text]", 1], ["#mDom .attach button", 1]] } },
     "in-manage-planet": { "auth": true, "url": "/projects?view=manage&id=101", "expect": { "visible": ["#mPlanetPick", "#mPick .pick .pickPreview .worldOrb .disc", "#mPick [data-pick-save]", "#mPick [data-pick-reset]", "#mPickWhat summary"], "count": [["#mPick .pickCells[role=\"radiogroup\"]", 3], ["#mPick .pickCell", 10], ["#mPick .pickCell.on", 3], ["#mPick .pickSw", 5], ["#mPick .pickSw.on", 1]], "attr": [["#mPick .pickPreview .worldOrb", "data-template", "pair-obsidian-tint"], ["#mOrb .worldOrb", "data-template", "pair-obsidian-tint"]], "checked": "#mPick input[name=\"mPickAccent\"][value=\"sea\"]", "text": [["#mPlanet .v small", "your choice."]] } },
     "in-manage-card": { "auth": true, "url": "/projects?view=manage&id=101", "expect": { "visible": ["#mCard", "#mCardPick .pick .pickPreview .cardBand", "#mCardPick [data-card-save]", "#mCardWhat summary"], "count": [["#mCardPick .pickCells[role=\"radiogroup\"]", 1], ["#mCardPick .pickCell", 5], ["#mCardPick .pickCell.on", 1]], "checked": "#mCardPick input[name=\"mCardBackdrop\"][value=\"\"]", "attr": [["#mCardPick .cardBand", "data-own", ""]] } },
+    "in-manage-invite": { "auth": true, "url": "/projects?view=manage&id=101", "expect": { "visible": ["#mInvite", "#mInvite h2", "#mInviteWho", "#mInvite [data-invite-send]"] } },
     "in-manage-snag": { "auth": true, "url": "/projects?view=manage&id=103", "expect": { "visible": ["#mMain", "#mErr", "#mActs"], "hidden": ["#mAddress"], "text": [["#mName", "tidepool"]] } },
     "in-manage-gone": { "auth": true, "url": "/projects?view=manage&id=104", "expect": { "visible": ["#mMain", "#mActs"], "hidden": ["#mErr", "#mAddress"], "text": [["#mName", "old-lantern"]] } },
     "in-manage-missing": { "auth": true, "url": "/projects?view=manage&id=999", "expect": { "visible": ["#mMissing"], "hidden": ["#mMain", "#mGate"] } },

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.538",
+  "version": "1.19.540",
   "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",