# Agent Guide for reachy_mini_minder

## Context

Reachy Mini Minder is a Reachy Mini robot application that helps users log medication intake and record a headache diary via natural language conversation. It uses the OpenAI Realtime API for voice-first interaction.

**Key Features:**

- Voice-first medication logging
- Headache diary with neurological-standard fields
- Private SQLite storage with CSV/HTML export
- Robot emotion expressions during conversation

## Structure & Navigation

```
reachy_mini_minder/
├── src/reachy_mini_conversation_app/  # Backend Python package (see src/AGENT.md)
│   ├── tools/                         # LLM tools (see tools/AGENT.md)
│   ├── profiles/                      # Conversation profiles (see profiles/AGENT.md)
│   └── prompts/                       # System prompts (see prompts/AGENT.md)
├── frontend/                           # Next.js React UI (see frontend/AGENT.md)
│   ├── src/components/                # Page panels (see components/AGENT.md)
│   ├── src/hooks/                     # Data hooks (see hooks/AGENT.md)
│   └── src/registry/                  # GenUI components (see registry/AGENT.md)
├── tests/                              # Test suite (see tests/AGENT.md)
├── documentation/                      # Docs, design system, case studies, guides
├── .agent/                             # Agent rules and skills
└── pyproject.toml                      # Package configuration
```

### Key Entry Points

- **Backend API**: `src/reachy_mini_conversation_app/console.py` (FastAPI on port 7860)
- **Frontend**: `frontend/` (Next.js on port 3000)
- **Robot app**: `src/reachy_mini_conversation_app/main.py`
- **CLI**: `reachy-mini-minder` (via pyproject.toml scripts)
- **Database**: `src/reachy_mini_conversation_app/database.py`

## Cross-Stack Dependency Map

When implementing features, these are the key chains that must be updated together:

| Feature Type             | Backend                                         | Bridge                                   | Frontend                                                 |
| ------------------------ | ----------------------------------------------- | ---------------------------------------- | -------------------------------------------------------- |
| **New LLM tool with UI** | Tool in `tools/` or `profiles/_locked_profile/` | `emit_ui_component()` in `stream_api.py` | GenUI component in `registry/` + register in `index.tsx` |
| **New REST data**        | Endpoint in `console.py`                        | —                                        | Hook in `hooks/` + wire into component                   |
| **Real-time event**      | `emit_*()` in `stream_api.py`                   | WebSocket event type                     | Handle in `useConversation` or new hook                  |
| **Voice navigation**     | `ui_control.py` tool                            | `emit_ui_navigate()`                     | Handle target in `ChatInterface.tsx`                     |
| **Settings change**      | `update_settings.py` tool                       | `emit_settings_updated()`                | `SettingsPanel` re-fetches data                          |
| **Session lifecycle**    | `console.py` session mgmt                       | `emit_session_event()`                   | `useSession` via DOM event from `useConversation`        |

## Development Workflow

```bash
# Backend
pip install -e .
python src/reachy_mini_conversation_app/console.py  # Standalone API server

# Frontend
cd frontend && npm install && npm run dev

# Tests
pytest tests/
```

## Configuration

- `OPENAI_API_KEY`: OpenAI Realtime API
- `REACHY_MINI_HOST`: Robot connection (optional)

See `.env.example` for all variables.