@bongos/core 1.18.3 → 1.18.19

package/modules/sessions/pollers/session-reward-reconcile.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// modules/sessions/pollers/session-reward-reconcile.js — the loader poller entry
+// for the STATE-BASED session-token-reward safety net (ADR 0120).
+//
+// The deferred cost-plus session reward books via two LIVE triggers only: the
+// upload-time gate and the in-process `task.shipped` listener. Both miss a task
+// that reaches status='shipped' OUT OF BAND — a direct-SQL / hotpatch flip, or a
+// ship in another process — leaving that session's drachmae stranded forever even
+// though the code landed. This poller periodically calls
+// db.reconcileUnbookedSessionRewards(), which books the reward for any already-
+// shipped session that has no session.token_reward row yet. It is the sessions-
+// domain twin of the publish-reconciler poller (the same loader inversion), and
+// mirrors the task 1679 achievements reconcile (reconcile from durable STATE, not
+// the event). Idempotent — a re-sweep never double-pays.
+//
+// Deliberately independent of any GitHub push credential (unlike the confirmed→
+// shipped publish-reconciler): this sweep touches no git and its whole purpose is
+// to run on a credential-less box and recover already-shipped-but-unbooked work.
+
+const db = require('../db');
+
+// Sweep cadence. A safety net, not a hot path — the live triggers do the real-time
+// work; this only catches out-of-band ships, so a relaxed interval is fine.
+const INTERVAL_MS = Number(process.env.SESSION_REWARD_RECONCILE_MS) || 10 * 60_000;
+const FIRST_SWEEP_DELAY_MS = Number(process.env.SESSION_REWARD_RECONCILE_FIRST_MS) || 90_000;
+
+let intervalTimer = null;
+let firstTimer = null;
+
+async function runSweep() {
+  const res = await db.reconcileUnbookedSessionRewards({ limit: 200 });
+  if (res && res.awarded > 0) {
+    console.log(
+      `[session-reward-reconcile] booked ${res.awarded} stranded session reward(s) (scanned ${res.scanned})`
+    );
+  }
+  return res;
+}
+
+// Start the periodic sweep. Idempotent (a second call is a no-op). Kill-switched by
+// SESSION_REWARD_RECONCILE_DISABLED=1. Timers are unref'd so they never hold the
+// process open on a systemd restart (the publish-reconciler / discord-bot precedent).
+function start() {
+  if (process.env.SESSION_REWARD_RECONCILE_DISABLED === '1') {
+    console.log('[session-reward-reconcile] disabled (SESSION_REWARD_RECONCILE_DISABLED=1)');
+    return;
+  }
+  if (intervalTimer) return; // already started
+
+  const tick = () => {
+    runSweep().catch((e) =>
+      console.error(`[session-reward-reconcile] sweep crashed: ${e && e.message ? e.message : e}`)
+    );
+  };
+
+  firstTimer = setTimeout(tick, FIRST_SWEEP_DELAY_MS);
+  if (firstTimer.unref) firstTimer.unref();
+  intervalTimer = setInterval(tick, INTERVAL_MS);
+  if (intervalTimer.unref) intervalTimer.unref();
+
+  console.log(
+    `[session-reward-reconcile] started — recovering out-of-band-ship rewards every ${Math.round(INTERVAL_MS / 1000)}s`
+  );
+}
+
+function stop() {
+  if (firstTimer) {
+    clearTimeout(firstTimer);
+    firstTimer = null;
+  }
+  if (intervalTimer) {
+    clearInterval(intervalTimer);
+    intervalTimer = null;
+  }
+}
+
+module.exports = { start, stop, runSweep, INTERVAL_MS };

package/modules/sessions/routes/sessions.js

@@ -133,7 +133,40 @@ function recordSessionRead(req, { route, targetBuilderId, target }) {
   });
 }
 
+// The module's kernel seam wiring, registered when this factory runs (the loader
+// runs it at boot, already gated to enabled instances — the discord precedent).
+// This is the LAND-side half of ADR 0120 "pay on land": core emits `task.shipped`
+// on EVERY land path (publish-reconciler + routes/tasks) with the shipped task
+// row; we react by booking the cost-plus SESSION token reward for any session
+// that shipped that task and DEFERRED its reward at upload time (the ci/async
+// order, where the digest upload precedes the land). The upload-side gate in
+// db.upsertSessionRecordWithReward covers the sync/laptop order; both call the
+// SAME idempotent award, so re-firing is a safe per-session_id no-op.
+//
+// sessions registers no PORT (provides: []) — this is an EVENT listener, not a
+// port, so module.json is unchanged. off→on guarded so a test re-instantiating
+// the router never stacks duplicate listeners (the discord listener precedent).
+let _shipRewardListenerOff = null;
+function registerSeams() {
+  if (_shipRewardListenerOff) _shipRewardListenerOff();
+  _shipRewardListenerOff = api.on('task.shipped', (task) => {
+    const id = task && task.id;
+    if (id == null) return;
+    // Best-effort: awardDeferredSessionRewardForTask is async, so a rejection
+    // (e.g. a transient DB error) surfaces as a rejected promise — .catch keeps
+    // it from escaping the listener. This matters because the dominant ci/async
+    // land path emits SYNCHRONOUSLY (publish-reconciler's emit()), which is
+    // fire-and-forget and would otherwise turn a throw here into an
+    // unhandledRejection. A missed reward is re-attempted idempotently on the
+    // next land/upload, so a best-effort miss never double-pays or loses money.
+    db.awardDeferredSessionRewardForTask(id).catch((e) =>
+      console.error('[sessions] deferred session-reward on task.shipped (non-blocking):',
+        e && e.message ? e.message : e));
+  });
+}
+
 module.exports = function buildSessionsRouter() {
+  registerSeams();
   const router = express.Router();
   const uploadJson = express.json({ limit: UPLOAD_BODY_LIMIT });
 

package/package-lock.json

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

package/package.json

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

package/public-landing/create.html

@@ -82,11 +82,6 @@ body{
 .exit-wizard kbd{font-family:var(--font-mono);font-size:10px;line-height:1;background:rgba(42,31,23,0.08);border-radius:4px;padding:2px 5px;color:var(--ink-faint);}
 .who{display:flex;align-items:center;gap:10px;font-size:14px;font-weight:600;color:var(--ink-soft);min-height:34px;}
 .who img{width:30px;height:30px;border-radius:50%;border:2px solid #fff;box-shadow:0 2px 8px rgba(42,31,23,0.12);}
-.who a{color:var(--accent-deep);text-decoration:none;font-weight:700;}
-.who a:hover{text-decoration:underline;}
-/* switch to a different GitHub account from inside the wizard (task 2098) */
-.who .switch-acct{font-size:12px;font-weight:600;color:var(--ink-faint);padding-left:10px;margin-left:2px;border-left:1px solid rgba(42,31,23,0.16);}
-.who .switch-acct:hover{color:var(--accent-deep);}
 
 /* ── layout ── */
 .wrap{
@@ -202,10 +197,6 @@ input[type=text].bad{border-color:var(--err);}
 .ghbtn:hover{background:#1b1f24;transform:translateY(-1px);}
 .ghbtn:active{transform:translateY(0) scale(.98);}
 .ghbtn .gh{width:18px;height:18px;fill:currentColor;}
-.ghcreate{display:none;margin-bottom:18px;}
-.ghcreate.on{display:block;}
-.ghcreate-note{font-size:13px;font-weight:500;color:var(--ink-faint);line-height:1.5;margin-top:9px;max-width:52ch;}
-.ghcreate-note strong{color:var(--ink-soft);}
 .steps .ghbtn{font-size:14px;padding:9px 16px;margin-top:10px;}
 
 /* buttons */
@@ -380,7 +371,11 @@ input[type=text].bad{border-color:var(--err);}
     <section class="panel" id="panel-gate" aria-labelledby="gate-h">
       <h1 id="gate-h">Create a project</h1>
       <p class="lede">Your own <strong data-brand-product-inline>Cloud Bongos</strong> project: its own repository, its own home on the web, and a hall of AI builders who do the building. You set the direction; agents lay down the code. Sign in with GitHub so the project belongs to <em>you</em> from the very first beat.</p>
-      <a class="btn big" id="signin" href="/api/bongos/auth/web/start?return=/create">
+      <!-- The wizard's own sign-in opts into repo scope (read:user + public_repo) up
+           front (&repos=1) — anyone here intends to create a project, which needs repo
+           access, so we ask once at sign-in instead of a second "Connect" step at Home.
+           Hall + CLI sign-in stay identity-only (ADR 0143 least-privilege default). -->
+      <a class="btn big" id="signin" href="/api/bongos/auth/web/start?return=/create&amp;repos=1">
         <svg class="gh" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>
         Sign in with GitHub
       </a>
@@ -430,7 +425,7 @@ input[type=text].bad{border-color:var(--err);}
              to the manual owner/repo inputs below (#manualHome), which stay authoritative. -->
         <div id="ghConnect" class="reassure">
           <p id="ghConnectMsg">&nbsp;</p>
-          <button type="button" class="btn" id="ghConnectBtn">Connect GitHub</button>
+          <button type="button" class="btn" id="ghConnectBtn">Allow repo access</button>
           <button type="button" class="linklike" id="ghManualToggle">or enter it manually</button>
         </div>
         <div id="ghBusy" class="hint" hidden>Reading your GitHub repositories…</div>
@@ -454,13 +449,6 @@ input[type=text].bad{border-color:var(--err);}
             <input type="text" id="f-repo" placeholder="mercury" autocomplete="off" maxlength="120">
           </label>
         </div>
-        <div class="ghcreate" id="ghCreate">
-          <a class="ghbtn" id="ghCreateBtn" href="https://github.com/new" target="_blank" rel="noopener">
-            <svg class="gh" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>
-            Create this repo on GitHub
-          </a>
-          <p class="ghcreate-note">Opens GitHub with the name already filled in — just click <strong>Create repository</strong> and leave it empty, then come back and press Next. Already made it? Just press Next.</p>
-        </div>
         <div class="hint" id="h-home">&nbsp;</div>
         <div class="nav">
           <button type="button" class="btn ghost" data-back="1">← Back</button>
@@ -607,10 +595,6 @@ input[type=text].bad{border-color:var(--err);}
     if (owner) u.searchParams.set('owner', owner);
     return u.toString();
   }
-  function updateGhCreateHref() {
-    var a = $('ghCreateBtn');
-    if (a) a.href = githubNewRepoUrl(state.owner, state.repo);
-  }
   function esc(s) {
     return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) {
       return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
@@ -664,7 +648,6 @@ input[type=text].bad{border-color:var(--err);}
     if (!state.repoTouched) {
       state.repo = deriveRepo(state.name);
       $('f-repo').value = state.repo;
-      updateGhCreateHref();
     }
     var h = $('h-name');
     if (state.slug) { h.innerHTML = 'its handle on the platform: <code>' + esc(state.slug) + '</code>'; h.className = 'hint'; }
@@ -678,10 +661,6 @@ input[type=text].bad{border-color:var(--err);}
     $('c-green').setAttribute('aria-pressed', String(mode === 'greenfield'));
     $('c-adopt').setAttribute('aria-pressed', String(mode === 'adopt'));
     $('adoptNote').classList.toggle('on', mode === 'adopt');
-    // The "create the repo on GitHub" button only makes sense when starting fresh —
-    // an adopted repo already exists.
-    $('ghCreate').classList.toggle('on', mode === 'greenfield');
-    updateGhCreateHref();
     saveDraft();
     syncHome();
   }
@@ -692,7 +671,7 @@ input[type=text].bad{border-color:var(--err);}
   /* ── GitHub-integrated repo picker (adopt) + auto-create (fresh) — task 1002099 / ADR 0143.
         Progressive enhancement: probe GET /github/repos once we reach step 2.
           200 → we hold repo access → show the picker (adopt) / name field (fresh);
-          403 → offer "Connect GitHub" (a ?repos=1 re-sign-in);
+          403 → offer to grant repo access (a ?repos=1 re-sign-in);
           503 (server can't store the token) or any error → the manual inputs.
         #manualHome (the classic owner/repo fields) is the always-safe fallback. ── */
   var repoAccess = null;   // null=unknown/loading · true · 'need-connect' · 'unavailable' · 'manual'
@@ -722,10 +701,10 @@ input[type=text].bad{border-color:var(--err);}
     $('manualHome').hidden = !isManualHome();
     if (need) {
       $('ghConnectMsg').textContent = adopt
-        ? 'Connect your GitHub account and pick the repository to adopt.'
-        : 'Connect your GitHub account and we’ll create the empty repo for you.';
+        ? 'You’re signed in — creating your project needs one more GitHub permission. Allow repo access to pick the repository to adopt.'
+        : 'You’re signed in — creating your project needs one more GitHub permission. Allow repo access and we’ll create the empty repo for you.';
     }
-    if (ok && adopt) renderRepoList();
+    if (ok && adopt) initAdoptPicker();
     if (ok && !adopt) syncFresh();
   }
 
@@ -749,25 +728,57 @@ input[type=text].bad{border-color:var(--err);}
   }
   $('ghNewName').addEventListener('input', function () { state.repo = this.value.trim(); updateFreshPreview(); saveDraft(); });
 
+  // The adopt picker behaves like a standard combobox (owner design review, task
+  // 1002247): the dropdown is open only while the visitor is choosing. Selecting a
+  // repo fills the search box with its full_name and collapses the list; focusing or
+  // typing reopens it.
+  function openRepoList() { $('ghList').hidden = false; renderRepoList(); }
+  function closeRepoList() { $('ghList').hidden = true; }
   function renderRepoList() {
     var q = ($('ghSearch').value || '').trim().toLowerCase();
-    var rows = repoList.filter(function (r) { return !q || String(r.full_name).toLowerCase().indexOf(q) >= 0; }).slice(0, 100);
     var sel = state.owner && state.repo ? (state.owner + '/' + state.repo) : '';
+    // When the box just shows the current selection verbatim, list everything (so the
+    // visitor can switch) instead of filtering down to the one selected repo.
+    var effectiveQ = q === sel.toLowerCase() ? '' : q;
+    var rows = repoList.filter(function (r) { return !effectiveQ || String(r.full_name).toLowerCase().indexOf(effectiveQ) >= 0; }).slice(0, 100);
     $('ghList').innerHTML = rows.length
       ? rows.map(function (r) {
           return '<button type="button" class="ghrow" role="option" data-full="' + esc(r.full_name) + '" aria-selected="' + (r.full_name === sel) + '">' +
             '<span>' + esc(r.full_name) + '</span>' + (r.private ? '<span class="priv">Private</span>' : '') + '</button>';
         }).join('')
-      : '<div class="hint" style="padding:10px 12px">No repositories match “' + esc(q) + '”.</div>';
+      : '<div class="hint" style="padding:10px 12px">No repositories match “' + esc(effectiveQ) + '”.</div>';
+  }
+  // Fill the search box with the current selection (if any) and collapse the list;
+  // with nothing chosen yet, open it so the visitor sees their repos right away.
+  function initAdoptPicker() {
+    var sel = state.owner && state.repo ? state.owner + '/' + state.repo : '';
+    // Only treat it as a confirmed pick if it's actually one of the visitor's repos.
+    // owner/repo are auto-derived from the project name, so a bare derived value must
+    // NOT masquerade as a chosen repo — that would collapse the list onto a repo that
+    // may not even exist.
+    var picked = sel && repoList.some(function (r) { return String(r.full_name).toLowerCase() === sel.toLowerCase(); });
+    var h = $('ghAdoptHint');
+    if (picked) {
+      $('ghSearch').value = sel;
+      h.className = 'hint ok'; h.innerHTML = 'Adopting <strong>' + esc(sel) + '</strong>.';
+      closeRepoList();
+    } else {
+      $('ghSearch').value = '';
+      h.className = 'hint'; h.innerHTML = '&nbsp;';
+      openRepoList();
+    }
   }
-  $('ghSearch').addEventListener('input', renderRepoList);
+  $('ghSearch').addEventListener('focus', function () { this.select(); openRepoList(); });
+  $('ghSearch').addEventListener('input', openRepoList);
   $('ghList').addEventListener('click', function (ev) {
     var row = ev.target.closest('.ghrow'); if (!row) return;
     var full = row.getAttribute('data-full'); var slash = full.indexOf('/');
     state.owner = full.slice(0, slash); state.repo = full.slice(slash + 1);
+    state.ownerTouched = true; state.repoTouched = true;   // a real pick — don't let name-derive clobber it
     saveDraft();
-    Array.prototype.forEach.call($('ghList').querySelectorAll('.ghrow'), function (b) { b.setAttribute('aria-selected', String(b === row)); });
+    $('ghSearch').value = full;                       // pull the choice into the search box …
     var h = $('ghAdoptHint'); h.className = 'hint ok'; h.innerHTML = 'Adopting <strong>' + esc(full) + '</strong>.';
+    closeRepoList();                                  // … and collapse the dropdown (typical UX)
   });
 
   function ensureRepoAccess() {
@@ -785,8 +796,8 @@ input[type=text].bad{border-color:var(--err);}
       .then(syncHome);
   }
 
-  $('f-owner').addEventListener('input', function () { state.owner = this.value.trim(); state.ownerTouched = true; updateGhCreateHref(); saveDraft(); });
-  $('f-repo').addEventListener('input', function () { state.repo = this.value.trim(); state.repoTouched = true; updateGhCreateHref(); saveDraft(); });
+  $('f-owner').addEventListener('input', function () { state.owner = this.value.trim(); state.ownerTouched = true; saveDraft(); });
+  $('f-repo').addEventListener('input', function () { state.repo = this.value.trim(); state.repoTouched = true; saveDraft(); });
 
   $('f-slug').addEventListener('input', function () {
     state.slugTouched = true;
@@ -815,7 +826,7 @@ input[type=text].bad{border-color:var(--err);}
     }
     if (step === 2) {
       var homeErr = function (msg) { $('h-home').textContent = msg; $('h-home').className = 'hint err'; return false; };
-      if (repoAccess === 'need-connect') return homeErr('Connect GitHub to pick or create your repository — or choose “enter it manually”.');
+      if (repoAccess === 'need-connect') return homeErr('Allow GitHub repo access to pick or create your repository — or choose “enter it manually”.');
       if (repoAccess === true && state.mode !== 'adopt') {
         // Fresh with access: just the new repo NAME (owner is the signed-in account).
         if (!validRepoName(state.repo)) return homeErr('Name the new repository (letters, numbers, and . _ -).');
@@ -1114,31 +1125,14 @@ input[type=text].bad{border-color:var(--err);}
     if (e.key === 'Escape') { e.preventDefault(); exitWizard(); }
   });
 
-  /* ── switch GitHub account from inside the wizard (task 2098) ── you are not
-     locked to the account you entered with: sign out of the Cloud Bongos session,
-     then restart GitHub sign-in so the wizard reloads under whichever account you
-     pick. (To land on a *different* GitHub account, switch accounts on GitHub's
-     side; this un-locks our session so the next sign-in is honored.) */
-  function switchAccount(e) {
-    if (e) e.preventDefault();
-    var back = API + '/auth/web/start?return=/create';
-    fetch(API + '/auth/logout', { method: 'POST', credentials: 'same-origin' })
-      .then(function () { window.location.assign(back); })
-      .catch(function () { window.location.assign(back); });
-  }
-
   /* ── boot: who am I? ── (task 2094: the wizard shows the signed-in identity
         ONLY — never a link into cloud bongos's own builders hall. A project
-        creator enters a hall from their own project's landing, not from here.
-        task 2098: + a "switch account" action so you're not locked in.) ── */
+        creator enters a hall from their own project's landing, not from here.) ── */
   function renderWho() {
     var w = $('who');
     if (me) {
       w.innerHTML = (me.avatar_url ? '<img src="' + esc(me.avatar_url) + '" alt="">' : '') +
-        '<span>' + esc(me.github_login || 'signed in') + '</span>' +
-        '<a href="#" class="switch-acct" id="switchAcct">switch account</a>';
-      var sw = $('switchAcct');
-      if (sw) sw.addEventListener('click', switchAccount);
+        '<span>' + esc(me.github_login || 'signed in') + '</span>';
     } else {
       w.innerHTML = '';
     }
@@ -1154,7 +1148,6 @@ input[type=text].bad{border-color:var(--err);}
       if (!state.ownerTouched && !state.owner && me && me.github_login) {
         state.owner = me.github_login;
         $('f-owner').value = state.owner;
-        updateGhCreateHref();
         saveDraft();
       }
       // returning after a create? resume watching that instance instead of a blank wizard

package/public-landing/gate/README.md

@@ -0,0 +1,137 @@
+# Cloud Bongos — landing gate (interactive)
+
+`index.html` is the Cloud Bongos landing experience — a small state machine over one
+self-contained page (`space.css` + `space.js` for the space side; the download scene + its
+drag physics live in the inline `<script>`), built from **drawn ATLA-style sprites**
+(`sprites/*.png` — a `> cloud bongos` terminal, an enter key, a search bar, and download tiles)
+refracting the backdrop through SVG displacement maps.
+
+## The flow (tasks 1721, 1722)
+
+Four body-class views: `view-entry` → `view-space` → `view-download` / `view-detail`.
+
+1. **Entry — type `bongos`, in space** (`#entry`, `view-entry`). Every visit lands here: the
+   `> cloud ▊` terminal floating in the **space sky** (deep-blue → sunrise gradient, drifting
+   clouds), *not* the temple world. Typing `bongos` is the ritual on every visit; the enter key
+   lights, and pressing enter flashes through into the circles. Driven by `space.js`
+   (`entryKey` / `enterSite`), reusing the terminal + enter CSS.
+2. **Space — the circles** (`#space` / `#space-canvas`, `view-space`). A pannable, zoomable sky
+   of project orbs, sized by number of builders, moving as a **living gravity cluster** — every
+   orb attracts every other by its mass (∝ size³), so the field swirls, bodies sling past one
+   another, and a small orb is sometimes briefly caught circling a big one like a moon (task
+   1733; see "The gravity" below). Project data is **inlined** in `space.js` (`PROJECTS`) — Caddy
+   404s `*.json` on staging — so swap in a real registry by changing `PROJECTS` + `layout()`.
+   - **Drag** empty sky to pan · **scroll** to zoom (toward the cursor).
+   - **Hover** an orb for an info card; **click** it to dive in.
+   - **Space bar** opens a search scoped to the orbs **currently in view** (client-side match
+     over name/tagline/tags now; the Claude-backed answer is a dormant seam, `aiAnswer()`, per
+     the "interaction now, AI wired next" decision).
+   - **Click empty sky** drops a new project circle.
+3. **Download — Cloud Bongos' install page** (`#land` in `.stage`, `view-download`). Clicking the
+   Cloud Bongos orb zooms **straight** into the search + download-tiles scene over the
+   temple-world backdrop — **no type-`bongos` gate in between** (that already happened at entry).
+   `space.js` fires `cb:show-download`; the inline script reveals `#land` and runs its drag.
+4. **Detail — other projects** (`#detail`, `view-detail`). Clicking any non-self orb opens a
+   themed "full story — coming soon" page with a link out to its live site.
+
+**ESC** rises from the download or detail page back to the circles (`space.js` → `cb:hide-download`).
+
+## The download scene's elastic-tether drag (task 1534)
+
+Every download sprite (search bar, tiles, wordmark) is draggable. Grab one and it resists like
+it's anchored; pull past the threshold and it snaps free, hovers, then drifts slowly home and
+re-docks, carrying a faint idle bob at rest. The physics is scoped to `.stage`, so it never
+grabs the entry terminal (which `space.js` owns). **This scene is separate from the space
+gravity below — the download interaction is unchanged by task 1733.**
+
+## The space gravity — a living n-body cluster (task 1733)
+
+The project orbs on the **space** view (`view-space`) are a real gravitational simulation, all
+in `space.js`. Each orb is a body with **mass ∝ size³** (more builders → bigger → heavier →
+pulls harder), so the sky behaves like planets, suns and the occasional fleeting moon rather
+than a fixed scatter. Under the hood:
+
+- **Softened Newtonian gravity**, every pair, so a close pass *slings* instead of blowing up
+  (no singularities).
+- A **fixed-timestep leapfrog integrator** (`physStep`) for accurate, energy-stable motion; the
+  frame loop (`tick` → `render`) interpolates between steps for smoothness.
+- **Soft collisions** so discs bounce rather than overlap; a **soft containment well** plus a
+  **band thermostat** keep the swirl bounded and lively *forever* — energy is free to ebb and
+  flow inside a band, and only a runaway collapse or blow-up gets a gentle nudge back.
+- Net drift is removed each step, so the cluster stays centred on screen (and stays put when a
+  visitor adds a new orb, which is flung into the swirl).
+
+Verified stable over a 60-minute headless simulation (no NaN, never off-screen, never
+interpenetrating). It replaced the earlier "drift around fixed anchors" motion.
+
+### Tuning the gravity
+
+All knobs live in the `GRAV` block near the top of `space.js`:
+
+| You want…                            | Edit (in `GRAV`)                                  |
+|--------------------------------------|---------------------------------------------------|
+| Livelier / faster swirl              | `SWIRL` ↑ (or `THERMO_LO` ↑)                       |
+| Calmer, slower motion                | `SWIRL` ↓ / `THERMO_LO` ↓                          |
+| Tighter cluster (less panning)       | `CONTAIN_R` ↓                                      |
+| Stronger pull between orbs           | `G` ↑                                              |
+| Fewer hard slingshots on near-misses | `SOFTEN` ↑                                         |
+| Bouncier contacts (→ elastic)        | `REST` → 1                                         |
+| Sharper size→mass contrast           | lower `R_REF`, or raise the `massFor` exponent     |
+
+Turn it off (freeze the orbs): comment out `initOrbits()` in `layout()` and the
+`requestAnimationFrame(tick)` at the bottom of the IIFE — pan, zoom, hover, dive, search and the
+table all keep working.
+
+> **Live:** password-locked at **staging.cloudbongos.com** (the future landing page, parked
+> for review). Setup + the password live in [`docs/recipes/cloudbongos-staging-gate.md`](../../../docs/recipes/cloudbongos-staging-gate.md).
+> Branding (logo coin / wordmark / mascot / code-glyphs) is still being finished and is
+> intentionally untouched here.
+
+## Preview it locally
+
+The page links to art one folder up (`../world/assets/…`), so it must be served from the
+**`brand/cloud-bongos/`** folder — not from `gate/` itself, or those paths break.
+
+**Easiest (Claude Code preview):** start the `gate-preview` server in `.claude/launch.json`,
+then open `http://127.0.0.1:8137/gate/index.html`.
+
+**From a terminal** (repo root): `python3 -m http.server --directory brand/cloud-bongos 8137`,
+then open <http://127.0.0.1:8137/gate/index.html>.
+
+Use a Chromium browser (Chrome/Edge) — the live-glass refraction relies on `backdrop-filter`
+with an SVG displacement map. Safari ignores the displacement and falls back to a plain
+frost, which still looks fine.
+
+## Tuning the drag
+
+All behaviour is in the single `<script>` at the bottom of `index.html`, which opens with a
+commented **TUNING** block. Common tweaks:
+
+| You want…                                | Edit (in the TUNING block)        |
+|------------------------------------------|-----------------------------------|
+| Harder / easier to pull a pane free      | `THRESHOLD` — ↑ harder, ↓ easier  |
+| How far a tap can move before it's a drag | `DEADZONE` — px                   |
+| Freed panes wait longer before returning | `HOVER` — milliseconds            |
+| Slower, more drifty return               | `DRIFT_MAXV` — ↓ slower           |
+| Wider, more wandering return path        | `WMAG` ↑ and/or `TURN` ↓          |
+| More / less idle "breathing"             | `BOB_X`, `BOB_Y` (px) — `0` = off |
+
+### Which elements are draggable
+
+The drag targets **`.mark`** (the wordmark) + every **`.el`** sprite pane (terminal, enter,
+search, tiles). To add one, give it the `el` class (or push it into the `els` array); to
+exclude one, filter it out of `els`.
+
+### Why it does not fight the other animations
+
+The drag only ever applies `transform: translate(…)` to each pane, and it owns that property
+exclusively — so the float/reveal animations were replaced by the drag's own idle bob, and
+the enter key's reveal uses opacity + blur only (no transform). The **scene** transforms
+(the dive's scale/translate) live on the parent `.gate`/`.land` containers, so they compose
+with the per-pane drag instead of clobbering it. When a scene settles, `measure()` re-runs
+so a freshly-revealed pane drags from the right home.
+
+### Turn the drag off
+
+Delete the second `<script>` IIFE (the drag) — the type→dive interaction and all the art
+keep working untouched.