diff --git a/README.md b/README.md
index 444337f..5516901 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,83 @@
-<div align="center">
-<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
-</div>
+# The Domestic Atelier (chat)
 
-# Run and deploy your AI Studio app
+**A warm, editorial family messaging app designed for the home.**
 
-This contains everything you need to run your app locally.
+A private family chat interface — "The Domestic Atelier" — built for household communication. Authenticated via PocketBase, with Apprise notifications and optional AI assistance. A cozy, editorial take on messaging that lives inside the home network.
 
-View your app in AI Studio: https://ai.studio/apps/4203dee4-c4d5-41ff-8d3c-99cf47d750e1
+## What it is
 
-## Run Locally
+A self-hosted family messaging application. Unlike public chat apps, it runs on the home network, keeps conversations private, and integrates with the household's own services (PocketBase for auth/data, Apprise for notifications). Designed with a warm, editorial aesthetic to feel like home, not a corporate tool.
 
-**Prerequisites:**  Node.js
+## Tech stack
 
+| Layer | Technology |
+|-------|-----------|
+| Framework | React 19 |
+| Build | Vite 6 |
+| Styling | Tailwind CSS 4 (via `@tailwindcss/vite`) |
+| Backend | PocketBase (`pocketbase` SDK) |
+| Notifications | Apprise |
+| AI | @google/genai (Gemini) |
+| Routing | React Router 7 |
+| Animation | Motion 12 |
+| Icons | lucide-react |
+| Language | TypeScript |
 
-1. Install dependencies:
-   `npm install`
-2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
-3. Run the app:
-   `npm run dev`
+## Architecture & design patterns
+
+- **Auth context** — `AuthContext` wraps the app, managing PocketBase auth state and session (`pb.authStore`)
+- **Service layer** — `lib/pocketbase.ts` centralizes the PocketBase client, base URL from `VITE_POCKETBASE_URL` (defaults to the homelab instance), and auth-state hooks
+- **Route-based pages** — Chat, Login, Settings, HowTo under a shared `Layout`
+- **Environment-driven config** — PocketBase & Apprise URLs via `VITE_*` env vars (never committed)
+- **Editorial design** — warm, styled messaging UI (`The Domestic Atelier` aesthetic)
+- **Client-side auth** — login flow with PocketBase email/password auth
+
+## Pages
+
+| Route | Purpose |
+|-------|---------|
+| `/chat` | The family chat interface |
+| `/login` | PocketBase authentication |
+| `/settings` | App & notification settings |
+| `/how-to` | Usage guide for the household |
+
+## Configuration
+
+Copy `.env.example` → `.env.local`:
+
+```bash
+VITE_POCKETBASE_URL=http://192.168.20.13:8090   # homelab PocketBase
+VITE_APPRISE_URL=                                # Apprise notification endpoint
+```
+
+## Getting started
+
+```bash
+npm install
+npm run dev      # development server
+npm run build    # production build
+```
+
+## Structure
+
+```
+src/
+├── components/    # Header, Layout
+├── contexts/      # AuthContext (PocketBase auth state)
+├── lib/           # pocketbase.ts (client + config)
+├── pages/         # Chat, Login, Settings, HowTo
+├── App.tsx        # Router + providers
+└── main.tsx       # Entry point
+```
+
+## Standards
+
+- TypeScript strict mode
+- Secrets never committed (`.env.*` gitignored)
+- Semantic HTML, accessible landmarks
+- Fully responsive, mobile-first (messaging on the go)
+- Self-hosted — data stays in the home
+
+---
+
+*Part of the Sam Rolfe portfolio family.*