From 79549c9f9a95cf2518ada5bcfb50fe887003197d Mon Sep 17 00:00:00 2001
From: Ruan <ruan.klein@gmail.com>
Date: Sun, 20 Sep 2026 22:47:02 -0300
Subject: [PATCH] docs(readme): add architecture diagram and fm-chat example

---
 README.md | 48 ++++++++++++++++++++++++++++++------------------
 1 file changed, 30 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 9c39561..a9250fb 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,30 @@ private framework bindings.
 It is a focused Go library: not a CLI, Apple SDK, Swift bridge, cgo bridge, or
 reimplementation of Foundation Models.
 
+## How It Works
+
+```mermaid
+flowchart LR
+    app[Go application]
+    fmgo["fmgo Client API<br/>platform checks<br/>process and stream management<br/>typed errors"]
+    ops["Native fm operations<br/><br/>respond · stream · chat<br/>count-tokens · schema<br/>available · license · serve"]
+    executable["Apple's native fm executable"]
+    models["Apple Foundation Models<br/>on-device model runtime"]
+    result["Responses, streams,<br/>and typed diagnostics"]
+
+    app --> fmgo
+    fmgo --> ops
+    ops --> executable
+    executable --> models
+    models -.-> result
+    result -.-> app
+```
+
+`fmgo` builds argument lists, validates the supported platform, manages the
+native `fm` process and streaming, translates known diagnostics into Go errors,
+and returns responses to the calling application. The Foundation Models runtime
+remains Apple's native on-device implementation; `fmgo` does not replace it.
+
 ## Footprint
 
 At `v0.1.2`, fmgo contains 31,794 bytes (about 31 KiB) of production Go source:
@@ -58,6 +82,12 @@ the native executable cannot be located.
 go get github.com/ruanklein/fmgo
 ```
 
+## Example Project
+
+[`fm-chat`](https://github.com/ruanklein/fm-chat) is a demonstration project
+that uses `fmgo` to build an interactive chat application with Apple's native
+Foundation Models CLI.
+
 ## Quick Start
 
 ```go
@@ -300,24 +330,6 @@ Known CLI conditions also map to `ErrFMNotFound`, `ErrModelUnavailable`,
 conservative and uses diagnostic markers emitted by the native CLI; inspect
 `CommandError.Stderr` when you need the original diagnostic text.
 
-## How It Works
-
-```text
-Go application
-      │
-      ▼
-    fmgo
-      │
-      ▼
-      fm
-      │
-      ▼
-Apple Foundation Models
-```
-
-`fmgo` builds argument lists, manages native subprocesses and streaming,
-translates known errors, and presents the native CLI through Go types.
-
 ## Platform Scope
 
 `fmgo` intentionally targets Apple's native `fm` command on macOS. It does not