Prepare docs site and release readiness

Author: code5717

AGENT.md

@@ -8,6 +8,9 @@ Compatibility pointer for tools that look for a singular `AGENT.md`.
   `AGENTS.md`.
 - **User-facing docs:** [`README.md`](README.md) and [`RELEASE.md`](RELEASE.md)
   remain authoritative for end users.
+- **Agent/curl docs:** [`site/public/llms.txt`](site/public/llms.txt) and
+  [`site/public/docs/index.md`](site/public/docs/index.md) are the
+  agent-readable public docs entry points derived from the authoritative docs.
 
 ## Key Commands (short form)
 
@@ -17,8 +20,10 @@ Compatibility pointer for tools that look for a singular `AGENT.md`.
   `uv run python scripts/build_examples.py --profile debug --backend both --clean`
 - Release artifacts:
   `uv run python scripts/build_examples.py --profile release --backend both --clean`
+- Backend parity: `uv run python scripts/verify_backend_parity.py`
 - Package build: `uv build`
 - Docs site build: `cd site && npm install && npm run build`
+- Agent/curl.md docs: `site/public/llms.txt` and `site/public/docs/`
 
 ## Key Rules (short form)
 
@@ -27,6 +32,8 @@ Compatibility pointer for tools that look for a singular `AGENT.md`.
   worklists in examples and tests.
 - Keep `README.md`, `docs/SPEC.md`, `CHANGELOG.md`, `MISSING_FEATURES.md`,
   and `TODO.md` aligned with any user-visible change.
+- Keep `site/public/llms.txt` and `site/public/docs/` aligned when site
+  navigation, release commands, CLI behavior, or public docs structure changes.
 
 See `AGENTS.md` for the full workflow, post-change checklist, and security
 caveats.

AGENTS.md

@@ -1,7 +1,10 @@
-# agents.md
+# AGENTS.md
 
 Guidance for coding agents working in this repository. Keep changes consistent
 with `README.md` and `RELEASE.md`; those are the authoritative user-facing docs.
+For terminal/curl workflows, `site/public/llms.txt` and
+`site/public/docs/index.md` are the agent-readable docs entry points derived
+from the authoritative docs.
 
 ## Running the Compiler
 
@@ -21,11 +24,19 @@ checkout without a synced environment.
 - Full local release gate: `./run_all_tests.sh`
 - Package build: `uv build`
 - Docs site build: `cd site && npm install && npm run build`
+- Agent/curl.md docs preview: `cd site && npm run build && npm run preview`
+  then check `/a7-py/llms.txt` and `/a7-py/docs/index.md`.
 
 `run_all_tests.sh` is the single source of truth for the full gate (pytest,
-backend tests, example e2e, debug + release artifacts, error-stage matrix,
-docs style). Run it before tagging or before reporting a task as done when
-changes are non-trivial.
+parser/semantic/codegen tests, example e2e for Zig and C, backend parity,
+debug + release artifacts, error-stage matrix, docs style, secrets check).
+Run it before tagging or before reporting a task as done when changes are
+non-trivial.
+
+The public docs site also ships Markdown entry points for agent tooling under
+`site/public/llms.txt` and `site/public/docs/`. Keep those files aligned with
+`README.md`, `RELEASE.md`, and user-visible site navigation when docs structure
+changes.
 
 ## A7 Source Rules
 
@@ -49,10 +60,13 @@ committing:
 3. **docs/SPEC.md** — update if language semantics or syntax changed
 4. **MISSING_FEATURES.md** — mark completed gaps or document new ones
 5. **TODO.md** — check off completed items or add newly discovered work
+6. **site/public/llms.txt** and **site/public/docs/** — update agent/curl.md
+   entry points if site navigation, release commands, CLI behavior, or public
+   docs structure changed
 
 Keep examples and docs aligned across `README.md`, `docs/SPEC.md`,
-`CHANGELOG.md`, `MISSING_FEATURES.md`, and `TODO.md` — drift between them is
-treated as a bug.
+`CHANGELOG.md`, `MISSING_FEATURES.md`, `TODO.md`, `site/public/llms.txt`, and
+`site/public/docs/` — drift between them is treated as a bug.
 
 ## Security Caveat
 

CHANGELOG.md

@@ -29,6 +29,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   status-only.
 - Added a selected Zig/C backend parity verifier that compiles, builds, runs,
   and compares non-example smoke programs across both native backends.
+- Expanded the parity verifier to cover match statements, match expressions,
+  slice fields, indexed slice iteration, and string slice iteration.
+- Added curl.md-friendly public Markdown docs and an `llms.txt` entry point
+  for agent and terminal documentation workflows.
 
 ## [0.3.0] - 2026-05-07
 

CLAUDE.md

@@ -3,6 +3,9 @@
 Project-level guidance for Claude Code. Mirrors `AGENTS.md`; treat that file
 as the canonical agent guide and keep both in sync. `README.md` and
 `RELEASE.md` remain the authoritative user-facing docs.
+For terminal/curl workflows, `site/public/llms.txt` and
+`site/public/docs/index.md` are the agent-readable docs entry points derived
+from the authoritative docs.
 
 ## Running the Compiler
 
@@ -21,10 +24,18 @@ the `main.py` wrapper when working from a fresh checkout.
 - Full local release gate: `./run_all_tests.sh`
 - Package build: `uv build`
 - Docs site build: `cd site && npm install && npm run build`
+- Agent/curl.md docs preview: `cd site && npm run build && npm run preview`
+  then check `/a7-py/llms.txt` and `/a7-py/docs/index.md`.
 
 `run_all_tests.sh` is the single source of truth for the full gate (pytest,
-backend tests, example e2e, debug + release artifacts, error-stage matrix,
-docs style). Run it before reporting a non-trivial task as done.
+parser/semantic/codegen tests, example e2e for Zig and C, backend parity,
+debug + release artifacts, error-stage matrix, docs style, secrets check).
+Run it before reporting a non-trivial task as done.
+
+The public docs site also ships Markdown entry points for agent tooling under
+`site/public/llms.txt` and `site/public/docs/`. Keep those files aligned with
+`README.md`, `RELEASE.md`, and user-visible site navigation when docs structure
+changes.
 
 ## A7 Source Rules
 
@@ -46,10 +57,13 @@ When language features, backends, or user-facing behavior change, update:
 3. `docs/SPEC.md` — language semantics or syntax
 4. `MISSING_FEATURES.md` — close or open gaps
 5. `TODO.md` — check off or add follow-ups
+6. `site/public/llms.txt` and `site/public/docs/` — update agent/curl.md entry
+   points when site navigation, release commands, CLI behavior, or public docs
+   structure changes
 
 Keep examples and docs aligned across `README.md`, `docs/SPEC.md`,
-`CHANGELOG.md`, `MISSING_FEATURES.md`, and `TODO.md` — drift between them is
-treated as a bug.
+`CHANGELOG.md`, `MISSING_FEATURES.md`, `TODO.md`, `site/public/llms.txt`, and
+`site/public/docs/` — drift between them is treated as a bug.
 
 ## Security Caveat
 

MISSING_FEATURES.md

@@ -64,7 +64,8 @@
    - Ownership/borrow-style lifetime guarantees are not implemented.
 
 4. **Backend semantic parity hardening**
-   - Core conformance is green, but differential/backend-equivalence checks should be expanded and kept mandatory for new language features.
+   - Core conformance is green, and the selected differential/backend-equivalence suite now covers control flow, match statements/expressions, slices, string slices, labels, and function pointers.
+   - Keep expanding mandatory parity cases for new language features.
    - C `match` expressions with side-effectful scrutinees lower through generated single-evaluation locals in variable initializers, return values, assignments, function arguments, and I/O arguments.
    - C backend generic function lowering is not implemented; generic coverage remains semantic/test-level rather than runtime example-level.
    - Union declarations lower, but runtime union field construction/access is not yet a completed source-language workflow.

README.md

@@ -175,6 +175,7 @@ Use fixed-width integers such as `i32`, `i64`, `u32`, or `u64` when the data its
 ## Learn More
 
 - Documentation website: `https://code5717.github.io/a7-py/`
+- Agent/curl.md docs entry point: `https://code5717.github.io/a7-py/llms.txt`
 - `docs/SPEC.md` - Language specification
 - `RELEASE.md` - Release/debug build checklist
 - `SECURITY.md` - Security policy and trust boundary

RELEASE.md

@@ -80,8 +80,8 @@ uvx pip-audit --strict
 - docs style checks
 - committed secrets check
 - full pytest suite
-- Python dependency audit
-- docs runtime dependency audit
+
+The Python and docs dependency audits are separate release-gate commands above.
 
 ## Tagging
 

RELEASE_READINESS_REVIEW.md

@@ -1,6 +1,6 @@
 # Release Readiness Review
 
-Date: 2026-05-07
+Date: 2026-05-08
 
 ## Result
 
@@ -21,6 +21,8 @@ The repository is substantially more release-ready than before this pass:
 - protected GitHub `pypi` environment requiring `code5717` review
 - semantic recursion rejection for direct and mutual named call cycles, with
   scope-aware handling for local function-pointer shadowing
+- consolidated docs-site navigation with curl.md-friendly Markdown entry points
+  under `site/public/llms.txt` and `site/public/docs/`
 
 This is not a claim that the implementation is free of all bugs or
 vulnerabilities. For a compiler and native-code build pipeline, that standard is
@@ -39,7 +41,12 @@ not factually provable from local tests alone.
 - `uvx bandit -r src scripts -q --severity-level medium`
 - `uv run python scripts/check_no_secrets.py`
 - `cd site && npm audit --omit=dev --audit-level=moderate`
-- `cd site && npm run build`
+- `cd site && npm run check`
+- direct Chromium CDP preview checks for canonical and compatibility hash links
+  such as `#/language#standard-library`, `#/stdlib`, `#/pipeline#backend-notes`,
+  and `#/cli#flags`
+- preview HTTP checks for `/a7-py/llms.txt`, `/a7-py/docs/index.md`,
+  `/a7-py/docs/status.md`, `/a7-py/sitemap.xml`, and `/a7-py/robots.txt`
 - built wheel installed into a temporary virtualenv and invoked as `a7`
 - `git diff --check`
 - hosted CI and Deploy Docs must be checked after each release-candidate push;
@@ -105,7 +112,16 @@ not factually provable from local tests alone.
   recursion reports when a local function-pointer variable shadows a top-level
   function name.
 - Selected non-example programs now run through both Zig and C backends and
-  compare runtime output.
+  compare runtime output, including match statements/expressions, slices,
+  string slices, labels, and function pointers.
+- Public docs-site top navigation is reduced and old CLI, stdlib, pipeline, and
+  testing pages are consolidated into Start, Language, and Compiler sections
+  with compatibility aliases and verified hash scrolling.
+- `llms.txt` and public Markdown docs under `site/public/docs/` provide stable
+  curl.md/agent entry points for CLI, language, compiler, examples, release,
+  and status information.
+- Site metadata, README, robots, and sitemap now consistently use
+  `https://code5717.github.io/a7-py/`.
 
 ## Residual Risks
 
@@ -116,7 +132,9 @@ not factually provable from local tests alone.
 - Built-in stdlib imports are virtual and still need unification with file-based
   module semantics.
 - Backend parity is verified for examples and selected differential smoke
-  programs, not all possible source programs.
+  programs, including core control flow, match, slices, string slices, labels,
+  and function pointers. It is still not exhaustive for all possible source
+  programs.
 - Tag-based PyPI publishing is wired, but `a7-py` is not yet a public PyPI
   project and still needs matching trusted-publisher configuration before the
   first real publish.

scripts/verify_backend_parity.py

@@ -84,6 +84,90 @@
     op = mul
     io.println("mul = {}", apply(op, 6, 7))
 }
+''',
+    "slice_index_fields": r'''
+io :: import "std/io"
+
+main :: fn() {
+    arr: [4]i32 = [10, 20, 30, 40]
+    tail := arr[1..4]
+    ptr := tail.ptr
+    total := tail[0]
+    for x in tail {
+        total += x
+    }
+    index_sum: usize = 0
+    indexed_value_total := 0
+    for i, x in tail {
+        index_sum += i
+        indexed_value_total += x
+    }
+    io.println("slice = {} {} {}", tail.len, ptr.val, total)
+    io.println("indexed = {} {}", index_sum, indexed_value_total)
+}
+''',
+    "match_statement_ranges": r'''
+io :: import "std/io"
+
+main :: fn() {
+    value := 7
+    match value {
+        case 0: io.println("zero")
+        case 1..5: io.println("small")
+        case 6..10: io.println("medium")
+        else: io.println("large")
+    }
+}
+''',
+    "match_expression_side_effects": r'''
+io :: import "std/io"
+
+calls: i32 = 0
+
+value :: fn() i32 {
+    calls += 1
+    ret 2
+}
+
+pick :: fn() i32 {
+    ret match value() {
+        case 2: 20
+        else: 0
+    }
+}
+
+identity :: fn(x: i32) i32 {
+    ret x
+}
+
+main :: fn() {
+    x: i32 = 0
+    x = match value() {
+        case 2: 7
+        else: 1
+    }
+    y := identity(match value() {
+        case 2: 5
+        else: 0
+    })
+    z := pick()
+    io.println("match = {} {} {} {}", x, y, z, calls)
+}
+''',
+    "string_slice_iteration": r'''
+io :: import "std/io"
+
+main :: fn() {
+    text: string = "abcdef"
+    io.print("text = ")
+    for ch in text[1..4] {
+        io.print("{}", ch)
+    }
+    for ch in text[4..] {
+        io.print("{}", ch)
+    }
+    io.println("")
+}
 ''',
 }
 
@@ -103,6 +187,12 @@ def ok(self) -> bool:
         return self.zig_ok and self.c_ok and self.output_match
 
 
+def result_to_json(result: ParityResult) -> dict[str, object]:
+    data = asdict(result)
+    data["ok"] = result.ok
+    return data
+
+
 def run_cmd(
     cmd: list[str],
     *,
@@ -285,7 +375,7 @@ def main() -> int:
                     "passed": passed,
                     "total": total,
                     "ok": passed == total,
-                    "results": [asdict(result) for result in results],
+                    "results": [result_to_json(result) for result in results],
                 },
                 indent=2,
             ),

site/index.html

@@ -9,20 +9,20 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;600;700&family=Newsreader:opsz,wght@6..72,400;6..72,500;6..72,600&display=swap" rel="stylesheet" />
-    <link rel="canonical" href="https://airbus5717.github.io/a7-py/" />
+    <link rel="canonical" href="https://code5717.github.io/a7-py/" />
     <title>A7 Programming Language</title>
     <meta name="description" content="A7 is a statically-typed, procedural language with array programming capabilities, generics, and manual memory management. Compiles to Zig." />
     <meta property="og:title" content="A7 Programming Language" />
     <meta property="og:description" content="A small systems language with explicit control flow, clear diagnostics, and direct compiler output." />
     <meta property="og:type" content="website" />
-    <meta property="og:url" content="https://airbus5717.github.io/a7-py/" />
+    <meta property="og:url" content="https://code5717.github.io/a7-py/" />
     <meta property="og:site_name" content="A7 Docs" />
     <meta property="og:locale" content="en_US" />
-    <meta property="og:image" content="https://airbus5717.github.io/a7-py/a7-terminal-hero.png" />
+    <meta property="og:image" content="https://code5717.github.io/a7-py/a7-terminal-hero.png" />
     <meta name="twitter:card" content="summary_large_image" />
     <meta name="twitter:title" content="A7 Programming Language" />
     <meta name="twitter:description" content="A small systems language with explicit control flow, clear diagnostics, and direct compiler output." />
-    <meta name="twitter:image" content="https://airbus5717.github.io/a7-py/a7-terminal-hero.png" />
+    <meta name="twitter:image" content="https://code5717.github.io/a7-py/a7-terminal-hero.png" />
   </head>
   <body>
     <div id="root"></div>