@descix/cli 1.0.6 → 1.0.8

package/lib/commands/briefer/index.js

@@ -1,319 +0,0 @@
-/**
- * `descix briefer` — main entry point.
- *
- * Per WS-DESCIX-BRIEFER-CLI scope doc §2 (Architecture / Option A):
- *
- *   descix briefer [--env=dev|demo|prod] [--out=PATH] [--check]
- *
- * Reads the per-section data sources defined in scope doc §2.2, dispatches to
- * the per-section extractors in ./sources/*.js, and emits a structured
- * BrieferDoc object. The stitcher composes the markdown; --check mode diffs
- * the regen against the canonical briefer file.
- *
- * HARD-FAIL philosophy (scope doc §2.3 + feedback_no-hardcoded-fallbacks):
- * every extractor that can't find its source data throws BrieferExtractorError
- * with a stable error code. No fallback strings. No try-catch-and-default.
- *
- * M1 SCOPE (this implementation):
- *   - CLI subcommand registration in bin/descix.js (separate edit).
- *   - This entry orchestrates 7 stub extractors.
- *   - Stitcher composes a real (non-empty) markdown with TODO placeholder bodies.
- *   - --check runs the full extraction, diffs against canonical, prints a
- *     unified-style diff, exits non-zero on drift (which is EXPECTED for M1 —
- *     stubs WILL differ from the manually-authored canonical briefer).
- *
- * M2+ SCOPE (NOT IMPLEMENTED HERE):
- *   - Real AST/regex parsing of source files.
- *   - Live gcloud probes.
- *   - Firestore Products counts via apifront.
- *   - MustKnow KB partition + auto-sync.
- *   - Bootstrap protocol edits (/cos skill, @bootstrap agent).
- *   - CI --check gate.
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import chalk from 'chalk';
-import { fileURLToPath } from 'url';
-
-import { BrieferExtractorError, BRIEFER_ERROR_CODES } from './errors.js';
-import { stitchBriefer, extractCitationTrail } from './stitcher.js';
-
-import * as identifiers from './sources/identifiers.js';
-import * as environments from './sources/environments.js';
-import * as routing from './sources/routing.js';
-import * as microserviceDeploy from './sources/microservice-deploy.js';
-import * as entitlements from './sources/entitlements.js';
-import * as whatIsNot from './sources/what-is-not.js';
-import * as canonicalSources from './sources/canonical-sources.js';
-
-import { WorkspaceConfig } from '../../workspace-config.js';
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Extractor dispatch table (scope doc §2.2 ordering)
-// ─────────────────────────────────────────────────────────────────────────────
-export const EXTRACTORS = Object.freeze([
-  identifiers,
-  environments,
-  routing,
-  microserviceDeploy,
-  entitlements,
-  whatIsNot,
-  canonicalSources
-]);
-
-export const VALID_ENVS = Object.freeze(['dev', 'demo', 'prod']);
-
-// Default output path (scope doc §2.1). Resolved relative to workspace root
-// via WorkspaceConfig.getWorkspaceRoot() — never a hardcoded absolute path.
-export const DEFAULT_OUT_RELATIVE = 'DeSciX/V2_docs/architecture/platform-must-know-briefer.md';
-
-const MECHANISM_TAG = 'descix briefer v1.0 (M2 — code-grounded extractors)';
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function resolveCliPaths() {
-  // Resolve the descix-cli root from this file's location, then walk up to
-  // DeSciX_Core and the parent repo. M2/M3 extractors that read source files
-  // will need these to anchor file reads.
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const descixCliRoot = path.resolve(here, '../../..');                // .../descix-cli
-  const descixCoreRoot = path.resolve(descixCliRoot, '..');             // .../DeSciX_Core
-  const desciXRoot = path.resolve(descixCoreRoot, '..');                // .../DeSciX
-  const repoRoot = path.resolve(desciXRoot, '..');                      // .../Unkamon
-  return { descixCliRoot, descixCoreRoot, desciXRoot, repoRoot };
-}
-
-export function resolveOutPath(cliOut, workspaceConfig, cliPaths, cwd) {
-  // Explicit override always wins.
-  if (cliOut) return path.resolve(cliOut);
-
-  // Default: workspace-root-relative path.
-  if (workspaceConfig) {
-    const wsRoot = workspaceConfig.getWorkspaceRoot();
-    return path.join(wsRoot, DEFAULT_OUT_RELATIVE);
-  }
-
-  // HARD-FAIL per feedback_no-hardcoded-fallbacks. The previous implementation
-  // derived a default from cliPaths.repoRoot (computed from the CLI file
-  // location), which silently produced a wrong path like
-  // "Unkamon/DeSciX/DeSciX/V2_docs/..." (double DeSciX/) when invoked from
-  // inside descix-cli/ with no workspace.json in cwd. No silent path-guessing.
-  throw new BrieferExtractorError({
-    code: BRIEFER_ERROR_CODES.WORKSPACE_NOT_FOUND,
-    section: 'briefer entry',
-    source: cwd || '(unknown cwd)',
-    expected: 'either .descix/workspace.json reachable by upward search, OR --out=<path>',
-    recovery: 'Run from your workspace root (where .descix/workspace.json lives), or pass --out=<path> explicitly.',
-    detail: `cliPaths.repoRoot was previously used as a silent fallback (resolved to ${cliPaths.repoRoot}); that fallback is removed.`
-  });
-}
-
-async function resolveRegenBy() {
-  // Best signal we have without forcing an auth round-trip in M1. M2 will
-  // require auth (for apifront/Firestore calls) and can use the wallet email
-  // from apiClient.loadCredentials() — at that point this changes to a hard
-  // requirement. For M1 scaffolding we just tag the system user.
-  return process.env.USER || process.env.USERNAME || 'unknown';
-}
-
-// Minimal unified-style diff (line-based). Avoids adding a new npm dependency
-// for the M1 scaffold; M2 may swap in the `diff` package if richer output is
-// needed (currently an unanswered question §9.1 in scope doc — Babel dep).
-function simpleLineDiff(a, b, { aLabel = 'canonical', bLabel = 'regen' } = {}) {
-  const aLines = (a || '').split(/\r?\n/);
-  const bLines = (b || '').split(/\r?\n/);
-  const out = [`--- ${aLabel}`, `+++ ${bLabel}`];
-  const max = Math.max(aLines.length, bLines.length);
-  let inHunk = false;
-  for (let i = 0; i < max; i++) {
-    const av = aLines[i];
-    const bv = bLines[i];
-    if (av === bv) {
-      if (inHunk) { out.push(' ' + (av ?? '')); inHunk = false; }
-      continue;
-    }
-    if (!inHunk) {
-      out.push(`@@ line ${i + 1} @@`);
-      inHunk = true;
-    }
-    if (av !== undefined) out.push(`-${av}`);
-    if (bv !== undefined) out.push(`+${bv}`);
-  }
-  return out.join('\n');
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// BrieferDoc — the structured object returned by buildBrieferDoc()
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * @typedef {object} BrieferSectionResult
- * @property {{number: number, heading: string, sourceFiles: string[]}} section
- * @property {{markdown: string, citations: object[]}} extract
- */
-
-/**
- * @typedef {object} BrieferDoc
- * @property {string} env
- * @property {string} mechanism
- * @property {string} regenBy
- * @property {BrieferSectionResult[]} sections
- * @property {string} markdown        Final stitched markdown.
- * @property {string[]} citationTrail Hidden HTML-comment trail (one per line).
- */
-
-/**
- * Run all extractors and return the BrieferDoc.
- *
- * @param {object} opts
- * @param {string} opts.env
- * @param {object} opts.cliPaths
- * @param {object|null} [opts.apiClient]  Optional in M1 (stubs don't need it).
- * @param {object|null} [opts.gcloud]     Optional in M1 (stubs don't need it).
- * @param {string}  opts.regenBy
- * @param {string} [opts.mechanism]
- * @returns {Promise<BrieferDoc>}
- */
-export async function buildBrieferDoc({ env, cliPaths, apiClient = null, gcloud = null, regenBy, mechanism = MECHANISM_TAG }) {
-  const sections = [];
-  for (const extractor of EXTRACTORS) {
-    const result = await extractor.extract({ env, cliPaths, gcloud, apiClient });
-    sections.push({ section: extractor.SECTION, extract: result });
-  }
-  const markdown = stitchBriefer({ env, mechanism, regenBy, sections });
-  const citationTrail = extractCitationTrail(markdown);
-  return { env, mechanism, regenBy, sections, markdown, citationTrail };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Public CLI entry — invoked by bin/descix.js `briefer` subcommand
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * @param {object} options Commander options object.
- * @param {string} [options.env]      dev|demo|prod (default: 'dev' for M1; M2 will hard-fail dev per scope doc §2.1).
- * @param {string} [options.out]      Output path override.
- * @param {boolean} [options.check]   Drift-detection mode: regen to memory, diff against canonical, exit non-zero on drift.
- * @param {boolean} [options.verbose] Print per-source timing + extractor names.
- */
-export async function runBriefer(options = {}) {
-  const env = (options.env || 'dev').toLowerCase();
-  if (!VALID_ENVS.includes(env)) {
-    console.error(chalk.red(`\n❌ Invalid --env=${options.env}. Must be one of: ${VALID_ENVS.join(', ')}\n`));
-    process.exit(1);
-  }
-
-  // Per scope §2.1: --env=dev is rejected by the routing extractor specifically
-  // (DEV has no LB URL map). Other extractors accept dev because they read
-  // only source files (no gcloud probe required). The rejection lives in
-  // sources/routing.js; this entry point passes env through unchanged.
-  if (options.verbose) {
-    console.log(chalk.gray(`[briefer] env=${env}`));
-  }
-
-  const cliPaths = resolveCliPaths();
-  const cwd = process.cwd();
-  let workspaceConfig = null;
-  try {
-    workspaceConfig = await WorkspaceConfig.tryLoad(cwd);
-  } catch {
-    // tryLoad returns null on missing workspace; an exception here means the
-    // workspace.json file exists but is invalid. Hard-fail per philosophy —
-    // do NOT proceed with a guessed default workspace.
-    throw new BrieferExtractorError({
-      code: BRIEFER_ERROR_CODES.PARSE_FAIL,
-      section: 'briefer entry',
-      source: '.descix/workspace.json',
-      expected: 'valid v2.1 workspace JSON',
-      recovery: 'Fix the workspace.json or run `descix init` to regenerate.'
-    });
-  }
-
-  const outPath = resolveOutPath(options.out, workspaceConfig, cliPaths, cwd);
-  const regenBy = await resolveRegenBy();
-
-  if (options.verbose) {
-    console.log(chalk.gray(`[briefer] outPath=${outPath}`));
-    console.log(chalk.gray(`[briefer] regenBy=${regenBy}`));
-    console.log(chalk.gray(`[briefer] extractors=${EXTRACTORS.length}`));
-  }
-
-  // Build the briefer doc. Each extractor is run sequentially; M2 can
-  // parallelize if hot-path latency matters (it likely won't for 7 sources).
-  let doc;
-  try {
-    doc = await buildBrieferDoc({ env, cliPaths, regenBy });
-  } catch (err) {
-    if (err instanceof BrieferExtractorError) {
-      console.error(chalk.red(`\n❌ Briefer extraction failed:\n`));
-      console.error(chalk.red(err.message));
-      console.error('');
-      process.exit(1);
-    }
-    throw err;
-  }
-
-  if (options.check) {
-    return runCheckMode({ doc, outPath, verbose: options.verbose });
-  }
-
-  // Write mode — overwrite the canonical briefer file.
-  await fs.mkdir(path.dirname(outPath), { recursive: true });
-  await fs.writeFile(outPath, doc.markdown, 'utf-8');
-
-  console.log(chalk.green(`\n✅ Briefer regenerated\n`));
-  console.log(chalk.cyan(`  Env:       ${env}`));
-  console.log(chalk.gray (`  Mechanism: ${doc.mechanism}`));
-  console.log(chalk.gray (`  By:        ${regenBy}`));
-  console.log(chalk.gray (`  Out:       ${outPath}`));
-  console.log(chalk.gray (`  Sections:  ${doc.sections.length}`));
-  console.log(chalk.gray (`  Citations: ${doc.citationTrail.length}\n`));
-  return doc;
-}
-
-export async function runCheckMode({ doc, outPath, verbose }) {
-  let canonical = null;
-  try {
-    canonical = await fs.readFile(outPath, 'utf-8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      console.error(chalk.red(`\n❌ --check failed: canonical briefer not found at ${outPath}\n`));
-      console.error(chalk.gray('   Run `descix briefer` (without --check) to create it.\n'));
-      process.exit(2);
-    }
-    throw err;
-  }
-
-  if (canonical === doc.markdown) {
-    console.log(chalk.green(`\n✅ Briefer is in sync — no drift detected.\n`));
-    return { drift: false, doc };
-  }
-
-  // Drift detected. Print a unified-style diff and exit non-zero.
-  // Per scope doc §2.2 §3, --check also compares the citation trail. For M1
-  // we report both prose-drift and citation-drift counts.
-  const canonicalTrail = extractCitationTrail(canonical);
-  const regenTrail = doc.citationTrail;
-  const trailChanged = (canonicalTrail.length !== regenTrail.length) ||
-    canonicalTrail.some((c, i) => c !== regenTrail[i]);
-
-  console.error(chalk.yellow(`\n⚠ [${BRIEFER_ERROR_CODES.DRIFT_DETECTED}] Briefer drift detected.\n`));
-  console.error(chalk.gray(`  Canonical:    ${outPath}`));
-  console.error(chalk.gray(`  Regen length: ${doc.markdown.length} bytes`));
-  console.error(chalk.gray(`  Canon length: ${canonical.length} bytes`));
-  console.error(chalk.gray(`  Citation trail drift: ${trailChanged ? 'YES' : 'no'}\n`));
-
-  if (verbose) {
-    console.error(simpleLineDiff(canonical, doc.markdown, { aLabel: outPath, bLabel: 'regen (in-memory)' }));
-    console.error('');
-  } else {
-    console.error(chalk.gray('  (Run with --verbose for the full diff.)\n'));
-  }
-
-  // M2: drift means a source-of-truth file changed shape since last regen.
-  // Caller should regenerate (run `descix briefer` without --check) and commit
-  // the updated canonical briefer.
-  process.exit(1);
-}

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 };
-}