diff --git a/CLAUDE.md b/CLAUDE.md
index 028ae87..7bfdb6e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -939,3 +939,60 @@ Currently using CPU synchronization (`vkQueueWaitIdle` / `glFinish`). Future imp
 ### Double Buffering
 
 The imported image is copied to a local texture each frame to prevent data races with MosisService rendering.
+
+## Developer Portal
+
+The Developer Portal is a web application for app developers to publish and manage their Mosis apps. Planning documents are in `DEV_PORTAL_M01-M12.md` files.
+
+### Architecture Decisions
+
+| Component | Technology | Rationale |
+|-----------|------------|-----------|
+| Backend | Go 1.22+ | Simple, fast, single binary deployment |
+| Router | Chi | Lightweight, idiomatic Go HTTP routing |
+| Database | SQLite + Litestream | Zero-ops, continuous backup to NAS storage |
+| Frontend | htmx + Go templates | Server-rendered, minimal JS, fast |
+| Storage | Synology NAS filesystem | Self-hosted, local volume mounts |
+| Auth | OAuth2 (GitHub/Google) + JWT | golang-jwt for tokens, Ed25519 for signing |
+| CLI | Go + Cobra | Cross-platform single binary |
+| Docs | Hugo + Docsy | Static site served from /docs/ |
+
+### Deployment Target
+
+Self-hosted on Synology NAS via Docker:
+
+```
+/volume1/mosis/
+├── data/
+│   ├── portal.db       # Main SQLite database
+│   └── telemetry.db    # Separate telemetry database
+├── packages/           # Uploaded app packages
+│   └── {dev_id}/{app_id}/{version}/
+├── backups/            # Litestream replicas
+└── docs/               # Hugo static site output
+```
+
+### Milestone Documents
+
+| File | Topic | Status |
+|------|-------|--------|
+| DEV_PORTAL_M01_OVERVIEW.md | Project overview | Decided |
+| DEV_PORTAL_M02_WEB_STACK.md | Go + Chi + htmx | Decided |
+| DEV_PORTAL_M03_DATABASE.md | SQLite + Litestream | Decided |
+| DEV_PORTAL_M04_AUTH.md | OAuth2 + JWT + Ed25519 | Decided |
+| DEV_PORTAL_M05_FRONTEND.md | htmx + Go templates | Decided |
+| DEV_PORTAL_M06_API.md | REST API design | Decided |
+| DEV_PORTAL_M07_STORAGE.md | NAS filesystem | Decided |
+| DEV_PORTAL_M08_TELEMETRY.md | SQLite + background workers | Decided |
+| DEV_PORTAL_M09_REVIEW.md | Go validation workers | Decided |
+| DEV_PORTAL_M10_DEVICE.md | C++ AppManager | Decided |
+| DEV_PORTAL_M11_CLI.md | Go + Cobra CLI | Decided |
+| DEV_PORTAL_M12_DOCS.md | Hugo + Docsy | Decided |
+
+### Key Design Principles
+
+1. **Single container** - Portal runs as one Docker container on NAS
+2. **No external services** - SQLite, local filesystem, Pagefind search
+3. **Pure Go** - `modernc.org/sqlite` (no CGO required)
+4. **Server-rendered** - htmx for interactivity, no SPA framework
+5. **Background workers** - Go goroutines for aggregation/cleanup jobs