🧑🍳 Let’s Cook
Audience: User, Org Admin, Developer, Support Related: Controls And Timers · Overview · Voice Assistants · Displays
Let’s Cook is Blackcap’s guided-cooking mode. A session presents preparation, ingredients, instructions, progress, timers, step completion, and session controls across Admin, Mobile, Hosted/Kiosk, voice, and display-only e-ink surfaces.
Sessions can show the full recipe before the current step, include a preparation step, track current-step ingredients, restore the display’s default content on completion, and record bounded session history for diagnostics and review.
Let’s Cook is Blackcap’s active cooking mode. It shares one durable cooking session across Admin, Mobile, Kiosk, hosted display receivers, and the attached e-ink renderer. The session tracks recipe steps, used ingredients, active timers, side reminders from the meal plan, restore behavior, and compact cooking history.
The current production design intentionally favors reliability over partial-refresh cleverness. The attached Waveshare 13.3" HAT (K) display uses full refresh only for Let’s Cook.
Surfaces
Let’s Cook is available from:
- Admin — full session control, timers, auto-mark controls, recent session history, and debugging visibility.
- Mobile — compact cooking controller with timers and ingredient/step controls. Mobile does not expose recent session history.
- Kiosk — tokenized display mini-app support for starting/continuing cooking sessions, including compact side reminders when a session is started from a meal-plan slot.
- Attached e-ink — passive cooking display: recipe, ingredients, steps, static timer indicator, and side reminders. E-ink does not expose timer-start controls.
- Remote Raspberry Pi client — GCP renders the Let’s Cook preview directly for the destination profile, a paired Pi pulls the changed preview, and the attached Type K panel performs one full four-level grayscale refresh.
Let’s Cook normally cooks one recipe at a time, but it now supports one special multi-stage case: direct Component Recipes selected during parent-recipe preflight. This does not enable general recursive multi-recipe cooking; Component processing is limited to one parent → direct Component level.
Meal Component settings are provisional until cooking
For a dated Meal, Component Recipe choices are shared across Meal Planner workflows rather than re-created independently. Blackcap derives the normal Component batch from the consuming Meal Recipe multiplier(s) and stores only explicit user decisions or true multiplier overrides. Shopping can resolve make/keep early when it needs to know which ingredients to buy. Plan Meal normally does not ask those questions and instead conservatively schedules unresolved Component work.
Let’s Cook is the final checkpoint. The same rich Component card shows the Component thumbnail, parent Recipe context, quantity/yield information and batch control. A deterministic sequential Meal also exposes the existing placement control. A current AI Meal Plan already coordinates Component timing, so the cook can keep that timing or mark the Component as already prepared; already-prepared work is omitted without regenerating the AI plan. Final choices are saved back to the dated Meal.
The Meal chooser in Start cooking by recipe or meal shows only today and future Meals during ordinary browsing. It uses a Meal image and edited Meal name when available; otherwise it groups the underlying Recipe/Meal Item thumbnails and names under the Meal Slot instead of presenting the long automatic concatenated title. Meal Planner can still deep-link a past dated Meal directly into Let’s Cook.
Direct Component Recipe preflight
When a non-Component parent recipe contains a structured ingredient whose name exactly matches an active same-organization recipe with Recipe Type Component, Let’s Cook offers that Component during start preflight. The user can make all, some, or none from scratch by checking or unchecking each Make from scratch choice, then choosing Continue. Cancel abandons the Let’s Cook start. Component Recipes are never inspected for additional Components.
Each card reads Make Component from scratch for and shows the parent recipe context immediately with a small thumbnail and recipe name. The UI supports more than one parent row even though current Let’s Cook starts from one main recipe, so the surface is ready for future multi-parent cooking without changing the Component card design. The Component recipe's time/cleanup/effort pills remain to the left of the parent list and the Component description follows below.
For each selected Component, the preflight shows the parent quantity required, structured Component yield when available, the recommended batch multiplier, and expected output. The recommendation comes from the same server-side Component quantity planner used by Shopping Lists: parent multiplier is applied first, compatible units use the normal measurement conversion service, and the existing discrete ingredient rules choose the smallest valid multiplier that makes enough. Missing/incompatible yield stays usable through manual multiplier selection.
The multiplier is a recommendation. The user can override it; Blackcap warns when the expected output is below the parent's required quantity. Parent and Component multipliers are persisted independently.
After choosing Make from scratch, the user also chooses when to make that Component:
- Before main recipe — useful for doughs, fillings, stocks, and other prerequisites.
- After main recipe — useful for icing, finishing sauces, toppings, and similar Components that should be prepared after the main recipe stage.
The session snapshots this decision and executes stages as:
before Components → parent recipe → after Components
Refresh/resume preserves the chosen Component recipe, required quantity, recommendation, user-selected multiplier, expected yield, timing, and completion state. Finishing a Component advances automatically to the next staged recipe. The parent recipe can show whether a direct Component was prepared, will be prepared after the main stage, or is being treated as already available.
A Component started directly from Recipe Library uses ordinary Let’s Cook multiplier behavior because there is no parent requirement to plan against.
One active recipe at a time
A multi-recipe Component session is still one durable Let’s Cook session, but every cooking display presents only the recipe that is currently active. Blackcap does not stack completed Component ingredients/instructions together with the parent or later Components. When the current recipe finishes, the session automatically advances to the next staged recipe and the display switches with it.
For example, two Components scheduled before the parent and one after it render in this sequence:
Component 1 → Component 2 → Parent recipe → Component 3
This is a display-fit rule as well as a presentation rule. Full-screen browser output, remote displays, and e-ink previews are rendered from the active recipe scope so a multi-recipe session does not require scrolling through other recipe stages. Browser full-screen mode compacts/scales the active recipe rather than introducing an internal cooking-content scrollbar.
Finish Let’s Cook and Kitchen Inventory
Admin and Mobile both finish through the same durable completion transaction and update the recipe's shared Made It data. The completion review supports recipe rating, cleanup rating, notes, and Mobile Made It photo capture.
Inventory handling follows the active organization's Kitchen Inventory mode:
- Full Inventory Tracking — only ingredients marked Used are consumed, oldest physical Package first. Admin can review/correct package fullness; Mobile stays compact and accepts Blackcap's calculated depletion. If the final active Package is emptied, the logical Kitchen Inventory item becomes Not On Hand.
- On Hand Only — no Product/package quantity is consumed. Admin and Mobile show only a compact On Hand / Not On Hand decision for each matched used logical ingredient. Put Away and Product-level controls do not participate.
- Track Kitchen Inventory off — the cooking session and Made It review complete normally without inventory mutation.
Component Recipes made from scratch continue to suppress consumption of the corresponding finished Component ingredient in the parent recipe so inventory is not depleted twice.
Attached e-ink refresh policy
Repeated partial refreshes proved unreliable on the Waveshare 13.3" HAT (K) panel: text could lighten, region replacement could garble, and timer countdown digits were especially poor. Let’s Cook therefore uses the safe model:
Controller state changes immediately
↓
Durable session state is saved
↓
Display refresh is marked pending
↓
Pi local panel: 10-second full-refresh coalescing
GCP remote client: immediate server preview generation
↓
Remote client polls every 5 seconds during Let’s Cook
↓
Physical e-ink refreshes only when the preview version changes
For both the attached local_eink preset and the remote_pi_client Type K preset, the Let’s Cook renderer resolves the display profile before drawing. It creates a 960 × 680 Pillow L canvas and publishes only the final four-gray PNG (0, 128, 192, 255). Hosted and kiosk targets continue to render RGB assets.
Attached e-ink refresh rules:
- ingredient complete/incomplete → queued full refresh
- step complete/incomplete → queued full refresh
- auto-used ingredients from step completion → queued full refresh
- timer start/pause/resume/cancel/complete → queued full refresh
- active timer countdown ticks → no e-ink refresh
- ending a session → release cooking state and restore the display’s default content
A locally attached Pi panel retains the roughly ten-second server-side coalescing window for normal session updates. For a GCP-hosted remote_pi_client, every durable Let’s Cook action renders the remote preview immediately with no server-side debounce, while the retry watcher remains available for failures or concurrent-state races. The client temporarily advertises a five-second pull interval instead of the normal 30 seconds.
The Waveshare full refresh remains the dominant delay, typically about 23–24 seconds. Changes made while that waveform is running are naturally coalesced into the newest server artifact. After each Let’s Cook physical refresh, the client polls the server immediately rather than waiting another five seconds, then resumes the five-second interval when no newer preview exists.
Ending a normal Let’s Cook session explicitly returns the display to its configured default content. Assigning another content type remains an intentional takeover: the session ends without restoring first because the newly assigned content immediately replaces it.
Required service
The display refresh loop is handled by:
blackcap_lets_cook_timer_refresh.service
Despite the historical name, this service now does more than timer refresh. It is the Let’s Cook watcher for:
- coalescing pending full e-ink refreshes;
- retrying
pending_display_retrystates after the display was busy; - updating completed timers in session state;
- avoiding live e-ink countdown pushes.
Install and enable it through the scheduled-operations installer. The same service name uses a host-appropriate scope:
- full-server Pi: attached local e-ink only, 10-second cadence;
- GCP: remote Raspberry Pi client previews only, 2-second cadence;
- client-only Pi: not installed.
For a Raspberry Pi with an attached local e-ink display:
sudo cp /home/pi/Blackcap-Pi/systemd/blackcap_lets_cook_timer_refresh.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now blackcap_lets_cook_timer_refresh.service
sudo systemctl restart inky_admin.service
The Pi service runs:
/home/pi/inky_env/bin/python3 /home/pi/Blackcap-Pi/run_lets_cook_timer_refresh.py --watch --interval 10 --quiet
The GCP scheduled-operations installer creates the same service with:
/opt/blackcap_env/bin/python3 /opt/Blackcap/run_lets_cook_timer_refresh.py --watch --interval 2 --remote-clients --quiet
It is intentionally separate from Gunicorn. The web request stays quick and durable; preview and hardware work happen in the watcher/client processes.
Removed partial-refresh worker
The persistent partial-refresh worker is no longer required and should not be installed:
blackcap_lets_cook_display_worker.service
run_lets_cook_display_worker.py
If a device tested earlier partial-refresh builds, remove the old worker:
sudo systemctl disable --now blackcap_lets_cook_display_worker.service 2>/dev/null || true
sudo rm -f /etc/systemd/system/blackcap_lets_cook_display_worker.service
rm -f /home/pi/Blackcap-Pi/systemd/blackcap_lets_cook_display_worker.service
rm -f /home/pi/Blackcap-Pi/run_lets_cook_display_worker.py
rm -rf /tmp/blackcap_lets_cook_display_queue
rm -f /tmp/blackcap_eink_partial_state.json
sudo systemctl daemon-reload
sudo systemctl reset-failed
push_eink_image.py remains at the project root and is still used for full attached e-ink pushes:
/home/pi/Blackcap-Pi/push_eink_image.py
All e-ink hardware access must continue to use the shared display lock.
Display lock and retry behavior
Let’s Cook uses the same shared display lock file as menu, recipe render, display restore, and deep clean operations:
/tmp/inky_menu_display.lock
If an attached e-ink push finds an existing lock, the helper checks the stored PID:
- live PID → another display operation is active; do not disturb it;
- dead PID → stale lock; remove and retry safely.
If the display is legitimately busy, the API still saves the Let’s Cook state and rendered preview. The display state is marked pending_display_retry; the blackcap_lets_cook_timer_refresh.service watcher retries later.
Meal-plan and implicit start behavior
Let’s Cook has two different start modes:
- Explicit recipe start — Admin/Mobile recipe search and recipe-page controls pass a recipe id, so Let’s Cook starts that recipe directly.
- Implicit display start — Kiosk and future voice-assistant starts do not identify a recipe directly, so Blackcap chooses the next applicable recipe-backed meal-plan item.
Implicit starts use lets_cook_selection_service.choose_next_meal_plan_recipe() and must not fall back to a saved recipe. If there is no upcoming meal-plan recipe, no session starts. This prevents the old unsafe behavior where a kiosk-style start could fall back to the first saved recipe.
Selection order for implicit starts:
- currently active timed meal slot containing a recipe-backed item;
- next upcoming timed meal slot containing a recipe-backed item;
- untimed meal-plan slots ordered by date, slot order, and entry order;
- no session if no recipe-backed item exists in the 7-day window.
When a meal-plan slot has additional recipe-backed entries, Let’s Cook can include them through the existing meal-plan slot recipe context rather than choosing a random recipe.
Timer behavior
Admin and Mobile are the live timer surfaces. They show the actual countdown and play the completion alarm.
Attached e-ink displays only show a static timer indicator, for example:
Active timer: Orzo simmer (12 min)
Timer behavior:
- starting a timer queues a full e-ink refresh with the static active timer indicator;
- countdown seconds do not refresh the e-ink display;
- pausing, resuming, cancelling, completing, or auto-completing queues a full e-ink refresh;
- when a web/mobile timer reaches zero, the controller sounds a repeating alarm until the cook stops/cancels it with 🛑 or extends/restarts it with +1, +5, or 🔁.
Timer controls on Admin and Mobile use compact icon buttons:
- ⏸️ pause while running
- ▶️ resume while paused
- ✅ mark done while running or paused
- 🔁 restart
- 🛑 stop/cancel
- +1 / +5 appear only after a timer is done, where they restart for one or five additional minutes
Timer controls are not rendered on the attached e-ink cooking display.
Voice timer start behavior
Voice-assistant start timer uses lets_cook_service.start_timer_for_current_incomplete_step(). It intentionally looks only at the first incomplete recipe step and starts the first timer candidate in that step that has not already completed or been cancelled. It does not skip ahead to a later recipe step just because a later step has a timer.
If the current incomplete step has no timer, Blackcap responds:
I don't see a timer in the current step.
If an active/paused timer already exists in the current step, Blackcap reports that a timer is already running for this step rather than starting a duplicate.
Voice end-session keyword
The clear voice keyword for ending a cooking session is:
end Let’s Cook
Accepted equivalents should map to END_LETS_COOK, including end the Let’s Cook session, end cooking with Blackcap, and finish cooking with Blackcap. Bare stop should not end the session because stop timer is a timer command.
Ingredient auto-completion
Admin and Mobile include an Auto-mark ingredients control near the cooking display selector:
- On · obvious matches is the default. When a completed instruction has high-confidence ingredient matches, Blackcap marks those ingredients used and shows a notice such as
Marked 3 ingredients used. - Off · manual only disables automatic ingredient marking from step completion on that controller.
The setting is intentionally controller-local and stored in browser localStorage.
Per-Recipe Meal-side reminders
The preserved Recipe → Let’s Cook action can still be started from one recipe-backed Meal Planner entry. In that per-Recipe path Blackcap keeps the session focused on the selected Recipe and shows the other entries as compact side reminders. The separate Meal Slot → Let’s Cook Meal action described below is the true multi-Recipe cooking path.
Example:
Spaghetti & Meatballs w/ Bread and Salad
The Let’s Cook header shows:
Sides: Bread · Salad
Side reminders appear in Admin, Mobile, Kiosk, and the attached e-ink recipe header. They are reminders only; they do not create additional recipe tabs or multi-recipe state.
Kiosk starts that automatically choose the current/next meal-plan recipe preserve the meal-plan entry id, so side reminders are available there too. Starting a saved recipe directly from kiosk search is recipe-only unless a meal-plan entry is supplied.
Completion, Kitchen Inventory, and Made It
Ending a successful Let’s Cook session commits the cooking session first. Blackcap then performs idempotent Inventory accounting from the persisted session snapshot and restores normal display/session behavior; an Inventory reconciliation error is recorded as retryable and does not trap or fail cooking completion.
Inventory accounting:
- considers only persisted ingredients whose
usedstate is true; - uses the scaled structured quantity/unit saved for the session rather than reparsing display text;
- consumes compatible physical Packages oldest first, using purchase time when known and creation time as the fallback;
- never creates negative inventory to compensate for missing stock;
- records unknown/incompatible usage without inventing a precise amount;
- avoids consuming both a Component made from scratch and the finished parent Component;
- respects the organization’s Track Kitchen Inventory setting;
- uses correlation keys so a completion retry cannot subtract the same ingredient twice.
- bridges volume and weight when needed using the platform Ingredient Density catalog, so a recipe using
1 cupof all-purpose flour can reduce a Package tracked inlb/oz; same-dimension conversions such asTbsp→fl ozremain ordinary unit conversion, and an unknown cross-dimension ingredient uses the explicit Water/default fallback with low confidence.
The completion preview uses the same ingredient-aware conversion service as final Inventory consumption. This is important for density bridges: the preview and the committed package quantity must agree rather than showing a unit-mismatch warning for a valid flour cup→pound conversion.
Before Admin completes a session, Blackcap opens a completion review. It lists the used ingredients and their source quantities, then shows the matching exact Product/physical Package rows in oldest-first order. Each row shows the amount before cooking and Blackcap's estimated amount left. The shared fullness slider can correct the estimate before automatic depletion is finalized inside the same inventory-completion transaction. If completion leaves a package-tracked ingredient with no non-empty physical Packages, Blackcap also marks the logical Kitchen Inventory item Not On Hand. Emptying one Package does not hide the ingredient while another Package still has stock. This gives Admin a full Product-level reconciliation without changing recipe quantities.
The same Admin completion dialog also captures the shared Recipe-level recipe review rating, cleanup rating, and notes. Existing Made It values are prefilled so completing another session updates the Recipe's existing Made It data rather than creating per-session ratings.
Mobile intentionally does not show the full Product/package reconciliation table. It uses the same oldest-first depletion assumptions automatically, then offers a compact Made It follow-up with the recipe review rating, cleanup rating, notes, and optional Made It photo capture. These fields remain optional and can be edited on a later cook. Made It is shared Recipe-level state, not per-user or per-session state, and it does not require AI.
Detailed Let’s Cook quantity activity follows the Inventory Activity retention setting (30 days by default) and is summarized before detail is purged.
Session history
When a Let’s Cook session ends, Blackcap writes a compact history row to:
lets_cook_session_history
The history summary records:
- recipe cooked and recipe id;
- display used, or
Herefor local/admin sessions; - source surface such as Admin, Mobile, Kiosk, or Meal Planner;
- started/ended timestamps and duration;
- completed step count;
- used ingredient count;
- timer started/completed/cancelled counts;
- a compact JSON summary for short-term debugging.
Admin Let’s Cook shows Recent cooking sessions below active sessions. The panel is collapsed by default and uses the same compact collapse-button styling as other Let’s Cook panels. Mobile does not expose session history.
History endpoints:
GET /api/lets-cook/history?limit=20
GET /api/lets-cook/history/<session_id>
Session history is separate from the Made It/rating/photo flow. Photos, ratings, and notes remain in the existing recipe-made-it experience.
Purge behavior
Let’s Cook uses two purge retention tiers:
purge.lets_cook_session_data.enabled = true
purge.lets_cook_session_data.after_days = 7
purge.lets_cook_session_history.enabled = true
purge.lets_cook_session_history.after_days = 30
When a session is completed, cancelled, or failed, its operational session graph is eligible after 7 days by default:
lets_cook_timerslets_cook_session_ingredientslets_cook_session_stepslets_cook_session_recipeslets_cook_display_statelets_cook_scheduled_content_deferralslets_cook_sessions
The compact summary in lets_cook_session_history is retained separately for 30 days by default. Migration 069_lets_cook_purge_retention_split.sql removes the history table’s session foreign key so the summary can survive after operational rows are purged.
Database Admin resources
The Database Admin page exposes all Let’s Cook resources under the Let’s Cook category:
lets_cook_sessionslets_cook_session_historylets_cook_session_recipeslets_cook_session_stepslets_cook_session_ingredientslets_cook_timerslets_cook_display_statelets_cook_scheduled_content_deferrals
Use these resources for inspection/debugging. Purge should still go through the domain-aware Data Cleanup workflow, not raw row deletion.
Manual testing checklist
After deployment, verify:
- Starting a session renders the recipe on the controller and queues a full e-ink refresh.
- Checking several ingredients quickly results in one coalesced e-ink full refresh after roughly 10 seconds.
- Completing a step optionally auto-marks high-confidence ingredients and shows controller feedback.
- Starting a timer shows a static active timer indicator on e-ink while Mobile/Admin continue live countdown.
- Timer completion alarm repeats until 🛑, +1, +5, or 🔁.
- Ending from Admin, Mobile, Kiosk, or the session close
Xrestores default display content. - Starting from a meal-plan slot with sides shows compact side reminders on Admin, Mobile, Kiosk, and e-ink.
- Ending a session creates Admin-only recent session history.
- Data Cleanup shows separate Let’s Cook Session Data and Let’s Cook Session History retention groups.
blackcap_lets_cook_display_worker.serviceis not installed/running.
Useful commands:
sudo systemctl status inky_admin.service
sudo systemctl status blackcap_lets_cook_timer_refresh.service
sudo journalctl -u inky_admin.service -n 120 --no-pager
sudo journalctl -u blackcap_lets_cook_timer_refresh.service -n 120 --no-pager
Useful log lines:
Let’s Cook display update queued for debounced full refresh
pending_display_retry
Let’s Cook local e-ink partial refresh disabled; using full refresh
Attached e-ink push complete
BASE_OK / LOCK_ACQUIRED / LOCK_RELEASED
active_timer_static_no_eink_refresh
Future work
The next major feature is true multi-recipe cooking, where one Let’s Cook session can coordinate multiple recipe-backed entries in the same meal. Until then, side reminders provide the lightweight reminder use case without introducing multi-recipe scheduling, assignment, or display orchestration complexity.
Current-step display mode
Displays can choose whether Let’s Cook sessions use the compact current-step layout by setting Let’s Cook Current Step Display Mode in the display rendering settings:
- Off keeps the existing full Let’s Cook layout and is the default.
- Only show current step for voice-initiated Let’s Cook shows all session ingredients above the current step only when the session is started by a voice assistant.
- Only show current step for all Let’s Cook sessions uses the same ingredients plus current-step layout for any session rendered on that display.
Current-step mode applies from the beginning of the session on the configured render surface and uses the existing session step order, including any meal-plan side/additional recipe context that is already present in the Let’s Cook session data. Admin and Mobile remain control surfaces and continue to show the full step list even when the selected display is rendering one step at a time.
Current-step display deliberately shows all session ingredients above the active step so the cook can see the full ingredient context. Ingredient auto-checking still uses the matching service described below; the renderer does not yet hide the ingredient list down to only the current step's matched ingredients because one ingredient can legitimately belong to multiple steps and collective phrases such as sauce ingredients need special handling.
Interactive takeover is one-way for this phase. If a session is in current-step mode, Admin, Mobile, Kiosk, and touch-enabled hosted receiver surfaces can show 📖 Show Entire Recipe. Pressing it switches only the active session to full-recipe rendering, preserves completed steps/ingredients/timers/current step, and does not change the display default for future sessions.
Ingredient auto-check matching and diagnostics
Let’s Cook links ingredients to steps before a session starts so completing a step can automatically check off ingredients when the match is clear. The matcher is intentionally conservative:
- Quantity and unit terms are ignored.
- Section headers are ignored.
- Ingredients marked or worded as divided/reserved are not auto-checked.
- Distinctive ingredient terms are preferred over generic context words.
- Generic words such as sauce, oil, cheese, salt, pepper, flour, sugar, broth, and cream are used as supporting context when a more specific term is present.
- If a distinctive term is mentioned in any step, generic context words are not allowed to add unrelated extra matches.
- If no distinctive term is mentioned in the steps, the matcher falls back to generic context so directions that say only
cheese,salt, orflourstill check off ingredients like cheddar cheese, kosher salt, or all-purpose flour. - Collective step phrases such as
sauce ingredients,marinade ingredients,dressing ingredients,seasoning mixture,dry ingredients,wet ingredients,filling ingredients, andtopping ingredientscan match likely members of that group even when the step does not repeat every ingredient by name. - Collective phrases also include a gap-fill fallback: if an ingredient has no direct step mention and a collective instruction exists, Blackcap can infer that the otherwise-unmentioned ingredient belongs to that collective instruction. This mirrors how a cook interprets
add sauce ingredientsafter noticing that garlic, ginger, or sugar are listed but never named in the directions. - Ordered ingredient group phrases such as
first five ingredients,first 5 ingredients, andremaining ingredients except zucchiniare resolved from the ingredient list order. This helps baking recipes that intentionally avoid repeating every dry or wet ingredient by name in the directions. - Product descriptors for ingredients such as
rice vinegarandpineapple juiceare guarded so they do not match unrelatedriceorpineapplesteps by themselves.
For example, 1 tbsp. Worcestershire sauce primarily matches steps containing Worcestershire; the word sauce should not cause that ingredient to match unrelated tomato/pasta sauce steps. Conversely, 1 c. shredded cheddar cheese can fall back to a step that only says cheese when cheddar is not mentioned in the directions. A sauce step that says Add sauce ingredients to pan can now match explicitly sauce-like components such as soy sauce, vinegar, barbecue sauce, pineapple juice, garlic, brown sugar, or ginger, and can also gap-fill another otherwise-unmentioned ingredient into that sauce step when there is no direct text match. A baking step that says Whisk together first five ingredients. In a separate bowl, whisk remaining ingredients except zucchini can match the first five ingredient-list entries to the first phrase, the later ingredients to the remaining phrase, and keep zucchini tied to its direct Add zucchini usage.
Admin Let’s Cook history now includes an Ingredient Auto-Check Review when detailed session rows are still retained. Open a completed cooking session in Recent cooking sessions to see:
- auto-checked, manually checked, unmatched, waiting, and possible-overmatch counts;
- each notable ingredient’s matched steps;
- whether the ingredient was waiting for another matched step;
- whether the session used older broader matching than the current matcher would use;
- cases where all matched steps were complete but the ingredient was not checked.
The review is read-only and recomputed from the stored session detail rows. Once detailed Let’s Cook rows are purged, only the compact history summary remains and the diagnostic review is unavailable for that session.
Session-only setup / mise en place step
Blackcap can generate a session-only Setup · Step 0 before the first real recipe step. Current-step displays generate Step 0 automatically when setup items exist. Full-recipe Let’s Cook displays generate Step 0 only when the display’s Show Setup Step in Full Let’s Cook setting is enabled. This setup step is not written back to the recipe and does not change the recipe instructions.
The setup step scans the scaled session ingredients for prep cues such as diced, chopped, minced, sliced, grated, shredded, zested, peeled, crushed, cubed, chiffonade, melted, softened, room temperature, drained, rinsed, thawed, toasted, divided, separated, beaten, or whisked. Straight measurements such as 1 cup flour do not create setup work, while ingredients such as 3 cloves garlic diced, 1/2 cup chopped onion, or basil, chiffonade become setup instructions like Dice 3 garlic cloves, Chop 1/2 cup onion, and Chiffonade basil. Compound preparation modifiers stay with the action rather than the ingredient identity, so 2 tbsp finely chopped thyme is stored/matched as thyme with preparation finely chopped and Step 0 says Finely chop 2 Tbsp thyme rather than reducing the instruction to plain Chop.
Setup uses the Let’s Cook session multiplier. For example, starting a 2x session from 3 cloves garlic diced produces Dice 6 garlic cloves.
Setup behavior intentionally stays lightweight:
- Step 0 appears only when there is at least one detected prep item.
- Step 0 appears before Step 1 and must be advanced before the first real cooking step is shown.
- Step 0 is displayed as
Step 0 of N, whereNis the real recipe step count. - Step 0 is not counted in the real recipe step total.
- Setup items are rendered as a compact command list without numeric sub-step prefixes, so the prep text does not look like additional recipe step numbers.
- Completing Step 0 does not check off ingredients, because the ingredients have only been prepared, not used.
- Timer behavior remains tied to the current real/incomplete step. Setup normally has no timer candidates.
- Alexa read-aloud uses Step 0 first when read-aloud is enabled, then reads Step 1 after the user advances.
The display setting is stored as show_setup_step_in_full_lets_cook and defaults to false to preserve the existing full-recipe layout and font fitting. Enabling it adds the same generated Step 0 to full-recipe Let’s Cook sessions on that display while leaving saved recipe rendering unchanged.
Full-recipe review before step-by-step cooking
Organizations can enable Show full recipe before step-by-step cooking on the Organization page near Preferred Recipe Units. The setting is stored as lets_cook.show_full_recipe_review_before_current_step, defaults to true, and applies when the target display will render the session in current-step mode.
When enabled, a current-step Let’s Cook session begins in an intentional pre-cook review phase:
- the render surface shows the full recipe without generated Step 0;
- the cook can read the complete ingredients and instructions first;
- saying next or pressing ▶ Start Step-by-Step switches the same active session into current-step mode;
- the first current-step screen is generated Step 0 when setup items exist, otherwise Step 1.
The review phase does not complete any steps, check off ingredients, start timers, or edit the saved recipe. It is only a session render phase. Admin and Mobile remain control surfaces and can start step-by-step mode for a non-touch display; Kiosk and touch-enabled hosted receiver surfaces show the same ▶ Start Step-by-Step control when they are allowed to control the active session.
When Alexa starts a current-step session and review is enabled, Blackcap responds: I sent the full recipe to your display. Say next when you’re ready to start cooking. The next voice command leaves review mode and reads Setup/Step 0 or Step 1 when Alexa read-aloud is enabled.
Current-step ingredient emphasis and touch advancement
Single-step mode keeps ingredients in their original recipe order and emphasizes ingredients confidently associated with the current step in place. This preserves visual verification for phrases such as “first five ingredients” and “remaining ingredients.” Relevance to the current step is separate from whether the ingredient becomes complete after that step.
On interactive hosted, kiosk, and touchscreen receivers, tapping the current step advances through the existing next-step behavior. The request includes the expected step and session version, ignores text selection and nested controls, and prevents duplicate taps. Static image/e-ink output remains non-interactive.
More information
- Let’s Cook Controls and Timers — Use and implement preparation, steps, progress, ingredient state, timers, touch controls, and session completion.
Recipe multipliers
Let’s Cook stores the resolved session multiplier and applies it to the ingredient quantities shown during the session using the same leading-quantity scaling rules as normal recipe rendering. Practical volumes respect the organization’s maximum US/metric volume preferences (for example, cups rather than quarts when Cups is selected), and displayed fractions use only halves, thirds, quarters, or eighths, rounding upward where necessary. Approximate measures like a pinch or dash remain a single unit for multipliers below 2×. A recipe started from a meal-plan slot uses that slot/session multiplier, and additional recipe-backed items in a multi-recipe slot use their own meal-plan multipliers. Step 0 prep generation uses the same multiplier without double-scaling the persisted ingredient rows.
Meal Slot → Let’s Cook Meal
Meal Planner Recipe slots can be cooked as one logical Let’s Cook Meal session. This extends the existing persisted multi-Recipe/Component Let’s Cook architecture; it does not replace ordinary Recipe → Let’s Cook.
Meal Planner exposes one ▶️ Cook Meal action, visually separate from optional AI planning. The Ready to cook meals cards on the Let’s Cook page place a compact ▶️ start button immediately beside the Meal Slot name (for example, Dinner ▶️). That button starts the Meal immediately on the currently selected Cooking Display: it executes a current saved AI Meal Plan when one is available, otherwise it starts the deterministic sequential Meal path. It does not open another popup. Blackcap chooses the execution path from the Meal Slot state:
- When there is no current usable AI Meal Plan (including a stale plan), Cook Meal starts the deterministic sequential path. It makes no AI provider request, consumes no AI Seeds, and creates no AI Usage row.
- When a current saved AI Meal Plan exists, Cook Meal executes that validated saved timeline. Starting or executing it makes no new AI request and consumes no AI Seeds.
To intentionally return a currently planned Meal to sequential cooking, delete the saved AI Meal Plan first; the Meal Slot and Recipes remain unchanged.
Sequential mode and authoritative Meal Slot order
Ordinary Recipes follow the Meal Slot's stored order. Each Recipe keeps its own multiplier; there is no Meal-wide multiplier.
Every Recipe receives the existing exact Component discovery and deterministic quantity planning behavior. The user can make all, some, or none of the detected Components from scratch.
For a Component associated with one Recipe, the existing simple before/after choice remains:
- ⬆️ before the Recipe;
- ⬇️ after the Recipe.
For one Component shared by N Meal Slot Recipes, Blackcap presents N + 1 visual insertion points anchored by the actual Recipe names: before all, one point between each adjacent pair of associated Recipes, and after all. A shared Component is prepared once.
When an in-between insertion is selected, the Component is inserted immediately before the later associated Recipe in the full Meal sequence. Unrelated Recipes that already precede that boundary keep their Meal Slot position. For example, if A and C share Component X while B is unrelated, choosing the insertion between associated A and C produces:
Recipe A → Recipe B → Component X → Recipe C
Blackcap does not try to make a deterministic culinary decision that Components must always be prepared before their parent. Icing can therefore be placed after a cake when the user chooses, while a frangipane Component can be placed before its tart.
The selected Components, deterministic multipliers, placement choices, final stage sequence, Meal Items, and current stage are snapshotted into the Let’s Cook session and survive refresh/resume.
Meal Items
Ordinary Meal Items are passive Meal context in Let’s Cook. They appear only in the compact Sides: treatment in the active Meal header; they are not checkable cooking tasks, do not have a ready/not-ready workflow, and never block Meal completion. The underlying Meal Planner entry is unchanged.
This distinction is intentional: a Meal Item such as rolls, salad, fruit, or another simple side belongs with the Meal for awareness, while executable Let’s Cook work comes from Recipes and Component Recipes.
Saved AI plan execution
Plan Meal decides when to perform trusted Recipe and Component Recipe source work. It can interleave those trusted source steps and use cooling/resting/baking/roasting periods, while ordinary Meal Items remain context-only sides. It does not rewrite Recipe quantities or Component multipliers and does not directly mutate Kitchen Inventory.
A saved plan can schedule cases such as:
Bake Cake → let Cake cool → prepare Icing Component → apply Icing
rather than encoding every Component as a prerequisite for starting its parent Recipe.
Each executable Recipe/Component step retains the stable source Recipe and source-step reference used to validate the plan. Meal Items never become execution steps. Ingredient completion stays Recipe/stage scoped, so checking an ingredient in one Recipe does not check the same named ingredient in another Recipe.
Timers continue to use the normal Let’s Cook timer engine and can remain active while another Recipe is current. In Meal sessions their labels include useful Recipe context, for example Turkey — Roast.
On displays, the active Recipe/Component and active instruction remain primary; Meal Items stay in the Meal header as side context. Blackcap does not attempt to render the entire Meal Plan on a 960×680 display. Voice commands and screen wake continue through the normal Let’s Cook session behavior.
Meal Slot context is incorporated into the existing active identity/header treatment rather than adding a separate permanent header row.
Kitchen Inventory completion
On Admin, finishing a session previews used-ingredient depletion oldest Product/package first. Remaining stock uses the shared package-fullness slider with Empty / Low / ¼ / ½ / ¾ / Full stops; the same slider is used when adjusting Product/package fullness in Admin and Mobile Kitchen Inventory, while exact quantity entry remains available in Product details when needed. The recipe rating uses the star control and cleanup uses the same five-step slider as Made It on mobile. Usage rows show the normalized quantity/unit once (for example 4 cup) beneath the ingredient heading rather than repeating the original abbreviated measurement text.