Add Dial-In Guide for Beginners to Home Page

[hessius]

Background

New users often struggle with dialing in espresso — it's the most common beginner pain point. The Meticulous machine ships with stock profiles, but users don't know which to start with or how to iterate based on taste feedback. Meticulous is releasing educational videos on the subject that could be integrated into the MCP knowledge base.

This feature introduces a guided "Dial In" wizard that walks beginners through the full cycle: select a coffee → pick a profile → brew → taste → get AI-powered recommendations → iterate. The Espresso Aficionados Coffee Compass (#261) provides the taste feedback mechanism.

Current State

Home Page

• StartView.tsx has 5 main buttons (profile generation, catalogue, pour-over, settings, about)
• Navigation uses ViewState union type with setView() to switch views
• The home page is the natural entry point for this wizard

Profile System

• Stock profiles exist on the machine; GET /api/machine/profiles lists all available profiles
• Profile data includes temperature, pressure curves, flow targets — all the parameters that affect extraction
• The MCP knowledge base (apps/mcp-server/) contains profiling knowledge that could be extended with dial-in guidance

Machine Commands

• Profiles can be selected with the machine, shots are monitored via WebSocket telemetry
• Shot data is retrieved via GET /api/shots/{profile_name}/{date}/{filename}
• Analysis: POST /api/shots/analyze-llm for AI-powered analysis

AI Analysis

• prompt_builder.py already contains PROFILING_KNOWLEDGE with troubleshooting mappings (sour → grind finer, bitter → lower temp, etc.)
• The Gemini analysis returns structured sections including profile recommendations
• This knowledge is currently only activated post-hoc — never proactively during a dial-in session

UX Concept — Dial-In Wizard Flow

Step 1: Coffee Selection

• User enters coffee details: roast level (light/medium/dark), origin (optional), process (optional), roast date (optional)
• These inform the AI's starting recommendations

Step 2: Profile Recommendation

• Based on coffee details, AI recommends a starting profile from the user's catalogue
• Shows 2–3 profile suggestions with brief rationale
• User selects one (or picks any profile manually)
• Option: "I already have a profile in mind" to skip recommendation

Step 3: Preparation Checklist

• Beginner-friendly prep steps: dose, grind setting, WDT, tamp
• Checklist format with optional explanations
• Profile-specific details (recommended dose, grind range from info_* variables)

Step 4: Brew & Monitor

• User runs the selected profile on the machine
• Option to view live shot telemetry (reuses existing LiveShotView components)
• Waits for shot completion

Step 5: Taste Feedback (Espresso Aficionados Compass)

• Interactive taste input using the Coffee Compass from Integrate Espresso Afficionados Compass Guide for taste-based shot analysis #261
• Axes: sour ↔ bitter, thin/watery ↔ harsh/astringent, strength (weak ↔ intense)
• Additional quick tags: "salty", "sweet", "balanced", "muddy", "clean"
• Visual compass display showing where the shot lands

Step 6: AI Recommendations

• Sends shot data + taste feedback + coffee details to Gemini
• Returns prioritized, beginner-friendly recommendations:
  • "Grind 2 clicks finer" (not "decrease particle size")
  • "Increase dose by 0.5g" (specific, actionable)
  • "Try increasing temperature by 1°C"
• Recommendations ranked by impact and confidence
• Each recommendation has a brief "why" explanation

Step 7: Iteration History

• Shows the dial-in session history: Shot 1 → feedback → changes → Shot 2 → feedback → ...
• Visual progress indicator (e.g., compass positions getting closer to center over iterations)
• "Try Again" button loops back to Step 3 with updated parameters
• "I'm Happy" button saves the session and final profile settings

Implementation Plan

Backend

1. New apps/server/services/dialin_service.py:

   • create_session(coffee_details) → returns session ID and profile recommendations
   • record_iteration(session_id, shot_ref, taste_feedback) → stores iteration data
   • get_recommendations(session_id, iteration) → calls Gemini with full session context
   • complete_session(session_id) → finalizes and saves session summary

2. New apps/server/models/dialin.py:

   • DialInSession: coffee_details, profile_name, iterations[], status
   • DialInIteration: shot_ref, taste_feedback, ai_recommendations, timestamp
   • TasteFeedback: compass coordinates (sour_bitter, thin_harsh), strength, tags[]

3. New endpoints in apps/server/api/routes/dialin.py:

   POST /api/dialin/session              — create session with coffee details
   GET  /api/dialin/session/{id}         — get session state
   POST /api/dialin/session/{id}/taste   — record taste feedback for current shot
   GET  /api/dialin/session/{id}/recommend — get AI recommendations
   POST /api/dialin/session/{id}/complete — finalize session
   GET  /api/dialin/sessions             — list past dial-in sessions
   

4. New Gemini prompt template for dial-in recommendations:

   • Input: coffee details + profile parameters + shot data + taste compass coordinates + session history
   • Output: beginner-friendly, prioritized recommendations with specific values
   • Context window includes all prior iterations for trend awareness

Frontend

5. New DialInWizard.tsx component:

   • Multi-step wizard with progress indicator
   • State machine managing the 7 steps
   • Back/Next navigation with step validation

6. Step components:

   • DialInCoffeeStep.tsx — coffee detail inputs (roast, origin, process)
   • DialInProfileStep.tsx — AI profile recommendations + manual selection
   • DialInPrepStep.tsx — preparation checklist
   • DialInBrewStep.tsx — live shot monitoring (reuses LiveShotView components)
   • DialInTasteStep.tsx — Espresso Compass input from Integrate Espresso Afficionados Compass Guide for taste-based shot analysis #261
   • DialInRecommendStep.tsx — AI recommendations display
   • DialInHistoryStep.tsx — iteration timeline with progress tracking

7. Add "Dial In" button to StartView.tsx — prominent position for beginners

8. Add 'dial-in' to ViewState type in types/index.ts

AI / Knowledge Base Integration

9. Extend MCP knowledge base with dial-in specific guidance:

   • Starting parameters by roast level
   • Common beginner mistakes and fixes
   • Compass coordinate → adjustment mappings
   • Meticulous video content summaries (when available)

10. Dial-in-specific prompt in prompt_builder.py — simplified language, prioritized recommendations, iteration-aware context

Dependencies

• Integrate Espresso Afficionados Compass Guide for taste-based shot analysis #261 (Espresso Aficionados Compass Guide) — provides the TasteCompassInput component for Step 5
• Create new top-level Shot Analysis view on home page #259 (Shot Analysis view) — shot listing infrastructure can be reused
• Existing profile and shot APIs provide the foundation

Acceptance Criteria

• Dial-In wizard accessible from home page
• Coffee details capture (roast level, origin, process)
• AI recommends starting profiles based on coffee details
• Preparation checklist with profile-specific details
• Live shot monitoring integration
• Espresso Compass taste feedback input (Integrate Espresso Afficionados Compass Guide for taste-based shot analysis #261 dependency)
• AI returns beginner-friendly, prioritized recommendations with specific values
• Iteration history showing progression across multiple shots
• "Try Again" loops back with updated parameters
• Session persistence (can resume or review past sessions)
• All labels use i18n keys
• Unit tests for dial-in service and endpoints
• Frontend tests for wizard flow and step validation
• Mobile-friendly layout for all wizard steps

Key Files

Area	File	Purpose
Backend	apps/server/services/dialin_service.py	Session management + AI integration
Backend	apps/server/models/dialin.py	Data models
Backend	apps/server/api/routes/dialin.py	API endpoints
Backend	apps/server/prompt_builder.py	Dial-in prompt template
Frontend	apps/web/src/components/DialInWizard.tsx	Main wizard component
Frontend	apps/web/src/components/DialIn*.tsx	Step components (7 files)
Frontend	apps/web/src/views/StartView.tsx	Home button
Frontend	apps/web/src/types/index.ts	ViewState extension
KB	apps/mcp-server/	Extended knowledge base

[hessius]

Shipped in v2.3.0 🎉