Prune README and add comprehensive documentation

README reduced to essentials: install, quick start, and links to docs/.
New docs/ covers Overview, Installation, Usage Guide, and Tips and Tricks.

docs/Installation.md

@@ -0,0 +1,157 @@
+# Installation
+
+This guide covers installing NVCurve from source, including building the frontend.
+
+## Prerequisites
+
+Make sure your system has the following before proceeding:
+
+- **Linux** (any distribution)
+- **NVIDIA GPU** with proprietary drivers installed
+- **Python 3.12+**
+- **Node.js 18+** and **pnpm** (for frontend development)
+- **Root/sudo access** (required for hardware interactions)
+
+## Quick Install (Pre-built)
+
+The recommended way to install NVCurve for end-use is via [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install nvcurve
+```
+
+This installs the CLI tool with the pre-built frontend bundled inside. After installation, verify everything works:
+
+```bash
+nvcurve setup
+```
+
+## Installation from Source
+
+Building from source is necessary if you want to modify the frontend, contribute to the project, or run a development build.
+
+### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/your-username/nvcurve.git
+cd nvcurve
+```
+
+### Step 2: Set Up the Python Environment
+
+Create a virtual environment and install the Python dependencies:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Or if you use `uv`:
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+```
+
+### Step 3: Build the Frontend
+
+The frontend is a React + TypeScript + Vite application located in the `frontend/` directory.
+
+Navigate to the frontend directory and install its dependencies:
+
+```bash
+cd frontend
+pnpm install
+```
+
+Build the production bundle:
+
+```bash
+pnpm run build
+```
+
+This produces a `dist/` directory containing the compiled static assets. The hatch build system automatically includes `frontend/dist` in the Python package under `nvcurve/frontend/dist`.
+
+### Step 4: Reinstall the Python Package
+
+After building the frontend, reinstall the Python package so it picks up the new frontend assets:
+
+```bash
+cd ..
+pip install -e .
+```
+
+### Step 5: Verify the Installation
+
+Run the hardware compatibility check:
+
+```bash
+nvcurve setup
+```
+
+This performs four checks:
+1. **NvAPI function probe** — verifies all required functions resolve in your driver
+2. **Curve read** — reads and displays your current V/F curve as a baseline
+3. **Write-verify** — writes `+5 MHz` to a safe point, reads it back, and confirms the change
+4. **Restore** — automatically restores the state from before the test write
+
+If `setup` reports **Compatible**, you're ready to go.
+
+## Frontend Development Mode
+
+For active frontend development, run the Vite dev server instead of building:
+
+```bash
+cd frontend
+pnpm run dev
+```
+
+This starts a hot-reload development server. The backend server runs separately:
+
+```bash
+# In another terminal
+nvcurve serve start
+```
+
+## Upgrading
+
+### Pre-built Install
+
+```bash
+uv tool upgrade nvcurve
+```
+
+If you're running NVCurve as a systemd service, restart it after upgrading:
+
+```bash
+nvcurve service restart
+```
+
+### Source Install
+
+```bash
+git pull
+pip install -e .
+cd frontend && pnpm install && pnpm run build
+cd .. && pip install -e .
+```
+
+## Troubleshooting
+
+### `nvcurve` command not found
+
+Ensure your virtual environment is activated, or that the package installation directory is on your `PATH`.
+
+### Frontend not loading in the web UI
+
+Verify that `frontend/dist` exists and contains built assets. If the directory is empty or missing, rebuild with `pnpm run build` and reinstall the Python package.
+
+### NvAPI functions not found
+
+Your NVIDIA driver may not expose the required undocumented functions. Try updating to the latest driver version. Run `nvcurve read --diag` for detailed diagnostics.
+
+### Permission denied on hardware operations
+
+All hardware-interacting commands require root. The CLI will automatically escalate via `sudo` when needed. If `sudo` is not configured for your user, run commands with `sudo` explicitly.

docs/Overview.md

@@ -0,0 +1,47 @@
+# NVCurve
+
+NVCurve is a Linux-based voltage-frequency (V/F) curve editor and overclocking tool for NVIDIA GPUs. It brings per-point V/F curve control — similar to MSI Afterburner on Windows — directly to Linux, using undocumented NvAPI functions exposed through `libnvidia-api.so`.
+
+## What It Does
+
+At its core, NVCurve lets you adjust the frequency offset for any voltage point on your GPU's V/F curve. This gives you fine-grained control over how your GPU clocks at different voltage levels, enabling both performance-oriented overclocking and efficiency-oriented undervolting.
+
+## Two Interfaces, One Tool
+
+NVCurve provides two ways to interact with your GPU:
+
+- **Web UI** — A modern React-based interface with an interactive curve graph, real-time hardware monitoring, point table editor, and profile management. This is the primary interface for most users.
+- **CLI** — A Python command-line tool for scripting, headless systems, automation, and quick one-off operations. Works independently of the web server.
+
+## Key Capabilities
+
+- **Per-Point Curve Editing** — Adjust the frequency offset for any individual voltage point on the V/F curve.
+- **Curve Flattening** — Select multiple points and flatten them to a common frequency using anchor-point targeting.
+- **Live Monitoring** — Track GPU voltage, clock speed, temperature, and power draw in real time via NvAPI and NVML.
+- **Profile Management** — Save, load, and switch between named profiles. Set a default profile that auto-applies on startup.
+- **Multi-GPU Support** *(experimental)* — Manage multiple NVIDIA GPUs from a single server instance with a GPU selector in the web UI.
+- **Snapshots** — Automatic snapshot-and-restore before every write, so you can always revert changes.
+
+## Architecture
+
+NVCurve consists of two components:
+
+| Component | Description |
+|---|---|
+| **Python Backend** | Talks directly to `libnvidia-api.so` (via ctypes) and `libnvidia-ml.so` to read and write GPU hardware state. Exposes functionality through a FastAPI REST + WebSocket server. |
+| **React Frontend** | Runs in the browser and communicates with the backend over HTTP and WebSockets. Handles curve visualization, point editing, live monitoring, and profile management. |
+
+The backend keeps all privileged operations isolated from the browser. The CLI can operate entirely standalone, bypassing the server for direct hardware access.
+
+## Important Notes
+
+> **Experimental Software** — NVCurve uses undocumented NvAPI functions that may change between driver releases. It has been tested on a range of NVIDIA GPUs including RTX 5090 (Blackwell), but compatibility is not guaranteed on all hardware/driver combinations.
+
+> **Read vs. Write Safety** — Read operations are generally safe. Write operations alter live GPU operational parameters. Always run the hardware compatibility check (`nvcurve setup`) before applying changes.
+
+## Requirements
+
+- **OS**: Linux
+- **GPU**: NVIDIA GPU with a supported driver
+- **Python**: 3.12 or later
+- **Privileges**: Root access for hardware interactions (CLI prompts for `sudo` when needed)

docs/Tips and Tricks.md

@@ -0,0 +1,144 @@
+# Tips and Tricks
+
+Practical tips, workflows, and techniques for getting the most out of NVCurve.
+
+## Understanding the V/F Curve
+
+The voltage-frequency curve defines how your GPU clocks at different voltage levels. Each point on the curve represents a (frequency, voltage) pair. NVCurve lets you add a frequency offset to each point, effectively shifting where your GPU operates.
+
+- **Positive offsets** increase clock speed at a given voltage (overclocking).
+- **Negative offsets** reduce clock speed at a given voltage, which can enable undervolting (lower voltage for the same performance, or same voltage at lower clocks for efficiency).
+
+## Start Small, Test Often
+
+When experimenting with offsets:
+
+1. Use `--dry-run` to preview changes before applying them:
+   ```bash
+   nvcurve write --global --delta 25 --dry-run
+   ```
+2. Apply small increments (10–25 MHz) and test stability between each step.
+3. Use snapshots to roll back: `nvcurve snapshot restore`.
+
+## The Global Offset Shortcut
+
+If all active points share the same delta, the **Global Offset** slider appears in the web UI toolbar. This is equivalent to `nvcurve write --global` but gives you interactive control. Drag the slider to stage a uniform offset across every point, then click Apply.
+
+## Curve Flattening for Efficiency
+
+Curve flattening is a powerful technique for efficiency-oriented tuning:
+
+1. Select a group of points in the upper voltage range.
+2. Click **Flatten to [anchor]** in the toolbar.
+3. This sets each selected point to land on the same effective frequency as your anchor point.
+
+The result is a "step" in your curve where multiple voltage points map to the same clock — useful for finding the sweet spot where your GPU delivers peak frequency with minimal voltage.
+
+## Keyboard-Driven Workflow
+
+For precise tuning, the keyboard shortcuts in the curve editor are your friend:
+
+- **Arrow keys** nudge selected point(s) by ±1 MHz.
+- **Ctrl/Cmd + arrow keys** nudge by ±10 MHz.
+- **Tab / Shift+Tab** steps selection through points one by one.
+- **Enter** opens inline input for exact values.
+
+This lets you make surgical adjustments without reaching for the mouse.
+
+## Profile Strategy
+
+A good profile setup covers your common use cases:
+
+| Profile | Purpose |
+|---|---|
+| `gaming` | Aggressive positive offsets for maximum performance |
+| `balanced` | Mild offsets for a good performance/temperature tradeoff |
+| `efficient` | Negative offsets or flattened curve for low power usage |
+| `stock` | Zero offsets (baseline for comparison) |
+
+Set your preferred profile as the default so it auto-applies on boot:
+
+```bash
+nvcurve profile default gaming
+```
+
+## LACT Conflict
+
+If you use LACT (Linux Auto-Clock Tuner) or similar tools, they will conflict with NVCurve because both write to the same hardware registers.
+
+**Before using NVCurve with a default profile:**
+
+```bash
+sudo systemctl disable --now lactd
+```
+
+Otherwise, `lactd` will apply its own curve on startup and overwrite NVCurve's auto-applied profile.
+
+## Multi-GPU Considerations
+
+In multi-GPU setups:
+
+- Each GPU maintains its own isolated state (write lock, active profile, monitoring).
+- Use `--gpu N` to target a specific GPU from the CLI.
+- In the web UI, switch GPUs using the dropdown in the status bar.
+- Set per-GPU default profiles:
+  ```bash
+  nvcurve --gpu 0 profile default gaming
+  nvcurve --gpu 1 profile default efficient
+  ```
+
+## Diagnostics Before Troubleshooting
+
+When something isn't working right, run diagnostics first:
+
+```bash
+nvcurve read --diag
+```
+
+This shows:
+- GPU name and driver version
+- VRAM totals
+- All NvAPI function probe results
+- Current clock offsets and memory offset ranges
+- Power limits
+
+Use `nvcurve inspect` to examine raw ClockBoostTable fields for specific points:
+
+```bash
+nvcurve inspect --point 80
+nvcurve inspect --range 78-82
+```
+
+## Headless / Scripting Workflow
+
+For headless systems or automation, the CLI is fully self-contained:
+
+```bash
+#!/bin/bash
+# Example: Apply a profile, run a benchmark, then restore
+
+nvcurve profile apply gaming
+./my-benchmark.sh
+nvcurve snapshot restore
+```
+
+All CLI commands that interact with hardware automatically escalate to root via `sudo`. The `--json` flag on `nvcurve read` makes it easy to parse output in scripts.
+
+## Safety Limits
+
+NVCurve enforces safety limits to prevent damage:
+
+- **Max delta cap**: ±3000 MHz hard limit per point.
+- **Auto-snapshot**: A snapshot is saved before every write (configurable).
+- **Negative frequency warnings**: The tool warns if an offset would result in a negative effective frequency.
+
+These safeguards are in place, but remember — you're writing to undocumented hardware registers. Always test stability after applying changes and monitor temperatures.
+
+## Background Daemon vs. Web Server
+
+NVCurve has two running components to understand:
+
+- **Daemon** (`nvcurve daemon`) — Lightweight Unix socket daemon that handles auto-loading profiles on boot. Managed via `nvcurve service`.
+- **Web server** (`nvcurve serve`) — FastAPI REST + WebSocket server for the web UI. Starts on demand.
+
+The systemd service (`nvcurve service install`) manages the daemon. The web server is optional and starts separately. Use `--auto-serve` at service install time if you want the web server to auto-start on boot as well.

docs/Usage Guide.md

@@ -0,0 +1,206 @@
+# Usage Guide
+
+This guide covers the day-to-day use of NVCurve, from launching the web UI to managing profiles and using the CLI.
+
+## First-Time Setup
+
+Before using NVCurve, always run the hardware compatibility check:
+
+```bash
+nvcurve setup
+```
+
+This verifies that your GPU and driver support the required NvAPI functions, performs a safe test write, and restores your GPU to its original state. Only proceed if the result is **Compatible**.
+
+## Web UI
+
+The web UI is the primary interface for curve editing and monitoring.
+
+### Launching the Web UI
+
+```bash
+nvcurve
+```
+
+This starts the backend server and opens your browser at `http://127.0.0.1:8042`.
+
+### Server Management
+
+```bash
+nvcurve serve start          # Start the web server
+nvcurve serve start --detach # Start in the background
+nvcurve serve status         # Check if the server is running
+nvcurve serve stop           # Stop the server
+```
+
+### Curve Editor
+
+The curve editor displays your GPU's V/F curve as an interactive graph with draggable points.
+
+| Action | How |
+|---|---|
+| Select a point | Click on it |
+| Multi-select | Shift+click to add/remove points |
+| Select all active points | Ctrl/Cmd+A |
+| Clear selection | Escape |
+| Edit a point | Drag it to stage a frequency offset |
+| Move multiple points | Drag with multiple points selected |
+| Exact value input | Select one point, press Enter |
+| Nudge ±1 MHz | Arrow keys (↑ / ↓) |
+| Nudge ±10 MHz | Ctrl/Cmd + arrow keys |
+| Step through points | Tab / Shift+Tab |
+| Box select | Shift+drag on the background |
+| Pan the graph | Drag on the background |
+| Zoom | Alt+scroll |
+
+### Point Table
+
+The point table provides a spreadsheet-like view of all curve points with their frequency, voltage, and offset values.
+
+| Action | How |
+|---|---|
+| Select a point | Click a row |
+| Toggle selection | Ctrl/Cmd+click |
+| Range select | Shift+click or drag across rows |
+| Select before/after | Click "Select Before" or "Select After" (appears for single selection) |
+
+### Toolbar
+
+The toolbar provides bulk operations:
+
+- **Global Offset Slider** — Appears when all active points share a uniform delta. Adjusts every point simultaneously.
+- **Flatten** — When two or more points are selected, flattens them to the anchor point's frequency. The anchor is the last explicitly clicked point (highlighted with an amber halo).
+- **Apply** — Commits staged changes to the GPU.
+- **Reset** — Clears all offsets back to zero.
+
+### Live Monitoring
+
+The monitoring panel shows real-time GPU metrics:
+
+- Voltage
+- Clock speed
+- Temperature
+- Power draw
+
+Data is streamed via WebSocket from the backend at a configurable poll interval (default: 1 second).
+
+### Multi-GPU
+
+When multiple NVIDIA GPUs are detected, a GPU selector dropdown appears in the status bar. Switching GPUs resets pending edits, selection state, and monitoring for the new target.
+
+## CLI Reference
+
+The CLI is designed for scripting, headless use, and quick operations. All write commands support `--dry-run` to preview changes.
+
+### Reading the Curve
+
+```bash
+nvcurve read                  # Condensed V/F curve
+nvcurve read --full           # All points including zeros
+nvcurve read --json           # JSON output for scripting
+```
+
+### Writing Offsets
+
+```bash
+# Preview changes without applying
+nvcurve write --global --delta 50 --dry-run
+nvcurve write --point 80 --delta 100 --dry-run
+
+# Apply changes
+nvcurve write --global --delta 50        # All active GPU points
+nvcurve write --point 80 --delta 100     # Single point
+nvcurve write --range 70-90 --delta 75   # Range of points
+nvcurve write --reset                    # Reset all to zero
+```
+
+> If you use LACT or similar tools, disable them before writing. Concurrent writes will overwrite each other.
+
+### Snapshots
+
+Snapshots are saved automatically before every write. You can also manage them manually:
+
+```bash
+nvcurve snapshot save
+nvcurve snapshot list
+nvcurve snapshot restore
+```
+
+Snapshots are stored in `/var/cache/nvcurve/snapshots`.
+
+### Profiles
+
+Profiles save a named set of curve offsets (plus optional memory offset and power limit settings). Profile commands work whether or not the server is running.
+
+```bash
+nvcurve profile save my_profile        # Save current curve state
+nvcurve profile apply my_profile       # Apply a saved profile
+nvcurve profile list                   # List all profiles
+nvcurve profile default my_profile     # Set as auto-load on startup
+nvcurve profile default --clear        # Clear auto-load setting
+```
+
+Profiles are stored as JSON files in `/etc/nvcurve/profiles`.
+
+### Diagnostics
+
+```bash
+nvcurve read --diag                     # Full NvAPI function probe + system info
+nvcurve inspect --point 80              # Raw ClockBoostTable fields
+nvcurve inspect --range 78-82           # Inspect a range of points
+nvcurve gpus                            # List detected GPUs
+```
+
+### Global Arguments
+
+The `--gpu N` flag can be placed before or after any subcommand to target a specific GPU in multi-GPU setups:
+
+```bash
+nvcurve --gpu 1 read
+nvcurve read --gpu 1
+nvcurve --gpu 1 profile default perf
+```
+
+## Systemd Service
+
+Install NVCurve as a systemd service for automatic profile loading on boot:
+
+### Install
+
+```bash
+nvcurve service install
+```
+
+With optional web server auto-start:
+
+```bash
+nvcurve service install --auto-serve --host 0.0.0.0 --port 8042
+```
+
+### Manage
+
+```bash
+nvcurve service start
+nvcurve service stop
+nvcurve service restart
+nvcurve service status
+nvcurve service uninstall
+```
+
+### Reconfigure
+
+```bash
+sudo nvcurve service configure --auto-serve
+sudo nvcurve service configure --no-auto-serve
+sudo nvcurve service configure --host 0.0.0.0 --port 8042
+```
+
+## Configuration Files
+
+| File | Purpose |
+|---|---|
+| `/etc/nvcurve/config.json` | Persistent config (host, port, auto-serve, default profiles) |
+| `/etc/nvcurve/profiles/*.json` | Saved profiles |
+| `/var/cache/nvcurve/snapshots/` | Auto-saved snapshots before writes |
+| `/run/nvcurve.json` | Runtime server info (host, port, PID) |
+| `/etc/systemd/system/nvcurve.service` | Systemd unit file |