fv-skills-baif 2.3.6 → 2.3.7

package/CHANGELOG.md

@@ -6,6 +6,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+## [2.3.7] - 2026-10-15
+
+### Added
+
+- The GitHub repository has a self-contained `skills/fvs-setup` entry, so the skills CLI can
+  discover FVS. It explains the native installation for Pi, Claude Code, Codex, OpenCode and Gemini
+  and asks before running an installer. Copying it alone does not install the FVS workflows (#81).
+- A practical Lake builds reference covers targeted checks, import artifacts and caches without
+  changing your project's toolchain or dependency pins, and credits its source talk. The Lean
+  writing commands load it (#79).
+
+### Changed
+
+- The README is shorter and organised around installation for each runtime, the two workflows,
+  commands, and updates and removal (#70).
+- Codex thinking stages for `/fvs:crypto-plan`, `/fvs:crypto-eval` and `/fvs:crypto-followup`
+  receive the full crypto-thinker role and a complete context file, run read-only, and return their
+  response. The parent command checks the response and writes the stage files (#63).
+- Crypto stages record requested, resolved and observed model settings separately and report a real
+  settings mismatch instead of completing the stage. Choosing OpenCode or Gemini as a statement
+  reviewer now says that route is unavailable and offers Codex, Claude, a fresh Pi session or an
+  acknowledged other reviewer, rather than substituting one (#63).
+
+### Fixed
+
+- Every Lean-writing specialist (executor, crypto executor, external modeler and Lean refactorer)
+  is granted lean-lsp-mcp diagnostics and goal states, and the Gemini and OpenCode conversions keep
+  those grants. Effective access inside each host has not been verified yet (#74).
+- The README lists OpenCode's help command as `/fvs-help`, the name the installer creates.
+- `npm run check:plugin`, which `npm publish` runs, no longer fails on macOS, where the default
+  temporary directory is reached through a symlink.
+
 ## [2.3.6] - 2026-09-29
 
 ### Added

package/README.md

@@ -1,427 +1,195 @@
-<div align="center">
+# Formal Verification Skills
 
-# FORMAL VERIFICATION SKILLS
-
-**Formal verification in Lean 4 with AI-assisted specification and proof — for Rust code (via Aeneas) and for maths/crypto papers. Multi-runtime.**
+FVS helps AI coding assistants write Lean 4 specifications and proofs. The functional-correctness
+track verifies Rust translated by Aeneas. The paper track formalises mathematics and cryptography
+directly from papers. You choose the targets, review the statements and decide when proof work begins.
 
 [![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)
-
-<br>
-
-```bash
-npx fv-skills-baif
-```
-
-**Works on Mac, Windows, and Linux. Supports Pi, Claude Code, Codex, OpenCode, and Gemini CLI.**
-
-<br>
+[Pi package](https://pi.dev/packages/fv-skills-baif) · [MIT license](LICENSE)
 
 ![FVS Install](assets/terminal.svg)
 
-<br>
-
-</div>
-
----
-
-## What This Is
-
-FVS encodes the expert formal verification workflow into skills for AI coding assistants. It takes Rust code through a structured pipeline — dependency analysis, deep code understanding, specification generation, and proof — using the AI to handle the tedious parts while you stay in control of the verification strategy.
-
-**FVS targets Lean 4** across two tracks. The **functional-correctness track** verifies Rust code via Aeneas (Rust → Charon → LLBC → Aeneas → Lean 4). The **paper track** formalises mathematics and crypto papers directly into Lean — no Rust source or Aeneas extraction required.
+## Getting started
 
-Some capabilities are framework-agnostic and work regardless of your verification target:
-- **Dependency mapping** builds function call graphs from any extracted code
-- **Verification planning** picks optimal targets using greedy graph traversal
-- **Natural language explanation** produces human-readable summaries of Rust functions with pre/post conditions
+Run `npx fv-skills-baif` for an interactive installation, or select your runtime explicitly:
 
-Framework-specific commands (currently Lean) handle the actual specification and proof generation.
+| Runtime | User/global install | Help after restarting the session |
+|---|---|---|
+| Pi | `npx fv-skills-baif --pi --global` | `/skill:fvs-help` |
+| Claude Code | `npx fv-skills-baif --claude --global` | `/fvs:help` |
+| Codex | `npx fv-skills-baif --codex --global` | `$fvs-help` |
+| Gemini CLI | `npx fv-skills-baif --gemini --global` | `/fvs:help` |
+| OpenCode | `npx fv-skills-baif --opencode --global` | `/fvs-help` |
 
----
+Replace `--global` with `--local` to install for the current project. Non-Pi installs copy the
+commands and support files into the runtime's configuration directory. Use
+`npx fv-skills-baif --help` for custom directory options. Keep one FVS installation per runtime.
 
-## Getting Started
+### Pi
 
-### Pi package
-
-Use the unified installer for an updateable user install or an exact project pin:
-
-```bash
-npx fv-skills-baif --pi --global
-npx fv-skills-baif --pi --local --pi-version 2.3.4
-```
-
-Pi's default scope is user/global. The default `latest` source stays unpinned and follows Pi
-package updates. An exact `--pi-version X.Y.Z` source is pinned and is skipped by `pi update`. If
-FVS exists in the opposite scope, interactive installs offer keep, move, or cancel; scripts must pass
-`--pi-conflict keep|move`. When both remain, Pi's project/local package takes precedence over the
-user/global package.
-
-Direct Pi commands remain available:
+The installer delegates to Pi's native package manager. You can also use it directly:
 
 ```bash
 pi install npm:fv-skills-baif
-pi install npm:fv-skills-baif@2.3.4 --local
+pi install npm:fv-skills-baif --local
 pi update npm:fv-skills-baif
-pi remove npm:fv-skills-baif
-pi remove npm:fv-skills-baif --local
 ```
 
-To roll back, reinstall the required exact version, for example
-`npx fv-skills-baif --pi --global --pi-version 2.3.4`. To remove FVS through the unified installer,
-run `npx fv-skills-baif --pi --global --uninstall` or replace `--global` with `--local`.
+Project packages require project trust and take precedence over the user installation.
+The default `latest` source stays updateable. `--pi-version X.Y.Z` selects a chosen published version;
+X.Y.Z is a metavariable. Exact pins are skipped by `pi update`; rollback means reinstalling a chosen
+published pin. If FVS exists in the opposite scope, choose keep, move or cancel. Scripts must pass
+`--pi-conflict keep` or `--pi-conflict move`. Pi owns its settings paths, so `--config-dir` does not
+redirect them. See [Pi package documentation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md).
 
-Start a new session, then run `/skill:fvs-help`. Bundle routers such as `/skill:fvs-fc` and
-`/skill:fvs-formalise`, plus member skills such as `/skill:fvs-crypto-plan`, are available directly.
+### Claude Code and Codex marketplace
 
-### Plugin marketplace (Claude Code and Codex)
-
-The Beneficial AI Foundation maintains one catalog for FVS and future BAIF plugins. Add the catalog
-once, then install FVS from its `beneficial-ai-foundation` marketplace identity:
+Install from the [BAIF catalog](https://github.com/Beneficial-AI-Foundation/plugins):
 
 ```bash
-# Claude Code
 claude plugin marketplace add Beneficial-AI-Foundation/plugins
 claude plugin install fvs@beneficial-ai-foundation
-
-# Codex
 codex plugin marketplace add Beneficial-AI-Foundation/plugins
 codex plugin add fvs@beneficial-ai-foundation
 ```
 
-Start a new session after installation. Run `/fvs:help` in Claude Code or mention `$fvs:help` in
-Codex.
-
-On Codex, the marketplace plugin ships the FVS agent prompts as Markdown but does not register them
-as Codex agent roles. When a workflow asks for an FVS specialist that Codex has not registered, FVS
-warns you. If the step does not depend on that specialist's settings, FVS runs a generic Codex agent
-with the specialist's prompt and labels its output, but Codex then does not guarantee the
-specialist's identity, sandbox, model, or reasoning effort. If the step does depend on them, FVS
-stops before starting the agent or writing files. A role registered some other way still has its
-settings checked at run time.
+Claude's default is user scope; `--scope project` and `--scope local` select plugin scopes.
+Codex has its own plugin interface; do not reuse Claude's scope flags. After restarting, use
+`/fvs:help` in Claude or `$fvs:help` in Codex.
 
-#### Codex specialist roles
+The Codex marketplace ships specialist prompts as Markdown without registering Codex agent roles.
+FVS warns when a requested role is missing. A settings-independent step may use a labelled generic
+agent with the full specialist prompt; its identity, sandbox, model and reasoning effort are not
+guaranteed. A settings-dependent step stops before dispatch or file writes. Registered roles also
+need their settings checked.
 
-Use one FVS installation per runtime. The npm installer installs a complete, separately managed FVS
-for Codex: skills as `$fvs-<name>`, scripts, hooks, a `config.toml` block, and the `fvs-*` agent
-roles. To get registered roles today, switch installations rather than adding a second copy:
+The npm installer supplies a complete, separately managed Codex installation with roles, hooks and
+configuration. To switch channels, remove the plugin first:
 
 ```bash
 codex plugin remove fvs@beneficial-ai-foundation
 npx fv-skills-baif --codex --global
 ```
 
-Adding or updating the marketplace plugin, including with `$fvs:update`, never registers roles or
-runs the npm installer.
-
-To refresh an existing install, update the catalog and then update or reinstall FVS:
-
-```bash
-# Claude Code
-claude plugin marketplace update beneficial-ai-foundation
-claude plugin update fvs@beneficial-ai-foundation
-
-# Codex
-codex plugin marketplace upgrade beneficial-ai-foundation
-codex plugin add fvs@beneficial-ai-foundation
-```
-
-The BAIF Git catalog is a versioned distribution source that can list multiple independently
-released plugins. It is separate from OpenAI's universal public Plugins Directory, which has its
-own per-plugin submission process.
-
-### Unified npm installer
-
-```bash
-npx fv-skills-baif
-```
-
-The installer prompts you to choose:
-1. **Runtime** — Pi, Claude Code, Codex, OpenCode, Gemini, or all
-2. **Location** — Global (all projects) or local (current project only)
-3. **Pi version** — updateable latest or an exact pinned version
-
-Pi installation delegates to Pi's native package manager; it never copies files into Pi's managed
-cache. `--config-dir` continues to apply to supported non-Pi runtimes and is ignored for Pi.
-Verify with `/skill:fvs-help` in Pi or `/fvs:help` in the other runtimes.
-
-### Prerequisites (Lean 4 / Aeneas)
-
-- 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
-
-For enhanced Lean 4 proof development with LLMs, install the [lean-lsp-mcp](https://github.com/oOo0oOo/lean-lsp-mcp) server. It provides instant goal state checking, local lemma search, and proof diagnostics without rebuilding.
-
-**Note:** Avoid using the `lean_multi_attempt` tool for formal verification tasks - FV proof states often explode in size, making multi-attempt testing prohibitively slow.
-
-### Staying Updated
-
-For a marketplace install, invoke `/fvs:update` in Claude Code or `$fvs:update` in Codex. For an npm
-install, run:
-
-```bash
-npx fv-skills-baif@latest
-```
-
-<details>
-<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
-
-```bash
-# Claude Code
-npx fv-skills-baif --claude --global   # Install to ~/.claude/
-npx fv-skills-baif --claude --local    # Install to ./.claude/
-
-# Codex
-npx fv-skills-baif --codex --global    # Install to ~/.codex/
-
-# OpenCode
-npx fv-skills-baif --opencode --global # Install to ~/.config/opencode/
+Plugin updates, including `$fvs:update`, do not register roles or run the npm installer.
 
-# Gemini CLI
-npx fv-skills-baif --gemini --global   # Install to ~/.gemini/
+### Before your first Lean task
 
-# Pi (latest is updateable; an exact version is pinned)
-npx fv-skills-baif --pi --global
-npx fv-skills-baif --pi --local --pi-version 2.3.4
+Use a Lean project with `lakefile.lean` or `lakefile.toml` and its existing `lean-toolchain` pin.
+For Rust verification, supply Aeneas-generated `Types.lean` and `Funs.lean`, or start with
+`/fvs:aeneas-extract`. Papers need no Rust or Aeneas. NotebookLM integration via `/fvs:kb-setup` is optional.
 
-# All runtimes (noninteractive use fails before mutation if Pi is unavailable)
-npx fv-skills-baif --all --global
-```
+We recommend [lean-lsp-mcp](https://github.com/oOo0oOo/lean-lsp-mcp) for goal states and diagnostics.
+Configure it in your chosen runtime and check that the writing agent can access it; IDE diagnostics
+alone do not provide goal states. If live feedback is required but unavailable, the task stops.
+Compiler-only work needs your explicit acceptance of that fallback. Project build, style and trust
+checks still apply. [Practical Lake builds](fv-skills/references/lake-build.md) explains targeted
+checks, import artifacts and caches without changing your project's toolchain or dependency pins.
 
-Use `--global` (`-g`) or `--local` (`-l`) to skip the location prompt.
-Use `--pi`, `--claude`, `--codex`, `--opencode`, `--gemini`, or `--all` to skip the runtime prompt.
-For an opposite-scope Pi install, scripts must choose `--pi-conflict keep` or
-`--pi-conflict move`.
+FC dependency graphs use [probe-aeneas](https://github.com/Beneficial-AI-Foundation/probe-aeneas).
+`/fvs:map-code` and `/fvs:fc-plan` first check your project's probe/toolchain combination and print
+readable setup diagnostics, so you never need to read the compatibility data yourself. If the
+combination is not verified, they offer probe setup, continuing without a graph, or cancelling.
+Verified mapping writes the function inventory and progress to `.formalising/CODEMAP.md`.
+Unsupported platforms or unverified probe/toolchain combinations cannot produce a verified graph.
+SPQR compatibility is not supported. Tools are not installed automatically, and runtime installation
+alone does not establish tool access.
 
-</details>
+FVS asks for runtime, model and effort choices at each relevant stage. Requested settings,
+resolved settings and observed settings are recorded separately; unavailable observations are stated
+explicitly. Use `/fvs:configure` to save defaults. See [model profiles](fv-skills/references/model-profiles.md)
+for selection rules and runtime limitations.
 
----
+## Workflows
 
-## Commands
+### Functional correctness
 
-Commands are grouped into five bundles. Each bundle has a **router** command that lists its members and forwards to the matched skill (invoke it bare to print the routing table). All member commands are also directly typeable.
-
-### Aeneas — `/fvs:aeneas`
-
-| Command | Description |
-|---------|-------------|
-| `/fvs:aeneas-extract` | Drive a Rust crate/folder/file through the bounded Aeneas extraction repair loop (pin audit, classify, auto-apply/bisect/gate/escalate, reversible records) |
-| `/fvs:model-external` | Model one lockfile/sysroot-grounded external Rust stub and its bounded dependency closure, with reversible writes and separate model/spec reviews |
-| `/fvs:sync-aeneas-verif` | Sync Aeneas/Charon upstream docs and reconcile the extraction blocker catalog via two specialised agents |
-
-### Context — `/fvs:context`
-
-| Command | Description |
-|---------|-------------|
-| `/fvs:map-code` | Build function dependency graph from extracted code and Rust source |
-
-### Formal-Core — `/fvs:fc`
-
-| Command | Description |
-|---------|-------------|
-| `/fvs:fc-plan` | Pick next verification targets via greedy dependency graph traversal |
-| `/fvs:model-external` | Resolve, model, review, prove, build, and trust-audit one external Rust stub plus its bounded external-stub closure |
-| `/fvs:lean-specify` | Generate a style-checked Lean spec skeleton with `@[step]` theorem pattern |
-| `/fvs:lean-spec-review` | Adversarially review an FC specification with a chosen runtime, model, and effort |
-| `/fvs:lean-verify` | Attempt proof with domain tactics while blocking new target-style violations |
-| `/fvs:natural-language` | Generate natural language explanation of module or function with pre/post conditions |
-| `/fvs:lean-refactor` | Refactor, simplify, and decompose verified proofs (dead code removal, simp sharpening, tactic golf) — *also in Formalise* |
-| `/fvs:trust-audit` | Build-backed audit of every sorry/axiom affecting a target layer; `#print axioms` classification, fail-if-unjustified gate, dependency-ordered table |
-
-`lean-specify` and `lean-verify` load a target style guide from
-`.formalising/fvs-config.json` (`project.style_guide_path`) or discover standard files such as
-`doc/STYLE_GUIDE`. With no guide they enforce a 100-column fallback. Their post-write gate also
-rejects ordinary Lean identifiers with three or more namespace dots, steering generated code
-toward scoped namespaces, `open`, and local names.
-
-After `lean-specify`, an interactive review menu resolves reviewer, exact catalog model, and
-model-supported effort; it never auto-selects a choice. It offers the other runtime first, a fresh
-reviewer in the current runtime, or another provider. Other providers use an exported source packet
-and imported response. One-run `Skip review` records `Unreviewed (user skipped)` and does not begin
-proof work. Reviews and source hashes live under `.formalising/spec-reviews/`.
-
-The reviewer stays read-only and `review.md` stays immutable. The `lean-specify` authoring seat
-writes separate `triage.md`. PASS proceeds; APPROVE-WITH-EDITS also proceeds after accepted bounded
-edits pass the structure/style/build gates, with no redundant second review. Only REVISE/BLOCKED
-starts another fresh review, carrying prior records as untrusted history, with a three-round cap.
-
-Automatic review works even without a config file. To disable the automatic menu, merge this
-setting into `.formalising/fvs-config.json` (or create that file with just this object):
-
-```json
-{"spec_review": {"automatic": false}}
+```text
+/fvs:natural-language → /fvs:lean-specify → automatic fresh /fvs:lean-spec-review
+                                                   ↓ when you request proof work
+                                             /fvs:lean-verify → repeat
 ```
 
-`/fvs:lean-spec-review <spec.lean>` remains available when automation is disabled. No migration or
-health command is needed. Missing/authentication failures offer setup and an explicit fallback;
-reviewer changes are never silent. A PASS approves the statement for proof work, not the proof.
+Use `/fvs:map-code` to map dependencies and `/fvs:fc-plan` to choose targets in dependency order.
+The FC prover works interactively, one-sorry at a time, with reviewable Write diffs and compilation
+feedback. Finish with `/fvs:lean-refactor` and `/fvs:trust-audit`.
+`/fvs:model-external` handles external Rust stubs with separate model and specification reviews,
+reversible writes, proof completion and a trust audit.
 
-`lean-specify`, `lean-verify`, and `lean-formalise` share an indexed proof-engineering store at
-`.formalising/proof-engineering/`. Commands read `index.md` first, load at most eight relevant
-lessons as delimited untrusted reference data, and reconcile at most three evidence-backed
-candidates after the run. Every lesson has its own Markdown file under `fc/`, `crypto/`, or
-`shared/`, capped at 800 words, so the memory stays searchable and reviewable instead of growing
-into one long note.
-Legacy `.formalising/PROOF-NOTES.md` content is retained as migration input. The store never keeps
-secrets, raw transcripts, ephemeral error dumps, unsupported guesses, or inferred preferences.
+### Papers and crypto
 
 ```text
-.formalising/                # Per-project FVS state
-├── CODEMAP.md               # Function inventory and verification status
-├── proof-engineering/       # Indexed, durable proof/modeling knowledge
-│   ├── index.md             # Read first; links and metadata only
-│   └── lessons/
-│       ├── fc/              # Functional-correctness lessons
-│       ├── crypto/          # Crypto proof and modeling lessons
-│       └── shared/          # Lessons validated across tracks
-└── fv-plans/                # Formalisation plans and reviews
+/fvs:crypto-plan → automatic fresh /fvs:crypto-review → /fvs:crypto-execute
+       ↑                                               (when you request it)
+/fvs:crypto-followup ← /fvs:crypto-eval ←────────────────────┘
+       └──────────── automatic fresh review before execution
 ```
 
-### Formalise (Paper Track) — `/fvs:formalise`
-
-| Command | Description |
-|---------|-------------|
-| `/fvs:lean-formalise` | Formalise paper/math content into Lean 4 specs and definitions (one-shot) |
-| `/fvs:lean-refactor` | Refactor, simplify, and decompose verified proofs — *also in Formal-Core* |
-| `/fvs:crypto-plan` | Author the next bounded, runtime-neutral plan for a topic-based crypto formalisation iteration (KB-grounded, cached under `sources/`) |
-| `/fvs:crypto-review` | Review a crypto plan with selected Codex, Claude, or Other runtime/model/effort |
-| `/fvs:crypto-execute` | Run the current iteration's bounded plan under the green-build guard |
-| `/fvs:crypto-eval` | Adversarially evaluate the iteration; ends in one of ACCEPT / FOLLOWUP / HUMAN_RULING / BLOCKED |
-| `/fvs:crypto-followup` | Convert eval findings into the next follow-up plan; HALTs on HUMAN_RULING |
-
-### Manage — `/fvs:manage`
-
-| Command | Description |
-|---------|-------------|
-| `/fvs:help` | Show available FVS commands and usage guide |
-| `/fvs:configure` | Configure runtime-aware subagent models, effort levels, and review defaults |
-| `/fvs:update` | Update FVS through the current installation channel |
-| `/fvs:reapply-patches` | Preserve customizations across FVS updates (patches for npm installs; fork guidance for plugin installs) |
-| `/fvs:kb-setup` | Set up NotebookLM knowledge base integration (venv, auth, config) |
-
-`/fvs:configure` stores concrete model IDs under the runtime and exact stage that reported them.
-The quality profile is role-aware: authority artifacts use the strongest detected model with max
-reasoning, execution/proof filling uses the executor model with xhigh, and research/eval/audit work
-uses a smaller model with high. Claude and Codex family preferences never cross runtimes; Pi uses
-provider-qualified IDs and keeps its active provider for ordinary work. Each interactive command
-shows one model/effort selection manifest with one-run, save, notes, and cancel paths. Missing models
-or unsupported efforts require a user choice; unresolved noninteractive runs fail before dispatch.
-
----
-
-## How It Works
-
-### 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. If extraction leaves a required external stub, `/fvs:model-external <stub>` resolves its exact Cargo/vendor/rustc source, journals a reversible hand-written Lean candidate, runs separate model-fidelity and specification reviews, completes proofs, builds, and requires a CLEAN trust audit. Unsafe Rust stops; observable effects require `HUMAN_RULING`. Once required external models are complete, the verification workflow begins:
-
-### 1. Map
-
-`/fvs:map-code` — Run probe-aeneas >= 0.19.0 to build an exact, reproducible function inventory and dependency graph. Models annotate and prioritize the canonical list but never determine its membership or count. Produces `CODEMAP.md` with every in-scope Rust function, its dependencies, and verification status.
-
-### 2. Plan
-
-`/fvs:fc-plan` — Walk the dependency graph bottom-up to find optimal verification targets. Prioritizes leaf functions (no unverified dependencies) using greedy traversal. Performs deep Rust source analysis to reason about pre/post conditions and bounds.
-
-### 3. Specify
-
-`/fvs:lean-specify <function>` — Generate a specification skeleton for the target function. For Lean 4: uses the `@[step] theorem fn_spec` pattern with preconditions from Rust source analysis and postconditions matching function behavior.
-
-The command reads the bounded proof-engineering index and may reviewably add one-file-per-lesson
-functional-correctness insights for later sessions.
-
-### 4. Verify
+`/fvs:lean-formalise` creates definitions and specification skeletons in one pass. For larger work,
+the crypto loop uses a dedicated whole-unit executor. Evaluation returns ACCEPT, FOLLOWUP,
+HUMAN_RULING or BLOCKED; unresolved human rulings and blockers stop the loop.
+Thinking stages can explicitly use `--codex`; execution has no such flag. An unavailable requested
+runtime requires a new choice rather than a silent fallback.
+
+Both tracks use a fresh read-only reviewer and immutable review evidence. The author owns triage
+and accepted edits. Approval after edits requires the prescribed checks; revision rounds are bounded.
+Skipped, disabled, failed or pending review does not approve a statement or start proof/execution.
+You can opt out of automatic review and explicitly request trusted-path work while retaining its
+unreviewed status. See [review policy](fv-skills/references/review-policy.md),
+[FC statement review](fv-skills/references/fc-spec-review.md) and
+[crypto plan review](fv-skills/references/crypto-plan-review.md).
+
+The learning store lives in `.formalising/proof-engineering/`. Commands read `index.md` first,
+load at most eight relevant lessons from `lessons/` (`fc/`, `crypto/`, `shared/`) as untrusted data,
+and propose at most three evidence-backed updates. Fresh crypto review remains memory-blind.
+[Learning-store details](fv-skills/references/proof-engineering-loop.md).
 
-`/fvs:lean-verify <function>` — Attempt to prove the specification. For Lean 4: uses domain-specific tactics (`step`, `simp`, `ring`, `field_simp`, `omega`). Reports proof status and remaining goals if incomplete.
-
-The proof loop loads a bounded selection from `.formalising/proof-engineering/` before research and
-can reviewably retain green-build patterns or lessons evidenced by actual Lean diagnostics.
-
-### 5. Simplify
-
-`/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. It target-filters the same canonical probe-aeneas inventory, then uses `#print axioms` to classify every supplied function as verified / `sorry` / axiom / uninspectable. The classical trio (`propext`, `Classical.choice`, `Quot.sound`) is auto-noted as Lean/Mathlib-standard; any project-custom axiom, sorry, or uninspectable entry keeps the gate 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 with
-  a fresh pre-execution review gate:
-
-  `/fvs:crypto-plan` → `/fvs:crypto-review` → `/fvs:crypto-execute` → `/fvs:crypto-eval` → `/fvs:crypto-followup` → `/fvs:crypto-review` → repeat
-
-  A high-effort thinker authors each bounded plan. Before execution, a selected Codex, Claude, or
-  Other fresh reviewer attacks the plan or follow-up under read-only controls and returns an
-  evidence-backed APPROVE / APPROVE-WITH-EDITS / REJECT verdict. The executor runs an approved plan
-  under a green-build guard; the post-execution 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 modeling ruling) and is reviewed again
-  before execution.
+## Commands
 
-  The authoring, execution, eval, and follow-up stages use the lightweight proof-engineering overlay:
-  they load at most eight relevant `crypto`/`shared` lessons and propose at most three reviewed
-  updates. Modeling lessons require paper or standard citations and remain provisional until an
-  accepted adversarial eval or explicit human ruling. The `crypto-review` gate is deliberately
-  memory-blind. It labels cross-runtime, same-runtime fresh reviewer, and unverified provenance;
-  Other uses packet export/import. APPROVE-WITH-EDITS becomes terminal after the authoring seat
-  applies accepted edits and reruns gates, with no second review. REJECT starts a fresh reviewed
-  revision with prior history, capped at three reviewer rounds per invocation. Automatic plan and
-  follow-up handoff asks reviewer -> model -> effort and never auto-selects. One-run `Skip review`
-  records `Unreviewed (user skipped)` and never starts execution. To opt out persistently, merge
-  `"crypto_review": {"automatic": false}` into `.formalising/fvs-config.json`; standalone review
-  and explicit trusted-path execution remain available without fabricating approval.
+The table uses Claude command notation. Use the help entry for your channel to find its spelling
+and arguments. Bundle routers list their members when invoked without arguments.
+[Full command help](commands/fvs/help.md).
 
-  **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.
+| Bundle | Members |
+|---|---|
+| `/fvs:aeneas` | `/fvs:aeneas-extract`, `/fvs:model-external`, `/fvs:sync-aeneas-verif` |
+| `/fvs:context` | `/fvs:map-code` |
+| `/fvs:fc` | `/fvs:fc-plan`, `/fvs:natural-language`, `/fvs:lean-specify`, `/fvs:lean-spec-review`, `/fvs:lean-verify`, `/fvs:lean-refactor`, `/fvs:model-external`, `/fvs:trust-audit` |
+| `/fvs:formalise` | `/fvs:lean-formalise`, `/fvs:lean-refactor`, `/fvs:crypto-plan`, `/fvs:crypto-review`, `/fvs:crypto-execute`, `/fvs:crypto-eval`, `/fvs:crypto-followup` |
+| `/fvs:manage` | `/fvs:help`, `/fvs:configure`, `/fvs:update`, `/fvs:reapply-patches`, `/fvs:kb-setup` |
 
----
+## Updates and removal
 
-## Uninstalling
+Use your channel's FVS update command, or rerun the npm installer with `fv-skills-baif@latest` and
+the same runtime/scope flags. `/fvs:reapply-patches` helps retain local customizations.
+For marketplace updates:
 
 ```bash
-# Global
-npx fv-skills-baif --claude --global --uninstall
-npx fv-skills-baif --opencode --global --uninstall
-
-# Local (current project)
-npx fv-skills-baif --claude --local --uninstall
+claude plugin marketplace update beneficial-ai-foundation
+claude plugin update fvs@beneficial-ai-foundation
+codex plugin marketplace upgrade beneficial-ai-foundation
+codex plugin add fvs@beneficial-ai-foundation
 ```
 
-Removes all FVS commands, agents, hooks, and settings entries. Does not affect other installed tools.
-
----
-
-## Acknowledgements
-
-FVS builds on the work of several open-source projects:
-
-- **[Aeneas](https://github.com/AeneasVerif/aeneas)** -- FVS incorporates and adapts
-  documentation and proof skills from the Aeneas verification framework (Apache 2.0).
-  The upstream Aeneas documentation is stored in `fv-skills/upstream/aeneas/` and can
-  be synced with `/fvs:sync-aeneas-verif`.
-
-- **[GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done)** -- FVS follows
-  the GSD plugin architecture for Claude Code skill distribution (MIT).
-
-- **[lean-lsp-mcp](https://github.com/oOo0oOo/lean-lsp-mcp)** -- MCP server for Lean
-  LSP integration, referenced in proof workflows (MIT).
-
-Individual contributions:
+Remove an npm installation with the same runtime/scope and `--uninstall`, for example
+`npx fv-skills-baif --claude --local --uninstall`. For Pi, use `pi remove npm:fv-skills-baif`
+for the user installation or `pi remove npm:fv-skills-baif --local` for the project. Unified Pi removal
+also supports `npx fv-skills-baif --pi --global --uninstall` (or `--local`). Remove a marketplace
+installation with its host's `plugin remove fvs@beneficial-ai-foundation` command.
 
-- **[Jin Xing Lim](https://github.com/jinxinglim)** -- proposed gating a crypto formalisation
-  plan on an independent second-runtime adversarial review before execution, and wrote the
-  reviewer prompt that `/fvs:crypto-review` (v2.1.0) is modelled on.
+If you use the skills CLI, set both `DISABLE_TELEMETRY=1` and `DO_NOT_TRACK=1` before invoking it.
+Later setup consent cannot cover earlier analytics. The opt-out also disables the CLI's external
+audit lookup, so retain independent source and integrity checks. See the [skills CLI FAQ](https://www.skills.sh/docs/faq)
+and [privacy policy](https://vercel.com/legal/privacy-policy). The `fvs-setup` entry provides native
+installation guidance; copying it alone does not install the full FVS workflows.
 
----
+## Credits and license
 
-## License
+FVS adapts documentation and proof skills from [Aeneas](https://github.com/AeneasVerif/aeneas)
+(Apache 2.0; [retained upstream documentation](fv-skills/upstream/aeneas/)). Its distribution
+architecture follows [GSD Core](https://github.com/open-gsd/gsd-core). We also use
+[probe-aeneas](https://github.com/Beneficial-AI-Foundation/probe-aeneas) and recommend
+[lean-lsp-mcp](https://github.com/oOo0oOo/lean-lsp-mcp). The Lake reference credits its source talk.
+[Jin Xing Lim](https://github.com/jinxinglim) proposed independent crypto-plan review and its reviewer prompt.
 
-MIT License. See [LICENSE](LICENSE) for details.
+MIT. See [LICENSE](LICENSE).