@bongos/core 1.25.21 → 1.25.22

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

@@ -478,6 +478,13 @@ body:has(#view-new:not([hidden])) footer.foot{position:relative;z-index:1;backgr
 .acctPick .acctTyped{display:flex;align-items:flex-end;gap:14px;}
 .acctPick .acctTyped .wizField{flex:1;min-width:0;}
 .acctPick .acctTyped .btn{flex:none;margin:0 0 2px;}
+/* start it from a folder (task 1005282): two buttons that wrap at phone width, then
+   the count or each refused file with its reason, one per line */
+.folderPick{max-width:680px;margin-top:18px;padding-top:14px;border-top:1px solid var(--rule);}
+.folderPick .folderBtns{display:flex;flex-wrap:wrap;align-items:center;gap:10px;margin-top:8px;}
+.folderPick .folderProblems{margin:6px 0 0;padding:0;list-style:none;max-height:180px;overflow-y:auto;}
+.folderPick .folderProblems li{margin:4px 0;overflow-wrap:anywhere;}
+.folderPick .folderProblems b{font-weight:600;}
 
 /* the choice (start fresh / adopt): two cells of one band on hairlines, the
    chosen one carrying the dot — the dot is the mark, so the icon leaves */
@@ -1798,6 +1805,23 @@ summary{min-height:24px;padding:3px 0;}
                             </div>
                             <p class="hint" id="raNote" aria-live="polite"></p>
                           </div>
+                          <!-- start it from a folder on this computer (task 1005282): papers,
+                               artwork or scaffolding go into the new private repo as its first
+                               commit. The files stay in this tab until Create; the server checks
+                               them again and refuses before anything is made. -->
+                          <div class="wizField folderPick" id="folderPick">
+                            <span>Start it with your files <small>(optional)</small></span>
+                            <p class="hint">Papers, artwork or a half-built project: choose the folder and everything in it goes into the new repository. Only you and the people you invite can see it.</p>
+                            <div class="folderBtns">
+                              <button type="button" class="btn small ghost" id="folderDirBtn">Choose a folder</button>
+                              <button type="button" class="btn small ghost" id="folderFilesBtn">Choose files</button>
+                              <button type="button" class="btn small ghost" id="folderClear" hidden>Remove</button>
+                              <input type="file" id="folderDir" webkitdirectory multiple hidden aria-hidden="true" tabindex="-1">
+                              <input type="file" id="folderFilesIn" multiple hidden aria-hidden="true" tabindex="-1">
+                            </div>
+                            <p class="hint" id="folderNote" aria-live="polite">Up to 50 MB in all, 25 MB a file. No programs, zipped files or password files.</p>
+                            <ul class="folderProblems hint err" id="folderProblems" hidden></ul>
+                          </div>
                         </div>
                         <div class="row2" id="manualHome">
                           <label class="wizField"><span>GitHub owner <small>(user or org)</small></span>
@@ -2357,6 +2381,9 @@ summary{min-height:24px;padding:3px 0;}
       line.push('. It sleeps when nobody visits and takes about a minute to wake.');
       box.appendChild(appPara(line));
       if (sb.links) box.appendChild(appPara([appLink(sb.links.service, 'Open the sandbox on Render')]));
+      /* the sandbox's safety (task 1005291): what it refused, and the key to lend */
+      if (sb.safety_page) box.appendChild(appPara([appLink(sb.safety_page, 'See what your sandbox refused')]));
+      box.appendChild(appPara(['It has no real keys unless you add them. If you lend one, lend a read-only key: the sandbox refuses sends, payments and changes it can see, but a read-only key is what makes it safe.'], 'finePrint'));
     }
     if (sb.database && sb.database.note) box.appendChild(appPara([String(sb.database.note)], 'finePrint'));
     if (sb.can_add) {
@@ -5703,6 +5730,84 @@ summary{min-height:24px;padding:3px 0;}
     }
     $('ghNewName').addEventListener('input', function () { state.repo = this.value.trim(); updateFreshPreview(); saveDraft(); });
 
+    /* ── start it from a folder (task 1005282) ──
+       A person with papers, artwork or scaffolding and no repository chooses a folder (or
+       files, where the browser has no folder picker — phones) and it becomes the new
+       repo's first commit. The File objects live in this tab only: a draft cannot carry
+       them, so after a reload or a GitHub round-trip the row asks for the folder again.
+       These sizes are a courtesy echo of the server's (src/bongos/folder-upload.js), which
+       checks every file again — type and path included — and refuses before anything is
+       made; its reasons are shown here, one per file. */
+    var FOLDER_MB = 1024 * 1024;
+    var FOLDER_LIMITS = { fileBytes: 25 * FOLDER_MB, totalBytes: 50 * FOLDER_MB, files: 1000 };
+    var FOLDER_SKIP = /(^|\/)(\.ds_store|thumbs\.db|desktop\.ini|ehthumbs\.db)$|(^|\/)(node_modules|__macosx)\//i;
+    var folderFiles = [];        /* [{ path, file }] */
+    var folderProblems = [];     /* [{ path, reason }], ours or the server's */
+    function folderSize(n) { return n >= FOLDER_MB ? (n / FOLDER_MB).toFixed(1) + ' MB' : Math.max(1, Math.round(n / 1024)) + ' KB'; }
+    /* the problems a size alone can show, before anything is sent */
+    function folderLocalProblems(list) {
+      var out = [], total = 0;
+      list.forEach(function (f) {
+        total += f.file.size;
+        if (f.file.size > FOLDER_LIMITS.fileBytes) out.push({ path: f.path, reason: 'Each file can be at most 25 MB.' });
+      });
+      if (list.length > FOLDER_LIMITS.files) out.unshift({ path: '', reason: 'The folder has ' + list.length + ' files; the most a folder can have is ' + FOLDER_LIMITS.files + '.' });
+      if (total > FOLDER_LIMITS.totalBytes) out.unshift({ path: '', reason: 'The folder is ' + folderSize(total) + '; the most a folder can be is 50 MB.' });
+      return out;
+    }
+    function takeFolder(fileList, fromDir) {
+      var list = [], skipped = 0;
+      Array.prototype.forEach.call(fileList || [], function (f) {
+        var p = (fromDir && f.webkitRelativePath) || f.name;
+        /* the chosen folder's own name is not part of the project */
+        if (fromDir && p.indexOf('/') > 0) p = p.slice(p.indexOf('/') + 1);
+        if (FOLDER_SKIP.test(p)) { skipped++; return; }
+        list.push({ path: p, file: f });
+      });
+      folderFiles = list;
+      folderProblems = folderLocalProblems(list);
+      state.fromFolder = list.length > 0;
+      state.folderCount = list.length;
+      state.folderBytes = list.reduce(function (n, f) { return n + f.file.size; }, 0);
+      state.folderSkipped = skipped;
+      state.folderUploaded = false;
+      state.uploadInto = undefined;
+      saveDraft(); paintFolder(); paintCreate();
+    }
+    function paintFolder() {
+      var note = $('folderNote'), ul = $('folderProblems');
+      while (ul.firstChild) ul.removeChild(ul.firstChild);
+      $('folderClear').hidden = !state.fromFolder;
+      ul.hidden = !folderProblems.length;
+      folderProblems.slice(0, 50).forEach(function (pr) {
+        var li = document.createElement('li');
+        if (pr.path) { var b = document.createElement('b'); b.textContent = pr.path; li.appendChild(b); li.appendChild(document.createTextNode(': ')); }
+        li.appendChild(document.createTextNode(pr.reason));
+        ul.appendChild(li);
+      });
+      if (!state.fromFolder) { note.className = 'hint'; note.textContent = 'Up to 50 MB in all, 25 MB a file. No programs, zipped files or password files.'; return; }
+      if (state.folderUploaded) { note.className = 'hint'; note.textContent = 'Your ' + state.folderCount + ' files are in the repository.'; return; }
+      if (!folderFiles.length) { note.className = 'hint err'; note.textContent = 'Choose your folder again: files aren’t kept while you’re away from this page.'; return; }
+      note.className = folderProblems.length ? 'hint err' : 'hint';
+      note.textContent = folderProblems.length
+        ? (folderProblems.length === 1 ? 'One thing to fix before Create:' : folderProblems.length + ' things to fix before Create:')
+        : state.folderCount + (state.folderCount === 1 ? ' file, ' : ' files, ') + folderSize(state.folderBytes) + ', ready to go into the new repository' + (state.folderSkipped ? ' (' + state.folderSkipped + ' system files left out)' : '') + '.';
+    }
+    /* why the folder cannot go in as it stands, or '' */
+    function folderWhy() {
+      if (!state.fromFolder || state.folderUploaded) return '';
+      if (!folderFiles.length) return 'Choose your folder again: files aren’t kept while you’re away from this page.';
+      return folderProblems.length ? 'Some files can’t go in. Fix them below, then create.' : '';
+    }
+    $('folderDirBtn').addEventListener('click', function () { $('folderDir').click(); });
+    $('folderFilesBtn').addEventListener('click', function () { $('folderFilesIn').click(); });
+    $('folderDir').addEventListener('change', function () { takeFolder(this.files, true); this.value = ''; });
+    $('folderFilesIn').addEventListener('change', function () { takeFolder(this.files, false); this.value = ''; });
+    $('folderClear').addEventListener('click', function () { takeFolder([], false); });
+    /* a browser with no folder picker (phones) offers the files one only */
+    if (!('webkitdirectory' in $('folderDir'))) $('folderDirBtn').hidden = true;
+    paintFolder();
+
     /* ── whose GitHub account: mine or an organisation's (task 1004651) ──
        Two pickers share this: the new repo's owner (part 02's Code row) and the app's
        (part 03). The founder's organisations come from GET /github/orgs; GitHub may not
@@ -6590,6 +6695,7 @@ summary{min-height:24px;padding:3px 0;}
            the organisation the founder picked, task 1004651). */
         if (!validRepoName(state.repo)) return homeErr('Name the new repository (letters, numbers, and . _ -).');
         if (state.repoAcct === 'org' && !state.repoOrg) return homeErr('Pick the organisation for the repo, or put it on your own account.');
+        if (folderWhy()) return homeErr(folderWhy());
       } else {
         /* Adopt (picker or manual) and the manual fallback: need a concrete owner + repo. */
         if (!state.owner || !state.repo) {
@@ -6862,7 +6968,8 @@ summary{min-height:24px;padding:3px 0;}
       if (key === 'code') {
         var adopt = state.mode === 'adopt';
         var where = state.owner && state.repo ? 'github.com/' + state.owner + '/' + state.repo : adopt ? 'Pick the repo to adopt.' : '';
-        return { v: adopt ? 'A repo I already have' : 'A new GitHub repo', s: where + (a.project_state === 'existing' ? (where ? ' · ' : '') + 'already started' : '') };
+        var folder = !adopt && state.fromFolder ? ' · with your ' + (state.folderCount || '') + ' files' : '';
+        return { v: adopt ? 'A repo I already have' : 'A new GitHub repo', s: where + folder + (a.project_state === 'existing' ? (where || folder ? ' · ' : '') + 'already started' : '') };
       }
       if (key === 'address') {
         var custom = state.domain && looksLikeDomain(state.domain);
@@ -7002,40 +7109,91 @@ summary{min-height:24px;padding:3px 0;}
       /* the founder's own account sends exactly what it always did; an organisation
          rides as `org`, and the server checks the name again (task 1004651) */
       var repoBody = state.repoAcct === 'org' && state.repoOrg ? { name: state.repo, org: state.repoOrg } : { name: state.repo };
+      /* from a folder (task 1005282): the files ride the same commit moment, and the
+         server refuses the lot, with each file's reason, before the repo exists */
+      if (state.fromFolder) {
+        return folderBody(repoBody).then(function (body) {
+          return fetch(API + '/github/repos/upload', {
+            method: 'POST', credentials: 'same-origin',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body)
+          });
+        }).then(repoMade);
+      }
       return fetch(API + '/github/repos', {
         method: 'POST', credentials: 'same-origin',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(repoBody)
-      }).then(function (res) {
-        return res.json().catch(function () { return {}; }).then(function (data) {
-          if (res.status === 401 || res.status === 403) {
-            /* the token went between the probe and Create: the hop fetches it again and
-               brings the founder back to this screen; if it cannot, the manual fields */
-            var hopped = hopForRepoAccess();
-            if (!hopped) { repoAccess = 'unavailable'; syncHome(); }
-            var e0 = new Error('reconnect'); e0.gotoHome = !hopped;
-            e0.homeMsg = 'We couldn’t create the repo on GitHub just now — enter one you made yourself below.';
-            throw e0;
-          }
-          if (!res.ok) {
-            var e = new Error((data.error && (data.error.message || data.error.code)) || ('HTTP ' + res.status));
-            e.data = data;
-            if (data.error && data.error.code === 'name_taken') { e.gotoHome = true; e.homeMsg = data.error.message; }
-            /* the organisation said no: its reason, where the owner is chosen */
-            if (data.error && /^(org_app_restricted|org_forbidden|org_not_found|bad_org)$/.test(data.error.code || '')) { e.gotoHome = true; e.homeMsg = data.error.message; }
-            throw e;
-          }
-          var full = data.repo && data.repo.full_name;
-          if (full && full.indexOf('/') > 0) {
-            state.owner = full.slice(0, full.indexOf('/'));
-            state.repo = full.slice(full.indexOf('/') + 1);
+      }).then(repoMade);
+    }
+    /* the upload's body: every file as base64, or a retry into the repo a failed push left */
+    function readBase64(file) {
+      return new Promise(function (resolve, reject) {
+        var r = new FileReader();
+        r.onload = function () { var u = String(r.result || ''); resolve(u.slice(u.indexOf(',') + 1)); };
+        r.onerror = function () { reject(r.error || new Error('read failed')); };
+        r.readAsDataURL(file);
+      });
+    }
+    function folderBody(repoBody) {
+      var why = folderWhy();
+      if (why) { var e0 = new Error(why); e0.gotoHome = true; e0.homeMsg = why; return Promise.reject(e0); }
+      return Promise.all(folderFiles.map(function (f) {
+        return readBase64(f.file).then(function (data) { return { path: f.path, data: data }; });
+      })).then(function (files) {
+        return state.uploadInto ? { into: state.uploadInto, files: files } : { name: repoBody.name, org: repoBody.org, files: files };
+      }, function () {
+        var e1 = new Error('read'); e1.gotoHome = true;
+        e1.homeMsg = 'A file couldn’t be read from your computer. Choose the folder again.';
+        throw e1;
+      });
+    }
+    function repoMade(res) {
+      return res.json().catch(function () { return {}; }).then(function (data) {
+        if (res.status === 401 || res.status === 403) {
+          /* the token went between the probe and Create: the hop fetches it again and
+             brings the founder back to this screen; if it cannot, the manual fields */
+          var hopped = hopForRepoAccess();
+          if (!hopped) { repoAccess = 'unavailable'; syncHome(); }
+          var e0 = new Error('reconnect'); e0.gotoHome = !hopped;
+          e0.homeMsg = 'We couldn’t create the repo on GitHub just now — enter one you made yourself below.';
+          throw e0;
+        }
+        if (res.status === 413) {
+          var big = new Error('too big'); big.gotoHome = true;
+          big.homeMsg = 'The folder is bigger than 50 MB, so nothing was created. Choose a smaller folder.';
+          throw big;
+        }
+        if (!res.ok) {
+          var e = new Error((data.error && (data.error.message || data.error.code)) || ('HTTP ' + res.status));
+          e.data = data;
+          var code = (data.error && data.error.code) || '';
+          if (code === 'name_taken') { e.gotoHome = true; e.homeMsg = data.error.message; }
+          /* the organisation said no: its reason, where the owner is chosen */
+          if (/^(org_app_restricted|org_forbidden|org_not_found|bad_org)$/.test(code)) { e.gotoHome = true; e.homeMsg = data.error.message; }
+          /* the folder was refused before anything was made: each file and its reason */
+          if (/^upload_/.test(code)) {
+            var det = data.error.details || {};
+            if (Array.isArray(det.problems)) folderProblems = det.problems.map(function (pr) { return { path: String(pr.path || ''), reason: String(pr.reason || '') }; });
+            /* the repo was made but the files did not reach it: the retry fills that one */
+            if (code === 'upload_failed' && det.repo && det.repo.full_name) state.uploadInto = det.repo.full_name;
+            if (code === 'upload_retry_refused') state.uploadInto = undefined;
+            saveDraft(); paintFolder();
+            e.gotoHome = true; e.homeMsg = data.error.message;
           }
-          /* Keep GitHub's own html_url so the done panel can link the repo it made
-             (task 1002855). It rides saveDraft(), so a resumed draft keeps the link. */
-          var made = data.repo && data.repo.html_url;
-          if (typeof made === 'string' && made.indexOf('https://github.com/') === 0) state.repoUrl = made;
-          state.repoAutoCreated = true; saveDraft();
-        });
+          throw e;
+        }
+        var full = data.repo && data.repo.full_name;
+        if (full && full.indexOf('/') > 0) {
+          state.owner = full.slice(0, full.indexOf('/'));
+          state.repo = full.slice(full.indexOf('/') + 1);
+        }
+        /* Keep GitHub's own html_url so the done panel can link the repo it made
+           (task 1002855). It rides saveDraft(), so a resumed draft keeps the link. */
+        var made = data.repo && data.repo.html_url;
+        if (typeof made === 'string' && made.indexOf('https://github.com/') === 0) state.repoUrl = made;
+        if (data.uploaded) { state.folderUploaded = true; state.uploadInto = undefined; folderFiles = []; paintFolder(); }
+        state.repoAutoCreated = true; saveDraft();
       });
     }
 
@@ -7103,7 +7261,9 @@ summary{min-height:24px;padding:3px 0;}
                existing history instead of pushing a fresh tree, which a repo that already
                has commits rejects as unrelated history. state.mode already tracked
                greenfield|adopt for the UI — it has to reach the server too. */
-            onboard_mode: state.mode === 'adopt' ? 'adopt' : 'greenfield',
+            /* a repo made from a folder already has commits, so the scaffold LAYERS onto
+               it (and never overwrites a file) instead of pushing a fresh tree (task 1005282) */
+            onboard_mode: state.mode === 'adopt' || state.folderUploaded ? 'adopt' : 'greenfield',
             /* the page filled itself in from the guide's plan (task 1005274): the hub
                carries the scope answers and the hand-off file into the new project */
             from_guide: state.fromGuide ? true : undefined,

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.21",
+  "version": "1.25.22",
   "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",
@@ -14,6 +14,7 @@
     "./bongos/api-path-404": "./src/bongos/api-path-404.js",
     "./module-loader/loader": "./src/module-loader/loader.js",
     "./modules": "./src/modules.js",
+    "./sandbox": "./src/sandbox/index.js",
     "./module-seams": "./src/module-seams.js"
   },
   "engines": {

package/release-notes.json

@@ -11886,5 +11886,19 @@
       "id": "1005290",
       "text": "Finished work now reaches a project's test copy first; the owner sees what is waiting and presses promote to put it on the live site, and every promotion is recorded."
     }
+  ],
+  "1.25.22": [
+    {
+      "id": "1005282",
+      "text": "People can now start a project by uploading a folder from their computer: papers, artwork or a half-built project. Bongos makes the private repository and puts the files in it, so nobody has to learn git. Uploads over 50 MB, f"
+    },
+    {
+      "id": "1005291",
+      "text": "A project's sandbox is now clearly marked on every page, starts with no real keys, and if real keys are lent it can only read: anything that would send, charge or change a record for real is refused and listed for the owner."
+    },
+    {
+      "id": "1005129",
+      "text": "Choosing how contributors are rewarded now shows, for every option, what the platform really requires and what is closed — and the project now remembers where it is and where its builders are, so those notes fit it."
+    }
   ]
 }

package/scripts/bongos/genesis.js

@@ -12,6 +12,9 @@
 // Usage:
 //   npx bongos genesis show [stage]                       every stage, or one, with its answers
 //   npx bongos genesis document <stage>                   the stage's document (task 1005115): what it left behind, editable any time
+//   npx bongos genesis facts                              what the project has said about itself (task 1005129)
+//   npx bongos genesis facts set <key> <value> | --clear  change one (reward_intents: a,b; minors_on_board: true|false)
+//   npx bongos genesis options                            each reward option: what the server enforces, and the facts beside it
 //   npx bongos genesis context                            what the founder said, as markdown (for planning sessions)
 //   npx bongos genesis assist <stage>                     the brief for the founder's AI session (the assisted door)
 //   npx bongos genesis answer <stage> <question> "<words>" [--origin founder|assisted]
@@ -29,7 +32,7 @@
 const fs = require('node:fs');
 const { apiCall, requireSession, errCode, cliExit } = require('./cli-lib');
 
-const USAGE = 'usage: npx bongos genesis show [stage] | context | document <stage> | assist <stage> | answer <stage> <question> "<words>" [--origin founder|assisted] | answer <stage> <question> --not-sure|--skip ["why"] | clear <stage> <question> | history <stage> <question> | door <stage> guided|open|assisted | page <stage> "<words>"|--file <path>|--remove | link <stage> <url>|--remove';
+const USAGE = 'usage: npx bongos genesis show [stage] | context | facts [set <key> <value>|--clear] | options | document <stage> | assist <stage> | answer <stage> <question> "<words>" [--origin founder|assisted] | answer <stage> <question> --not-sure|--skip ["why"] | clear <stage> <question> | history <stage> <question> | door <stage> guided|open|assisted | page <stage> "<words>"|--file <path>|--remove | link <stage> <url>|--remove';
 
 const STATE_LABEL = { answered: '', not_sure: '[not sure yet] ', skipped: '[skipped] ' };
 const ORIGIN_LABEL = { assisted: ' (with AI help)', carried_over: ' (carried over — confirm or edit)' };
@@ -82,6 +85,15 @@ function formatAdvice(a) {
   return out;
 }
 
+// Pure: a fact's value from the command line. --clear un-answers it.
+function parseFactValue(key, words) {
+  const w = words.join(' ').trim();
+  if (w === '--clear') return null;
+  if (key === 'minors_on_board') return w === 'true' ? true : w === 'false' ? false : w;
+  if (key === 'reward_intents') return w.split(',').map((s) => s.trim()).filter(Boolean);
+  return w;
+}
+
 // Pure: parse `answer` arguments into the PUT body, or { error }.
 function parseAnswer(rest) {
   const args = [...rest];
@@ -140,6 +152,30 @@ async function main(argv) {
     console.log(d.markdown || 'The founder has not written anything in genesis yet.');
     return 0;
   }
+  if (cmd === 'facts' && !stage) {
+    const d = await call('GET', '/founding/facts', null, 'read the project facts');
+    if (!d) return 1;
+    for (const f of d.facts) console.log(`${f.label}: ${f.answered ? (Array.isArray(f.value) ? f.value.join(', ') : String(f.value)) + (f.origin === 'carried_over' ? ' (from project creation)' : '') : 'not answered'}`);
+    return 0;
+  }
+  if (cmd === 'facts' && stage === 'set') {
+    const [key, ...val] = rest;
+    if (!key || !val.length) { console.error(USAGE); return 2; }
+    const d = await call('PUT', '/founding/facts', { facts: { [key]: parseFactValue(key, val) } }, 'save the fact');
+    if (!d) return 1;
+    console.log('Saved.');
+    for (const c of d.changed) {
+      for (const n of c.new_notes) console.log(`  ${c.label}: now — ${n}`);
+      for (const n of c.gone_notes) console.log(`  ${c.label}: no longer — ${n}`);
+    }
+    return 0;
+  }
+  if (cmd === 'options') {
+    const d = await call('GET', '/founding/legalize/options', null, 'read the reward options');
+    if (!d) return 1;
+    console.log(d.markdown);
+    return 0;
+  }
   if (!stage) { console.error(USAGE); return 2; }
   if (cmd === 'document') {
     const d = await call('GET', `/founding/work/${enc(stage)}/document`, null, 'read the document');
@@ -214,4 +250,4 @@ if (require.main === module) {
     .catch((err) => { console.error('fatal:', err && err.message ? err.message : err); cliExit(1); });
 }
 
-module.exports = { main, formatStage, parseAnswer };
+module.exports = { main, formatStage, parseAnswer, parseFactValue };

package/scripts/bongos/init.js

@@ -545,6 +545,19 @@ function buildReadme(branding = {}) {
     '',
     'Requires Node >= 22 and Postgres installed locally (macOS/Linux; on Windows use WSL). If anything looks off, `bongos doctor` checks your setup and prints the fix.',
     '',
+    // The project's sandbox (task 1005291, ADR 0406 §5): the one line that makes the app
+    // behave safely when it runs as its sandbox copy, and nothing at all on the live site.
+    "## Your app's sandbox",
+    '',
+    "If your app runs on Render, Bongos also runs a free sandbox copy of it that takes every finished change first. Put this at the top of a Node app so the sandbox only reads from payment, email and messaging providers, and shows a \"Sandbox\" band on every page:",
+    '',
+    '```js',
+    "const sandbox = require('@bongos/core/sandbox').install(); // does nothing on the live site",
+    'app.use(sandbox.middleware); // Express-style apps: the band, and /__bongos/sandbox',
+    '```',
+    '',
+    'Seed test data when `BONGOS_SANDBOX=1`, and give the sandbox test keys. If you lend a real key, lend a read-only one.',
+    '',
     '## Where to look next',
     '',
     '- `CLAUDE.md` — how this project is built (the operating manual agents read first).',

package/scripts/bongos/package-core.js

@@ -330,6 +330,8 @@ function buildPackageJson({ version, sourceDeps, sourceOverrides }) {
       './bongos/api-path-404': './src/bongos/api-path-404.js',
       './module-loader/loader': './src/module-loader/loader.js',
       './modules': './src/modules.js',
+      // A project's app loads this to behave as its sandbox (task 1005291, ADR 0406 §5).
+      './sandbox': './src/sandbox/index.js',
       './module-seams': './src/module-seams.js',
     },
     engines: { node: '>=22' },

package/scripts/bongos/provision-render-sandbox.js

@@ -112,10 +112,14 @@ async function standupSandbox(api, inst, host, deps) {
     let svc = sb.serviceId ? await api.getService(sb.serviceId).catch(() => null) : null;
     if (!svc) svc = await api.findServiceByName(name);
     if (!svc) {
+      // The sandbox page's key (task 1005291): kept on the row, which only the owner's
+      // project page reads, and set on the sandbox, which checks it.
+      const pageToken = require('node:crypto').randomBytes(24).toString('hex');
       const created = await api.createService(payload.sandboxServicePayload(inst, {
         ownerId: api.ownerId, repoUrl: `https://github.com/${repo.owner}/${repo.name}`, region, build,
-        dbUrl: dbStage.state === 'ready' ? dbStage.url : null,
+        dbUrl: dbStage.state === 'ready' ? dbStage.url : null, pageToken,
       }));
+      await recordSandbox(db, inst.id, { pageKey: pageToken });
       svc = created.service;
       log(`  [render] created sandbox service ${svc.id} (free, follows main)`);
     }

package/scripts/bongos/render-payload.js

@@ -87,11 +87,14 @@ function renderServicePayload(inst, { ownerId, repoUrl, branch, webPlan, region,
 // with BONGOS_SANDBOX=1 so the app (and the starter's outbound gate, task 1005291) knows
 // it is not the live site. `dbUrl` is the sandbox's OWN database, never the live one.
 const SANDBOX_SUFFIX = 'sandbox';
-function sandboxServicePayload(inst, { ownerId, repoUrl, region, build, dbUrl }) {
+// `pageToken` is the sandbox's own page key: its /__bongos/sandbox shows what was refused
+// and which real keys are lent only to a visitor who carries it (the owner, via their
+// owner-only project page). Not a credential to anything else (task 1005291).
+function sandboxServicePayload(inst, { ownerId, repoUrl, region, build, dbUrl, pageToken }) {
   const p = renderServicePayload(inst, { ownerId, repoUrl, branch: 'main', webPlan: 'free', region, build, dbUrl });
   p.name = resourceName(inst, SANDBOX_SUFFIX);
   p.autoDeploy = 'yes';
-  p.envVars = [{ key: 'BONGOS_SANDBOX', value: '1' }, ...p.envVars];
+  p.envVars = [{ key: 'BONGOS_SANDBOX', value: '1' }, ...(pageToken ? [{ key: 'BONGOS_SANDBOX_PAGE_KEY', value: pageToken }] : []), ...p.envVars];
   return p;
 }