chore(tidy): T-5 — refresh wiki README + add honesty banners to overstated pages

## wiki/README.md rewrite

The wiki landing page had multiple structural problems:
- Linked to ~20 non-existent .md files (installation, hello-world,
  expressions, errors, package-manager, lsp, formatter, linter,
  primitives, collections, effects (stdlib), io, concurrency, fuzzing,
  benchmarks, design/*). Every one was a broken-link click.
- Referenced `../ROADMAP.md` at root, which now lives at
  `../docs/ROADMAP.adoc` after T-3 (#365).
- Pointed at `../docs/spec.md` as "Complete language specification",
  but that file carries an "OUT OF DATE" banner pointing elsewhere.
- Aspirational code examples (e.g. `Vec[n + 1, T]` dependent-type
  reasoning) implied enforcement that does not exist today —
  CAPABILITY-MATRIX says dependent types are `parse-only`.

Rewrite drops every dead link, points at the **authoritative**
in-repo matrices (`docs/CAPABILITY-MATRIX.adoc`,
`docs/TECH-DEBT.adoc`, `docs/ECOSYSTEM.adoc`) for live status,
annotates each "Features at a Glance" example with its current
maturity (`enforced` / `partial` / `parse-only`), and updates the
Quick Links table to the post-tidy-3 docs/ paths.

The Ownership example also moved from `&File` / `&mut File` sigil
syntax to the canonical `ref File` / `mut File` keyword syntax that
the parser actually accepts at the type level (the `&T` sigil is
deliberately not added — see CAPABILITY-MATRIX CORE-01 row).

## Honesty banners

Two pages had pure-aspirational content that overstated current
enforcement:

- `wiki/language-reference/dependent-types.md` — gets a `parse-only`
  banner: surface parses, but the typechecker does not reduce
  predicates and there is no SMT/decision procedure. Predicates and
  refinements are not enforced. Cross-link to CAPABILITY-MATRIX
  "Dependent / refinement types" + TECH-DEBT CORE-05.

- `wiki/language-reference/traits.md` — gets a `partial` banner:
  registry / TopTrait / TopImpl / find_impl / impl-satisfies-trait
  are wired; associated-type substitution, where-clause supertraits,
  and coherence checking are not. Cross-link to CAPABILITY-MATRIX
  "Traits" + TECH-DEBT CORE-04.

These banners DO NOT delete content — the wiki pages still describe
the *designed* surface, useful for reading the language reference.
They just stop claiming the language enforces what it currently
parses-and-shrugs.

## What this PR does NOT do

- Doesn't add the ~20 missing wiki pages (installation, hello-world,
  effects-stdlib, io, concurrency, design/*, etc.). That's content
  authoring at a different scope; the README rewrite stops linking
  to them, which makes the wiki navigable as-is.
- Doesn't sync to the upstream GitHub wiki repo. wiki/ is tracked in
  this repo but the GitHub-wiki surface is a separate git repo; the
  owner pushes wiki/ contents upstream separately. The commit message
  on this PR is the cue.
- Doesn't refresh wiki/{compiler,language-reference,tooling,
  stdlib,testing,tutorials}/*.md content beyond the two honesty
  banners. Comprehensive content refresh of those ~30 pages is a
  much larger effort and out of scope for this tidy phase.

## Test plan

- [ ] Pure-markdown PR; expected to inherit `main`'s baseline CI
      state. No `.ml` / `.mli` touched.
- [ ] Hypatia: no new findings.

Author: claude

wiki/README.md

@@ -1,123 +1,120 @@
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+<!-- SPDX-FileCopyrightText: 2024-2026 hyperpolymath -->
+
 # AffineScript Wiki
 
-Welcome to the AffineScript language wiki - your comprehensive guide to learning and using AffineScript.
+A guide to learning and using AffineScript — a language with affine types,
+algebraic effects, and a typed-WebAssembly compilation target.
+
+> **⚠️ Authoritative status lives in the repo, not this wiki.**
+> Where this wiki's prose implies broader maturity than the in-repo matrices
+> state, *the matrices win* — see
+> [`docs/CAPABILITY-MATRIX.adoc`](../docs/CAPABILITY-MATRIX.adoc) for live
+> per-feature readiness and [`docs/TECH-DEBT.adoc`](../docs/TECH-DEBT.adoc)
+> for the coordination ledger. AffineScript is **alpha** today, with the
+> CORE-01 borrow-checker work in progress (see issue #177).
 
 ## Quick Navigation
 
 ### Getting Started
-- [Introduction](tutorials/introduction.md) - What is AffineScript?
-- [Installation](tutorials/installation.md) - Setting up your environment
-- [Hello World](tutorials/hello-world.md) - Your first program
-- [Quick Start Guide](tutorials/quickstart.md) - Get productive fast
+
+- [Introduction](tutorials/introduction.md) — What is AffineScript?
+- [Quick Start](tutorials/quickstart.md) — Get productive with the CLI
+
+> 📌 For setup instructions, the canonical source is the root
+> [`README.adoc`](../README.adoc) §"Getting Started" and the
+> [`CONTRIBUTING.md`](../CONTRIBUTING.md) §"Quick Start".
 
 ### Language Reference
-- [Lexical Structure](language-reference/lexical.md) - Tokens, literals, comments
-- [Types](language-reference/types.md) - Type system overview
-- [Expressions](language-reference/expressions.md) - Expression syntax and semantics
-- [Patterns](language-reference/patterns.md) - Pattern matching
-- [Functions](language-reference/functions.md) - Function definitions
-- [Ownership](language-reference/ownership.md) - Affine types and borrowing
-- [Effects](language-reference/effects.md) - Algebraic effect system
-- [Traits](language-reference/traits.md) - Type classes
-- [Modules](language-reference/modules.md) - Module system
-- [Dependent Types](language-reference/dependent-types.md) - Indexed and refined types
-- [Row Polymorphism](language-reference/rows.md) - Extensible records
+
+These pages cover the language surface as designed. **For each feature,
+cross-reference the [Capability Matrix](../docs/CAPABILITY-MATRIX.adoc) to
+see whether it is `enforced`, `works`, `partial`, `declared-but-unwired`,
+or `parse-only` today.**
+
+- [Lexical Structure](language-reference/lexical.md) — Tokens, literals, comments
+- [Types](language-reference/types.md) — Type system overview
+- [Patterns](language-reference/patterns.md) — Pattern matching
+- [Functions](language-reference/functions.md) — Function definitions
+- [Ownership](language-reference/ownership.md) — Affine types and borrowing
+- [Effects](language-reference/effects.md) — Algebraic effect system
+- [Traits](language-reference/traits.md) — Type classes *(currently `partial`)*
+- [Modules](language-reference/modules.md) — Module system
+- [Dependent Types](language-reference/dependent-types.md) — Indexed and refined types *(currently `parse-only`)*
+- [Row Polymorphism](language-reference/rows.md) — Extensible records
 
 ### Compiler
-- [Architecture Overview](compiler/architecture.md) - Compiler pipeline
-- [Lexer](compiler/lexer.md) - Lexical analysis
-- [Parser](compiler/parser.md) - Syntactic analysis
-- [Type Checker](compiler/type-checker.md) - Type inference and checking
-- [Borrow Checker](compiler/borrow-checker.md) - Ownership verification
-- [Code Generation](compiler/codegen.md) - WASM backend
-- [Error Messages](compiler/errors.md) - Diagnostic system
+
+- [Architecture Overview](compiler/architecture.md) — Compiler pipeline
+- [Lexer](compiler/lexer.md) — Lexical analysis
+- [Parser](compiler/parser.md) — Syntactic analysis
+- [Type Checker](compiler/type-checker.md) — Type inference and checking
+- [Borrow Checker](compiler/borrow-checker.md) — Ownership verification
+- [Code Generation](compiler/codegen.md) — WASM backend
 
 ### Tooling
-- [CLI Reference](tooling/cli.md) - Command-line interface
-- [REPL Guide](tooling/repl.md) - Interactive environment
-- [Package Manager](tooling/package-manager.md) - aspm reference
-- [LSP Server](tooling/lsp.md) - Editor integration
-- [Formatter](tooling/formatter.md) - Code formatting
-- [Linter](tooling/linter.md) - Code analysis
+
+- [CLI Reference](tooling/cli.md) — Command-line interface
+- [REPL Guide](tooling/repl.md) — Interactive environment
 
 ### Standard Library
-- [Overview](stdlib/overview.md) - Library organization
-- [Primitives](stdlib/primitives.md) - Basic types
-- [Collections](stdlib/collections.md) - Data structures
-- [Effects](stdlib/effects.md) - Standard effects
-- [I/O](stdlib/io.md) - Input/output
-- [Concurrency](stdlib/concurrency.md) - Threading and async
+
+- [Overview](stdlib/overview.md) — Library organisation
+
+> The standard library is **AOT-coherent** (per
+> [`docs/CAPABILITY-MATRIX.adoc`](../docs/CAPABILITY-MATRIX.adoc) STDLIB-AOT).
+> `stdlib/json.affine` and `stdlib/dict.affine` are live; the
+> Http/Promise/IO surface is documented under STDLIB-01..05 in
+> [`docs/TECH-DEBT.adoc`](../docs/TECH-DEBT.adoc).
 
 ### Testing
-- [Testing Guide](testing/guide.md) - Writing tests
-- [Property-Based Testing](testing/property-based.md) - QuickCheck-style testing
-- [Fuzzing](testing/fuzzing.md) - Fuzz testing
-- [Benchmarking](testing/benchmarks.md) - Performance testing
 
-### Design Documents
-- [Language Design](design/language.md) - Design philosophy
-- [Type System](design/type-system.md) - Type theory background
-- [Effect System](design/effects.md) - Effect theory
-- [Memory Model](design/memory.md) - Memory management
+- [Testing Guide](testing/guide.md) — Writing tests
+- [Property-Based Testing](testing/property-based.md) — QuickCheck-style testing
+
+> Canonical testing standards: [`docs/standards/TESTING.adoc`](../docs/standards/TESTING.adoc).
 
 ## Quick Links
 
 | Resource | Description |
 |----------|-------------|
-| [Full Specification](../docs/spec.md) | Complete language specification |
-| [Roadmap](../ROADMAP.md) | Development roadmap |
-| [Examples](../examples/) | Example programs |
-| [Contributing](../CONTRIBUTING.md) | How to contribute |
+| [`README.adoc`](../README.adoc) | Project overview + Getting Started |
+| [`docs/CAPABILITY-MATRIX.adoc`](../docs/CAPABILITY-MATRIX.adoc) | **Authoritative** per-feature readiness |
+| [`docs/TECH-DEBT.adoc`](../docs/TECH-DEBT.adoc) | Coordination ledger (CORE / STDLIB / INT / DOC) |
+| [`docs/ECOSYSTEM.adoc`](../docs/ECOSYSTEM.adoc) | Spine + AS↔typed-wasm contract |
+| [`docs/ROADMAP.adoc`](../docs/ROADMAP.adoc) | Development roadmap |
+| [`docs/specs/SPEC.adoc`](../docs/specs/SPEC.adoc) | Core language specification |
+| [`examples/`](../examples/) | Example programs |
+| [`CONTRIBUTING.md`](../CONTRIBUTING.md) | How to contribute |
 
 ## Language Features at a Glance
 
-### Ownership & Borrowing
+### Ownership & Borrowing *(enforced)*
+
 ```affine
 fn transfer(file: own File) -> own File {
   // file is owned, must be returned or consumed
   file
 }
 
-fn read_only(file: &File) -> String {
+fn read_only(file: ref File) -> String {
   // file is borrowed immutably
   file.read_all()
 }
 
-fn modify(file: &mut File) {
+fn modify(file: mut File) {
   // file is borrowed mutably
   file.write("data")
 }
 ```
 
-### Dependent Types
-```affine
-// Length-indexed vectors
-fn head[n: Nat, T](vec: Vec[n + 1, T]) -> T {
-  vec[0]  // Statically safe - vector has at least 1 element
-}
-
-fn append[n: Nat, m: Nat, T](
-  a: Vec[n, T],
-  b: Vec[m, T]
-) -> Vec[n + m, T] {
-  // Return type precisely tracks length
-  ...
-}
-```
-
-### Row Polymorphism
-```affine
-// Works on any record with 'name' field
-fn greet[r](person: {name: String, ..r}) -> String {
-  "Hello, " ++ person.name
-}
+QTT (Quantitative Type Theory) semiring enforced on every `check`, `compile`,
+and `eval` invocation — see [`lib/quantity.ml`](../lib/quantity.ml). Linear
+arrows enforced. Borrow-graph validation + NLL last-use landed
+(CORE-01 parts 1–3 Slice A, see CAPABILITY-MATRIX).
 
-// Can call with any matching record
-greet({name: "Alice", age: 30})
-greet({name: "Bob", role: "Admin", active: true})
-```
+### Algebraic Effects *(partial — interpreter complete; WasmGC dispatch via CPS in flight)*
 
-### Algebraic Effects
 ```affine
 effect Ask[A] {
   fn ask() -> A
@@ -135,28 +132,48 @@ fn main() -{IO}-> Unit {
 }
 ```
 
-### Totality Checking
+Pure/impure separation + effect polymorphism enforced in the typechecker.
+Handlers are interpreter-complete; WasmGC dispatch is the CPS-transform
+line (#225, closed end-to-end; #234 generalised the boundary recogniser).
+
+### Row Polymorphism *(partial)*
+
 ```affine
-// Guaranteed to terminate
-total fn factorial(n: Nat) -> Nat {
-  match n {
-    0 -> 1,
-    n -> n * factorial(n - 1)
-  }
+// Works on any record with 'name' field
+fn greet[r](person: {name: String, ..r}) -> String {
+  "Hello, " ++ person.name
 }
 
-// May diverge (partial by default)
-fn loop_forever() -> Never {
-  loop_forever()
+// Can call with any matching record
+greet({name: "Alice", age: 30})
+greet({name: "Bob", role: "Admin", active: true})
+```
+
+Records + effect rows in typecheck/unify. Not fully exercised end-to-end yet.
+
+### Dependent Types *(parse-only — not enforced)*
+
+```affine
+// Length-indexed vectors — SYNTAX PARSES, but predicates do not
+// reduce and there is no SMT/decision procedure. These types are
+// not enforced at runtime today.
+fn head[n: Nat, T](vec: Vec[n + 1, T]) -> T {
+  vec[0]
 }
 ```
 
+This surface parses but has *no semantics behind it yet* — `TRefined`
+constructors exist in the AST but the typechecker does not reduce
+predicates or check refinements. See `docs/CAPABILITY-MATRIX.adoc`
+row "Dependent / refinement types".
+
 ## Community
 
 - **GitHub**: [github.com/hyperpolymath/affinescript](https://github.com/hyperpolymath/affinescript)
-- **Issues**: Report bugs and request features
-- **Discussions**: Ask questions and share ideas
+- **Issues**: [Report bugs and request features](https://github.com/hyperpolymath/affinescript/issues)
+- **Discussions**: [Ask questions and share ideas](https://github.com/hyperpolymath/affinescript/discussions)
 
 ---
 
-*AffineScript - Safe, Expressive, Predictable*
+*AffineScript — affine types + algebraic effects + typed-WebAssembly.
+Status (live): [`docs/CAPABILITY-MATRIX.adoc`](../docs/CAPABILITY-MATRIX.adoc).*

wiki/language-reference/dependent-types.md

@@ -1,5 +1,15 @@
 # Dependent Types
 
+> **⚠️ Current state: `parse-only`.**
+> The surface syntax described in this page parses, but the typechecker
+> **does not reduce predicates** and there is **no SMT / decision
+> procedure** wired in today. `TRefined` constructors exist in the AST.
+> Predicates and refinements are not enforced at runtime.
+> Authoritative source: [`docs/CAPABILITY-MATRIX.adoc`](../../docs/CAPABILITY-MATRIX.adoc)
+> row "Dependent / refinement types". The ledger entry CORE-05 in
+> [`docs/TECH-DEBT.adoc`](../../docs/TECH-DEBT.adoc) tracks the work
+> needed to lift this from parse-only to enforced.
+
 Dependent types allow types to depend on values, enabling compile-time verification of invariants.
 
 ## Table of Contents

wiki/language-reference/traits.md

@@ -1,5 +1,16 @@
 # Traits
 
+> **⚠️ Current state: `partial`.**
+> Registry, `TopTrait`/`TopImpl`, unification-based `find_impl`, and
+> impl-satisfies-trait are wired into the typechecker. **Missing today:**
+> associated-type substitution in method bodies, where-clause
+> supertraits, coherence checking. The surface and runtime guarantees
+> described below may overstate current enforcement — cross-check with
+> [`docs/CAPABILITY-MATRIX.adoc`](../../docs/CAPABILITY-MATRIX.adoc)
+> row "Traits", and see CORE-04 in
+> [`docs/TECH-DEBT.adoc`](../../docs/TECH-DEBT.adoc) for the remaining
+> work.
+
 Traits define shared behavior that types can implement. They enable polymorphism and code reuse.
 
 ## Table of Contents