docs: add complete project documentation

- SPEC.md: project specification and goals
- ARCHITECTURE.md: system design and component descriptions
- database-schema.md: PostgreSQL schema with all tables
- implementation-plan.md: 12-phase implementation guide
- RUNNING.md: deployment and troubleshooting guide
- ORIENTATION.md: context compaction recovery guide
- README.md: project overview and quick start

Family profile: 2 adults, 2 children. Mushroom avoidance for 3/4.
Approval workflow: email proposals, one denial swaps meal.
Tech stack: FastAPI, PostgreSQL, React, Playwright, SendGrid.

README.md

@@ -0,0 +1,76 @@
+# Meal Planner
+
+Self-hosted meal planning system that integrates with Lucky California grocery store, sends weekly meal proposals via email to family members, generates shopping lists, and learns from feedback.
+
+## Background
+
+This project was born out of frustration with meal kit services (Blue Apron → EveryPlate → HungryRoot → Sunbasket) that:
+- Escalate costs to 3x ingredient markup
+- Fall into repetitive meal rhythms
+- Force users to log into apps to manage selections
+- Don't integrate with home pantry items
+
+## Features
+
+- **Grocery Integration**: Scrapes Lucky California weekly ads and sales
+- **Family Approval Workflow**: Email proposals with approve/deny; one denial swaps the meal
+- **Shopping List Generation**: Weekly list grouped by store aisles, highlighting sales
+- **Pantry Integration**: Specify home items to incorporate into suggestions
+- **Web UI**: Modern interface for the whole family
+- **Learning**: Feedback-based meal recommendations
+- **Recipe Images**: Scraped from public recipe sites, AI fallback available
+
+## Architecture
+
+- **Backend**: Python/FastAPI
+- **Database**: PostgreSQL
+- **Frontend**: React + Tailwind CSS
+- **Email**: SendGrid
+- **Hosting**: Docker Compose with nginx reverse proxy
+
+## Documentation
+
+- [Project Specification](docs/SPEC.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Database Schema](docs/database-schema.md)
+- [Implementation Plan](docs/implementation-plan.md)
+- [Running Guide](docs/RUNNING.md)
+
+## Quick Start
+
+```bash
+# Clone and start
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop
+docker-compose down
+```
+
+## Family Profile
+
+Household: 2 adults, 2 children
+- One adult likes mushrooms, one child OK with them
+- Three family members do NOT like mushrooms
+- No allergies
+- Calorie, budget, and health conscious eating
+
+## Approval Workflow
+
+1. System generates 7-day meal plan based on sales, dietary constraints, budget, variety
+2. Email sent to both adults with meal previews
+3. One denial = meal swapped; no denials = auto-approved
+4. Shopping list generated after approval
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Backend | Python 3.11, FastAPI |
+| Database | PostgreSQL 15 |
+| Frontend | React 18, TypeScript, Tailwind |
+| Scraping | Playwright, BeautifulSoup |
+| Email | SendGrid |
+| Hosting | Docker Compose, nginx |