@bongos/core 1.19.412 → 1.19.414

package/docs/design/landing-page-direction-v2.md

@@ -60,6 +60,8 @@ What the pick settles: the settled constraint (dark-first with a real, tested li
 
 **2026-08-28, the second note (task 1003334).** Seeing the before/after of task 1003333, the owner found the chrome bongo pair sitting on the top-right sweeping form did not fit ("the random bongos on the blobs background"). Offered three treatments (remove it from the hero; keep it off the blob on plain black or paper; phones only), the owner picked **remove it from the hero**. The pair is no longer a hero object: `.mark`, its arrival and its tokens leave; it stays as the closing figure, the second project orb and the bar's mark. The sweeping form stays as a bare backdrop. Under 900 the masthead is the big blob alone, with the words keeping the 56vw the pair used to hold above them.
 
+**2026-08-28, the third note — dark only (task 1003336, [ADR 0204](../adr/<redacted>.md)).** Reviewing the planets (task 1003319) with both grounds in front of them, the owner took option 4 of §5 after all, widened to the whole apex: "only black or only white is a bit bland, frankly I am leaning towards only dark mode for this page and keep the dark/light mode to be solely for the builder hall … we could invest into a cool space themed backdrop for the blobs." Built: `data-mode="dark"` fixed on `<html>` of every apex page, the pre-paint script and the persisted `cb-color-mode` gone, the moon/sun glyph and its wiring out of both bars, the kit rendering dark only. What the 2026-08-27 pick settled about light — the cutouts on paper under a contact shadow, the toggle staying on the landing — no longer describes the apex; the cutouts remain the closing figure and the planets' masks. The light tier of `world.css` stays until its own removal. The space backdrop is the next task (1003337).
+
 ## 7. Shot list: real imagery still owed
 
 No version left a placeholder slot: every image on the three pages is a real plate (the round-2 chrome set, the single blob, the two bongo pairs, the two new blob cutouts) or the real Verro Labs medallion, and the proof is the ledger rendered as page content, so no hall or hub capture is used. What the build will still owe:

package/docs/design/projects-hub-direction-v2.md

@@ -170,3 +170,7 @@ Three mastheads, rendered dark and light at 1440 / 390 / 320 (ALL CLEAN) and mea
 **What was built.** In `cosmos.css` the orb's disc is a masked colour layer over a cutout (`.disc::before`: the plate as both background and mask, `background-blend-mode` by style), sized `--d` by the object's own aspect; `[data-shape]` carries the three crops, `[data-style]` the three blends; the relationship ring is a circle behind the object (a mask clips a box-shadow away), the search spotlight an accent drop-shadow on the disc's filter after the contact shadow (dark's `--orb-shadow` is `opacity(1)`, a no-op, so the two compose). The starfield, its 3.2s twinkle, the 74px gravity grid and `--star-display` are gone; the labels, the badge, the hint and the hover card moved onto the world's type (hairline pill, label face, no accent on a fact, no shadow). In `projects.html` `ORB_TEMPLATES` walks beside `ORB_ACCENTS` in `assignAccents` (consecutive positions change shape and style; nine against five repeat every forty-five projects), `templateOf()` prefers a curated name, an owned-only entry walks by its slug, the orb carries `data-template` / `data-shape` / `data-style`, the physics measures the disc's own height, and the slot widths grew a quarter (a cutout's silhouette reads smaller than a filled disc of the same box). The platform's own orb is the pair in chrome. On the catalog side migration `<redacted>` adds the nullable `template` column with its nine-value CHECK, `upsertProject` carries it COALESCE-preserved, `POST /projects` validates it against `PROJECT_TEMPLATES`, and the public `/projects/featured` projection returns it. The kit's fixture gives Example a curated `bead-wash` and the `in-map` state reads it back off the orb.
 
 **Not done, on purpose:** no owner-facing picker — a template is set through the curation route today, the way `featured` is; whether a project's owner chooses their own planet from the manage view is the owner's call. The manage view's small `.orb` spheres keep their old look (the scope named the sky's `a.worldOrb` only).
+
+## 12. Dark only (task 1003336)
+
+**Date:** 2026-08-28 (decided), 2026-08-29 (built) · the owner's call on the planets review (§11): the apex renders dark only and the light/dark switch is the builders' hall's alone — [ADR 0204](../adr/<redacted>.md). On `/projects`: `data-mode="dark"` is fixed on `<html>`, the pre-paint script is gone, the `#modeToggle` glyph and its `resolvedMode` / `paintModeToggle` wiring leave the bar (Projects, then the chip), the `.modeBtn` rules and the icon-swap twins leave `cosmos.css`, the mode-toggle probe leaves `projects.probes.json`, and `projects.states.json` declares `"modes": ["dark"]` so the kit renders the hub's twelve states at three widths in one mode (48 shots, ALL CLEAN; probes 31/31). The light tier of `cosmos.css` stays until its own removal. Why first: the space backdrop for the field (task 1003337) is a black-ground plate; one mode is what lets the field commit to it.

package/docs/module-api-changelog.md

@@ -1261,5 +1261,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.410 with no explicit bump. run 33218290583. (task 1002620)
   1.19.412 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.411 with no explicit bump. run 33259357678. (task 1002620)
+  1.19.413 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.412 with no explicit bump. run 33259477562. (task 1002620)
+  1.19.414 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.413 with no explicit bump. run 33260596712. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/ui-look-before-you-ship.md

@@ -56,7 +56,8 @@ Then a state's own `expect` (a band open, a dialog present, a field's value, a c
 {
   "page": "/projects",
   "surface": "public-landing",
-  "modeQuery": "mode",
+  "modes": ["dark"],
+  "modeQuery": false,
   "ignoreRequests": ["/api/(gds|bongos)/me$", "/my-projects"],
   "ignoreConsole": ["\\b401\\b"],
   "ignoreControls": [".skip", ".vh"],
@@ -69,6 +70,8 @@ Then a state's own `expect` (a band open, a dialog present, a field's value, a c
 }
 ```
 
+`modes` names the modes the page renders (default both). A page that pins one mode — the apex pins `data-mode="dark"` on `<html>` since task 1003336 — declares it here so a plain `--page` render never walks a mode the page cannot show; `--modes` on the command line still overrides. `modeQuery: false` says no query walks a mode.
+
 Actions: `click`, `focus`, `press`, `fill`, `wait`, `clickAt x y`, `clickIfVisible`, `dispatchClick`, `check`, `back`, `forward`. Expectations: `expanded`, `dialog`, `visible[]`, `hidden[]`, `open`, `closed`, `activeId`, `activeText`, `expandedIds[]`, `param{}`, `attr[[sel,name,value]]`, `text[[sel,value]]`, `href[[sel,value]]`, `count[[sel,n]]`, `value[[sel,v]]`, `hasClass[[sel,class,bool]]`, `checked`, `noOverflow`, `top[[sel,px]]` (an element's viewport top — assert it closed, open a band, assert it again: the proof an overlay did not push the page). The kit validates the file before it opens a browser and names every problem.
 
 The worked examples: `public-landing/projects.states.json` (the hub's thirteen), `public-landing/index.states.json` (the landing's four), `modules/hall-ui/public/ranks.states.json` (a second surface under its own prefix — it renders **red**, deliberately: the hall predates the 24px floor and Ranks has no `<h1>`, and the states file declares the shell's un-fixtured feeds rather than hiding the findings; idea 1000863 carries them).

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

@@ -93,6 +93,24 @@
               <p class="settings-status" id="cross-project-status" role="status" aria-live="polite"></p>
             </section>
 
+            <!-- Profile privacy (platform-identity module, privacy spec D1 / task
+                 1002966). The same own-scoped GET/PATCH /me/cross-project as the
+                 section above, so it reveals and hides with it; P04 later moves
+                 both into the Profile rail group. -->
+            <section class="scroll" id="privacy-scroll" aria-labelledby="privacy-h" data-group="account" hidden>
+              <h2 id="privacy-h" class="scroll__h">Profile privacy</h2>
+              <p class="scroll__lede">
+                Who can find you. Your profile page can be public or private, and
+                recruiters looking for builders are allowed in separately — so a
+                private profile can still be reachable for work, and a public one
+                can stay out of recruiting entirely.
+              </p>
+              <div id="privacy-rows"></div>
+              <p class="settings-status" id="privacy-status" role="status" aria-live="polite"></p>
+              <p class="section-note">Your choices are saved to your account now. They start applying as
+                the public profile page and the recruiting surfaces land — nothing is hidden yet.</p>
+            </section>
+
             <!-- CRAFT — discipline preferences (GET /me, PATCH /me/disciplines). -->
             <section class="scroll" id="craft-scroll" aria-labelledby="craft-h" data-group="account" hidden>
               <h2 id="craft-h" class="scroll__h">Preferred disciplines</h2>

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

@@ -583,29 +583,98 @@
       '</div>';
   }
 
-  // PATCH the hide flag. Body: { hide_stats: <bool> } (routes/profile.js).
-  async function saveCrossProject(hide, btn) {
-    const status = $('#cross-project-status');
+  // ---- section: PROFILE PRIVACY (account_visibility + recruiter_discoverable
+  // — privacy spec D1/D3, task 1002966)
+  //
+  // Two more rows on the SAME own-scoped GET/PATCH /me/cross-project, because
+  // both flags live on the hub account beside hide_stats (never behavior_prefs).
+  // The recruiter row's copy must name EXACTLY what being discoverable grants —
+  // the spec's D3 sliver — and that grant shrinks to name-only when the
+  // cross-project record is hidden, because the rest of the sliver is derived
+  // from it. `recruiter_discoverable` is tri-state server-side: null means the
+  // answer follows the visibility setting, which the row says out loud. The
+  // toggle is deliberately BINARY (spec D1: "one column, one settings toggle");
+  // resetting back to null stays an API affordance, not a third UI state.
+  //
+  // COPY RULE while the read paths are unenforced: this task stores the flags,
+  // it does not gate any public read (that is task 1002967), so nothing here
+  // may promise that a page is already hidden — the rows say what the choice
+  // WILL do and the section note says plainly that it is not in force yet. A
+  // toggle that claims protection it does not have is worse than no toggle.
+  function renderPrivacy(data) {
+    const wrap = $('#privacy-rows');
+    if (!wrap) return;
+    const isPublic = !data || data.account_visibility !== 'private';
+    const discoverable = !!(data && data.recruiter_discoverable_effective);
+    const follows = !data || data.recruiter_discoverable == null;
+    const grant = data && data.hide_stats
+      ? 'Because your cross-project record is hidden, they will see your name and nothing else.'
+      : 'They will see your name, your disciplines, and whether you have been active in the last 30 days — never your credits, works shipped, karma, or the projects you build on.';
+    wrap.innerHTML =
+      privacyRow('visibility', 'Public profile page', isPublic ? 'Public' : 'Private', isPublic,
+        'Public means anyone can open your profile page and find you by name. Private will hide the page from everyone but you.', '') +
+      privacyRow('discoverable', 'Discoverable by recruiters', discoverable ? 'On' : 'Off', discoverable,
+        `Recruiters looking for builders will be able to find you. ${grant}`,
+        follows ? ' <span class="voices__default">· follows your profile setting</span>' : '');
+  }
+
+  // One row of the privacy section, in the same sound-row markup every toggle on
+  // this page uses. `note` is trusted markup (a caller-supplied span), the label
+  // and description are escaped.
+  function privacyRow(key, label, state, on, desc, note) {
+    return `<div class="sound-row" data-privacy="${key}">` +
+      '<div class="sound-row__text">' +
+      `<div class="sound-row__label">${escapeHtml(label)}${note}</div>` +
+      `<div class="sound-row__desc">${escapeHtml(desc)}</div>` +
+      '</div>' +
+      `<button type="button" class="sound-toggle" data-on="${on ? '1' : '0'}" aria-pressed="${on ? 'true' : 'false'}">${state}</button>` +
+      '</div>';
+  }
+
+  // The status/toast line for a privacy toggle. Deliberately says only what the
+  // flag itself changed — the exact grant lives in the row's description, which
+  // re-renders from the server right after the save.
+  function privacyMsg(key, on) {
+    if (key === 'visibility') {
+      return on
+        ? 'Saved — your profile page is set to public.'
+        : 'Saved — your profile page is set to private.';
+    }
+    return on
+      ? 'Saved — you are set to be findable by recruiters.'
+      : 'Saved — you are set to stay out of recruiting search.';
+  }
+
+  // PATCH any own-scoped privacy flag (routes/profile.js): { hide_stats } and/or
+  // { account_visibility, recruiter_discoverable }. Always re-reads afterwards —
+  // the effective recruiter answer is derived server-side, so the server's own
+  // view is the only state worth rendering.
+  async function savePrivacy(body, statusSel, msg, btn) {
+    const status = $(statusSel);
     if (status) status.textContent = 'Saving…';
     if (btn) btn.disabled = true;
     try {
-      const res = await api.request('PATCH', `${API}/me/cross-project`, { body: { hide_stats: hide } });
+      const res = await api.request('PATCH', `${API}/me/cross-project`, { body });
       if (res.status === 401) { toAuth(); return; }
       if (!res.ok) throw new Error(`cross-project PATCH → ${res.status}`);
-      await loadCrossProject(); // re-render from the server's truth (flag + record)
-      const msg = hide
-        ? 'Cross-project record hidden — removed from your profile and directories immediately.'
-        : 'Cross-project record shown on your public profile.';
+      await loadCrossProject(); // re-render from the server's truth (flags + record)
       if (status) status.textContent = msg;
       toast(msg);
     } catch (err) {
-      console.error('[settings] save cross-project failed', err);
+      console.error('[settings] save privacy failed', err);
       if (status) status.textContent = 'Could not save. Try again.';
-      toast('Could not save your cross-project preference. Try again.');
+      toast('Could not save your privacy preference. Try again.');
       if (btn) btn.disabled = false;
     }
   }
 
+  // The hide flag. Body: { hide_stats: <bool> } (routes/profile.js).
+  function saveCrossProject(hide, btn) {
+    return savePrivacy({ hide_stats: hide }, '#cross-project-status', hide
+      ? 'Cross-project record hidden — removed from your profile and directories immediately.'
+      : 'Cross-project record shown on your public profile.', btn);
+  }
+
   let crossProjectWired = false;
   async function loadCrossProject() {
     const section = $('#cross-project-scroll');
@@ -615,7 +684,10 @@
       if (res.status === 401) { toAuth(); return; }
       if (!res.ok) return; // module off / route absent → the section stays hidden
       renderCrossProject(res.data);
+      renderPrivacy(res.data);
       section.hidden = false;
+      const privacy = $('#privacy-scroll');
+      if (privacy) privacy.hidden = false;
       if (!crossProjectWired) {
         crossProjectWired = true;
         $('#cross-project-rows').addEventListener('click', (e) => {
@@ -623,6 +695,16 @@
           if (!b || b.disabled) return;
           saveCrossProject(b.dataset.on === '1', b); // shown → hide; hidden → show
         });
+        $('#privacy-rows').addEventListener('click', (e) => {
+          const b = e.target.closest('.sound-toggle');
+          if (!b || b.disabled) return;
+          const row = b.closest('[data-privacy]');
+          const on = b.dataset.on === '1';
+          const body = row && row.dataset.privacy === 'visibility'
+            ? { account_visibility: on ? 'private' : 'public' }
+            : { recruiter_discoverable: !on };
+          savePrivacy(body, '#privacy-status', privacyMsg(row && row.dataset.privacy, !on), b);
+        });
       }
     } catch (err) {
       // Network/parse failure on an optional module section — stay hidden, log only.
@@ -1179,6 +1261,7 @@
     'connections': 'connections-scroll',
     'display-name': 'display-name-scroll',
     'cross-project': 'cross-project-scroll',
+    'privacy': 'privacy-scroll',
     'disciplines': 'craft-scroll',
     'cli': 'cli-scroll',
     'art-key': 'art-key',

package/modules/platform-identity/migrations/platform_identity_012_account_privacy.sql

@@ -0,0 +1,59 @@
+-- platform_identity_012_account_privacy.sql — the two account privacy flags
+-- (task 1002966 / goal 1000045; spec docs/specs/bongos-v1-privacy-and-invites.md
+-- D1, which extends ADR 0171 D3/D4 rather than replacing it).
+--
+-- ADR 0171 already owns two axes on this table: profile_state (consent — has a
+-- live hub session ever touched the account) and hide_stats (numbers — suppress
+-- everything rollup-derived, for every reader). This migration adds the other
+-- two the spec's D1 matrix needs:
+--
+--   account_visibility — EXISTENCE. Does /u/<handle> exist to the world?
+--           'private' means 404-to-strangers and absent from search,
+--           leaderboards, sitemap and every Explore-adjacent surface. Default
+--           'public' = today's behaviour unchanged, so the backfill IS the
+--           DEFAULT clause (the migration 011 precedent) — no separate UPDATE,
+--           and no existing profile changes state when this lands.
+--
+--   recruiter_discoverable — RECRUITING REACH, and deliberately NULLABLE. The
+--           tri-state is the whole design: NULL means "follow visibility", and
+--           the effective value is
+--               COALESCE(recruiter_discoverable, account_visibility = 'public')
+--           which reconciles two owner texts that only LOOKED contradictory —
+--           recruiting reach is OPT-OUT for a public account (every public
+--           profile is reachable; a builder can remove themselves and stay
+--           public) and OPT-IN for a private one (invisible unless this flag is
+--           explicitly true). One column, one settings toggle, whose default
+--           state tracks visibility. A NOT NULL boolean cannot express that: it
+--           would have to pick one default and get the other case wrong.
+--           The single JS twin of that COALESCE is isRecruiterDiscoverable()
+--           in platform-identity.js — the predicate every reader adopts
+--           (enforcement across the read paths is task 1002967's job).
+--
+-- NEITHER COLUMN IS EVER PUBLIC. They are inputs to the public predicates, not
+-- outputs: no public response body may carry them (tests/profile_route.mjs +
+-- tests/hub_profile_leak.mjs are the sentinels; the module's public reads stay
+-- explicit whitelists).
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Forward-safe: ADD
+-- COLUMN only, so the previous code release still runs against this schema.
+-- Idempotent (IF NOT EXISTS + the drop-then-add CHECK pattern from migration 011).
+
+BEGIN;
+
+ALTER TABLE platform_identity_accounts
+  ADD COLUMN IF NOT EXISTS account_visibility text NOT NULL DEFAULT 'public',
+  ADD COLUMN IF NOT EXISTS recruiter_discoverable boolean;
+
+ALTER TABLE platform_identity_accounts
+  DROP CONSTRAINT IF EXISTS platform_identity_accounts_account_visibility_check;
+ALTER TABLE platform_identity_accounts
+  ADD CONSTRAINT platform_identity_accounts_account_visibility_check
+  CHECK (account_visibility IN ('public', 'private'));
+
+COMMENT ON COLUMN platform_identity_accounts.account_visibility IS
+  'Existence axis (spec D1): public|private. Private means the public profile read answers 404 to EVERYONE including its owner (the owner sees their page through the own-scope side door instead), and the account is absent from search, leaderboards and the sitemap. Independent of hide_stats, which suppresses numbers without touching addressability.';
+
+COMMENT ON COLUMN platform_identity_accounts.recruiter_discoverable IS
+  'Recruiting reach (spec D1), TRI-STATE: NULL = follow visibility. Effective value is COALESCE(recruiter_discoverable, account_visibility = ''public'') — opt-out for public accounts, opt-in for private ones. An explicit true on a private account is exactly the D2 "private, discoverable" row: the recruiter sees the D3 sliver and nothing else. hide_stats still beats it (a hidden account''s sliver is name-only).';
+
+COMMIT;

package/modules/platform-identity/platform-identity.js

@@ -150,6 +150,7 @@ async function getAccountByLogin(githubLogin, { pool = defaultPool } = {}) {
 async function getAccount(githubId, { pool = defaultPool } = {}) {
   const { rows } = await pool.query(
     `SELECT id, github_id, github_login, display_name, avatar_url, profile_state, hide_stats,
+            account_visibility, recruiter_discoverable,
             handle, previous_handle, handle_changed_at, bio, links, display_name_source,
             created_at, updated_at
        FROM platform_identity_accounts WHERE github_id = $1`,
@@ -825,7 +826,8 @@ async function setAccountHideStats({ githubId, githubLogin, displayName, avatarU
      ON CONFLICT (github_id) DO UPDATE SET
        hide_stats = EXCLUDED.hide_stats,
        updated_at = now()
-     RETURNING github_id, github_login, profile_state, hide_stats, handle`,
+     RETURNING github_id, github_login, profile_state, hide_stats,
+               account_visibility, recruiter_discoverable, handle`,
     [githubId, githubLogin, displayName ?? null, avatarUrl ?? null, !!hide],
   );
   const row = rows[0];
@@ -835,6 +837,90 @@ async function setAccountHideStats({ githubId, githubLogin, displayName, avatarU
   return row;
 }
 
+// -------------------------------------------------------------------------
+// Account privacy: visibility + recruiter reach (task 1002966 — privacy spec D1)
+// -------------------------------------------------------------------------
+
+// The two stored values of account_visibility (spec D1's EXISTENCE axis).
+// 'private' means the public profile read 404s to everyone — including the
+// owner, who reaches their own page through the own-scope side door instead.
+const ACCOUNT_VISIBILITY = ['public', 'private'];
+
+// isRecruiterDiscoverable(account) — THE effective-recruiter-reach predicate
+// (privacy spec D1). One definition, so every reader answers "may a recruiting
+// surface see this account at all?" the same way; task 1002967 adopts this
+// rather than re-deriving it, and nothing else should spell the COALESCE out.
+//
+// The JS twin of  COALESCE(recruiter_discoverable, account_visibility='public').
+// The tri-state is the point: NULL = follow visibility (opt-OUT for a public
+// account, opt-IN for a private one), an explicit boolean overrides — an
+// explicit true on a PRIVATE account is exactly the spec's D2 "private,
+// discoverable" row, which is what the recruiter sliver exists to serve.
+//
+// NOT a complete gate on its own. profile_state='active' still floors every
+// recruiter surface (a provisional account is never visible), and hide_stats
+// still empties the sliver down to name-only — both stay the caller's to apply.
+// Fail-closed on a missing/absent account.
+function isRecruiterDiscoverable(account) {
+  if (!account) return false;
+  const explicit = account.recruiter_discoverable;
+  if (typeof explicit === 'boolean') return explicit;
+  return account.account_visibility === 'public';
+}
+
+// The own-scoped privacy WRITE (task 1002966) — callers key this by the
+// AUTHENTICATED session's github_id, never a caller-named one. Validates here,
+// next to the data, then upserts on the setAccountProfileFields pattern: the
+// INSERT branch creates a fail-closed provisional account (a hub builder who
+// never federated can still set their privacy ahead of time); the UPDATE branch
+// touches ONLY the flags the caller sent — never identity re-sync, never
+// profile_state (activation stays /sso/authorize's alone, D3), never hide_stats
+// (which keeps its own writer, setAccountHideStats).
+//
+// recruiter_discoverable accepts null on purpose: that is the caller RESETTING
+// the flag to "follow visibility", not an omitted field.
+async function setAccountPrivacy({ githubId, githubLogin, displayName, avatarUrl, fields = {} }, { pool = defaultPool } = {}) {
+  if (!isNumericGithubId(githubId)) return { error: 'no_account' };
+  const setVisibility = 'account_visibility' in fields;
+  const setDiscoverable = 'recruiter_discoverable' in fields;
+  if (!setVisibility && !setDiscoverable) return { error: 'no_fields' };
+  if (setVisibility && !ACCOUNT_VISIBILITY.includes(fields.account_visibility)) {
+    return { error: 'invalid_account_visibility', allowed: ACCOUNT_VISIBILITY };
+  }
+  if (setDiscoverable && fields.recruiter_discoverable !== null
+      && typeof fields.recruiter_discoverable !== 'boolean') {
+    return { error: 'invalid_recruiter_discoverable' };
+  }
+  const { rows } = await pool.query(
+    `INSERT INTO platform_identity_accounts
+       (github_id, github_login, display_name, avatar_url, account_visibility, recruiter_discoverable)
+     VALUES ($1, $2, $3, $4, $5, $6)
+     ON CONFLICT (github_id) DO UPDATE SET
+       account_visibility     = CASE WHEN $7::boolean THEN EXCLUDED.account_visibility
+                                     ELSE platform_identity_accounts.account_visibility END,
+       recruiter_discoverable = CASE WHEN $8::boolean THEN EXCLUDED.recruiter_discoverable
+                                     ELSE platform_identity_accounts.recruiter_discoverable END,
+       updated_at = now()
+     RETURNING github_id, github_login, profile_state, hide_stats,
+               account_visibility, recruiter_discoverable, handle`,
+    [
+      githubId,
+      githubLogin,
+      displayName ?? null,
+      avatarUrl ?? null,
+      setVisibility ? fields.account_visibility : 'public',
+      setDiscoverable ? fields.recruiter_discoverable : null,
+      setVisibility,
+      setDiscoverable,
+    ],
+  );
+  const row = rows[0];
+  // This upsert can CREATE the account row — seed the handle then, same as
+  // upsertAccount / setAccountHideStats.
+  if (row && !row.handle) row.handle = await ensureHandle({ githubId, githubLogin }, { pool });
+  return row;
+}
+
 // -------------------------------------------------------------------------
 // Builder handle (P01, task 1002797 — profile-page spec Decision 3, ADR 0171 D8)
 // -------------------------------------------------------------------------
@@ -1295,6 +1381,10 @@ module.exports = {
   getPublicProfileExtras,
   getOwnProfileExtras,
   setAccountHideStats,
+  // account privacy: visibility + recruiter reach (privacy spec D1)
+  ACCOUNT_VISIBILITY,
+  isRecruiterDiscoverable,
+  setAccountPrivacy,
   // builder handle (P01)
   RESERVED_HANDLES,
   HANDLE_RENAME_WINDOW_MS,

package/modules/platform-identity/routes/profile.js

@@ -3,16 +3,23 @@
 // endpoints behind a live session; both key on req.builder.github_id — never a
 // caller-named id — so a builder can only ever read or flip their own flag.
 //
-//   GET   /me/cross-project — the Settings self view: the hide flag + consent
-//                             state + the builder's own rollup, served regardless
-//                             of flags (getOwnProfileExtras — a hidden builder
+//   GET   /me/cross-project — the Settings self view: the privacy flags (hide,
+//                             visibility, recruiter reach + its one derived
+//                             effective answer) + consent state + the builder's
+//                             own rollup, served regardless of flags
+//                             (getOwnProfileExtras — a hidden builder
 //                             inspects their numbers HERE, not on the public
 //                             route, which stays viewer-independent).
-//   PATCH /me/cross-project — flip hide_stats. Takes effect immediately on every
-//                             public surface (profile cross_project, /people,
-//                             /scouting): enforcement lives in the module's read
-//                             functions (D2) and the hub profile response is
-//                             no-store (D5), so there is no cache to outwait.
+//   PATCH /me/cross-project — the privacy write: hide_stats (ADR 0171 D4) plus
+//                             account_visibility + recruiter_discoverable (task
+//                             1002966, privacy spec D1). hide_stats takes effect
+//                             immediately on every public surface (profile
+//                             cross_project, /people, /scouting): enforcement
+//                             lives in the module's read functions (D2) and the
+//                             hub profile response is no-store (D5), so there is
+//                             no cache to outwait. The other two are STORED here
+//                             and read by the predicates task 1002967 wires into
+//                             the read paths.
 //   PATCH /me/handle        — rename the caller's own handle (P01, task 1002797;
 //                             spec Decision 3). Low rate limit, previous handle
 //                             kept for the 301 window.
@@ -36,13 +43,18 @@ const { pool, requireBuilder, validateOrRespond } = api;
 module.exports = function profileRoutes() {
   const router = express.Router();
 
-  // rank: any-builder — the caller's OWN cross-project record + hide flag (own data).
+  // rank: any-builder — the caller's OWN cross-project record + privacy flags (own data).
   router.get('/me/cross-project', requireBuilder, async (req, res) => {
     try {
       // Core builders include system:* principals whose github_id is not numeric;
       // they have no platform identity — answer the empty shape, not a 500.
       if (!pi.isNumericGithubId(req.builder.github_id)) {
-        return res.json({ hide_stats: false, profile_state: null, handle: null, display_name: null, bio: null, links: null, cross_project: null });
+        return res.json({
+          hide_stats: false, profile_state: null, handle: null, display_name: null,
+          bio: null, links: null, cross_project: null,
+          account_visibility: 'public', recruiter_discoverable: null,
+          recruiter_discoverable_effective: false,
+        });
       }
       const [acct, extras] = await Promise.all([
         pi.getAccount(req.builder.github_id, { pool }),
@@ -50,6 +62,11 @@ module.exports = function profileRoutes() {
       ]);
       res.json({
         hide_stats: !!(acct && acct.hide_stats),
+        // The two privacy flags (task 1002966, spec D1) + the ONE derived answer
+        // the toggle renders, so the client never re-derives the COALESCE.
+        account_visibility: (acct && acct.account_visibility) || 'public',
+        recruiter_discoverable: acct ? (acct.recruiter_discoverable ?? null) : null,
+        recruiter_discoverable_effective: pi.isRecruiterDiscoverable(acct),
         profile_state: acct ? acct.profile_state : null,
         handle: (acct && acct.handle) || null,
         // P02: the account-global profile fields, for the Settings form (P04).
@@ -64,24 +81,58 @@ module.exports = function profileRoutes() {
     }
   });
 
-  // rank: any-builder — flip the caller's OWN hide flag (C2's self-serve opt-out;
-  // own data, keyed on the authenticated github_id).
+  // rank: any-builder — flip the caller's OWN privacy flags (C2's self-serve
+  // opt-out plus the task-1002966 pair; own data, keyed on the authenticated
+  // github_id — a builder can never name another account here). Every field is
+  // optional and at least one is required, so a client sends only what changed;
+  // recruiter_discoverable accepts an explicit null (reset to "follow
+  // visibility"), which is why it is checked with `in` rather than truthiness.
   router.patch('/me/cross-project', requireBuilder, async (req, res) => {
     if (validateOrRespond(req, res, {
-      hide_stats: { required: true, type: 'boolean' },
+      hide_stats: { type: 'boolean' },
+      account_visibility: { type: 'string', enum: pi.ACCOUNT_VISIBILITY },
+      recruiter_discoverable: { type: 'boolean' },
     })) return;
+    const body = req.body || {};
+    const fields = {};
+    for (const k of ['account_visibility', 'recruiter_discoverable']) {
+      if (k in body) fields[k] = body[k];
+    }
+    const setsHide = 'hide_stats' in body;
+    if (!setsHide && !Object.keys(fields).length) {
+      return res.fail('no_fields', { status: 400, message: 'send at least one of hide_stats, account_visibility, recruiter_discoverable' });
+    }
     try {
       if (!pi.isNumericGithubId(req.builder.github_id)) {
         return res.fail('no_platform_identity', 400);
       }
-      const row = await pi.setAccountHideStats({
+      const who = {
         githubId: req.builder.github_id,
         githubLogin: req.builder.github_login,
         displayName: req.builder.display_name,
         avatarUrl: req.builder.avatar_url,
-        hide: req.body.hide_stats,
-      }, { pool });
-      res.json({ hide_stats: !!(row && row.hide_stats) });
+      };
+      let row = null;
+      if (setsHide) row = await pi.setAccountHideStats({ ...who, hide: body.hide_stats }, { pool });
+      if (Object.keys(fields).length) {
+        const out = await pi.setAccountPrivacy({ ...who, fields }, { pool });
+        if (out.error === 'invalid_account_visibility') {
+          return res.fail('invalid_account_visibility', { status: 400, message: `account_visibility is one of ${pi.ACCOUNT_VISIBILITY.join(', ')}` });
+        }
+        if (out.error === 'invalid_recruiter_discoverable') {
+          return res.fail('invalid_recruiter_discoverable', { status: 400, message: 'recruiter_discoverable is true, false, or null (follow visibility)' });
+        }
+        if (out.error) {
+          return res.fail('cross_project_write_failed', { status: 500, message: 'internal error' });
+        }
+        row = out;
+      }
+      res.json({
+        hide_stats: !!(row && row.hide_stats),
+        account_visibility: (row && row.account_visibility) || 'public',
+        recruiter_discoverable: row ? (row.recruiter_discoverable ?? null) : null,
+        recruiter_discoverable_effective: pi.isRecruiterDiscoverable(row),
+      });
     } catch (err) {
       console.error('[platform-identity] PATCH /me/cross-project', err);
       res.fail('cross_project_write_failed', { status: 500, message: 'internal error' });

package/modules/ui-design/kit/lib.js

@@ -235,7 +235,8 @@ function reducedMotionProblems({ running = [], frames = 0 } = {}) {
 
 // ── the states file ───────────────────────────────────────────────────────────
 // { "page": "/projects", "surface"?: "public-landing", "stub"?: { prefix?, child? },
-//   "modeQuery"?: "mode" | false, "ignoreRequests"?: [regex strings], "ignoreConsole"?: [...],
+//   "modes"?: ["dark" | "light", …] (the modes the page renders; default both — a page that pins
+//   one mode declares it here), "modeQuery"?: "mode" | false, "ignoreRequests"?: [regex strings], "ignoreConsole"?: [...],
 //   "ignoreControls"?: [selectors], "states": { name: { url?, auth?, actions?, expect? } },
 //   "reducedMotion"?: { auth?, url?, actions? } }
 function validateStatesFile(json) {
@@ -245,6 +246,7 @@ function validateStatesFile(json) {
   if (json.surface !== undefined && typeof json.surface !== 'string') errors.push('surface: a string (a checkout dir or a module key)');
   errors.push(...validateStub(json.stub, 'stub'));
   if (json.modeQuery !== undefined && json.modeQuery !== false && typeof json.modeQuery !== 'string') errors.push('modeQuery: the query param the page reads for its colour mode (default "mode"), or false');
+  if (json.modes !== undefined && !(Array.isArray(json.modes) && json.modes.length && json.modes.every((m) => MODES.includes(m)))) errors.push('modes: a non-empty array of "dark" | "light" — the modes the page renders (default both); a page that pins one mode declares it here');
   for (const k of ['ignoreRequests', 'ignoreConsole', 'ignoreControls']) if (json[k] !== undefined && !(Array.isArray(json[k]) && json[k].every((s) => typeof s === 'string'))) errors.push(`${k}: an array of strings`);
   const states = json.states;
   if (!states || typeof states !== 'object' || Array.isArray(states) || !Object.keys(states).length) errors.push('states: required — a non-empty object of name → { url?, auth?, actions?, expect? }');

package/modules/ui-design/kit/render.js

@@ -3,9 +3,10 @@
 // render.js — render a page's states and audit every render against the platform
 // floors (task 1003320, ADR 0197). The states live in a JSON file BESIDE the
 // surface (<dir>/<page>.states.json: name → url + actions + expectations); each
-// is rendered in dark + light at 1440x900 / 390x844 / 320x700 through two stubs
-// this file starts itself (signed out, signed in), then a reduced-motion pass per
-// mode. Writes the shots + a JSON report; exits non-zero on any problem.
+// is rendered at 1440x900 / 390x844 / 320x700 in the modes the states file names
+// (`"modes"`; both by default — the apex pins dark, task 1003336; `--modes` overrides)
+// through two stubs this file starts itself (signed out, signed in), then a
+// reduced-motion pass per mode. Writes the shots + a JSON report; exits non-zero on any problem.
 //
 //   node modules/ui-design/kit/render.js --page /projects              (public-landing/projects.states.json)
 //   node modules/ui-design/kit/render.js --page /builders/ranks --surface hall-ui
@@ -65,7 +66,7 @@ async function main() {
   const args = process.argv.slice(2);
   if (lib.hasFlag(args, '--help')) usage('');
   const { file, json, surface } = locate(args);
-  const modes = lib.listArg(args, '--modes', [...lib.MODES]).filter((m) => lib.MODES.includes(m));
+  const modes = lib.listArg(args, '--modes', json.modes || [...lib.MODES]).filter((m) => lib.MODES.includes(m));
   const sizes = lib.listArg(args, '--sizes', Object.keys(lib.SIZES)).map(Number).filter((w) => lib.SIZES[w]);
   const only = lib.listArg(args, '--only', null);
   const names = Object.keys(json.states).filter((n) => !only || only.includes(n));

package/package-lock.json

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

package/package.json

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