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.

meal-planner-plan.md

@@ -0,0 +1,95 @@
+# Meal Planner System
+
+## Goal
+Self-hosted meal planning system that sources ingredients from Lucky California sales, generates weekly meal plans, sends approval requests to you and your wife via email, and creates actionable shopping lists.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    MealPlanner App                       │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
+│  │ Scraper  │  │ Recipe   │  │ Meal     │  │ Notif.   │  │
+│  │ Service  │  │ Engine   │  │ Planner  │  │ Service  │  │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  │
+│       │             │             │             │         │
+│  ┌────┴─────────────┴─────────────┴─────────────┴────┐  │
+│  │              PostgreSQL Database                   │  │
+│  └───────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+         │                │                │
+         ▼                ▼                ▼
+  Lucky California   SendGrid Email    Web UI (React)
+  (scraper)         / Twilio WA       (local + reverse proxy)
+```
+
+## Tech Stack
+- **Backend**: Python/FastAPI
+- **Database**: PostgreSQL
+- **Frontend**: React + Tailwind CSS
+- **Scraping**: Playwright for Lucky California
+- **Email**: SendGrid
+- **Image Gen**: AI (on-demand fallback only)
+- **Hosting**: Docker Compose + reverse proxy
+
+## Project Structure
+```
+mealplanner/
+├── docker-compose.yml
+├── backend/
+│   ├── app/
+│   │   ├── main.py
+│   │   ├── scraper/
+│   │   │   ├── lucky_ca.py
+│   │   │   └── recipe_scraper.py
+│   │   ├── models/
+│   │   ├── api/
+│   │   └── services/
+│   └── requirements.txt
+└── frontend/
+    ├── src/
+    └── package.json
+```
+
+## Tasks
+
+### Phase 1: Foundation
+- [ ] Set up Docker Compose with PostgreSQL, backend, frontend services
+- [ ] Create PostgreSQL schema (recipes, meal_plans, family_profiles, home_items, feedback)
+- [ ] Build FastAPI skeleton with basic CRUD endpoints
+- [ ] Set up reverse proxy (nginx or Caddy) for local + remote access
+
+### Phase 2: Scraping
+- [ ] Build Lucky California scraper (weekly ad + product catalog)
+- [ ] Scrape recipe images from public recipe sites (NYT, AllRecipes, etc.) as primary image source
+- [ ] Store scraped data in PostgreSQL
+
+### Phase 3: Recipe & Meal Engine
+- [ ] Recipe database with ingredient tags, dietary info, cuisine types
+- [ ] Meal planner that selects meals based on: family profile (mushroom avoidance), budget, seasonal ingredients, variety
+- [ ] "Never suggest" and rating feedback loop to train preferences
+- [ ] Incorporate home pantry items as constraints
+
+### Phase 4: Notifications & Approval
+- [ ] SendGrid email integration for weekly meal approval
+- [ ] Approval workflow: meal proposed → email to both → one deny = swap meal
+- [ ] Email contains: meal name, image, ingredients, cooking time
+- [ ] Store approval/denial history for learning
+
+### Phase 5: Shopping List & UI
+- [ ] Generate weekly shopping list grouped by Lucky California aisle/sales
+- [ ] React web UI for family members to: view meals, approve/deny, adjust home pantry items, view recipes
+- [ ] Print-friendly recipe view
+- [ ] Feedback mechanism ("Never suggest this", "Loved it", etc.)
+
+### Phase 6: Polish
+- [ ] AI image generation as fallback when scraped images unavailable
+- [ ] Meal variety analysis (sauce/ingredient rhythm detection)
+- [ ] Budget tracking and optimization
+
+## Done When
+- [ ] Family receives email each week with proposed meals
+- [ ] Shopping list reflects actual Lucky California sales and in-season items
+- [ ] Home pantry items influence meal suggestions
+- [ ] Web UI accessible to non-technical family members
+- [ ] System learns from feedback over time