docs: reorganize documentation and add ROADMAP

- Rewrite README.md with proper project overview, setup, and structure
- Create ROADMAP.md capturing future improvements and known gaps
- Move reference docs to docs/ directory:
  - docs/spec.md (theme system specification)
  - docs/plans/sample-content.md (POD content refresh plan)
  - docs/plans/page-builder.md (existing)
  - docs/research/typography.md
  - docs/research/ux-patterns.md
- Delete obsolete planning files:
  - PLAN.md (work complete)
  - PHASE_9_PLAN.md (work complete)
  - PHASE_9_PROGRESS.md (stale tracker)
  - RECENT_CHANGES.md (stale)
- Keep AGENTS.md (Phoenix codegen guidelines)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -1,18 +1,132 @@
 # SimpleshopTheme
 
-To start your Phoenix server:
+A customisable e-commerce theme system built with Phoenix LiveView. Designed for print-on-demand sellers who want beautiful, professional shops without design expertise.
 
-* Run `mix setup` to install and setup dependencies
-* Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
+## Features
 
-Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
+### Theme Editor (`/admin/theme`)
+- **8 curated presets** - Gallery, Studio, Boutique, Bold, Playful, Minimal, Night, Classic
+- **Real-time preview** - See changes instantly across 7 page types
+- **Comprehensive customisation**:
+  - Mood (Neutral, Warm, Cool, Dark)
+  - Typography (Clean, Editorial, Modern, Classic, Friendly, Minimal)
+  - Shape (Sharp, Soft, Round, Pill)
+  - Density (Compact, Balanced, Spacious)
+  - Accent colours with automatic contrast
+  - Layout options (grid columns, header style, width)
+  - Feature toggles (announcement bar, sticky header, etc.)
+- **Logo upload** with optional SVG recolouring
+- **Header image** with zoom and position controls
 
-Ready to run in production? Please [check our deployment guides](https://hexdocs.pm/phoenix/deployment.html).
+### Public Storefront
+- Home page with hero, categories, featured products, testimonials
+- Products listing with grid layout
+- Product detail pages with image gallery
+- Shopping cart page
+- About and Contact pages
+- Themed 404/500 error pages
 
-## Learn more
+### Technical Highlights
+- CSS custom properties for instant theme switching
+- Three-layer CSS architecture (primitives → attributes → semantic)
+- ETS-based CSS caching for performance
+- SQLite database with BLOB storage for images
+- Shared PageTemplates between preview and live shop
 
-* Official website: https://www.phoenixframework.org/
-* Guides: https://hexdocs.pm/phoenix/overview.html
-* Docs: https://hexdocs.pm/phoenix
-* Forum: https://elixirforum.com/c/phoenix-forum
-* Source: https://github.com/phoenixframework/phoenix
+## Getting Started
+
+### Prerequisites
+- Elixir 1.17+
+- Erlang 27+
+- Node.js 20+ (for assets)
+
+### Setup
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd simpleshop_theme
+
+# Install dependencies
+mix setup
+
+# Start the server
+mix phx.server
+```
+
+Visit:
+- **Shop**: http://localhost:4000
+- **Theme Editor**: http://localhost:4000/admin/theme
+
+### Running Tests
+
+```bash
+mix test
+```
+
+## Project Structure
+
+```
+lib/
+├── simpleshop_theme/           # Core business logic
+│   ├── settings.ex             # Theme settings context
+│   ├── settings/
+│   │   └── theme_settings.ex   # Theme settings schema
+│   ├── media.ex                # Image upload handling
+│   └── theme/
+│       ├── css_generator.ex    # Generates CSS from settings
+│       ├── css_cache.ex        # ETS cache for generated CSS
+│       ├── presets.ex          # 8 theme presets
+│       └── preview_data.ex     # Mock data for previews
+│
+├── simpleshop_theme_web/       # Web layer
+│   ├── components/
+│   │   ├── layouts/            # App and shop layouts
+│   │   ├── page_templates/     # Shared page templates (*.heex)
+│   │   ├── page_templates.ex   # PageTemplates module
+│   │   └── shop_components.ex  # Reusable shop UI components
+│   ├── live/
+│   │   ├── theme_live/         # Theme editor LiveView
+│   │   └── shop_live/          # Public shop LiveViews
+│   └── controllers/
+│       └── error_html.ex       # Themed error pages
+
+assets/css/
+├── app.css                     # Main stylesheet
+├── theme-layer1-primitives.css # Design tokens
+├── theme-layer2-attributes.css # Theme-specific values
+└── theme-layer3-semantic.css   # Component styles
+```
+
+## Routes
+
+| Path | Description |
+|------|-------------|
+| `/` | Shop home page |
+| `/products` | Products listing |
+| `/products/:id` | Product detail page |
+| `/cart` | Shopping cart |
+| `/about` | About page |
+| `/contact` | Contact page |
+| `/admin/theme` | Theme editor (requires auth) |
+| `/dev/errors/404` | Preview 404 page (dev only) |
+| `/dev/errors/500` | Preview 500 page (dev only) |
+
+## Documentation
+
+- [ROADMAP.md](ROADMAP.md) - Future features and improvements
+- [docs/spec.md](docs/spec.md) - Theme system specification
+- [docs/plans/](docs/plans/) - Feature plans
+- [docs/research/](docs/research/) - Design research and guidelines
+
+## Design Philosophy
+
+1. **"One theme, infinite variations"** - Rather than multiple themes, one solid foundation with curated customisation
+2. **Constrained creativity** - Limit choices to prevent poor design outcomes
+3. **No professional photography required** - Works with product mockups
+4. **Mobile-first** - All features work on touch devices
+5. **Ethical design** - No dark patterns or fake urgency
+
+## License
+
+MIT