diff --git a/README.ja.md b/README.ja.md
index 44356ce..3d7c937 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -1,160 +1,198 @@
-# BE Framework デモ集
+# Be Framework パターン集
 
-BE Frameworkの存在論的プログラミングアプローチを示すデモプロジェクト集です。
+[Be Framework](https://github.com/be-framework/be) のための**変容（メタモルフォーシス）パターンカタログ**です。8つの実行可能なPHPデモを収録し、それぞれが1つのフロー形状を独立して示しているため、自分のアプリケーションの出発点としてそのままコピーできます。
 
-## 哲学
+> **「Be, Don't Do（するな、あれ）」** — すべてのパターンは、ワークフローを「データに対して動作するメソッド」ではなく、「次の状態へと *becoming* する型付き・不変な状態の連鎖」としてモデル化します。
 
-BE Frameworkは「Be, Don't Do（するな、あれ）」の原則を体現しています。ソフトウェアを動作の連続ではなく、存在の変容（メタモルフォーシス）としてモデル化します。各デモは6つの哲学的レイヤーを通じて異なる変容パターンを示します：
+---
 
-| レイヤー | 語源 | 役割 |
-|---------|------|------|
-| **Input** | δύναμις（デュナミス） | システムに入る生の可能態 |
-| **Being** | Dasein（現存在） | 計算されたプロパティを持つ存在状態 |
-| **Moment** | 契機 | 遅延Potentialを持つ過渡的段階 |
-| **Final** | ἐνέργεια（エネルゲイア） | 完全に現実化された結果 |
-| **Semantic** | Sinn（意味） | ドメイン検証ルール |
-| **Reason** | 充足理由律 | ビジネスロジックと外部連携 |
+## パターンを選ぶ
 
-## デモカタログ
+あなたの問題に最も近い行を選んでください。各リンクから完全な実装（テスト付き）に飛べます。
 
-### 初級
+| こんな問題には… | パターン | デモ |
+|---|---|---|
+| 入力1、出力1、中間状態なし | **最小変換** | [hello-world](./demos/hello-world/) |
+| 単一フォームの検証と正規化 | **線形** | [contact-form](./demos/contact-form/) |
+| 順序のある複数の変換 | **連鎖チェーン** | [user-registration](./demos/user-registration/) |
+| 独立した関心事が注入Momentを通じてFinalで収束 | **ダイヤモンド** | [order-processing](./demos/order-processing/) |
+| 1つのBeingが複数Reasonサービスをオーケストレーション | **マルチReason Being** | [blog-publishing](./demos/blog-publishing/) |
+| 1入力から判定で複数結果に分岐 | **分岐** | [medical-triage](./demos/medical-triage/) |
+| 段階的なMoment実現（ステージ1がステージ2のゲート） | **カスケードダイヤモンド** | [loan-application](./demos/loan-application/) |
+| 複数入力が複数Finalに分岐し、Momentを共有 | **複合収束** | [insurance-claim](./demos/insurance-claim/) |
 
-#### [hello-world](./demos/hello-world/)
-**パターン:** 最小変換
-**フロー:** `Input → Final`
+> このカタログの機械可読版は [`docs/patterns.json`](./docs/patterns.json) にあります。
+>
+> **図の凡例**: 実線矢印（`→`）は `#[Be]` による変換チェーン。破線矢印（`⇢`）は `#[Inject]` で Final に注入される Moment を表し、各 Moment は Final のコンストラクタ内で自己完結（`be()`）します。
+
+---
+
+## パターンカタログ
 
-最もシンプルなBE Frameworkデモ。BeingやMomentレイヤーを持たない挨拶変換です。
+### 最小変換 — [hello-world](./demos/hello-world/)
 
-```text
-HelloInput → Hello
+**フロー:** `Input → Final`
+
+```mermaid
+flowchart LR
+    I([Input]) --> F([Final])
 ```
 
-#### [contact-form](./demos/contact-form/)
-**パターン:** 線形変換
-**フロー:** `Input → Being → Final`
+最もシンプルなBe Frameworkデモ。BeingやMomentレイヤーを持たない挨拶変換です。
+
+> 具体: `HelloInput → Hello`
 
-最もシンプルなBE Frameworkパターン。基本的な入力検証、メール正規化、受領証生成を示すお問い合わせフォームです。
+### 線形 — [contact-form](./demos/contact-form/)
 
-```text
-ContactInput → EmailNormalized → ContactReceived
+**フロー:** `Input → Being → Final`
+
+```mermaid
+flowchart LR
+    I([Input]) --> B([Being]) --> F([Final])
 ```
 
-#### [user-registration](./demos/user-registration/)
-**パターン:** 連鎖チェーン
-**フロー:** `Input → Being(A) → Being(B) → Being(C) → Final`
+基本的な入力検証、メール正規化、受領証生成を示すお問い合わせフォームです。
 
-Being変換を連鎖させたユーザー登録：メール検証、パスワードハッシュ化、プロフィール拡充。
+> 具体: `ContactInput → EmailNormalized → ContactReceived`
+
+### 連鎖チェーン — [user-registration](./demos/user-registration/)
+
+**フロー:** `Input → Being(A) → Being(B) → Being(C) → Final`
 
-```text
-RegistrationInput → EmailVerified → PasswordHashed → ProfileEnriched → UserRegistered
+```mermaid
+flowchart LR
+    I([Input]) --> B1([Being]) --> B2([Being]) --> B3([Being]) --> F([Final])
 ```
 
-### 中級
+Being変換を連鎖させたユーザー登録：メール検証、パスワードハッシュ化、プロフィール拡充。
+
+> 具体: `RegistrationInput → EmailVerified → PasswordHashed → ProfileEnriched → UserRegistered`
 
-#### [order-processing](./demos/order-processing/)
-**パターン:** ダイヤモンドメタモルフォーシス
-**フロー:** `Input → [並列Beings] → [並列Moments] → Final`
+### ダイヤモンド — [order-processing](./demos/order-processing/)
 
-並列Beingチェーン（在庫、決済、配送）がMomentを生成し、Final状態で収束するECオーダー処理。
+**フロー:** `Input → Final`（3つのMomentがFinalに注入される）
 
-```text
-OrderInput ─┬→ StockLocated → QuantityChecked   → InventoryReserved ─┬→ OrderConfirmed
-            ├→ CardValidated → PaymentAuthorized → PaymentCompleted  ─┤
-            └→ AddressValidated → CarrierSelected → ShippingArranged ─┘
+```mermaid
+flowchart LR
+    I([Input]) --> F([Final])
+    M1([Moment]) -.-> F
+    M2([Moment]) -.-> F
+    M3([Moment]) -.-> F
 ```
 
-#### [blog-publishing](./demos/blog-publishing/)
-**パターン:** 連鎖変換（3 Being、2 Moment）
-**フロー:** `Input → Moment → Being → Being → Moment → Being → Final`
+ECオーダー処理。`OrderInput` は直接 `OrderConfirmed` に遷移し、`OrderConfirmed` が3つの独立した Moment（`InventoryReserved`、`PaymentCompleted`、`ShippingArranged`）を `#[Inject]` します。各 Moment の `be()` は `OrderConfirmed` のコンストラクタ内で呼び出され、3つの関心事が1点で自己完結する「ダイヤモンドメタモルフォーシス」を形成します。
 
-マークダウンレンダリング、スラグ生成、抜粋抽出、著者解決を段階的に処理する記事公開デモ。BeingクラスはArticlePrepared、MarkdownRendered、SlugGenerated。MomentクラスはContentPreparedとMetadataResolved。
+> 具体: `OrderInput → OrderConfirmed`（Final に `InventoryReserved`・`PaymentCompleted`・`ShippingArranged` を注入）
 
-```text
-ArticleInput → ContentPrepared → ArticlePrepared → MarkdownRendered → MetadataResolved → SlugGenerated → ArticlePublished
+### マルチReason Being — [blog-publishing](./demos/blog-publishing/)
+
+**フロー:** `Input → Being → Final`
+
+```mermaid
+flowchart LR
+    I([Input]) --> B([Being]) --> F([Final])
 ```
 
-### 上級
+記事公開デモ。外形的には Linear と同じ `ArticleInput → ArticlePrepared → ArticlePublished` です。特徴は中間 Being（`ArticlePrepared`）が複数の Reason サービス（`MarkdownRenderer`、`SlugGenerator`、`ExcerptExtractor`、`AuthorResolver`）をオーケストレーションし、マークダウンレンダリング・スラグ生成・抜粋抽出・著者解決を1つの変換の中でまとめて行う点にあります。
+
+> 具体: `ArticleInput → ArticlePrepared → ArticlePublished`
+
+### 分岐 — [medical-triage](./demos/medical-triage/)
 
-#### [medical-triage](./demos/medical-triage/)
-**パターン:** 分岐メタモルフォーシス
 **フロー:** `Input → Being → [分岐] → Final(A) | Final(B) | Final(C)`
 
+```mermaid
+flowchart LR
+    I([Input]) --> B([Being])
+    B --> F1([Final A])
+    B --> F2([Final B])
+    B --> F3([Final C])
+```
+
 JTASプロトコルを実装した救急トリアージ。1つの入力が型付き`$being`識別子を通じて3つの異なるFinalに分岐し、各分岐の振る舞いはReason戦略クラスが保持します。
 
-```text
-PatientInput → TriageLevelDetermined
-                      │
-       ┌──────────────┼──────────────┐
-       ↓              ↓              ↓
-  [ImmediateCase] [UrgentCase] [NonUrgentCase]
-       ↓              ↓              ↓
-EmergencyAdmitted  UrgentQueued  OutpatientReferred
+> 具体:
+> ```text
+> PatientInput → TriageLevelDetermined
+>                       │
+>        ┌──────────────┼──────────────┐
+>        ↓              ↓              ↓
+>   [ImmediateCase] [UrgentCase] [NonUrgentCase]
+>        ↓              ↓              ↓
+> EmergencyAdmitted  UrgentQueued  OutpatientReferred
+> ```
+
+### カスケードダイヤモンド — [loan-application](./demos/loan-application/)
+
+**フロー:** `Input → Final`（2つのMomentがFinalに注入され、段階的に実現される）
+
+```mermaid
+flowchart LR
+    I([Input]) --> F([Final])
+    M1([Moment · ステージ1]) -.-> F
+    M2([Moment · ステージ2]) -.-> F
 ```
 
-#### [loan-application](./demos/loan-application/)
-**パターン:** カスケードダイヤモンド（2段階）
-**フロー:** `Input → Stage1(並列 → 収束) → Stage2(並列 → Final)`
+住宅ローン申請デモ。`LoanInput` は直接 `LoanApproved` に遷移し、`LoanApproved` が `CollateralValued` と `InsurancePrepared` を注入します。「カスケード」は Moment 内部の Potential にあり、ステージ1の関心事（身元確認・信用・所得）がステージ2の関心事（物件評価・保険）より先に実現されなければならない点を指します。両ステージは1つの Final に収束します。
 
-段階的Moment実現を伴う住宅ローン申請。Stage 1のMomentは適格性確認時に実現、Stage 2のMomentは最終承認時に実現。
+> 具体: `LoanInput → LoanApproved`（Final に `CollateralValued`・`InsurancePrepared` を注入）
 
-```text
-LoanInput → IdentityVerified ─┬→ CreditScored   → CreditApproved   ─┬→ EligibilityConfirmed
-                              └→ IncomeAssessed → IncomeApproved   ─┘
-                                                                     ↓
-                              ┌→ PropertyAppraised → CollateralValued ─┬→ LoanApproved
-                              └→ InsuranceQuoted   → InsurancePrepared ─┘
-```
-
-#### [insurance-claim](./demos/insurance-claim/)
-**パターン:** 複合収束
-**フロー:** `Input(A) + Input(B) → 収束 → 並列(3) → 分岐 → Final(A) | Final(B)`
+### 複合収束 — [insurance-claim](./demos/insurance-claim/)
 
-複数入力の収束、3方向並列評価、分岐Finalを持つ保険請求処理。
+**フロー:** 2つの Input が、共有 Moment を注入された 2つの Final のいずれかに分岐する
 
-```text
-ClaimInput ──┬→ ClaimRegistered ─┬→ ClaimValidated ─┬→ DamageAssessed  ─┬→ [閾値判定] → ClaimSettled
-PolicyInput ─┴→ PolicyVerified  ─┘                  ├→ AdjusterAssigned ─┤               または
-                                                    └→ FraudScreened   ─┘               ClaimEscalated
+```mermaid
+flowchart LR
+    I1([Input A]) --> F1([Final A])
+    I1 --> F2([Final B])
+    I2([Input B]) --> F1
+    I2 --> F2
+    M1([Moment]) -.-> F1 & F2
+    M2([Moment]) -.-> F1 & F2
+    M3([Moment]) -.-> F1 & F2
 ```
 
-## パターン一覧
+保険請求処理デモ。`ClaimInput` と `PolicyInput` はどちらも `#[Be([ClaimSettled, ClaimEscalated])]` を宣言しており、`$being` の型マッチングによって各 Input がちょうど1つの Final に解決されます。`DamageValued`、`AdjustmentReviewed`、`FraudCleared` などの Moment は両方の Final に注入されるため、どちらの分岐を辿っても同じ自己完結ロジックが共有されます。
 
-| パターン | デモ | 入力数 | Being数 | Moment数 | Final数 |
-|---------|------|--------|---------|----------|---------|
-| 最小 | hello-world | 1 | 0 | 0 | 1 |
-| 線形 | contact-form | 1 | 1 | 0 | 1 |
-| 連鎖 | user-registration | 1 | 3 | 0 | 1 |
-| ダイヤモンド | order-processing | 1 | 6 | 6 | 1 |
-| 連鎖 | blog-publishing | 1 | 3 | 2 | 1 |
-| 分岐 | medical-triage | 1 | 1 | 0 | 3 |
-| カスケード | loan-application | 1 | 5 | 4 | 1 |
-| 複合 | insurance-claim | 2 | 5 | 3 | 2 |
+> 具体: `ClaimInput` + `PolicyInput` → `ClaimSettled` または `ClaimEscalated`（各 Final に共有 Moment を注入）
 
-## テスト実行
+---
 
-各デモには以下をカバーする包括的なテストが含まれます：
-- 正常系統合テスト
-- Semantic検証単体テスト
-- Reasonレイヤーロジックテスト
-- Potential冪等性テスト（該当する場合）
+## テスト実行
 
 ```bash
-# 全テスト実行
-composer test
-
 # 特定デモのテスト実行
-./demos/vendor/bin/phpunit demos/medical-triage/tests/
+cd demos/hello-world && composer install && vendor/bin/phpunit
 ```
 
+各デモには正常系統合テスト、Semantic検証単体テスト、Reasonレイヤーロジックテスト、そして該当する場合はPotential冪等性テストが含まれます。
+
 ## 要件
 
 - PHP 8.2+
 - [Ray.Di](https://ray-di.github.io/)（依存性注入）
 
+## 背景
+
+上記のすべてのパターンは、同じ6つのレイヤーからなる語彙で構築されています。パターンをコピーして使うだけならこの語彙を理解する必要は**ありません**。さらに深く学びたい場合は以下から：
+
+- [`CLAUDE.md`](./CLAUDE.md) — 不変条件と読み順（AIアシスタント向けの契約でもあります）
+- [`docs/GLOSSARY.md`](./docs/GLOSSARY.md) — 用語→ファイル逆引きインデックス
+- [`demos/order-processing/docs/PHILOSOPHY.md`](./demos/order-processing/docs/PHILOSOPHY.md) — 概念的な理論的背景
+
+| レイヤー | 語源 | 役割 |
+|---|---|---|
+| **Input** | δύναμις（デュナミス） | システムに入る生の可能態 |
+| **Being** | Dasein（現存在） | 計算されたプロパティを持つ存在状態 |
+| **Moment** | 契機 | 遅延Potentialを持つ過渡的段階 |
+| **Final** | ἐνέργεια（エネルゲイア） | 完全に現実化された結果 |
+| **Semantic** | Sinn（意味） | ドメイン検証ルール |
+| **Reason** | 充足理由律 | ビジネスロジックと外部連携 |
+
 ## ライセンス
 
 MIT
 
 ---
 
-[English version](./README.md)
\ No newline at end of file
+[English version](./README.md)
diff --git a/README.md b/README.md
index 80d5cbb..2695c6f 100644
--- a/README.md
+++ b/README.md
@@ -1,160 +1,198 @@
-# BE Framework Demos
+# Be Framework Patterns
 
-A collection of demonstration projects showcasing the BE Framework's ontological programming approach.
+A catalog of **metamorphosis patterns** for the [Be Framework](https://github.com/be-framework/be) — eight runnable PHP demos, each isolating one flow shape so you can copy it as a starting point for your own application.
 
-## Philosophy
+> **"Be, Don't Do."** Every pattern models a workflow as a chain of typed, immutable *states that become the next state*, rather than methods that act on data.
 
-The BE Framework embodies the principle "Be, Don't Do" - modeling software as transformations of being rather than sequences of actions. Each demo illustrates different metamorphosis patterns through six philosophical layers:
+---
 
-| Layer | Greek/German | Role |
-|-------|--------------|------|
-| **Input** | δύναμις (Dynamis) | Raw potential entering the system |
-| **Being** | Dasein | Existential state with computed properties |
-| **Moment** | 契機 (Keiki) | Transitional phase with deferred Potentials |
-| **Final** | ἐνέργεια (Energeia) | Fully actualized result |
-| **Semantic** | Sinn | Domain validation rules |
-| **Reason** | Sufficient Reason | Business logic and external integrations |
+## Choose a pattern
 
-## Demo Catalog
+Pick the row that best describes your problem. Each link goes to a complete, tested implementation.
 
-### Beginner Level
+| If your problem looks like… | Pattern | Demo |
+|---|---|---|
+| One input, one output — no intermediate state | **Minimal** | [hello-world](./demos/hello-world/) |
+| Validate and normalize a single form | **Linear** | [contact-form](./demos/contact-form/) |
+| Several transformations that must run in order | **Sequential Chain** | [user-registration](./demos/user-registration/) |
+| Independent concerns converge in a Final via injected Moments | **Diamond** | [order-processing](./demos/order-processing/) |
+| One Being orchestrating multiple Reason services | **Multi-Reason Being** | [blog-publishing](./demos/blog-publishing/) |
+| One input, several outcomes chosen by a decision | **Branching** | [medical-triage](./demos/medical-triage/) |
+| Staged Moment realization (stage 1 gates stage 2) | **Cascade Diamond** | [loan-application](./demos/loan-application/) |
+| Multiple inputs branch to multiple Finals with shared Moments | **Complex Convergence** | [insurance-claim](./demos/insurance-claim/) |
 
-#### [hello-world](./demos/hello-world/)
-**Pattern:** Minimal Transformation
-**Flow:** `Input → Final`
+> A machine-readable version of this catalog lives in [`docs/patterns.json`](./docs/patterns.json).
+>
+> **Diagram legend.** Solid arrows (`→`) show the `#[Be]` transformation chain. Dashed arrows (`⇢`) show Moments injected into a Final via `#[Inject]`, where each Moment self-completes inside the Final constructor.
+
+---
+
+## Pattern catalog
+
+### Minimal — [hello-world](./demos/hello-world/)
 
-The simplest possible BE Framework demo. A greeting transformation with no Being or Moment layers.
+**Flow:** `Input → Final`
 
-```text
-HelloInput → Hello
+```mermaid
+flowchart LR
+    I([Input]) --> F([Final])
 ```
 
-#### [contact-form](./demos/contact-form/)
-**Pattern:** Linear Transformation
-**Flow:** `Input → Being → Final`
+The simplest possible Be Framework demo. A greeting transformation with no Being or Moment layers.
+
+> Concrete: `HelloInput → Hello`
 
-The simplest BE Framework pattern. An email contact form demonstrating basic input validation, email normalization, and receipt generation.
+### Linear — [contact-form](./demos/contact-form/)
 
-```text
-ContactInput → EmailNormalized → ContactReceived
+**Flow:** `Input → Being → Final`
+
+```mermaid
+flowchart LR
+    I([Input]) --> B([Being]) --> F([Final])
 ```
 
-#### [user-registration](./demos/user-registration/)
-**Pattern:** Sequential Chain
-**Flow:** `Input → Being(A) → Being(B) → Being(C) → Final`
+A contact form demonstrating basic input validation, email normalization, and receipt generation.
 
-User registration with chained Being transformations: email verification, password hashing, and profile enrichment.
+> Concrete: `ContactInput → EmailNormalized → ContactReceived`
+
+### Sequential Chain — [user-registration](./demos/user-registration/)
+
+**Flow:** `Input → Being(A) → Being(B) → Being(C) → Final`
 
-```text
-RegistrationInput → EmailVerified → PasswordHashed → ProfileEnriched → UserRegistered
+```mermaid
+flowchart LR
+    I([Input]) --> B1([Being]) --> B2([Being]) --> B3([Being]) --> F([Final])
 ```
 
-### Intermediate Level
+User registration with chained Being transformations: email verification, password hashing, and profile enrichment.
+
+> Concrete: `RegistrationInput → EmailVerified → PasswordHashed → ProfileEnriched → UserRegistered`
 
-#### [order-processing](./demos/order-processing/)
-**Pattern:** Diamond Metamorphosis
-**Flow:** `Input → [parallel Beings] → [parallel Moments] → Final`
+### Diamond — [order-processing](./demos/order-processing/)
 
-E-commerce order processing with parallel Being chains (Inventory, Payment, Shipping) that produce Moments converging in the Final state.
+**Flow:** `Input → Final` with three Moments injected into the Final
 
-```text
-OrderInput ─┬→ StockLocated → QuantityChecked   → InventoryReserved ─┬→ OrderConfirmed
-            ├→ CardValidated → PaymentAuthorized → PaymentCompleted  ─┤
-            └→ AddressValidated → CarrierSelected → ShippingArranged ─┘
+```mermaid
+flowchart LR
+    I([Input]) --> F([Final])
+    M1([Moment]) -.-> F
+    M2([Moment]) -.-> F
+    M3([Moment]) -.-> F
 ```
 
-#### [blog-publishing](./demos/blog-publishing/)
-**Pattern:** Sequential Chain (3 Beings, 2 Moments)
-**Flow:** `Input → Moment → Being → Being → Moment → Being → Final`
+E-commerce order processing. `OrderInput` transitions directly to `OrderConfirmed`, which injects three independent Moments — `InventoryReserved`, `PaymentCompleted`, `ShippingArranged`. Each Moment's `be()` is called inside the `OrderConfirmed` constructor, so the three concerns converge ("diamond metamorphosis") at a single point of self-completion.
 
-Article publishing with staged processing through three Being classes (ArticlePrepared, MarkdownRendered, SlugGenerated) and two Moment classes (ContentPrepared, MetadataResolved), handling markdown rendering, slug generation, excerpt extraction, and author resolution.
+> Concrete: `OrderInput → OrderConfirmed` with `InventoryReserved`, `PaymentCompleted`, `ShippingArranged` injected into the Final.
 
-```text
-ArticleInput → ContentPrepared → ArticlePrepared → MarkdownRendered → MetadataResolved → SlugGenerated → ArticlePublished
+### Multi-Reason Being — [blog-publishing](./demos/blog-publishing/)
+
+**Flow:** `Input → Being → Final`
+
+```mermaid
+flowchart LR
+    I([Input]) --> B([Being]) --> F([Final])
 ```
 
-### Advanced Level
+Article publishing. Externally the shape is Linear — `ArticleInput → ArticlePrepared → ArticlePublished`. What makes it distinctive is the intermediate Being (`ArticlePrepared`), which orchestrates several injected Reason services (`MarkdownRenderer`, `SlugGenerator`, `ExcerptExtractor`, `AuthorResolver`) to carry out markdown rendering, slug generation, excerpt extraction and author resolution in a single transformation.
 
-#### [medical-triage](./demos/medical-triage/)
-**Pattern:** Branching Metamorphosis
-**Flow:** `Input → Being → [Branch] → Final(A) | Final(B) | Final(C)`
+> Concrete: `ArticleInput → ArticlePrepared → ArticlePublished`
+
+### Branching — [medical-triage](./demos/medical-triage/)
 
-Emergency room triage implementing JTAS protocol. One input branches to three possible Finals via a typed `$being` discriminator, with each branch's behavior carried by a Reason strategy class.
+**Flow:** `Input → Being → [Branch] → Final(A) | Final(B) | Final(C)`
 
-```text
-PatientInput → TriageLevelDetermined
-                      │
-       ┌──────────────┼──────────────┐
-       ↓              ↓              ↓
-  [ImmediateCase] [UrgentCase] [NonUrgentCase]
-       ↓              ↓              ↓
-EmergencyAdmitted  UrgentQueued  OutpatientReferred
+```mermaid
+flowchart LR
+    I([Input]) --> B([Being])
+    B --> F1([Final A])
+    B --> F2([Final B])
+    B --> F3([Final C])
 ```
 
-#### [loan-application](./demos/loan-application/)
-**Pattern:** Cascade Diamond (2-Stage)
-**Flow:** `Input → Stage1(parallel → converge) → Stage2(parallel → Final)`
+Emergency room triage implementing the JTAS protocol. One input branches to three possible Finals via a typed `$being` discriminator, with each branch's behavior carried by a Reason strategy class.
 
-Mortgage application with staged Moment realization. Stage 1 Moments realize at eligibility confirmation; Stage 2 Moments realize at final approval.
+> Concrete:
+> ```text
+> PatientInput → TriageLevelDetermined
+>                       │
+>        ┌──────────────┼──────────────┐
+>        ↓              ↓              ↓
+>   [ImmediateCase] [UrgentCase] [NonUrgentCase]
+>        ↓              ↓              ↓
+> EmergencyAdmitted  UrgentQueued  OutpatientReferred
+> ```
 
-```text
-LoanInput → IdentityVerified ─┬→ CreditScored   → CreditApproved   ─┬→ EligibilityConfirmed
-                              └→ IncomeAssessed → IncomeApproved   ─┘
-                                                                     ↓
-                              ┌→ PropertyAppraised → CollateralValued ─┬→ LoanApproved
-                              └→ InsuranceQuoted   → InsurancePrepared ─┘
+### Cascade Diamond — [loan-application](./demos/loan-application/)
+
+**Flow:** `Input → Final` with two Moments injected, realized in staged order
+
+```mermaid
+flowchart LR
+    I([Input]) --> F([Final])
+    M1([Moment · stage 1]) -.-> F
+    M2([Moment · stage 2]) -.-> F
 ```
 
-#### [insurance-claim](./demos/insurance-claim/)
-**Pattern:** Complex Convergence
-**Flow:** `Input(A) + Input(B) → converge → parallel(3) → Branch → Final(A) | Final(B)`
+Mortgage application. `LoanInput` transitions directly to `LoanApproved`, which injects `CollateralValued` and `InsurancePrepared`. The "cascade" is in the Moments' internal Potentials: stage 1 concerns (identity, credit, income) must realize before stage 2 concerns (appraisal, insurance) can commit, even though both stages converge in a single Final.
+
+> Concrete: `LoanInput → LoanApproved` with `CollateralValued`, `InsurancePrepared` injected into the Final.
 
-Insurance claim processing with multiple input convergence, three-way parallel assessment, and branching finals.
+### Complex Convergence — [insurance-claim](./demos/insurance-claim/)
 
-```text
-ClaimInput ──┬→ ClaimRegistered ─┬→ ClaimValidated ─┬→ DamageAssessed  ─┬→ [threshold] → ClaimSettled
-PolicyInput ─┴→ PolicyVerified  ─┘                  ├→ AdjusterAssigned ─┤              or
-                                                    └→ FraudScreened   ─┘              ClaimEscalated
+**Flow:** Two Inputs, each branching to one of two Finals, with Moments shared across branches
+
+```mermaid
+flowchart LR
+    I1([Input A]) --> F1([Final A])
+    I1 --> F2([Final B])
+    I2([Input B]) --> F1
+    I2 --> F2
+    M1([Moment]) -.-> F1 & F2
+    M2([Moment]) -.-> F1 & F2
+    M3([Moment]) -.-> F1 & F2
 ```
 
-## Pattern Summary
+Insurance claim processing. `ClaimInput` and `PolicyInput` both declare `#[Be([ClaimSettled, ClaimEscalated])]`, so each Input resolves to exactly one of the two Finals by `$being` type matching. Moments such as `DamageValued`, `AdjustmentReviewed` and `FraudCleared` are injected into both Finals, so the same self-completion logic is shared regardless of which branch is taken.
 
-| Pattern | Demo | Inputs | Beings | Moments | Finals |
-|---------|------|--------|--------|---------|--------|
-| Minimal | hello-world | 1 | 0 | 0 | 1 |
-| Linear | contact-form | 1 | 1 | 0 | 1 |
-| Sequential | user-registration | 1 | 3 | 0 | 1 |
-| Diamond | order-processing | 1 | 6 | 6 | 1 |
-| Sequential | blog-publishing | 1 | 3 | 2 | 1 |
-| Branching | medical-triage | 1 | 1 | 0 | 3 |
-| Cascade | loan-application | 1 | 5 | 4 | 1 |
-| Complex | insurance-claim | 2 | 5 | 3 | 2 |
+> Concrete: `ClaimInput` + `PolicyInput` → `ClaimSettled` | `ClaimEscalated`, with shared Moments injected into each Final.
 
-## Running Tests
+---
 
-Each demo includes comprehensive tests covering:
-- Happy path integration tests
-- Semantic validation unit tests
-- Reason layer logic tests
-- Potential idempotency tests (where applicable)
+## Running tests
 
 ```bash
-# Run all tests
-composer test
-
-# Run specific demo tests
-./demos/vendor/bin/phpunit demos/medical-triage/tests/
+# Run a specific demo
+cd demos/hello-world && composer install && vendor/bin/phpunit
 ```
 
+Every demo ships with happy-path integration tests, Semantic validation unit tests, Reason layer logic tests, and (where applicable) Potential idempotency tests.
+
 ## Requirements
 
 - PHP 8.2+
 - [Ray.Di](https://ray-di.github.io/) (dependency injection)
 
+## Background
+
+Every pattern above is built from the same six-layer vocabulary. You do **not** need to understand the vocabulary to copy a pattern — but when you want to go deeper, start here:
+
+- [`CLAUDE.md`](./CLAUDE.md) — invariants and reading order (also the AI assistant contract)
+- [`docs/GLOSSARY.md`](./docs/GLOSSARY.md) — term-to-file reverse index
+- [`demos/order-processing/docs/PHILOSOPHY.md`](./demos/order-processing/docs/PHILOSOPHY.md) — the conceptual rationale
+
+| Layer | Greek / German | Role |
+|---|---|---|
+| **Input** | δύναμις (Dynamis) | Raw potential entering the system |
+| **Being** | Dasein | Existential state with computed properties |
+| **Moment** | 契機 (Keiki) | Transitional phase with deferred Potentials |
+| **Final** | ἐνέργεια (Energeia) | Fully actualized result |
+| **Semantic** | Sinn | Domain validation rules |
+| **Reason** | Sufficient Reason | Business logic and external integrations |
+
 ## License
 
 MIT
 
 ---
 
-[日本語版はこちら](./README.ja.md)
\ No newline at end of file
+[日本語版はこちら](./README.ja.md)