@descix/cli 1.0.1 → 1.0.3

package/lib/commands/briefer/index.js

@@ -0,0 +1,319 @@
+/**
+ * `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

@@ -0,0 +1,129 @@
+/**
+ * §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

@@ -0,0 +1,209 @@
+/**
+ * §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}`
+  });
+  const reExportMatch = findInLines({
+    lines: cm.lines,
+    regex: /export\s*\{\s*hydrateCommunityIdFromProducts\s*\}/,
+    section: `§${SECTION.number} ${SECTION.heading}`,
+    source: `${CM_FILE} (hydrate re-export)`,
+    expected: 'export { hydrateCommunityIdFromProducts }',
+    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 };
+}