diff --git a/README.md b/README.md
index 7a5b563..8331999 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,56 @@
 # 👾 dvorakmortonxd.dev
 
-> The source code for my own website.
-This repository contains the Next.js frontend for my personal portfolio and link tree, **[dvorakmortonxd.dev](https://dvorakmortonxd.dev)**.
-It's designed with a custom terminal/TUI aesthetic (using the Monocraft font and a Gruvbox-inspired theme) to list out my socials, hardware collections, self-hosted homelab services, and various scattered coding projects.
+> The source code for my personal website, **[dvorakmortonxd.dev](https://dvorakmortonxd.dev)**.
+
+This is not a normal portfolio page. It ships **two fully interactive shells** and picks
+which one to show based on the saved theme and the device, all from the same content:
+
+- **`skeuo`** (default) — a KDE Plasma / Windows-style **desktop simulation**: draggable
+  snap-to-grid icons, resizable/floating windows, a Start menu, taskbar and live clock.
+  On phones it becomes an **iOS-style home screen** with a widget grid, dock, drag-to-reorder
+  and an iOS launch animation.
+- **`terminal`** — a **Gruvbox TUI** version of the site: TUI panels, an animated ASCII
+  train background, a clickable easter-egg logo, and a working in-browser terminal (Alacritty)
+  with commands like `help`, `ls`, `cat`, `neofetch`, `emerge`, `ssh` and more.
+
+Both shells surface the same personal content: socials, self-hosted services with **live
+up/down health checks**, a hardware collection, coding projects, a **GitDXD contribution
+heatmap**, a gym SBD panel and links to friends' sites.
+
+## ✨ Features
+
+- **Two themes / shells** — KDE-style desktop and Gruvbox terminal, toggled from either UI
+  and persisted in `localStorage` (applied pre-paint to avoid a flash).
+- **Phone vs. desktop detection** — a user-agent sniff on `<html data-device>` decides whether
+  the desktop or the mobile home screen is shown.
+- **Draggable desktop icons** — free placement that snaps to a measured grid, one icon per
+  cell, with a follow-the-cursor drag ghost.
+- **Multi-window manager** — draggable, resizable, minimizable, maximizable, focus/z-order
+  and animated open/close (with reduced-motion support).
+- **Working terminal app** — command input with history (`↑`/`↓`, `Ctrl+L` to clear) and a
+  hidden `ssh` easter egg.
+- **Live service status** — each self-hosted service is health-checked through the site's
+  own API; Minecraft is checked through mcstatus.io.
+- **Live GitDXD stats** — contribution heatmap + latest commit activity proxied server-side
+  from the self-hosted Forgejo instance.
+- **Extras** — a playable `Revival Inc.` game embedded at `/revival-inc`, `llms.txt`,
+  `robots.txt` and a `sitemap.xml`.
 
 ## 🛠️ Tech Stack
- 
-- **Framework:** Next.js (App Router)
-- **Language:** TypeScript
-- **Styling:** Custom CSS for that retro TUI vibe
+
+- **Framework:** Next.js 16 (App Router, Turbopack)
+- **Language:** TypeScript, React 19 (client components everywhere interactivity lives)
+- **Styling:** hand-written CSS — `src/app/page.css` (terminal theme), `src/app/skeuo.css`
+  (desktop + mobile), `src/app/globals.css` (base/reset). Tailwind v4 is imported for the
+  base layer but the UI is custom CSS.
+- **Fonts:** Monocraft (self-hosted in `public/`, used by the terminal theme; the desktop
+  theme uses the system sans stack)
+- **Images:** `next/image`
+- **Version:** `2.1.0` (see `package.json`)
 
 ## 🚀 Running Locally
 
-Want to spin it up and check the code out yourself?
+Requires **Node.js >= 20.9.0** (Next.js 16).
 
 ```bash
 git clone https://git.dvorakmortonxd.dev/dvorakmortonxd/dvorakmortonxd.dev
@@ -21,17 +59,83 @@ npm install
 npm run dev
 ```
 
-Then open [http://localhost:3000](http://localhost:3000) in your browser.
+Then open [http://localhost:3000](http://localhost:3000).
+
+### Scripts
+
+```bash
+npm run dev     # next dev --turbopack
+npm run build   # next build --turbopack
+npm run start   # next start (production)
+npm run lint    # eslint
+```
+
+Handy checks before shipping: `npx tsc --noEmit`, `npx eslint <files>`, `npm run build`.
+
+### Testing from a phone on your LAN
+
+`next.config.ts` sets `allowedDevOrigins` so the dev server can be reached from other devices
+on the local network (otherwise Next.js 403s the dev asset requests).
+
+## 📡 API Routes
+
+| Route | Method | What it does |
+| --- | --- | --- |
+| `/api/heatmap` | `GET` | Proxies the user's contribution heatmap from `git.dvorakmortonxd.dev`. |
+| `/api/activities` | `GET` | Fetches the GitDXD activity feed and keeps only the user's own events. |
+| `/api/ping?url=…` | `GET` | Health-checks a service. Handles `minecraft://host:port` via mcstatus.io; treats any non-5xx HTTP response as "up". |
+
+## 📁 Project Structure
+
+```
+src/app/
+  page.tsx                → renders <ThemeRoot/>, imports the two theme stylesheets
+  layout.tsx              → html shell + metadata, injects ThemeScript
+  globals.css             → base/reset styles + Tailwind import
+  page.css                → terminal theme styles
+  skeuo.css               → desktop + mobile home styles
+  data.ts                 → socials, codingProjects, techProjects, friends, wallpapers
+  revival-inc/page.tsx    → embeds the bundled game at /public/revival-inc/index.html
+  api/
+    heatmap/route.ts      → contribution heatmap proxy
+    activities/route.ts   → GitDXD activity feed proxy
+    ping/route.ts         → service health check (HTTP + Minecraft)
+  components/
+    ThemeRoot.tsx           → picks which shell(s) to mount
+    ThemeScript.tsx         → pre-paint script: theme + device detection
+    useTheme.ts             → theme state via useSyncExternalStore
+    TerminalLayout.tsx      → the Gruvbox terminal shell
+    WindowsDesktop.tsx      → desktop shell: icons, windows, taskbar, Start menu
+    MobileHome.tsx          → phone shell: iOS home screen + app view
+    WinWindow.tsx           → one draggable/resizable window
+    apps.tsx                → APPS registry, window contents, in-app terminal
+    useDesktopIcons.ts      → desktop icon grid + drag/drop logic
+    useDragOrder.ts         → list reordering (mobile grid/dock)
+    ServiceButton.tsx       → service link + live status dot
+    ContributionHeatmap.tsx → heatmap + recent commits widget
+    Clock.tsx               → live clock
+    JokerLogo.tsx           → logo with click easter egg
+    SlBackground.tsx        → animated ASCII train background
+public/                     → fonts, wallpapers, icons, friend pages, /revival-inc game, llms.txt, robots.txt, sitemap.xml
+```
 
 ## 🌍 Deploying?
 
-In order to deploy the website youd want to set up a reverse proxy and something that runs it as a service, me personally, I use cloudflared and pm2.
-you could also use something like vercel but I prefer selfhosting, also please if you want to deploy it,
-you gotta change it enough so that you dont directly copy my website, and also follow the GPL3.0-only license,
-meaning you gotta make your code opensource too
+In order to deploy the website you'd want to set up a reverse proxy and something that runs it
+as a service. Me personally, I use cloudflared and pm2. You could also use something like
+Vercel, but I prefer self-hosting. Also, if you want to deploy it, you gotta change it enough
+so that you don't directly copy my website, and also follow the GPL3.0-only license, meaning
+you gotta make your code open source too.
 
-Detailed step-by-step production instructions for **PM2 + npm on Debian and Alpine Linux** are in
+Detailed step-by-step production instructions for **PM2 + npm on Debian and Alpine Linux**
+(including the Cloudflare Tunnel / Nginx reverse-proxy setup) are in
 [`DEPLOYMENT.md`](./DEPLOYMENT.md).
 
 ## 📬 Contact
-To see my projects or get in touch, visit the live site or email me at [dvorak@dvorakmortonxd.dev](mailto:dvorak@dvorakmortonxd.dev). 
+
+To see my projects or get in touch, visit the live site or email me at
+[dvorak@dvorakmortonxd.dev](mailto:dvorak@dvorakmortonxd.dev).
+
+## 📄 License
+
+GPL-3.0-only — see [`LICENSE`](./LICENSE).
diff --git a/opencode.md b/opencode.md
index e3abf2a..181ffa6 100644
--- a/opencode.md
+++ b/opencode.md
@@ -5,6 +5,25 @@ a minute. Read this first, then skim the files it points at.
 
 ---
 
+## Keep README.md in sync — do this on EVERY prompt
+
+**Before you finish any task, update `README.md` so it still matches the code.**
+This is a standing requirement, not a one-off. The README is meant to describe the
+project as it is right now, so treat it as part of "done":
+
+- If a change adds/removes/renames a feature, script, route, app, theme, file or
+  dependency, reflect it in `README.md` (Features, Tech Stack, API Routes, Project
+  Structure, Scripts, running/deploying sections — whichever apply).
+- Re-read `README.md` and the files you touched; fix anything the change made stale.
+- Keep the author's voice and existing emoji-section formatting; don't rewrite the
+  whole thing when a small edit will do.
+- If a task genuinely changes nothing user- or contributor-visible, it's fine to
+  leave the README untouched — use judgement, don't churn it for nothing.
+
+When in doubt, prefer updating it. A stale README is treated as a bug.
+
+---
+
 ## What this project is
 
 Personal portfolio site for **dvorakmortonxd.dev**. It's not a normal website —
@@ -40,21 +59,32 @@ Do not print it, copy it into new files, or push it anywhere else.
 ```
 src/app/
   page.tsx              → renders <ThemeRoot/>, imports page.css + skeuo.css
-  layout.tsx            → html shell, ThemeScript
-  data.ts               → friends[], WALLPAPER, MOBILE_WALLPAPER (static content)
+  layout.tsx            → html shell, metadata, ThemeScript
+  globals.css           → base/reset styles + Tailwind import
+  data.ts               → socials, codingProjects, techProjects, friends, wallpapers
   page.css              → base / terminal theme styles
   skeuo.css             → Windows/Plasma desktop + mobile home styles
+  revival-inc/page.tsx  → fullscreen iframe embedding /public/revival-inc/index.html
+  api/
+    heatmap/route.ts    → proxy for git.dvorakmortonxd.dev contribution heatmap
+    activities/route.ts → proxy for the user's GitDXD activity feed
+    ping/route.ts       → service health check (HTTP + minecraft:// via mcstatus.io)
   components/
     ThemeRoot.tsx       → picks which shell to show (the router of the UI)
     TerminalLayout.tsx  → "terminal" theme (Gruvbox)
     WindowsDesktop.tsx  → "skeuo" theme, desktop: icons, windows, taskbar
     MobileHome.tsx      → "skeuo" theme, phone: app grid + dock
     WinWindow.tsx       → a single draggable/resizable window
-    apps.tsx            → APPS registry + the content of each app
+    apps.tsx            → APPS registry + the content of each app + in-app terminal
     useDesktopIcons.ts  → desktop icon grid + drag/drop  (THE KEY FILE, see below)
     useDragOrder.ts     → simple list reordering (mobile home screen only)
     useTheme.ts         → theme state via useSyncExternalStore
     ThemeScript.tsx     → inline pre-hydration script: theme + device detection
+    ServiceButton.tsx   → service link + live status dot (pings /api/ping)
+    ContributionHeatmap.tsx → heatmap + recent-commit widget (uses the two proxies)
+    Clock.tsx           → live clock (useSyncExternalStore + interval)
+    JokerLogo.tsx       → site logo with a click easter egg
+    SlBackground.tsx    → animated ASCII train background (terminal theme)
 ```
 
 ### How UI selection works
@@ -180,8 +210,9 @@ list reordering, not free placement. Don't confuse the two.
 
 ## After finishing — push to git
 
-When the work is done, run **only** these three commands (no extra flags, no
-rebasing, no force-push):
+First make sure `README.md` is up to date (see "Keep README.md in sync" at the
+top), then run **only** these three commands (no extra flags, no rebasing, no
+force-push):
 
 ```bash
 git add .