diff --git a/README.md b/README.md
index 0c43eab..a0c1f24 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,180 @@
-# sc-summercms-app
+# SummerCMS
+
+A Scala/ZIO-based Content Management Framework — a modern rewrite of WinterCMS/OctoberCMS with better performance, type safety, and horizontal scaling.
+
+## Status
+
+**Phase 1: Foundation** — Complete
+
+- Mill build system with Scala 3.3.4
+- ZIO HTTP server with health endpoints
+- PostgreSQL integration via Quill (compile-time SQL validation)
+- Flyway database migrations
+- Repository pattern with typed errors
+- Pulumi/Besom infrastructure for AWS deployment
+- Docker containerization
+
+## Requirements
+
+- Java 21+ (tested with Java 25)
+- PostgreSQL 14+
+- Mill 1.1.1+ (included as `./mill` launcher)
+
+## Quick Start
+
+### 1. Database Setup
+
+```bash
+# Create database user and database
+sudo -u postgres psql -c "CREATE USER summercms WITH PASSWORD 'summercms';"
+sudo -u postgres psql -c "CREATE DATABASE summercms OWNER summercms;"
+```
+
+Or use environment variables to connect to an existing database.
+
+### 2. Run the Server
+
+```bash
+# Start the development server
+./mill summercms.run
+```
+
+You should see the SummerCMS banner and the server starting on port 8080.
+
+### 3. Verify
+
+```bash
+# Health check (always returns 200)
+curl http://localhost:8080/health
+
+# Readiness check (returns 200 if database connected, 503 otherwise)
+curl http://localhost:8080/ready
+```
+
+## Configuration
+
+Configuration uses HOCON format in `summercms/resources/application.conf`. Environment variables override defaults:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SERVER_HOST` | 0.0.0.0 | Server bind address |
+| `SERVER_PORT` | 8080 | Server port |
+| `DB_HOST` | localhost | PostgreSQL host |
+| `DB_PORT` | 5432 | PostgreSQL port |
+| `DB_NAME` | summercms | Database name |
+| `DB_USER` | summercms | Database user |
+| `DB_PASSWORD` | summercms | Database password |
+
+## Project Structure
+
+```
+summercms/
+├── build.mill                 # Mill build configuration
+├── summercms/
+│   ├── src/
+│   │   ├── Main.scala         # Application entry point
+│   │   ├── api/               # HTTP routes
+│   │   │   ├── Routes.scala
+│   │   │   └── HealthRoutes.scala
+│   │   ├── config/            # Configuration
+│   │   │   └── AppConfig.scala
+│   │   ├── db/                # Database layer
+│   │   │   ├── QuillContext.scala
+│   │   │   └── Migrator.scala
+│   │   ├── model/             # Domain models
+│   │   │   └── User.scala
+│   │   └── repository/        # Data access
+│   │       ├── RepositoryError.scala
+│   │       └── UserRepository.scala
+│   └── resources/
+│       ├── application.conf   # HOCON configuration
+│       └── db/migration/      # Flyway SQL migrations
+├── infra/                     # Pulumi/Besom infrastructure
+│   ├── project.scala
+│   └── Main.scala
+└── Dockerfile                 # Container build
+```
+
+## Development
+
+### Build Commands
+
+```bash
+# Compile
+./mill summercms.compile
+
+# Run
+./mill summercms.run
+
+# Build fat JAR
+./mill summercms.assembly
+
+# Run tests
+./mill summercms.test
+```
+
+### Database Migrations
+
+Migrations are in `summercms/resources/db/migration/` using Flyway naming convention (`V1__description.sql`).
+
+Migrations are **not** auto-run on startup. They will be invoked via CLI commands (coming in Phase 5).
+
+### Docker
+
+```bash
+# Build image
+docker build -t summercms .
+
+# Run container
+docker run -p 8080:8080 \
+  -e DB_HOST=host.docker.internal \
+  -e DB_PASSWORD=secret \
+  summercms
+```
+
+### Infrastructure (Pulumi)
+
+The `infra/` directory contains Pulumi infrastructure using Besom (Scala Pulumi SDK):
+
+```bash
+cd infra
+pulumi stack init dev
+pulumi config set dbPassword --secret <password>
+pulumi up
+```
+
+Defines:
+- S3 bucket for assets
+- RDS PostgreSQL instance
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Language | Scala 3.3.4 |
+| Effect System | ZIO 2.1.14 |
+| HTTP Server | zio-http 3.0.1 |
+| Database | PostgreSQL + Quill 4.8.5 |
+| Migrations | Flyway 10.21.0 |
+| Configuration | zio-config + HOCON |
+| Build | Mill 1.1.1 |
+| Infrastructure | Pulumi + Besom 0.5.0 |
+
+## Roadmap
+
+SummerCMS is being built in phases:
+
+- [x] **Phase 1: Foundation** — Database, migrations, repository pattern, deployment
+- [ ] **Phase 2: Plugin System** — Plugin discovery, lifecycle, dependencies, extension API
+- [ ] **Phase 3: Component System** — Reusable UI components with HTMX handlers
+- [ ] **Phase 4: Theme Engine** — Layouts, partials, asset management, Vue integration
+- [ ] **Phase 5: CLI Scaffolding** — Commands to create plugins, themes, components
+- [ ] **Phase 6: Backend Authentication** — Admin users, login/logout, RBAC
+- [ ] **Phase 7: Admin Forms & Lists** — YAML-driven form and list generation
+- [ ] **Phase 8: Admin Dashboard** — Dashboard widgets and plugin settings
+- [ ] **Phase 9: Content Management** — CMS pages, media library, menus
+- [ ] **Phase 10: Core Plugins** — User plugin and Blog plugin
+
+## License
+
+[TBD]