diff --git a/README.md b/README.md
index 81fe998..e6f9174 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,74 @@
-<div align="center">
-<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
-</div>
+# Sam Developer
 
-# Run and deploy your AI Studio app
+**A full-stack developer portfolio — career overview, AI systems, portfolio work, and a showcase of engineering craft.**
 
-This contains everything you need to run your app locally.
+A polished React portfolio presenting a 30+ year coding career across 22 agencies and 20+ clients, with 35+ IoT projects. Includes a career overview, portfolio gallery, resume, AI systems showcase, image generation work, and the human side of engineering.
 
-View your app in AI Studio: https://ai.studio/apps/21d9d5ea-d35f-40ac-9e6c-3ad96f614864
+## What it is
 
-## Run Locally
+The flagship portfolio site for employment outreach. It presents experience, skills, and projects in a motion-rich, editorial interface designed to make an impression — while demonstrating the front-end architecture and design patterns used to build it.
 
-**Prerequisites:**  Node.js
+## Tech stack
 
+| Layer | Technology |
+|-------|-----------|
+| Framework | React 19 |
+| Build | Vite 6 |
+| Styling | Tailwind CSS 4 (via `@tailwindcss/vite`) |
+| Animation | Motion 12 (staggered fade/slide variants) |
+| Routing | React Router 7 |
+| Icons | lucide-react |
+| AI | @google/genai (Gemini integrations) |
+| Backend bits | Express + dotenv (API support) |
+| 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
+
+- **Motion design system** — shared `container`/`item` variants (fade-up, staggered children, ease-out timing) for consistent page animation
+- **Stats-driven storytelling** — animated stat blocks (years coding, agencies, clients, IoT projects)
+- **Domain pages** — AI Systems, Image Generation, and Beyond Code give depth beyond the resume
+- **Route-based SPA** — React Router with shared `Layout` shell
+- **Semantic hero** — editorial headline + tagline hierarchy
+- **Accessible, responsive** — semantic HTML, full mobile support
+
+## Pages
+
+| Route | Purpose |
+|-------|---------|
+| `/` | Home — hero, stats, career overview |
+| `/portfolio` | Portfolio gallery of key projects |
+| `/resume` | Detailed resume / experience |
+| `/ai-systems` | AI systems & agentic development |
+| `/image-gen` | AI image generation work |
+| `/beyond-code` | Interests & the human side |
+| `/contact` | Contact + links |
+
+## Standards
+
+- TypeScript strict mode
+- Semantic HTML, accessible landmarks
+- Tailwind utility-first styling with design tokens
+- Motion 12 animation patterns (variants, stagger, easing)
+- Fully responsive
+
+## Getting started
+
+```bash
+npm install
+npm run dev      # development server
+npm run build    # production build
+```
+
+## Structure
+
+```
+src/
+├── components/    # Layout shell
+├── pages/         # Home, Portfolio, Resume, AISystems, ImageGen, BeyondCode, Contact
+├── App.tsx        # Router + app shell
+└── main.tsx       # Entry point
+```
+
+---
+
+*Flagship of the Sam Rolfe portfolio family — see [sam-devops](https://gitea.lab.audasmedia.com.au/sam/sam-devops), [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).*