diff --git a/README.md b/README.md
index a05b21d..30870d5 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,141 @@
-# ScratchingPost
+# Scratching Post — Sunbeam Digital Signage
 
-Sunbeam Digital Signage — A self-hosted notice board system for IIS. WYSIWYG slides, embeds, ICS calendars, device playlists.
\ No newline at end of file
+A self-hosted digital notice board / signage system built on ASP.NET Core 8, designed for IIS on Windows Server 2019/2022.
+
+## Terminology
+
+| Component | Name | Description |
+|-----------|------|-------------|
+| Individual slide | **Meow** | A single content slide — WYSIWYG, embed, or calendar |
+| Slide collection | **PURR** | Persistent User Requests and Reminders — a device playlist |
+| Priority slide | **ASK** | Attention Seeking Kitty — overrides collection order *(planned)* |
+| Display node | **Kitten** | A device that plays a playlist of Meows |
+| Backend | **Scratching Post** | The admin panel where all content is managed |
+| Framework | **Sunbeam** | The underlying system powering everything |
+
+## Features
+
+- **WYSIWYG Editor** — TinyMCE with image upload, tables, rich text
+- **Embed Web Content** — iframe any URL as a slide
+- **ICS Calendar** — display upcoming events from any .ics feed
+- **Device Playlists** — assign slides to specific devices with individual durations
+- **Per-Device Resolution** — configure display resolution per device
+- **URL-Based Devices** — access displays via `http://server/frontofhouse`, `http://server/staffroom`
+- **Drag-and-Drop Playlist** — reorder slides in the admin
+- **Live Updates** — display polls for changes every 30 seconds
+- **Full-Screen Display** — hidden cursor, clock overlay, progress bar
+- **Smooth Transitions** — fade or slide transitions
+
+## Requirements
+
+- Windows Server 2019 or 2022
+- IIS with ASP.NET Core Hosting Bundle
+- .NET 8 SDK (for building) / .NET 8 Runtime (for hosting)
+
+## Quick Start
+
+### 1. Install Prerequisites
+
+Download and install:
+- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
+- [ASP.NET Core Hosting Bundle](https://dotnet.microsoft.com/download/dotnet/8.0) (under Hosting Bundle)
+
+### 2. Build
+
+```powershell
+cd ScratchingPost
+dotnet restore
+dotnet publish -c Release -o ./publish
+```
+
+### 3. Deploy to IIS
+
+1. Open **IIS Manager**
+2. Create a new **Site** (e.g. ScratchingPost)
+3. Set the **physical path** to the `publish` folder
+4. Set the **binding** (e.g. port 80, or a hostname like `sign.local`)
+5. Set the **Application Pool** to **No Managed Code** (the Hosting Bundle handles .NET)
+6. Ensure the App Pool identity has **write access** to the publish folder (for SQLite DB and uploads)
+
+### 4. First Run
+
+The SQLite database (`noticeboard.db`) is created automatically on first start with two demo devices seeded:
+- **Front of House** at `http://server/frontofhouse`
+- **Staff Room** at `http://server/staffroom`
+
+### 5. Access
+
+| URL | Purpose |
+|-----|---------|
+| `http://server/admin` | Scratching Post admin panel |
+| `http://server/admin/slides` | Manage Meows (slides) |
+| `http://server/admin/devices` | Manage Kittens (devices) |
+| `http://server/frontofhouse` | Front of House display |
+| `http://server/staffroom` | Staff Room display |
+
+## Configuration
+
+Edit `appsettings.json`:
+
+```json
+{
+  "MaxUploadSizeMB": 20
+}
+```
+
+## How It Works
+
+1. **Create Meows** (slides) — use the WYSIWYG editor for rich content, embed external URLs, or point to an ICS calendar feed
+2. **Create Kittens** (devices) — give each a name, URL slug, and display resolution
+3. **Build PURRs** (playlists) — assign Meows to Kittens with individual durations and drag-and-drop ordering
+4. **Display** — point a browser at `http://server/{slug}` and it runs full-screen with smooth transitions
+
+The display page polls for changes every 30 seconds, so updates appear on devices without restarting.
+
+## Display Controls
+
+Keyboard shortcuts on display pages (useful during setup):
+
+| Key | Action |
+|-----|--------|
+| Right Arrow or Space | Skip to next slide |
+| Left Arrow | Go to previous slide |
+| F or F11 | Toggle fullscreen |
+| C | Toggle cursor visibility |
+
+## Data Storage
+
+- **Database**: SQLite (`noticeboard.db`) — created automatically, zero config
+- **Uploads**: `wwwroot/uploads/` — images uploaded via TinyMCE or the file upload API
+- Both need write permissions for the IIS App Pool identity
+
+## TinyMCE Note
+
+The WYSIWYG editor uses TinyMCE CDN with `no-api-key`. This shows a small notification banner. For production, register for a free TinyMCE API key at [tiny.cloud](https://www.tiny.cloud/) and replace `no-api-key` in `Views/Slides/Create.cshtml` and `Edit.cshtml`.
+
+## Project Structure
+
+```
+ScratchingPost/
+├── Controllers/         # MVC controllers
+│   ├── AdminController   # Dashboard
+│   ├── SlidesController  # Meow CRUD
+│   ├── DevicesController # Kitten CRUD + Playlist management
+│   ├── DisplayController # Device display + playlist API
+│   └── ApiController     # Image upload, ICS parsing
+├── Data/                # EF Core DbContext + seed data
+├── Models/              # Slide, Device, DeviceSlide
+├── Routing/             # DeviceSlugConstraint
+├── Views/               # Razor views (Admin, Slides, Devices, Display)
+├── wwwroot/             # Static files
+│   ├── css/             # admin.css, display.css
+│   ├── js/              # admin.js, display.js (Sunbeam engine)
+│   └── uploads/         # User-uploaded images
+├── appsettings.json     # Configuration
+├── web.config           # IIS configuration
+└── NoticeBoard.csproj   # Project file
+```
+
+## Version History
+
+- **v1.0.0** — Initial release: WYSIWYG slides, embed, ICS calendar, device playlists, drag-and-drop ordering, live polling, IIS-ready deployment