From eaa77614371001131082a47ed7e9b6e259b53bcd Mon Sep 17 00:00:00 2001
From: Sam Rolfe <samuelrolfe@gmail.com>
Date: Tue, 13 Oct 2026 12:27:14 +1100
Subject: [PATCH] docs: align README with project-docs Gitea template

Add Demonstrated Skills & Tech Stack and System Architecture (Mermaid +
Archify map link) sections. Rename Install to Quick Start and group manual
commands under Usage & Configuration.
---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 42 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 0df3c5d..9b1df5b 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,40 @@ ships a small purpose-built parser so it deploys onto hosts without pip
 
 ---
 
+## 🛠 Demonstrated Skills & Tech Stack
+
+- **Core Technologies**: Python 3.10+ using the **standard library only** — no
+  PyYAML, no pip dependencies; systemd user services; YAML frontmatter.
+- **Key Tools**: TypeSafe JEV (`POST api.typesafe.ai/v1/systemone`) for semantic
+  classification, stdlib `urllib` for HTTP, `mmdc` + Archify for diagrams,
+  `rsync` for deployment, Git + Gitea for version control.
+- **Engineering Capabilities**: a deterministic rule engine with a probabilistic
+  second tier, atomic file writes (`tempfile` + `os.replace`), idempotent index
+  updates, a human-in-the-loop approval gate, and a purpose-built YAML parser
+  written to avoid runtime dependencies on NixOS hosts.
+
+## 📐 System Architecture
+
+```mermaid
+flowchart LR
+    A["Sam writes a note"] --> B["010 inbox/"]
+    B --> C{"Watcher<br/>systemd user service<br/>polls every 10s"}
+    C --> D["Tier 1 — rules<br/>folder + keyword hints<br/>user tags win"]
+    D -->|"confident"| F["Proposal"]
+    D -->|"unsure"| E["Tier 2 — TypeSafe JEV<br/>bucket + folder + tags"]
+    E --> F
+    F --> G["Proposal written<br/>into the note frontmatter"]
+    G --> H["Sam reviews in Obsidian"]
+    H -->|"ticks approved"| I["Writer"]
+    H -->|"edits folder first"| G
+    I --> J["Destination folder"]
+    I --> K["Table of Contents"]
+```
+
+*Interactive Architecture Map:* [maps.lab.audasmedia.com.au/obsidian-sorter/docs/obsidian-sorter-map.html](https://maps.lab.audasmedia.com.au/obsidian-sorter/docs/obsidian-sorter-map.html)
+
+---
+
 ## The taxonomy (simplified 2026-09-24)
 
 **The type of a note mirrors the folder it lives in.** Nothing is guessed from
@@ -56,7 +90,7 @@ which area it belongs to while it is still a project.
 
 ---
 
-## Install
+## 🚀 Quick Start
 
 Nothing to install — pure standard library, Python 3.10+.
 
@@ -119,7 +153,9 @@ Logs: `~/.local/state/obsidian-sorter.log`
 
 ---
 
-## Manual use
+## 📝 Usage & Configuration
+
+### Manual use
 
 `obsidian-sort` is installed on `.27` (in `~/bin`):
 
@@ -139,9 +175,9 @@ python3 -m sorter --vault ~/obsidian --inbox "010 inbox" sort-inbox --jev --appl
 
 ---
 
-## Usage reference
+### Usage reference
 
-### Read-only
+#### Read-only
 
 ```bash
 # Vault shape: counts, types, what needs classification
@@ -155,7 +191,7 @@ python3 -m sorter --vault ~/obsidian --inbox "010 inbox" \
     propose "010 inbox/My Note.md" --jev
 ```
 
-### Filing (writes)
+#### Filing (writes)
 
 Dry run by default — nothing is written without `--apply`.
 
@@ -189,7 +225,7 @@ Plan for: 010 inbox/50 Legendary Websites.md
   - remove  010 inbox/50 Legendary Websites.md   (moved out of inbox)
 ```
 
-### Measuring the semantic tier
+#### Measuring the semantic tier
 
 ```bash
 python3 -m sorter --vault ~/obsidian --inbox "010 inbox" benchmark --all --quiet