diff --git a/README.md b/README.md
index 4061103..f62e5a4 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,273 @@
 # Wireguard UI
 
-An admin dashboard for Wireguard.
+An admin dashboard for Wireguard — manage hosts, clients, tunnels, and IP rules through a web interface.
 
-Installation script located at `https://git.tben.me/Moduletrace/wireguard-ui/raw/branch/main/src/scripts/install-wg-ui.sh`
+## Features
+
+- **Host Management** — Create and configure WireGuard hosts with public keys, IP addresses, and listen ports
+- **Client Management** — Add clients per host with WireGuard configs, allowed IPs, and notes
+- **Client Rules** — Define IP table rules per client (rule type, destination, ports, protocol)
+- **Media Management** — Upload and manage media assets (images, documents, etc.) with tagging, thumbnails, and RAG ingestion
+- **User Management** — Multi-user support with role-based access (user types)
+- **Persistent Storage** — MariaDB-backed database with automatic schema generation
+- **WebSocket Support** — Real-time updates via WebSocket connections
+- **Responsive UI** — Tailwind CSS v4 with twui design system components
+
+## Prerequisites
+
+- **Bun** 1.3.1 or later ([install](https://bun.sh/install))
+- **MariaDB** (or compatible SQL database)
+- **git**
+- **Linux** (Debian, Ubuntu, Fedora, Arch, Alpine, or similar)
+- Root access (for installation script and system service setup)
+
+## Installation
+
+### Automatic (Recommended)
+
+Run the install script on a fresh machine:
+
+```bash
+REPO_URL=https://git.tben.me/Moduletrace/wireguard-ui.git bash -c '$(< <(curl -fsSL https://git.tben.me/Moduletrace/wireguard-ui/raw/branch/main/src/scripts/install-wg-ui.sh))'
+```
+
+Or clone the repo and run the script manually:
+
+```bash
+git clone https://git.tben.me/Moduletrace/wireguard-ui.git
+cd wireguard-ui
+REPO_URL=https://git.tben.me/Moduletrace/wireguard-ui.git bash src/scripts/install-wg-ui.sh
+```
+
+The install script will:
+
+1. Install system dependencies (git, curl, ca-certificates, openssl)
+2. Install Bun 1.3.14 to `/opt/bun`
+3. Set up library directories under `/var/lib/wgui` (keys, clients, hosts, iptables, scripts)
+4. Clone or update the repo to `/var/lib/wgui/webapp`
+5. Install app dependencies (`bun install`)
+6. Generate `.env` with encryption secrets
+7. Run WireGuard setup (if available)
+8. Install the `wg-quick` helper script
+9. Set up a systemd or OpenRC service (`wgui`)
+
+### Docker
+
+Build and run with the provided Dockerfile:
+
+```bash
+docker build -t wireguard-ui .
+docker run -d --name wireguard-ui \
+  -p 10752:10752 \
+  -v wgui-data:/app/db \
+  --restart unless-stopped \
+  wireguard-ui
+```
+
+The entrypoint (`entrypoint.sh`) installs dependencies and starts the server.
+
+### Manual (Development)
+
+```bash
+git clone https://git.tben.me/Moduletrace/wireguard-ui.git
+cd wireguard-ui
+bun install
+NODE_ENV=development bun run dev
+```
+
+The dev server runs on port **10752** by default.
+
+## Configuration
+
+### Environment Variables
+
+The `.env` file (gitignored) controls runtime behavior. It is auto-generated during installation if missing:
+
+| Variable            | Description                          | Default              |
+| ------------------- | ------------------------------------ | -------------------- |
+| `NODE_ENV`          | Environment (`development`/`production`) | `production`       |
+| `ENCRYPTION_KEY`    | Encryption key for sensitive data    | Auto-generated       |
+| `ENCRYPTION_SALT`   | Encryption salt for sensitive data   | Auto-generated       |
+| `DATA_DIR`          | Application data directory           | `$INSTALL_DIR/.data` |
+
+### Database Configuration
+
+Edit `bun-sqlite.config.ts` to change database settings:
+
+```typescript
+const config: BunSQLiteConfig = {
+    db_name: "wgui",          // Database file name
+    db_dir: "./db",           // Database directory
+    typedef_file_path: "./db/types/db.ts",  // Generated types
+    db_schema_file_name: "schema.ts",       // Schema definition
+};
+```
+
+### Server Port
+
+The server port is defined in `src/data/site-data.ts`:
+
+```typescript
+export const SiteData = {
+    ServerPort: 10752,
+    // ...
+} as const;
+```
+
+## Available Scripts
+
+| Command             | Description                                      |
+| ------------------- | ------------------------------------------------ |
+| `bun run dev`       | Start development server (requires root)         |
+| `bun run start`     | Start production server                          |
+| `bun run build`     | Build with bunext                                |
+| `bun run db:schema` | Generate/update database schema and types        |
+| `bun run db:admin`  | Open database admin interface                    |
+| `bun run deploy:prod` | Deploy to production server                    |
+| `bunx tsc --noEmit` | Type-check only (no emit)                        |
+| `bun test <file>`   | Run individual test files                        |
+
+## Project Structure
+
+```
+wireguard-ui/
+├── src/
+│   ├── pages/              # File-system based routes (__root.tsx, index.tsx, etc.)
+│   │   ├── (sections)/     # Page sections
+│   │   ├── (partials)/     # Page-local components
+│   │   ├── (data)/         # Page-local data
+│   │   ├── (functions)/    # Page-local functions
+│   │   ├── (utils)/        # Page-local utilities
+│   │   └── (hooks)/        # Page-local hooks
+│   ├── components/
+│   │   ├── twui/           # Local design system (publishable package)
+│   │   ├── ui/             # shadcn/ui components
+│   │   ├── shadcnblocks/   # shadcnblocks registry components
+│   │   └── general/        # Shared page components (chat, date-picker, logo, etc.)
+│   ├── hooks/              # Shared React hooks
+│   ├── functions/
+│   │   ├── backend/        # Server-only: DB queries, email, media upload, RAG
+│   │   ├── frontend/       # Client-safe: CRUD handlers, fetch handlers
+│   │   └── general/        # Platform-agnostic: join builders
+│   ├── utils/              # Utility modules (auth, crypto, CSRF, hashing, etc.)
+│   ├── dict/               # Constants and dictionaries (user types, gates, etc.)
+│   ├── data/               # Static data (app constants, location data, etc.)
+│   ├── types/              # Type definitions
+│   ├── scripts/            # Install and setup scripts
+│   └── server.ts           # Entry point — starts Bun.serve with WebSocket support
+├── db/
+│   ├── schema.ts           # Database schema definition
+│   └── types/db.ts         # Generated database types
+├── deploy/
+│   └── deploy-prod.sh      # Production deployment script (rsync + Docker)
+├── public/                 # Static assets served by the server
+├── assets/                 # Project assets
+├── Dockerfile              # Container image (oven/bun:1.3.1-debian)
+├── entrypoint.sh           # Docker entrypoint
+├── bun-sqlite.config.ts    # Database configuration
+├── bunext.config.ts        # Bunext configuration
+├── package.json            # Dependencies and scripts
+├── tsconfig.json           # TypeScript configuration
+└── .env                    # Environment variables (gitignored)
+```
+
+## Database Schema
+
+The database consists of the following tables:
+
+| Table            | Description                                    |
+| ---------------- | ---------------------------------------------- |
+| `users`          | User accounts (name, email, username, password) |
+| `user_types`     | User type assignments per user                 |
+| `media`          | Media assets (images, documents, etc.)         |
+| `media_paradigms`| Media paradigm classifications per media item  |
+| `clients`        | WireGuard clients per host                     |
+| `hosts`          | WireGuard host configurations                  |
+| `client_rules`   | IP table rules for each client                 |
+| `variables`      | Application-wide key-value variables           |
+
+Generate types from the schema:
+
+```bash
+bun run db:schema
+```
+
+## Deployment
+
+### Production Deployment
+
+The deployment script (`deploy/deploy-prod.sh`) handles production deployment:
+
+```bash
+SOURCE_DIRECTORY=/path/to/wireguard-ui bun run deploy:prod
+```
+
+This will:
+
+1. Rsync the project files to the production server (`deploy@195.26.246.243:/docker/bunext-mariadb`)
+2. SSH into the server, rebuild the Docker image, and restart the container
+
+### Docker Production
+
+The Docker image (`Dockerfile`) is based on `oven/bun:1.3.1-debian` with MariaDB client tools installed:
+
+```bash
+docker build -t bunext-mariadb .
+docker run --name bunext-mariadb -d \
+  --network cloudflare --network mariadb \
+  -v server-data:/data \
+  --restart unless-stopped \
+  bunext-mariadb:latest
+```
+
+The server runs on the port defined in `SiteData.ServerPort` (default: **10752**).
+
+## Admin Route Hierarchy
+
+| Route Pattern       | Access                        | Features                                    |
+| ------------------- | ----------------------------- | ------------------------------------------- |
+| `/admin/*`          | Residents                     | Access booking, payments, chat, dependants, notifications, events, settings, support |
+| `/admin/admin/*`    | Admin / ExCo                  | User management, payment schemes, documents, chat group management |
+| `/admin/security/*` | Security / ExCo / Manager / ACo | Gate control, guest access monitoring, dependant verification |
+
+## Development
+
+### Development Mode
+
+Set `NODE_ENV=development` and run:
+
+```bash
+NODE_ENV=development bun run dev
+```
+
+In development mode, the install script skips cloning and system service setup — the server is assumed to already be running.
+
+### Path Alias
+
+`@/*` resolves from the repository root. Examples:
+
+```typescript
+import { Button } from "@/src/components/ui/button";
+import type { BUN_SQLITE_WGUI_USERS } from "@/db/types/db";
+```
+
+### Type-Checking
+
+Run type checks with:
+
+```bash
+bunx tsc --noEmit
+```
+
+### Testing
+
+Run individual test files:
+
+```bash
+bun test path/to/test.file.test.ts
+```
+
+## Repository
+
+- **URL**: [https://git.tben.me/Moduletrace/wireguard-ui](https://git.tben.me/Moduletrace/wireguard-ui)
+- **Install Script**: [src/scripts/install-wg-ui.sh](https://git.tben.me/Moduletrace/wireguard-ui/raw/branch/main/src/scripts/install-wg-ui.sh)