fv-skills-baif 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to FVS (Formal Verification Skills) will be documented in th
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.0.2] - 2026-07-02
+
+### Fixed
+- Codex installs now enable hooks with `[features].hooks = true` instead of an invalid root-level `hooks = true`, which current Codex parses as the hooks config table and rejects at startup.
+
+## [2.0.1] - 2026-07-01
+
+Documentation polish. No code or behavior changes.
+
+### Changed
+- README "How It Works" now documents the Aeneas extraction repair loop, the trust audit, and the paper track's crypto loop -- previously only the v1.x five-stage functional-correctness flow was described; the tagline and Prerequisites now cover both the code and paper tracks
+- `/fvs:help` documents the crypto loop's `--codex` single- vs dual-runtime flag (which stages accept it, what it swaps, and the no-silent-fallback behavior), and Quick Start / Core Workflow now surface the extraction and crypto-loop entry points
+- Install screenshot (`assets/terminal.svg`) version label updated to the v2.0 line
+
 ## [2.0.0] - 2026-06-30
 
 Structural cleanup and bundle architecture. Updating from v1.3 applies all renames, moves, and removals automatically (deleted and renamed commands/agents self-heal on install); the installer prints a one-time summary of the changes below.

package/README.md

@@ -2,7 +2,7 @@
 
 # FORMAL VERIFICATION SKILLS
 
-**Formal verification of Rust code with AI-assisted specification and proof. Multi-framework, multi-runtime.**
+**Formal verification in Lean 4 with AI-assisted specification and proof — for Rust code (via Aeneas) and for maths/crypto papers. Multi-runtime.**
 
 [![npm version](https://img.shields.io/npm/v/fv-skills-baif?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/fv-skills-baif)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
@@ -54,9 +54,10 @@ Verify with `/fvs:help` inside your chosen runtime.
 
 ### Prerequisites (Lean 4 / Aeneas)
 
-- A Lean 4 project with `lakefile.toml` and `lean-toolchain`
-- Aeneas-generated output (`Types.lean`, `Funs.lean`) from your Rust source
-- Lean 4 toolchain installed and working
+- A working Lean 4 toolchain, and a Lean project with `lakefile.toml` and `lean-toolchain`
+- **Functional-correctness track:** Aeneas-generated Lean (`Types.lean`, `Funs.lean`). Produce it from a Rust crate with `/fvs:aeneas-extract`, or supply the output of an existing Aeneas run.
+- **Paper track:** no Rust or Aeneas needed — bring your paper/source material (PDF, LaTeX, images).
+- **Optional:** the Codex CLI, to run the crypto loop's thinking stages dual-runtime (`--codex`).
 
 ### Recommended: Lean LSP MCP Server
 
@@ -150,7 +151,9 @@ Commands are grouped into five bundles. Each bundle has a **router** command tha
 
 ## How It Works
 
-FVS follows a five-stage workflow. Each stage builds on the previous.
+### Functional-correctness track (Rust → Lean 4)
+
+This track verifies Rust that Aeneas has lowered to Lean 4. Starting from a Rust crate, `/fvs:aeneas-extract <path>` drives it through the bounded **extraction repair loop** — pin audit → classify → auto-apply / bisect / gate / escalate → reversible records — until you reach a clean build or a documented escalation. It writes reversible source records (`src-modifications.diff` plus a derived `.json`/`.md` and `src-assumptions.md`) at the crate root and never edits generated Lean. Once you have `Types.lean` / `Funs.lean`, the five-stage verification workflow begins:
 
 ### 1. Map
 
@@ -172,6 +175,23 @@ FVS follows a five-stage workflow. Each stage builds on the previous.
 
 `/fvs:lean-refactor <spec_path>` — Refactor, simplify, and decompose verified proofs. Applies tiered heuristics (dead code removal, simp sharpening, tactic golf, smart automation) while verifying compilation after every change. Three modes: safe, balanced (default), and aggressive.
 
+### 6. Audit
+
+`/fvs:trust-audit <target>` — Build-backed audit of the trust surface. Runs a green-build precondition, then uses `#print axioms` to classify every in-scope declaration as verified / `sorry` / axiom. The classical trio (`propext`, `Classical.choice`, `Quot.sound`) is auto-noted as Lean/Mathlib-standard; any project-custom axiom must be justified or the gate reports NOT-CLEAN. Produces a re-runnable, dependency-ordered table under `.formalising/audits/`.
+
+### The paper track (maths / crypto)
+
+The paper track formalises papers directly into Lean 4 — no Rust, no Aeneas. Two entry points:
+
+- **One-shot:** `/fvs:lean-formalise` reads your PDFs / images / LaTeX (optionally grounded in a NotebookLM knowledge base via `/fvs:kb-setup`) and produces Lean definition and spec files in a single pass.
+- **Iterative crypto loop:** for larger crypto formalisations, a topic-based, restartable loop of four stages:
+
+  `/fvs:crypto-plan` → `/fvs:crypto-execute` → `/fvs:crypto-eval` → `/fvs:crypto-followup` → repeat
+
+  A high-effort thinker authors each bounded plan; the executor runs it under a green-build guard; an adversarial eval tries to refute the spec, proof, and assumptions and ends in exactly one of ACCEPT / FOLLOWUP / HUMAN_RULING / BLOCKED; follow-up turns findings into the next plan (halting for a human ruling on modeling decisions).
+
+  **Single- vs dual-runtime (`--codex`).** By default the loop is single-runtime — the thinking stages (`crypto-plan`, `crypto-eval`, `crypto-followup`) run the in-runtime `fvs-crypto-thinker`. Pass `--codex` to hand a stage's thinking to an independent **Codex CLI** thinker instead, so the adversarial planner/evaluator runs on a *different engine* than the executor and blind spots don't correlate. `crypto-execute` is the runtime-neutral executor and takes no `--codex`. Without the Codex CLI installed, a `--codex` stage stops with an install hint rather than silently falling back.
+
 ---
 
 ## Uninstalling

package/bin/install.js

@@ -16,13 +16,20 @@ const reset = '\x1b[0m';
 // Codex config.toml constants
 const FVS_CODEX_MARKER = '# FVS Agent Configuration \u2014 managed by fv-skills-baif installer';
 
-// Codex hooks feature flag. Current Codex CLI reads a boolean `hooks` flag in
-// config.toml to enable its hook dispatcher; an older naming used `codex_hooks`.
-// Emit the canonical key and treat the legacy alias as equivalent so a reinstall
-// over an older config migrates the flag forward instead of leaving a duplicate.
+// Codex hooks feature flag. Current Codex CLI reads feature flags under the
+// `[features]` table; a root-level `hooks = true` is parsed as the hooks config
+// object itself and is rejected. Emit `[features].hooks`, and treat the legacy
+// alias as equivalent so a reinstall over an older config migrates forward
+// instead of leaving a duplicate.
 const CODEX_HOOKS_FEATURE_KEY = 'hooks';
 const CODEX_HOOKS_FEATURE_LEGACY_KEYS = ['codex_hooks'];
 const CODEX_HOOKS_FEATURE_ALL_KEYS = [CODEX_HOOKS_FEATURE_KEY, ...CODEX_HOOKS_FEATURE_LEGACY_KEYS];
+const CODEX_FEATURES_TABLE = 'features';
+const FVS_CODEX_HOOKS_FEATURE_COMMENT = '# FVS-owned Codex hooks feature flag';
+
+function isCodexHooksFeatureKey(key) {
+  return CODEX_HOOKS_FEATURE_ALL_KEYS.includes(key);
+}
 
 // The only FVS hook script with a Codex event target is the update checker,
 // wired as a SessionStart hook. The statusline has no Codex renderer surface and
@@ -1083,6 +1090,123 @@ function removeContentRanges(content, ranges) {
   return cleaned;
 }
 
+function joinTomlLines(lines) {
+  return lines.map((line) => line.text + line.eol).join('');
+}
+
+function parseCodexHooksFeatureAssignment(lineText) {
+  const m = lineText.match(/^\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_]+))\s*=\s*(true|false)(\s*(?:#.*)?)?$/);
+  if (!m) return null;
+  const key = m[1] || m[2] || m[3];
+  if (!isCodexHooksFeatureKey(key)) return null;
+  return { key, value: m[4], suffix: m[5] || '' };
+}
+
+function parseRootDottedCodexHooksFeatureAssignment(lineText) {
+  const m = lineText.match(/^\s*features\.(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_]+))\s*=\s*(true|false)(\s*(?:#.*)?)?$/);
+  if (!m) return null;
+  const key = m[1] || m[2] || m[3];
+  if (!isCodexHooksFeatureKey(key)) return null;
+  return { key, value: m[4], suffix: m[5] || '' };
+}
+
+function renderCodexHooksFeatureAssignment(lineText) {
+  const indent = (lineText.match(/^\s*/) || [''])[0];
+  const parsed = parseCodexHooksFeatureAssignment(lineText);
+  return `${indent}${CODEX_HOOKS_FEATURE_KEY} = true${parsed ? parsed.suffix : ''}`;
+}
+
+function renderRootDottedCodexHooksFeatureAssignment(lineText) {
+  const indent = (lineText.match(/^\s*/) || [''])[0];
+  const parsed = parseRootDottedCodexHooksFeatureAssignment(lineText);
+  return `${indent}features.${CODEX_HOOKS_FEATURE_KEY} = true${parsed ? parsed.suffix : ''}`;
+}
+
+function removeRootCodexHooksFeatureFlags(content) {
+  const lines = splitTomlLines(content);
+  const firstHeaderIdx = lines.findIndex((line) => parseTomlTableHeader(line.text));
+  let changed = false;
+  const kept = lines.filter((line, index) => {
+    if (firstHeaderIdx !== -1 && index >= firstHeaderIdx) return true;
+    if (!parseCodexHooksFeatureAssignment(line.text)) return true;
+    changed = true;
+    return false;
+  });
+  return { content: changed ? joinTomlLines(kept) : content, changed };
+}
+
+function getCodexFeaturesSection(content) {
+  return getTomlTableSections(content)
+    .find((section) => !section.array && section.path === CODEX_FEATURES_TABLE);
+}
+
+function rewriteRootDottedCodexHooksFeature(content) {
+  const lines = splitTomlLines(content);
+  const firstHeaderIdx = lines.findIndex((line) => parseTomlTableHeader(line.text));
+  let found = false;
+  let changed = false;
+  const kept = [];
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (firstHeaderIdx !== -1 && i >= firstHeaderIdx) {
+      kept.push(line);
+      continue;
+    }
+
+    if (!parseRootDottedCodexHooksFeatureAssignment(line.text)) {
+      kept.push(line);
+      continue;
+    }
+
+    if (!found) {
+      found = true;
+      const rendered = renderRootDottedCodexHooksFeatureAssignment(line.text);
+      if (rendered !== line.text) changed = true;
+      kept.push({ ...line, text: rendered });
+    } else {
+      changed = true;
+    }
+  }
+
+  return { content: changed ? joinTomlLines(kept) : content, found, changed };
+}
+
+function stripFvsManagedCodexHooksFeature(content) {
+  // Self-heal v2.0.1 installs, which wrote the now-invalid root `hooks = true`.
+  let cleaned = removeRootCodexHooksFeatureFlags(content).content;
+  const featuresSection = getCodexFeaturesSection(cleaned);
+  if (!featuresSection) return cleaned;
+
+  const body = cleaned.slice(featuresSection.headerEnd, featuresSection.end);
+  const lines = splitTomlLines(body);
+  const kept = [];
+  let removed = false;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line.text.trim() === FVS_CODEX_HOOKS_FEATURE_COMMENT) {
+      removed = true;
+      const next = lines[i + 1];
+      if (next && parseCodexHooksFeatureAssignment(next.text)) {
+        i += 1;
+      }
+      continue;
+    }
+    kept.push(line);
+  }
+
+  if (!removed) return cleaned;
+
+  const nextBody = joinTomlLines(kept);
+  const hasRemainingContent = nextBody.split(/\r?\n/).some((line) => line.trim() !== '');
+  if (!hasRemainingContent) {
+    return cleaned.slice(0, featuresSection.start) + cleaned.slice(featuresSection.end);
+  }
+
+  return cleaned.slice(0, featuresSection.headerEnd) + nextBody + cleaned.slice(featuresSection.end);
+}
+
 /**
  * Strip FVS sections from Codex config.toml content.
  *
@@ -1129,21 +1253,11 @@ function stripFvsFromCodexConfig(content) {
     cleaned = before + after;
   }
 
-  // Remove the FVS-owned root-level hooks feature flag (canonical + legacy).
-  // The flag is inserted by ensureCodexHooksFeature between the FVS marker and
-  // the first FVS table, so once the marker and tables are gone it is left
-  // orphaned. Only strip it when the FVS marker was present — a flag in a
-  // config that FVS never marked is the user's and must be preserved.
+  // Remove the FVS-owned hooks feature gate. v2.0.1 emitted an invalid root
+  // `hooks = true`; current installs mark their `[features].hooks` insertion so
+  // uninstall can remove only the FVS-owned line and preserve user/GSD flags.
   if (hadFvsMarker) {
-    const flagLines = cleaned.split(/\r?\n/);
-    const firstHeaderIdx = flagLines.findIndex((l) => /^\s*\[/.test(l));
-    cleaned = flagLines
-      .filter((line, i) => {
-        if (firstHeaderIdx !== -1 && i >= firstHeaderIdx) return true;
-        const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=\s*true\s*$/);
-        return !(m && CODEX_HOOKS_FEATURE_ALL_KEYS.includes(m[1]));
-      })
-      .join('\n');
+    cleaned = stripFvsManagedCodexHooksFeature(cleaned);
   }
 
   // Collapse runs of blank lines the removals may have left behind, then
@@ -1165,9 +1279,9 @@ function stripFvsFromCodexConfig(content) {
  *
  * On reinstall this first strips any previously-emitted FVS tables via the
  * TOML-aware strip (so foreign user/GSD tables survive verbatim and stale FVS
- * tables are removed), then appends the freshly-generated FVS block. The
- * FVS-emitted block carries no `[features]`/`multi_agent` keys, so none are
- * injected into the user's config.
+ * tables are removed), then appends the freshly-generated FVS agent block. The
+ * hook feature gate is handled separately by ensureCodexHooksFeature so it can
+ * coexist with user/GSD `[features]` settings.
  */
 function mergeCodexConfig(configPath, fvsBlock) {
   // Case 1: No config.toml -- create fresh.
@@ -1539,62 +1653,103 @@ function removeCodexHooksJsonSessionStart(targetDir) {
   return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand: null });
 }
 
-// Ensure the Codex hooks feature flag is present and set true under the
-// canonical key. If the file already enables the flag under the legacy key,
-// rewrite that line to the canonical key (migrate forward) rather than adding a
-// duplicate. Returns { content, changed }.
+// Ensure the Codex hooks feature flag is present as `[features].hooks = true`.
+// Older FVS versions wrote root-level `hooks = true`, which current Codex parses
+// as the hooks config table and rejects; remove that stale shape while inserting
+// the valid feature flag.
 function ensureCodexHooksFeature(configContent) {
-  const content = typeof configContent === 'string' ? configContent : '';
+  const original = typeof configContent === 'string' ? configContent : '';
+  const rootStripped = removeRootCodexHooksFeatureFlags(original);
+  let content = rootStripped.content;
   const eol = content ? detectLineEnding(content) : '\n';
-  const lines = content.length ? content.split(/\r?\n/) : [];
 
-  let canonicalIdx = -1;
-  let legacyIdx = -1;
-  for (let i = 0; i < lines.length; i += 1) {
-    const m = lines[i].match(/^\s*([A-Za-z0-9_]+)\s*=\s*(.+?)\s*$/);
-    if (!m) continue;
-    const key = m[1];
-    if (key === CODEX_HOOKS_FEATURE_KEY && canonicalIdx === -1) canonicalIdx = i;
-    else if (CODEX_HOOKS_FEATURE_LEGACY_KEYS.includes(key) && legacyIdx === -1) legacyIdx = i;
-  }
-
-  // Only operate on root-level flag lines (not inside a [table]); a flag line
-  // appearing after the first [section] header is treated as section-scoped and
-  // left alone — FVS emits the flag at the document root before any table.
-  const firstHeaderIdx = lines.findIndex((l) => /^\s*\[/.test(l));
-  const isRootLevel = (idx) => idx !== -1 && (firstHeaderIdx === -1 || idx < firstHeaderIdx);
-
-  if (isRootLevel(canonicalIdx)) {
-    if (/=\s*true\s*$/.test(lines[canonicalIdx])) return { content, changed: false };
-    lines[canonicalIdx] = `${CODEX_HOOKS_FEATURE_KEY} = true`;
-    return { content: lines.join(eol), changed: true };
-  }
-  if (isRootLevel(legacyIdx)) {
-    lines[legacyIdx] = `${CODEX_HOOKS_FEATURE_KEY} = true`;
-    return { content: lines.join(eol), changed: true };
-  }
-
-  // Insert a fresh canonical flag line at the document root, above any table.
-  const insertLine = `${CODEX_HOOKS_FEATURE_KEY} = true`;
-  if (firstHeaderIdx === -1) {
-    const base = content.trimEnd();
-    const next = base ? `${insertLine}${eol}${base}${eol}` : `${insertLine}${eol}`;
+  const featuresSection = getCodexFeaturesSection(content);
+  if (featuresSection) {
+    const body = content.slice(featuresSection.headerEnd, featuresSection.end);
+    const lines = splitTomlLines(body);
+    let found = false;
+    let changed = rootStripped.changed;
+    const kept = [];
+
+    for (const line of lines) {
+      const parsed = parseCodexHooksFeatureAssignment(line.text);
+      if (!parsed) {
+        kept.push(line);
+        continue;
+      }
+
+      if (!found) {
+        found = true;
+        const rendered = renderCodexHooksFeatureAssignment(line.text);
+        if (rendered !== line.text) changed = true;
+        kept.push({ ...line, text: rendered });
+      } else {
+        changed = true;
+      }
+    }
+
+    if (found) {
+      const next = content.slice(0, featuresSection.headerEnd) +
+        joinTomlLines(kept) +
+        content.slice(featuresSection.end);
+      return { content: next, changed: changed || next !== original };
+    }
+
+    const needsLineBreak = featuresSection.end > 0 &&
+      !content.slice(0, featuresSection.end).endsWith('\n') &&
+      !content.slice(0, featuresSection.end).endsWith('\r\n');
+    const insertText = `${needsLineBreak ? eol : ''}${FVS_CODEX_HOOKS_FEATURE_COMMENT}${eol}${CODEX_HOOKS_FEATURE_KEY} = true${eol}`;
+    const next = content.slice(0, featuresSection.end) + insertText + content.slice(featuresSection.end);
+    return { content: next, changed: true };
+  }
+
+  const dotted = rewriteRootDottedCodexHooksFeature(content);
+  if (dotted.found) {
+    return { content: dotted.content, changed: rootStripped.changed || dotted.changed || dotted.content !== original };
+  }
+
+  const featuresBlock = [
+    `[${CODEX_FEATURES_TABLE}]`,
+    FVS_CODEX_HOOKS_FEATURE_COMMENT,
+    `${CODEX_HOOKS_FEATURE_KEY} = true`,
+    '',
+  ].join(eol);
+
+  if (!content) return { content: featuresBlock, changed: true };
+
+  const firstTable = getTomlTableSections(content)[0];
+  if (firstTable) {
+    const before = content.slice(0, firstTable.start);
+    const after = content.slice(firstTable.start);
+    const needsGap = before.length > 0 && !before.endsWith(eol + eol);
+    const next = before + (needsGap ? eol : '') + featuresBlock + eol + after;
     return { content: next, changed: true };
   }
-  lines.splice(firstHeaderIdx, 0, insertLine, '');
-  return { content: lines.join(eol), changed: true };
+
+  const base = content.trimEnd();
+  const needsGap = base.length > 0;
+  const next = `${base}${needsGap ? eol + eol : ''}${featuresBlock}`;
+  return { content: next, changed: true };
 }
 
 function hasEnabledCodexHooksFeature(configContent) {
   if (typeof configContent !== 'string') return false;
-  const firstHeaderIdx = configContent.split(/\r?\n/).findIndex((l) => /^\s*\[/.test(l));
-  const lines = configContent.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i += 1) {
-    if (firstHeaderIdx !== -1 && i >= firstHeaderIdx) break;
-    const m = lines[i].match(/^\s*([A-Za-z0-9_]+)\s*=\s*true\s*$/);
-    if (m && CODEX_HOOKS_FEATURE_ALL_KEYS.includes(m[1])) return true;
+  const featuresSection = getCodexFeaturesSection(configContent);
+  if (featuresSection) {
+    const body = configContent.slice(featuresSection.headerEnd, featuresSection.end);
+    for (const line of splitTomlLines(body)) {
+      const parsed = parseCodexHooksFeatureAssignment(line.text);
+      if (parsed && parsed.value === 'true') return true;
+    }
   }
-  return false;
+
+  const lines = splitTomlLines(configContent);
+  const firstHeaderIdx = lines.findIndex((line) => parseTomlTableHeader(line.text));
+  return lines.some((line, index) => {
+    if (firstHeaderIdx !== -1 && index >= firstHeaderIdx) return false;
+    const parsed = parseRootDottedCodexHooksFeatureAssignment(line.text);
+    return Boolean(parsed && parsed.value === 'true');
+  });
 }
 
 /**

package/commands/fvs/help.md

@@ -23,18 +23,25 @@ Commands are grouped into five bundles. Each bundle has a router command (e.g. `
 
 ## Quick Start
 
-1. `/fvs:map-code` - Analyze project, build dependency graph
-2. `/fvs:fc-plan` - Select verification targets
-3. `/fvs:lean-specify <function>` - Generate spec with sorry
-4. `/fvs:lean-verify <spec_path>` - Attempt proof interactively
-5. `/fvs:lean-refactor <spec_path>` - Golf and clean up verified proofs
-6. `/fvs:lean-formalise` - Formalise paper/math content into Lean specs
+**From a Rust crate — functional-correctness track:**
+1. `/fvs:aeneas-extract <path>` - Extract Rust → Lean 4 via the bounded Aeneas repair loop
+2. `/fvs:map-code` - Analyze project, build dependency graph
+3. `/fvs:fc-plan` - Select verification targets
+4. `/fvs:lean-specify <function>` - Generate spec with sorry
+5. `/fvs:lean-verify <spec_path>` - Attempt proof interactively
+6. `/fvs:lean-refactor <spec_path>` - Golf and clean up verified proofs
+7. `/fvs:trust-audit <target>` - Audit the sorry/axiom trust surface
+
+**From a paper — paper track:**
+- `/fvs:lean-formalise` - One-shot formalisation of paper/math content, or
+- `/fvs:crypto-plan <topic>` - Start the multi-iteration crypto loop (see Formalise below)
 
 ## Core Workflow
 
 ```
-/fvs:map-code → /fvs:fc-plan → /fvs:lean-specify → /fvs:lean-verify → /fvs:lean-refactor → repeat
-Paper track:    /fvs:lean-formalise → /fvs:lean-verify → /fvs:lean-refactor
+Code track:  /fvs:aeneas-extract → /fvs:map-code → /fvs:fc-plan → /fvs:lean-specify → /fvs:lean-verify → /fvs:lean-refactor → /fvs:trust-audit
+Paper track: /fvs:lean-formalise → /fvs:lean-verify → /fvs:lean-refactor
+Crypto loop: /fvs:crypto-plan → /fvs:crypto-execute → /fvs:crypto-eval → /fvs:crypto-followup → repeat
 ```
 
 ## Bundles
@@ -188,24 +195,28 @@ Refactor, simplify, and decompose verified Lean proofs while preserving compilat
 
 Usage: `/fvs:lean-refactor Specs/Backend/Field/Sub.lean`
 
-The crypto formalisation loop (plan -> execute -> eval -> follow-up) is a topic-based, multi-iteration alternative to the one-shot `lean-formalise`. Its four stages share the artifact tree under `fv-plans/<topic>/` and the loop is restartable from those records. The loop is runtime-neutral (it runs as a same-runtime pair by default).
+The crypto formalisation loop (plan -> execute -> eval -> follow-up) is a topic-based, multi-iteration alternative to the one-shot `lean-formalise`. Its four stages share the artifact tree under `fv-plans/<topic>/` and the loop is restartable from those records.
 
-**`/fvs:crypto-plan <topic>`**
+**Single- vs dual-runtime (`--codex`).** By default the loop is *single-runtime*: the high-effort thinking (planning, adversarial eval, follow-up) is done by the in-runtime `fvs-crypto-thinker`. The three *thinking* stages — `crypto-plan`, `crypto-eval`, `crypto-followup` — also accept `--codex`, which hands that stage's thinking to an independent **Codex CLI** thinker instead. That makes the loop *dual-runtime*: the adversarial planner/evaluator runs on a different engine than the executor, reducing correlated blind spots. `crypto-execute` is the runtime-neutral executor and takes no `--codex`. Pass `--codex` without the Codex CLI installed and the stage stops with an install hint (never a silent fallback) — re-run without it to stay single-runtime.
+
+**`/fvs:crypto-plan <topic> [nN] [--codex]`**
 Author the next bounded, runtime-neutral executor plan for a topic, grounded in the paper via the NotebookLM knowledge base (answers cached under `sources/`).
 
 Usage: `/fvs:crypto-plan "CKA from KEM"`
+Usage: `/fvs:crypto-plan "CKA from KEM" --codex`   # hand the planning think-step to Codex
 
 **`/fvs:crypto-execute <topic> nN`**
-Run the current iteration's bounded plan under the green-build guard; a failed proof triggers a short interactive redirect early.
+Run the current iteration's bounded plan under the green-build guard; a failed proof triggers a short interactive redirect early. (Executor stage — takes no `--codex`.)
 
 Usage: `/fvs:crypto-execute "CKA from KEM" n1`
 
-**`/fvs:crypto-eval <topic> nN`**
+**`/fvs:crypto-eval <topic> nN [--codex]`**
 Adversarially evaluate the iteration; ends in exactly one decision (ACCEPT / FOLLOWUP / HUMAN_RULING / BLOCKED).
 
 Usage: `/fvs:crypto-eval "CKA from KEM" n1`
+Usage: `/fvs:crypto-eval "CKA from KEM" n1 --codex`
 
-**`/fvs:crypto-followup <topic> nN`**
+**`/fvs:crypto-followup <topic> nN [--codex]`**
 Convert eval findings into the next bounded follow-up plan; HALTs for a human ruling on a modeling decision.
 
 Usage: `/fvs:crypto-followup "CKA from KEM" n1`

package/fv-skills/VERSION

@@ -1 +1 @@
-2.0.0
+2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fv-skills-baif",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Formal verification skills for Claude Code, Codex, OpenCode, and Gemini. Rust -> Lean 4 via Aeneas.",
   "bin": {
     "fv-skills-baif": "bin/install.js"