From 9fc6809f974a2bd97e2108e7733ac4bcfd03392f Mon Sep 17 00:00:00 2001
From: Kareem Horstink <kareem@horstink.me>
Date: Fri, 3 Jul 2026 08:33:44 +0000
Subject: [PATCH] Update README and docs for settings page, PIN manager, and
 auto-config

- README: Added settings page, secure PIN/token, auto-config, startup scripts
- configuration-design.md: Documented PIN system, API token, auto-config, settings page
- Updated architecture diagram references
---
 README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 60 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index c8beae1..06cf51c 100644
--- a/README.md
+++ b/README.md
@@ -68,15 +68,18 @@ flowchart TD
 - **Hardware Telemetry** — CPU/GPU core temps, VRAM usage from HWiNFO64
 - **Hardware Fallbacks** — Startup check reports which subsystems are available/unavailable
 - **Custom Notifications** — External scripts can push progress bars or rich text alerts via `POST /api/v1/notify`
-- **Settings Screen** — Change PIN and API token via the web client (protected by API token)
+- **Settings Page** — Localhost-only web UI at `/settings` (accessed via tray icon) to edit PIN, token, host, port, log level, and PIN TTL
+- **Secure PIN System** — 6-digit codes with 5-minute TTL, single-use, auto-generated on startup
+- **Cryptographic API Token** — 256-bit entropy via `secrets.token_urlsafe(32)`
+- **Auto-Configuration** — `config.yaml` created automatically on first run with detected local IP
 - **Configuration Files** — Use `config.yaml`, `.env`, or environment variables
 - **E-Ink Optimized UI** — High-contrast styling, discrete zone gestures, minimal refresh
-- **System Tray .exe** — Runs unobtrusively in the Windows notification bar with a quit option
+- **System Tray .exe** — Runs unobtrusively in the Windows notification bar with Settings and Quit options
 
 ## Authentication
 
-1. **Dashboard UI (Boox Tablet):** Shared PIN authentication via WebSocket handshake (`?pin=XXXX`)
-2. **External Scripts/CLI:** Static Bearer Token via `Authorization: Bearer <SECRET_TOKEN>` header
+1. **Dashboard UI (Boox Tablet):** Time-limited PIN authentication via WebSocket handshake (`?pin=XXXX`). PINs are 6-digit, expire after 5 minutes (configurable), and can only be used once.
+2. **External Scripts/CLI:** Cryptographic Bearer Token via `Authorization: Bearer <SECRET_TOKEN>` header (32 bytes / 256 bits of entropy)
 
 ## Project Structure
 
@@ -88,12 +91,17 @@ e-ink-dash/
 ├── server/                # Python FastAPI server
 │   ├── main.py            # Application entry point
 │   ├── config.py          # Configuration management (YAML/.env/env vars)
+│   ├── pin_manager.py     # Time-limited single-use PIN generation
 │   ├── audio_mixer.py     # Audio mixer abstraction (Windows + Voicemeeter)
 │   ├── media.py           # Media playback tracking (GSMTC)
 │   ├── notifications.py   # Notification system (progress + alerts)
 │   ├── telemetry.py       # Hardware telemetry (HWiNFO)
 │   ├── tray_wrapper.py    # System tray .exe wrapper
+│   ├── settings.html      # Settings page (localhost-only)
+│   ├── settings.css       # Settings page stylesheet
 │   ├── build_exe.py       # PyInstaller build script
+│   ├── start.bat          # Windows development startup
+│   ├── start.sh           # Linux/macOS development startup
 │   ├── .env.example       # Example environment file
 │   ├── requirements.txt
 │   └── tests/             # Test suite
@@ -108,7 +116,23 @@ e-ink-dash/
 
 ## Getting Started
 
-### Server
+### Quick Start (Development)
+
+```bash
+cd server
+python start.bat    # Windows
+# or
+bash start.sh       # Linux/macOS
+```
+
+The scripts create a venv, install dependencies, and start the server. On first run, `config.yaml` is auto-generated with:
+
+- A random 6-digit PIN (logged to console)
+- A random API token (logged to console)
+- Detected local IP address
+- Default port 8921
+
+### Manual Setup
 
 ```bash
 cd server
@@ -121,24 +145,50 @@ python -m uvicorn main:app --host 0.0.0.0 --port 8921
 Configure via one of:
 
 1. **Environment variables:**
-   - `DASHBOARD_PIN` — 4-digit PIN for the E-Ink client
+   - `DASHBOARD_PIN` — (optional, auto-generated if missing)
    - `API_TOKEN` — Bearer token for external scripts
+   - `PIN_TTL` — PIN expiration in seconds (default: 300)
+   - `HOST` — Server bind address (default: detected local IP)
+   - `PORT` — Server port (default: 8921)
+   - `LOG_LEVEL` — Logging level (default: INFO)
 
 2. **`.env` file** (in project root or exe directory):
 
    ```
-   DASHBOARD_PIN=1234
    API_TOKEN=your-token-here
+   PIN_TTL=300
+   HOST=192.168.1.100
+   PORT=8921
+   LOG_LEVEL=INFO
    ```
 
-3. **`config.yaml`** (in project root or exe directory):
+3. **`config.yaml`** (auto-created on first run, or manually):
 
    ```yaml
-   dashboard_pin: "1234"
    api_token: "your-token-here"
+   pin_ttl: 300
+   host: "192.168.1.100"
+   port: 8921
+   log_level: "INFO"
    ```
 
-See `.env.example` and `config.yaml.example` for reference.
+### Settings Page
+
+Access the settings UI via the system tray icon → **Settings**. This opens `http://127.0.0.1:8921/settings` in your browser.
+
+**Available only from localhost** — you must be on the PC running PaperDash.
+
+Edit: PIN, API token, host, port, log level, and PIN TTL. Changes are saved to `config.yaml` and take effect on next restart.
+
+### Build .exe
+
+```bash
+cd server
+python build_exe.py
+# Output: server/dist/PaperDash.exe
+```
+
+The `.exe` bundles `settings.html` and `settings.css` for the settings page.
 
 ### Build .exe