docs: add CONTRIBUTING.md and update README

Add a contributing guide covering dev setup, testing (unit, frontend,
e2e, hardware integration), linting, branch/commit conventions, the
Vite proxy gotcha for new API endpoints, and fork-based PR workflow.
Point contributors to the Discord #dev channel.

Update README with refreshed content, swap hero image to og-image.jpg,
and link the Contributing section to the new in-repo guide.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CONTRIBUTING.md

@@ -0,0 +1,187 @@
+# Contributing to Dune Weaver
+
+Thanks for your interest in contributing to Dune Weaver! Whether it's a bug fix, a new feature, or improved docs, every contribution helps make kinetic sand tables more accessible.
+
+If you have questions or ideas, join the [#dev channel on Discord](https://discord.com/channels/864079106424832021/1329553521032560791) or browse the existing [Issues](https://github.com/tuanchris/dune-weaver/issues).
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.10+
+- Node.js 18+ and npm
+- Git
+
+### Clone and install
+
+```bash
+git clone https://github.com/tuanchris/dune-weaver.git
+cd dune-weaver
+
+# Python dependencies (use nonrpi on a dev machine, full requirements.txt on a Raspberry Pi)
+pip install -r requirements-nonrpi.txt
+
+# Testing/dev extras
+pip install -r requirements-dev.txt
+
+# Frontend + root dependencies
+npm install
+cd frontend && npm install && cd ..
+```
+
+### Start the dev server
+
+```bash
+npm run dev
+```
+
+This runs **both** servers concurrently:
+
+| Service  | URL                    | Notes                              |
+| -------- | ---------------------- | ---------------------------------- |
+| Frontend | `http://localhost:5173` | Vite dev server with hot reload   |
+| Backend  | `http://localhost:8080` | FastAPI (proxied by Vite in dev)  |
+
+Open `http://localhost:5173` in your browser. Vite proxies all API and WebSocket requests to the backend automatically.
+
+## Project Structure
+
+```
+dune-weaver/
+├── frontend/           # React 19 + TypeScript + Vite
+│   ├── src/
+│   │   ├── pages/      # Route-level page components
+│   │   ├── components/ # Shared UI and feature components
+│   │   ├── hooks/      # Custom React hooks
+│   │   ├── lib/        # Utilities and API client
+│   │   └── contexts/   # React contexts (multi-table, etc.)
+│   └── package.json
+├── modules/            # Backend modules
+│   ├── core/           # Pattern/playlist managers, state, scheduling
+│   ├── connection/     # Serial and WebSocket hardware communication
+│   ├── led/            # WLED integration
+│   └── mqtt/           # MQTT integration
+├── patterns/           # .thr pattern files (theta-rho coordinates)
+├── main.py             # FastAPI application entry point
+└── package.json        # Root scripts (dev, build, prepare)
+```
+
+## Running Tests
+
+### Backend (pytest)
+
+```bash
+pytest tests/unit/ -v
+pytest tests/unit/ -v --cov       # with coverage
+```
+
+### Frontend (Vitest)
+
+```bash
+cd frontend && npm test           # single run
+cd frontend && npm run test:watch # watch mode
+cd frontend && npm run test:coverage
+```
+
+### End-to-end (Playwright)
+
+```bash
+cd frontend && npx playwright install chromium   # first time only
+cd frontend && npm run test:e2e
+cd frontend && npm run test:e2e:ui               # interactive UI mode
+```
+
+### Hardware Integration Tests (pytest)
+
+Integration tests exercise real hardware — serial connections, homing, movement, and pattern execution. They are **skipped by default** and in CI.
+
+```bash
+# Run all integration tests (hardware must be connected via USB)
+pytest tests/integration/ --run-hardware -v
+
+# Run a specific suite
+pytest tests/integration/test_hardware.py --run-hardware -v
+
+# Show live output (useful for watching motor activity)
+pytest tests/integration/ --run-hardware -v -s
+```
+
+| Test file | What it covers | Approx. duration |
+| --------- | -------------- | ---------------- |
+| `test_hardware.py` | Serial connection, homing, movement, pattern execution | ~5–10 min |
+| `test_playback_controls.py` | Pause, resume, stop, skip, speed control | ~5 min |
+| `test_playlist.py` | Playlist modes, clear patterns, state updates | ~5 min |
+
+> **Safety:** These tests physically move the table. Make sure the ball path is clear and the table is powered on before running them.
+
+## Linting
+
+### Python — Ruff
+
+```bash
+ruff check .                # check for issues
+ruff check --fix .          # auto-fix what it can
+```
+
+### Frontend — ESLint
+
+```bash
+cd frontend && npm run lint
+```
+
+### Pre-commit hook
+
+A pre-commit hook runs Ruff on staged Python files and Vitest on staged TypeScript files automatically. It's installed when you run `npm install` at the repo root (via the `prepare` script). You can also install it manually:
+
+```bash
+cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+```
+
+## Branch and Commit Conventions
+
+### Branching
+
+Create branches from `main` using these prefixes:
+
+- `feature/` — new functionality (e.g., `feature/pattern-editor`)
+- `fix/` — bug fixes (e.g., `fix/playlist-reorder`)
+- `chore/` — maintenance, tooling, docs (e.g., `chore/update-deps`)
+
+### Commit messages
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat(ui): add dark mode toggle to settings page
+fix(backend): prevent crash when serial port disconnects
+chore: update Python dependencies
+```
+
+## Adding API Endpoints
+
+When you add a new backend endpoint, you **must** also register its path in the Vite proxy so it works during development:
+
+1. Add the route in `main.py` (or the appropriate module).
+2. Open `frontend/vite.config.ts` and add the endpoint path to the `server.proxy` object:
+   ```ts
+   '/my_new_endpoint': 'http://localhost:8080',
+   ```
+3. Restart the Vite dev server (`npm run dev`).
+
+> **Tip:** Endpoints under the `/api` prefix are already proxied by a single rule, so prefer using `/api/...` paths for new routes.
+
+## Submitting a Pull Request
+
+1. **Fork** the repository and clone your fork.
+2. Create a branch from `main` (see [Branch and Commit Conventions](#branch-and-commit-conventions)).
+3. Make sure all tests pass and linting is clean:
+   ```bash
+   ruff check .
+   cd frontend && npm run lint && npm test && cd ..
+   pytest tests/unit/ -v
+   ```
+4. Push your branch to your fork and open a PR against `main` on the upstream repo.
+5. Fill in a clear description of **what** changed and **why**.
+6. CI will run backend tests, frontend tests, E2E tests, and Ruff lint automatically.
+
+Thanks for helping make Dune Weaver better!

README.md

@@ -1,192 +1,102 @@
 # Dune Weaver
 
-[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/tuanchris)
+[![Patreon](https://img.shields.io/badge/Patreon-F96854?style=for-the-badge&logo=patreon&logoColor=white)](https://www.patreon.com/cw/DuneWeaver)
 
-![Dune Weaver Gif](./static/IMG_7404.gif)
+![Dune Weaver](./static/og-image.jpg)
 
-Dune Weaver is a web-controlled kinetic sand table system that creates mesmerizing patterns in sand using a steel ball guided by magnets beneath the surface. This project seamlessly integrates hardware control with a modern web interface, featuring real-time pattern execution, playlist management, and synchronized lighting effects.
+**An open-source kinetic sand art table that creates mesmerizing patterns using a ball controlled by precision motors.**
 
-## 🌟 Key Features
+## Features
 
-- **Web-Based Control Interface**: Modern, responsive web UI for pattern management and table control
-- **Real-Time Pattern Execution**: Live preview and control of pattern drawing with progress tracking
-- **Playlist System**: Queue multiple patterns for continuous execution
-- **WLED Integration**: Synchronized lighting effects during pattern execution
-- **Pattern Library**: Browse, upload, and manage custom patterns with preview generation
-- **Polar Coordinate System**: Specialized θ-ρ coordinate system optimized for radial designs
-- **Auto-Update System**: GitHub-integrated version management with update notifications
+- **Modern React UI** — A responsive, touch-friendly web interface that installs as a PWA on any device
+- **Pattern Library** — Browse, upload, and manage hundreds of sand patterns with auto-generated previews
+- **Live Preview** — Watch your pattern come to life in real time with progress tracking
+- **Playlists** — Queue up multiple patterns with configurable pause times and automatic clearing between drawings
+- **LED Integration** — Synchronized lighting via native DW LEDs or WLED, with separate idle, playing, and scheduled modes
+- **Still Sands Scheduling** — Set quiet hours so the table pauses automatically on your schedule
+- **Multi-Table Support** — Control several sand tables from a single interface
+- **Home Assistant Integration** — Connect to Home Assistant or other home automation systems using MQTT
+- **Auto-Updates** — One-click software updates right from the settings page
+- **Add-Ons** — Optional [Desert Compass](https://duneweaver.com/docs) for auto-homing and [DW Touch](https://duneweaver.com/docs) for dedicated touchscreen control
 
-### **📚 Complete Documentation: [Dune Weaver Wiki](https://github.com/tuanchris/dune-weaver/wiki)**
+## How It Works
 
----
-
-The Dune Weaver comes in two versions:
-
-1. **Small Version (Mini Dune Weaver)**:
-   - Uses two **28BYJ-48 DC 5V stepper motors**.
-   - Controlled via **ULN2003 motor drivers**.
-   - Powered by an **ESP32**.
-
-2. **Larger Version (Dune Weaver)**:
-   - Uses two **NEMA 17 or NEMA 23 stepper motors**.
-   - Controlled via **TMC2209 or DRV8825 motor drivers**.
-   - Powered by an **Arduino UNO with a CNC shield**.
-
-Each version operates similarly but differs in power, precision, and construction cost.
-
-The sand table consists of two main bases:
-1. **Lower Base**: Houses all the electronic components, including motor drivers, and power connections.
-2. **Upper Base**: Contains the sand and the marble, which is moved by a magnet beneath.
-
-Both versions of the table use two stepper motors:
-
-- **Radial Axis Motor**: Controls the in-and-out movement of the arm.
-- **Angular Axis Motor**: Controls the rotational movement of the arm.
+The system is split across two devices connected via USB:
 
-The small version uses **28BYJ-48 motors** driven by **ULN2003 drivers**, while the larger version uses **NEMA 17 or NEMA 23 motors** with **TMC2209 or DRV8825 drivers**.: Controls the in-and-out movement of the arm.
-- **Angular Axis Motor**: Controls the rotational movement of the arm.
+```
+┌─────────────────┐         USB          ┌─────────────────┐
+│  Raspberry Pi   │ ◄──────────────────► │  DLC32 / ESP32  │
+│  (Dune Weaver   │                      │  (FluidNC)      │
+│   Backend)      │                      │                 │
+└─────────────────┘                      └─────────────────┘
+        │                                        │
+        │ Wi-Fi                                  │ Motor signals
+        ▼                                        ▼
+   Web Browser                            Stepper Motors
+   (Control UI)                           (Theta & Rho)
+```
 
-Each motor is connected to a motor driver that dictates step and direction. The motor drivers are, in turn, connected to the ESP32 board, which serves as the system's main controller. The entire table is powered by a single USB cable attached to the ESP32.
+The **Raspberry Pi** runs the web UI, manages pattern files and playlists, and converts patterns into G-code. The **DLC32/ESP32** running [FluidNC](https://github.com/bdring/FluidNC) firmware receives that G-code and drives the stepper motors in real time.
 
----
+## Hardware
 
-## Coordinate System
-Unlike traditional CNC machines that use an **X-Y coordinate system**, the sand table operates on a **theta-rho (θ, ρ) coordinate system**:
-- **Theta (θ)**: Represents the angular position of the arm, with **2π radians (360 degrees) for one full revolution**.
-- **Rho (ρ)**: Represents the radial distance of the marble from the center, with **0 at the center and 1 at the perimeter**.
+Dune Weaver comes in three premium models:
 
-This system allows the table to create intricate radial designs that differ significantly from traditional Cartesian-based CNC machines.
+| | [DW Pro](https://duneweaver.com/products/dwp) | [DW Mini Pro](https://duneweaver.com/products/dwmp) | [DW Gold](https://duneweaver.com/products/dwg) |
+|---|---|---|---|
+| **Size** | 75 cm (29.5") | 25 cm (10") | 45 cm (17") |
+| **Enclosure** | IKEA VITTSJÖ table | IKEA BLANDA bowl | IKEA TORSJÖ side table |
+| **Motors** | 2 × NEMA 17 | 2 × NEMA 17 | 2 × NEMA 17 |
+| **Controller** | DLC32 | DLC32 | DLC32 |
+| **Best for** | Living rooms | Desktops | Side-table accent piece |
 
----
+All models run the same software with [FluidNC](https://github.com/bdring/FluidNC) firmware — only the mechanical parts differ.
 
-## Homing and Position Tracking
-Unlike conventional CNC machines, the sand table **does not have a limit switch** for homing. Instead, it uses a **crash-homing method**:
-1. Upon power-on, the radial axis moves inward to its physical limit, ensuring the marble is positioned at the center.
-2. The software then assumes this as the **home position (0,0 in polar coordinates)**.
-3. The system continuously tracks all executed coordinates to maintain an accurate record of the marble’s position.
+Free 3D-printable models on MakerWorld: [DW OG](https://makerworld.com/en/models/841332-dune-weaver-a-3d-printed-kinetic-sand-table#profileId-787553) · [DW Mini](https://makerworld.com/en/models/896314-mini-dune-weaver-not-your-typical-marble-run#profileId-854412)
 
----
-
-## Mechanical Constraints and Software Adjustments
-### Coupled Angular and Radial Motion
-Due to the **hardware design choice**, the angular axis **does not move independently**. This means that when the angular motor moves one full revolution, the radial axis **also moves slightly**—either inwards or outwards, depending on the rotation direction.
+> **Build guides, BOMs, and wiring diagrams** are in the [Dune Weaver Docs](https://duneweaver.com/docs).
 
-To counteract this behavior, the software:
-- Monitors how many revolutions the angular axis has moved.
-- Applies an offset to the radial axis to compensate for unintended movements.
+## Quick Start
 
-This correction ensures that the table accurately follows the intended path without accumulating errors over time.
+The fastest way to get running on a Raspberry Pi:
 
----
-
-Each pattern file consists of lines with theta and rho values (in degrees and normalized units, respectively), separated by a space. Comments start with #.
-
-Example:
-
-```
-# Example pattern
-0 0.5
-90 0.7
-180 0.5
-270 0.7
+```bash
+curl -fsSL https://raw.githubusercontent.com/tuanchris/dune-weaver/main/setup-pi.sh | bash
 ```
 
-## API Endpoints
-
-The project exposes RESTful APIs for various actions. Here are some key endpoints:
- • List Serial Ports: /list_serial_ports (GET)
- • Connect to Serial: /connect (POST)
- • Upload Pattern: /upload_theta_rho (POST)
- • Run Pattern: /run_theta_rho (POST)
- • Stop Execution: /stop_execution (POST)
-
-## 🚀 Quick Start
-
-1. **Clone the repository**:
-   ```bash
-   git clone https://github.com/tuanchris/dune-weaver.git
-   cd dune-weaver
-   ```
+This installs Docker, clones the repo, and starts the application. Once it finishes, open **http://\<hostname\>.local** in your browser.
 
-2. **Install dependencies**:
+For full deployment options (Docker, manual install, development setup, Windows, and more), see the **[Deploying Backend](https://duneweaver.com/docs/deploying-backend)** guide.
 
-   **On Raspberry Pi (full hardware support):**
-   ```bash
-   pip install -r requirements.txt
-   npm install
-   ```
+### Polar coordinates
 
-   **On Windows/Linux/macOS (development/testing):**
-   ```bash
-   pip install -r requirements-nonrpi.txt
-   npm install
-   ```
-   > **Note**: The development installation excludes Raspberry Pi GPIO libraries. The application will run fully but DW LED features will be disabled. WLED integration will still work.
+The sand table uses **polar coordinates** instead of the typical X-Y grid:
 
-3. **Build CSS**:
-   ```bash
-   npm run build-css
-   ```
+- **Theta (θ)** — the angle in radians (2π = one full revolution)
+- **Rho (ρ)** — the distance from the center (0.0 = center, 1.0 = edge)
 
-4. **Start the application**:
-   ```bash
-   python main.py
-   ```
-
-5. **Open your browser** and navigate to `http://localhost:8080`
-
-## 📁 Project Structure
+Patterns are stored as `.thr` text files — one coordinate pair per line:
 
 ```
-dune-weaver/
-├── main.py                     # FastAPI application entry point
-├── VERSION                     # Current software version
-├── modules/
-│   ├── connection/             # Serial & WebSocket connection management
-│   ├── core/                   # Core business logic
-│   │   ├── cache_manager.py    # Pattern preview caching
-│   │   ├── pattern_manager.py  # Pattern file handling
-│   │   ├── playlist_manager.py # Playlist system
-│   │   ├── state.py           # Global state management
-│   │   └── version_manager.py  # GitHub version checking
-│   ├── led/                    # WLED integration
-│   ├── mqtt/                   # MQTT support
-│   └── update/                 # Software update management
-├── patterns/                   # Pattern files (.thr format)
-├── static/                     # Web assets (CSS, JS, images)
-├── templates/                  # HTML templates
-├── firmware/                   # Hardware controller firmware
-└── requirements.txt            # Python dependencies
+# A simple four-point star
+0.000 0.5
+1.571 0.7
+3.142 0.5
+4.712 0.7
 ```
 
-## 🔧 Configuration
-
-The application uses several configuration methods:
-- **Environment Variables**: `LOG_LEVEL`, connection settings
-- **State Persistence**: Settings saved to `state.json`
-- **Version Management**: Automatic GitHub release checking
-
-## 🌐 API Endpoints
+The same pattern file works on any table size thanks to the normalized coordinate system. You can create patterns by hand, generate them with code, or browse the built-in library.
 
-Core API endpoints for integration:
+## Documentation
 
-- **Pattern Management**: `/upload_theta_rho`, `/list_theta_rho_files`
-- **Execution Control**: `/run_theta_rho`, `/pause_execution`, `/stop_execution`
-- **Hardware Control**: `/connect`, `/send_home`, `/set_speed`
-- **Version Management**: `/api/version`, `/api/update`
-- **Real-time Updates**: WebSocket at `/ws/status`
+Full setup instructions, hardware assembly, firmware flashing, and advanced configuration:
 
-## 🤝 Contributing
+**[Dune Weaver Docs](https://duneweaver.com/docs)**
 
-We welcome contributions! Please check out our [Contributing Guide](https://github.com/tuanchris/dune-weaver/wiki/Contributing) for details.
+## Contributing
 
-## 📖 Documentation
-
-For detailed setup instructions, hardware assembly, and advanced configuration:
-
-**🔗 [Visit the Complete Wiki](https://github.com/tuanchris/dune-weaver/wiki)**
+We welcome contributions! See the [Contributing Guide](CONTRIBUTING.md) for how to get started.
 
 ---
 
-**Happy sand drawing with Dune Weaver! ✨**
-
+**Happy sand drawing!**