Assess & stage migration of zkApp Developers section to o1Labs docs (docs.o1labs.org/o1js)

[dkijania]

Summary

We are progressively delegating o1js / zkApp content to the o1Labs docs site. This issue captures an assessment of the entire "zkApp Developers" section (docs/zkapps/**, 272 files) and a staged plan to migrate as much as possible while avoiding orphaned content and broken links.

Verdict: do not remove the whole section at once — delegate in stages. The clean, safe first step is retiring the auto-generated o1js API reference (217 of 272 files) with redirects; the hand-written guides and tutorials should stay until o1Labs reaches parity.

Important correction on the target

o1js.dev is not the delegation target — it currently serves a stock, unmodified Docusaurus template with no real content, and docs.o1js.org is unreachable. The actively-maintained o1js docs live at https://docs.o1labs.org/o1js (o1js 2.15.0, changelog dated 2026-03-16). All redirects/banners must point there. The existing in-repo MigrateBanner already does.

What's in the section

Group	Files	Notes
o1js-reference/** (auto-generated API ref)	217	Machine-generated mirror of the o1js API
o1js/** (primitive guides)	13	basic-concepts, recursion, circuit-writing-primer, gadgets, bitwise-operations, foreign-fields, merkle-tree, indexed-merkle-map, keccak, ecdsa, sha256
writing-a-zkapp/**	20	introduction-to-zkapps (11) + feature-overview (9)
tutorials/**	13	numbered series (hello-world … account-updates, message board, server-side)
advanced/, front-end-integration-guides/, top-level (faq, roadmap, standards, zkapp-development-frameworks)	~9
Total	272

Coverage: docs.o1labs.org vs. what we'd remove

Already covered on o1labs (safe to delegate):

• Core zkApp model: how zkApps work, smart contracts, permissions, events, actions & reducers, deployment, upgradability, local development
• o1js conceptual/primitives: constraint systems, witnesses, recursion, ZkProgram, merkle trees, hashing
• Full generated API reference — cleanest 1:1 overlap with our o1js-reference/**

Gaps still served ONLY by Mina docs (would be orphaned by a full removal):

• zkApp CLI (install, scaffolding, CLI-based deploy)
• The numbered tutorial series (o1labs Tutorials currently only has HMAC + frontend-integration)
• Feature guides: off-chain storage, custom tokens, time-locked accounts, indexed merkle map
• Primitive guides: foreign fields, ECDSA, bitwise operations
• Lightnet local testing
• zkApps for Ethereum developers

Inherently out of o1js scope — must stay on Mina docs:

• Mina-network specifics: faucet/devnet funding, GraphQL endpoints, account model, ecosystem/standards/roadmap pages, using-mina/how-to-use-zkapp

Signals delegation is already underway

• Commit 7d2ff91b (2025-09-23, Coby @ o1Labs) added a MigrateBanner ("🚀 o1js reference documentation is now available at the new o1Labs docs site") to 34 pages across o1js/** and writing-a-zkapp/**. Wording is scoped to reference docs; tutorials and front-end guides deliberately don't carry it.
• vercel.json already has redirect history (snarkyjs → o1js, feature-page moves). The redirect mechanism is in active use.

Risks of a full removal today

Risk	Severity	Detail
Orphaned content	High	CLI, tutorial series, foreign-fields/ECDSA/bitwise/offchain/custom-tokens/time-locked guides have no o1labs equivalent yet
Broken inbound deep links	Medium	External blogs/tutorials link to docs.minaprotocol.com/zkapps/...; mitigated only with redirects
Internal broken links	Low–Medium	Only ~17 incoming links from non-zkapps docs (mina-signer, glossary, archive-node, …) — easy to repoint
SEO / discoverability	Medium	Mina pages currently rank for foreign-fields/ECDSA/bitwise; o1labs has no equivalent pages to inherit traffic

Migration plan

Phase 1 — retire the generated API reference (now, low risk)

• Delete docs/zkapps/o1js-reference/** (217 files)
• Add vercel.json redirects /zkapps/o1js-reference/:path* → https://docs.o1labs.org/o1js/api-reference/...
• Remove the o1js Reference category from sidebars.js
• Repoint any internal links into o1js-reference/**
• Regenerate static/llms-full.txt / static/llms.txt (the check-llms-txt CI job fails otherwise)

Phase 2 — delegate guides page-by-page (gated on o1labs parity)

For each topic, only after confirming the live o1labs equivalent URL exists, replace with a stub + vercel.json redirect:

• o1js primitive guides that o1labs covers (recursion, merkle-tree, basic-concepts, hashing/keccak/sha256)
• Feature-overview pages o1labs covers (permissions, events, actions-and-reducer, upgradability, on-chain values)
• introduction-to-zkapps pages o1labs covers (how-zkapps-work, smart-contracts, deploy, local-development)
• Tutorial series — only once o1labs reproduces them

Keep on Mina docs (do not delegate)

• Mina-network-specific material: faucet/devnet, account model, GraphQL, using-mina/how-to-use-zkapp, roadmap/standards/ecosystem framing
• Guides o1labs has not hosted: zkApp CLI, Lightnet, zkApps-for-Ethereum-developers (until that changes)

Per-deletion checklist (repo convention)

• Add the vercel.json redirect in the same change as the deletion
• Repoint internal cross-links (~17 total from outside zkapps/)
• Regenerate the llms artifacts and commit
• Verify the live o1labs URL for every page before removing its counterpart

Bottom line

The direction is correct and already started, but "freely remove the whole section" is not safe today. Phase 1 (generated API reference) can ship immediately behind redirects; the rest should be delegated incrementally as o1labs reaches parity, each move paired with a redirect to docs.o1labs.org/o1js (never o1js.dev).

[dkijania]

Phase 1 is up as a draft PR: #1209 — retires the 217 auto-generated o1js-reference pages behind redirects to docs.o1labs.org/o1js/api-reference, repoints the 12 in-repo links, and passes a full docusaurus build with no broken links. Phases 2+ (guides/tutorials) remain gated on o1labs parity per the plan above.