@bongos/core 1.21.70 → 1.21.72

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

@@ -167,9 +167,9 @@
     { "name": "the review (tasks 1004504, 1004550): Edit opens a row in place, Done confirms it, and Continue is the one confirmation for the rest", "auth": true, "width": 1440, "url": "/projects?view=new",
       "steps": [["wait",600],["click","#termsAck"],["wait",100],["click","#wizStart"],["wait",400],["fill","#newName","Mercury"],["click","#typeCards .tpill[data-type=\"game\"]"],["click","#panel-what button[type=submit]"],["wait",400],["select","#physCountry","US"],["wait",100],["click","[data-phys=\"builder_geography\"][data-val=\"global\"]"],["click","[data-phys=\"minors_on_board\"][data-val=\"false\"]"],["click","[data-phys=\"entity\"][data-val=\"intent-solo\"]"],["click","#physNext"],["wait",700],["click","#reviewRows .setRow[data-row=\"team\"] [data-row-chg]"],["wait",200],["click","[data-phys-solo=\"many\"]"],["wait",600],["click","#reviewRows .setRow[data-row=\"team\"] [data-row-chg]"],["wait",200]],
       "expect": {"visible":["#panel-review","#reviewRows .setRow[data-row=\"rewards\"]","#reviewRows .setRow.done[data-row=\"team\"]"]} },
-    { "name": "the wizard driver (tasks 1003346 and 1004504): the fork, what, the checks, every review row confirmed (the stub grants repo access, so the new repository is named from the project; the dotless stub host takes a domain the founder owns), the look, then the filing — the done panel with the standup strip and the human steps", "auth": true, "width": 1440, "url": "/projects?view=new",
+    { "name": "the wizard driver (tasks 1003346 and 1004504): the fork, what, the checks, every review row confirmed (the stub grants repo access, so the new repository is named from the project; the dotless stub host takes a domain the founder owns), the look, then the filing — the done panel waits with the cloud hop and its status line (task 1004578), the strip and the locked checklist standing down", "auth": true, "width": 1440, "url": "/projects?view=new",
       "steps": [["wait",600],["click","#termsAck"],["wait",100],["click","#wizStart"],["wait",400],["fill","#newName","Mercury"],["click","#typeCards .tpill[data-type=\"game\"]"],["click","#panel-what button[type=submit]"],["wait",400],["select","#physCountry","US"],["wait",100],["click","[data-phys=\"builder_geography\"][data-val=\"global\"]"],["click","[data-phys=\"minors_on_board\"][data-val=\"false\"]"],["click","[data-phys=\"entity\"][data-val=\"intent-solo\"]"],["click","#physNext"],["wait",700],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["fill","#f-slug","mercury"],["wait",900],["fill","#f-domain","mercury.example.com"],["wait",200],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["click","#reviewGo"],["wait",500],["click","#doCreate"],["wait",1500]],
-      "expect": {"visible":["#panel-done","#liveProgress .prog","#liveProgress .prog .stages li.now","#humanSteps li"],"hidden":["#panel-look","#panel-review"],"text":[["#done-h","Setting up Mercury"]]} },
+      "expect": {"visible":["#panel-done","#hop","#hopCanvas","#hopStatus","#hopJump"],"hidden":["#panel-look","#panel-review","#liveProgress","#humanSteps"],"text":[["#done-h","Setting up Mercury"],["#hopStatus","Raising the server, database, and address — nothing needed from you."]]} },
     { "name": "the front door at 390: the fork's two doors stack inside one pill", "auth": true, "width": 390, "url": "/projects?view=new",
       "steps": [["wait",600],["click","#termsAck"],["wait",100]],
       "expect": {"visible":["#panel-fork",".doorPill","#wizDemo","#wizStart"]} },

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

@@ -57,7 +57,7 @@
     "in-new-review-run": {"auth":true,"url":"/projects?view=new","actions":[["wait",600],["click","#termsAck"],["wait",100],["click","#wizStart"],["wait",400],["fill","#newName","Mercury"],["click","#typeCards .tpill[data-type=\"game\"]"],["fill","#f-desc","A co-op farming game where the seasons never repeat."],["click","#panel-what button[type=submit]"],["wait",400],["select","#physCountry","US"],["wait",100],["click","[data-phys=\"builder_geography\"][data-val=\"global\"]"],["click","[data-phys=\"minors_on_board\"][data-val=\"false\"]"],["click","[data-phys=\"entity\"][data-val=\"intent-solo\"]"],["click","#physNext"],["wait",700],["click","#reviewRows .setRow[data-row=\"run\"] [data-row-chg]"],["wait",300],["click","[data-phys=\"framing\"][data-val=\"hybrid\"]"],["wait",600]],"expect":{"visible":["#physSuite"]}},
     "in-new-review-confirmed": {"auth":true,"url":"/projects?view=new","actions":[["wait",600],["click","#termsAck"],["wait",100],["click","#wizStart"],["wait",400],["fill","#newName","Mercury"],["click","#typeCards .tpill[data-type=\"game\"]"],["fill","#f-desc","A co-op farming game where the seasons never repeat."],["click","#panel-what button[type=submit]"],["wait",400],["select","#physCountry","US"],["wait",100],["click","[data-phys=\"builder_geography\"][data-val=\"global\"]"],["click","[data-phys=\"minors_on_board\"][data-val=\"false\"]"],["click","[data-phys=\"entity\"][data-val=\"intent-solo\"]"],["click","#physNext"],["wait",700],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["fill","#f-slug","mercury"],["wait",900],["fill","#f-domain","mercury.example.com"],["wait",200],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200]],"expect":{"visible":["#reviewGo","#reviewRows .setRow.done"],"text":[["#reviewGo","Looks right, continue"]]}},
     "in-new-look": {"auth":true,"url":"/projects?view=new","actions":[["wait",600],["click","#termsAck"],["wait",100],["click","#wizStart"],["wait",400],["fill","#newName","Mercury"],["click","#typeCards .tpill[data-type=\"game\"]"],["fill","#f-desc","A co-op farming game where the seasons never repeat."],["click","#panel-what button[type=submit]"],["wait",400],["select","#physCountry","US"],["wait",100],["click","[data-phys=\"builder_geography\"][data-val=\"global\"]"],["click","[data-phys=\"minors_on_board\"][data-val=\"false\"]"],["click","[data-phys=\"entity\"][data-val=\"intent-solo\"]"],["click","#physNext"],["wait",700],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["fill","#f-slug","mercury"],["wait",900],["fill","#f-domain","mercury.example.com"],["wait",200],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["click","#reviewGo"],["wait",500]],"expect":{"visible":["#panel-look","#wizLook","#wizRecap","#doCreate"],"hidden":["#panel-review"],"attr":[["#wizRoom","data-screen","look"]]}},
-    "in-new-done": {"auth":true,"url":"/projects?view=new","actions":[["wait",600],["click","#termsAck"],["wait",100],["click","#wizStart"],["wait",400],["fill","#newName","Mercury"],["click","#typeCards .tpill[data-type=\"game\"]"],["fill","#f-desc","A co-op farming game where the seasons never repeat."],["click","#panel-what button[type=submit]"],["wait",400],["select","#physCountry","US"],["wait",100],["click","[data-phys=\"builder_geography\"][data-val=\"global\"]"],["click","[data-phys=\"minors_on_board\"][data-val=\"false\"]"],["click","[data-phys=\"entity\"][data-val=\"intent-solo\"]"],["click","#physNext"],["wait",700],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["fill","#f-slug","mercury"],["wait",900],["fill","#f-domain","mercury.example.com"],["wait",200],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["click","#reviewGo"],["wait",500],["click","#doCreate"],["wait",1500]],"expect":{"visible":["#panel-done","#liveProgress .prog","#humanSteps li","#wizInviteLater"],"hidden":["#panel-look","#qWrap","#wizBack","#wizInvite"]}},
+    "in-new-done": {"auth":true,"url":"/projects?view=new","actions":[["wait",600],["click","#termsAck"],["wait",100],["click","#wizStart"],["wait",400],["fill","#newName","Mercury"],["click","#typeCards .tpill[data-type=\"game\"]"],["fill","#f-desc","A co-op farming game where the seasons never repeat."],["click","#panel-what button[type=submit]"],["wait",400],["select","#physCountry","US"],["wait",100],["click","[data-phys=\"builder_geography\"][data-val=\"global\"]"],["click","[data-phys=\"minors_on_board\"][data-val=\"false\"]"],["click","[data-phys=\"entity\"][data-val=\"intent-solo\"]"],["click","#physNext"],["wait",700],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["fill","#f-slug","mercury"],["wait",900],["fill","#f-domain","mercury.example.com"],["wait",200],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["click","#reviewGo"],["wait",500],["click","#doCreate"],["wait",1500]],"expect":{"visible":["#panel-done","#hop","#hopCanvas","#hopStatus","#hopJump"],"hidden":["#panel-look","#qWrap","#wizBack","#wizInvite","#liveProgress","#humanSteps","#wizInviteLater","#stepPager"]}},
     "in-new-resume-offer": {"auth":true,"url":"/projects?view=new","actions":[["wait",600],["click","#termsAck"],["wait",100],["click","#wizStart"],["wait",400],["fill","#newName","Mercury"],["click","#typeCards .tpill[data-type=\"game\"]"],["fill","#f-desc","A co-op farming game where the seasons never repeat."],["click","#panel-what button[type=submit]"],["wait",400],["select","#physCountry","US"],["wait",100],["click","[data-phys=\"builder_geography\"][data-val=\"global\"]"],["click","[data-phys=\"minors_on_board\"][data-val=\"false\"]"],["click","[data-phys=\"entity\"][data-val=\"intent-solo\"]"],["click","#physNext"],["wait",700],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["fill","#f-slug","mercury"],["wait",900],["fill","#f-domain","mercury.example.com"],["wait",200],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["click","#reviewGo"],["wait",500],["click","#doCreate"],["wait",1500],["click","#projTrig"],["wait",350],["click","#menuProjects [data-nav=\"new\"]"],["wait",500]],"expect":{"visible":["#panel-fork","#wizResume","#wizResumeGo"],"hidden":["#panel-done"],"text":[["#wizResumeName","Mercury"]]}},
     "in-new-look-custom": {"auth":true,"url":"/projects?view=new","actions":[["wait",600],["click","#termsAck"],["wait",100],["click","#wizStart"],["wait",400],["fill","#newName","Mercury"],["click","#typeCards .tpill[data-type=\"game\"]"],["fill","#f-desc","A co-op farming game where the seasons never repeat."],["click","#panel-what button[type=submit]"],["wait",400],["select","#physCountry","US"],["wait",100],["click","[data-phys=\"builder_geography\"][data-val=\"global\"]"],["click","[data-phys=\"minors_on_board\"][data-val=\"false\"]"],["click","[data-phys=\"entity\"][data-val=\"intent-solo\"]"],["click","#physNext"],["wait",700],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["fill","#f-slug","mercury"],["wait",900],["fill","#f-domain","mercury.example.com"],["wait",200],["click","#reviewRows .setRow[data-row=\"address\"] [data-row-chg]"],["wait",200],["click","#reviewGo"],["wait",500],["click","#wizLook-custom"],["wait",200]],"expect":{"visible":["#panel-look","#wizAccent","#wizAccentNote"],"hidden":["#panel-review"]}},
     "out-new": {"auth":false,"url":"/projects?view=new","expect":{"visible":["#panel-gate","#wizSignin"],"hidden":["#qWrap","#panel-fork"]}},

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.70",
+  "version": "1.21.72",
   "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/release-notes.json

@@ -9199,5 +9199,48 @@
     {
       "text": "Reporting a problem with Bongos now works from every project, including ones like Will's that could not send feedback before. It takes a second, needs no extra sign-in, and the Bongos team can see who really sent each report."
     }
+  ],
+  "1.21.71": [
+    {
+      "id": "1004595",
+      "text": "A hosted project's Software update page no longer stops at \"Update ready\". When the people who run its server do the upgrade, the owner now sees who that is and an \"Ask for this upgrade\" button; one press reaches the Cloud Bon"
+    },
+    {
+      "id": "1004621",
+      "text": "The assistant in a Bongos project no longer starts every session with a failed command. Its instructions now say `npx bongos …`, which works as soon as the project is installed, instead of a bare `bongos` that the computer cou"
+    },
+    {
+      "id": "1004586",
+      "text": "The goal-planning assistant can now finish a goal that was started in the hall: it works out the goal's scope, its 'done when' checks and its first tasks, then releases the goal's work."
+    },
+    {
+      "id": "1004622",
+      "text": "Fixed a broken test that was stopping every new Bongos release from being published."
+    },
+    {
+      "id": "1004596",
+      "text": "When someone on a hosted project (like Will's) asks to upgrade from their own computer, Bongos now tells them plainly that the project's operator does upgrades, and how to ask for one — from the Software update page or with on"
+    },
+    {
+      "id": "1004619",
+      "text": "Bongos now has a written plan for red and blue security teams: attacks happen on a separate practice server, never on the live site, and every release gets checked there."
+    },
+    {
+      "id": "1004597",
+      "text": "Recording routine Bongos upkeep, such as a core upgrade, no longer gets refused just because none of a project's goals fit. Filed as upkeep with no goal, it now goes into the version's standing maintenance goal. Any other task"
+    },
+    {
+      "id": "1004585",
+      "text": "A goal created from the hall now arrives with a 'Spec goal N' task. Nothing else in that goal can be picked up until someone finishes it, so a goal never sits half-defined."
+    },
+    {
+      "text": "Hosted projects like Will's now get a working Update button in Settings, instead of being told to run a command on a server they don't have access to."
+    }
+  ],
+  "1.21.72": [
+    {
+      "id": "1004578",
+      "text": "While a new project is being set up, founders now get a little cloud-hopping game: each cloud is a public project on the platform, in its own planet colour. When the project goes live, clouds and stars fill the screen and fade"
+    }
   ]
 }

package/scripts/gds/claude-materialize.js

@@ -33,7 +33,7 @@ const { spawnSync } = require('node:child_process');
 const { VERBS } = require('../../bin/bongos.js'); // side-effect-free require (guarded main)
 const ic = require('../../src/instance-config'); // neutral configDir/envPrefix fallbacks (never a founder literal)
 const { isCorePackageName, CORE_PACKAGE_NAMES } = require('../../src/module-loader/catalog'); // one definition of "this checkout IS the core"
-const { renderInstanceClaudeMd } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
+const { renderInstanceClaudeMd, refreshStarterCliLines } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
 
 // script basename (e.g. "ship.js") → dedicated bongos verb, for verbs that map to a bare script with
 // NO prefixArgs. Verbs whose script is driven by prefixArgs (box → api.js) are EXCLUDED so a generic
@@ -61,16 +61,40 @@ const GDS_INVOCATION_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJ
 // A non-gds core script under scripts/ (rare in skills, but keep the transform total).
 const OTHER_SCRIPT_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!gds\/)[a-zA-Z0-9_./-]+\.js)"?`, 'g');
 
-// Pure: rewrite core-script invocations in a skill/settings command string to the bongos bin.
-// Idempotent (a string with no matching invocation is returned unchanged).
+// How a project runs the CLI (task 1004621). The `bongos` bin ships inside the @bongos/core
+// dependency (node_modules/.bin/bongos), which is NOT on PATH, so a bare `bongos ship` written
+// into a project's skills failed with `command not found` on every session's first call and the
+// assistant had to recover by retrying through npx. `npx` finds the project's own bin right after
+// `npm install`, with no setup, on every OS and shell — so that is the spelling a project reads.
+const PROJECT_CLI = 'npx bongos';
+
+// A hand-written bare `bongos <verb>` in skill prose (e.g. "`bongos paste-token <token>`"), so it
+// takes the npx spelling too. Case-sensitive on purpose ("Bongos status" is a product noun), only a
+// KNOWN verb, and never when already prefixed by `npx ` or glued to a path/name (`@bongos/core`,
+// `bongos-feedback`, `bongos: command not found` all stay). The `npx ` lookbehind is what keeps a
+// second run from writing `npx npx bongos`.
+function bareVerbRe(verbs) {
+  const names = Object.keys(verbs || {}).filter((v) => /^[a-z][a-z-]*$/.test(v));
+  if (!names.length) return null;
+  names.sort((a, b) => b.length - a.length); // `paste-token` before a shorter prefix of it
+  return new RegExp(String.raw`(?<![\w@/.\-])(?<!npx )bongos (${names.join('|')})(?![\w-])`, 'g');
+}
+
+// Pure: rewrite core-script invocations in a skill/settings command string to the project's CLI
+// spelling (`npx bongos <verb>`, else `npx bongos exec scripts/gds/<x>.js`), and give any bare
+// `bongos <verb>` the same npx prefix. Idempotent: its own output contains neither a
+// `node scripts/…` invocation nor an un-prefixed `bongos <verb>`, so a second run changes nothing.
 function bongosify(text, verbs = VERBS) {
   const map = scriptToVerb(verbs);
-  return String(text == null ? '' : text)
+  const bare = bareVerbRe(verbs);
+  let out = String(text == null ? '' : text);
+  if (bare) out = out.replace(bare, (_whole, verb) => `${PROJECT_CLI} ${verb}`);
+  return out
     .replace(GDS_INVOCATION_RE, (_whole, script) => {
       const verb = map[`${script}.js`];
-      return verb ? `bongos ${verb}` : `bongos exec scripts/gds/${script}.js`;
+      return verb ? `${PROJECT_CLI} ${verb}` : `${PROJECT_CLI} exec scripts/gds/${script}.js`;
     })
-    .replace(OTHER_SCRIPT_RE, (_whole, rel) => `bongos exec scripts/${rel}`);
+    .replace(OTHER_SCRIPT_RE, (_whole, rel) => `${PROJECT_CLI} exec scripts/${rel}`);
 }
 
 // ---- instance rebrand (task 2103) -----------------------------------------
@@ -340,34 +364,38 @@ function copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true
 // path and is the agent's escape hatch, so allow-listing it would be a blanket
 // grant wearing a narrow rule's clothes. The one script the core's own list
 // blesses (`api.js`) is named in full instead.
+//
+// EVERY RULE IS THE `npx bongos` SPELLING (task 1004621): a project has no bare
+// `bongos` on PATH, so its skills, its CLAUDE.md and Settings → CLI access
+// (task 1004575) all say `npx bongos …`, and a bare-`bongos` rule would allow a
+// command nothing runs. An instance that took the older bare starter gains the
+// npx twin of each bare rule it still holds on its next upgrade
+// (topUpNpxAllowTwins below).
 const STARTER_COMMANDS = [
-  'bongos claim:*',
-  'bongos ship:*',
-  'bongos release:*',
-  'bongos reauth:*',
-  'bongos paste-token:*',
-  // What Settings → CLI access hands out since task 1004575: a clone has no
-  // bare `bongos` on PATH, so the copied command runs through npx.
+  'npx bongos claim:*',
+  'npx bongos ship:*',
+  'npx bongos release:*',
+  'npx bongos reauth:*',
   'npx bongos paste-token:*',
-  'bongos exec scripts/gds/api.js:*',
+  'npx bongos exec scripts/gds/api.js:*',
   // The read-only subset (task 1003992, ADR 0304). `git branch` and `git fetch`
   // are exact forms on purpose: a flag turns either into a write or an exec. No
   // `git diff|log|show` rule, also on purpose: the harness already runs their
   // read-only forms unprompted, and a prefix rule would switch off its flag check
   // (`--output=<file>` writes anywhere, `diff --no-index` reads any file).
   // tests/cli_allowlist_permissions.mjs pins this list to the core's, rule for rule.
-  'bongos start:*',
-  'bongos status:*',
-  'bongos recall:*',
-  'bongos exec scripts/gds/me.js:*',
-  'bongos doctor:*',
-  'bongos exec scripts/gds/preflight.js:*',
-  'bongos exec scripts/gds/skill-preflight.js:*',
-  'bongos exec scripts/gds/ship-check.js:*',
-  'bongos exec scripts/gds/fitness.js:*',
-  'bongos exec scripts/gds/strand-watch.js:*',
-  'bongos exec scripts/gds/stale-worktrees.js:*',
-  'bongos exec scripts/gds/read-session-export.js:*',
+  'npx bongos start:*',
+  'npx bongos status:*',
+  'npx bongos recall:*',
+  'npx bongos exec scripts/gds/me.js:*',
+  'npx bongos doctor:*',
+  'npx bongos exec scripts/gds/preflight.js:*',
+  'npx bongos exec scripts/gds/skill-preflight.js:*',
+  'npx bongos exec scripts/gds/ship-check.js:*',
+  'npx bongos exec scripts/gds/fitness.js:*',
+  'npx bongos exec scripts/gds/strand-watch.js:*',
+  'npx bongos exec scripts/gds/stale-worktrees.js:*',
+  'npx bongos exec scripts/gds/read-session-export.js:*',
   'git status:*',
   'git branch --list',
   'git branch --show-current',
@@ -473,6 +501,37 @@ function topUpStarterDeny(existingText, wanted) {
   return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
 }
 
+// topUpNpxAllowTwins — the `npx bongos` twin of every bare-`bongos` allow rule an instance's OWN
+// settings.json holds (task 1004621). The skills an upgrade lands now say `npx bongos ship`, and a
+// `Bash(bongos ship:*)` rule does not match that, so without the twin the upgrade would trade a
+// `command not found` for a permission prompt on every blessed command. This is NOT the shell-rule
+// top-up task 1004158 ruled out: nothing new is offered. Each twin is a rule the owner already
+// holds, respelled for the one launcher that reaches the same project-local bin — a rule they
+// removed gets no twin, and nothing they wrote is removed or rewritten. Same { text, added, reason }
+// contract as topUpStarterDeny; an unreadable shape is left alone and reported.
+const BARE_BONGOS_RULE_RE = /^(\w+)\(bongos (.+)\)$/;
+function topUpNpxAllowTwins(existingText) {
+  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const cannotCheck = (reason) => ({ text: null, added: [], reason });
+  let doc;
+  try { doc = JSON.parse(existingText); } catch (err) { return cannotCheck(`not valid JSON (${err.message})`); }
+  if (!isObject(doc)) return cannotCheck('its top level is not a JSON object');
+  const perms = doc.permissions === undefined ? {} : doc.permissions;
+  if (!isObject(perms)) return cannotCheck('its "permissions" is not an object');
+  const allow = perms.allow === undefined ? [] : perms.allow;
+  if (!Array.isArray(allow)) return cannotCheck('its "permissions.allow" is not an array');
+  const have = new Set(allow);
+  const added = [];
+  for (const rule of allow) {
+    const m = typeof rule === 'string' && rule.match(BARE_BONGOS_RULE_RE);
+    const twin = m && `${m[1]}(${PROJECT_CLI} ${m[2]})`;
+    if (twin && !have.has(twin)) { have.add(twin); added.push(twin); }
+  }
+  if (!added.length) return { text: null, added: [], reason: null };
+  const next = { ...doc, permissions: { ...perms, allow: [...allow, ...added] } };
+  return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
+}
+
 // The starter an instance gets when the core root carries no settings.json — a
 // package-only install. Permissions ONLY: no hooks (they are topology), no env.
 function renderStarterSettings(branding = {}) {
@@ -778,9 +837,26 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
       // The read is guarded: existsSync passing does not mean readable (a directory at that path,
       // a locked or root-owned file), and this runs AFTER the pin moved and the migrations ran, so
       // a throw here would leave a half-applied upgrade. It fails soft, like its sibling above.
+      // The npx twins of the owner's own bare-`bongos` allow rules ride the same single read and
+      // write (task 1004621): applied first, so the deny top-up below works on — and writes — the
+      // text that already carries them. An unparseable file trips both the same way and is
+      // reported once, by the deny half.
       let topUp;
-      try { topUp = topUpStarterDeny(fs.readFileSync(settingsDest, 'utf8'), credentialDeny(toBranding)); }
-      catch (err) { topUp = { text: null, added: [], reason: `it could not be read (${err.code || err.message})` }; }
+      let twins = { text: null, added: [], reason: null };
+      try {
+        const raw = fs.readFileSync(settingsDest, 'utf8');
+        twins = topUpNpxAllowTwins(raw);
+        topUp = topUpStarterDeny(twins.text || raw, credentialDeny(toBranding));
+      } catch (err) { topUp = { text: null, added: [], reason: `it could not be read (${err.code || err.message})` }; }
+      if (twins.added.length) {
+        summary.settingsAllowTwinsAdded = twins.added;
+        summary.notes.push(`.claude/settings.json kept every rule it already had and GAINED the \`npx bongos\` twin of ${twins.added.length} bare-\`bongos\` allow rule(s) it held — the skills now say \`npx bongos …\`, which a bare rule does not match: ${twins.added.join(', ')}`);
+        log(`  ${dryRun ? '[dry-run] would add' : '✓ added'} the npx twin of ${twins.added.length} bare-bongos allow rule(s) to .claude/settings.json (skills now run \`npx bongos …\`; every rule you wrote is kept): ${twins.added.join(', ')}`);
+        if (!topUp.text && !topUp.reason) {
+          if (!dryRun) fs.writeFileSync(settingsDest, twins.text);
+          if (!dryRun) addWritten('.claude/settings.json'); // real run only — the same reasoning as the deny write below
+        }
+      }
       if (topUp.text) {
         if (!dryRun) fs.writeFileSync(settingsDest, topUp.text);
         // Reported as written only on the REAL run, deliberately. writtenPaths doubles as the set
@@ -803,7 +879,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
         summary.settingsDenyUncheckable = topUp.reason;
         summary.notes.push(`.claude/settings.json could not be checked for missing deny rules — ${topUp.reason}. It was left exactly as it is, so if it predates task 1003966 its local agent can still read keys and session tokens; compare its permissions.deny against the starter by hand, or fix the file and upgrade again.`);
         log(`  ! .claude/settings.json could NOT be checked for missing deny rules — ${topUp.reason}. Left untouched; its deny half may still be missing.`);
-      } else {
+      } else if (!twins.added.length) {
         summary.skippedFiles.push('settings.json');
         log('  • .claude/settings.json already present — left untouched (the instance owns it; it already carries every credential deny rule. The starter\'s shelf rules are not offered here — they guard a workflow, not a secret, and are starter-only: task 1004158).');
       }
@@ -859,9 +935,27 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   //    branding. Written only when ABSENT — never clobber a CLAUDE.md the instance has
   //    grown (safe for init, adopt, and upgrade alike; the self-copy guard above already
   //    keeps this from ever touching the core/OTB checkout's own CLAUDE.md).
+  //    One narrow exception (task 1004621): the starter's OWN sentences that told the assistant to
+  //    type a bare `bongos …` — not on PATH in a project — are swapped for their `npx bongos …` form
+  //    where they still read exactly as the starter wrote them (refreshStarterCliLines). Not in
+  //    adopt mode, which never touches what the owner already had.
   const claudeMdPath = path.join(instanceDir, 'CLAUDE.md');
   if (fs.existsSync(claudeMdPath)) {
-    summary.notes.push('CLAUDE.md already present — left untouched (the instance owns it).');
+    let refreshed = { changed: 0 };
+    if (overwrite) {
+      try { refreshed = refreshStarterCliLines(fs.readFileSync(claudeMdPath, 'utf8')); } catch { /* unreadable: leave it, as before */ }
+    }
+    if (refreshed.changed) {
+      if (!dryRun) fs.writeFileSync(claudeMdPath, refreshed.text);
+      // Real run only, like the settings top-up: it preserves content, so the upgrade pre-flight's
+      // "materialize overwrites this anyway" waiver must not cover an owner's uncommitted edit.
+      if (!dryRun) addWritten('CLAUDE.md');
+      summary.claudeMdCliLines = refreshed.changed;
+      summary.notes.push(`CLAUDE.md kept as the instance's own, except ${refreshed.changed} unedited starter sentence(s) now say \`npx bongos …\` — the CLI is not on PATH in a project, so a bare \`bongos\` failed with command not found.`);
+      log(`  ${dryRun ? '[dry-run] would update' : '✓ updated'} ${refreshed.changed} unedited starter sentence(s) in CLAUDE.md to \`npx bongos …\` (everything else untouched)`);
+    } else {
+      summary.notes.push('CLAUDE.md already present — left untouched (the instance owns it).');
+    }
   } else {
     if (!dryRun) {
       fs.mkdirSync(instanceDir, { recursive: true });
@@ -1018,4 +1112,4 @@ if (require.main === module) {
   process.exit(s.refused.length ? 1 : 0);
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };
+module.exports = { scriptToVerb, bongosify, PROJECT_CLI, topUpNpxAllowTwins, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };

package/scripts/gds/claude-md-template.js

@@ -56,15 +56,15 @@ function renderInstanceClaudeMd(branding = {}) {
 
 Read this at the start of every session. Keep it lean — it loads in full every time.
 
-## First run — before any \`bongos\` command
+## First run — before any \`npx bongos\` command
 
-**If \`node_modules/@bongos/core\` is missing, run \`npm install\` first.** The \`bongos\` CLI ships *inside* that dependency, so until the install completes there is no \`bongos\` command and every instruction below fails with \`command not found\`:
+**If \`node_modules/@bongos/core\` is missing, run \`npm install\` first.** The \`bongos\` CLI ships *inside* that dependency and is **not on your PATH**, so it always runs through npx — \`npx bongos <command>\`, never a bare \`bongos\` (that fails with \`command not found\`). Until the install completes, every \`npx bongos\` instruction below fails too:
 
 \`\`\`bash
 npm install
 \`\`\`
 
-Once per machine, per clone — it is not committed (\`node_modules/\` is ignored on purpose), so a fresh \`git clone\` always needs it. If a \`bongos\` command then still misbehaves, \`bongos doctor\` checks the toolchain and session and prints the fix.
+Once per machine, per clone — it is not committed (\`node_modules/\` is ignored on purpose), so a fresh \`git clone\` always needs it. If an \`npx bongos\` command then still misbehaves, \`npx bongos doctor\` checks the toolchain and session and prints the fix.
 
 ## What this is
 
@@ -74,17 +74,17 @@ ${ident}
 
 **Every change is backed by a claimed Bongos task. No exceptions.** Code, docs, migrations, config — if you are about to change project state and do not hold an active claim covering it, stop: create or find the task, claim it, then make the change. There is no "tiny fix" or "just a doc" loophole; the database is the complete ledger of what happened to this project.
 
-- **Start every session with \`bongos start\`** (or \`/builder-start\`) — it lists the tasks you can claim right now, parallel-safe against everyone else's active claims.
-- **\`bongos claim <id>\`** locks a task to your session. If it refuses (already claimed, not ready, dependencies not shipped), pick another.
-- **\`bongos ship\`** runs the smoke + grade, then merges and deploys; **\`bongos release <id>\`** drops a claim with no credit. Ship or release before you sign off.
+- **Start every session with \`npx bongos start\`** (or \`/builder-start\`) — it lists the tasks you can claim right now, parallel-safe against everyone else's active claims.
+- **\`npx bongos claim <id>\`** locks a task to your session. If it refuses (already claimed, not ready, dependencies not shipped), pick another.
+- **\`npx bongos ship\`** runs the smoke + grade, then merges and deploys; **\`npx bongos release <id>\`** drops a claim with no credit. Ship or release before you sign off.
 - **Dependencies gate everything** — a task becomes claimable only once every task it depends on has shipped.
 - **Code you write or touch carries a doc-comment** — each module a header, each public function/class a line or two, saying *what* it does and *why* it exists (never how), in the words someone would search for. Agents find code by searching text, so meaning written into the source is what makes it findable.
 
 ## Where things live
 
-- **Live work state** (tasks, versions, ranks, ${currency}): the Bongos DB — \`bongos start\` / \`bongos status\`, or ${hallLine}.${statusLine}
+- **Live work state** (tasks, versions, ranks, ${currency}): the Bongos DB — \`npx bongos start\` / \`npx bongos status\`, or ${hallLine}.${statusLine}
 - **This instance's identity** (product, world, brand, addresses): \`config/branding.json\`. **Which features are on**: \`config/modules.json\`.
-- **The platform you stand on** (rank ladder, the ship/grade/deploy pipeline, permissions, migrations) is vendored **Cloud Bongos core** — build the product, not the platform under it. Landing code is Bongos's job: claim a task and run \`bongos ship\`, never a raw \`git push\`/deploy.
+- **The platform you stand on** (rank ladder, the ship/grade/deploy pipeline, permissions, migrations) is vendored **Cloud Bongos core** — build the product, not the platform under it. Landing code is Bongos's job: claim a task and run \`npx bongos ship\`, never a raw \`git push\`/deploy.
 
 ## Permissions
 
@@ -96,8 +96,45 @@ Builders are rewarded in **${currency}** for shipped work.
 
 ---
 
-*This is a starter, authored by \`bongos init\`. Grow it as the project grows — add your architecture, versioning methodology, and hard-won gotchas — but keep it lean: every line spends context budget in every session.*
+*This is a starter, authored by \`npx bongos init\`. Grow it as the project grows — add your architecture, versioning methodology, and hard-won gotchas — but keep it lean: every line spends context budget in every session.*
 `;
 }
 
-module.exports = { renderInstanceClaudeMd };
+// The starter's own sentences as an earlier `bongos init` wrote them, each beside its `npx bongos`
+// form (task 1004621). Every pair is branding-independent text this template authored, so an exact
+// match can only be a line the owner never changed.
+const LEGACY_CLI_LINES = [
+  ['## First run — before any `bongos` command\n\n**If `node_modules/@bongos/core` is missing, run `npm install` first.** The `bongos` CLI ships *inside* that dependency, so until the install completes there is no `bongos` command and every instruction below fails with `command not found`:',
+    '## First run — before any `npx bongos` command\n\n**If `node_modules/@bongos/core` is missing, run `npm install` first.** The `bongos` CLI ships *inside* that dependency and is **not on your PATH**, so it always runs through npx — `npx bongos <command>`, never a bare `bongos` (that fails with `command not found`). Until the install completes, every `npx bongos` instruction below fails too:'],
+  ['If a `bongos` command then still misbehaves, `bongos doctor` checks', 'If an `npx bongos` command then still misbehaves, `npx bongos doctor` checks'],
+  ['- **Start every session with `bongos start`** (or `/builder-start`)', '- **Start every session with `npx bongos start`** (or `/builder-start`)'],
+  ['- **`bongos claim <id>`** locks a task to your session.', '- **`npx bongos claim <id>`** locks a task to your session.'],
+  ['- **`bongos ship`** runs the smoke + grade, then merges and deploys; **`bongos release <id>`** drops', '- **`npx bongos ship`** runs the smoke + grade, then merges and deploys; **`npx bongos release <id>`** drops'],
+  ['the Bongos DB — `bongos start` / `bongos status`, or', 'the Bongos DB — `npx bongos start` / `npx bongos status`, or'],
+  ['claim a task and run `bongos ship`, never', 'claim a task and run `npx bongos ship`, never'],
+  ['*This is a starter, authored by `bongos init`.', '*This is a starter, authored by `npx bongos init`.'],
+];
+
+// refreshStarterCliLines — bring an EXISTING project's CLAUDE.md onto the `npx bongos` spelling
+// (task 1004621). The starter is written only when CLAUDE.md is absent, so every project scaffolded
+// before this kept telling its assistant to type a bare `bongos start` — a command that is not on
+// PATH — in the one file loaded every session. The instance owns the file, so this replaces ONLY
+// the starter's own sentences, matched exactly: a line the owner reworded is left alone, nothing
+// is added or removed, and a file grown from the starter keeps everything else byte for byte.
+// Pure: returns { text, changed } where `changed` counts the sentences replaced.
+function refreshStarterCliLines(text) {
+  let out = String(text == null ? '' : text);
+  let changed = 0;
+  // A Windows checkout (git autocrlf) holds the file with CRLF endings; match it in its own.
+  const eol = out.includes('\r\n') ? (s) => s.replace(/\n/g, '\r\n') : (s) => s;
+  for (const [legacyLf, currentLf] of LEGACY_CLI_LINES) {
+    const legacy = eol(legacyLf);
+    const current = eol(currentLf);
+    if (!out.includes(legacy)) continue;
+    out = out.split(legacy).join(current);
+    changed += 1;
+  }
+  return { text: out, changed };
+}
+
+module.exports = { renderInstanceClaudeMd, refreshStarterCliLines, LEGACY_CLI_LINES };

package/scripts/gds/cli-lib.js

@@ -512,7 +512,7 @@ function printUnauthGuidanceAndExit() {
     console.error(`  Recover the fast (UI-first) way — run ${surfaceAction('reauth')}`);
     console.error('  (opens your Settings page; under "CLI Access" click "Re-issue CLI');
     console.error('   token", copy the one-liner, paste it back — no terminal Device Flow.)');
-    console.error('  Fallback (browser sign-in): bongos login <instance-url>');
+    console.error('  Fallback (browser sign-in): npx bongos login <instance-url>');
   } else {
     console.error('  Recover the fast (UI-first) way — run /builder-reauth, or:');
     console.error('    node scripts/gds/reauth.js');
@@ -609,7 +609,7 @@ function printInstanceMismatchAndExit({ expected, actual }) {
   console.error(`    Your session is signed in to:         ${actual}`);
   console.error('');
   console.error('  Sign in to THIS instance, then re-run your command:');
-  console.error(`    bongos login ${expected}`);
+  console.error(`    npx bongos login ${expected}`);
   console.error(`    (or, from a checkout without the bongos bin:  node scripts/gds/login.js ${expected})`);
   console.error('');
   console.error('  Intentionally targeting another instance? Set the base explicitly, e.g.');
@@ -764,8 +764,8 @@ async function requireSession() {
     if (isTerminalSurface()) {
       // A terminal reader may have no instance configured at all — naming one is the whole point
       // of `login`, and `/builder-*` does not exist outside a Claude Code session (task 1003730).
-      console.error(`  • First time here            → run bongos login <instance-url>  (sign in with a browser click)`);
-      console.error(`  • Signed in before / expired → run bongos reauth                (re-issue your CLI token)`);
+      console.error(`  • First time here            → run npx bongos login <instance-url>  (sign in with a browser click)`);
+      console.error(`  • Signed in before / expired → run npx bongos reauth                (re-issue your CLI token)`);
     } else {
       console.error(`  • First time on the project  → run /builder-setup   (one-time GitHub sign-in that also registers you)`);
       console.error(`  • Signed in before / expired → run /builder-reauth  (fast UI re-issue of your CLI token)`);

package/scripts/gds/feedback-send.js

@@ -29,9 +29,9 @@ const ic = require('../../src/instance-config');
 
 const USAGE = [
   'usage:',
-  '  bongos feedback "what went wrong"          report a problem with Bongos',
-  '  bongos feedback --idea "what you wish for" suggest an improvement',
-  '  bongos feedback --message-file notes.md    send a longer note from a file (- for stdin)',
+  '  npx bongos feedback "what went wrong"          report a problem with Bongos',
+  '  npx bongos feedback --idea "what you wish for" suggest an improvement',
+  '  npx bongos feedback --message-file notes.md    send a longer note from a file (- for stdin)',
   '',
   'Goes to the Cloud Bongos maintainers. Only the text you type and the Bongos',
   'versions you run are sent — no code, chat or files from your project.',

package/scripts/gds/paste-token.js

@@ -86,7 +86,7 @@ const API_BASE = RESOLVED.base;
 function usage(extra) {
   if (extra) console.error(extra);
   console.error('');
-  console.error('Usage: bongos paste-token <token> [--api-base <url>]');
+  console.error('Usage: npx bongos paste-token <token> [--api-base <url>]');
   console.error('   (inside a core checkout: node scripts/gds/paste-token.js <token>)');
   console.error('');
   // Fall back to the inferred base for this hint when --api-base was the thing that

package/scripts/gds/provision-net.js

@@ -12,14 +12,7 @@
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { CONFIG } = require('./provision-config.js');
-const { provisionedEnvPrefix } = require('./provision-units.js');
-
-function federationHubOrigin() {
-  const explicit = process.env.PROVISION_HUB_ORIGIN;
-  if (explicit) return String(explicit).replace(/\/+$/, '');
-  const own = process.env[`${provisionedEnvPrefix()}_PUBLIC_ORIGIN`];
-  return own ? String(own).replace(/\/+$/, '') : null;
-}
+const { federationHubOrigin, provisionedEnvPrefix } = require('./provision-units.js'); // lives beside the hub-upgrade address it also feeds (task 1004608)
 
 // Whether provisioning should federate this instance's sign-in through the hub.
 //

package/scripts/gds/provision-units.js

@@ -258,13 +258,15 @@ GITHUB_APP_PRIVATE_KEY=${String(appPem).replace(/\r?\n/g, '\\n')}
   // Postgres with every sibling and the control plane, so its pool may not take pg's
   // default 10 of the server's 97. src/bongos/pool.js reads it bare.
   const poolLine = `PGPOOL_MAX=${CONFIG.instancePoolMax}\n`;
+  // Where this project's Update button goes (task 1004608) — see hubUpgradeEnvVarsFor.
+  const hubUpgradeLines = Object.entries(hubUpgradeEnvVarsFor(inst)).map(([k, v]) => `${k}=${v}\n`).join('');
   return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
 ${credComment}
 ${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
 ${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
 ${firstAdminLine}${originLines}${appLines}PORT=${inst.port}
 PGDATABASE=${dbName(inst)}
-${poolLine}${dbLines}${fedLines}${settingsEnvLines(inst, prefix)}`;
+${poolLine}${dbLines}${fedLines}${hubUpgradeLines}${settingsEnvLines(inst, prefix)}`;
 }
 function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
   return path.posix.join(etcBase, inst.slug, 'web.env');
@@ -295,7 +297,7 @@ function originEnvVarsFor(inst) {
 function settingsEnvVarsFor(inst, envBody) {
   const { settingsEnvVars } = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning')); // eslint-disable-line global-require
   const prefix = inst && inst.hosting_shape === 'control-plane' ? selfEnvPrefix({ envBody }) : provisionedEnvPrefix();
-  return settingsEnvVars(inst, prefix);
+  return { ...settingsEnvVars(inst, prefix), ...hubUpgradeEnvVarsFor(inst) };
 }
 
 // The env-var prefix the CONTROL PLANE's own web process resolves (task 1004334). The
@@ -414,8 +416,32 @@ function renamedEnvCarry(body) {
 // <PREFIX>_HUB_ORIGIN (what auth.js loadIdpConfig reads). Explicit PROVISION_HUB_ORIGIN
 // wins; otherwise the control plane's OWN public origin (<PREFIX>_PUBLIC_ORIGIN, the
 // env the hub already runs under). Null → not hub-configured → shouldFederate is false.
+function federationHubOrigin() {
+  const explicit = process.env.PROVISION_HUB_ORIGIN;
+  if (explicit) return String(explicit).replace(/\/+$/, '');
+  const own = process.env[`${provisionedEnvPrefix()}_PUBLIC_ORIGIN`];
+  return own ? String(own).replace(/\/+$/, '') : null;
+}
+
+// WHERE A HOSTED PROJECT'S UPDATE BUTTON GOES (task 1004608): the hub's deploy door for
+// THIS project, written as <PREFIX>_HUB_UPGRADE_URL. The hall used to learn the hub only
+// from the sign-in federation block, which only a co-tenant gets, so every cloud-host
+// project (and any that keeps its own GitHub app) told its owner to run `bongos upgrade`
+// on a server the platform runs. The door admits the owner of both tenant shapes
+// (modules/provisioning/core-upgrade-authz.js), so both get the address. Not a secret and
+// grants nothing: the door re-checks every request. Empty for the tenant shapes when no hub
+// origin resolves (a key that came and went would leave a stale line behind); absent for
+// every other shape, which has no door on this hub.
+const HUB_UPGRADE_SHAPES = new Set(['co-tenant', 'cloud-host']);
+function hubUpgradeEnvVarsFor(inst) {
+  if (!inst || !HUB_UPGRADE_SHAPES.has(inst.hosting_shape) || !inst.slug) return {};
+  const origin = federationHubOrigin();
+  return { [`${provisionedEnvPrefix()}_HUB_UPGRADE_URL`]: origin ? `${origin}/deploy?project=${encodeURIComponent(String(inst.slug))}` : '' };
+}
 
 module.exports = {
+  federationHubOrigin,
+  hubUpgradeEnvVarsFor,
   ENV_PREFIX_PACK,
   envPrefixMismatch,
   normalizePackEnvPrefix,

package/scripts/gds/reauth.js

@@ -96,7 +96,7 @@ function printGuidance({ opened }) {
   console.log("        you're already signed in there via your browser cookie)");
   console.log('  2. Under the "CLI Access" section, click "Re-issue CLI token".');
   console.log('  3. Click "Copy" — it copies a one-line command that looks like:');
-  console.log('       bongos paste-token <token>');
+  console.log('       npx bongos paste-token <token>');
   console.log('  4. Paste that one line back to Claude. It will run it for you,');
   console.log('     verify the token, and write your new session.');
   console.log('');

package/scripts/gds/run-unit-tests.js

@@ -106,6 +106,9 @@ const INTEGRATION = new Set([
   // never was a dedicated consumer-layout-boot workflow, whatever older notes say.
   'consumer_layout_boot',
   'claim_gate_open_blocker', 'claim_gate_rebase',
+  // task 1004585: a hall-made goal's spec task gates its other work — the edge, the
+  // claim gate's unsatisfiedDeps read, and the ship-time auto-promotion, on real Postgres.
+  'goal_spec_task_db',
   // task 1003457: proves the blocker-resolve auto-promotion trigger (migration
   // 009, tightened by core_223) fires on the HALL'S OWN write path — the real
   // buildGdsRouter() HTTP routes, not a static SQL-text pin (blocker_resolve_guard.mjs,

package/scripts/gds/setup.js

@@ -356,7 +356,7 @@ async function finishSetup(builder) {
       console.log(`  3. Claim + ship:      ${surfaceAction('claim', 'N')}    →    ${surfaceAction('ship')}`);
       // Claiming writes code, so it needs a checkout. In a terminal the public CLI answers
       // `bongos claim` with where to get one; say so here rather than let step 3 look self-serve.
-      if (isTerminalSurface()) console.log('     (claim + ship run in a checkout — `bongos claim` shows how to get one)');
+      if (isTerminalSurface()) console.log('     (claim + ship run in a checkout — `npx bongos claim` shows how to get one)');
       console.log('  4. Ship three works and you rise to Thetes — the whole queue opens.');
     }
   } catch (_) {