flecto 3.0.2 → 4.0.0

package/index.js

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 
 import { program } from 'commander';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, realpathSync } from 'fs';
-import { resolve, relative, dirname, join } from 'path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'fs';
+import { resolve, relative, dirname, basename, join, isAbsolute } from 'path';
 import { fileURLToPath } from 'url';
-import { createHash } from 'crypto';
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 
 import { parseFile, isSupported, parseContent } from './src/parser.js';
-import { diffTrees, secretMatchPath } from './src/differ.js';
+import { diffTrees } from './src/differ.js';
 import { documentKeysOf, withDocumentKeys } from './src/documents.js';
 import { startWatcher } from './src/watcher.js';
 import {
@@ -21,7 +20,7 @@ import {
   renderWarn,
   renderPolicyFindings,
   maskChangeEvent,
-  maskSensitiveValue,
+  maskFindings,
 } from './src/renderer.js';
 import { deliverPrComment, renderPrComment } from './src/pr-comment.js';
 import { PR_PROVIDER_IDS } from './src/pr-providers.js';
@@ -31,11 +30,17 @@ import {
   readTerraformPlanFile,
 } from './src/terraform.js';
 import { renderReportHtml } from './src/report.js';
-import { redactSecretString } from './src/secrets.js';
 import { fireAlerts } from './src/alerter.js';
 import { resolveWebhookFormat, WEBHOOK_FORMAT_CHOICES } from './src/notifiers.js';
 import { createEnvelope } from './src/envelope.js';
+import { startLanguageServer } from './src/lsp.js';
 import { buildSarif } from './src/sarif.js';
+import {
+  maskState,
+  resolveSnapshotStore,
+  SNAPSHOT_MASK_MODES,
+  SNAPSHOT_STORE_IDS,
+} from './src/snapshot-store.js';
 import {
   loadBaseline,
   applyBaseline,
@@ -55,6 +60,18 @@ import {
   addPolicyPackFromPackage,
 } from './src/policy.js';
 import { testPolicyFixture } from './src/policy-test.js';
+import { makeCliRunner, runStdioServer } from './src/mcp.js';
+import {
+  assertExplainNotFromRc,
+  buildExplainPayload,
+  buildExplainRequest,
+  describeRequest,
+  estimateInputTokens,
+  EXPLAIN_PROVIDERS,
+  formatNarration,
+  narrate,
+  resolveExplainConfig,
+} from './src/explain.js';
 import {
   loadRcConfig,
   resolveEffectiveOptions,
@@ -63,13 +80,16 @@ import {
   resolveProfileName,
   resolvePolicyOptions,
   assertTargetContained,
+  assertWriteDestinationContained,
+  assertAlertActionsFromCli,
+  assertSnapshotRefFromCli,
+  assertSafeGitRef,
 } from './src/config.js';
 
 const PKG = JSON.parse(
   readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8'),
 );
 
-const SNAPSHOT_DIR = '.flecto-snapshots';
 const FAIL_ON_CHOICES = ['changed', 'added', 'removed', 'policy', 'error', 'warn'];
 
 /**
@@ -82,85 +102,42 @@ const FAIL_ON_CHOICES = ['changed', 'added', 'removed', 'policy', 'error', 'warn
 const PLAN_DEFAULT_FAIL_ON = 'error';
 const PLAN_DEFAULT_POLICIES = 'terraform';
 
-function snapshotIdForPath(absPath) {
-  const normalized = absPath.replaceAll('\\', '/');
-  return createHash('sha256').update(normalized).digest('hex').slice(0, 16);
-}
-
-function snapshotPathForFile(absPath) {
-  const id = snapshotIdForPath(absPath);
-  return resolve(`${SNAPSHOT_DIR}/${id}.json`);
-}
-
-function snapshotHistoryPathForFile(absPath) {
-  const id = snapshotIdForPath(absPath);
-  let timestamp = Date.now();
-  let path = resolve(`${SNAPSHOT_DIR}/${id}.${timestamp}.json`);
-  while (existsSync(path)) {
-    timestamp += 1;
-    path = resolve(`${SNAPSHOT_DIR}/${id}.${timestamp}.json`);
-  }
-  return path;
-}
-
 /**
- * Snapshot ids that already have at least one timestamped history entry.
+ * Put the live side of a diff in the same form the store recorded the baseline
+ * in.
  *
- * Listed once per run and threaded through the snapshot loop: probing the
- * directory per file made writing N baselines cost N listings of O(N) entries
- * each, which is quadratic in the number of tracked files.
- * @returns {Set<string>}
+ * A masked store holds `flecto:sha256:…` where a secret was. Diffing that
+ * against the plaintext on disk would report every secret in the file as changed
+ * on every single run — noise that would train a team to ignore the tool, from a
+ * store whose whole purpose is to be trusted. Masking both sides compares digest
+ * to digest, so a rotated credential still reports as changed and an untouched
+ * one reports nothing.
+ * @template T
+ * @param {T} state
+ * @param {import('./src/snapshot-store.js').SnapshotStore} store
+ * @returns {T}
  */
-function snapshotIdsWithHistory() {
-  /** @type {Set<string>} */
-  const ids = new Set();
-  if (!existsSync(SNAPSHOT_DIR)) return ids;
-  for (const name of readdirSync(SNAPSHOT_DIR)) {
-    const match = /^([a-f0-9]{16})\.\d+\.json$/.exec(name);
-    if (match) ids.add(match[1]);
-  }
-  return ids;
-}
-
-function preserveLegacySnapshotForHistory(absPath, snapshotPath, idsWithHistory) {
-  if (!existsSync(snapshotPath) || idsWithHistory.has(snapshotIdForPath(absPath))) return;
-
-  const legacy = JSON.parse(readFileSync(snapshotPath, 'utf8'));
-  writeFileSync(
-    snapshotHistoryPathForFile(absPath),
-    JSON.stringify({
-      file: legacy.file ?? absPath,
-      state: legacy.state ?? legacy,
-      ...(Array.isArray(legacy.documents) ? { documents: legacy.documents } : {}),
-      createdAt: legacy.createdAt ?? statSync(snapshotPath).mtime.toISOString(),
-    }, null, 2),
-    'utf8',
-  );
+function alignStateWithStore(state, store) {
+  return store.maskMode === 'hash' ? /** @type {T} */ (maskState(state)) : state;
 }
 
-function readLocalSnapshotHistory() {
-  if (!existsSync(SNAPSHOT_DIR)) return [];
-
-  const entries = readdirSync(SNAPSHOT_DIR, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'));
-  const historyEntries = entries.filter((entry) => /^[a-f0-9]{16}\.\d+\.json$/.test(entry.name));
-  const historyIds = new Set(historyEntries.map((entry) => entry.name.slice(0, 16)));
-  const legacyEntries = entries.filter((entry) =>
-    /^[a-f0-9]{16}\.json$/.test(entry.name) && !historyIds.has(entry.name.slice(0, 16)));
-  const snapshotEntries = [...historyEntries, ...legacyEntries];
-
-  return snapshotEntries.map((entry) => {
-    const path = resolve(SNAPSHOT_DIR, entry.name);
-    const snapshot = JSON.parse(readFileSync(path, 'utf8'));
-    const state = restoreSnapshotDocumentKeys(snapshot?.state ?? snapshot, snapshot);
-    if (typeof snapshot?.file !== 'string') {
-      throw new Error(`Invalid snapshot file: ${path}`);
-    }
-    return {
-      file: snapshot.file,
-      state,
-      createdAt: snapshot.createdAt ?? statSync(path).mtime.toISOString(),
-    };
+/**
+ * Resolve the snapshot store a command should read and write (#141).
+ *
+ * Every snapshot consumer goes through this, so `--snapshot-store shared` in
+ * `.flectorc` means the same thing to `watch`, `ci`, `history`, and `report` —
+ * a store the editor of the config and the runner gating it disagree about
+ * would be worse than having only the local one.
+ * @param {Record<string, unknown>} effective
+ * @returns {import('./src/snapshot-store.js').SnapshotStore}
+ */
+function snapshotStoreFromEffective(effective) {
+  return resolveSnapshotStore({
+    store: effective.snapshotStore,
+    dir: effective.snapshotDir,
+    mask: effective.snapshotMask,
+    retention: effective.snapshotRetention,
+    cwd: process.cwd(),
   });
 }
 
@@ -265,11 +242,6 @@ function maybeMaskChanges(events, maskSecrets) {
 }
 
 /**
- * Redact secret-shaped text from policy messages. A rule using
- * `messageTemplate` can interpolate `{before}` / `{after}`, so a finding can
- * carry a credential even when the change events beside it are masked. Replace
- * exact interpolated values using the same path-aware masking as change events,
- * then catch any other recognizable secret fragments in free-form messages.
  * @param {import('./src/policy.js').PolicyFinding[]} findings
  * @param {import('./src/differ.js').ChangeEvent[]} changes
  * @param {boolean} maskSecrets
@@ -277,17 +249,7 @@ function maybeMaskChanges(events, maskSecrets) {
  */
 function maybeMaskFindings(findings, changes, maskSecrets) {
   if (!maskSecrets) return findings;
-  return findings.map((finding) => {
-    let message = String(finding.message ?? '');
-    for (const change of changes.filter((event) => event.path === finding.path)) {
-      for (const value of [change.before, change.after]) {
-        const original = String(value);
-        const masked = String(maskSensitiveValue(value, secretMatchPath(change)));
-        if (original && original !== masked) message = message.replaceAll(original, masked);
-      }
-    }
-    return { ...finding, message: redactSecretString(message) };
-  });
+  return maskFindings(findings, changes);
 }
 
 /**
@@ -347,6 +309,37 @@ function restoreSnapshotDocumentKeys(state, snapshot) {
   return withDocumentKeys(state, documents.map(String));
 }
 
+/**
+ * Read a snapshot named as a path, with the containment every other read in
+ * Flecto already has.
+ *
+ * A baseline path is attacker-reachable in the shape that matters: the
+ * operator names an in-repo snapshot such as `.flecto/baseline.json`, and the
+ * pull request replaces that file with a symlink. Without this check the
+ * contents of any JSON file on the runner became the "baseline" and were
+ * printed as `removed` changes -- the same read-outside-the-repo leak that
+ * `assertTargetContained` was added for, and that `src/mcp.js` already refuses
+ * for a ref naming a file. This was the one remaining surface without the rule.
+ *
+ * `assertTargetContained` is about escape, not location, so an operator's
+ * deliberate absolute path to a snapshot outside the project still works.
+ * @param {string} given
+ * @param {string} option the flag to name in an error
+ * @returns {unknown}
+ */
+function readSnapshotFile(given, option) {
+  if (given === '') {
+    // An unset CI variable expands to this. Everything else here refuses
+    // loudly; silently falling back to the local store would be the one path
+    // that quietly compares against something the operator did not choose.
+    throw new Error(`${option} was given an empty value`);
+  }
+  const resolved = resolve(given);
+  assertTargetContained(resolved, process.cwd());
+  if (!existsSync(resolved)) throw new Error(`no snapshot file at "${given}"`);
+  return readSnapshotStateFromFile(resolved);
+}
+
 function readSnapshotStateFromFile(snapshotPath) {
   const snap = JSON.parse(readFileSync(snapshotPath, 'utf8'));
   return restoreSnapshotDocumentKeys(snap?.state ?? snap, snap);
@@ -367,7 +360,41 @@ function gitRepoRelativePath(filePath) {
   const top = execFileSync('git', ['-C', dirname(filePath), 'rev-parse', '--show-toplevel'], {
     encoding: 'utf8',
   }).trim();
-  return relative(canonicalPath(top), canonicalPath(filePath)).replaceAll('\\', '/');
+  // Canonicalize the *directory* and keep the name as written. Canonicalizing
+  // the file itself resolved its final symlink, so the path handed to
+  // `git show` was the link's destination rather than the path the operator
+  // gated -- and a pull request that replaced the gated file with a link to any
+  // other file unchanged in the baseline got `before == after`, a genuinely
+  // empty diff that no --fail-on value catches. Every reason the comment above
+  // gives for canonicalizing (Windows 8.3 and case, the macOS /tmp and /var
+  // links) is a property of directories, so none of it is lost.
+  const nominal = join(canonicalPath(dirname(filePath)), basename(filePath));
+  return relative(canonicalPath(top), nominal).replaceAll('\\', '/');
+}
+
+/**
+ * Is the entry at this path, in this commit, a symbolic link?
+ *
+ * Git stores a link as mode 120000 whose blob is the *target path*, so reading
+ * one as a config file yields the target string rather than any configuration.
+ * That is a baseline Flecto cannot honestly compare against, and saying so
+ * beats emitting a diff between a filename and a document.
+ * @param {string} commit
+ * @param {string} rel
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function baselineEntryIsSymlink(commit, rel, dir) {
+  try {
+    const entry = execFileSync(
+      'git',
+      ['-C', dir, 'ls-tree', '--format=%(objectmode)', '--end-of-options', commit, '--', rel],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    return entry === '120000';
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -402,29 +429,169 @@ function canonicalPath(path) {
   }
 }
 
-function readSnapshotStateFromRef(filePath, snapshotRef) {
+function gitFailureReason(err) {
+  if (err?.code === 'ENOENT') return 'git is not installed or not on PATH';
+  if (err?.status === 128) return 'this is not a git repository';
+  // The most likely remaining cause by far: `--end-of-options` arrived in git
+  // 2.24 (2019), and an older git rejects it as an unknown option. Naming a
+  // version someone can check beats printing the raw spawn failure.
+  return 'git rejected the command -- Flecto needs git 2.24 or newer'
+    + ` (${String(err?.message ?? 'unknown error').split('\n')[0]})`;
+}
+
+/**
+ * Resolve a ref to the single commit it names, or null when it names none.
+ *
+ * `git show` accepts far more than a commit: `A..B` is a *range*, and asking
+ * it to show one succeeds while printing nothing. An empty read then parses as
+ * an empty document, every key looks `added` rather than `changed`, and the
+ * default `--fail-on changed,policy,error` never fires -- the same silent-pass
+ * chain as the `--output=` injection, reached without a single dash.
+ * `rev-parse --verify <ref>^{commit}` refuses anything that is not exactly one
+ * commit, which closes the whole shape rather than the one spelling of it.
+ *
+ * Resolving also means the value handed to `git show` afterwards is a hex SHA
+ * this function produced, not a string the attacker wrote.
+ * @param {string} ref
+ * @param {string} dir a directory inside the repository
+ * @returns {string | null} the commit SHA, or null when `ref` is not a revision
+ */
+function resolveGitCommit(ref, dir) {
+  try {
+    const out = execFileSync(
+      'git',
+      ['-C', dir, 'rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    return { usable: true, commit: out || null };
+  } catch (err) {
+    // Exactly one failure means "git works, that revision is not here": exit 1
+    // from `--verify --quiet`. Everything else -- git missing (ENOENT), not a
+    // repository (128), an option this git does not know (pre-2.24) -- means
+    // Flecto cannot tell whether the ref exists. Collapsing those into "not a
+    // revision" is what let a missing git turn a baseline into whatever file
+    // happened to share the ref's name.
+    if (err?.status === 1) return { usable: true, commit: null };
+    return { usable: false, commit: null, reason: gitFailureReason(err) };
+  }
+}
+
+/**
+ * Is this value written the way a *path* is written, rather than a revision?
+ *
+ * `--snapshot-ref` has always accepted either a git revision or a snapshot
+ * file, and that ambiguity is the vulnerability: the file is resolved against
+ * the checkout root, whose file names an untrusted pull request controls. A
+ * pull request that commits a file named after the operator's ref replaces the
+ * baseline with one the attacker wrote, and since they can make it match their
+ * own tip exactly, the diff is genuinely empty -- no `--fail-on` setting
+ * catches it.
+ *
+ * The first attempt at this asked "does the value look like a revision?" and
+ * refused the file branch when it did. That is a denylist over a value space
+ * identical to the one it is trying to exclude: branch and tag names are
+ * ordinary words, so `origin/main`, `main`, and `v1.2.3` all fell through it
+ * and stayed exploitable -- and `origin/main` is the form this project's own
+ * documentation puts in a workflow.
+ *
+ * So the polarity is inverted. The *file* branch must prove itself, and the
+ * proof is a shape the git ref grammar cannot produce: an absolute path, or an
+ * explicit `./` or `../`. Everything else must resolve as a revision or the run
+ * fails, pointing at `--snapshot-file`. The failure mode is now "a snapshot
+ * file named like a ref is refused, and says which flag to use" rather than
+ * "an attacker's file is read as the baseline".
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isExplicitPath(value) {
+  // git-check-ref-format forbids a ref whose component begins with `.` and a
+  // ref beginning with `/`, so none of these can name a revision. An earlier
+  // version of this also accepted a `.json`/`.yaml` suffix, which was the same
+  // mistake a third time: those ARE legal in a ref name, so `release/v1.json`
+  // skipped git entirely and read an attacker's committed file in preference to
+  // a real, resolvable tag of that name. A suffix is a convention; these are a
+  // grammar.
+  return isAbsolute(value)
+    || value.startsWith('./')
+    || value.startsWith('../')
+    || value.startsWith('.\\')
+    || value.startsWith('..\\');
+}
+
+function readSnapshotStateFromRef(filePath, snapshotRef, store, snapshotFile) {
+  if (snapshotRef === '') {
+    // The same unset-CI-variable case readSnapshotFile refuses. Falling back to
+    // the store here would compare against something the operator did not
+    // choose -- and on an untrusted pull request a committed shared store is
+    // something the change under review wrote.
+    throw new Error('--snapshot-ref was given an empty value');
+  }
+  // `--snapshot-file` is the unambiguous form: a path, never a revision. It
+  // exists because overloading one flag with both is what made an
+  // attacker-committed file able to stand in for the operator's baseline.
+  if (snapshotFile !== undefined) {
+    return readSnapshotFile(String(snapshotFile), '--snapshot-file');
+  }
   if (!snapshotRef) {
-    const snapshotPath = snapshotPathForFile(filePath);
     // Failing closed here is right — a diff with no baseline is not a clean
-    // diff — but an ENOENT on a hashed filename explains nothing. Snapshot
-    // history is local to the working directory, so this is what an ephemeral
-    // CI runner hits on every run (#141).
-    if (!existsSync(snapshotPath)) {
-      throw new Error(
-        `no local snapshot has been saved for this file (${SNAPSHOT_DIR}/ holds none).`
-          + ' Save one with "flecto watch <file> --snapshot", or pass --snapshot-ref'
-          + ' <git-ref> to diff against a committed revision instead',
-      );
+    // diff — but an ENOENT on a hashed filename explains nothing. The default
+    // store is local to the working directory, so this is what an ephemeral CI
+    // runner hits on every run; the message names the store it looked in and
+    // the two ways to give it one (#141).
+    const record = store.readLatest(filePath);
+    if (!record) {
+      throw new Error(`no snapshot has been saved for this file (${store.emptyHint})`);
     }
-    return readSnapshotStateFromFile(snapshotPath);
+    return record.state;
   }
-  const maybePath = resolve(snapshotRef);
-  if (existsSync(maybePath)) {
-    return readSnapshotStateFromFile(maybePath);
+  // The path decision comes before assertSafeGitRef, which refuses `..` -- a
+  // legitimate `../snapshots/base.json` is a path, not a commit range.
+  if (isExplicitPath(String(snapshotRef))) {
+    return readSnapshotFile(String(snapshotRef), '--snapshot-ref');
+  }
+
+  const ref = assertSafeGitRef(snapshotRef);
+  const repoDir = dirname(resolve(filePath));
+  const { usable, commit, reason } = resolveGitCommit(ref, repoDir);
+  if (!usable) {
+    // Never fall through to a file here. Not knowing whether the revision
+    // exists is exactly when reading a same-named file is most dangerous.
+    throw new Error(
+      `cannot resolve "${ref}" as a git revision: ${reason}.`
+      + ' Pass --snapshot-file <path> if you meant a snapshot file.',
+    );
+  }
+  if (!commit) {
+    const shadow = resolve(ref);
+    throw new Error(
+      `"${ref}" does not resolve to a git revision here`
+      + ' (a shallow clone is the usual reason -- on a pull request, actions/checkout does not'
+      + ' create origin/<base> unless you fetch it; try fetch-depth: 0).'
+      + (existsSync(shadow)
+        ? ` A file named "${ref}" exists and was NOT read as the baseline: a pull request can`
+        + ' commit such a file, and reading it would let the change under review choose what it'
+        + ' is compared against. Pass --snapshot-file if you genuinely meant that file.'
+        : ' Pass --snapshot-file <path> if you meant a snapshot file.'),
+    );
   }
 
   const rel = gitRepoRelativePath(filePath);
-  const raw = execFileSync('git', ['show', `${snapshotRef}:${rel}`], { encoding: 'utf8' });
+  if (baselineEntryIsSymlink(commit, rel, repoDir)) {
+    throw new Error(
+      `"${rel}" is a symbolic link in ${ref}, so the baseline there is a path, not a configuration.`
+      + ' Point --snapshot-ref at a revision where it is a regular file, or gate the file the link'
+      + ' resolves to.',
+    );
+  }
+  // `-C repoDir` matches where the revision was resolved, and the operand is a
+  // SHA this process produced rather than any string the attacker wrote.
+  // maxBuffer matches the LSP's reader: a megabyte-scale baseline blob is
+  // ordinary, and the default 1 MB dies with a raw ENOBUFS.
+  const raw = execFileSync(
+    'git',
+    ['-C', repoDir, 'show', '--end-of-options', `${commit}:${rel}`],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 },
+  );
   return parseContent(filePath, raw);
 }
 
@@ -651,6 +818,50 @@ async function deliverPrCommentSafely(body, enabled, provider) {
   }
 }
 
+/**
+ * `ci --explain` (#143): narration for the run, or null.
+ *
+ * Called only after the gate is decided, and it cannot change it: every failure
+ * here — no provider configured, over budget, network, refusal — is a warning
+ * and a null, never a thrown error. Status goes to stderr, so the machine
+ * output on stdout is byte-for-byte what it is without the flag.
+ * @param {import('./src/explain.js').ExplainInputFile[]} files unmasked; the payload builder masks
+ * @param {{ dryRun: boolean, cwd: string }} options
+ * @returns {Promise<{ text: string, provider: string, model: string, cached: boolean, truncated: boolean } | null>}
+ */
+async function narrateForCi(files, { dryRun, cwd }) {
+  try {
+    const payload = buildExplainPayload(files, { cwd });
+    if (payload.files.length === 0) {
+      renderNote('flecto explain: nothing to narrate — no changes and no findings.');
+      return null;
+    }
+    const resolved = resolveExplainConfig({}, process.env, { dryRun });
+    if (!resolved.ok) {
+      renderWarn(`No narration: ${resolved.reason}.`);
+      return null;
+    }
+    if (dryRun) {
+      const request = describeRequest(buildExplainRequest(payload, resolved.config), resolved.config);
+      renderNote(
+        `flecto explain --explain-dry-run: nothing was sent. ~${estimateInputTokens(request.body)} input`
+        + ` tokens (estimated), output capped at ${resolved.config.maxTokens}. The request:`,
+      );
+      process.stderr.write(`${JSON.stringify(request, null, 2)}\n`);
+      return null;
+    }
+    const result = await narrate(payload, resolved.config, { onNote: renderNote });
+    if (!result.ok) {
+      renderWarn(`No narration: ${result.reason}.`);
+      return null;
+    }
+    return result;
+  } catch (err) {
+    renderWarn(`No narration: ${err.message}.`);
+    return null;
+  }
+}
+
 program
   .name('flecto')
   .description('Flecto — semantic config watcher for meaningful structured file changes')
@@ -684,6 +895,10 @@ program
   .option('--mask-secrets-webhooks', 'Also mask secrets in webhook payloads', false)
   .option('--snapshot', 'Save current state as baseline instead of watching')
   .option('--diff', 'Diff current file against saved baseline and exit')
+  .option('--snapshot-store <id>', `Snapshot store: ${SNAPSHOT_STORE_IDS.join(' | ')} (shared is repo-relative and meant to be committed)`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
+  .option('--snapshot-mask <mode>', `How the store records secret-like values: ${SNAPSHOT_MASK_MODES.join(' | ')} (default: hash for shared, none for local)`)
+  .option('--snapshot-retention <n>', 'Snapshots kept per file, 0 keeps every one (default: 20 for shared, unlimited for local)')
   .option('--allow-empty', 'Allow --snapshot to succeed when nothing was written', false)
   .action(async (files, opts, command) => {
     try {
@@ -691,6 +906,7 @@ program
       const profile = resolveProfileName(opts.profile);
       const cliOverrides = stripUnsetCliOverrides(opts, command);
       const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      assertAlertActionsFromCli(effective, cliOverrides);
       const { policies, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
@@ -707,16 +923,18 @@ program
       const maskSecretsWebhooks = Boolean(effective.maskSecretsWebhooks);
       const webhookFormat = resolveWebhookFormat(effective.webhookFormat, effective.webhook);
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
+      const snapshotStore = snapshotStoreFromEffective(effective);
 
       if (effective.snapshot) {
-        mkdirSync(SNAPSHOT_DIR, { recursive: true });
-        // Snapshots carry config values, so a .flecto-snapshots/ that is itself a
+        mkdirSync(snapshotStore.root, { recursive: true });
+        // Snapshots carry config values, so a store directory that is itself a
         // link out of the project would write them somewhere the repository does
         // not control. Same rule as a target, checked after mkdir so an existing
         // link is seen rather than a path that does not exist yet.
-        assertTargetContained(resolve(SNAPSHOT_DIR), process.cwd());
-        const idsWithHistory = snapshotIdsWithHistory();
+        assertTargetContained(snapshotStore.root, process.cwd());
         let written = 0;
+        let pruned = 0;
+        const warnings = new Set();
         for (const filepath of targets) {
           if (!existsSync(filepath)) {
             renderWarn(`Skipping missing file: ${filepath}`);
@@ -727,25 +945,32 @@ program
             continue;
           }
           const state = parseFile(filepath);
-          const snapshotPath = snapshotPathForFile(filepath);
-          preserveLegacySnapshotForHistory(filepath, snapshotPath, idsWithHistory);
           // Only a multi-document file records `documents`, so an ordinary
           // snapshot is byte-for-byte what it was before this field existed.
-          const documents = documentKeysOf(state) ?? [];
-          const snapshot = {
-            file: filepath,
+          const result = snapshotStore.write(filepath, {
             state,
-            ...(documents.length > 0 ? { documents: [...documents] } : {}),
-            createdAt: new Date().toISOString(),
-          };
-          writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), 'utf8');
-          writeFileSync(snapshotHistoryPathForFile(filepath), JSON.stringify(snapshot, null, 2), 'utf8');
-          // Keep the set in step with what this run has written, so a repeated
-          // target behaves exactly as it did when the check hit the disk.
-          idsWithHistory.add(snapshotIdForPath(filepath));
-          console.log(chalk.green(`✓ Snapshot saved: ${snapshotPath}`));
+            documents: documentKeysOf(state) ?? [],
+          });
+          if (result.warning) warnings.add(result.warning);
+          pruned += result.pruned;
+          console.log(chalk.green(`✓ Snapshot saved: ${result.path}`));
           written += 1;
         }
+        for (const warning of warnings) renderWarn(warning);
+        if (pruned > 0) {
+          renderNote(
+            `Pruned ${pruned} snapshot${pruned === 1 ? '' : 's'} beyond the`
+            + ` ${snapshotStore.retention}-entry retention of the ${snapshotStore.id} store.`,
+          );
+        }
+        if (written > 0 && snapshotStore.id === 'shared') {
+          renderNote(
+            `Shared store: commit ${snapshotStore.label} so every runner reads the same history.`
+            + (snapshotStore.maskMode === 'none'
+              ? ' Masking is off, so these files carry config values verbatim into git history.'
+              : ' Secret-like values are stored as digests, not plaintext.'),
+          );
+        }
         if (written === 0 && !effective.allowEmpty) {
           throw new Error(
             'No snapshots written — all targets were missing or unsupported.' +
@@ -760,14 +985,14 @@ program
         let compared = 0;
         let missing = 0;
         for (const filepath of targets) {
-          const snapshotPath = snapshotPathForFile(filepath);
-          if (!existsSync(snapshotPath)) {
-            renderWarn(`No snapshot found for "${filepath}"`);
+          const record = snapshotStore.readLatest(filepath);
+          if (!record) {
+            renderWarn(`No snapshot found for "${filepath}" in ${snapshotStore.label}`);
             missing += 1;
             continue;
           }
-          const before = readSnapshotStateFromFile(snapshotPath);
-          const after = parseFile(filepath);
+          const before = record.state;
+          const after = alignStateWithStore(parseFile(filepath), snapshotStore);
           const events = diffTrees(before, after, dOpts);
           renderDiff(filepath, events, { maskSecrets });
           compared += 1;
@@ -779,7 +1004,7 @@ program
         // is the normal state of a fresh CI runner.
         if (compared === 0) {
           throw new Error(
-            'No snapshot found for any target, so nothing was compared.'
+            `No snapshot found for any target in ${snapshotStore.label}, so nothing was compared.`
               + ' Run "flecto watch <file> --snapshot" first — no history is not no drift.',
           );
         }
@@ -897,8 +1122,10 @@ program
 
 program
   .command('history [files...]')
-  .description('Summarize drift across local snapshots')
+  .description('Summarize drift across saved snapshots')
   .option('-l, --limit <n>', 'Number of recent snapshots to show', '10')
+  .option('--snapshot-store <id>', `Snapshot store to read: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
   .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('--ignore <keys>', 'Comma-separated key paths to ignore (e.g. "updated_at,meta.ts")')
   .option('--array-id-key <key>', 'Diff arrays by this object identity key (opt-in)')
@@ -917,7 +1144,8 @@ program
       const ignorePaths = parseCsv(effective.ignore);
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
-      const allSnapshots = readLocalSnapshotHistory();
+      const snapshotStore = snapshotStoreFromEffective(effective);
+      const allSnapshots = snapshotStore.readHistory();
       let snapshots = allSnapshots;
       if (files.length > 0) {
         const targets = new Set((await resolveTargetFiles(files, config)).map((file) => resolve(file)));
@@ -928,13 +1156,20 @@ program
       if (summaries.length === 0) {
         if (files.length > 0 && allSnapshots.length > 0) {
           throw new Error(
-            'No local snapshots matched the given files. Omit files to view all saved snapshot history.',
+            `No snapshots in ${snapshotStore.label} matched the given files.`
+            + ' Omit files to view all saved snapshot history.',
           );
         }
-        throw new Error('No local snapshots found. Run "flecto watch <file> --snapshot" first.');
+        throw new Error(
+          `No snapshots found in ${snapshotStore.label}.`
+          + ` Run "flecto watch <file> --snapshot${snapshotStore.id === 'shared' ? ' --snapshot-store shared' : ''}" first`
+          + ' — no history is not no drift.',
+        );
       }
 
-      console.log(`Local snapshot history (${summaries.length} snapshots)`);
+      console.log(
+        `Snapshot history from ${snapshotStore.label} (${summaries.length} snapshots, ${snapshotStore.id} store)`,
+      );
       let baselines = 0;
       for (const snapshot of summaries) {
         const file = relative(process.cwd(), snapshot.file) || snapshot.file;
@@ -965,8 +1200,10 @@ program
 
 program
   .command('report [files...]')
-  .description('Render local snapshot history as a self-contained HTML report')
+  .description('Render saved snapshot history as a self-contained HTML report')
   .option('-o, --output <path>', 'Write the report to this path', 'flecto-report.html')
+  .option('--snapshot-store <id>', `Snapshot store to read: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
   .option('-l, --limit <n>', 'Number of recent snapshots to include', '10')
   .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('--ignore <keys>', 'Comma-separated key paths to ignore (e.g. "updated_at,meta.ts")')
@@ -992,10 +1229,15 @@ program
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
       const maskSecrets = Boolean(effective.maskSecrets);
       const outputPath = resolve(String(effective.output ?? 'flecto-report.html'));
+      assertWriteDestinationContained(outputPath, {
+        option: '--output',
+        fromCli: cliOverrides.output !== undefined,
+      });
 
       // Same snapshot source, filtering, and errors as `flecto history` — this
       // command only changes how that history is rendered.
-      const allSnapshots = readLocalSnapshotHistory();
+      const snapshotStore = snapshotStoreFromEffective(effective);
+      const allSnapshots = snapshotStore.readHistory();
       let snapshots = allSnapshots;
       if (files.length > 0) {
         const targets = new Set((await resolveTargetFiles(files, config)).map((file) => resolve(file)));
@@ -1006,10 +1248,15 @@ program
       if (summaries.length === 0) {
         if (files.length > 0 && allSnapshots.length > 0) {
           throw new Error(
-            'No local snapshots matched the given files. Omit files to report on all saved snapshot history.',
+            `No snapshots in ${snapshotStore.label} matched the given files.`
+            + ' Omit files to report on all saved snapshot history.',
           );
         }
-        throw new Error('No local snapshots found. Run "flecto watch <file> --snapshot" first.');
+        throw new Error(
+          `No snapshots found in ${snapshotStore.label}.`
+          + ` Run "flecto watch <file> --snapshot${snapshotStore.id === 'shared' ? ' --snapshot-store shared' : ''}" first`
+          + ' — no history is not no drift.',
+        );
       }
 
       const reportSnapshots = [];
@@ -1043,6 +1290,7 @@ program
         version: PKG.version,
         limit,
         maskSecrets,
+        store: snapshotStore.label,
       });
       mkdirSync(dirname(outputPath), { recursive: true });
       writeFileSync(outputPath, html, 'utf8');
@@ -1059,7 +1307,10 @@ program
   .command('ci [files...]')
   .description('Run semantic diff in CI mode')
   .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
-  .option('--snapshot-ref <ref>', 'Snapshot reference: snapshot path or git ref')
+  .option('--snapshot-ref <ref>', 'Baseline git revision (a snapshot path also works if it is path-shaped)')
+  .option('--snapshot-file <path>', 'Baseline snapshot file, never consulted as a git revision')
+  .option('--snapshot-store <id>', `Snapshot store to read: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
   .option('--format <type>', 'Output format: json | ndjson | sarif | github-annotations | pr-comment', 'json')
   .option('--pr-comment-post', 'With --format pr-comment, upsert the comment on the PR (needs a token + merge request context)', false)
   .option('--pr-provider <name>', `Force the comment delivery target: ${PR_PROVIDER_IDS.join(' | ')} (default: detect from CI)`)
@@ -1076,12 +1327,18 @@ program
   .option('--show-suppressed', 'List inline-suppressed findings instead of only counting them', false)
   .option('--changed-only', 'With --format json|ndjson, replace envelopes for unchanged files with one scanned manifest', false)
   .option('--allow-empty', 'Allow CI to succeed when no files were diffed', false)
+  .option('--explain', 'Add model-generated narration of the masked diff (advisory; provider set by FLECTO_EXPLAIN_* env)', false)
+  .option('--explain-dry-run', 'Print the narration request that --explain would send, and send nothing', false)
   .action(async (files, opts, command) => {
     try {
       const { config } = loadRcConfig(process.cwd());
       const profile = resolveProfileName(opts.profile);
       const cliOverrides = stripUnsetCliOverrides(opts, command);
       const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      assertExplainNotFromRc(effective, cliOverrides);
+      assertSnapshotRefFromCli(effective, cliOverrides);
+      const explainDryRun = Boolean(cliOverrides.explainDryRun);
+      const explainRequested = Boolean(cliOverrides.explain) || explainDryRun;
       const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
@@ -1112,14 +1369,37 @@ program
       }
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
+      const snapshotStore = snapshotStoreFromEffective(effective);
+
       const cwd = process.cwd();
       const baselinePath = effective.baseline ? resolve(cwd, String(effective.baseline)) : null;
+      if (baselinePath) {
+        assertWriteDestinationContained(baselinePath, {
+          option: '--baseline',
+          fromCli: cliOverrides.baseline !== undefined,
+          cwd,
+        });
+      }
+      // `--update-baseline` accepts every finding this run produced, so honoring
+      // it from `.flectorc` would let a pull request turn its own failing gate
+      // green — including one whose `--fail-on` was set explicitly on the command
+      // line. It is an action, not a setting: the CLI is the only place it can
+      // come from, and a declaration in the rc file is refused rather than
+      // ignored, so a repository that meant it finds out.
+      if (effective.updateBaseline && cliOverrides.updateBaseline === undefined) {
+        throw new Error(
+          'updateBaseline is declared in .flectorc, and it is refused there: it accepts every'
+          + ' current finding, which would turn a failing gate green from a file a pull request'
+          + ' can edit. Pass --update-baseline on the command line when you mean to record a'
+          + ' baseline.',
+        );
+      }
       const updateBaseline = Boolean(effective.updateBaseline);
       if (updateBaseline && !baselinePath) {
         throw new Error('--update-baseline requires --baseline <file> naming the file to write.');
       }
 
-      /** @type {Array<{ filepath: string, relFile: string, outboundChanges: any[], outboundFindings: any[], changesFail: boolean }>} */
+      /** @type {Array<{ filepath: string, relFile: string, events: any[], outboundChanges: any[], outboundFindings: any[], changesFail: boolean }>} */
       const perFile = [];
       /** @type {Array<{ file: string, finding: any, reason: string }>} */
       const allSuppressed = [];
@@ -1134,10 +1414,14 @@ program
           renderWarn(`Skipping unsupported file: ${filepath}`);
           continue;
         }
-        const after = parseFile(filepath);
+        // A `--snapshot-ref` baseline is read straight from git, so it is never
+        // masked; only a store-provided baseline needs the live side aligned.
+        const after = (effective.snapshotRef || effective.snapshotFile)
+          ? parseFile(filepath)
+          : alignStateWithStore(parseFile(filepath), snapshotStore);
         let before;
         try {
-          before = readSnapshotStateFromRef(filepath, effective.snapshotRef);
+          before = readSnapshotStateFromRef(filepath, effective.snapshotRef, snapshotStore, effective.snapshotFile);
         } catch (err) {
           throw new Error(
             `Failed to resolve snapshot baseline for "${filepath}"` +
@@ -1167,6 +1451,7 @@ program
         perFile.push({
           filepath,
           relFile: baselineRelativePath(filepath, cwd),
+          events,
           outboundChanges: maybeMaskChanges(events, maskSecrets),
           outboundFindings: maybeMaskFindings(policyFindings, events, maskSecrets),
           changesFail: shouldFailFromChanges(events, failOn),
@@ -1268,13 +1553,24 @@ program
         }
       }
 
+      // Asked for only once `shouldFail` is settled, and handed nothing that
+      // could change it. Narration covers the findings the gate sees — active
+      // ones, after baseline and suppressions.
+      const narration = explainRequested
+        ? await narrateForCi(
+          perFile.map((f) => ({ file: f.filepath, changes: f.events, findings: activeByFile.get(f.relFile) ?? [] })),
+          { dryRun: explainDryRun, cwd },
+        )
+        : null;
+
       if (format === 'pr-comment') {
-        const body = renderPrComment(results, { cwd, failed: shouldFail });
+        const body = renderPrComment(results, { cwd, failed: shouldFail, narration });
         await writeStdout(body);
         await deliverPrCommentSafely(body, prCommentPost, effective.prProvider);
       } else {
         const collapsible = changedOnly && (format === 'json' || format === 'ndjson');
         await printCiOutput(collapsible ? collapseUnchangedResults(results) : results, format);
+        if (narration) process.stderr.write(`\n${formatNarration(narration)}\n`);
       }
       process.exit(shouldFail ? 1 : 0);
     } catch (err) {
@@ -1283,6 +1579,161 @@ program
     }
   });
 
+program
+  .command('explain [files...]')
+  .description('Narrate the masked semantic diff with a model you configure — advisory, opt-in, bring your own key (#143)')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
+  .option('--snapshot-ref <ref>', 'Baseline git revision (a snapshot path also works if it is path-shaped)')
+  .option('--snapshot-file <path>', 'Baseline snapshot file, never consulted as a git revision')
+  .option('--snapshot-store <id>', `Snapshot store to read: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
+  .option('--provider <id>', `Model provider: ${EXPLAIN_PROVIDERS.join(' | ')} (else FLECTO_EXPLAIN_PROVIDER)`)
+  .option('--model <name>', 'Model id (else FLECTO_EXPLAIN_MODEL; anthropic defaults to claude-opus-5)')
+  .option('--max-tokens <n>', 'Output token cap (else FLECTO_EXPLAIN_MAX_TOKENS; default 16000)')
+  .option('--format <type>', 'Output format: human | json', 'human')
+  .option('--dry-run', 'Print the exact request that would be sent, and send nothing', false)
+  .option('--no-cache', 'Neither read nor write the narration cache')
+  .option('--ignore <keys>', 'Comma-separated key paths to ignore')
+  .option('--policies <ids>', 'Comma-separated policy pack ids')
+  .option('--plugins <paths>', 'Comma-separated local ESM plugin paths')
+  .option('--array-id-key <key>', 'Diff arrays by this object identity key')
+  .option('--no-array-id', 'Diff arrays by index instead of object identity')
+  .option('--array-ignore-order', 'Treat array order as insignificant', false)
+  .action(async (files, opts, command) => {
+    try {
+      const { config } = loadRcConfig(process.cwd());
+      const profile = resolveProfileName(opts.profile);
+      const cliOverrides = stripUnsetCliOverrides(opts, command);
+      const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      assertExplainNotFromRc(effective, cliOverrides);
+      assertSnapshotRefFromCli(effective, cliOverrides);
+      // Everything that shapes the request is read from the command line, never
+      // from the merged options: `.flectorc` can name a `format` or `model` for
+      // other commands, and none of it may steer where the diff goes.
+      const format = String(cliOverrides.format ?? 'human');
+      if (!['human', 'json'].includes(format)) {
+        throw new Error('--format must be human or json');
+      }
+      const dryRun = Boolean(cliOverrides.dryRun);
+      const snapshotRef = cliOverrides.snapshotRef;
+      const snapshotFile = cliOverrides.snapshotFile;
+      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
+      const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
+      if (targets.length === 0) {
+        throw new Error('No files matched. Provide files or configure .flectorc files/include.');
+      }
+      const dOpts = diffOptionsFromEffective(effective, parseCsv(effective.ignore));
+      const snapshotStore = snapshotStoreFromEffective(effective);
+      const cwd = process.cwd();
+
+      /** @type {import('./src/explain.js').ExplainInputFile[]} */
+      const diffed = [];
+      for (const filepath of targets) {
+        if (!existsSync(filepath)) {
+          renderWarn(`Skipping missing file: ${filepath}`);
+          continue;
+        }
+        if (!isSupported(filepath)) {
+          renderWarn(`Skipping unsupported file: ${filepath}`);
+          continue;
+        }
+        const after = (snapshotRef || snapshotFile)
+          ? parseFile(filepath)
+          : alignStateWithStore(parseFile(filepath), snapshotStore);
+        let before;
+        try {
+          before = readSnapshotStateFromRef(filepath, snapshotRef, snapshotStore, snapshotFile);
+        } catch (err) {
+          throw new Error(
+            `Failed to resolve snapshot baseline for "${filepath}"`
+            + `${snapshotRef ? ` (ref: ${snapshotRef})` : ''}: ${err.message}`,
+          );
+        }
+        const events = diffTrees(before, after, dOpts);
+        const rawFindings = await evaluatePolicies(events, {
+          cwd,
+          file: filepath,
+          profile: profile ?? null,
+          source: 'diff',
+          policies: packIds,
+          plugins,
+          severityRemap,
+        });
+        const { active } = resolveSuppressed(filepath, rawFindings);
+        diffed.push({ file: filepath, changes: events, findings: active });
+      }
+      if (diffed.length === 0) {
+        throw new Error('No files were diffed — all targets were missing or unsupported.');
+      }
+
+      // The operator sees what is narrated, masked the way it is sent.
+      if (format === 'human') {
+        for (const { file, changes, findings } of diffed) {
+          renderDiff(file, changes, { maskSecrets: true, baseline: snapshotRef ?? 'snapshot' });
+          renderPolicyFindings(maskFindings(findings, changes));
+        }
+      }
+
+      const payload = buildExplainPayload(diffed, { cwd });
+      if (payload.files.length === 0) {
+        if (format === 'json') {
+          await writeStdout(JSON.stringify({ advisory: true, narration: null, reason: 'no changes and no findings', payload }, null, 2));
+        } else {
+          renderInfo('Nothing to narrate: no semantic changes and no policy findings.');
+        }
+        process.exit(0);
+      }
+
+      const resolved = resolveExplainConfig(
+        {
+          provider: cliOverrides.provider,
+          model: cliOverrides.model,
+          maxTokens: cliOverrides.maxTokens,
+          cache: cliOverrides.cache,
+        },
+        process.env,
+        { dryRun },
+      );
+      if (!resolved.ok) throw new Error(`Cannot narrate: ${resolved.reason}.`);
+
+      if (dryRun) {
+        const request = describeRequest(buildExplainRequest(payload, resolved.config), resolved.config);
+        renderNote(
+          `flecto explain --dry-run: nothing was sent. ~${estimateInputTokens(request.body)} input tokens`
+          + ` (estimated), output capped at ${resolved.config.maxTokens}.`,
+        );
+        await writeStdout(JSON.stringify(request, null, 2));
+        process.exit(0);
+      }
+
+      const result = await narrate(payload, resolved.config, { onNote: renderNote });
+      if (format === 'json') {
+        await writeStdout(JSON.stringify({
+          advisory: true,
+          narration: result.ok
+            ? {
+              model_generated: true,
+              provider: result.provider,
+              model: result.model,
+              cached: result.cached,
+              truncated: result.truncated,
+              text: result.text,
+            }
+            : null,
+          reason: result.ok ? undefined : result.reason,
+          payload,
+        }, null, 2));
+      } else if (result.ok) {
+        await writeStdout(`\n${formatNarration(result)}`);
+      }
+      if (!result.ok) renderWarn(`No narration: ${result.reason}.`);
+      process.exit(0);
+    } catch (err) {
+      renderError(err.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('plan <planFiles...>')
   .description('Diff Terraform plan JSON (terraform show -json) and run policies on it')
@@ -1583,6 +2034,75 @@ program
     renderInfo(`Policy packs: ${detection.packs.join(', ')}`);
   });
 
+program
+  .command('mcp')
+  .description('Run Flecto as a read-only Model Context Protocol server over stdio (#140)')
+  .action(async () => {
+    // The server writes JSON-RPC to stdout and nothing else, so diagnostics go
+    // to stderr. Tools invoke the read-only `ci` path as a subprocess of this
+    // same CLI; the seam is the JSON envelope, so this lifts cleanly into a
+    // standalone flecto-mcp package later without touching the protocol code.
+    const cliPath = fileURLToPath(import.meta.url);
+    const runFlecto = makeCliRunner({ nodeExec: process.execPath, cliPath, cwd: process.cwd() });
+    // Readiness goes to stderr — stdout must carry JSON-RPC and nothing else.
+    renderNote('flecto mcp: read-only server ready (stdio). Secrets masked by default.');
+    await runStdioServer({ version: PKG.version, cwd: process.cwd(), runFlecto });
+  });
+
+program
+  .command('lsp')
+  .description('Run a Language Server Protocol server over stdio: findings and changes as editor diagnostics (#142)')
+  .option('--stdio', 'Talk LSP over stdin/stdout (the only transport; accepted because editors pass it)')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
+  .option('--snapshot-ref <ref>', 'Git ref to diff open files against', 'HEAD')
+  .option('--snapshot-store <id>', `Diff against a snapshot store instead of git: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store')
+  .option('--plugins <paths>', 'Comma-separated absolute paths of ESM policy plugins to load (never read from .flectorc)')
+  .option('--changes <level>', 'How semantic changes appear: hint | info | none', 'hint')
+  .option('--debounce <ms>', 'Wait this long after the last edit before analyzing', '250')
+  .option('--timeout <ms>', 'Stop an analysis that runs longer than this', '10000')
+  .action(async (opts) => {
+    try {
+      const changes = String(opts.changes);
+      if (!['hint', 'info', 'none'].includes(changes)) {
+        throw new Error('--changes must be hint, info, or none');
+      }
+      const debounceMs = Number(opts.debounce);
+      const timeoutMs = Number(opts.timeout);
+      if (!Number.isInteger(debounceMs) || debounceMs < 0) throw new Error('--debounce must be a whole number of milliseconds');
+      if (!Number.isInteger(timeoutMs) || timeoutMs < 100) throw new Error('--timeout must be at least 100 milliseconds');
+      const plugins = opts.plugins === undefined ? undefined : parseCsv(opts.plugins);
+      // A relative path would resolve against whichever repository the editor
+      // opens — including one that ships a file at exactly that path.
+      for (const plugin of plugins ?? []) {
+        if (!isAbsolute(plugin)) {
+          throw new Error(`--plugins must be absolute paths in the language server (got "${plugin}"): a relative path would resolve inside whatever repository is open.`);
+        }
+      }
+      renderNote('flecto lsp: ready (stdio). Plugins from .flectorc are never loaded here.');
+      const { done } = startLanguageServer({
+        input: process.stdin,
+        output: process.stdout,
+        version: PKG.version,
+        cwd: process.cwd(),
+        debounceMs,
+        timeoutMs,
+        settings: {
+          profile: resolveProfileName(opts.profile),
+          plugins,
+          snapshotRef: opts.snapshotRef,
+          snapshotStore: opts.snapshotStore,
+          snapshotDir: opts.snapshotDir,
+          changes: /** @type {'hint' | 'info' | 'none'} */ (changes),
+        },
+      });
+      process.exit(await done);
+    } catch (err) {
+      renderError(err.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('doctor')
   .description('Check Flecto setup, config, and environment')