@bongos/core 1.19.724 → 1.19.725

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.724",
-  "core_contract": "1.19.724",
-  "source_commit": "26fe0e32ab8d71694d4a83ebd8aec4d442ce8da0",
+  "core_version": "1.19.725",
+  "core_contract": "1.19.725",
+  "source_commit": "5a98310e9967d2430aba88122213a7a722ae07ad",
   "source_ref": "HEAD",
-  "built_at": "2026-09-13T13:15:36.801Z",
+  "built_at": "2026-09-13T13:36:04.522Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 478,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2162,
+    "functional_verbatim": 2163,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2664,
-  "tree_sha256": "444d762aa2ed1f4ebcc9269d0542680f83ed9da1a928a98ac6a36ebe09c691da",
+  "file_count": 2665,
+  "tree_sha256": "41c25536b149d9641dc2e413a0da01a4e49c306b619ec412c2f2ea7b552944c6",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2807,7 +2807,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "690b1a1f85cb9eb8e3b9e326b39cd56724bd0e3287d96539a7e84c6267231507"
+      "sha256": "793f097cac5faadbbf7d9aaec4c2b5b413a535b913b2e3258ef17361982f7ef9"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6137,7 +6137,7 @@
     {
       "path": "modules/onboarding/approval-broadcast.js",
       "mode": "0000644",
-      "sha256": "5d88c9b42e5f76b0959a543d097456a00c3ec1f4ef1a75ca8de6334b826ba983"
+      "sha256": "2225b1a2196f6195bdf1b24f38da5295e0f44cbd95395d09c6109d8680fc5b01"
     },
     {
       "path": "modules/onboarding/db.js",
@@ -7837,12 +7837,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "10ce0347095f2fef439846e19eee1535447edac0fd659fb0ef8703f50df6e60f"
+      "sha256": "82be9f1fd6d0b97fdc7b5ac3d36e9e7537c2b42818af2bb643be5ecf6610d22a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "ddfcaa576b63f9169be34c591a1c0dccd629ca0399b0e27bf514a4a54fc21c6d"
+      "sha256": "f1796793605e11cb891209283c562e08772ee65f956bbe5039ee799e1969a013"
     },
     {
       "path": "public-docs/index.html",
@@ -7907,7 +7907,7 @@
     {
       "path": "scripts/gds/adopt-preflight.js",
       "mode": "0000644",
-      "sha256": "07ff338beac12979eba50e4a6fe9c2f6dbfd842fa01abe1c412b19888d10c4a0"
+      "sha256": "1e2c8a70aec49eaa0d95a9cbf37145fa1c851b46e2ec27f72f773d4198356ab9"
     },
     {
       "path": "scripts/gds/adr-namespace.js",
@@ -8067,7 +8067,7 @@
     {
       "path": "scripts/gds/build-cli-package.js",
       "mode": "0000644",
-      "sha256": "bd7509b408b56ded44c07f3cbad8cf361211fd8349e5139c75c49d31fcaa07a9"
+      "sha256": "314004ef2af628fca5f572daca5e2404d1c2129b3ad650d715294cc26cc2fe13"
     },
     {
       "path": "scripts/gds/bump-version.js",
@@ -8117,7 +8117,7 @@
     {
       "path": "scripts/gds/claude-md-template.js",
       "mode": "0000644",
-      "sha256": "68f2c65ac9297328f44927ccb9a40a0fa536b91d9056aaa980a92149a64ce47c"
+      "sha256": "afd825409590fa0c81cdc072bb925555e70bd543f819b8c68110760919ca67e1"
     },
     {
       "path": "scripts/gds/cleanup-orphans.js",
@@ -8219,6 +8219,11 @@
       "mode": "0000644",
       "sha256": "79effdf07519d26153f6fe846fd052cd4a37fa1e25b6b1a278146c9d8bcf6766"
     },
+    {
+      "path": "scripts/gds/device-flow-help.js",
+      "mode": "0000644",
+      "sha256": "802b8875e2aa7e51b1b95800aae461c5d289d7684ef57e6da95bebc458aa0f5e"
+    },
     {
       "path": "scripts/gds/diagnose-achievements.js",
       "mode": "0000644",
@@ -8452,7 +8457,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "b0971625852fca93ca474d2f9e31e3601397f1b9efbef3241a0b0c47f17d925f"
+      "sha256": "e81ab71bcd7d2f06b5aaf462dd099776c966f9840a109846a9753f12482b5281"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -8522,7 +8527,7 @@
     {
       "path": "scripts/gds/login.js",
       "mode": "0000644",
-      "sha256": "bdc7fcc0876a1185fb15339740793944c755d716d998bb68533ab3a721d39ab2"
+      "sha256": "b5e00007cf68a5fa719d2603fdd7405dbc2e474a41721acde274e43bcec59ab0"
     },
     {
       "path": "scripts/gds/main-audit.js",
@@ -8972,7 +8977,7 @@
     {
       "path": "scripts/gds/setup.js",
       "mode": "0000644",
-      "sha256": "15243de5b4bde57313c601bf96bd2a10bb86dedceb18cb0a31495b998d1ca835"
+      "sha256": "bd78df6f5f296588721afd9ebf2e477b5d463ca3d12cbee8894e115a0a6779f7"
     },
     {
       "path": "scripts/gds/shell.js",
@@ -9492,7 +9497,7 @@
     {
       "path": "src/bongos/repo-info.js",
       "mode": "0000644",
-      "sha256": "ae6cd8950ec8e23935febcc14c4ba65ff39f045c01202a1237d1ad79a39153f2"
+      "sha256": "38c98f7cdb9dbc9d73dc53d0ad29466bc2fc8f762cd8db3961ab40df44dae11c"
     },
     {
       "path": "src/bongos/route-rank-check.js",
@@ -9632,7 +9637,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "e4a9cdca849f840e277b0632217f9a8aec42d570d96373548f47d04bd1fce0bd"
+      "sha256": "5aa7b8b121af462b9feba77bbd2a87b997e6dad22d3c8e6bf467ca122016d3d0"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9727,7 +9732,7 @@
     {
       "path": "tests/adopt_preflight.mjs",
       "mode": "0000644",
-      "sha256": "125edcec8c7d7536365b9675daa1fceb9fe072a30e2a4a68ee2911cd258a8c10"
+      "sha256": "2489a19e7c36f53c4046a4a6fab54a55dbdfe8da6daa3452316f9e0abea01742"
     },
     {
       "path": "tests/adr_renumber_integrity.mjs",
@@ -10052,7 +10057,7 @@
     {
       "path": "tests/bongos_login.mjs",
       "mode": "0000644",
-      "sha256": "f273c511d9c42093da170572a0db55f78cada57787e7631aefdd622228c2fad9"
+      "sha256": "abad290fe23b159a6c42a70fbc6cec68bfc0406c90776a96b57513e9b4b8ef04"
     },
     {
       "path": "tests/box_access.mjs",
@@ -10272,7 +10277,7 @@
     {
       "path": "tests/claude_materialize.mjs",
       "mode": "0000644",
-      "sha256": "9ae022d9051937e80b0d3a4baf3840d57560fa9d441b93beff746cfa11871d35"
+      "sha256": "8292d8c7a788e7839599d38f6c78a5dbb68f6ae50a58771a66e6481a562f0ace"
     },
     {
       "path": "tests/clawback_confirmed_backlog.mjs",
@@ -10572,7 +10577,7 @@
     {
       "path": "tests/discord_approvals.mjs",
       "mode": "0000644",
-      "sha256": "f5acf8bac78844a0015ecec64d3f85c0546bb3e186eabb19311cb9e33cd6dc64"
+      "sha256": "1b4df0a8cd7dc48f393cd2c3ca7ec91759270c7df87a50397fb3d18d3b6a29fe"
     },
     {
       "path": "tests/discord_autojoin.mjs",
@@ -11557,7 +11562,7 @@
     {
       "path": "tests/init.mjs",
       "mode": "0000644",
-      "sha256": "4a79313db6d6393415ace3e24f985be397156c10845b6543fdfbda3944ddeec0"
+      "sha256": "5b0eaf9cee1a51a4ff41197c4af844a0ba89e5a44f23d0f00de09e5ca8900f08"
     },
     {
       "path": "tests/instance_config.mjs",
@@ -11842,7 +11847,7 @@
     {
       "path": "tests/module_api.mjs",
       "mode": "0000644",
-      "sha256": "ac7d0fd4eb478b79cf9e72994f133e5d6bcca9caef3efd3a388779a18c58292d"
+      "sha256": "53aa3732865dfce17a3216390b057dae825a6a7a8056309f3f31654c06636bee"
     },
     {
       "path": "tests/module_api_lazy.mjs",
@@ -12477,7 +12482,7 @@
     {
       "path": "tests/repo_info_binding.mjs",
       "mode": "0000644",
-      "sha256": "f6a95140fc8e99a7045cf8d3ccc41606fe911138fd915f40061437f2b2cc283a"
+      "sha256": "384a494fab8da8cab77e1241ce8ebd954b658bcc56c578065c6f80bc0fd74f7d"
     },
     {
       "path": "tests/repo_map.mjs",
@@ -12742,7 +12747,7 @@
     {
       "path": "tests/setup_device_flow_fallback.mjs",
       "mode": "0000644",
-      "sha256": "f047b209ec3b0ea2fcffbee7c3b36d8cf01bb18e19cfcfa9d32267db672d834d"
+      "sha256": "f59a1381d0f71f5eb25c8e691cda2347fc34ae2569db191ae074fe2f07c87f1a"
     },
     {
       "path": "tests/setup_smoke.mjs",

package/docs/module-api-changelog.md

@@ -1922,5 +1922,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.722 with no explicit bump. run 34758720786. (task 1002620)
   1.19.724 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.723 with no explicit bump. run 34759302425. (task 1002620)
+  1.19.725 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.724 with no explicit bump. run 34760272743. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/onboarding/approval-broadcast.js

@@ -48,12 +48,39 @@ async function postLine(channel, line, deps = {}) {
   }
 }
 
+// Is the half that CLOSES this loop actually loaded? The line we post invites a 👍,
+// and that reaction is only ever applied by modules/discord/discord-approvals.js —
+// which lives in the `discord` module. onboarding is default-ON and discord is
+// default-OFF, and nothing gated one on the other, so a default instance posted an
+// approve/decline control with nothing listening: an Archon reacts, watches the
+// reaction land, and believes they admitted someone. Nobody is told otherwise.
+//
+// A control that cannot work is worse than no message, so the outbound half now
+// refuses to post without its inbound half. The hall queue is the source of truth
+// either way, so nothing is lost — only a false affordance is withheld.
+// Reached through the published doorway (the one core file a module may require,
+// ADR 0083), never a direct require of src/modules.js. Fails CLOSED: if enablement
+// can't be resolved we do not post, because that is the state we cannot vouch for.
+function discordHandlerLoaded(deps = {}) {
+  try {
+    const isEnabled = deps.isModuleEnabled || require('../../src/module-api').isModuleEnabled;
+    return isEnabled('discord') === true;
+  } catch (_) {
+    return false;
+  }
+}
+
 async function postMemberApprovalRequest(request, deps = {}) {
   if (!request || request.id == null) return { posted: false, skipped: 'no_request' };
+  if (!discordHandlerLoaded(deps)) {
+    (deps.log || console.log)('[gds] approval broadcast: skipped — the `discord` module is off, so no reaction handler would apply a 👍. Approve from the hall queue.');
+    return { posted: false, skipped: 'discord_module_off' };
+  }
   return postLine('member_approvals', memberApprovalLine(request), deps);
 }
 
 module.exports = {
   memberApprovalLine,
   postMemberApprovalRequest,
+  discordHandlerLoaded, // exported for unit tests — the gate is the whole fix
 };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.724",
+  "version": "1.19.725",
   "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/scripts/gds/adopt-preflight.js

@@ -11,11 +11,20 @@
 //     floor (ADR 0043, via gate-review.js's canonical matchesHardFloor).
 //   • CI collisions — the repo's workflows vs core's expected unit/secret-scan/
 //     gate-review checks.
+//   • IGNORED incoming files — a pre-existing .gitignore rule that would swallow what
+//     adopt is about to commit (task 1003400). This is the check that was missing when
+//     Cloud Bongos was adopted onto a repo whose .gitignore already carried `.claude/`:
+//     the skills, hooks and settings.json were materialized onto disk and then dropped
+//     by `git add`, so the adopt commit landed 8 files with no methodology surface at
+//     all. Nothing failed, nothing was logged, and every clone of that repo has been
+//     missing its /builder-* commands since. BLOCKING, because the result is a
+//     non-functional instance that looks fine.
 // READ-ONLY: it computes findings; the accept-gate that decides whether to proceed
 // lives in init.js runAdopt. Pure check functions + a thin fs-reading orchestrator.
 
 const nodeFs = require('node:fs');
 const nodePath = require('node:path');
+const { execFileSync: nodeExecFileSync } = require('node:child_process');
 const { filenameViolation, INSTANCE_NS } = require('./migration-namespace');
 const { matchesHardFloor } = require('./gate-review');
 
@@ -79,10 +88,66 @@ function checkCiCollisions(workflows = []) {
   return [{ category: 'ci', severity: SEV.INFO, message: `${workflows.length} existing CI workflow(s); core will ADD its own unit/secret-scan/gate-review checks alongside them — confirm no required-check conflict.` }];
 }
 
+// PURE — [{ path, rule }] of incoming files a .gitignore rule would swallow → findings.
+// BLOCKING: an ignored incoming file is not a style problem, it is silent data loss at
+// `git add` time, and the instance that results is broken in a way nothing reports.
+function checkIgnoredIncoming(ignored = [], { checked = true } = {}) {
+  if (!checked) {
+    return [{ category: 'ignored-incoming', severity: SEV.INFO, message: 'could not run `git check-ignore` here (no git, or not a repo yet) — cannot confirm the incoming files are committable. Re-check after `git init` if adopt lands nothing under .claude/.' }];
+  }
+  if (!ignored.length) {
+    return [{ category: 'ignored-incoming', severity: SEV.INFO, message: 'no existing ignore rule swallows the files adopt writes — they will all reach the commit.' }];
+  }
+  const lines = ignored.map((i) => (i.rule ? `${i.path} (ignored by ${i.rule})` : i.path));
+  return [{
+    category: 'ignored-incoming',
+    severity: SEV.BLOCK,
+    message: `${ignored.length} file(s) adopt writes are IGNORED by this repo and would be silently dropped from the commit: ${lines.join('; ')}. `
+      + 'Adopt would appear to succeed and produce an instance missing that surface — a repo ignoring `.claude/` gets no /builder-* commands on any clone. '
+      + 'Fix the rule (delete it, or add a negation such as `!.claude/` after it), then re-run.',
+  }];
+}
+
+// Which of `incoming` does this repo's ignore rules match? Uses `git check-ignore -v`,
+// which reports the SOURCE RULE for each match, so the finding can name the exact line
+// the owner has to change rather than leaving them to hunt for it.
+//
+// Returns { ignored:[{path, rule}], checked:boolean }. `checked:false` means the probe
+// could not run at all (no git, not a repo) — deliberately distinct from "nothing is
+// ignored", because the two warrant different advice. execFileSync is injectable for
+// tests; git exits 1 when nothing matches, which is a normal answer and not an error.
+function probeIgnoredIncoming({ dir, incoming = INCOMING_PATHS, execFileSync = nodeExecFileSync } = {}) {
+  // Trailing slashes are ours (they mark dirs in the list); git wants plain pathnames.
+  const paths = incoming.map((p) => String(p).replace(/\/+$/, ''));
+  let out = '';
+  try {
+    out = execFileSync('git', ['check-ignore', '-v', '--stdin'], {
+      cwd: dir, input: paths.join('\n'), encoding: 'utf8', timeout: 5000,
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }) || '';
+  } catch (err) {
+    // Exit 1 = "no path is ignored" (a real answer, stdout empty). Anything else means
+    // the probe itself could not run.
+    if (err && err.status === 1) return { ignored: [], checked: true };
+    return { ignored: [], checked: false };
+  }
+  const ignored = [];
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue;
+    // `<source>:<line>:<pattern>\t<pathname>`
+    const tab = line.lastIndexOf('\t');
+    if (tab === -1) continue;
+    const rule = line.slice(0, tab).trim();
+    const pathname = line.slice(tab + 1).trim();
+    ignored.push({ path: pathname, rule });
+  }
+  return { ignored, checked: true };
+}
+
 // Read the repo (migrations, src/bongos, workflows) and run every check. `stack` is the
 // adopt-detect summary (task 2043); we re-read only what the checks need. Returns
 // { findings, counts:{blocking,warning,info}, hasBlocking }.
-function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath } = {}) {
+function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath, execFileSync = nodeExecFileSync } = {}) {
   const listFiles = (rel) => { try { return fs.readdirSync(path.join(dir, rel)).filter((f) => { try { return fs.statSync(path.join(dir, rel, f)).isFile(); } catch { return false; } }); } catch { return []; } };
   const exists = (rel) => { try { return fs.existsSync(path.join(dir, rel)); } catch { return false; } };
 
@@ -105,6 +170,7 @@ function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath } = {})
     ...checkFitnessBoundary({ topLevelDirs: stack.topLevelDirs || [], hasSrcBongos: exists('src/bongos') }),
     ...checkProtectedPaths(INCOMING_PATHS),
     ...checkCiCollisions(workflows),
+    ...(() => { const { ignored, checked } = probeIgnoredIncoming({ dir, execFileSync }); return checkIgnoredIncoming(ignored, { checked }); })(),
   ];
   const counts = { blocking: 0, warning: 0, info: 0 };
   for (const f of findings) counts[f.severity === SEV.BLOCK ? 'blocking' : f.severity === SEV.WARN ? 'warning' : 'info']++;
@@ -118,4 +184,4 @@ function formatPreflight(report) {
   return report.findings.map((f) => `  ${mark[f.severity] || '·'}  [${f.category}] ${f.message}`);
 }
 
-module.exports = { preflightAdopt, formatPreflight, checkMigrationNamespace, checkFitnessBoundary, checkProtectedPaths, checkCiCollisions, INCOMING_PATHS, CORE_EXPECTED_CHECKS, SEV };
+module.exports = { preflightAdopt, formatPreflight, checkMigrationNamespace, checkFitnessBoundary, checkProtectedPaths, checkCiCollisions, checkIgnoredIncoming, probeIgnoredIncoming, INCOMING_PATHS, CORE_EXPECTED_CHECKS, SEV };

package/scripts/gds/build-cli-package.js

@@ -51,6 +51,7 @@ const FILES = [
   'scripts/gds/login.js',
   'scripts/gds/reauth.js',
   'scripts/gds/setup.js',
+  'scripts/gds/device-flow-help.js', // shared leaf: login.js + setup.js both require it (task 1003881)
   'scripts/gds/onboarding-config.js', // lazy dep of setup.js
   'scripts/gds/install-git-hooks.js', // lazy dep of setup.js
   'scripts/gds/preflight.js',

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

@@ -12,6 +12,14 @@
 // of a mature instance's CLAUDE.md — the instance grows its own. Coordinates with
 // task 1963 (neutralizing the core's own CLAUDE.md into the portable template).
 //
+// FIRST-RUN SECTION. The template used to open by instructing the agent to run
+// `bongos start` without ever saying the CLI ships inside an uninstalled dependency,
+// so an agent opening a fresh clone followed its first instruction straight into
+// `command not found`. The root README carries the same signpost for humans — but only
+// when the repo had no README to begin with, which an ADOPTED repo always does. This
+// file lands on BOTH paths and loads in full every session, so it is the one place the
+// bootstrap is guaranteed to be read.
+//
 // PURE (branding in → markdown out), so it unit-tests standalone and carries no
 // hardcoded host identity (everything comes from the branding object — R76-safe).
 
@@ -48,6 +56,16 @@ 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
+
+**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\`:
+
+\`\`\`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.
+
 ## What this is
 
 ${ident}

package/scripts/gds/device-flow-help.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/device-flow-help.js — the one explanation of a Device-Flow refusal, shared
+// by `bongos setup` and `bongos login` (task 1003400).
+//
+// WHY IT EXISTS AT ALL. GitHub creates an App from a manifest with Device Flow OFF and
+// exposes no API to switch it on — only a checkbox in the App's settings. So on every
+// wizard-born instance the documented terminal sign-in is hard-broken from birth, for
+// every builder, until the owner ticks that box. Nothing in the product can do it for
+// them; the least we can do is say so precisely, and name a route that works meanwhile.
+//
+// WHY IT IS ITS OWN FILE. setup.js grew the detector + the guidance first; login.js threw
+// a bare "could not start sign-in (HTTP 424)" — a dead end sitting directly downstream of
+// the CLI's OWN wrong-instance advice to run `bongos login`. setup.js already requires
+// login.js for runDeviceFlow, so having login.js require setup.js back would close a
+// require cycle. Both now depend on this leaf instead: one source of truth, no cycle.
+//
+// PURE — no fs, no network, no process state; both functions unit-test standalone.
+
+// Does this /auth/device/start response carry GitHub's device_flow_disabled refusal?
+//
+// Matches on TEXT, not status, deliberately: the CLI talks to many core versions, and the
+// server envelope moved from 502 to 424 (a 502 body was being eaten by the CDN). Both
+// register. Must NOT match auth_not_configured or any other upstream failure — those have
+// different cures, and a wrong cure is worse than a generic error.
+function isDeviceFlowDisabled(start) {
+  if (!start || start.ok) return false;
+  const err = start.data && start.data.error;
+  const text = [
+    typeof err === 'string' ? err : '',
+    err && typeof err === 'object' ? `${err.code || ''} ${err.message || ''}` : '',
+    start.data && start.data.message ? String(start.data.message) : '',
+  ].join(' ');
+  return /device_flow_disabled/i.test(text);
+}
+
+// The plain-language guidance: what happened, the web route that works RIGHT NOW, and the
+// owner's one-checkbox repair. Returns an array of lines (the callers join them).
+//
+// `finish` names the caller, because only the closing move differs: setup prompts for the
+// token inline ("paste it below"), login has no such prompt and must tell you to run the
+// one-liner instead. Everything above that step is genuinely shared and stays shared.
+function deviceFlowFallbackLines(base, { finish = 'setup' } = {}) {
+  const settings = `${base}/builders/settings`;
+  const close = finish === 'login'
+    ? [
+      '  3. Copy the one-liner it shows and run it in this shell — that writes',
+      '     the same session `bongos login` would have.',
+    ]
+    : [
+      '  3. Copy the token it shows and paste it below (or run the printed',
+      '     one-liner in another shell, then re-run setup).',
+    ];
+  return [
+    '',
+    "This project's GitHub App has Device Flow switched off, so terminal sign-in",
+    'cannot start. Apps created by the one-click setup begin this way — GitHub',
+    'only offers the switch as a checkbox in the App settings; no setup flow can',
+    'tick it automatically.',
+    '',
+    'Sign in through the web instead (works right now):',
+    `  1. Open ${settings} and sign in with GitHub.`,
+    '  2. Under "CLI Access", click "Re-issue CLI token".',
+    ...close,
+    '',
+    'To repair terminal sign-in for everyone (the project owner, once):',
+    '  GitHub → Settings → Developer settings → GitHub Apps → your app →',
+    '  check "Enable Device Flow" → Save. Web sign-in is unaffected either way.',
+  ];
+}
+
+module.exports = { isDeviceFlowDisabled, deviceFlowFallbackLines };

package/scripts/gds/init.js

@@ -525,6 +525,62 @@ function buildReadme(branding = {}) {
   ].join('\n');
 }
 
+// The START-HERE content as an APPENDABLE section, for a repo that already has a
+// README of its own. Fenced by a stable marker so re-running init is idempotent and so
+// an owner can find (and delete) the block we added.
+//
+// WHY this is not just buildReadme: an ADOPTED repo always has a README, and the
+// write-if-absent rule below therefore skipped the first-run guide on every single adopt
+// — silently, logging "already present — left untouched" as though nothing were owed.
+// That removed the one human-facing instruction to run `npm install`, without which the
+// repo has no `bongos` command at all. Appending mirrors how the adopt path already
+// treats .gitignore: keep what the owner wrote, add only what the instance needs.
+const README_MARKER = '<!-- cloud-bongos:start-here -->';
+
+function buildReadmeSection(branding = {}) {
+  const guide = buildReadme(branding);
+  // Reuse the canonical guide, demoted one heading level so it nests under the owner's
+  // own README, and drop its H1 title (their README already has one).
+  const body = guide
+    .split('\n')
+    .slice(1)                                   // drop "# <product>"
+    .join('\n')
+    .replace(/^## /gm, '### ')
+    .trim();
+  return `${README_MARKER}\n\n## Working on this project (Cloud Bongos)\n\n${body}\n`;
+}
+
+// Append the START-HERE section to an existing README unless it is already there.
+// PURE (text in → text out) so the idempotence is unit-testable without fs.
+// Returns { text, action } where action is 'appended' | 'present'.
+function appendReadmeSection(existing, section) {
+  const prev = String(existing == null ? '' : existing);
+  if (prev.includes(README_MARKER)) return { text: prev, action: 'present' };
+  return { text: `${prev.replace(/\n*$/, '\n')}\n---\n\n${section}`, action: 'appended' };
+}
+
+// Put the first-run guide in the repo's README whichever state it is in: mint the whole
+// guide when there is no README, else append the marked section. Shared by the greenfield
+// and adopt paths so neither can silently owe it. Returns the action taken.
+function layerReadme(branding, { dir, dryRun, log = console.log } = {}) {
+  const readmePath = path.join(dir, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    if (dryRun) { log(`  [dry-run] would write README.md (first-run START-HERE)`); return 'created'; }
+    fs.writeFileSync(readmePath, buildReadme(branding));
+    log(`  ✓ wrote README.md (first-run START-HERE)`);
+    return 'created';
+  }
+  const { text, action } = appendReadmeSection(fs.readFileSync(readmePath, 'utf8'), buildReadmeSection(branding));
+  if (action === 'present') {
+    log('  • README.md already carries the Cloud Bongos start-here section — left untouched.');
+    return 'present';
+  }
+  if (dryRun) { log('  [dry-run] would append the Cloud Bongos start-here section to the existing README.md'); return 'appended'; }
+  fs.writeFileSync(readmePath, text);
+  log('  ✓ appended the Cloud Bongos start-here section to README.md (your own content is untouched)');
+  return 'appended';
+}
+
 function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log }) {
   const configDir = path.join(dir, 'config');
   const brandingPath = path.join(configDir, 'branding.json');
@@ -572,14 +628,9 @@ function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })
   log(`  ✓ wrote ${path.relative(dir, modulesPath)}`);
   log(`  ✓ wrote ${path.relative(dir, hierarchyPath)}`);
   log(`  ✓ wrote ${path.relative(dir, pkgPath)} (pins ${CORE_PKG} → ${pinNote})`);
-  // README START-HERE (task 1002404): write-if-absent so a --force re-init or an
-  // owner's own README is never clobbered.
-  if (!fs.existsSync(readmePath)) {
-    fs.writeFileSync(readmePath, buildReadme(branding));
-    log(`  ✓ wrote ${path.relative(dir, readmePath)} (first-run START-HERE)`);
-  } else {
-    log(`  • ${path.relative(dir, readmePath)} already present — left untouched`);
-  }
+  // README START-HERE (task 1002404): mint it when absent, else APPEND the marked
+  // section. Never a blind overwrite — an owner's own README content always survives.
+  layerReadme(branding, { dir, dryRun: false, log });
   return { brandingPath, modulesPath, hierarchyPath, pkgPath, readmePath, wrote: true };
 }
 
@@ -816,6 +867,10 @@ async function runAdopt(spec, { dir, dryRun, noSeed = false, accept = false, cor
 
   const cfg = layerConfigs(spec, { dir, dryRun, log });
   const pkg = layerPackageJson(spec, { dir, dryRun, log, ...(coreDep ? { coreRange: coreDep } : {}) });
+  // The first-run guide, which adopt used to skip entirely: an adopted repo always has a
+  // README, so the greenfield write-if-absent rule never fired and the one instruction to
+  // run `npm install` was silently owed on every adopt.
+  layerReadme(buildBrandingConfig(spec), { dir, dryRun, log });
 
   // Vendor the pinned core tarball + generate the lockfile, mirroring the greenfield
   // --vendor-core steps, so the adopted repo is `npm ci --omit=dev`-installable (ADR 0108).
@@ -1061,6 +1116,7 @@ module.exports = {
   provisioningSlug, provisioningRequest, productionTopologyKickoff,
   // --adopt (brownfield layering, ADR 0121 / task 2042)
   mergeCoreDependency, coreDepRange, layerConfigs, layerPackageJson, runAdopt,
+  buildReadmeSection, appendReadmeSection, layerReadme, README_MARKER,
   KNOWN_MODULES, HOSTING_SHAPES, CORE_PKG,
   // greenfield installability (ADR 0108 gap 1/4, task 2053)
   buildInstancePackageJson, coreVersionSafe, INSTANCE_START_SCRIPT, INSTANCE_MIGRATE_SCRIPT,

package/scripts/gds/login.js

@@ -23,6 +23,10 @@
 const readline = require('node:readline');
 const { spawnSync } = require('node:child_process');
 const { saveSession, loadStoredSession, listStoredSessions } = require('./cli-lib');
+// The device-flow refusal detector + its plain-language cure (task 1003400). A leaf
+// module, NOT setup.js: setup requires this file for runDeviceFlow, so requiring it
+// back would close a require cycle. Both callers depend on the leaf instead.
+const { isDeviceFlowDisabled, deviceFlowFallbackLines } = require('./device-flow-help');
 const { branding } = require('../../src/branding');
 
 // --- pure helpers (unit-tested) ---------------------------------------------
@@ -102,6 +106,20 @@ async function runDeviceFlow(base, { log, idp = null }) {
   if (start.status === 503 || (start.data && (start.data.error === 'auth_not_configured' || (start.data.error && start.data.error.code === 'idp_signing_unconfigured')))) {
     throw new Error('that instance has no sign-in configured yet — ask its Archon to set it up.');
   }
+  // Device Flow is OFF on every GitHub App born from a manifest, and GitHub exposes no
+  // API to enable it — so terminal sign-in is broken from birth on a fresh instance,
+  // for everyone, until its owner ticks one checkbox. This threw a bare
+  // "could not start sign-in (HTTP 424)", which is where the CLI's OWN wrong-instance
+  // refusal sends every multi-project user: a dead end at the end of our own advice.
+  // In federated mode the device flow runs against the HUB, so the cure is on the hub's
+  // app — point the guidance at whichever origin actually refused.
+  if (isDeviceFlowDisabled(start)) {
+    const refusedBy = idp ? idp.origin : base;
+    throw new Error([
+      'GitHub refused the device-code request for this project.',
+      ...deviceFlowFallbackLines(refusedBy, { finish: 'login' }),
+    ].join('\n'));
+  }
   if (!start.ok || !start.data || !start.data.device_code) {
     throw new Error(`could not start sign-in (HTTP ${start.status}).`);
   }

package/scripts/gds/setup.js

@@ -274,45 +274,11 @@ async function promptOnboardingConsent() {
 }
 
 // ── W1: the manifest-born App has Device Flow OFF (task 1003051) ─────────────
-// GitHub creates an App from a manifest with Device Flow unchecked and offers
-// no API to enable it (only a settings checkbox), so on a fresh wizard-born
-// instance the documented CLI sign-in is hard-broken until the owner ticks the
-// box. Detect the proxied refusal (POST /auth/device/start surfaces GitHub's
-// device_flow_disabled — task 2126's envelope) and fall back to the hall's
-// CLI-token path so setup still completes. Pure; exported for tests.
-function isDeviceFlowDisabled(start) {
-  if (!start || start.ok) return false;
-  const err = start.data && start.data.error;
-  const text = [
-    typeof err === 'string' ? err : '',
-    err && typeof err === 'object' ? `${err.code || ''} ${err.message || ''}` : '',
-    start.data && start.data.message ? String(start.data.message) : '',
-  ].join(' ');
-  return /device_flow_disabled/i.test(text);
-}
-
-// The plain-language fallback guidance (task 1003051): what happened, the web
-// path that works right now, and the one-checkbox owner fix. Pure; exported.
-function deviceFlowFallbackLines(base) {
-  const settings = `${base}/builders/settings`;
-  return [
-    '',
-    "This project's GitHub App has Device Flow switched off, so terminal sign-in",
-    'cannot start. Apps created by the one-click setup begin this way — GitHub',
-    'only offers the switch as a checkbox in the App settings; no setup flow can',
-    'tick it automatically.',
-    '',
-    'Sign in through the web instead (works right now):',
-    `  1. Open ${settings} and sign in with GitHub.`,
-    '  2. Under "CLI Access", click "Re-issue CLI token".',
-    '  3. Copy the token it shows and paste it below (or run the printed',
-    '     one-liner in another shell, then re-run setup).',
-    '',
-    'To repair terminal sign-in for everyone (the project owner, once):',
-    '  GitHub → Settings → Developer settings → GitHub Apps → your app →',
-    '  check "Enable Device Flow" → Save. Web sign-in is unaffected either way.',
-  ];
-}
+// The detector + the guidance moved to ./device-flow-help (task 1003400) so
+// `bongos login` can use the same words without closing a require cycle back
+// through this file (setup requires login for runDeviceFlow). Re-exported here
+// because both are part of setup.js's tested public surface.
+const { isDeviceFlowDisabled, deviceFlowFallbackLines } = require('./device-flow-help');
 
 // Verify a hall-minted CLI token against /me and save the session (the
 // paste-token.js contract: nothing is written unless the token verifies).

package/src/bongos/repo-info.js

@@ -12,10 +12,11 @@
 // transfers, the deploy's git remote changes and the served links follow,
 // with zero code edits required.
 //
-// Cached on first call. Falls back to env vars (OTB_GITHUB_OWNER /
-// OTB_GITHUB_REPO / OTB_GITHUB_BRANCH) for environments where git isn't
-// available (e.g. a stripped-down container deploy). Returns { error } when
-// neither source resolves, so callers can degrade gracefully.
+// Cached on first call. Three sources, in order: env vars (OTB_GITHUB_OWNER /
+// OTB_GITHUB_REPO / OTB_GITHUB_BRANCH — the operator's explicit override), the git
+// remote when this package IS the repo, then the instance's committed branding pack
+// (config/branding.json `repo`) — the source a standalone instance actually has.
+// Returns { error } when none resolves, so callers can degrade gracefully.
 
 const { execSync } = require('node:child_process');
 const path = require('node:path');
@@ -44,6 +45,34 @@ function loadFromEnv() {
   return null;
 }
 
+// The instance's OWN declared GitHub binding, read from the committed branding pack
+// (`config/branding.json` -> `repo: { owner, name }` — a first-class key in the
+// branding contract). `bongos init` writes it at scaffold time, so a standalone
+// instance carries the correct answer on disk from birth.
+//
+// WHY it exists: an installed core (ADR 0140) lives in node_modules/@bongos/core, so
+// loadFromGit's anchor rule correctly returns null — and nothing sets
+// <PREFIX>_GITHUB_OWNER/REPO on a provisioned instance. EVERY standalone instance
+// therefore resolved no_repo_info and served a 503 from /public/repo-info, with public
+// build status and every repo-linked surface dead. The identity was one file away the
+// whole time, simply never read.
+//
+// Placed LAST in the chain on purpose: the env pin stays the operator's explicit
+// override and git stays authoritative for the core dev checkout, so this source can
+// only ever turn an ERROR into an answer — it can never change one that already
+// resolved. Required lazily so module load order never depends on branding, and
+// fail-soft: a malformed or absent pack must degrade to no_repo_info, not crash boot.
+function loadFromBranding(deps = {}) {
+  try {
+    const read = deps.branding || require('../branding').branding;
+    const pack = read() || {};
+    const owner = pack.repo && String(pack.repo.owner || '').trim();
+    const name = pack.repo && String(pack.repo.name || '').trim();
+    if (owner && name) return { owner, repo: name };
+  } catch (_) { /* fall through — an unreadable pack is not an answer */ }
+  return null;
+}
+
 // The directory this file's package occupies: <root>/src/bongos -> <root>. In the core
 // dev checkout that is the repo root; installed, it is node_modules/@bongos/core.
 const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
@@ -92,12 +121,13 @@ function loadFromGit(deps = {}) {
 function loadRepoInfo(deps = {}) {
   if (cached) return cached;
   const branch = ic.resolveEnv('GITHUB_BRANCH') || 'main';
-  const parsed = loadFromEnv() || loadFromGit(deps);
+  const parsed = loadFromEnv() || loadFromGit(deps) || loadFromBranding(deps);
   if (!parsed) {
     cached = {
       error: 'no_repo_info',
       detail:
-        'git remote origin not resolvable from this package (an installed core does not sit inside the repo it publishes to) and <PREFIX>_GITHUB_OWNER/REPO unset',
+        'git remote origin not resolvable from this package (an installed core does not sit inside the repo it publishes to), '
+        + 'config/branding.json has no repo.owner/repo.name, and <PREFIX>_GITHUB_OWNER/REPO unset',
     };
     return cached;
   }
@@ -123,5 +153,6 @@ module.exports = {
   loadRepoInfo,
   parseRemote,
   loadFromGit, // exported for unit tests — the anchor rule is the whole fix
+  loadFromBranding, // exported for unit tests — the standalone-instance source
   _resetCacheForTests,
 };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.724'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.725'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');
@@ -427,6 +427,13 @@ module.exports = {
   //     directly. Resolved lazily so requiring the doorway never forces a config
   //     read at module-load (BV1.R81 / ADR 0093 §1).
   enabledDisciplines: (...a) => require('./modules').enabledDisciplines(...a),
+  //     isModuleEnabled(name) — is THIS module on for this instance? A module needs
+  //     it when its own behaviour depends on ANOTHER module being present: onboarding
+  //     posts a Discord approve/decline control whose 👍 is only ever applied by the
+  //     `discord` module's reaction handler, so with discord off the control is a lie
+  //     and must not be posted at all. Throws on an unknown name (a typo is a bug, not
+  //     a silent false). Lazy, like its sibling above.
+  isModuleEnabled: (...a) => require('./modules').isModuleEnabled(...a),
 
   // --- the seam registry — how modules cooperate without importing each other.
   //     Three primitives: PORTS (one required provider), EVENTS (many optional

package/tests/adopt_preflight.mjs

@@ -101,5 +101,77 @@ t('preflightAdopt: a clean repo → no blocking; every category reports', () =>
   } finally { rmSync(dir, { recursive: true, force: true }); }
 });
 
+// ---- ignored-incoming: the check that was missing (task 1003400) ----------
+//
+// The failure it exists to stop: adopt onto a repo whose .gitignore already carries
+// `.claude/`. The skills/hooks/settings are written to disk, `git add` drops them, the
+// commit looks clean, and every clone of that repo is missing its /builder-* commands
+// with nothing anywhere saying why.
+
+t('checkIgnoredIncoming: an ignored incoming file BLOCKS and names the rule to change', () => {
+  const f = pf.checkIgnoredIncoming([{ path: '.claude/skills', rule: '.gitignore:7:.claude/' }]);
+  assert.equal(f.length, 1);
+  assert.equal(f[0].severity, pf.SEV.BLOCK, 'silent data loss at git add is not a warning');
+  assert.match(f[0].message, /\.claude\/skills/, 'names the swallowed path');
+  assert.match(f[0].message, /\.gitignore:7/, 'names the exact rule line so the owner need not hunt');
+});
+
+t('checkIgnoredIncoming: nothing ignored → INFO, not blocking', () => {
+  const f = pf.checkIgnoredIncoming([]);
+  assert.equal(f[0].severity, pf.SEV.INFO);
+  assert.equal(f.filter((x) => x.severity === pf.SEV.BLOCK).length, 0);
+});
+
+t('checkIgnoredIncoming: probe could not run → INFO that says so, never a false all-clear', () => {
+  const f = pf.checkIgnoredIncoming([], { checked: false });
+  assert.equal(f[0].severity, pf.SEV.INFO);
+  assert.match(f[0].message, /could not run/, 'unknown must not be reported as clean');
+});
+
+t('probeIgnoredIncoming: parses git check-ignore -v into path + rule', () => {
+  const execFileSync = () => '.gitignore:7:.claude/\t.claude/skills\n.gitignore:7:.claude/\t.claude/hooks\n';
+  const { ignored, checked } = pf.probeIgnoredIncoming({ dir: '/x', execFileSync });
+  assert.equal(checked, true);
+  assert.deepEqual(ignored, [
+    { path: '.claude/skills', rule: '.gitignore:7:.claude/' },
+    { path: '.claude/hooks', rule: '.gitignore:7:.claude/' },
+  ]);
+});
+
+t('probeIgnoredIncoming: git exit 1 means NOTHING ignored — a real answer, not a failure', () => {
+  const execFileSync = () => { const e = new Error('exit 1'); e.status = 1; throw e; };
+  assert.deepEqual(pf.probeIgnoredIncoming({ dir: '/x', execFileSync }), { ignored: [], checked: true });
+});
+
+t('probeIgnoredIncoming: no git / not a repo → checked:false, distinct from "clean"', () => {
+  const execFileSync = () => { const e = new Error('not a git repository'); e.status = 128; throw e; };
+  assert.deepEqual(pf.probeIgnoredIncoming({ dir: '/x', execFileSync }), { ignored: [], checked: false });
+});
+
+t('probeIgnoredIncoming: strips our trailing dir slashes before handing paths to git', () => {
+  let input = null;
+  const execFileSync = (_cmd, _args, opts) => { input = opts.input; return ''; };
+  pf.probeIgnoredIncoming({ dir: '/x', incoming: ['.claude/hooks/', 'package.json'], execFileSync });
+  assert.equal(input, '.claude/hooks\npackage.json', 'git check-ignore wants plain pathnames');
+});
+
+t('preflightAdopt (end to end): mercury\'s .gitignore would have BLOCKED the adopt', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'pf-ignored-'));
+  try {
+    // The exact rule that swallowed the methodology surface on the real repo.
+    writeFileSync(join(dir, '.gitignore'), '.env\nvenv/\n\n#claude code\n.claude/\n');
+    const report = pf.preflightAdopt({
+      dir,
+      stack: { migrationsDirs: [], topLevelDirs: [], ci: [] },
+      // Stand in for git so the case is hermetic (no repo needed in tmp).
+      execFileSync: () => '.gitignore:5:.claude/\t.claude/settings.json\n.gitignore:5:.claude/\t.claude/skills\n',
+    });
+    assert.ok(report.hasBlocking, 'adopt must stop rather than produce a silently broken instance');
+    const found = cats(report.findings, 'ignored-incoming');
+    assert.equal(found.length, 1);
+    assert.equal(found[0].severity, pf.SEV.BLOCK);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
 console.log(`\nadopt_preflight: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/bongos_login.mjs

@@ -1,11 +1,20 @@
-// tests/bongos_login.mjs — pure helpers behind `bongos login <instance>`
-// (V4.R83 / task 1250). DB-free + network-free. Picked up by run-unit-tests.js.
+// tests/bongos_login.mjs — the helpers and the failure surface behind
+// `bongos login <instance>` (V4.R83 / task 1250). DB-free; the one end-to-end case
+// drives the real CLI against a 127.0.0.1 stub, so it needs no network either.
+// Picked up by run-unit-tests.js.
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const { normalizeInstanceBase, pollDecision } = require('../scripts/gds/login.js');
+const LOGIN_JS = path.join(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'), 'scripts', 'gds', 'login.js');
 
 test('normalizeInstanceBase adds https, strips trailing slashes + a pasted /api/gds', () => {
   assert.equal(normalizeInstanceBase('amazonprimea.com'), 'https://amazonprimea.com');
@@ -32,3 +41,61 @@ test('pollDecision maps the /access-requests/status body to a loop action', () =
   assert.equal(pollDecision(null), 'wait');
   assert.equal(pollDecision({}), 'wait');
 });
+
+// ---- the Device-Flow dead end (task 1003400) -------------------------------
+//
+// Device Flow is OFF on every GitHub App created from a manifest and GitHub offers no
+// API to switch it on, so terminal sign-in is broken from birth on a fresh instance —
+// for every builder. `bongos login` used to answer that with a bare
+// "could not start sign-in (HTTP 424)": no cause, no cure, and sitting directly
+// downstream of the CLI's own wrong-instance advice to run `bongos login`.
+//
+// Drives the REAL CLI against a stub replaying the exact body a live instance returned.
+
+test('login on a Device-Flow-disabled instance explains the cause and the cure', async () => {
+  const server = http.createServer((req, res) => {
+    const send = (code, body) => {
+      res.writeHead(code, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(body));
+    };
+    if (req.url.endsWith('/api/gds/instance')) {
+      return send(200, { schema: 'instance-manifest/v1', name: 'Stub', admission: { policy: 'invite-only' } });
+    }
+    if (req.url.endsWith('/api/gds/auth/device/start')) {
+      // Byte-for-byte what a real instance returned when its App had the box unticked.
+      return send(424, { error: { code: 'device_start_failed', message: 'device/code failed (400): {"error":"device_flow_disabled","error_description":"Device Flow must be explicitly enabled for this App"}' } });
+    }
+    return send(404, { error: { code: 'not_found' } });
+  });
+  server.listen(0, '127.0.0.1');
+  await new Promise((r) => server.once('listening', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  // A throwaway HOME so the run can never read or write the real session.
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'login-df-'));
+
+  // spawn, not execFileSync: the stub server lives in THIS process, so a synchronous
+  // child would block the event loop that has to answer it — a deadlock, not a failure.
+  let out = '';
+  try {
+    out = await new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, [LOGIN_JS, base], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, HOME: home, USERPROFILE: home },
+      });
+      let buf = '';
+      child.stdout.on('data', (d) => { buf += d; });
+      child.stderr.on('data', (d) => { buf += d; });
+      const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('login did not exit')); }, 30000);
+      child.on('close', () => { clearTimeout(timer); resolve(buf); });
+      child.on('error', (e) => { clearTimeout(timer); reject(e); });
+    });
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+
+  assert.doesNotMatch(out, /could not start sign-in \(HTTP 424\)/, 'the bare dead end is gone');
+  assert.match(out, /Device Flow switched off/, 'names the actual cause');
+  assert.match(out, /Enable Device Flow/, 'names the owner\'s one-checkbox repair');
+  assert.match(out, /works right now/, 'names a route that works while the owner fixes it');
+});

package/tests/claude_materialize.mjs

@@ -510,6 +510,15 @@ t('renderInstanceClaudeMd: brand-substituted — names the instance + its hall/c
   assert.ok(!md.toLowerCase().includes('amazonprimea') && !md.includes('~/.config/otb'), 'no founder literal in the starter');
 });
 
+t('renderInstanceClaudeMd: the first-run bootstrap precedes every bongos instruction', () => {
+  const md = tmpl.renderInstanceClaudeMd({ identity: { productName: 'Acme' } });
+  const iNpm = md.indexOf('npm install');
+  const iStart = md.indexOf('bongos start');
+  assert.ok(iNpm > 0, 'names npm install at all — without it a fresh clone has no bongos command');
+  assert.ok(iStart > iNpm, 'npm install comes BEFORE the first bongos instruction, or the agent hits command not found');
+  assert.ok(/@bongos\/core/.test(md), 'explains WHY: the CLI ships inside the dependency');
+});
+
 t('renderInstanceClaudeMd: degrades cleanly on a minimal branding (no world dup, defaults currency)', () => {
   const md = tmpl.renderInstanceClaudeMd({ identity: { productName: 'Solo', worldName: 'Solo' } });
   assert.ok(md.startsWith('# Solo — Project Memory'));

package/tests/discord_approvals.mjs

@@ -170,5 +170,50 @@ await t('a DB error returns {error}, never throws', async () => {
   assert.equal(r.outcome, 'error');
 });
 
+// ---- the outbound half must not outlive the inbound half (task 1003400) ----
+//
+// The 👍 this line invites is applied ONLY by discord-approvals.js, which lives in the
+// `discord` module. onboarding (which posts) is default-ON; discord is default-OFF; and
+// nothing gated one on the other. A default instance therefore posted a working-looking
+// approve/decline control into a channel where no handler was listening — an Archon
+// reacts, sees it land, and believes they admitted a builder who is still locked out.
+
+await t('discord module OFF → the control is NOT posted', async () => {
+  let posted = false;
+  const r = await bcast.postMemberApprovalRequest(
+    { id: 7, github_login: 'carol' },
+    { postWebhook: async () => { posted = true; }, log: () => {}, isModuleEnabled: () => false },
+  );
+  assert.equal(posted, false, 'a 👍 nobody applies must never be invited');
+  assert.equal(r.skipped, 'discord_module_off');
+  assert.equal(r.posted, false);
+});
+
+await t('discord module ON → the control posts exactly as before', async () => {
+  let line = null;
+  const r = await bcast.postMemberApprovalRequest(
+    { id: 7, github_login: 'carol' },
+    { postWebhook: async (_ch, l) => { line = l; }, log: () => {}, isModuleEnabled: () => true },
+  );
+  assert.equal(r.posted, true, 'the working path is untouched');
+  assert.deepEqual(ap.parseApprovalMarker(line), { kind: 'member', id: 7 }, 'and still round-trips');
+});
+
+await t('enablement unresolvable → fails CLOSED (no post)', async () => {
+  let posted = false;
+  const r = await bcast.postMemberApprovalRequest(
+    { id: 7, github_login: 'carol' },
+    { postWebhook: async () => { posted = true; }, log: () => {}, isModuleEnabled: () => { throw new Error('config unreadable'); } },
+  );
+  assert.equal(posted, false, 'a state we cannot vouch for is not a state we post into');
+  assert.equal(r.skipped, 'discord_module_off');
+});
+
+await t('the gate is reachable through the published doorway, not a direct core require', async () => {
+  const doorway = require('../src/module-api.js');
+  assert.equal(typeof doorway.isModuleEnabled, 'function', 'ADR 0083: modules read enablement here');
+  assert.throws(() => doorway.isModuleEnabled('no-such-module'), /unknown module/, 'a typo must be a bug, not a silent false');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/init.mjs

@@ -535,10 +535,60 @@ test('writeConfigs (greenfield): writes a root README START-HERE, never clobberi
     const md = readFileSync(res.readmePath, 'utf8');
     assert.ok(/## Start here/.test(md) && md.includes('npm install'), 'is the START-HERE guide');
 
-    // A --force re-init must NOT clobber a README the owner has since edited.
+    // A --force re-init must NOT clobber a README the owner has since edited. It APPENDS
+    // the start-here section instead of skipping (the old behaviour silently owed the
+    // `npm install` instruction to every repo that already had a README).
     writeFileSync(res.readmePath, '# my own readme\n');
     init.writeConfigs(fullSpec(), { dir, force: true, dryRun: false, log: () => {} });
-    assert.equal(readFileSync(res.readmePath, 'utf8'), '# my own readme\n', 'existing README left untouched on --force');
+    const after = readFileSync(res.readmePath, 'utf8');
+    assert.ok(after.startsWith('# my own readme\n'), 'the owner\'s own README content is never clobbered');
+    assert.ok(after.includes('npm install'), 'and the first-run instruction is still delivered');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('appendReadmeSection: appends once, then is idempotent', () => {
+  const section = init.buildReadmeSection({ identity: { productName: 'Mercury' } });
+  const own = '# hermes_inventory_management\nInventory Management\n';
+  const first = init.appendReadmeSection(own, section);
+  assert.equal(first.action, 'appended');
+  assert.ok(first.text.startsWith(own), 'the owner\'s content stays at the top, byte-identical');
+  assert.ok(first.text.includes('npm install'), 'delivers the first-run instruction');
+
+  const second = init.appendReadmeSection(first.text, section);
+  assert.equal(second.action, 'present', 're-running init must not stack duplicate sections');
+  assert.equal(second.text, first.text, 'and must not rewrite the file at all');
+});
+
+test('buildReadmeSection: nests under the owner\'s README — no second H1', () => {
+  const section = init.buildReadmeSection({ identity: { productName: 'Mercury' } });
+  assert.ok(!/^# /m.test(section), 'no H1 that would compete with the owner\'s title');
+  assert.ok(section.includes(init.README_MARKER), 'carries the marker that makes re-runs idempotent');
+});
+
+test('layerReadme (adopt): an existing README GETS the start-here section, not a skip', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'adopt-readme-'));
+  try {
+    // The exact shape that broke: a brownfield repo whose own README predates adoption.
+    writeFileSync(join(dir, 'README.md'), '# hermes_inventory_management\nInventory Management\n');
+    const action = init.layerReadme({ identity: { productName: 'Mercury' } }, { dir, dryRun: false, log: () => {} });
+    assert.equal(action, 'appended');
+    const md = readFileSync(join(dir, 'README.md'), 'utf8');
+    assert.ok(md.startsWith('# hermes_inventory_management'), 'owner content preserved');
+    assert.ok(md.includes('npm install'), 'THE FIX: adopt no longer silently owes the first-run guide');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('layerReadme (dry-run): reports the append but writes nothing', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'adopt-readme-dry-'));
+  try {
+    writeFileSync(join(dir, 'README.md'), '# mine\n');
+    const action = init.layerReadme({ identity: { productName: 'Mercury' } }, { dir, dryRun: true, log: () => {} });
+    assert.equal(action, 'appended');
+    assert.equal(readFileSync(join(dir, 'README.md'), 'utf8'), '# mine\n', 'dry-run writes nothing');
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }

package/tests/module_api.mjs

@@ -48,6 +48,7 @@ const PUBLISHED_SURFACE = [
   'artistGate', // added by task 1003575 (ADR 0241): the artist gate — off | advisory | strict, plus the pure verdict helpers over it. Two modules ask it two different questions ("file this review?" and "does an open one hold the deploy?") and both must resolve the knob through this one reader, never branding().project
   'readApplicantProfileFromHub', // added by task 1002972 (privacy spec D7): the reviewer queue's LIVE per-render read of one applicant's hub profile view. NARROW by design — the underlying call is authenticated with this instance's hub client secret, and loadIdpConfig stays OFF the doorway so no module ever holds the credential that speaks for the whole project
   'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
+  'isModuleEnabled', // task 1003400: is ANOTHER module present? onboarding's Discord approve/decline control is only actionable when the `discord` module's reaction handler is loaded, so the posting half has to be able to ask
   'registerProvider', 'hasProvider', 'resolve', 'resolveOptional', 'listPorts', 'verifyPortsSatisfied',
   'on', 'emit', 'emitAsync', 'listEvents', 'seamSnapshot',
   'contribute', 'contributions', 'collectContributions', 'listContributionPoints',

package/tests/repo_info_binding.mjs

@@ -208,6 +208,88 @@ test('a good bind still produces the blob/tree bases callers rely on', () => {
   }
 });
 
+// ---- loadFromBranding: the source a standalone instance actually has -------
+//
+// An installed core sits in node_modules/@bongos/core, so loadFromGit correctly refuses
+// and nothing sets the env pin — which meant EVERY standalone instance served a 503 from
+// /public/repo-info while `config/branding.json` held the answer. These cases pin the new
+// source AND, just as importantly, pin that it did not disturb the two above it.
+
+const PACK = { repo: { owner: FIXTURE_OWNER, name: FIXTURE_REPO } };
+
+test('a branding pack with owner + name binds (repo.name maps to repo)', () => {
+  assert.deepEqual(ri.loadFromBranding({ branding: () => PACK }), {
+    owner: FIXTURE_OWNER,
+    repo: FIXTURE_REPO,
+  });
+});
+
+test('the neutral pack (empty strings) is NOT an answer', () => {
+  assert.equal(ri.loadFromBranding({ branding: () => ({ repo: { owner: '', name: '' } }) }), null);
+  assert.equal(ri.loadFromBranding({ branding: () => ({ repo: { owner: '  ', name: FIXTURE_REPO } }) }), null);
+});
+
+test('a pack with no repo key at all → null', () => {
+  assert.equal(ri.loadFromBranding({ branding: () => ({ identity: { productName: 'x' } }) }), null);
+  assert.equal(ri.loadFromBranding({ branding: () => null }), null);
+});
+
+test('a THROWING branding loader degrades to null, never a crash', () => {
+  assert.equal(ri.loadFromBranding({ branding: () => { throw new Error('malformed pack'); } }), null);
+});
+
+test('THE FIX: packaged instance, no env, no git → branding answers instead of 503', () => {
+  ri._resetCacheForTests();
+  try {
+    const root = path.resolve('/srv/instance/node_modules/@bongos/core');
+    const info = ri.loadRepoInfo({
+      execSync: mkExec({ toplevel: path.resolve('/srv/instance') }), // git walks up → refused
+      packageRoot: root,
+      branding: () => PACK,
+    });
+    assert.equal(info.error, undefined, 'the instance declares its own repo — that is not an error case');
+    assert.equal(info.owner, FIXTURE_OWNER);
+    assert.equal(info.repo, FIXTURE_REPO);
+    assert.equal(info.blob_base, `https://github.com/${FIXTURE_OWNER}/${FIXTURE_REPO}/blob/main`);
+  } finally {
+    ri._resetCacheForTests();
+  }
+});
+
+test('git still WINS over branding (the core dev checkout is unchanged)', () => {
+  ri._resetCacheForTests();
+  try {
+    const root = path.resolve('/srv/cloud-bongos');
+    const info = ri.loadRepoInfo({
+      execSync: mkExec({ toplevel: root }), // the remote resolves → git answers
+      packageRoot: root,
+      branding: () => ({ repo: { owner: 'packowner', name: 'packrepo' } }),
+    });
+    assert.equal(info.owner, FIXTURE_OWNER, 'branding must never override a resolved git remote');
+  } finally {
+    ri._resetCacheForTests();
+  }
+});
+
+test('the env pin still WINS over branding (the operator override stays on top)', () => {
+  ri._resetCacheForTests();
+  process.env.OTB_GITHUB_OWNER = 'envowner';
+  process.env.OTB_GITHUB_REPO = 'envrepo';
+  try {
+    const root = path.resolve('/srv/instance/node_modules/@bongos/core');
+    const info = ri.loadRepoInfo({
+      execSync: mkExec({ toplevel: path.resolve('/srv/instance') }),
+      packageRoot: root,
+      branding: () => PACK,
+    });
+    assert.equal(info.owner, 'envowner');
+  } finally {
+    delete process.env.OTB_GITHUB_OWNER;
+    delete process.env.OTB_GITHUB_REPO;
+    ri._resetCacheForTests();
+  }
+});
+
 // ---- end-to-end canary: the regression this must never cause ---------------
 //
 // The only case that touches real git. It earns its place — an anchor rule that is too

package/tests/setup_device_flow_fallback.mjs

@@ -91,6 +91,22 @@ t('names the Settings page, CLI Access, and the owner checkbox repair', () => {
   assert.match(text, /Web sign-in is unaffected/i, 'says what still works');
 });
 
+t('the closing step adapts to the caller — setup pastes, login runs a one-liner', () => {
+  const forSetup = setup.deviceFlowFallbackLines('https://spike.cloudbongos.com').join('\n');
+  const forLogin = setup.deviceFlowFallbackLines('https://spike.cloudbongos.com', { finish: 'login' }).join('\n');
+
+  // The default must be byte-stable — setup's own prompt still says "paste it below".
+  assert.match(forSetup, /paste it below/, 'setup keeps its inline-paste wording');
+  assert.doesNotMatch(forLogin, /paste it below/, '`bongos login` has no paste prompt to point at');
+  assert.match(forLogin, /run it in this shell/, 'login tells you what actually works there');
+
+  // Everything that is genuinely shared stays shared — one source of truth.
+  for (const shared of [/Enable Device Flow/, /CLI Access/, /builders\/settings/]) {
+    assert.match(forSetup, shared);
+    assert.match(forLogin, shared);
+  }
+});
+
 // ── redeemCliToken in a hermetic child against a stubbed instance API ────────
 // A child process because API_BASE + the session path resolve at module load:
 // the child gets GDS_API_BASE → the stub and HOME/USERPROFILE → a throwaway