@bongos/core 1.21.70 → 1.21.71

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 (_) {

package/scripts/gds/start.js

@@ -615,7 +615,7 @@ function instanceNotRunningCard({ origin, depsMissing } = {}) {
     out.push(`2. If that doesn't load either, the instance itself is down: \`curl -sI ${origin}/healthz\` says whether it's answering.`);
     out.push(`3. Once it answers, re-run ${surface.code(surface.action('start'))}.`);
     out.push('');
-    out.push(`${surface.strong(`Don't run ${surface.code('bongos dev')} for this.`)} It stands up a separate local instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
+    out.push(`${surface.strong(`Don't run ${surface.code(surface.cli('dev'))} for this.`)} It stands up a separate local instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
     if (depsMissing) {
       out.push('');
       out.push(`(The ${surface.code('bongos')} CLI isn't installed here. It's optional — the website above is the same board. ${surface.code('@bongos/core')} is ${surface.strong('public')} on npm, so ${surface.code('npm install @bongos/core')} needs no token or login; a failure here is a real error, not the expected tokenless 404 it used to be.)`);
@@ -629,10 +629,10 @@ function instanceNotRunningCard({ origin, depsMissing } = {}) {
   if (depsMissing) {
     out.push(`${n++}. \`npm install\` — installs the toolchain first (the \`bongos\` CLI ships inside \`@bongos/core\`, so nothing else runs until this does).`);
   }
-  out.push(`${n++}. \`bongos dev\` — one command: starts Postgres, builds the tables, runs the server, and signs you in.`);
+  out.push(`${n++}. ${surface.code(surface.cli('dev'))} — one command: starts Postgres, builds the tables, runs the server, and signs you in.`);
   out.push(`${n++}. Re-run ${surface.code(surface.action('start'))}.`);
   out.push('');
-  out.push(`Meant to work on a *different* instance that's already running? Sign in to it with \`bongos login <url>\` first.`);
+  out.push(`Meant to work on a *different* instance that's already running? Sign in to it with ${surface.code(surface.cli('login <url>'))} first.`);
   return out.join('\n');
 }
 function emitInstanceNotRunningCard(opts) {
@@ -980,7 +980,7 @@ async function main() {
 
   // ---------- next ----------
   console.log('');
-  console.log(`→ ${surface.isTerminal() ? `Claim one with ${surface.code('bongos claim <id>')} in a checkout` : `${surface.strong('Tell me a number')} to claim it`}.`);
+  console.log(`→ ${surface.isTerminal() ? `Claim one with ${surface.code(surface.cli('claim <id>'))} in a checkout` : `${surface.strong('Tell me a number')} to claim it`}.`);
   if (full) {
     console.log('');
     console.log('Commands:');

package/scripts/gds/surface.js

@@ -43,11 +43,23 @@ function taskRef(id, url, env = process.env) {
   return isTerminal(env) ? `#${id}` : `[#${id}](${url}${id})`;
 }
 
+// How a reader runs the CLI (task 1004621). The `bongos` bin ships inside @bongos/core and is not
+// on PATH — in a project it sits at node_modules/.bin/bongos, and the global @cloudbongos/cli that
+// once put a bare `bongos` on PATH is retired (ADR 0324). `npx` finds the local bin with no setup,
+// in a project and in a core checkout alike, so every printed command uses it. A bare `bongos …`
+// sent the first command of a project's session into `command not found`.
+const CLI = 'npx bongos';
+
+// A CLI command line to print: `cli('claim <id>')` → `npx bongos claim <id>`.
+function cli(rest) {
+  return rest ? `${CLI} ${rest}` : CLI;
+}
+
 // An action the reader can actually run. In a session that is the slash command; in a terminal it
-// is the `bongos` verb. `/builder-ship 123` does not exist outside Claude Code.
+// is the `npx bongos` verb. `/builder-ship 123` does not exist outside Claude Code.
 function action(verb, arg, env = process.env) {
   const tail = arg == null ? '' : ` ${arg}`;
-  return isTerminal(env) ? `bongos ${verb}${tail}` : `/builder-${verb}${tail}`;
+  return isTerminal(env) ? cli(`${verb}${tail}`) : `/builder-${verb}${tail}`;
 }
 
 // Markdown emphasis is decoration in a feed and literal asterisks on a console.
@@ -86,4 +98,4 @@ function table(headers, rows, env = process.env) {
   ].join('\n');
 }
 
-module.exports = { AGENT, TERMINAL, resolveSurface, isTerminal, taskRef, action, strong, em, code, table };
+module.exports = { AGENT, TERMINAL, CLI, cli, resolveSurface, isTerminal, taskRef, action, strong, em, code, table };

package/scripts/gds/task.js

@@ -19,10 +19,12 @@
 // Task CREATION is Archon-gated SERVER-SIDE (creating work shapes scope, ADR 0016). This
 // CLI adds no authority — a lower rank gets a clear 403 message pointing at idea capture.
 
-const { cliClient, requireSession, arg, hasFlag } = require('./cli-lib');
+const { cliClient, requireSession, arg, hasFlag, errCode } = require('./cli-lib');
 // task 1003109: the ship-time VISUAL. The CLI screens the file with the SERVER's
 // own constants, so what it accepts is exactly what the upload route accepts.
 const taskVisuals = require('../../modules/lifecycle/task-visuals');
+// task 1004597: the one spelling of "this is platform upkeep" (kind infra, no goal).
+const { UPKEEP_KIND } = require('../../modules/lifecycle/upkeep-home');
 
 // Valid enums (mirrors the server's task-classifier vocab; a friendly client-side check
 // so an obvious typo fails before the round-trip — the server stays authoritative).
@@ -87,6 +89,8 @@ function usage() {
   console.error('  bongos task visual <id> <image> [--alt "caption"]   attach or replace the ship-time visual');
   console.error('  bongos task visual <id> --remove                    remove it again');
   console.error('  bongos task visual <id> <image> --slot <name>       attach or replace a named visual (e.g. after-phone-dark)');
+  console.error('\n  Platform upkeep (a Bongos upgrade, maintenance) needs no goal: pass --kind infra');
+  console.error("  and leave out --goal, and it is filed under the version's maintenance goal.");
   console.error(`\n  kinds: ${VALID_KINDS.join(' | ')}`);
   console.error(`  disciplines: ${VALID_DISCIPLINES.join(' | ')}`);
 }
@@ -111,6 +115,22 @@ async function resolveDefaultVersion(api) {
   return building[0].id;
 }
 
+// goalRequiredHelp — PURE: what a builder reads when a task names no goal
+// (task 1004597). Two ways forward: name a product goal, or — when the work is
+// platform upkeep such as a Bongos upgrade — file it as kind infra with no goal.
+function goalRequiredHelp(body) {
+  const lines = ['Every task belongs to a goal, and this one did not name one.'];
+  if (body && body.kind === UPKEEP_KIND) {
+    lines.push(`Version ${body.version_id} is not being built right now, so it has no maintenance goal.`);
+    lines.push('Re-run with --version <the version being built> (see `bongos status`).');
+  } else {
+    lines.push('  - Product work: re-run with --goal <id> (`bongos status` lists the goals).');
+    lines.push('  - Platform upkeep (a Bongos upgrade or other maintenance): re-run with --kind infra and no --goal.');
+    lines.push("    It goes into this version's maintenance goal.");
+  }
+  return lines.join('\n');
+}
+
 async function cmdNew(args) {
   const { body, errors } = buildTaskBody(args);
   if (errors.length) { console.error('task new: ' + errors.join('; ') + '\n'); usage(); process.exit(2); }
@@ -120,7 +140,7 @@ async function cmdNew(args) {
   if (!body.version_id) {
     body.version_id = await resolveDefaultVersion(api);
     if (!body.version_id) {
-      console.error('task new: could not resolve an active version — pass --version <id> (see `bongos status`).');
+      console.error('task new: could not resolve an active version — pass --version <id> (see `npx bongos status`).');
       process.exit(2);
     }
   }
@@ -128,7 +148,13 @@ async function cmdNew(args) {
   if (r.status === 403) {
     console.error('Creating a task is Archon-gated (creating work shapes scope). Your rank is lower, so the server declined.');
     console.error('To propose it instead, capture an idea for triage:');
-    console.error('  bongos exec scripts/gds/capture.js "<your idea>"');
+    console.error('  npx bongos exec scripts/gds/capture.js "<your idea>"');
+    process.exit(1);
+  }
+  // task 1004597: a goal-less filing is refused unless it is platform upkeep.
+  // Say both ways forward in plain words instead of dumping the raw error.
+  if (r.status === 400 && errCode(r.data) === 'goal_id_required') {
+    console.error(goalRequiredHelp(body));
     process.exit(1);
   }
   if (r.status !== 201 || !r.data?.task) {
@@ -141,8 +167,9 @@ async function cmdNew(args) {
   console.log(`✓ Created task #${task.id} [${task.status}] — ${task.title}`);
   console.log(`  kind=${task.kind} · discipline=${task.discipline}${task.priority ? ` · P${task.priority}` : ''}${task.goal_id ? ` · goal ${task.goal_id}` : ''}`);
   console.log(`  ${hallLink(API_BASE, task.id)}`);
+  if (r.data.goal_home === 'maintenance') console.log(`  Filed under ${body.version_id}'s maintenance goal, the standing home for platform upkeep.`);
   if (task.status !== 'ready') console.log(`  (status '${task.status}' — pass --ready to make it claimable now, deps permitting)`);
-  console.log(`  next: bongos claim ${task.id}`);
+  console.log(`  next: npx bongos claim ${task.id}`);
 }
 
 async function cmdShow(args) {
@@ -243,4 +270,4 @@ if (require.main === module) {
   main().catch((err) => { console.error('fatal:', err); process.exit(1); });
 }
 
-module.exports = { buildTaskBody, VALID_KINDS, VALID_DISCIPLINES, csv, hallLink };
+module.exports = { buildTaskBody, goalRequiredHelp, VALID_KINDS, VALID_DISCIPLINES, csv, hallLink };

package/scripts/gds/upgrade-operator.js

@@ -0,0 +1,73 @@
+// scripts/gds/upgrade-operator.js — "who upgrades this project?" for `bongos upgrade`
+// run from a builder's own computer (task 1004596).
+//
+// A hosted project (its Settings → Software update button leads to the hub — door kind
+// 'hub', see src/bongos/routes/core-update.js updateDoor) lives on its operator's server.
+// Its builders work from a laptop checkout that has no database and no server access. Run
+// there, `bongos upgrade` used to say only "cannot determine which database to migrate.
+// Set PGDATABASE…" — and an assistant reading that, plus the release recipe, wrote the
+// builder server steps full of guessed names for a machine they cannot reach. This module
+// replaces that dead end with the one supported path: the operator upgrades it, and here
+// is how to ask.
+//
+// THE CONDITION, and why it cannot touch the real operator path: BOTH must hold —
+//   1. no database is known in this checkout (no PGDATABASE, no db.database in the
+//      branding pack). On the server a database is always known, or upgrade.js already
+//      refuses there; so the server never reaches step 2.
+//   2. the project, asked through this builder's own CLI session, says its update door is
+//      the hub's. No session, no answer, an older core, a self-hosted or provisioning
+//      instance → no message, and upgrade.js behaves exactly as before.
+
+// Ask the project (via this builder's CLI session) where its Update button leads.
+// Returns { kind, url, hall } or null on ANY failure — a missing answer is never a verdict.
+async function readUpdateDoor({ timeoutMs = 5000 } = {}) {
+  try {
+    const { readSessionToken, dispatchedFetch, noKeepAliveDispatcher, CLI_USER_AGENT, hallBase } = require('./cli-lib');
+    const session = readSessionToken();
+    if (!session) return null;
+    const res = await dispatchedFetch(`${session.apiBase}/api/bongos/software-update`, {
+      headers: { Authorization: `Bearer ${session.token}`, 'User-Agent': CLI_USER_AGENT },
+      signal: AbortSignal.timeout(timeoutMs),
+      dispatcher: noKeepAliveDispatcher(),
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const door = body && body.door;
+    if (!door || typeof door.kind !== 'string') return null;
+    return { kind: door.kind, url: door.url || null, hall: hallBase(session.apiBase) };
+  } catch { return null; }
+}
+
+// The door when the operator runs this project and this checkout is not where it runs;
+// null otherwise (including whenever the answer cannot be read).
+async function operatorRunsThisProject({ instanceDir }, deps = {}) {
+  const { db } = (deps.resolveInstanceDb || require('./upgrade').resolveInstanceDb)({ instanceDir }, deps.run);
+  if (db) return null;
+  const door = await (deps.readUpdateDoor || readUpdateDoor)();
+  return door && door.kind === 'hub' ? door : null;
+}
+
+// What the builder (and any assistant reading over their shoulder) is told. Plain words,
+// one supported path, no server steps and nothing for anyone to fill in.
+function operatorRunMessage(door = {}) {
+  const settings = door.hall ? `${door.hall}/settings#software-update` : 'Settings → Software update';
+  return [
+    'This project is upgraded by its operator, not from this computer.',
+    'It runs on the operator\'s server, and nothing you run here can upgrade it.',
+    '',
+    'To ask for the upgrade:',
+    `  • Open ${settings} and use the button there.`,
+    '  • Or, from this terminal:  bongos feedback "Please upgrade this project to the latest version"',
+    '',
+    'There are no server steps for you to take. An assistant should not write any, or guess',
+    'server, database or service names for this project — pass the request on instead.',
+  ].join('\n') + '\n';
+}
+
+// The message to show, or null — what `bongos upgrade` (upgrade.js main) asks before anything else.
+async function operatorNotice({ instanceDir }, deps = {}) {
+  const door = await operatorRunsThisProject({ instanceDir }, deps);
+  return door ? operatorRunMessage(door) : null;
+}
+
+module.exports = { readUpdateDoor, operatorRunsThisProject, operatorRunMessage, operatorNotice };

package/scripts/gds/upgrade.js

@@ -1433,7 +1433,7 @@ function parseArgs(argv) {
   };
 }
 
-async function main(argv = process.argv.slice(2)) {
+async function main(argv = process.argv.slice(2), deps = {}) {
   if (hasFlag('--help', argv) || argv[0] === 'help') {
     process.stdout.write([
       'bongos upgrade — pull the Cloud Bongos core to a new version and apply it.',
@@ -1471,9 +1471,14 @@ async function main(argv = process.argv.slice(2)) {
   }
   // Backward-compatible: bare `bongos upgrade` (no --to) is the documented module-compatibility
   // PRE-CHECK — unchanged behavior, delegated to the module CLI. A --to switches to the real channel.
+  // task 1004596: from a builder's own checkout of a project its OPERATOR runs, say who upgrades it and how to ask — never a server-only refusal (upgrade-operator.js has the condition).
+  const operatorMsg = await (deps.operatorNotice || require('./upgrade-operator').operatorNotice)({ instanceDir: path.resolve(arg('--instance', argv) || process.cwd()) });
   if (!arg('--to', argv)) {
-    return require('./module').cmdUpgrade(argv);
+    const code = await (deps.cmdUpgrade || require('./module').cmdUpgrade)(argv);
+    if (operatorMsg) process.stdout.write(`\n${operatorMsg}`);
+    return code;
   }
+  if (operatorMsg) { process.stderr.write(`\n✖ ${operatorMsg}`); return 1; }
   const res = await runUpgrade(parseArgs(argv));
   if (!res.ok) { process.stderr.write(`\n✖ ${res.error || 'upgrade failed'}\n${require('./upgrade-outcome').outcomeLine(res)}`); return 1; } // the outcome line: how far it got, for the deploy runner (task 1004446)
   return 0;

package/scripts/hall-preview/server.js

@@ -180,6 +180,9 @@ const CANNED_WRITES = [
   // a vote cast from the street's matter card (task 1004528), so the card's
   // answer (the toast, the building lighting) renders here too.
   ['POST', /^government\/board\/items\/\d+\/votes$/, 'government__board__items__votes.post'],
+  // Settings → Software update's "Ask for this upgrade" (task 1004595), so the
+  // pending line the panel draws after the press renders here too.
+  ['POST', /^software-update\/request$/, 'software-update__request.post'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request