docs: polish proof and generated output references in README

Author: bsayli

README.md

@@ -40,7 +40,7 @@ and want boundaries that remain **visible and verifiable** as systems, teams, an
 * Maven 3.9+
 * macOS / Linux / WSL (the proof runner is a shell script)
 
-> Goal: see **GREEN → RED → GREEN** using **build-time architecture guardrails**.
+> **Goal:** see **GREEN → RED → GREEN** using **build-time architecture guardrails (strict mode)**.
 >
 > No app startup required. Guardrails run during `mvn verify` and fail the build deterministically on boundary violations.
 
@@ -80,7 +80,7 @@ CODEGEN_JAR="$(ls -1 ../../target/codegen-blueprint-*.jar | head -n 1)" ./proof/
 * ❌ `mvn verify` fails **deterministically** with a generated ArchUnit rule
 * ✅ The violation is reverted and the build returns to green
 
-Full walkthrough (screenshots + exact failures):
+**Executable evidence bundle (screenshots, exact failures, and proof artifacts):**
 
 👉 [Executable Architecture Proof](docs/demo/executable-architecture-proof.md)
 

docs/demo/executable-architecture-proof.md

@@ -9,7 +9,7 @@ This document provides an end-to-end **GREEN → RED → GREEN** proof that Code
 
 ## Table of Contents
 
-- [Fast Proof (Console-First)](#fast-proof-consolefirst)
+- [Fast Proof (Console-First)](#fast-proof-console-first)
 - [What this proves](#what-this-proves)
 - [Proof Flow (High-Level)](#proof-flow-highlevel)
 - [Proof Output (Persistent, Inspectable Artifacts)](#proof-output-persistent-inspectable-artifacts)
@@ -46,10 +46,10 @@ This document provides an end-to-end **GREEN → RED → GREEN** proof that Code
 - [Why this matters](#why-this-matters-1)
 
 
-## Fast Proof (Console‑First)
+## Fast Proof (Console-First)
 
-If you want to see the **GREEN → RED → GREEN** proof **purely via the console** —
-no screenshots, no explanations, just deterministic build output — run:
+If you want to see the **GREEN → RED → GREEN** proof (**strict architecture guardrails**)  
+**purely via the console** — no screenshots, no explanations, just deterministic build output — run:
 
 ```bash
 # From the repository root
@@ -58,7 +58,8 @@ chmod +x ./proof/proof-runner.sh
 CODEGEN_JAR="$(ls -1 ../../target/codegen-blueprint-*.jar | head -n 1)" ./proof/proof-runner.sh
 ```
 
-The command exits with a **non‑zero code on any unexpected behavior** and prints a concise, step‑by‑step status to the console.
+The command exits with a **non-zero code on any contract violation or unexpected behavior**
+and prints a concise, step-by-step execution status to the console.
 
 ---
 
@@ -182,7 +183,7 @@ The `proof-output` directory proves:
 
 This transforms guardrails from:
 
-*"trust me, it works"*
+*“trust me, it works”*
 
 into:
 
@@ -191,6 +192,7 @@ into:
 ---
 
 ## Notes
+
 * Each run is append‑only; older runs are preserved unless manually removed
 * For deeper inspection of generated projects, run with:
 
@@ -201,16 +203,16 @@ KEEP_WORK_DIR=1 ./proof-runner.sh
 ---
 
 > This is not documentation.
-> This is not convention.
+> This is not a convention.
 >
 > **This is architecture enforced, evaluated, and proven at build time.**
 
 ---
 
 ## Why there is a detailed walkthrough below
 
-The remainder of this document is the **high-resolution proof** —
-the **human-readable version of the console-first proof**:
+The remainder of this document is the **high‑resolution proof** —
+the **human‑readable version of the console‑first proof**:
 
 * screenshots of the generated structure
 * the exact minimal code change that introduces the violation *(same as the script injects)*
@@ -614,8 +616,9 @@ If you want to see what **actual projects generated by Codegen Blueprint look li
 
 see:
 
-→ **Generated Project README Previews**
-[Generated Readmes](./generated-readmes.md)
+* 📘 **Generated Project README Previews** — real, generated README outputs shipped with projects
+
+  → [Generated Readmes](./generated-readmes.md)
 
 These READMEs are **real generator output**, not examples.
 

docs/policies/release-discipline.md

@@ -110,7 +110,7 @@ If a project was generated under **1.0.0** and was valid under the GA contract,
 * A fix that corrects behavior that was **objectively incorrect, unsafe, or security-relevant**.
 * In rare cases, this can **tighten guardrails** when the previous behavior was a bug (e.g., a rule not being applied correctly).
 
-Patch releases may remove accidental loopholes; they do not redefine the intended contract or introduce new architectural intent.
+> Patch releases may remove accidental loopholes; they do not redefine the intended contract or introduce new architectural intent.
 
 ---