docs: Mina ↔ o1js documentation overlap — findings index (from Mina_o1js_Excel_Report.xlsx)

[dkijania]

Source

Analysis of Mina_o1js_Excel_Report.xlsx — a page-by-page comparison of the overlap between MinaProtocol/docs2 and o1-labs/o1js-documentation-site, verified against o1js 2.15.0.

Every claim below was re-checked against this repo and against the live o1Labs site on 2026-09-06 before filing. This issue is the index; #1208 holds the migration plan.

What the workbook found

• 20 overlapping topics compared page by page
• 6 topics only on o1Labs, 9 only on Mina docs
• 1 outright technical error

State of the repo at time of analysis

Phase 1 of #1208 is complete (217 generated API-reference pages retired behind redirects). Phase 2 partly shipped in 7d2169bd — 11 guides deleted, all 11 with vercel.json redirects. vercel.json now holds 38 redirects. docs/zkapps/ is down to 43 pages.

That closes most of the workbook's DUPLICATE rows. What remains is below.

Issues opened from this report

#	Finding	Kind
#1224	Next.js front-end guide duplicated with o1Labs	duplicate
#1225	Angular front-end guide duplicated with o1Labs	duplicate
#1226	Two overlapping Mina custom-token pages	internal duplicate
#1227	Phase 2 delegated 6 pages to thinner o1Labs targets	regression
#1228	Circuit-writing primer — o1Labs is canonical	delegate
#1229	basic-concepts.mdx cross-links missing	cross-link
#1230	Off-chain storage names o1js 1.9.1	stale
#1231	Four Mina-only pages untouched since 2024	stale
#1232	Seven tutorials untouched since 2024	stale (umbrella)
#1233	o1Labs-only topics, zero mentions here	gap
#1234	25 of 43 zkApp pages carry no o1Labs link	gap
#1235	Broken links + canonical-host mismatch + no CI check	risk
#1236	o1Labs links back to Mina docs from one page	upstream

What live verification added beyond the workbook

1. Six of the eleven Phase 2 targets are still thinner than the pages we deleted. smart-contracts redirects a 2212-word / 20-code-block guide to a 278-word / 2-code-block page. Three targets have since reached or passed parity.
2. o1Labs declares a canonical host that does not resolve. Every page carries rel="canonical" pointing at documentation.o1labs.org, and its sitemap lists 1105 URLs all on that host — which fails DNS. docs.o1labs.org, where our 37 links and 20 redirects point, appears zero times in their sitemap.
3. Two links are broken now: indexed-merkle-map.mdx:73 (404) and glossary.mdx:310 (200, anchor deleted).
4. The workbook's o1Labs-only list was incomplete. The live sitemap also has zkapps/upgrade-mesa, zkapps/account-updates, writing-constraint-systems/zk-program, zkapps/zkprogram-proofs, and three basic-types pages. upgrade-mesa matters most — two Mesa upgrade guides on two sites during an active upgrade.
5. Two workbook URLs are wrong: getting-started/intro 404s, and the HMAC tutorial is tutorials/hmac/hmac-basics.
6. The misspelled frontent-integration-guides path is live; the correct spelling 404s.

Verification notes carried from the workbook

Three rows were checked against the o1js library source:

• Recursion — Experimental.ZkProgram is fully removed in 2.15.0, not deprecated. The stale note lived on o1js/recursion.mdx, deleted by Phase 2. I grepped the repo: no Experimental.ZkProgram mention remains. Resolved, no action.
• Foreign fields / ECDSA — createForeignCurve(Crypto.CurveParams.Secp256k1) and createEcdsa match the 2.15.0 type definitions exactly. No action.
• Off-chain state — API valid in 2.15.0; only the version wording is dated. Covered by its own issue.

Related: #1208

---

PRs opened (2026-09-06)

PR	Fixes	Status
#1238	#1235 (broken links)	CI green
#1239	#1230	CI green
#1240	#1233	CI green
#1241	#1228, #1229, #1234	CI green
#1242	#1235 (CI check)	CI green
#1243	#1226	CI green

Five of the six touch static/llms-full.txt; after the first merge the rest need the llms artifacts regenerated.

Still needing a decision, not a patch: #1227 (Phase 2 parity — upstream the content or restore the pages), #1224/#1225 (which side owns the front-end guides), #1231/#1232 (stale 2024 content), #1236 (upstream requests, incl. the canonical host).

Found while writing the PRs: o1js/custom-tokens.mdx was not merely duplicated — it taught this.token.mint/burn/send, Experimental.Callback and Experimental.createChildAccountUpdate, none of which exist in o1js. All four of its code blocks were broken. See #1243.