From 89ece928dc2d11818aaae0f6924b2aed0cdf8822 Mon Sep 17 00:00:00 2001
From: vingrad <vingrad@gmail.com>
Date: Thu, 11 Jun 2026 00:59:26 +0200
Subject: [PATCH] Add a system-flow diagram to the README intro
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A Mermaid flowchart of the core loop — goal in, ranked plan out,
immutable versions, signals through the materiality gate, outcomes
recorded back — now opens the README. The ASCII arrow list in "Core
idea" said the same thing lower down, so it is folded into the new
diagram and the section keeps only its prose.
---
 README.md | 36 +++++++++++++++---------------------
 1 file changed, 15 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index a4d6af7..2c403b1 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,20 @@ It is built for use cases where a system should not simply ask an LLM “what sh
 
 The project focuses on **decision infrastructure**, not chatbot coaching.
 
+How it works at a glance:
+
+```mermaid
+flowchart TD
+    G["🎯 Goal<br/>context · assets · constraints"] --> E["Decision Engine"]
+    E --> P["Ranked action plan<br/>moves · experiments · fallbacks · provenance"]
+    P --> V[("Immutable plan versions<br/>v1 → v2 → …")]
+    S["📡 Signal<br/>new information"] --> M{"material?"}
+    M -- "yes — replan" --> E
+    M -- "no — version stands, audited" --> V
+    O["✅ Outcome<br/>recorded result"] --> V
+    V -. "world changes" .-> S
+```
+
 ---
 
 ## Why this exists
@@ -43,27 +57,7 @@ This project explores how to build that as a clean, scalable backend component.
 
 ## Core idea
 
-```text
-Goal
-  + Context
-  + Assets
-  + Constraints
-  + Signals
-  + Outcomes
-  + Live data (fetched from external sources at decision time)
-        ↓
-Decision Engine
-        ↓
-Ranked Action Plan
-        ↓
-Versioned Plan State
-        ↓
-New Signals / Outcomes
-        ↓
-Replanning
-```
-
-Instead of returning a single `next_best_action`, the engine returns ranked action paths with rationale, experiments, fallbacks, and provenance.
+Instead of returning a single `next_best_action`, the engine returns ranked action paths with rationale, experiments, fallbacks, and provenance — and keeps them versioned as the world changes (see the flow above).
 
 ---