docs: migrate recursion docs to OpenVM

[stephenh-axiom-xyz]

Resolves INT-6799.

[github-actions]

Claude finished @stephenh-axiom-xyz's task in 2m 15s —— View job

---

Code Review: docs: migrate recursion docs to OpenVM

• Read and analyze all 17 new documentation files
• Check for correctness, consistency, and quality
• Verify references to code paths and crate names are accurate
• Post review feedback

---

Overall this is excellent, comprehensive documentation of the recursion circuit. The 39-AIR inventory, bus connectivity maps, group-by-group walkthroughs, and verifier-mapping correctness arguments are thorough and well-organized. A few issues to address:

Issues to Fix

1. Stale repository reference in README.md (line 292)

The recursion circuit source code is at `openvm/crates/recursion/src/` within the v2-proof-system repository.
The stark-backend verifier it constrains is at `stark-backend/crates/stark-backend/src/verifier/`.

This refers to v2-proof-system repository which appears to be an internal/old repo name. Since this documentation now lives in the openvm repo, this should be updated. Suggestion:

The recursion circuit source code is at `crates/recursion/src/`.
The stark-backend verifier it constrains is in the [stark-backend](https://github.com/openvm-org/stark-backend) repository at `crates/stark-backend/src/verifier/`.

Fix this →

2. Source path prefix openvm/ throughout group docs

All group documentation files reference source paths with an openvm/ prefix, e.g.:

• openvm/crates/recursion/src/transcript/transcript/air.rs (group-01, line 34)
• openvm/crates/recursion/src/batch_constraint/fractions_folder/air.rs (group-05, line 61)
• etc.

Since these docs now live within the openvm repo, the correct relative path from the repo root would be crates/recursion/src/... (without the openvm/ prefix). This pattern appears in all group docs and bus-inventory.md (~20+ occurrences).

Fix this →

3. Stale stark-backend path in verifier-mapping.md (line 7)

The stark-backend verifier (`stark-backend/crates/stark-backend/src/verifier/mod.rs`)

This path assumes a local checkout of stark-backend as a sibling directory. Since stark-backend is a separate repository, consider clarifying this is an external reference or linking to the GitHub source.

Minor Observations (Non-blocking)

4. Terminology: "6 modules" vs "13 groups"
The README and AIR_MAP use both "6 modules" (ProofShape, GKR, BatchConstraint, Stacking, WHIR, Transcript) and "13 groups" (the bus-connectivity partitioning). Both are correct views, and the README does explain both, but a brief clarifying sentence like "The 6 modules reflect the protocol pipeline; the 13 groups reflect bus-level coupling and match the per-group documentation below" would help readers who encounter both concepts.

5. Group docs missing source paths
Groups 7-13 (eq-univariate through whir-folding) don't include **Source:** annotations for each AIR, unlike groups 1-6. This is a minor consistency gap -- not blocking, but worth noting for future improvement.

6. Documentation quality
The Mermaid diagrams, per-AIR walkthrough tables, bus inventories, and correctness arguments in verifier-mapping.md are all very well done. The cross-group bus connection table in AIR_MAP.md is particularly useful for understanding inter-module dependencies.

Summary

The main actionable item is fixing the source code path references (items 1-3) to reflect that these docs now live in the openvm repository rather than the v2-proof-system monorepo. The documentation content itself is thorough and accurate.

[jonathanpwang]

Update docs/crates/README.md with a link to the sub-readme

[github-actions]

Claude finished @stephenh-axiom-xyz's task in 1m 4s —— View job

---

Code Review: docs: migrate recursion docs to OpenVM

• Read and analyze all changed documentation files
• Check for stale references and path issues
• Verify fixes from previous review were applied
• Post review feedback

---

This is a re-review after the 93f23e9 commit which added the link to docs/crates/README.md (addressing the reviewer's approval comment). The documentation content itself remains excellent.

However, the three path-related issues from the previous review are still unresolved:

Issues Still Open

1. Stale v2-proof-system repository reference (docs/crates/recursion/README.md:292)

The recursion circuit source code is at `openvm/crates/recursion/src/` within the v2-proof-system repository.

Should be updated to reflect that this now lives in the openvm repo:

The recursion circuit source code is at `crates/recursion/src/`.
The stark-backend verifier it constrains is in the [stark-backend](https://github.com/openvm-org/stark-backend) repository at `crates/stark-backend/src/verifier/`.

Fix this →

2. openvm/ prefix in source paths (21 occurrences across 8 files)

All group docs and bus-inventory.md reference paths with an openvm/ prefix (e.g., openvm/crates/recursion/src/transcript/...). Since these docs live inside the openvm repo, the correct relative path from repo root is crates/recursion/src/....

Affected files:

File	Occurrences
group-05-batch-constraint-sumcheck.md	4
group-04-gkr.md	4
group-01-transcript.md	3
group-02-proof-shape.md	3
group-06-batch-constraint-expr-eval.md	3
group-03-primitives.md	2
bus-inventory.md	1
README.md	1

Fix this →

3. stark-backend/ path in verifier-mapping.md (line 7)

The stark-backend verifier (`stark-backend/crates/stark-backend/src/verifier/mod.rs`)

Since stark-backend is a separate repository, this should link to the GitHub source rather than implying a local sibling checkout.

Fix this →

Summary

The second commit (93f23e9) correctly adds the link to docs/crates/README.md per the reviewer's request. The three source-path issues flagged in the first review still need to be addressed before merging. These are straightforward find-and-replace fixes.

[jonathanpwang]

@claude make a PR to fix all issues mentioned in #2553 (comment)
the PR should target branch develop-v2.0.0-beta

Make sure all links and paths, including backlinks, are up to date

[claude]

Claude finished @jonathanpwang's task in 1m 52s —— View job • claude/pr-2553-20260313-2232 • [Create PR ➔](https://github.com/openvm-org/openvm/compare/main...claude/pr-2553-20260313-2232?quick_pull=1&title=PR%20%232553%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20pr%20%232553%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Fixing stale path references in recursion docs

• Read affected files and identify all occurrences
• Fix stale v2-proof-system repository reference in README.md
• Replace openvm/crates/recursion/src/ prefix with crates/recursion/src/ across all files (21 occurrences in 8 files)
• Fix stark-backend/ path in verifier-mapping.md with GitHub link
• Verify no remaining stale references
• Commit and push changes
• Create PR targeting develop-v2.0.0-beta

All three issues from the review comment have been fixed:

1. README.md: Removed v2-proof-system reference, updated paths to be repo-relative
2. 8 files: Replaced openvm/crates/recursion/src/ → crates/recursion/src/ (21 occurrences)
3. verifier-mapping.md: Updated stark-backend path to link to the GitHub repository

PR: #2554