ponshu-room-lite/docs/README.md

# 📚 Ponshu Room Lite - Documentation Index

**Last Updated**: 2026-01-21  
**Purpose**: Central navigation for all project documentation  
**Audience**: AI collaborators (Claude, Antigravity, Gemini) + Human developers

---

## 🚀 Quick Start (For New AI Collaborators)

**Read these first**:
1. [CURSOR_CHAT_MASTER_CONTEXT.md](architecture/CURSOR_CHAT_MASTER_CONTEXT.md) - Antigravity handoff context
2. [PROJECT_TODO.md](PROJECT_TODO.md) - Current tasks and priorities
3. [DARK_MODE_COLOR_GUIDELINES.md](DARK_MODE_COLOR_GUIDELINES.md) - Critical: Read before any UI changes

---

## 📋 Task Management

| Document | Purpose | When to Use |
|----------|---------|-------------|
| [PROJECT_TODO.md](PROJECT_TODO.md) | **Active tasks, deferred work** | Before starting any work |
| [PROJECT_BACKLOG_MASTER.md](PROJECT_BACKLOG_MASTER.md) | High-level roadmap (52 tasks) | Strategic planning |
| [UI_UX_BACKLOG.md](UI_UX_BACKLOG.md) | UI/UX improvements (18 tasks) | Design work |

---

## 🎨 Design & Implementation Guidelines

| Document | Purpose | When to Use |
|----------|---------|-------------|
| [DARK_MODE_COLOR_GUIDELINES.md](DARK_MODE_COLOR_GUIDELINES.md) | **Critical: Dark Mode patterns** | Before ANY UI changes |
| [PHASE_2_IMPLEMENTATION_PLAN.md](PHASE_2_IMPLEMENTATION_PLAN.md) | Phase 2 feature specs | Implementing Phase 2 features |
| [gamification_specification.md](gamification_specification.md) | Badge/Level/EXP system | Gamification work |

---

## 🏗️ Architecture & Technical

| Document | Purpose | When to Use |
|----------|---------|-------------|
| [ARCHITECTURE_DECISION_RECORD.md](ARCHITECTURE_DECISION_RECORD.md) | Key technical decisions | Understanding "why" |
| [CURSOR_CHAT_MASTER_CONTEXT.md](architecture/CURSOR_CHAT_MASTER_CONTEXT.md) | Antigravity handoff | Understanding project history |
| [TRANSLATION_STATUS.md](TRANSLATION_STATUS.md) | i18n status | Translation work |

---

## 🎯 Feature-Specific Documentation

### Business Mode
- [BUSINESS_MODE_SPECIFICATION.md](BUSINESS_MODE_SPECIFICATION.md) - Business features (menu creation, pricing)

### Future Plans
- [future_plan.md](future_plan.md) - Archived long-term ideas
- [RECOMMENDATION_EXPANSION_PLAN.md](RECOMMENDATION_EXPANSION_PLAN.md) - "あわせて飲みたい" expansion (Phase 3)

---

## 🔍 Finding Information

### "Where should I...?"

**Q: Fix a Dark Mode visibility issue?**  
→ Read [DARK_MODE_COLOR_GUIDELINES.md](DARK_MODE_COLOR_GUIDELINES.md) first  
→ Check [PROJECT_TODO.md](PROJECT_TODO.md) for deferred Dark Mode fixes

**Q: Add a new feature?**  
→ Check [PROJECT_TODO.md](PROJECT_TODO.md) for current priorities  
→ Review [PROJECT_BACKLOG_MASTER.md](PROJECT_BACKLOG_MASTER.md) for planned features  
→ See if it conflicts with [PHASE_2_IMPLEMENTATION_PLAN.md](PHASE_2_IMPLEMENTATION_PLAN.md)

**Q: Fix a badge/level/gamification issue?**  
→ [gamification_specification.md](gamification_specification.md)

**Q: Understand past decisions?**  
→ [ARCHITECTURE_DECISION_RECORD.md](ARCHITECTURE_DECISION_RECORD.md)  
→ [CURSOR_CHAT_MASTER_CONTEXT.md](architecture/CURSOR_CHAT_MASTER_CONTEXT.md)

**Q: Add business mode features?**  
→ [BUSINESS_MODE_SPECIFICATION.md](BUSINESS_MODE_SPECIFICATION.md)

**Q: Find a TODO/task?**  
→ [PROJECT_TODO.md](PROJECT_TODO.md) - Active/urgent tasks  
→ [PROJECT_BACKLOG_MASTER.md](PROJECT_BACKLOG_MASTER.md) - All 52 tasks  
→ [UI_UX_BACKLOG.md](UI_UX_BACKLOG.md) - UI/UX-specific

---

## 🚨 Critical Rules (DO NOT SKIP)

### Before Modifying UI Code:
1. ✅ Read [DARK_MODE_COLOR_GUIDELINES.md](DARK_MODE_COLOR_GUIDELINES.md)
2. ✅ Never use `Colors.blue`, `Color(0xFF...)` hardcoded colors
3. ✅ Never use `brightness == Brightness.dark` manual checks
4. ✅ Always use `Theme.of(context).colorScheme.xxx`

### Before Adding Features:
1. ✅ Check [PROJECT_TODO.md](PROJECT_TODO.md) for current priorities
2. ✅ Check [PROJECT_BACKLOG_MASTER.md](PROJECT_BACKLOG_MASTER.md) for planned work
3. ✅ Run `flutter analyze` before and after changes

### Before Committing:
1. ✅ Update relevant documentation
2. ✅ Run `flutter analyze` and fix new warnings
3. ✅ Test in both Light and Dark modes

---

## 📦 Document Status

| Status | Meaning |
|--------|---------|
| ✅ Complete | Up-to-date, use as reference |
| 🔄 Needs Update | Partially outdated, use with caution |
| 📝 In Progress | Being actively updated |
| 🗃️ Archived | Historical reference only |

### Current Status

- ✅ DARK_MODE_COLOR_GUIDELINES.md
- ✅ PROJECT_TODO.md
- ✅ CURSOR_CHAT_MASTER_CONTEXT.md
- ✅ ARCHITECTURE_DECISION_RECORD.md
- ✅ gamification_specification.md
- 🔄 PROJECT_BACKLOG_MASTER.md (needs Dark Mode status update)
- 🔄 UI_UX_BACKLOG.md (needs Coach Mark status update)
- 📝 PHASE_2_IMPLEMENTATION_PLAN.md (being created)
- 🗃️ future_plan.md (archived)

---

## 🤝 For AI Collaborators

### Communication Protocol
- Update [PROJECT_TODO.md](PROJECT_TODO.md) when tasks change
- Leave comments in code explaining "why", not "what"
- Follow guidelines strictly to avoid breaking existing work

### Handoff Checklist
When transferring work to another AI:
- [ ] Update [PROJECT_TODO.md](PROJECT_TODO.md) with progress
- [ ] Document any deferred decisions
- [ ] Note any discovered issues
- [ ] Update relevant spec documents

---

## 📞 Contact & Maintenance

**Project Owner**: User (Maita)  
**Primary AI**: Claude Sonnet 4.5 (via Cursor)  
**Collaborators**: Antigravity, Gemini  

**To update this index**: Edit this file when adding/removing documentation.

**Last Major Update**: 2026-01-21 (Dark Mode Phase 1 completion)

---

## 🗺️ Document Map (Visual)

```
docs/
├── README.md (← YOU ARE HERE)
├── PROJECT_TODO.md ⭐ START HERE
├── PROJECT_BACKLOG_MASTER.md (52 tasks)
├── UI_UX_BACKLOG.md (18 UI tasks)
│
├── Guidelines/
│   ├── DARK_MODE_COLOR_GUIDELINES.md ⭐ CRITICAL
│   └── TRANSLATION_STATUS.md
│
├── Implementation Plans/
│   ├── PHASE_2_IMPLEMENTATION_PLAN.md (Phase 2 features)
│   ├── BUSINESS_MODE_SPECIFICATION.md
│   ├── gamification_specification.md
│   └── RECOMMENDATION_EXPANSION_PLAN.md (Phase 3)
│
├── Architecture/
│   ├── ARCHITECTURE_DECISION_RECORD.md
│   ├── CURSOR_CHAT_MASTER_CONTEXT.md (Antigravity handoff)
│   └── (other arch docs)
│
└── Archive/
    └── future_plan.md (historical)
```