Merge pull request #9 from nickroci/docs/readme-architecture-diagram

docs(readme): architecture diagram for 'Design, in one paragraph'

Author: nickroci

README.md

@@ -30,6 +30,12 @@ It's your library. On your disk. In plain markdown. You can `ls` it, `cat` it, `
 
 Ultan is modelled — deliberately, at the level of the architecture, not as decoration — on how mammalian brains decide what to remember and how to surface it again later. Three ideas drive the whole system:
 
+<p align="center">
+  <a href="docs/architecture.png">
+    <img src="docs/architecture.png" width="800" alt="Coding sessions (multiple cascading windows) on the left, exchanging events with Ultan on the right. Inside Ultan: Librarian (Sonnet) sits above Scholar (Opus, the gate) which writes approved entries down into a stack of markdown documents labelled Knowledge." />
+  </a>
+</p>
+
 1. **Surprise gates storage.** Memory is not a transcript. The brain encodes events that violate prediction; novelty and reward-prediction-error are the dopaminergic signals that license hippocampal write (Lisman & Grace, 2005; Schultz, Dayan & Montague, 1997). Ultan's curator does the same: it captures an entry only when the user has told it something a competent assistant would *not* have produced unprompted. No surprise, no write. The three salience signals — **contradicts**, **novel**, **reinforces** — are direct analogues of prediction-error, novelty, and reactivation/consolidation (Sinclair & Barense, 2019).
 2. **Two systems, asymmetric bars.** Fast recall-tuned detection, slow precision-tuned deliberation — System 1 and System 2 (Kahneman, 2011). The Librarian (Sonnet) flags candidates aggressively. The Scholar (Opus) verifies them slowly and decides whether to commit. Cheap-and-broad gates expensive-and-narrow, the way the brain's salience network gates the prefrontal cortex.
 3. **Three retrieval tiers.** Humans don't query memory uniformly. They get ambient familiarity-driven priming, deliberate hippocampal recollection, and a fast orbital-PFC "stop signal" when the environment matches a stored constraint (Yonelinas, 2002; Aron, Robbins & Poldrack, 2014). Ultan exposes each as a separate mechanism with its own latency budget (§ *Three retrieval tiers*, below).