Overhaul docs site: in-page Markdown, mermaid diagrams, dedupe, llms-full

- Render Markdown in-page (marked + DOMPurify) instead of linking to raw .md;
  add .markdown-body theme reusing existing tokens; rewrite same-base /docs/*.md
  anchors into react-router navigations.
- Add mermaid diagrams (dark, strict, dynamic import): pipeline + verification
  layers (compiler.md, pipeline.md), language surface mindmap (language.md),
  release flow (release.md), fetch order (guide/agent-usage.md), doc tree
  (index.md), and Implemented/Gaps/Planned buckets (status.md).
- Deduplicate near-duplicate docs into canonical /guide/* and /dev/* pages with
  short alias stubs: installation, cli, api, features, agent-usage, plugins,
  contributing. Update navigation.ts to point at canonical paths.
- Content fixes: drop empty bash fence in getting-started.md; sync example
  count to 43 (README.md, Status.tsx, examples.ts, test_examples_e2e.py,
  examples.md, changelog.md, Home.tsx, release.md); add Errors and Exit
  Codes table to guide/cli.md.
- Expand site/public/llms-full.txt into a true single-file context: full
  43-example catalog, errors/exit-codes table, ASCII pipeline + architecture
  diagrams, agent fetch order, plugin pointers, docs cross-refs.
- Add 5 application-style examples (038-042) with golden outputs; bump
  Examples verified to 43/43.
- Remove stale duplicate AGENT.md (canonical is AGENTS.md).

Author: code5717

AGENT.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- Docs site now renders Markdown in-page with mermaid diagrams (pipeline,
+  verification layers, release flow, doc tree, fetch order, language surface);
+  deduped near-duplicate docs into `/guide` and `/dev` canonical pages with
+  short aliases; expanded `site/public/llms-full.txt` into a true single-file
+  context with the full 43-example catalog, errors/exit-codes table, ASCII
+  pipeline and architecture diagrams, agent fetch order, and plugin pointers.
 - Semantic analysis now has an internal safety-proof phase after base type
   checking and semantic validation. Risky casts, division/modulo, indexing,
   slicing, and reference dereferences must be approved through a `BackendPlan`
@@ -19,6 +25,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   non-zero, bounds, and non-nil facts live in the safety analysis layer.
 - Examples using heap `new` now check against `nil` before field access, and the
   function example guards division by zero.
+- Added five runnable application-style examples covering inventory reporting,
+  text analysis, task-board risk scoring, route simulation, and gradebook
+  averages.
 - C backend support has been retired from the public compiler. Zig is now the
   only supported code generation target, and CI/release/example verification
   gates focus on Zig output.

CHANGELOG.md

@@ -188,7 +188,7 @@ Use fixed-width integers such as `i32`, `i64`, `u32`, or `u64` when the data its
 - `SECURITY.md` - Security policy and trust boundary
 - `RELEASE_READINESS_REVIEW.md` - Current release-readiness audit
 - `COMPLETION_AUDIT.md` - Strict objective-to-evidence release audit
-- `examples/` - 38 sample programs
+- `examples/` - 43 sample programs
 - `MISSING_FEATURES.md` - Feature status and roadmap
 - `CHANGELOG.md` - Change history
 - `docs/ERROR_ANALYSIS.md` - Historical error-analysis snapshot, not current status

README.md

@@ -0,0 +1,60 @@
+// Inventory report with structs, refs, and guarded arithmetic
+
+io :: import "std/io"
+
+Item :: struct {
+    name: string
+    stock: i32
+    reorder: i32
+    price: i32
+}
+
+value_of :: fn(item: Item) i32 {
+    ret item.stock * item.price
+}
+
+apply_discount :: fn(item: ref Item, percent: i32) {
+    if percent <= 0 {
+        ret
+    }
+    if percent >= 100 {
+        item.price = 0
+        ret
+    }
+
+    remaining := 100 - percent
+    item.price = (item.price * remaining) / 100
+}
+
+print_item :: fn(index: i32, item: Item) i32 {
+    line_value := value_of(item)
+    if item.stock <= item.reorder {
+        io.println("{}: {} stock={} value={} reorder=yes", index, item.name, item.stock, line_value)
+        ret 1
+    }
+
+    io.println("{}: {} stock={} value={} reorder=no", index, item.name, item.stock, line_value)
+    ret 0
+}
+
+main :: fn() {
+    io.println("=== Inventory Report ===")
+
+    wrench := Item{name: "wrench", stock: 12, reorder: 5, price: 15}
+    bolt := Item{name: "bolt", stock: 48, reorder: 50, price: 1}
+    sensor := Item{name: "sensor", stock: 7, reorder: 8, price: 42}
+    panel := Item{name: "panel", stock: 3, reorder: 2, price: 75}
+
+    apply_discount(sensor, 10)
+
+    total := value_of(wrench) + value_of(bolt) + value_of(sensor) + value_of(panel)
+    reorder_count := 0
+
+    reorder_count += print_item(0, wrench)
+    reorder_count += print_item(1, bolt)
+    reorder_count += print_item(2, sensor)
+    reorder_count += print_item(3, panel)
+
+    io.println("total value = {}", total)
+    io.println("items to reorder = {}", reorder_count)
+}

examples/038_inventory_report.a7

@@ -0,0 +1,52 @@
+// Text analyzer using strings, chars, slices, and loops
+
+io :: import "std/io"
+
+is_vowel :: fn(ch: char) bool {
+    ret ch == 'a' or ch == 'e' or ch == 'i' or ch == 'o' or ch == 'u' or ch == 'A' or ch == 'E' or ch == 'I' or ch == 'O' or ch == 'U'
+}
+
+count_vowels :: fn(text: string) usize {
+    count: usize = 0
+    for ch in text {
+        if is_vowel(ch) {
+            count += 1
+        }
+    }
+    ret count
+}
+
+count_char :: fn(text: string, needle: char) usize {
+    count: usize = 0
+    for ch in text {
+        if ch == needle {
+            count += 1
+        }
+    }
+    ret count
+}
+
+main :: fn() {
+    io.println("=== Text Analyzer ===")
+
+    text: string = "A7 systems language"
+    prefix := text[0..2]
+    word := text[3..10]
+
+    io.println("text = {}", text)
+    io.println("vowels = {}", count_vowels(text))
+    io.println("spaces = {}", count_char(text, ' '))
+    io.println("letter a = {}", count_char(text, 'a'))
+
+    io.print("prefix = ")
+    for ch in prefix {
+        io.print("{}", ch)
+    }
+    io.println("")
+
+    io.print("word = ")
+    for ch in word {
+        io.print("{}", ch)
+    }
+    io.println("")
+}

examples/039_text_analyzer.a7

@@ -0,0 +1,73 @@
+// Task board with ref mutation and priority labels
+
+io :: import "std/io"
+
+Task :: struct {
+    title: string
+    priority: i32
+    estimate: i32
+    done: bool
+}
+
+complete :: fn(task: ref Task) {
+    task.done = true
+}
+
+raise_priority :: fn(task: ref Task) {
+    if task.priority < 5 {
+        task.priority += 1
+    }
+}
+
+risk_score :: fn(task: Task) i32 {
+    if task.done {
+        ret 0
+    }
+    ret task.priority * task.estimate
+}
+
+priority_label :: fn(priority: i32) string {
+    match priority {
+        case 1: { ret "low" }
+        case 2, 3: { ret "normal" }
+        case 4: { ret "high" }
+        else: { ret "critical" }
+    }
+}
+
+print_task :: fn(index: i32, task: Task) i32 {
+    score := risk_score(task)
+    io.println("{}: {} priority={} done={} risk={}", index, task.title, priority_label(task.priority), task.done, score)
+    if task.done {
+        ret 0
+    }
+    ret 1
+}
+
+main :: fn() {
+    io.println("=== Task Board ===")
+
+    parser := Task{title: "parser cleanup", priority: 3, estimate: 4, done: false}
+    docs := Task{title: "docs pass", priority: 2, estimate: 3, done: false}
+    audit := Task{title: "release audit", priority: 4, estimate: 5, done: false}
+    examples := Task{title: "examples", priority: 1, estimate: 2, done: false}
+
+    complete(docs)
+    raise_priority(audit)
+    raise_priority(examples)
+
+    open_tasks := 0
+    total_risk := 0
+
+    open_tasks += print_task(0, parser)
+    total_risk += risk_score(parser)
+    open_tasks += print_task(1, docs)
+    total_risk += risk_score(docs)
+    open_tasks += print_task(2, audit)
+    total_risk += risk_score(audit)
+    open_tasks += print_task(3, examples)
+    total_risk += risk_score(examples)
+
+    io.println("open tasks = {}", open_tasks)
+    io.println("total risk = {}", total_risk)
+}

examples/040_task_board.a7

@@ -0,0 +1,44 @@
+// Route simulation with structs, arrays, and iterative movement
+
+io :: import "std/io"
+
+Point :: struct {
+    x: i32
+    y: i32
+}
+
+abs_i32 :: fn(value: i32) i32 {
+    if value < 0 {
+        ret -value
+    }
+    ret value
+}
+
+move_by :: fn(point: ref Point, dx: i32, dy: i32) {
+    point.x += dx
+    point.y += dy
+}
+
+manhattan :: fn(point: Point) i32 {
+    ret abs_i32(point.x) + abs_i32(point.y)
+}
+
+main :: fn() {
+    io.println("=== Route Simulation ===")
+
+    position := Point{x: 0, y: 0}
+    dx: [6]i32 = [2, 1, -1, 0, 3, -2]
+    dy: [6]i32 = [0, 2, 1, -3, 1, 0]
+
+    total_distance := 0
+
+    for i := cast(usize, 0); i < 6; i += 1 {
+        step_distance := abs_i32(dx[i]) + abs_i32(dy[i])
+        total_distance += step_distance
+        move_by(position, dx[i], dy[i])
+        io.println("step {} -> ({}, {}) distance={}", i, position.x, position.y, step_distance)
+    }
+
+    io.println("final manhattan = {}", manhattan(position))
+    io.println("path distance = {}", total_distance)
+}

examples/041_route_simulation.a7

@@ -0,0 +1,58 @@
+// Gradebook with nested arrays in structs and ref-based curve updates
+
+io :: import "std/io"
+
+Student :: struct {
+    name: string
+    scores: [3]i32
+}
+
+average :: fn(student: Student) i32 {
+    total := student.scores[0] + student.scores[1] + student.scores[2]
+    ret total / 3
+}
+
+letter :: fn(avg: i32) string {
+    match avg {
+        case 90..100: { ret "A" }
+        case 80..89: { ret "B" }
+        case 70..79: { ret "C" }
+        case 60..69: { ret "D" }
+        else: { ret "F" }
+    }
+}
+
+add_curve :: fn(student: ref Student, points: i32) {
+    for i := cast(usize, 0); i < 3; i += 1 {
+        next := student.scores[i] + points
+        if next > 100 {
+            student.scores[i] = 100
+        } else {
+            student.scores[i] = next
+        }
+    }
+}
+
+print_student :: fn(index: i32, student: Student) i32 {
+    avg := average(student)
+    io.println("{}: {} avg={} grade={}", index, student.name, avg, letter(avg))
+    ret avg
+}
+
+main :: fn() {
+    io.println("=== Gradebook ===")
+
+    mira := Student{name: "Mira", scores: [88, 91, 84]}
+    noah := Student{name: "Noah", scores: [73, 78, 81]}
+    lina := Student{name: "Lina", scores: [95, 97, 99]}
+
+    add_curve(noah, 5)
+
+    class_total := 0
+    class_total += print_student(0, mira)
+    class_total += print_student(1, noah)
+    class_total += print_student(2, lina)
+
+    class_avg := class_total / 3
+    io.println("class average = {}", class_avg)
+}