docs: clarify GA guarantees, remove misleading production/runtime claims, and fix generated README formatting

Author: bsayli

README.md

@@ -26,8 +26,8 @@
 
 Codegen Blueprint exists for that exact moment: when architecture needs to become **observable**, not aspirational.
 
-> If you’re looking for a fast scaffold, use Spring Initializr.  
-> This is for teams who want architecture that stays **observable and executable** over time.
+> This separation keeps the core engine isolated from technology choices
+> and enables future stack expansion **without changing the engine’s architectural contract**.
 
 ---
 
@@ -629,6 +629,8 @@ From Day Zero to Production — architecture stays **intentional**, **testable**
 
 ### 🧭 Roadmap Principles (Order Matters)
 
+> This roadmap expresses direction and intent, not contractual guarantees.
+
 Blueprint evolves in intentional layers to protect its core promise:
 
 1. **Prove the contract** (determinism, guardrails, reproducible proof)

SECURITY.md

@@ -90,7 +90,6 @@ Severity determines prioritization and disclosure timing.
 
 * Codegen Blueprint generator engine (domain, application, adapter)
 * CLI interface and option parsing
-* Generated architecture guardrails (e.g., ArchUnit tests/rules)
 * Templates, profiles, and build configuration produced by the generator
 * CI/CD configuration and repository automation
 

docs/architecture/architecture-governance-and-ai-protocol.md

@@ -57,9 +57,10 @@ Therefore:
 
 Every non-trivial change follows this explicit sequence:
 
-> **Skipping any step invalidates the change — regardless of test results.**
+> **Skipping any step makes the change not eligible for merge — regardless of test results.**
 
-This protocol exists to ensure architectural intent survives beyond individual implementations.
+This protocol exists to ensure that architectural intent
+survives beyond individual implementations and tooling outcomes.
 
 ### 3.1 Intent
 
@@ -135,20 +136,23 @@ This protocol exists to ensure architectural intent survives beyond individual i
 
 ## 5. Architecture Guardrails Philosophy
 
-* Architecture guardrails are **opt-in**, never hidden
-* Guardrails rules are **generated**, not hard-wired
+Architecture guardrails exist to make architectural intent
+**visible and enforceable at build time**.
 
-> Generated guardrails rules are platform-defined and centrally evolved,
-> while remaining visible and reviewable at the service level.
+They are:
 
-Supported guardrails modes (explicitly selected at generation time):
+* **explicitly opt-in** — never implicit or hidden
+* **generated artifacts** — not hand-written conventions
+* **evaluated during the build** — not at runtime
+
+Supported guardrails modes are selected explicitly at generation time:
 
 * `none` — generation only
-* `basic` — structural & dependency guards
+* `basic` — structural and dependency boundaries
 * `strict` — architecture drift prevention
 
-> Architecture guardrails must surface violations deterministically —
-> or they must not be claimed at all.
+> Guardrails are only claimed where violations
+> surface deterministically via the build.
 
 ---
 

docs/architecture/architecture-guardrails-rulebook.md

@@ -615,11 +615,15 @@ Whether a project enables:
 is determined **explicitly by CLI flags and release-level defaults**,  
 not by this document.
 
-For **Codegen Blueprint 1.0.0 GA**:
+For **Codegen Blueprint 1.0.0 GA**, guardrails activation follows the
+**CLI contract and release notes**:
 
-* The default guardrails mode is **`basic`**
-* **`strict`** guardrails are **explicitly opt-in**
-* No project is forced into strict enforcement unless explicitly requested
+* `basic` is the default mode unless explicitly overridden
+* `strict` is opt-in only
+* No project is forced into strict enforcement without an explicit request
+
+> 📌 The authoritative source for defaults and activation behavior
+> is the **CLI contract and the release notes**, not this rulebook.
 
 The **authoritative source** for:
 

docs/architecture/executable-architecture-contract.md

@@ -48,7 +48,7 @@ Anything not explicitly listed here is **out of scope** for 1.0.0 GA.
 
 The engine today:
 
-> Generates clean, production‑viable Spring Boot services with **architecture‑aware** and **test‑ready** output.
+> Generates deterministic, build-verified Spring Boot projects with **architecture-aware** and **test-ready** output.
 
 ---
 
@@ -311,4 +311,4 @@ Any change touching architecture must answer:
 * Architecture‑aware structure
 * Predictable foundations for evolution
 
-> 🚀 **Executable Architecture becomes observable — and testable — here.**
+> **Executable Architecture becomes observable — and testable — here.**

docs/demo/executable-architecture-proof.md

@@ -71,9 +71,9 @@ This single command demonstrates — end to end — that Codegen Blueprint can:
 * fail the build **deterministically** when a boundary is violated
 * return to green immediately once the violation is removed
 
-No app server run.
-No runtime checks.
-No custom test harness.
+No application run (no `spring-boot:run`, no `java -jar`).
+No runtime enforcement — guardrails are evaluated at build time.
+No custom test framework beyond standard JUnit + ArchUnit.
 
 > **Architecture is evaluated by the build itself.**
 
@@ -165,7 +165,7 @@ A machine‑readable and human‑readable execution ledger:
 * exact log and excerpt file references
 * final proof result
 
-This file is the **contractual evidence** that the proof executed as intended.
+This file is the **primary evidence ledger** that the proof executed as intended.
 
 ---
 
@@ -266,7 +266,7 @@ Specifically, it demonstrates that:
 * A style guide
 
 No manual app server is started.
-The proof is driven by **`mvn verify`** (tests may start a Spring test context as part of the build — that is still build-time evaluation).
+The proof is driven by **`mvn verify`**
 
 ---
 

docs/demo/generated/hexagonal/README.md

@@ -131,7 +131,7 @@ They provide **deterministic** feedback during:
 * Canonical vocabulary (generated contract surface):
   * `src/test/java/io/github/blueprintplatform/greeting/architecture/archunit/HexagonalGuardrailsScope.java`
 * Generated rules live under:
-* `src/test/java/io/github/blueprintplatform/greeting/architecture/archunit/`
+  * `src/test/java/io/github/blueprintplatform/greeting/architecture/archunit/`
 
 ---
 

docs/demo/generated/standard/README.md

@@ -125,7 +125,7 @@ They provide **deterministic** feedback during:
 * Canonical vocabulary (generated contract surface):
   * `src/test/java/io/github/blueprintplatform/greeting/architecture/archunit/StandardGuardrailsScope.java`
 * Generated rules live under:
-* `src/test/java/io/github/blueprintplatform/greeting/architecture/archunit/`
+  * `src/test/java/io/github/blueprintplatform/greeting/architecture/archunit/`
 
 ---
 

docs/policies/release-discipline.md

@@ -54,7 +54,7 @@ Where:
 
 ## 1.0.0 — General Availability (GA)
 
-Version **1.0.0** marks the point where Codegen Blueprint becomes a **stable product**, not an experiment.
+Version **1.0.0** marks the point where Codegen Blueprint becomes a **contractually stable product**, not an experiment.
 
 From this version onward:
 
@@ -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.
+Patch releases may remove accidental loopholes; they do not redefine the intended contract or introduce new architectural intent.
 
 ---
 

pom.xml

@@ -15,9 +15,7 @@
     <artifactId>codegen-blueprint</artifactId>
     <version>1.0.0</version>
     <name>codegen-blueprint</name>
-    <description>Hexagonal, profile-driven blueprint engine for generating production-ready project scaffolding across
-        frameworks and languages
-    </description>
+    <description>Architecture-first project generator for Spring Boot with build-time executable architecture guardrails.</description>
     <url>https://github.com/blueprint-platform/codegen-blueprint</url>
 
     <licenses>