Docs beautify pass: README + ARCHITECTURE to PhysicalPlant standard (#826)

Emoji headers, shields, mermaid loop diagram, contents TOC, module table,
quick start, docs index, cross-links. Pattern: pfv-bms README.

https://projects.knownelement.com/issues/826#note-10

docs/ARCHITECTURE.md

@@ -1,17 +1,30 @@
-# KNELPerf v2 — architecture for dynamic, intelligent performance optimization
+# 🏗️ KNELPerf v2 — architecture for dynamic, intelligent performance optimization
 
-Status: DRAFT v1 (2026-09-06, #826). Founder directive: end-to-end
-baseline → audit/benchmark → tweak → re-baseline loop, two-week program.
+> Status: DRAFT v1 (2026-09-06,
+> [#826](https://projects.knownelement.com/issues/826)). Founder directive:
+> end-to-end baseline → audit/benchmark → tweak → re-baseline loop,
+> two-week program.
+
+## 📑 Contents
+
+1. [The loop](#1-the-loop) · 2. [Scheduling architecture](#2-scheduling-architecture-ultix-breakout-redesign) ·
+3. [Proxmox resource groups & VM balancing](#3-proxmox-resource-groups--vm-balancing) ·
+4. [k8s scheduling & Slurm](#4-where-k8s-scheduling-fits-slurm) ·
+5. [Telemetry spine](#5-telemetry-spine-beszel--power) ·
+6. [Workload priority classes](#6-workload-priority-classes-founder-set-order) ·
+7. [Solar + Home Assistant](#7-solar--home-assistant-integration) ·
+8. [Two-site power economics](#8-two-site-power-economics-site-2-printer-farm--laser--cnc) ·
+9. [Hardware plan hooks](#9-hardware-plan-hooks) · 10. [Organization](#10-organization)
 
 ## 1. The loop
 
-```
-        ┌──────────────────────────────────────────────────┐
-        │                                                  │
-   BASELINE ──► AUDIT/BENCHMARK ──► TWEAK ──► RE-BASELINE ─┘
-   (capture)     (diff + beszel/       (CR-gated,   (compare vs
-                 PSI/rapl context)     idempotent)  baseline; keep
-                                                     or roll back)
+```mermaid
+flowchart LR
+    B[📋 BASELINE<br/>cpu-bench.tsv + bench-run.tsv<br/>+ PSI snapshot per host] --> A[🔍 AUDIT<br/>tolerance diff vs bundle<br/>beszel + PSI context]
+    A -->|drift found| T[🔧 TWEAK<br/>tweaks/&lt;id&gt;.sh — idempotent,<br/>GLPI CR-gated on prod]
+    T --> R[📈 RE-BASELINE<br/>capture + compare<br/>evidence to Redmine]
+    R --> A
+    A -->|clean| B
 ```
 
 - **baseline**: `loop/perf-loop.sh baseline <host>` stores a bundle
@@ -31,7 +44,7 @@ Cadence: nightly audit during the 22:00–07:00 batch window (self-measuring:
 the audit itself is low-cost); re-baseline only after a tweak or hardware
 change. First full-fleet baseline wave is this week's deliverable.
 
-## 2. Scheduling architecture (Ultix breakout redesign)
+## 2. 🗓️ Scheduling architecture (Ultix breakout redesign)
 
 See `scheduler/README.md` for the port map and the lessons-learned list. Core
 redesign decisions:
@@ -45,7 +58,7 @@ redesign decisions:
 4. **Deployed by AWX (KNELIAC), not ad-hoc ssh** — scripts here are the
    payload; job templates own the rollout waves.
 
-## 3. Proxmox resource groups & VM balancing
+## 3. 🖥️ Proxmox resource groups & VM balancing
 
 Current fleet (dmidecode-verified 2026-09-06):
 
@@ -78,7 +91,7 @@ Directions:
   needs founder ruling — will be proposed on #826 with a capacity table once
   tsys8/2 land.
 
-## 4. Where k8s scheduling fits; Slurm?
+## 4. ☸️ Where k8s scheduling fits; Slurm?
 
 - **k8s (pfv-k8s, k3s)** owns long-running services + tenant classes
   (ADR-0001 buckets). Resource requests/limits ARE the scheduling policy for
@@ -95,7 +108,7 @@ Directions:
 - The knelperf daynight engine gives the batch window (22:00–07:00) its
   expanded resource envelope on each participating node.
 
-## 5. Telemetry spine: beszel + power
+## 5. 📡 Telemetry spine: beszel + power
 
 - **Beszel has 100% VM+physical coverage** → it is the always-on signal for
   the audit phase (CPU/mem/disk/net per host). Plan: beszel agent metrics
@@ -114,7 +127,7 @@ Directions:
   legs keep fleet draw separable from house load — needed exactly on EEA
   days, so local (non-cloud) telemetry matters.
 
-## 6. Workload priority classes (founder-set order)
+## 6. 🏆 Workload priority classes (founder-set order)
 
 | class | tenants | profile | scheduling |
 |---|---|---|---|
@@ -122,7 +135,7 @@ Directions:
 | 2 | Rogue Technologies (staff engagements), Suborbital Systems (R&D cost center) | bursty, business hours | Burstable QoS; preemptable by class 1 |
 | 3 | HFNOC batch | GIS ETL, weather, time-series OLAP, ERP MRP/capacity-planning | night window (22:00–07:00) or solar-surplus hours; checkpointable, preemptable by 1–2 |
 
-## 7. Solar + Home Assistant integration
+## 7. ☀️ Solar + Home Assistant integration
 
 - SITER-Solar (4 kW baseline design, PVWatts) → once the plant is live, Home
   Assistant exposes real-time production. The loop consumes: surplus watts =
@@ -139,7 +152,7 @@ Directions:
   (deprecated python script), header/ROI inconsistencies, and fixed-cost
   scenario assumptions — fixes landing in that repo.
 
-## 8. Two-site power economics (site 2: printer farm / laser / CNC)
+## 8. 🏭 Two-site power economics (site 2: printer farm / laser / CNC)
 
 The fleet has a second site with 3D-printer farm, laser cutter, and CNC — on
 MUCH more expensive grid power than the main site. That asymmetry drives
@@ -165,7 +178,7 @@ scheduling policy as much as raw performance:
 - KillBill reservation calendar × solar forecast × site-2 tariff = the
   promotion/job-timing advisor output: "cheapest week to run X".
 
-## 9. Hardware plan hooks
+## 9. 🔩 Hardware plan hooks
 
 - Purchases (RAM/CPU) deferred until after 2026-10-11; until then the wins
   are placement + spindles (tsys4's 3 USB toasters join the spindle farm:
@@ -175,7 +188,7 @@ scheduling policy as much as raw performance:
 - tsys2 (Precision 7510 clone + NVMe) → second fast singleton; NVMe pair
   with tsys3 for latency-sensitive class-1 storage.
 
-## 10. Organization
+## 10. 👥 Organization
 
 Performance management org reports to VPTechOps, dotted line VPFacilities —
 identities per the TSGCOO pattern (Cloudron + Bitwarden + Redmine/Gitea/GLPI