diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0012c4a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# Sam DevOps
+
+**A DevOps and infrastructure portfolio — documenting a self-hosted homelab from NixOS configuration to Docker orchestration.**
+
+An interactive React showcase of the homelab infrastructure: NixOS flakes, the Niri compositor, Docker ecosystems, Home Assistant automation, Snapcast audio, Zigbee/ESP32 sensor networks, security hardening, and remote setup — presented as deep-dive pages with code blocks and stats.
+
+## What it is
+
+A portfolio site that documents how the homelab is architected and operated. Each infrastructure domain gets a dedicated page with architecture notes, configuration snippets (`CodeBlock`), tooling chips, and status indicators — demonstrating real production DevOps work.
+
+## Tech stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | React 19 |
+| Build | Vite 6 |
+| Styling | Tailwind CSS 4 (via `@tailwindcss/vite`) |
+| Animation | Motion 12 |
+| Routing | React Router 7 |
+| Icons | lucide-react |
+| Language | TypeScript |
+
+## Architecture & design patterns
+
+- **Domain-per-page** — 17 infrastructure pages, each a focused deep-dive
+- **Code-first documentation** — `CodeBlock` renders syntax-highlighted config (NixOS, Docker Compose, YAML)
+- **Stat cards** — `StatCard` for key metrics per domain
+- **Status badges** — `StatusBadge` shows service/component health
+- **Tool chips** — `ToolChip` visualizes the toolchain used per domain
+- **Section cards** — `SectionCard` structures long-form content
+- **AI flow page** — documents the AI development pipeline (`AIFlow`)
+- **Shared shell** — `Layout` + `PageHeader` + nav from `navItems.ts`
+- **Route-based pages** — multi-page SPA
+
+## Pages
+
+| Route | Domain |
+|-------|--------|
+| `/` | Dashboard — infrastructure overview |
+| `/nixos` | NixOS configuration & flakes |
+| `/niri` | Niri compositor setup |
+| `/docker` | Docker orchestration & services |
+| `/home-assistant` | Home Assistant automation |
+| `/snapcast` | Multi-room audio |
+| `/zigbee-esp32` | Zigbee & ESP32 sensor networks |
+| `/mobile-car-tracker` | Vehicle GPS tracking |
+| `/terminal` / `/nvim` | Dev environment tooling |
+| `/security` | Hardening & access control |
+| `/remote-setup` | Remote access & setup |
+| `/website` | This site's own infra |
+| `/ai-flow` | AI development pipeline |
+| `/home-ai` / `/home-networking` / `/dev-environment` | Supporting domains |
+| `/contact` | Contact + links |
+
+## Standards
+
+- TypeScript strict mode
+- Semantic HTML, accessible landmarks
+- Tailwind utility-first styling
+- Fully responsive
+- Content as structured data (`navItems.ts`) + code-first documentation
+
+## Getting started
+
+```bash
+npm install
+npm run dev      # development server
+npm run build    # production build
+```
+
+## Structure
+
+```
+src/
+├── components/    # CodeBlock, StatCard, StatusBadge, ToolChip,
+│                  # SectionCard, Layout, PageHeader, AiChatBox
+├── data/          # navItems.ts
+├── pages/         # 17 domain pages + Contact
+├── App.tsx        # Router + app shell
+└── main.tsx       # Entry point
+```
+
+---
+
+*Part of the Sam Rolfe portfolio family — see [sam-iot-electronics](https://gitea.lab.audasmedia.com.au/sam/sam-iot-electronics) and [sam-pursuits](https://gitea.lab.audasmedia.com.au/sam/sam-pursuits).*