Copilot/standardize document headers

CONTRIBUTING.md

@@ -16,7 +16,7 @@ CrypSA is **architecture-first**.
 This means:
 
 * the **spec defines runtime behavior**
-* the **architecture defines structure and boundaries**
+* the **architecture defines system structure and conceptual models**
 * implementation follows these definitions
 
 > Contributions must preserve clarity and consistency of the model.
@@ -27,13 +27,13 @@ This means:
 
 The repository is structured by document authority:
 
-| Layer             | Purpose                        | Authority         |
-| ----------------- | ------------------------------ | ----------------- |
-| `spec/`           | Runtime behavior               | **Highest**       |
-| `architecture/`   | Structure and responsibilities | High              |
-| `implementation/` | How to build                   | Support           |
-| `diagrams/`       | Visualization                  | Non-authoritative |
-| `exploratory/`    | Ideas                          | Non-authoritative |
+| Layer             | Purpose                                   | Authority         |
+| ----------------- | ----------------------------------------- | ----------------- |
+| `spec/`           | Authoritative runtime behavior            | **Highest**       |
+| `architecture/`   | System structure and responsibilities     | High              |
+| `implementation/` | How to build                              | Support           |
+| `diagrams/`       | Visualization                             | Non-authoritative |
+| `exploratory/`    | Ideas                                     | Non-authoritative |
 
 ### Rules
 
@@ -75,13 +75,13 @@ All contributors must follow the terminology defined in:
 
 ✔ Correct:
 
-``` id="tr8wq5"
+```
 validator validates events
-````
+```
 
 ❌ Incorrect:
 
-```id="83nmq2"
+```
 server validates events
 ```
 
@@ -125,9 +125,11 @@ The following phrases are **canonical** and must be used exactly as written.
 
 Do not rephrase, simplify, substitute, or partially restate these phrases.
 
-If a sentence expresses one of these concepts, it must use the canonical phrasing exactly.
+If a sentence expresses one of these concepts, it must use the canonical phrasing exactly.  
 Near matches are not acceptable.
 
+These phrases are enforced by documentation linting and must not be altered.
+
 ---
 
 ### Validator Authority
@@ -169,11 +171,11 @@ CrypSA enforces strict separation:
 | Truth          | Validation + canonical event history |
 | Translation    | Adapters                             |
 | Interpretation | Lenses                               |
-| Experience     | UI / simulation                      |
+| Experience     | UI and local simulation              |
 
 ### Rules
 
-* Adapters **change structure, not meaning**
+* Adapters **change structure without interpreting meaning**
 * Lenses **define meaning, not structure**
 * UI **does not define truth**
 * Observers **never define canonical truth**
@@ -200,7 +202,7 @@ Do not blur these boundaries in contributions.
 
 2. Reference it elsewhere:
 
-```id="f6o525"
+```
 See: Terminology Primer → [Term]
 ```
 
@@ -234,9 +236,9 @@ When contributing documentation:
 
 Examples:
 
-❌ Spec logic inside architecture docs
-❌ Implementation details inside spec
-❌ New concepts defined inside diagrams
+❌ Spec logic inside architecture docs  
+❌ Implementation details inside spec  
+❌ New concepts defined inside diagrams  
 
 ---
 

CrypSA_Architecture_Overview.md

@@ -10,14 +10,22 @@ For a worked example, see:
 
 ---
 
-## 📜 Specification Authority
+## 📜 Authority Level
 
-The `/spec` directory is the **authoritative definition of runtime behavior**.
+CrypSA documentation is structured across layers:
 
-Architecture documents explain the system.
-The spec defines how it must behave.
+* `/spec` — authoritative definition of runtime behavior
+* `/architecture` — system structure and conceptual models
 
-If there is any conflict, **the spec takes precedence**.
+This document provides a high-level structural overview.
+
+For strict separation of responsibilities, see:
+
+→ `CrypSA_Boundary_Definitions.md`
+
+If there is any conflict:
+
+* spec takes precedence over architecture
 
 ---
 
@@ -57,6 +65,10 @@ They are responsible for local simulation and experience.
 
 Observers do **not define truth**.
 
+For the boundary between observers and the validator, see:
+
+→ `CrypSA_Boundary_Definitions.md`
+
 ---
 
 ### Validator
@@ -68,12 +80,14 @@ The validator:
 * accepts or rejects them
 * assigns canonical ordering (`canonical_sequence`)
 
-Accepted events become canonical and are appended to canonical event history, which defines what is true.
+If accepted, an event becomes canonical and is appended to canonical event history.
 
 > Canonical event history is the source of truth.
 
 The validator is a **logical role**, not a specific machine.
 
+It is the only component that defines what becomes canonical.
+
 It may run:
 
 * locally (within an observer environment)
@@ -97,13 +111,16 @@ Not all validators are servers, but all servers host a validator.
 
 Adapters:
 
-* reshape canonical and observer data
+* reshape canonical data and observer-local data
 * prepare structured outputs for interpretation and UI
 
 Adapters are the **translation layer**.
 
-They change structure, not meaning.
-They do not define truth.
+They reshape data for downstream systems.
+
+For strict responsibility boundaries between adapters and lenses, see:
+
+→ `CrypSA_Boundary_Definitions.md`
 
 ---
 
@@ -117,7 +134,11 @@ Lenses:
 
 Lenses are the **interpretation layer**.
 
-They do not define truth or mutate canonical data.
+They interpret data for observer experience.
+
+For strict responsibility boundaries between lenses and adapters, see:
+
+→ `CrypSA_Boundary_Definitions.md`
 
 ---
 
@@ -152,6 +173,22 @@ This separation prevents:
 
 ---
 
+## Responsibility Boundaries
+
+CrypSA enforces strict boundaries between system responsibilities.
+
+These boundaries prevent:
+
+* responsibility overlap
+* architectural drift
+* ambiguity in system design
+
+For formal definitions of these boundaries, see:
+
+→ `CrypSA_Boundary_Definitions.md`
+
+---
+
 ## Why This Structure Exists
 
 Traditional architectures often combine:
@@ -169,30 +206,36 @@ CrypSA separates them to:
 * support multiple observer perspectives
 * allow independent evolution of layers
 
+For how this architecture affects infrastructure design, see:
+
+→ `CrypSA_Infrastructure_Implications.md`
+
 ---
 
 ## Data Flow (Simplified)
 
-```mermaid id="e9z2gk"
+```mermaid
 flowchart LR
 
-A[Canonical Event History] --> B[Derived Canonical State]
-B --> C[Adapters]
-C --> D[Lenses]
-D --> E[UI / Experience]
+A["Canonical Event History"] --> B["Derived Canonical State"]
+B --> C["Adapters"]
+C --> D["Lenses"]
+D --> E["UI / Experience"]
 ```
 
 ---
 
 ## Intent Flow (Simplified)
 
-```mermaid id="n3b6rq"
+```mermaid
 flowchart LR
 
-A[User Action] --> B[Candidate Event]
-B --> C[Validator]
-C -->|Accepted| D[Canonical Event History]
-C -->|Rejected| E[Rejection]
+A["User Action"] --> B["Invariant Boundary"]
+B -->|Remains Local| C["Local Result"]
+B -->|Crosses Boundary| D["Candidate Event"]
+D --> E["Validator"]
+E -->|Accepted| F["Canonical Event History"]
+E -->|Rejected| G["Reconciliation"]
 ```
 
 ---
@@ -209,7 +252,9 @@ Truth is established through validation and recorded in canonical event history.
 
 Derived canonical state is reconstructed via replay.
 
-> Derived canonical state is a projection of canonical event history. It is not the source of truth.
+Derived canonical state is not a source of truth.
+
+> Derived canonical state is a projection of canonical event history.
 
 Everything else builds on that.
 

CrypSA_In_5_Minutes.md

@@ -11,6 +11,14 @@ Before reading this, you should have seen:
 
 This document explains the same system in words.
 
+For a complete end-to-end explanation of how CrypSA operates at runtime, see:
+
+→ architecture/CrypSA_Runtime_Model.md
+
+For how CrypSA affects infrastructure and scaling, see:
+
+→ CrypSA_Infrastructure_Implications.md
+
 ---
 
 ## The Core Idea
@@ -26,28 +34,29 @@ In CrypSA:
 * **observers** simulate locally
 * actions are proposed as **candidate events**
 * a **validator** evaluates those events
-* accepted events become **canonical events**
-* canonical events are appended to **canonical event history**
+* If accepted, an event becomes canonical and is appended to canonical event history
 
-> The shared world is defined by accepted events, not continuously synchronized state.
 > Canonical event history is the source of truth.
 
 ---
 
-## The Event Flow
+## The Event Flow (Conceptual)
+
+Everything in CrypSA follows a consistent event-driven process:
 
-Everything in CrypSA follows this flow:
+* observers simulate locally
+* candidate events are proposed
+* the validator evaluates events against invariants
+* if accepted, events become canonical and are appended to canonical event history
+* observers derive state through replay and reconcile with canonical event history
 
-1. An observer simulates locally
-2. The observer proposes a **candidate event**
-3. The **validator** checks invariants
-4. If accepted → the event becomes **canonical and is appended to canonical event history**
-5. Observers reconcile to canonical truth
+👉 For the exact runtime flow, see:
+→ architecture/CrypSA_Runtime_Model.md
 
-This is the boundary between:
+This defines the boundary between:
 
-* local possibility
-* canonical reality
+* local possibility  
+* canonical reality  
 
 ---
 
@@ -57,6 +66,7 @@ The validator is responsible for:
 
 * accepting or rejecting candidate events
 * enforcing invariants
+* If accepted, an event becomes canonical and is appended to canonical event history
 * maintaining canonical event history
 
 > The validator defines what becomes canonical.
@@ -96,7 +106,7 @@ end
 
 subgraph Experience
 E[UI and Observer Experience]
-F[Local Simulation]
+F[Local Prediction]
 end
 
 A --> B
@@ -113,7 +123,7 @@ Think of CrypSA like this:
 
 * the validator determines what becomes canonical
 * observers simulate what they think is happening
-* only validated events become part of canonical history
+* only validated events become part of canonical event history
 * everything else is local prediction
 
 The system is easiest to understand as **four separate responsibilities**.
@@ -206,6 +216,18 @@ But:
 ## Derived State
 
 > Derived canonical state is a projection of canonical event history. It is not the source of truth.
+> Derived canonical state is reconstructed via replay.
+
+---
+
+## Determinism
+
+Given the same:
+
+* canonical event history
+* interpretation logic
+
+all observers derive equivalent derived canonical state via replay.
 
 ---
 
@@ -284,7 +306,7 @@ It is a way of structuring:
 * authority
 * validation
 * interpretation
-* shared reality
+* shared system behavior
 
 ---
 
@@ -317,8 +339,8 @@ CrypSA is not ideal for:
 
 ## If You Understand This, You Understand CrypSA
 
-* events become truth only after validation
-* truth is an append-only history
-* state is derived, not stored
+* events become canonical only after validation
+* canonical event history is the source of truth
+* derived canonical state is reconstructed via replay
 * observers simulate locally and reconcile
-* the validator defines canonical reality
+* the validator defines what becomes canonical