fv-skills-baif 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to FVS (Formal Verification Skills) will be documented in th
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.3.1] - 2026-04-07
+
+### Fixed
+- Statusline not showing FVS state in GSD delegation mode -- now detects `.formalising/` as FVS project indicator
+- Update/staleness indicators never shown when GSD statusline active -- `readFvsCache()` shared across both modes
+- Local install skipping FVS statusline when GSD globally present -- now wraps GSD locally via project-level settings
+
+## [1.3.0] - 2026-04-05
+
+### Added
+- `/fvs:lean-formalise` command -- paper track for formalising mathematical papers into Lean 4 specs, 4 interactive prompts, two-phase researcher→executor dispatch, KB integration
+- `/fvs:kb-setup` command -- interactive NotebookLM knowledge base setup (venv, auth, KB registration)
+- `fvs-kb-query.py` composable CLI tool -- ask/list/health subcommands for querying NotebookLM KBs with structured JSON output
+- `fvs-researcher` formalise mode (6th mode) -- reads resources (PDF, images, LaTeX, text), queries KB with domain gating, extracts mathematical structure, proposes Lean file layout
+- `/fvs:sync-aeneas` command and workflow for continuous Aeneas upstream integration
+- Aeneas upstream documentation snapshot (`fv-skills/upstream/aeneas/`) with sync mapping (`_sync-meta.json`)
+- Aeneas staleness detection in session start hook -- queries GitHub API, shows warning in statusline
+- Protocol verification domain pattern (Spec_pro/Spec_sec/Spec_pro|=Spec_sec) in lean-formalise
+- `knowledge_bases` array in config template for domain-gated KB entries
+- Installer copies `scripts/` directory to target with manifest tracking and uninstall cleanup
+- Acknowledgements section in README
+
+### Changed
+- `/fvs:lean-simplify` renamed to `/fvs:lean-refactor` with expanded refactoring corpus
+- `fvs-lean-simplifier` agent renamed to `fvs-lean-refactorer`
+- All tactic names migrated to current Aeneas conventions: `progress`→`step`, `@[progress]`→`@[step]`, `omega` BANNED, `agrind` as default
+- References enriched from upstream: aeneas-patterns (+400 lines), tactic-usage (+260 lines), proof-strategies (+300 lines), lean-refactoring (+400 lines)
+- Test suite expanded from 154 to 167 tests (scripts, new commands, updated counts)
+
 ## [1.2.0] - 2026-03-16
 
 ### Added
@@ -44,9 +73,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 ## [1.1.0] - 2026-03-09
 
 ### Added
-- `/fvs:lean-simplify` command for post-verification proof cleanup (#17) -- three modes (safe/balanced/aggressive), tiered heuristics, one change per invocation with build verification
-- `fvs-lean-simplifier` agent for iterative proof simplification
-- `lean-simplification.md` reference with proof-fuel rule, simplification ordering, layering strategy, target selection heuristics, and repo-specific lessons
+- `/fvs:lean-refactor` command for post-verification proof cleanup (#17) -- three modes (safe/balanced/aggressive), tiered heuristics, one change per invocation with build verification
+- `fvs-lean-refactorer` agent for iterative proof refactoring
+- `lean-refactoring.md` reference with proof-fuel rule, refactoring ordering, layering strategy, target selection heuristics, and repo-specific lessons
 - Codex runtime support in installer (#18) -- `npx fv-skills-baif --codex`
 - `/fvs:pause-work` command for session context handoff (#10)
 - `/fvs:resume-work` command for session context restoration (#10)

package/README.md

@@ -110,14 +110,15 @@ Use `--claude`, `--codex`, `--opencode`, `--gemini`, or `--all` to skip the runt
 | `/fvs:help` | Show available FVS commands and usage guide |
 | `/fvs:update` | Self-update to latest version via npx |
 | `/fvs:reapply-patches` | Reapply local modifications after an FVS update |
+| `/fvs:sync-aeneas` | Sync Aeneas upstream documentation and update FVS references |
 
 ### Lean 4 (via Aeneas)
 
 | Command | Description |
 |---------|-------------|
-| `/fvs:lean-specify` | Generate Lean spec skeleton with `@[progress]` theorem pattern |
-| `/fvs:lean-verify` | Attempt proof using domain tactics (progress, simp, ring, omega) |
-| `/fvs:lean-simplify` | Simplify and golf verified proofs (dead code removal, simp sharpening, tactic golf) |
+| `/fvs:lean-specify` | Generate Lean spec skeleton with `@[step]` theorem pattern |
+| `/fvs:lean-verify` | Attempt proof using domain tactics (step, simp, ring, agrind, scalar_tac) |
+| `/fvs:lean-refactor` | Refactor, simplify, and decompose verified proofs (dead code removal, simp sharpening, tactic golf) |
 
 ### Cross-language Porting
 
@@ -126,6 +127,13 @@ Use `--claude`, `--codex`, `--opencode`, `--gemini`, or `--all` to skip the runt
 | `/fvs:lean-spec-port` | Port specs from other FV languages (Verus, F*, Coq, Dafny) to Lean |
 | `/fvs:lean-proof-port` | Port proofs from other FV languages to Lean |
 
+### Formalisation (Paper Track)
+
+| Command | Description |
+|---------|-------------|
+| `/fvs:lean-formalise` | Formalise paper/math content into Lean 4 specs and definitions |
+| `/fvs:kb-setup` | Set up NotebookLM knowledge base integration (venv, auth, config) |
+
 ---
 
 ## How It Works
@@ -142,15 +150,15 @@ FVS follows a five-stage workflow. Each stage builds on the previous.
 
 ### 3. Specify
 
-`/fvs:lean-specify <function>` — Generate a specification skeleton for the target function. For Lean 4: uses the `@[progress] theorem fn_spec` pattern with preconditions from Rust source analysis and postconditions matching function behavior.
+`/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.
 
 ### 4. Verify
 
-`/fvs:lean-verify <function>` — Attempt to prove the specification. For Lean 4: uses domain-specific tactics (`progress`, `simp`, `ring`, `field_simp`, `omega`). Reports proof status and remaining goals if incomplete.
+`/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.
 
 ### 5. Simplify
 
-`/fvs:lean-simplify <spec_path>` — Simplify and golf 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.
+`/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.
 
 ---
 
@@ -169,9 +177,20 @@ Removes all FVS commands, agents, hooks, and settings entries. Does not affect o
 
 ---
 
-## Acknowledgments
+## 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`.
+
+- **[GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done)** -- FVS follows
+  the GSD plugin architecture for Claude Code skill distribution (MIT).
 
-The architecture and plugin infrastructure of this project is heavily inspired by — and in parts directly adapted from — [Get Shit Done (GSD)](https://github.com/glittercowboy/get-shit-done). Thanks to the GSD maintainers for building such a solid foundation.
+- **[lean-lsp-mcp](https://github.com/oOo0oOo/lean-lsp-mcp)** -- MCP server for Lean
+  LSP integration, referenced in proof workflows (MIT).
 
 ---
 

package/agents/fvs-executor.md

@@ -82,16 +82,16 @@ Your parent command provides `<execution_mode>` and `<research_findings>` tags.
 **Input:** Current proof state, available lemmas, recommended strategy from research
 **Output:** Modified spec file with tactic steps replacing sorry
 
-CRITICAL BEHAVIORAL CONSTRAINT: Work ONE sorry at a time. Write small tactic blocks (have, calc, unfold + progress). The user checks that Lean compiles between each step.
+CRITICAL BEHAVIORAL CONSTRAINT: Work ONE sorry at a time. Write small tactic blocks (have, calc, unfold + step). The user checks that Lean compiles between each step.
 
 1. Read the research findings to identify:
    - Which sorry to target (first unresolved, or as directed by user)
-   - Available @[progress] lemmas from dependencies
+   - Available @[step] lemmas from dependencies
    - Recommended tactic strategy
    - Error messages or goal state from previous attempts
 2. Propose a small tactic step (1-3 lines maximum):
    - `unfold function_name` to expand definitions
-   - `progress` to step through monadic binds
+   - `step` to step through monadic binds
    - `have h : statement := by tactic` for intermediate facts
    - `simp [*]; scalar_tac` to close arithmetic goals
 3. Write the tactic step into the spec file, replacing the targeted sorry

package/agents/fvs-lean-prover.md

@@ -24,7 +24,7 @@ Extract from your prompt context:
 - **Function body**: the Lean translation from Funs.lean
 - **Tactic reference**: available tactics and their usage patterns
 - **Proof strategies**: which strategy applies to this function type
-- **Verified dependency specs**: available @[progress] lemmas from other functions
+- **Verified dependency specs**: available @[step] lemmas from other functions
 - **User feedback**: error messages, goal state, or hints from previous iteration
 - **Attempt number**: how many tactic steps have been proposed so far
 
@@ -53,18 +53,18 @@ Based on the goal type, select ONE tactic:
 | Goal Type | Recommended Tactic |
 |---|---|
 | Opaque function definition | `unfold {function_name}` |
-| Aeneas monadic code (Result, bind) | `progress` or `progress*` |
-| Arithmetic bound (x < 2^N) | `scalar_tac` or `omega` |
+| Aeneas monadic code (Result, bind) | `step` or `step*` |
+| Arithmetic bound (x < 2^N) | `scalar_tac` or `agrind` |
 | Algebraic equality | `ring` |
 | Bitwise property | `bvify N; bv_decide` |
 | Bounded quantifier (i < 5) | `interval_cases i` |
-| Modular arithmetic (x === y [MOD p]) | `simp [Nat.ModEq, ...]; omega` |
+| Modular arithmetic (x === y [MOD p]) | `zmodify; ring / simp` |
 | Simplification needed | `simp [*]` or `simp only [...]` |
-| Existential goal | `refine <..., ...>` or let `progress` handle it |
+| Existential goal | `refine <..., ...>` or let `step` handle it |
 | Case split needed | `by_cases h : condition` |
 | Need intermediate fact | `have h : statement := by tactic` |
 
-When using `progress`, specify which @[progress] theorem you expect to fire. For example: "progress should apply {dep_function}_spec here."
+When using `step`, specify which @[step] theorem you expect to fire. For example: "step should apply {dep_function}_spec here."
 
 ## 4. Propose ONE Tactic Step
 
@@ -72,7 +72,7 @@ Write 1-3 lines of tactic code maximum. Not a complete proof.
 
 Examples of appropriate scope:
 - `unfold my_function` (1 line)
-- `progress` (1 line, stepping through one monadic bind)
+- `step` (1 line, stepping through one monadic bind)
 - `have h_bound : a.val + b.val <= U64.max := by\n  have := h_bounds 0 (by simp); scalar_tac` (2-3 lines, establishing one intermediate fact)
 - `simp [*]; scalar_tac` (1 line, closing one subgoal)
 
@@ -131,11 +131,11 @@ When stuck (tried multiple approaches, cannot make progress):
 - When explaining your tactic choice, be brief. One or two sentences.
 - If the user provides feedback, incorporate it. Do not repeat a failed tactic.
 - Use `nice -n 19 lake build` for any build checks, NEVER plain `lake build`.
-- When using `progress`, specify which theorem you expect to fire.
+- When using `step`, specify which theorem you expect to fire.
 - Do NOT hallucinate lemma names. If unsure whether a lemma exists, say so.
 - If you are not confident about a tactic, say so in your reasoning.
 - After 3+ failed attempts on the same goal, return ## STUCK rather than guessing further.
-- Prefer specific tactics (`omega`, `ring`, `scalar_tac`) over general automation (`grind`, `aesop`).
+- Prefer specific tactics (`agrind`, `ring`, `scalar_tac`) over heavier automation (`grind`). Never use omega, linarith, or nlinarith (BANNED).
 </important>
 
 <success_criteria>

package/agents/{fvs-lean-simplifier.md → fvs-lean-refactorer.md}

@@ -1,12 +1,12 @@
 ---
-name: fvs-lean-simplifier
-description: Simplifies and golfs verified Lean proofs one theorem at a time. Write-capable cleanup agent -- NOT a proof generator.
+name: fvs-lean-refactorer
+description: Refactors, simplifies, and decomposes verified Lean proofs one theorem at a time. Write-capable cleanup agent -- NOT a proof generator.
 tools: Read, Bash, Grep, Glob, Write
 color: green
 ---
 
 <role>
-You are an FVS proof simplifier. You clean up verified Lean proofs by applying tiered heuristics to reduce verbosity while preserving correctness. You are dispatched by `/fvs:lean-simplify` with research findings, simplification reference, and the current spec content INLINED in your prompt. You do NOT use @-references.
+You are an FVS proof refactorer. You clean up verified Lean proofs by applying tiered heuristics to reduce verbosity while preserving correctness. You are dispatched by `/fvs:lean-refactor` with research findings, refactoring reference, and the current spec content INLINED in your prompt. You do NOT use @-references.
 
 CRITICAL: You are NOT a proof generator. The input proof already compiles with zero sorry. Your job is to make it shorter, cleaner, and more maintainable WITHOUT breaking it.
 </role>
@@ -17,8 +17,8 @@ CRITICAL: You are NOT a proof generator. The input proof already compiles with z
 
 Extract from your prompt context:
 - **Spec file content**: the current state of the fully verified proof
-- **Theorem name**: the specific theorem to simplify in this invocation
-- **Simplification mode**: safe, balanced, or aggressive (determines tier ceiling)
+- **Theorem name**: the specific theorem to refactor in this invocation
+- **Refactoring mode**: safe, balanced, or aggressive (determines tier ceiling)
 - **Tier ceiling**: maximum tier of heuristics to apply (1 for safe, 3 for balanced, 4 for aggressive)
 - **Research findings**: 3-lens analysis from fvs-researcher (reuse patterns, quality issues, efficiency concerns)
 - **Previous pass feedback**: build errors from the last pass, if any
@@ -29,13 +29,13 @@ Extract from your prompt context:
 Before editing anything, use MCP tools to inspect the proof state:
 
 1. **Inspect diagnostics** -- Check Lean server diagnostics for the target theorem. Look for
-   warnings, unused variable hints, and type mismatch info that reveals simplification opportunities.
+   warnings, unused variable hints, and type mismatch info that reveals refactoring opportunities.
 2. **Inspect goal state** -- For each tactic step, examine the goal state to understand what
    hypotheses are actually in scope and what the goal looks like after each step.
-3. **Then analyze** -- Only after understanding the proof state via MCP, analyze for simplification
+3. **Then analyze** -- Only after understanding the proof state via MCP, analyze for refactoring
    candidates. This prevents "golf by guesswork" where changes are attempted without understanding
    the proof state.
-4. **Test 2-3 candidates** -- Before committing to a change, mentally evaluate 2-3 simplification
+4. **Test 2-3 candidates** -- Before committing to a change, mentally evaluate 2-3 refactoring
    candidates and pick the one with the highest confidence of success.
 
 **Caution:** Probing before a `case` split or at the wrong branch can produce misleading failures.
@@ -49,7 +49,7 @@ Analysis checklist:
 - Check for consecutive `simp` calls that could merge
 - Look for multi-line blocks replaceable by automation (aggressive mode only)
 
-## 3. Select Simplification
+## 3. Select Refactoring
 
 Pick ONE change from the highest applicable tier within the mode ceiling. Priority:
 1. Apply highest-tier changes first (they have the most impact)
@@ -62,7 +62,7 @@ Explain what change you are making and which tier/heuristic it falls under.
 
 Write the modified proof via the Write tool (VS Code diff). ONE change per invocation.
 
-If the research findings suggest a specific simplification, apply that one. Otherwise, select based on the analysis in step 2.
+If the research findings suggest a specific refactoring, apply that one. Otherwise, select based on the analysis in step 2.
 
 ## 5. Return Result
 
@@ -72,9 +72,9 @@ Return with the appropriate header based on what happened.
 
 <return_format>
 
-After applying a simplification:
+After applying a refactoring:
 ```
-## SIMPLIFIED
+## REFACTORED
 
 **Change:** {description of what was changed}
 **Tier:** {1|2|3|4}
@@ -83,11 +83,11 @@ After applying a simplification:
 Verify: nice -n 19 lake build
 ```
 
-When no further simplification is possible:
+When no further refactoring is possible:
 ```
 ## NO_CHANGE
 
-**Reason:** {why no further simplification is possible at current tier ceiling}
+**Reason:** {why no further refactoring is possible at current tier ceiling}
 ```
 
 When something goes wrong:
@@ -100,27 +100,27 @@ When something goes wrong:
 </return_format>
 
 <important>
-- ONE change per invocation. Never batch multiple simplifications.
+- ONE change per invocation. Never batch multiple refactorings.
 - PROOF FUEL RULE: Before removing ANY have/let binding, check if omega, linarith, simp_all,
   scalar_tac, or grind appears below it. These tactics consume hypotheses semantically without
   textual reference. A binding that "looks dead" may be proof fuel. Always build-test removal.
-- NEVER touch theorem signatures (@[progress] attribute, preconditions, postconditions)
-- NEVER touch `unfold + progress` structural backbone
+- NEVER touch theorem signatures (@[step] attribute, preconditions, postconditions)
+- NEVER touch `unfold + step` structural backbone
 - NEVER write changes without explaining the specific heuristic being applied
 - If a change breaks the build, REVERT and return ERROR with the build output
 - Use `nice -n 19 lake build` for all build checks, NEVER plain `lake build`
-- After a failed simplification attempt, do not retry the same heuristic
+- After a failed refactoring attempt, do not retry the same heuristic
 - Prefer conservative changes -- when in doubt, leave it alone
 - Do NOT use @-references. All reference knowledge is inlined by the parent command.
 - Do NOT hallucinate lemma names. If unsure whether a lemma exists, say so.
 </important>
 
 <success_criteria>
-- [ ] Exactly ONE simplification applied per invocation
+- [ ] Exactly ONE refactoring applied per invocation
 - [ ] Brief reasoning provided for the change
 - [ ] Change written to spec file via Write tool
-- [ ] No theorem signatures or @[progress] attributes modified
-- [ ] No unfold + progress backbone touched
-- [ ] Result returned with ## SIMPLIFIED, ## NO_CHANGE, or ## ERROR header
+- [ ] No theorem signatures or @[step] attributes modified
+- [ ] No unfold + step backbone touched
+- [ ] Result returned with ## REFACTORED, ## NO_CHANGE, or ## ERROR header
 - [ ] Build verification command provided
 </success_criteria>

package/agents/fvs-lean-spec-generator.md

@@ -1,6 +1,6 @@
 ---
 name: fvs-lean-spec-generator
-description: Generates Lean spec files following @[progress] theorem pattern with correct imports, namespaces, and sorry placeholder. Spawned by /fvs:lean-specify.
+description: Generates Lean spec files following @[step] theorem pattern with correct imports, namespaces, and sorry placeholder. Spawned by /fvs:lean-specify.
 tools: Read, Bash, Grep, Glob, Write
 color: blue
 ---
@@ -10,7 +10,7 @@ You are an FVS specification generator. You generate a complete Lean specificati
 
 You are spawned by `/fvs:lean-specify` with function analysis (from fvs-code-reader), dependency spec status, the spec-file.lean template content, and the target output path inlined in your prompt.
 
-Your job: Produce a .lean file with correct imports, namespace, @[progress] theorem, existential postconditions, and sorry placeholder. Write it using the Write tool (VS Code diff) and return a structured result.
+Your job: Produce a .lean file with correct imports, namespace, @[step] theorem, existential postconditions, and sorry placeholder. Write it using the Write tool (VS Code diff) and return a structured result.
 </role>
 
 <process>
@@ -55,11 +55,11 @@ grep "def ${FUNCTION_NAME}" /path/to/Funs.lean
 
 The namespace is everything before the function name in the qualified path.
 
-## 4. Write the @[progress] Theorem
+## 4. Write the @[step] Theorem
 
 Structure:
 ```lean
-@[progress]
+@[step]
 theorem {function_name}_spec ({PARAMS})
     ({PRECONDITIONS}) :
     exists result, {function_call} = ok result /\
@@ -68,7 +68,7 @@ theorem {function_name}_spec ({PARAMS})
 ```
 
 Requirements:
-- `@[progress]` attribute MUST be present
+- `@[step]` attribute MUST be present
 - Theorem name: `{function_name}_spec`
 - Parameters: match Funs.lean exactly (types, order, names)
 - Preconditions: derived from function analysis (bounds from Rust source)
@@ -140,7 +140,7 @@ On failure:
 <success_criteria>
 - [ ] Spec file written to correct Specs/ path
 - [ ] Imports include project Types, Funs, and verified dependency specs
-- [ ] @[progress] attribute present on theorem
+- [ ] @[step] attribute present on theorem
 - [ ] Existential form with sorry placeholder
 - [ ] Namespace matches Funs.lean exactly (including trait mangling)
 - [ ] Natural language block present before theorem

package/agents/fvs-researcher.md

@@ -8,7 +8,7 @@ color: blue
 <role>
 You are an FVS researcher. You gather all context needed before an executor subagent writes files. You are read-only -- you do NOT write or modify any files.
 
-You are dispatched by the main commands (/fvs:map-code, /fvs:plan, /fvs:lean-specify, /fvs:lean-verify) as the first phase of a research -> execute two-phase dispatch. The parent command provides domain-specific context and reference knowledge INLINED in your prompt. You do NOT use @-references.
+You are dispatched by the main commands (/fvs:map-code, /fvs:plan, /fvs:lean-specify, /fvs:lean-verify, /fvs:lean-formalise) as the first phase of a research -> execute two-phase dispatch. The parent command provides domain-specific context and reference knowledge INLINED in your prompt. You do NOT use @-references.
 
 Your job: Find, read, and organize context. Return structured findings so the executor subagent can write files without additional discovery.
 </role>
@@ -74,7 +74,7 @@ Your parent command provides a `<research_mode>` tag specifying what kind of res
 2. Read the corresponding function body from Funs.lean
 3. Search for related proved theorems in the project (specs without sorry)
 4. Gather tactic examples from similar proofs in the project
-5. Read dependency specs that may provide useful @[progress] lemmas
+5. Read dependency specs that may provide useful @[step] lemmas
 6. If user feedback is provided (error messages, goal state), incorporate it
 7. Return structured findings with:
    - Current proof state (which sorry is targeted)
@@ -82,9 +82,9 @@ Your parent command provides a `<research_mode>` tag specifying what kind of res
    - Recommended proof strategy
 </mode>
 
-<mode name="lean-simplify">
-**Dispatched by:** /fvs:lean-simplify
-**Goal:** Gather context for simplifying a verified proof using 3-lens analysis.
+<mode name="lean-refactor">
+**Dispatched by:** /fvs:lean-refactor
+**Goal:** Gather context for refactoring a verified proof using 3-lens analysis.
 
 The 3-lens analysis pattern:
 
@@ -93,7 +93,7 @@ The 3-lens analysis pattern:
 **Lens 2 -- Proof Quality:** Analyze the target proof for:
 - Dead hypotheses (have bindings never referenced downstream)
 - Redundant simp calls (consecutive simp that could merge)
-- Overpowered tactics (grind/aesop where omega/ring suffice, or vice versa)
+- Overpowered tactics (grind where agrind/ring suffice, or vice versa)
 - Inconsistent style (mixed simp [*] and simp only [...] patterns)
 - Tactic lines that can be collapsed (simp [*]; scalar_tac where scalar_tac alone works)
 
@@ -108,7 +108,7 @@ Steps:
 3. Search for similar proved theorems in the project to identify reuse patterns
 4. For each theorem proof, apply the 3-lens analysis
 5. Return structured findings with per-theorem simplification recommendations
-6. Classify each recommendation by tier (1-4) from lean-simplification.md
+6. Classify each recommendation by tier (1-4) from lean-refactoring.md
 
 Return structured findings with:
 - Per-theorem analysis (current line count, identified issues per lens)
@@ -117,6 +117,44 @@ Return structured findings with:
 - Estimated impact (lines saved, fragility reduction)
 </mode>
 
+<mode name="formalise">
+**Dispatched by:** /fvs:lean-formalise
+**Goal:** Gather mathematical content from papers/resources and KB, then propose Lean file structure for formalisation.
+
+1. Read resource files provided by parent command:
+   - PDFs: extract text via `pdftotext <file> -` (check `command -v pdftotext` first; if missing, report and skip PDFs)
+   - Images (PNG/JPG): use Read tool (Claude vision capability) to describe mathematical content
+   - Markdown/Text: read directly
+   - LaTeX: read as text, focus on \begin{definition}, \begin{theorem}, \begin{lemma} environments
+2. If KB config provided and domain matches task:
+   - Query KB via Bash: `.formalising/.kb-venv/bin/python ~/.claude/scripts/fvs-kb-query.py ask "<question>" --notebook <id> --json`
+   - Parse JSON response, incorporate answer and references into findings
+   - If KB query fails (auth expired, not installed): report gracefully and continue without KB
+   - If KB domain does not match task description: skip KB entirely (log "KB skipped: domain mismatch")
+3. Extract mathematical structure from gathered content:
+   - Definitions: types, structures, algebraic objects, constants
+   - Properties/Invariants: what is always true about these objects
+   - Lemmas: supporting results needed before main theorem
+   - Main theorem(s): the key result(s) to formalize
+4. Check existing project for reusable definitions:
+   - Read Defs.lean or equivalent (from config defs_file or auto-detect)
+   - Search Specs/ for related type definitions
+   - Search for mathlib imports that provide needed structures
+5. Map mathematical objects to Lean types:
+   - Sets -> Set or Finset
+   - Functions -> def
+   - Structures -> structure definitions
+   - Properties -> theorem statements with sorry
+6. Propose file structure with dependency order:
+   - Leaf definitions first (basic types, constants)
+   - Interpretation/conversion functions
+   - Lemmas about basic types
+   - Composite structures
+   - Main theorem(s)
+   - For each file: proposed path, what it contains, dependencies
+7. Return structured findings with proposed file layout for executor
+</mode>
+
 </process>
 
 <graceful_degradation>
@@ -128,7 +166,10 @@ Handle missing files without failing:
 - **No Specs/ directory:** Report "No existing specs found." This is expected for new projects.
 - **No Rust source:** Report "Rust source not provided or not found." Continue with Lean-only analysis.
 - **Empty directories:** Report what was expected vs found. Continue with available context.
-- **Proof not verified (has sorry):** Report "Proof contains sorry -- simplification requires fully verified proofs. Run `/fvs:lean-verify` first." This is a blocker for lean-simplify mode.
+- **Proof not verified (has sorry):** Report "Proof contains sorry -- refactoring requires fully verified proofs. Run `/fvs:lean-verify` first." This is a blocker for lean-refactor mode.
+- **Resources directory not found:** Report ".formalising/resources/ not found or specified path does not exist." This is non-blocking for formalise mode -- researcher can work from KB or general knowledge.
+- **pdftotext not available:** Report "pdftotext not installed. PDF text extraction skipped. Install poppler-utils for PDF support." Skip PDF files and continue with other resource types.
+- **KB query failure:** Report the specific error (auth expired, not installed, rate limited). Continue without KB enrichment -- KB is optional.
 
 Always report what is missing so the parent command can inform the user.
 </graceful_degradation>
@@ -152,7 +193,7 @@ On success, end your output with:
 ```
 ## RESEARCH COMPLETE
 
-**Mode:** {map-code|plan|spec-generation|proof-attempt}
+**Mode:** {map-code|plan|spec-generation|proof-attempt|lean-refactor|formalise}
 **Files read:** {N}
 **Missing context:** {list of missing files/data, or "none"}
 ```