@descix/cli 1.0.7 → 1.0.9

package/lib/commands/briefer/sources/canonical-sources.js

@@ -1,129 +0,0 @@
-/**
- * §7 — Where to look for canonical answers extractor (M2 implementation).
- *
- * Per WS-DESCIX-BRIEFER-CLI scope doc §2.2 §7, this section is PARTIALLY
- * DERIVED, PARTIALLY EDITORIAL:
- *   - "Question → Canonical source" rows verify each cited path resolves.
- *   - The "Do NOT trust" list is editorial cruft inventory, optionally read
- *     from a JSON sidecar (.briefer-cruft-inventory.json) — if absent, a
- *     minimal default list (the docs called out in the canonical briefer
- *     yesterday) is rendered.
- *
- * Files cited as canonical sources (all must exist at extract time):
- *   - provision-platform-lb.js (routing source)
- *   - serviceManifestManager.js (dispatch source)
- *   - entitlements/index.js, communityManagement.js, bootstrap.js (Products)
- *   - dev/gateway.js, createViteProxyConfig.js (local dev)
- *   - descix-cloud-core/src/config.js (bootstrap precedence)
- *   - platform-runtime-mental-model.md (env parallelism + cutover)
- */
-import fs from 'fs/promises';
-import path from 'path';
-import {
-  readSourceFile,
-  makeCitation,
-  resolveRepoPath
-} from '../util/source-reader.js';
-import { BrieferExtractorError, BRIEFER_ERROR_CODES } from '../errors.js';
-
-export const SECTION = {
-  number: 7,
-  heading: '7. Where to look for canonical answers',
-  sourceFiles: [
-    'DeSciX/DeSciX_Cloud/microservice/admin/scripts/deploy/provision-platform-lb.js',
-    'DeSciX/DeSciX_Cloud/microservice/services/serviceManifestManager.js',
-    'DeSciX/DeSciX_Core/descix-platform-api/src/entitlements/index.js',
-    'DeSciX/DeSciX_Cloud/microservice/services/communityManagement.js',
-    'DeSciX/DeSciX_Cloud/microservice/admin/bootstrap.js',
-    'DeSciX/DeSciX_Core/descix-app-sdk/src/dev/gateway.js',
-    'DeSciX/DeSciX_Core/descix-app-sdk/src/dev/createViteProxyConfig.js',
-    'DeSciX/DeSciX_Core/descix-cloud-core/src/config.js',
-    'DeSciX/V2_docs/architecture/platform-runtime-mental-model.md'
-  ]
-};
-
-const CRUFT_SIDECAR = 'DeSciX/V2_docs/architecture/.briefer-cruft-inventory.json';
-
-export async function extract({ env, cliPaths } = {}) {
-  if (!env) {
-    throw new BrieferExtractorError({
-      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
-      section: `§${SECTION.number} ${SECTION.heading}`,
-      source: 'extractor argument',
-      expected: 'env (dev|demo|prod) provided by caller',
-      recovery: 'Pass {env} from the briefer entry point.'
-    });
-  }
-  if (!cliPaths) {
-    throw new BrieferExtractorError({
-      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
-      section: `§${SECTION.number} ${SECTION.heading}`,
-      source: 'extractor argument',
-      expected: 'cliPaths provided by caller',
-      recovery: 'Pass {cliPaths} from the briefer entry point.'
-    });
-  }
-
-  // Verify each cited canonical source actually exists. HARD-FAIL with
-  // BRIEFER-SRC-NOT-FOUND on the FIRST missing file — surfaces drift early.
-  const citations = [];
-  for (const rel of SECTION.sourceFiles) {
-    const file = await readSourceFile({
-      cliPaths,
-      relPath: rel,
-      section: `§${SECTION.number} ${SECTION.heading}`
-    });
-    citations.push(makeCitation({
-      file: rel,
-      lines: `1-${file.lines.length}`,
-      anchor: 'canonical source',
-      fileLines: file.lines
-    }));
-  }
-
-  // Cruft sidecar — optional. If present, render the entries; if absent, render
-  // the default minimal cruft list from yesterday's briefer.
-  let cruftRows;
-  let cruftSource = null;
-  try {
-    const sidecarAbs = resolveRepoPath(cliPaths, CRUFT_SIDECAR);
-    const raw = await fs.readFile(sidecarAbs, 'utf-8');
-    const data = JSON.parse(raw);
-    cruftRows = (data.entries || []).map(e => `- ${e.path || e.file}${e.note ? ` — ${e.note}` : ''}`);
-    cruftSource = CRUFT_SIDECAR;
-  } catch (err) {
-    // Sidecar absent or malformed — fall back to the canonical-briefer's list
-    // for prose continuity. This is NOT a value-fallback (per
-    // feedback_no-hardcoded-fallbacks); it's the documented default rendering
-    // until the sidecar lands.
-    cruftRows = [
-      '- `unified-product-registry.md` routing section',
-      '- `cloud-lb-decentralized-routing.md` table without host-dim context',
-      '- Any cloud-KB chunk that claims runtime-Gateway / runtime-Firestore-lookup-for-routing'
-    ];
-  }
-
-  const markdown = [
-    `Trust order for any new architectural question:`,
-    ``,
-    `1. **Code with \`file:line\` cite.** Always wins.`,
-    `2. \`DeSciX/V2_docs/architecture/platform-runtime-mental-model.md\` — closest to a code-grounded reference doc.`,
-    `3. \`DeSciX/CLAUDE.md\` — mostly right (note: any "load balancers look up by app_id" phrasing is misleading; the LB's host rules + path matchers do the routing, not a runtime lookup).`,
-    `4. \`DeSciX/V2_docs/architecture/split-stack-production-architecture.md\` — signal.`,
-    ``,
-    `**Do NOT trust** (cruft inventory${cruftSource ? `, from \`${cruftSource}\`` : ', default list — install `.briefer-cruft-inventory.json` to override'}):`,
-    ``,
-    cruftRows.join('\n'),
-    ``,
-    `| Question | Canonical source (in this order) | Notes |`,
-    `|---|---|---|`,
-    `| How does prod LB route? | \`DeSciX_Cloud/microservice/admin/scripts/deploy/provision-platform-lb.js\`; verify with \`gcloud compute url-maps describe descix-discord-app-lb\` | Code = signal |`,
-    `| How does the env command-broker dispatch external commands? | \`services/serviceManifestManager.js\` (\`proxyToExternalService\`) and \`services/apiFront.js\` | Code = signal |`,
-    `| What is Products for? | \`descix-platform-api/src/entitlements/index.js\`, \`services/communityManagement.js\`, \`admin/bootstrap.js\` | Code = signal |`,
-    `| How does local \`descix serve\` work? | \`descix-app-sdk/src/dev/gateway.js\` + \`createViteProxyConfig.js\` | Code = signal |`,
-    `| Bootstrap & config precedence? | \`descix-cloud-core/src/config.js\` | Code = signal |`,
-    `| Environment parallelism & PROD cutover? | \`platform-runtime-mental-model.md\` | Distilled architectural doc |`
-  ].join('\n');
-
-  return { markdown, citations };
-}

package/lib/commands/briefer/sources/entitlements.js

@@ -1,220 +0,0 @@
-/**
- * §5 — Entitlements & Products Firestore extractor (M2 implementation).
- *
- * Per WS-DESCIX-BRIEFER-CLI scope doc §2.2 §5 + M2 dispatch §6.7 extension:
- *   - Products schema fields + readers — cite hydrateCommunityIdFromProducts
- *     in @descix/platform-api/src/entitlements/index.js + the apiFront
- *     middleware that invokes it (communityManagement.js re-export site).
- *   - Writers — grep DeSciX_Cloud/microservice/admin/ for Products write
- *     patterns (bootstrap.js hydrate-env + confirm_site_deploy).
- *   - App-level config layer (§6.7 extension) — cite the resolver chain
- *     in geminiInteractions.js::resolveModelThinkingPair: request level → kb_model_override
- *     → default_app_model → levelConfig → DEFAULT_AI_MODEL.
- *
- * NO direct @google-cloud/firestore or @pinecone-database/pinecone imports
- * (AC-7 anti-regression). All Firestore touches in the briefer code go
- * through apifront or @descix/cloud-core wrappers.
- */
-import {
-  readSourceFile,
-  findInLines,
-  makeCitation,
-  grepFiles,
-  probeFirestoreRest
-} from '../util/source-reader.js';
-import { BrieferExtractorError, BRIEFER_ERROR_CODES } from '../errors.js';
-// The (model, thinking) precedence chain in words, from its ONE owner. The briefer
-// QUOTES the served contract rather than paraphrasing it — a briefer paraphrase of a
-// chain is exactly how the old five-step list outlived the code it described.
-import { MODEL_THINKING_CHAIN } from '@descix/platform-api/mcp-tools';
-
-export const SECTION = {
-  number: 5,
-  heading: '5. Entitlements & Products Firestore',
-  sourceFiles: [
-    'DeSciX/DeSciX_Core/descix-platform-api/src/entitlements/index.js',
-    'DeSciX/DeSciX_Cloud/microservice/services/communityManagement.js',
-    'DeSciX/DeSciX_Cloud/microservice/admin/bootstrap.js',
-    'DeSciX/DeSciX_Cloud/microservice/services/geminiInteractions.js'
-  ]
-};
-
-const ENTITLEMENTS_FILE = 'DeSciX/DeSciX_Core/descix-platform-api/src/entitlements/index.js';
-const CM_FILE = 'DeSciX/DeSciX_Cloud/microservice/services/communityManagement.js';
-const BOOTSTRAP_FILE = 'DeSciX/DeSciX_Cloud/microservice/admin/bootstrap.js';
-const GEMINI_FILE = 'DeSciX/DeSciX_Cloud/microservice/services/geminiInteractions.js';
-
-export async function extract({ env, cliPaths } = {}) {
-  if (!env) {
-    throw new BrieferExtractorError({
-      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
-      section: `§${SECTION.number} ${SECTION.heading}`,
-      source: 'extractor argument',
-      expected: 'env (dev|demo|prod) provided by caller',
-      recovery: 'Pass {env} from the briefer entry point.'
-    });
-  }
-  if (!cliPaths) {
-    throw new BrieferExtractorError({
-      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
-      section: `§${SECTION.number} ${SECTION.heading}`,
-      source: 'extractor argument',
-      expected: 'cliPaths provided by caller',
-      recovery: 'Pass {cliPaths} from the briefer entry point.'
-    });
-  }
-
-  // ── Source 1: entitlements/index.js — hydrateCommunityIdFromProducts ──
-  const ent = await readSourceFile({
-    cliPaths,
-    relPath: ENTITLEMENTS_FILE,
-    section: `§${SECTION.number} ${SECTION.heading}`
-  });
-  const hydrateMatch = findInLines({
-    lines: ent.lines,
-    regex: /export\s+async\s+function\s+hydrateCommunityIdFromProducts\b/,
-    section: `§${SECTION.number} ${SECTION.heading}`,
-    source: `${ENTITLEMENTS_FILE} (hydrateCommunityIdFromProducts)`,
-    expected: 'export async function hydrateCommunityIdFromProducts(params)',
-    recovery: `Re-locate hydrateCommunityIdFromProducts in ${ENTITLEMENTS_FILE}.`
-  });
-
-  // ── Source 2: communityManagement.js — re-export site ──
-  const cm = await readSourceFile({
-    cliPaths,
-    relPath: CM_FILE,
-    section: `§${SECTION.number} ${SECTION.heading}`
-  });
-  // The symbol is matched WITHIN an export list rather than as the list's sole member. The old
-  // pattern anchored on the closing brace immediately after the name, so it broke the moment a
-  // second symbol was re-exported beside it — the extractor reported the re-export missing when
-  // it was present and one token wider.
-  //
-  // HONEST LIMITATION, stated rather than implied: this is still textual matching, so it remains a
-  // derivation of a fact the module itself owns. The robust fix is to consume the owner's actual
-  // exports, but this extractor cannot import communityManagement.js — that would pull the whole
-  // Cloud service graph (config bootstrap, Firestore) into the CLI. Matching the identifier inside
-  // any export list is what survives a re-ordering; a move to `export * from` would still need
-  // this line changed.
-  const reExportMatch = findInLines({
-    lines: cm.lines,
-    regex: /export\s*\{[^}]*\bhydrateCommunityIdFromProducts\b/,
-    section: `§${SECTION.number} ${SECTION.heading}`,
-    source: `${CM_FILE} (hydrate re-export)`,
-    expected: 'hydrateCommunityIdFromProducts named in an export list',
-    recovery: `Verify ${CM_FILE} still re-exports hydrateCommunityIdFromProducts.`
-  });
-
-  // ── Source 3: bootstrap.js — hydrate-env writer ──
-  const bootstrap = await readSourceFile({
-    cliPaths,
-    relPath: BOOTSTRAP_FILE,
-    section: `§${SECTION.number} ${SECTION.heading}`
-  });
-  const hydrateEnvMatch = findInLines({
-    lines: bootstrap.lines,
-    regex: /hydrate-env|hydrateEnv|hydrate_env/,
-    section: `§${SECTION.number} ${SECTION.heading}`,
-    source: `${BOOTSTRAP_FILE} (hydrate-env writer)`,
-    expected: 'hydrate-env subcommand or hydrateEnv function declaration',
-    recovery: `Re-locate the hydrate-env writer in ${BOOTSTRAP_FILE}.`
-  });
-
-  // ── Source 4: geminiInteractions.js — the (model, thinking) pair owner (§6.7 link) ──
-  const gemini = await readSourceFile({
-    cliPaths,
-    relPath: GEMINI_FILE,
-    section: `§${SECTION.number} ${SECTION.heading}`
-  });
-  const resolverMatch = findInLines({
-    lines: gemini.lines,
-    regex: /export\s+function\s+resolveModelThinkingPair\b/,
-    section: `§${SECTION.number} ${SECTION.heading}`,
-    source: `${GEMINI_FILE} (resolveModelThinkingPair)`,
-    expected: 'export function resolveModelThinkingPair(...)',
-    recovery: `Re-locate resolveModelThinkingPair in ${GEMINI_FILE}.`
-  });
-
-  // ── Optional grep: count Products readers across services/ ──
-  let runtimeReadersList = '';
-  const readers = await grepFiles({
-    repoRoot: cliPaths.repoRoot,
-    relPaths: ['DeSciX/DeSciX_Cloud/microservice/services'],
-    regex: /Products\.doc\(|collection\(['"]Products['"]\)|getProductContext/,
-    excludePaths: new Set(['/node_modules/', '/.git/'])
-  });
-  if (readers.length > 0) {
-    const unique = [...new Set(readers.map(r => r.file))].slice(0, 8);
-    runtimeReadersList = unique.map(f => `  - \`${f}\``).join('\n');
-  }
-
-  // ── M3: live Firestore Products probe (HARD-FAIL on demo/prod, skipped on dev) ──
-  // Uses Firestore REST API via gcloud-derived access token. Per AC-7
-  // anti-regression: no @google-cloud/firestore import — this is a different
-  // API surface (REST + gcloud-CLI token), explicitly permitted.
-  const probeCitations = [];
-  let productsLiveNote = '';
-  if (env === 'dev') {
-    productsLiveNote = '\n_DEV: Firestore probe skipped (local dev — no cloud Firestore for the descix-dev database in this regen scope)._\n';
-  } else {
-    const productsProbe = await probeFirestoreRest({
-      dbPath: `descix-${env}/documents/Products`,
-      query: { pageSize: 200, 'mask.fieldPaths': 'app_id' },
-      env,
-      section: `§${SECTION.number} ${SECTION.heading}`,
-      anchor: 'products-collection-list',
-      expected: `Firestore Products list for env=${env}`,
-      recovery: `Run 'gcloud auth login' and ensure the account has Firestore read scope. The Products collection cross-check is required for env=${env}.`
-    });
-    const docs = (productsProbe.json && productsProbe.json.documents) || [];
-    const names = docs
-      .map(d => (d.name || '').split('/').pop())
-      .filter(Boolean)
-      .sort();
-    const sample = names.slice(0, 8);
-    productsLiveNote = [
-      '',
-      `**Live Products collection** (probed \`Firestore REST listDocuments\` against \`descix-${env}/documents/Products\`):`,
-      `- Docs returned: \`${names.length}\` (pageSize=200; further pages not enumerated this milestone)`,
-      `- Sample app_ids: ${sample.length > 0 ? sample.map(n => '\`' + n + '\`').join(', ') : '_(none)_'}${names.length > sample.length ? ` (+ ${names.length - sample.length} more)` : ''}`,
-      ''
-    ].join('\n');
-    probeCitations.push(productsProbe.citation);
-  }
-
-  // ── Render markdown ──
-  const markdown = [
-    `\`Products/{app_id}\` in \`descix-{env}\` Firestore holds:`,
-    `- \`productPath\`: \`Community/{community_id}/Apps/{app_id}\` (operational path)`,
-    `- \`gcsPath\`: \`gs://descix-assets-public/{env}/{app_id}/\``,
-    `- \`ip_site_gcs_path_url\`: subdomain URL (set by \`confirm_site_deploy\` AFTER site deploy)`,
-    `- \`community_id\` (operational metadata)`,
-    `- \`type\`, \`price\`, \`metadata\``,
-    ``,
-    `**Readers at runtime:** \`hydrateCommunityIdFromProducts()\` middleware (canonical at \`${ENTITLEMENTS_FILE}:${hydrateMatch.lineNumber}\`, re-exported at \`${CM_FILE}:${reExportMatch.lineNumber}\`), purchase / entitlement handlers, app-metadata handlers. **ALL AT THE APIFRONT-OR-DOWNSTREAM LAYER.** **NEVER AT THE LB.**`,
-    ...(runtimeReadersList ? ['', `_Grep of \`services/\` for Products readers:_`, runtimeReadersList] : []),
-    ``,
-    `**Writers:** \`${BOOTSTRAP_FILE}\` \`hydrate-env\` (\`:${hydrateEnvMatch.lineNumber}\`), \`confirm_site_deploy\`, migration scripts.`,
-    ``,
-    `**Consumer at deploy time:** Products drives bootstrap; platform peer hosts are configured in \`provision-platform-lb.js\` (\`PLATFORM_PEER_APPS\`), not read from Products at deploy time.`,
-    ``,
-    `### App-level config layer (§6.7 — added 2026-05-26)`,
-    ``,
-    `App-level and KB-level config flows from Firestore (\`Community/{c}/Apps/{a}\` for \`default_app_model\`, \`Community/{c}/Apps/{a}/KnowledgeBases/{k}\` for \`kb_model_override\`) into \`resolveModelThinkingPair()\` at \`${GEMINI_FILE}:${resolverMatch.lineNumber}\` — the ONE owner of the (model, thinking) pair. Both fields are **opt-in** — null means the tier below applies.`,
-    ``,
-    MODEL_THINKING_CHAIN,
-    ``,
-    `\`app.default_app_model\` no longer shadows an intelligence_level named on the request: a level names a (model, thinking) PAIR and outranks it. It still outranks the KB's own configured level and the platform default. Apps that want per-level routing leave \`default_app_model = null/absent\`.`,
-    productsLiveNote
-  ].join('\n');
-
-  const citations = [
-    makeCitation({ file: ENTITLEMENTS_FILE, lines: String(hydrateMatch.lineNumber), anchor: 'hydrateCommunityIdFromProducts (canonical)', fileLines: ent.lines }),
-    makeCitation({ file: CM_FILE, lines: String(reExportMatch.lineNumber), anchor: 'hydrate re-export', fileLines: cm.lines }),
-    makeCitation({ file: BOOTSTRAP_FILE, lines: String(hydrateEnvMatch.lineNumber), anchor: 'hydrate-env writer', fileLines: bootstrap.lines }),
-    makeCitation({ file: GEMINI_FILE, lines: String(resolverMatch.lineNumber), anchor: 'resolveModelThinkingPair (app-level config bridge)', fileLines: gemini.lines }),
-    ...probeCitations
-  ];
-
-  return { markdown, citations };
-}

package/lib/commands/briefer/sources/environments.js

@@ -1,205 +0,0 @@
-/**
- * §2 — Environments extractor (M2 implementation).
- *
- * Per WS-DESCIX-BRIEFER-CLI scope doc §2.2 §2, this extractor reads:
- *   - DEV/DEMO/PROD parallelism — architectural fact distilled from
- *     V2_docs/architecture/platform-runtime-mental-model.md (cite the doc).
- *   - ENV_CONFIG block from provision-platform-lb.js:32-47.
- *   - DEPLOY_ENV-bound-once hard-fail from descix-cloud-core/src/config.js
- *     (locate dynamically; canonical briefer line range is allowed to drift).
- *   - Secret Manager config name pattern from DeSciX_Cloud/CLAUDE.md (cite the
- *     doc since the values are env-keyed and live in env-vars/secrets, not
- *     code) — locate the "Secret Manager — Per-Environment Isolation" table.
- *
- * Optional gcloud verification: list Cloud Function names matching `apiFront-http`
- * and Firestore database names matching `descix-{env}` / `descix`.
- */
-import {
-  readSourceFile,
-  findInLines,
-  makeCitation,
-  sliceRange,
-  probeGcloudJson
-} from '../util/source-reader.js';
-import { BrieferExtractorError, BRIEFER_ERROR_CODES } from '../errors.js';
-
-export const SECTION = {
-  number: 2,
-  heading: '2. Environments',
-  sourceFiles: [
-    'DeSciX/V2_docs/architecture/platform-runtime-mental-model.md',
-    'DeSciX/DeSciX_Cloud/microservice/admin/scripts/deploy/provision-platform-lb.js',
-    'DeSciX/DeSciX_Core/descix-cloud-core/src/config.js',
-    'DeSciX/DeSciX_Cloud/CLAUDE.md'
-  ]
-};
-
-const RUNTIME_MM = 'DeSciX/V2_docs/architecture/platform-runtime-mental-model.md';
-const MESH_FILE = 'DeSciX/DeSciX_Cloud/microservice/admin/scripts/deploy/provision-platform-lb.js';
-const CONFIG_FILE = 'DeSciX/DeSciX_Core/descix-cloud-core/src/config.js';
-const CLOUD_CLAUDE = 'DeSciX/DeSciX_Cloud/CLAUDE.md';
-
-export async function extract({ env, cliPaths } = {}) {
-  if (!env) {
-    throw new BrieferExtractorError({
-      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
-      section: `§${SECTION.number} ${SECTION.heading}`,
-      source: 'extractor argument',
-      expected: 'env (dev|demo|prod) provided by caller',
-      recovery: 'Pass {env} from the briefer entry point.'
-    });
-  }
-  if (!cliPaths) {
-    throw new BrieferExtractorError({
-      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
-      section: `§${SECTION.number} ${SECTION.heading}`,
-      source: 'extractor argument',
-      expected: 'cliPaths provided by caller',
-      recovery: 'Pass {cliPaths} from the briefer entry point.'
-    });
-  }
-
-  // ── Source 1: ENV_CONFIG in provision-platform-lb.js ──
-  const mesh = await readSourceFile({
-    cliPaths,
-    relPath: MESH_FILE,
-    section: `§${SECTION.number} ${SECTION.heading}`
-  });
-  const envConfigMatch = findInLines({
-    lines: mesh.lines,
-    regex: /const\s+ENV_CONFIG\s*=\s*\{/,
-    section: `§${SECTION.number} ${SECTION.heading}`,
-    source: `${MESH_FILE} (ENV_CONFIG)`,
-    expected: 'const ENV_CONFIG = { prod: {...}, demo: {...}, dev: {...} }',
-    recovery: `Re-locate the ENV_CONFIG construct in ${MESH_FILE}.`,
-    expectedRange: [20, 60]
-  });
-  const envConfigEnd = findObjectEnd(mesh.lines, envConfigMatch.lineNumber);
-  const envConfigBlock = sliceRange(mesh.lines, envConfigMatch.lineNumber, envConfigEnd);
-
-  // ── Source 2: config.js — DEPLOY_ENV-bound-once hard-fail ──
-  const config = await readSourceFile({
-    cliPaths,
-    relPath: CONFIG_FILE,
-    section: `§${SECTION.number} ${SECTION.heading}`
-  });
-  const deployEnvBoundMatch = findInLines({
-    lines: config.lines,
-    regex: /FATAL:\s*DEPLOY_ENV\s+not\s+set/,
-    section: `§${SECTION.number} ${SECTION.heading}`,
-    source: `${CONFIG_FILE} (DEPLOY_ENV bound-once hard-fail)`,
-    expected: 'throw with message starting "[CloudConfig] FATAL: DEPLOY_ENV not set"',
-    recovery: `Re-locate the DEPLOY_ENV hard-fail in ${CONFIG_FILE}.`
-  });
-
-  // ── Source 3: runtime-mental-model.md doc cite (distilled architectural fact) ──
-  // We just verify the doc exists + record SHA of the canonical range. The doc
-  // is the source for "DEV/DEMO/PROD are fully parallel" because that's an
-  // assertion spread across many code paths — too noisy to grep.
-  const rmm = await readSourceFile({
-    cliPaths,
-    relPath: RUNTIME_MM,
-    section: `§${SECTION.number} ${SECTION.heading}`
-  });
-
-  // ── Source 4: Cloud CLAUDE.md Secret Manager table ──
-  const claude = await readSourceFile({
-    cliPaths,
-    relPath: CLOUD_CLAUDE,
-    section: `§${SECTION.number} ${SECTION.heading}`
-  });
-  const secretTableMatch = findInLines({
-    lines: claude.lines,
-    regex: /descix_config_demo/,
-    section: `§${SECTION.number} ${SECTION.heading}`,
-    source: `${CLOUD_CLAUDE} (Secret Manager Per-Environment Isolation table)`,
-    expected: 'descix_config_demo row in the per-env secret table',
-    recovery: `Re-locate the Secret Manager isolation table in ${CLOUD_CLAUDE}.`
-  });
-
-  // ── M3: live gcloud probes (HARD-FAIL on demo/prod, skipped on dev) ──
-  const probeCitations = [];
-  let gcloudCfNote = '';
-  let gcloudFsNote = '';
-
-  if (env === 'dev') {
-    // DEV is local. Probe is intentionally skipped; emit a stanza so the
-    // operator knows live state was not verified for this regen.
-    gcloudCfNote = '\n_DEV: gcloud probes skipped (local dev environment — no Cloud Functions or Firestore to probe)._\n';
-  } else {
-    const cfProbe = await probeGcloudJson({
-      command: ['functions', 'list', '--v2', '--format=json'],
-      env,
-      section: `§${SECTION.number} ${SECTION.heading}`,
-      anchor: 'cloud-functions-list',
-      expected: 'JSON array of gen2 Cloud Functions for project descix',
-      recovery: `Run 'gcloud auth login' and 'gcloud config set project descix'. The Cloud Functions list cross-check is required for env=${env}.`
-    });
-    const apiFrontCfs = (cfProbe.json || [])
-      .filter(f => /apiFront-http/.test(f.name || ''))
-      .map(f => (f.name || '').split('/').pop());
-    gcloudCfNote = `\n_Live Cloud Functions matching \`apiFront-http\` (probed \`${cfProbe.citation.probe}\`, env=\`${env}\`):_ ${apiFrontCfs.length > 0 ? apiFrontCfs.map(n => '\`' + n + '\`').join(', ') : '_(none found)_'}\n`;
-    probeCitations.push(cfProbe.citation);
-
-    const fsProbe = await probeGcloudJson({
-      command: ['firestore', 'databases', 'list', '--format=json'],
-      env,
-      section: `§${SECTION.number} ${SECTION.heading}`,
-      anchor: 'firestore-databases-list',
-      expected: 'JSON array of Firestore databases for project descix',
-      recovery: `Run 'gcloud auth login' and 'gcloud config set project descix'. The Firestore databases cross-check is required for env=${env}.`
-    });
-    const dbs = (fsProbe.json || [])
-      .map(d => (d.name || '').split('/').pop())
-      .filter(n => /^descix/.test(n));
-    gcloudFsNote = `\n_Live Firestore databases matching \`descix*\` (probed \`${fsProbe.citation.probe}\`, env=\`${env}\`):_ ${dbs.length > 0 ? dbs.map(n => '\`' + n + '\`').join(', ') : '_(none found)_'}\n`;
-    probeCitations.push(fsProbe.citation);
-  }
-
-  // ── Render markdown ──
-  const markdown = [
-    `DEV / DEMO / PROD are **fully parallel cloud deployments.** They co-exist; PROD does not replace DEMO. — \`${RUNTIME_MM}\``,
-    ``,
-    `Per env, isolated:`,
-    `- Cloud Function: \`apiFront-http-{env}\` (and \`apiFront-http\` for PROD)`,
-    `- Firestore DB: \`descix-{env}\` (and \`descix\` for PROD)`,
-    `- Secret Manager config: \`descix_config_{env}\` (DEV/DEMO) or \`descix_config\` with version aliases (PROD/PREVIEW) — \`${CLOUD_CLAUDE}:${secretTableMatch.lineNumber}\``,
-    `- GCS bucket prefix: \`{env}/\``,
-    `- LB host suffix: \`.{env}.descix.net\` for DEV/DEMO, \`.descix.net\` for PROD`,
-    ``,
-    `ENV_CONFIG (the deploy-time env table — \`${MESH_FILE}:${envConfigMatch.lineNumber}-${envConfigEnd}\`):`,
-    ``,
-    '```js',
-    envConfigBlock,
-    '```',
-    ``,
-    `One process serves exactly one env, determined by \`DEPLOY_ENV\`. The cloud-core bootstrap **hard-fails** at construct time if \`DEPLOY_ENV\` is unset — there is no default. — \`${CONFIG_FILE}:${deployEnvBoundMatch.lineNumber}\``,
-    gcloudCfNote,
-    gcloudFsNote
-  ].join('\n');
-
-  const citations = [
-    makeCitation({ file: MESH_FILE, lines: `${envConfigMatch.lineNumber}-${envConfigEnd}`, anchor: 'ENV_CONFIG', fileLines: mesh.lines }),
-    makeCitation({ file: CONFIG_FILE, lines: String(deployEnvBoundMatch.lineNumber), anchor: 'DEPLOY_ENV bound-once', fileLines: config.lines }),
-    makeCitation({ file: RUNTIME_MM, lines: `1-${rmm.lines.length}`, anchor: 'DEV/DEMO/PROD parallelism', fileLines: rmm.lines }),
-    makeCitation({ file: CLOUD_CLAUDE, lines: String(secretTableMatch.lineNumber), anchor: 'Secret Manager per-env isolation', fileLines: claude.lines }),
-    ...probeCitations
-  ];
-
-  return { markdown, citations };
-}
-
-function findObjectEnd(lines, startLine) {
-  const MAX = Math.min(lines.length, startLine + 50);
-  let depth = 0;
-  for (let i = startLine - 1; i < MAX; i++) {
-    for (const ch of lines[i]) {
-      if (ch === '{') depth++;
-      else if (ch === '}') {
-        depth--;
-        if (depth === 0) return i + 1;
-      }
-    }
-  }
-  return Math.min(lines.length, startLine + 30);
-}