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>

ROADMAP.md

@@ -0,0 +1,140 @@
+# SimpleshopTheme Roadmap
+
+This document tracks future improvements, features, and known gaps.
+
+## Quick Wins (Low Effort)
+
+### CSS Cache Warming on Startup
+**Status:** Not implemented
+**Effort:** Small
+
+Currently the CSS cache (ETS) is created on startup but not pre-warmed. The first request after server restart generates CSS on-demand.
+
+**Implementation:**
+Add cache warming to `lib/simpleshop_theme/application.ex`:
+```elixir
+# After supervisor starts
+Task.start(fn ->
+  settings = SimpleshopTheme.Settings.get_theme_settings()
+  css = SimpleshopTheme.Theme.CSSGenerator.generate(settings)
+  SimpleshopTheme.Theme.CSSCache.put(css)
+end)
+```
+
+### Navigation Links Between Admin and Shop
+**Status:** Not implemented
+**Effort:** Small
+
+No links exist to navigate between the theme editor (`/admin/theme`) and the public shop (`/`).
+
+**Implementation:**
+- Add "View Shop" button in theme editor header
+- Add "Edit Theme" link in shop header (when authenticated)
+
+### Collection Slug Routes
+**Status:** Partial
+**Effort:** Small
+
+Currently we have `/products` but the original plan included `/collections/:slug` for filtered views by category.
+
+---
+
+## Medium Features
+
+### Sample Content Refresh ("Wildprint Studio")
+**Status:** Planned (see `docs/plans/sample-content.md`)
+**Effort:** Medium
+
+Replace current preview data with POD-focused content:
+- 16 products across 5 categories (Art Prints, Apparel, Homewares, Stationery, Accessories)
+- Nature/botanical primary theme with variety
+- UK-focused (prices in £)
+- Printify API integration for automated mockup generation
+
+### Page Builder (Database-Driven Pages)
+**Status:** Planned (see `docs/plans/page-builder.md`)
+**Effort:** Large
+
+Allow shop owners to build custom pages by combining pre-built sections:
+- Hero, Featured Products, Testimonials, Newsletter, etc.
+- Drag-and-drop section ordering
+- Per-section configuration
+- Database-backed page storage
+
+---
+
+## Future Features (Large Scope)
+
+### Products Context
+Real product management instead of preview data:
+- Product CRUD
+- Variant support (size, colour)
+- Inventory tracking
+- Image galleries
+
+### Orders & Cart Functionality
+Currently cart is display-only with mock data:
+- Session-based cart persistence
+- Add to cart functionality
+- Checkout flow
+- Order creation and history
+
+### Multi-Admin Support
+Currently single-user authentication:
+- Multiple admin users
+- Role-based permissions
+- Audit logging
+
+### Custom Domains
+Allow shops to use their own domain:
+- Domain verification
+- SSL certificate provisioning
+- DNS configuration guidance
+
+### Theme Export/Import
+Backup and restore theme settings:
+- JSON export of all settings
+- Import with validation
+- Preset sharing between shops
+
+### Advanced Theme Features
+- Custom CSS injection
+- Custom JavaScript snippets
+- Code-level overrides for developers
+
+---
+
+## Technical Debt
+
+### Test Coverage
+Phase 9 testing is basic. Areas needing better coverage:
+- Shop LiveView integration tests
+- CSS cache invalidation flow
+- Theme application across all pages
+- Responsive behaviour
+- Accessibility validation
+
+### Error Handling
+- Better error states for missing products
+- Graceful degradation when theme settings are invalid
+- Network error handling in LiveView
+
+---
+
+## Completed (For Reference)
+
+### Phase 1-8: Theme Editor ✅
+- Theme settings schema and persistence
+- CSS three-layer architecture
+- 8 theme presets
+- All customisation controls
+- Logo/header image uploads
+- SVG recolouring
+- Preview system with 7 pages
+
+### Phase 9: Storefront Integration ✅
+- Public shop routes (/, /products, /products/:id, /cart, /about, /contact)
+- Shared PageTemplates for shop and preview
+- CSS injection via shop layout
+- Themed error pages (404/500)
+- Dev routes for error page preview