diff --git a/README.md b/README.md
index 92fea10..1f25adc 100644
--- a/README.md
+++ b/README.md
@@ -18,22 +18,23 @@ Pi Zero 2W + Arduino Nano motorcycle info terminal.
 
 ```
 smart-serow/
-├── arduino/              # Arduino sketches
-│   └── hello.ino
+├── arduino/                # Arduino sketches (sensor interface)
+├── extra/                  # Assets deployed alongside app
+│   ├── fonts/              # Custom fonts
+│   ├── images/             # Static images
+│   └── themes/             # Theme JSON files (→ generate_theme.py)
 ├── pi/
-│   └── ui/               # Flutter app (elinux target)
-│       ├── lib/main.dart
-│       ├── pubspec.yaml
-│       └── elinux/       # Generated by flutter-elinux (gitignored)
-├── scripts/
-│   ├── build.py          # Cross-compile for ARM64
-│   ├── deploy.py         # Push to Pi via rsync
-│   ├── build-deploy.py   # One-click build + deploy
-│   ├── deploy_target.sample.json
-│   ├── pi_setup.sh       # One-time Pi setup
-│   └── smartserow-ui.service.sample
-├── pi_sysroot/           # Pi libraries for cross-linking (gitignored)
-└── LICENSE
+│   └── ui/                 # Flutter app
+│       ├── lib/
+│       │   ├── main.dart           # Entry point
+│       │   ├── app_root.dart       # Screen state management
+│       │   ├── screens/            # Full-screen views
+│       │   ├── widgets/            # Reusable components
+│       │   ├── services/           # Singletons (config, sensors, theme)
+│       │   └── theme/              # Colors and theme provider
+│       └── config.json             # Runtime config (navigator, paths)
+├── scripts/                # Build, deploy, and setup helpers
+└── pi_sysroot/             # Pi libraries for cross-linking (gitignored)
 ```
 
 ## Theme System
diff --git a/arduino/README.md b/arduino/README.md
new file mode 100644
index 0000000..d9f4d3f
--- /dev/null
+++ b/arduino/README.md
@@ -0,0 +1,36 @@
+# Arduino
+
+Sensor interface running on Arduino Nano, communicating with Pi via UART.
+
+## Sketches
+
+| Folder | Purpose |
+|--------|---------|
+| `main/` | Primary telemetry sketch |
+
+## Current Capabilities
+
+- Battery voltage monitoring (voltage divider on A0)
+- Serial output at 9600 baud, 1Hz update rate
+
+## Planned
+
+- RPM sensing (pulse counting from ignition coil)
+- Engine temperature (thermocouple/NTC)
+- Gear position indicator
+- Turn signal / high beam status
+
+## Hardware
+
+- **MCU**: Arduino Nano (ATmega328P)
+- **Connection**: UART to Pi GPIO (TX→RX, RX→TX, common GND)
+- **Voltage sensing**: Resistor divider scaled for 0-20V input range
+
+## Protocol
+
+Simple text-based for now:
+```
+V_bat: 12.45V
+```
+
+Future: structured binary or JSON for multiple sensors.
diff --git a/extra/README.md b/extra/README.md
new file mode 100644
index 0000000..66fe9fb
--- /dev/null
+++ b/extra/README.md
@@ -0,0 +1,51 @@
+# Extra Assets
+
+Runtime assets deployed alongside the Flutter app. Not bundled into the binary — loaded from disk at runtime via paths in `config.json`.
+
+## Structure
+
+```
+extra/
+├── fonts/          # Custom fonts (TTF/OTF)
+├── images/         # Static images
+│   └── navigator/  # Navigator character sprites
+│       └── {name}/ # Folder per navigator (e.g., "zumo", "rei")
+│           ├── default.png
+│           ├── happy.png
+│           ├── surprise.png
+│           └── ...
+└── themes/         # Color theme definitions
+```
+
+## Themes
+
+JSON files defining dark/bright color schemes. Converted to Dart by `scripts/generate_theme.py`.
+
+### Format
+
+```json
+{
+  "dark": {
+    "background": "#101010",
+    "foreground": "#EAEAEA",
+    "highlight": "#FA1504",
+    "subdued": "#E47841"
+  },
+  "bright": {
+    "background": "#E47841",
+    "foreground": "#202020",
+    "highlight": "#F0F0F0",
+    "subdued": "#BC4600"
+  }
+}
+```
+
+### Adding a Theme
+
+1. Create `extra/themes/yournavigator.json`
+2. Set `"navigator": "yournavigator"` in `pi/ui/config.json`
+3. Build — `generate_theme.py` picks it up automatically
+
+### Fallback Chain
+
+`{navigator}.json` → `default.json` → hardcoded defaults
diff --git a/pi/ui/lib/README.md b/pi/ui/lib/README.md
new file mode 100644
index 0000000..0a297b9
--- /dev/null
+++ b/pi/ui/lib/README.md
@@ -0,0 +1,48 @@
+# Flutter App Structure
+
+## Entry Flow
+
+```
+main.dart → AppThemeProvider → MaterialApp → AppRoot → Screen
+```
+
+## Folders
+
+| Folder | Purpose |
+|--------|---------|
+| `screens/` | Full-screen views (splash, dashboard, overheat) |
+| `widgets/` | Reusable components (stat_box, navigator) |
+| `services/` | Singletons with business logic |
+| `theme/` | Color definitions and runtime theme switching |
+
+## Services
+
+All services use singleton pattern with `ServiceName.instance`.
+
+| Service | Role |
+|---------|------|
+| `ConfigService` | Loads `config.json`, exposes settings |
+| `PiIO` | Pi hardware interface (CPU temp, future GPIO) |
+| `OverheatMonitor` | Polls temp, fires callback when threshold exceeded |
+| `ThemeService` | Dark/bright mode state, notifies listeners |
+| `TestFlipFlopService` | Debug: toggles theme + navigator emotion every 2s |
+
+## Theme System
+
+- `AppColors` — static color constants (dark/bright variants), auto-generated from JSON
+- `AppTheme` — InheritedWidget providing runtime colors via `AppTheme.of(context)`
+- `ThemeService` — singleton holding current mode, call `setDarkMode(bool)` or `toggle()`
+
+Usage in widgets:
+```dart
+final theme = AppTheme.of(context);
+backgroundColor: theme.background,
+color: theme.foreground,
+```
+
+## Screen Lifecycle
+
+`AppRoot` manages which screen is visible:
+1. **SplashScreen** — during init sequence
+2. **DashboardScreen** — normal operation
+3. **OverheatScreen** — when `OverheatMonitor` triggers (leads to shutdown)
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..1a5240f
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,62 @@
+# Scripts
+
+Build, deploy, and setup helpers for the Smart Serow project.
+
+## Build & Deploy
+
+| Script | Purpose |
+|--------|---------|
+| `build.py` | Cross-compile Flutter app for ARM64. Runs `generate_theme.py` first. |
+| `deploy.py` | rsync bundle to Pi, optionally restart service |
+| `build-deploy.py` | Convenience wrapper: build → deploy → restart |
+
+```bash
+# Typical workflow
+python3 build.py              # Build only
+python3 deploy.py --restart   # Deploy and restart service
+python3 build-deploy.py       # All-in-one
+
+# Clean rebuild (clears CMake cache)
+python3 build.py --clean
+```
+
+## Theme Generation
+
+| Script | Purpose |
+|--------|---------|
+| `generate_theme.py` | Converts `extra/themes/*.json` → `pi/ui/lib/theme/app_colors.dart` |
+
+Called automatically by `build.py`. Looks for theme matching `navigator` in `config.json`, falls back to `default.json`.
+
+## Pi Setup
+
+| Script | Purpose |
+|--------|---------|
+| `pi_setup.sh` | First-time Pi configuration (deps, permissions, systemd service) |
+| `smartserow-ui.service.sample` | Systemd unit file template |
+
+```bash
+# On the Pi
+chmod +x pi_setup.sh
+./pi_setup.sh
+```
+
+## Configuration
+
+| File | Purpose |
+|------|---------|
+| `deploy_target.sample.json` | Template for deploy settings |
+| `deploy_target.json` | Your actual deploy config (gitignored) |
+
+```json
+{
+  "user": "pi",
+  "host": "raspberrypi.local",
+  "remote_path": "/opt/smartserow",
+  "service_name": "smartserow-ui"
+}
+```
+
+## Shell vs Python
+
+Both `.sh` and `.py` versions exist for some scripts. The Python versions are more robust (better error handling, colored output). Use those.