Skip to content

docs/wiki: refresh for currency + audience tracks (developers / maintainers / end users) #59

Description

@hyperpolymath

Audit (2026-06-21)

The local wiki/ has a sound skeleton (Home.md + compiler/ internals/ language/ reference/ stdlib/ tooling/ tutorials/, CC-BY-SA-4.0), but it is stale, link-broken, and not segmented by audience — it covers setup + basics but not the depth needed to really engage with the materials.

Findings

  1. Broken navigation. Home.md links many pages that don't exist: getting-started/* (Installation, Hello-World, IDE-Setup), contributing/* (Development-Setup, Code-Style, Testing), several tutorials/* (Basic-Calculator, Lists, Smart-Contracts, Reversible-Computing), reference/* (Standard-Library, CLI-Commands, Error-Messages), tooling/* (REPL, VS-Code). Actual content is much thinner (tutorials/Getting-Started.md, reference/Grammar.md, tooling/{CLI,LSP,Property-Testing}.md, etc.).
  2. Currency gap. No pages for the work landed this cycle: the Echo + Epistemic effect system (@echo/@epi, ADR-0009), reversibility tiering (ADR-0007), neg/dialect + purity certificate (ADR-0008), number-system stratification (ADR-0010), or the formal-proofs narrative (verification/PROOF-CAPABILITY-MATRIX.adoc: type_preservation, interpreter_correctness, the approxGroup witness).
  3. No audience tracks. Content implicitly splits users (tutorials/language) vs developers (internals/compiler), but there is no Maintainer track and the "Contributing" section Home links to doesn't exist.
  4. Depth. "Beyond setup/basic" is thin: stdlib is a single Overview; one real tutorial.

Proposed structure — three tracks

  • End Users: getting-started (real pages), language guide, tutorials (calculator / lists / reversible), CLI + REPL, number systems, error messages.
  • Developers: compiler architecture, AST, type checker, the Echo/Epistemic effect system, grammar/parser, WASM, contributing (setup / style / testing).
  • Maintainers: release process; CI + the hyperpolymath/standards reusables + the proof-regression gate; the contractiles + .machine_readable/6a2 (Mustfile/Intentfile/Trustfile/STATE); governance; PROOF-CAPABILITY-MATRIX as the authoritative proof status; an ADR index (0001–0010).

Tasks

  • Fix or delink every dead Home.md link.
  • Add a "Formal guarantees" page linking PROOF-CAPABILITY-MATRIX.adoc + the proof advances.
  • Add effect-system (Echo/Epistemic) + number-systems-stratification pages.
  • Introduce the three audience tracks on Home.md.
  • Add the Maintainer track (CI/standards/contractiles/ADR index).

Source of truth for proofs is verification/PROOF-CAPABILITY-MATRIX.adoc; the wiki should point to it, not restate it.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions