Docs: developer / maintainer / end-user learning paths (beyond setup + basic run)

[hyperpolymath]

Gap

The current docs let a reader set up and run Oblíbený, but there is no educational path that lets someone arriving here engage fully with the materials. Specifically:

• The wiki is integration-focused (Home, Ecosystem-Integration, Cerro-Torre, Selur, Svalinn, Vordr pages) — it documents ecosystem wiring, not the language.
• No audience-divided learning path. README.adoc / EXPLAINME.adoc / docs/TUTORIAL.md cover orientation + a basic run; docs/LANGUAGE-SPEC.md is reference, not pedagogy; docs/academic/ is research-level.
• The proof story is undocumented for humans: the Idris2 ABI layer (src/abi/Packages/Hello/*) and the new constrained-form metatheory (src/abi/Lang/*, see Language-soundness metatheory (src/abi/Lang/*): follow-ons toward verified extraction #78) have no reader-facing explanation of what is proven and why it matters.

Proposed structure (three audiences)

End users — use the language

• The dual form (Turing-complete factory → Turing-incomplete constrained form) and why.
• Writing & running .obl; the reversible/accountable constrained form; the echo[A,B] residue by example.
• Reading the accountability trace (--dump-trace); obli-pkg usage and the triple-signature trust model.

Developers — extend the language

• Architecture walkthrough: lexer → parse → typecheck → eval → constrained_check → static_analyzer.
• The proof layer: the Idris2 ABI (installReversible/echoResidueNonTrivial) and the Lang.* metatheory — what each guarantee means, how to extend a slice, the model-fidelity caveat.
• The Zig crypto FFI; adding a language feature end-to-end.

Maintainers — run the project

• CI gates (Mustfile/justfile, ci.yml), the contractiles + 6a2 governance model, the proof-debt.md discipline, the standards reusable workflows, the release transition.

Acceptance

Audience-divided pages (wiki and/or docs/), cross-linked from README.adoc; the ABI + Lang.* proof story explained for a newcomer; each page goes beyond setup into genuine engagement with the materials.