Browse documentation

🧭 Start Here

Blackcap Overview ✨ Blackcap Feature Catalog 🤖 AI Features 🧱 Technology, Administration, and Reliability Installation First Run

📘 User Guides

Administration and Operations Platform Configuration Organization Configuration Email and Consent Management

🚀 Deploy Blackcap

Platform Stacks and Raspberry Pi Hardware Raspberry Pi Deployment Raspberry Pi Client Services GCP Deployment Packaged Blackcap deployment Application Updates After Your First Blackcap Login: Self-Hosted Setup Guide Blackcap Release Notes Environment Variables and Secrets Reverse Proxy and TLS Background Jobs and Schedules

🛠️ Administer Blackcap

Organizations Users, Permissions, and Authentication Configuration Workspace Backups and Restore Database Administration Regression Testing Performance and Job Status Audit, Access Activity, and Logging GeoIP and Access Location Data Retention and Purge Support Chat Administration Support Requests API Tester and Postman Instance Reporting Third-Party Packages and Attribution AI Provider Usage and Billing Portals Microwave Pie licensing for Blackcap Microwave Pie licensing for Blackcap

🍽️ Use Recipes

Recipes and the Recipe Library Recipe Import and Discovery Recipe Editing and Cache Artifacts Recipe Sharing Social Recipe Import AI Recipe Image Generation 🪄 Adapt Recipe and 🎲 Variations

📅 Plan Meals

Meal Planner

🛒 Use Shopping Lists

Shopping Lists and Shop a List External and Household Shopping 🔗 Chrome Extension Shop With

🧺 Manage Kitchen Inventory

🧺 Kitchen Inventory

🖥️ Use Displays

Displays and Connections Assigning and Scheduling Display Content Remote Pi Client E-Ink Rendering Menu Refresh and Rendering Noun Project Footer Images

🧑‍🍳 Cook with Let’s Cook

🧑‍🍳 Let’s Cook 🧑‍🍳 Let’s Cook Controls and Timers

🤖 Use and Administer AI

🤖 AI in Blackcap 🤖 AI Providers and Connections 🤖 AI Seeds and Usage Support Chat

🔗 Use the Chrome Extension

🔗 Blackcap Chrome Extension 🔗 Chrome Extension Recipe Capture 🔗 Chrome Extension Shop With 🔗 Chrome Extension Release and Privacy

🎮 Play Games

Games and trivia Bramble Harvest — Player Guide Flavor Lab — Player Guide

🔌 Integrations

Email Integration Cloud Storage Integrations Voice Assistants Shop With Integrations Authentication Providers

⚙️ Develop Blackcap

Application Architecture Database Service and Data Access SQLite and PostgreSQL Database Migrations Background Job Architecture Testing Games platform — current developer reference Bramble Harvest developer tools API Architecture Security and Organization Scoping UI, Icons, and Documentation Assets Blackcap-Safe Emoji Support Chat Architecture Extending Support Chat Support Chat Model Benchmark Documentation Standards Terminology

⚠️ Troubleshoot Blackcap

⚠️ Troubleshooting Licensing Troubleshooting Deployment Troubleshooting Display Troubleshooting Recipe Import Troubleshooting 🤖 AI Troubleshooting Backup Troubleshooting Database Troubleshooting Diagnostic Organization Clones Support Chat

Meal Planner

Audience: User, Org Admin, Developer, Support Related: Shopping Lists · Kitchen Inventory · Assigning And Scheduling · Email

Meal Planner supports organization-scoped week and month planning, configurable week start, meal slots, optional slot times, Recipes, Meal Items, durable Recipe Suggestions, AI Plan Meals, recipe multipliers, whole-Meal custom names/images, optional AI-generated Meal images, saved AI Plan Meal timelines, moves (including off-calendar future dates), review, PDF/email output, shopping-list generation, and Day/Week/Month display rendering. Mobile provides a focused week workflow.

Meal Planner reuses Recipe Library, Shopping Lists, Kitchen Inventory, Displays, and Shop With rather than duplicating those systems.

Meal Planner is an organization-scoped planning workflow for building weekly household meal plans from existing recipes, Recipe Discovery results, and ingredient-style manual meal items.

It is available in both the Admin UI and Mobile UI:

  • Admin UI supports week and month calendar planning, drag/drop style planning, day detail editing, review/share, shopping-list creation, and configuration links.
  • Mobile UI is intentionally week-only and touch-first, with a Step 1 / Step 2 flow for choosing a day and planning that day.

Meal Planner does not replace Recipe Library, Recipe Discovery, Shopping Lists, Shop a List, Kitchen Inventory, or On Hand behavior. It chooses planned meals and hands shopping-relevant sources to the existing shopping-list workflow.


Goals

  • Plan future meals on a calendar.
  • Respect an organization-configured week start day.
  • Use organization-configured meal slots such as Breakfast, Lunch, Snack, Dinner, and Dessert.
  • Support recipe-backed meal entries without duplicating recipe records.
  • Support manual/non-recipe entries such as French fries, 2 salad kits, or Burger sauce as shopping-relevant ingredient candidates.
  • Capture recipe multipliers with the shared display formatter, such as 1x, 1 ¼x, 1 ½x, and 2x.
  • Generate shopping lists through the existing Shopping List services.
  • Keep Kitchen Inventory / On Hand logic owned by Shopping Lists and Shop a List.
  • Provide a readable meal-plan review surface and shareable PDF/email output.
  • Render Meal Plan Day/Week/Month views to display targets without changing the Admin/Mobile planning UI.
  • Optionally auto-show recipe-backed meal-plan entries on displays during configured meal-slot time windows.
  • Store meal-slot start/end times as canonical HH:mm values while displaying user-facing labels with the organization time format.
  • Keep organization scoping, permissions, auditability, and future hosted/SaaS readiness intact.

User-facing surfaces

Admin Meal Planner

Path:

/admin/meal-planner

Admin supports:

  • Week view.
  • Month view.
  • Previous / Today / Next navigation.
  • Organization-configured week start day.
  • Day selection with a right-side Day view panel.
  • Collapsible Day view panel so the calendar can use more horizontal space.
  • Calendar slot abbreviations for compact display.
  • Hover tooltips with full slot/item details.
  • Add existing recipe to a slot.
  • Add meal item to a slot, including approved Blackcap emoji characters.
  • Launch Recipe Discovery from a slot.
  • Edit recipe multiplier.
  • Edit manual meal item details.
  • Remove entries.
  • Move item, slot, or whole day.
  • Drag a Recipe, Meal Item, whole Meal, or whole day to the full-width Move to another date drop zone below the visible week/month. Individual items/Meals choose an off-calendar future date plus destination Meal Slot; a whole-day move only needs the destination date and carries Recipes, Meal Items, and unresolved Recipe Ideas together.
  • Edit the persistent whole-Meal custom name with the shared emoji picker and use an uploaded or AI-generated whole-Meal image.
  • Optionally create/reopen/delete a saved AI Meal Plan for Recipe-bearing Meal Slots.
  • Review Plan.
  • Download meal plan PDF.
  • Email meal plan PDF.
  • Plan Meals across selected dates/Meal Slots.
  • Create Shopping List.

Meal Planner uses one transient plan/shop checkbox per displayed day/slot for both Plan Meals and Create Shopping List. The selection is cleared after either action succeeds; cancellation or validation/provider failure leaves it selected for correction/retry.

Meal-slot configuration uses native browser time inputs for start/end fields instead of free-form text, so values like 1500 are not accepted. Blackcap stores the values as canonical HH:mm. Native browser picker chrome can follow the browser/operating-system 12/24-hour preference, so the organization setting controls Blackcap's labels and saved/displayed formatting but cannot force the native picker popup itself into 24-hour mode on every PC.

The Meal Slots panel exposes timezone once as a compact inline control in its header rather than repeating the same selector on every row or reserving a tall settings card for it. Rows are laid out as Name · Abbr. · Start · End · Recipe Type · Save so the Recipe Type association receives the wider space previously occupied by the per-slot timezone selector. Saving any row synchronizes the header timezone to all of the organization's Meal Slots; adding a slot also uses that same timezone.

The Admin layout follows the newer Blackcap scroll/viewport pattern: the page heading can scroll away, the main workspace can fill the viewport, and the Day view remains a single scroll region with smooth handoff to the page.

Mobile Meal Planner

Path:

/mobile/meal-planner

Mobile is week-only by design. It supports:

  • Previous week / next week controls.
  • Today button.
  • Swipe week navigation from the week strip.
  • Step 1: choose a day.
  • Step 2: plan the selected day.
  • Swipe day navigation from the Day view.
  • Automatic working-week context updates when swiping into a different week.
  • Add recipe.
  • Add meal item.
  • Launch Recipe Discovery from a slot.
  • Edit recipe multiplier.
  • Edit manual meal item details.
  • Remove entries.
  • Tap-based Move item, Move slot, and Move day flows.
  • Edit the same persistent whole-Meal custom name/image identity used by Admin and Let’s Cook.
  • Reopen a saved AI Meal Plan for a Recipe-bearing Meal Slot.
  • Show Week summary.
  • Review Plan.
  • Download/email meal plan PDF.
  • Create Shopping List.

Mobile does not depend on long-press drag/drop. Move actions use a styled dialog with target day, optional date picker, target slot, placement, and append/replace choices.


Configuration

Meal Planner configuration lives under:

Configuration → Organization → Meal Planner

The configuration panel manages organization-scoped defaults:

  • First day of week — fully flexible, such as Sunday, Monday, Wednesday, or any other weekday.
  • Meal slots — organization-owned slots shown in the Day view and used for planning. Each slot also has an explicit Recipe Type mapping. Standard slots are seeded as Breakfast/Lunch/Snack/Dinner/Dessert; migrated or newly created custom slots are conservatively inferred from the slot name when no mapping is supplied, then the saved configuration becomes authoritative. Plan Meals uses this mapping both to rank reusable Recipe Library candidates and to type a new Recipe created by Find & Add.
  • Slot abbreviations — compact labels used in Admin calendar cells.
  • Slot ordering — drag/drop ordering in the configuration panel.
  • Optional slot start/end times — organization-level meal windows such as Breakfast 7:00-9:00 AM or Dinner 5:00-7:00 PM.
  • Meal Slot timezone — configured once for the organization in the Meal Slots panel header. The database intentionally keeps the existing per-slot timezone field for compatibility, but the configuration UI treats it as one shared value: saving any Meal Slot applies the selected timezone to every Meal Slot in that organization, and newly created slots inherit the same value. A blank value continues to mean Organization default. If older data contains mixed per-slot values, the header identifies that state until the next slot save synchronizes them.
  • Slot archiving — hides a slot from new planning while preserving existing meal-plan entries.
  • Display refresh delay — coalesces Current Meal Plan display pushes after meal-plan edits so local e-ink hardware is not rewritten after every recipe or note change.

Default slots are seeded as:

Slot Calendar abbreviation
Breakfast B
Lunch L
Snack S
Dinner D
Dessert Ds

The full slot name is used in the Day view, Review Plan, PDF output, shopping-list generation, and display rendering. Abbreviations are only for compact calendar display. Slot start/end times do not change manual planning behavior; they are only used by display auto-show scheduling when a display opts in.

Display refresh debounce

When the default e-ink display, hosted receiver, kiosk, or remote client is currently showing Current Meal Plan, Meal Planner edits mark the impacted display assignment as stale instead of pushing immediately. The periodic display-content runner performs the actual render/push after the quiet period.

The organization setting lives in the same Meal Planner configuration panel:

meal_planner.display_refresh_debounce_seconds

Default value: 300 seconds. Set it to 0 to restore immediate refresh behavior. For testing, 60 or 120 seconds is often a better balance between fast feedback and avoiding repeated local e-ink writes. The setting is organization-scoped, so one organization can use a shorter delay without changing another organization’s display behavior.

The runner responsible for due/stale display content is:

/home/pi/inky_env/bin/python3 /home/pi/Blackcap-Pi/run_display_content_refresh.py

Planning entries

Meal Planner has three planning entry types.

Recipe-backed entries

Recipe-backed entries reference an existing recipe in the current organization.

They store planning-specific details such as:

  • plan date;
  • slot;
  • display order;
  • quantity multiplier;
  • source type, such as recipe library or Recipe Discovery.

The recipe name, description, ingredients, source URL, PDF, thumbnail, and editable recipe content still belong to the Recipe Library. Meal Planner does not duplicate recipe records or edit recipe titles.

Recipe multiplier editing uses a compact styled dialog. Values are normalized to quarter steps and shown as friendly labels:

  • 1x
  • 1 ¼x
  • 1 ½x
  • 1 ¾x
  • 2x

When a shopping list is generated, the multiplier is passed to the existing shopping-list recipe ingredient logic.

Manual meal items

Manual entries are called meal items in the UI. Meal item names can include approved Blackcap emojis through the shared emoji picker. Unsupported emoji characters are validated using the existing emoji registry/cache behavior so e-ink and display rendering do not break.

Use Add meal item for non-recipe items such as:

  • French fries
  • 2 salad kits
  • Burger sauce
  • Fruit
  • School lunch
  • Takeout pizza

Manual meal items are treated as ingredient-style shopping candidates, not vague notes. They can capture:

  • item name;
  • quantity;
  • unit / measurement;
  • optional canonical ingredient text;
  • optional notes;
  • whether the item should be included in shopping-list generation.

This matches the behavior expected for recipe ingredients that cannot be reconciled directly. For example, a recipe ingredient such as Burger sauce, for serving (optional) and a manually planned Burger sauce meal item should both be able to flow into shopping-list review/canonical validation.

Manual meal items store fields such as:

  • item_quantity_label
  • item_unit
  • normalized_name
  • canonical_name
  • search_name
  • ingredient_validation_status
  • include_in_shopping

If an item is not linked to a known canonical, it remains reviewable through the shopping/database cleanup flow rather than being silently discarded.


Recipe Suggestions

Recipe Suggestions are durable planning placeholders created when Plan Meals proposes a dish that needs a Recipe but no authoritative Recipe has been captured yet. A Suggestion has its own public ID and can retain a suggested name, optional ingredient hints, optional safe source URL/source kind, primary/side role, and Meal Slot position. It is deliberately not a fake Recipe and not a Meal Item.

Plan Meals deliberately biases ambiguous low-complexity foods toward Meal Item rather than creating unnecessary Recipes. Multiple named foods or preparation adjectives alone do not make a Recipe. Simple assemblies and basic preparations such as avocado toast, scrambled eggs with spinach, shredded lettuce and diced tomatoes, sliced fruit, plain rice, baked potatoes, and plainly cooked vegetables remain Meal Items unless the proposed dish actually depends on reusable preparation guidance such as a prepared sauce/dressing/marinade, meaningful seasoning ratios, a distinctive technique, or timing-sensitive multi-step work. Blackcap also applies a deterministic simple-food guard before Find & Add invokes Recipe Discovery, so a provider over-classification does not automatically consume a Recipe search.

Suggestion ingredient hints are discovery context only. They contribute zero Shopping ingredients and are never treated as Nutrition, Let’s Cook instructions, Component Recipe data, or authoritative ingredients. Hints are normalized into atomic ingredient phrases before they are stored: alternatives are split so udon or rice noodles becomes separate udon noodles and rice noodles hints rather than one unusable search chip. Meal Planner/Home render Suggestions with a Needs Recipe treatment and highlight Recipe Discovery while unresolved Suggestions remain. The Recipe Discovery action keeps its normal detective icon and shows the unresolved count as a small notification badge rather than changing the button text. Following that action is an intentional resolution workflow, so it does not show the generic unresolved-Suggestion leave warning. Recipe Discovery is pre-seeded with the Suggestion name as search text, ingredient hints as ingredient chips, the retained source URL in the URL fallback when available, and the exact Dietary Preferences & Restrictions snapshot used by the originating Plan Meals run. Resolving a Suggestion with an existing or newly imported Recipe replaces it atomically in the same Meal Slot position and preserves primary/side ordering. If the idea is actually simple enough not to need Recipe instructions, the Meal Planner also offers 🍽️ Convert Recipe Idea to Meal Item; this replaces the unresolved Suggestion in the same slot position without another AI request. Removing a Suggestion simply dismisses that placeholder.

Users may leave with unresolved Suggestions. Blackcap uses a Recipe-Idea-specific navigation warning explaining that the ideas are already saved and can be resolved later; it does not use the browser's generic unsaved changes warning merely because a Recipe Idea exists. The final prompt is page-sensitive: Home asks whether to leave the Home page, while Meal Planner asks whether to leave Meal Planner. Shopping, Meal Plan review, Plan Meal, and Meal-level Let’s Cook warn when Suggestions are in scope and may continue while ignoring those unresolved entries.

Add Recipe flow

From either Admin or Mobile Day view:

  1. Choose a meal slot.
  2. Select Add Recipe.
  3. Search the organization’s Recipe Library.
  4. Optionally filter by recipe type.
  5. Optionally add ingredient chips for multi-ingredient search.
  6. Review recipe cards with thumbnail, title, type/source metadata, and description.
  7. Set the multiplier on the recipe tile.
  8. Add the recipe to the selected date and slot.

The Add Recipe picker uses the existing organization-scoped recipe data and the token/auth-safe recipe thumbnail route based on public recipe ids. It does not create a recipe record and does not use made-it/completion photos as picker thumbnails.


Add meal item / Edit meal item flow

Manual meal items use a styled Blackcap dialog, not browser prompt() calls.

The same dialog is used for:

  • adding a meal item;
  • editing a meal item.

The dialog uses progressive disclosure so the common path stays compact. By default it shows only:

  • meal item name;
  • Include in shopping list;
  • the Cancel and Add/Save buttons.

A collapsed Advanced section contains the less-common fields:

  • quantity;
  • unit / measurement;
  • canonical ingredient text;
  • notes;
  • the shopping-list reconciliation guidance.

The Advanced section starts collapsed every time the dialog opens, including Edit Meal Item. The dialog uses its natural content height while Advanced is collapsed and grows only when Advanced is expanded, up to the normal viewport-safe maximum where the body can scroll.

The dialog title changes between Add meal item and Edit meal item based on context. The same progressive-disclosure behavior is used by the Admin Meal Planner, the Home Meal Planner surface, and Mobile Meal Planner.


Display rendering and auto-show behavior

Meal Plan display rendering is separate from the Admin and Mobile planning UI. The planning screens continue to show individual recipe and manual entries, while display output summarizes each populated slot for readability.

Display rendering rules:

  • Slot order follows the organization-configured meal slot order, not alphabetical order and not the order entries were first encountered.
  • Week view renders only populated slot columns and orders them left-to-right by configured slot order.
  • Day and Month card views use the same configured slot order.
  • The first recipe-backed entry in a populated slot is treated as the main recipe.
  • Remaining entries in the same slot, including non-recipe meal items and additional recipe-backed entries, are rendered as sides using Main Recipe w/Side One and Side Two.
  • If a slot has no recipe-backed entries, the first visible item becomes the main item and remaining items become sides.
  • Approved Blackcap emojis in recipe/item names remain visible in display text.
  • Color/image-capable displays can include the main recipe thumbnail; B&W/e-ink displays remain text-first.

Display Detail includes an opt-in setting for auto-show timed Meal Plan recipes. When enabled, the periodic display-content refresh runner checks active meal slots with start/end times. If the display's default/current content is a Meal Plan Day/Week/Month view and the active slot contains recipe-backed entries, Blackcap temporarily shows the first recipe-backed entry, lists the virtual auto-show activity in Scheduled Display Content, and restores the display's default Meal Plan view after the slot ends. Non-recipe-only slots and slots without time windows are ignored. Auto-show is disabled by default.

Let’s Cook integration

Blackcap preserves the existing Recipe → Let’s Cook action from an individual meal-plan entry. That path keeps the selected Recipe active, carries the parent meal-plan entry id, and shows the other entries as compact side reminders. For example, a dinner slot with Spaghetti & Meatballs, Bread, and Salad can still start a single-Recipe session for Spaghetti & Meatballs while showing Sides: Bread · Salad.

Meal Planner also provides the separate Meal Slot → Let’s Cook Meal selection path. The Meal image ▶️ does not start cooking immediately; it opens the Let’s Cook page and populates that Meal into Start cooking by recipe or meal. The user can then choose the Cooking Display before starting. Meal and Recipe selections are mutually exclusive. Recipe mode retains its multiplier control; Meal mode deliberately has no whole-Meal multiplier because each Recipe keeps the multiplier already stored on its Meal Planner entry. When started, Meal mode cooks all Recipe-backed entries in authoritative Meal Slot order (plus selected Component stages) as one logical session, or executes a current saved AI Meal Plan. The lightweight side-reminder behavior remains only for the preserved per-Recipe launch.


Recipe Discovery integration

Meal Planner can launch Recipe Discovery with date/slot context.

Admin example:

/admin/recipe-discovery?meal_plan_date=2026-05-28&meal_slot_id=<slot_id>&return_to=meal_planner

Mobile example:

/mobile/recipe-discovery?meal_plan_date=2026-05-28&meal_slot_id=<slot_id>&return_to=mobile_meal_planner

When a recipe is saved from Recipe Discovery with Meal Planner context:

  1. The recipe is saved normally into the current organization.
  2. Editable recipe content and ingredient/search indexes are written normally.
  3. The normal recipe cache/PDF/image build is queued.
  4. A Meal Planner recipe-backed entry is created for the selected date/slot.
  5. The user returns to the Meal Planner context.

Recipe Discovery remains fully usable as a standalone recipe import workflow.


Moving entries

Admin

Admin supports planning moves at three levels:

  • individual recipe/manual item;
  • whole meal slot;
  • whole day.

Calendar/day interactions support drag/drop style movement and append/replace conflict choices where needed. Dragging a whole day moves all visible content in that day together: Recipe-backed entries, Meal Items, and unresolved Recipe Ideas. In append mode the source content is added after destination content while preserving its combined order; in replace mode destination Recipe/Meal Item entries are removed and destination unresolved Recipe Ideas are dismissed before the source day is moved. Dragging an individual item onto another calendar day opens a compact slot selector instead of assuming a target slot. A full-width Move to another date drop zone below the visible week/month accepts a Recipe, Meal Item, whole Meal, or whole day. Individual Recipe/Meal Item/Meal moves use an explicit future date plus Meal Slot selector. Whole-day moves use only the destination date because each source item keeps its own Meal Slot; Recipes, Meal Items, unresolved Recipe Ideas, and Meal-level metadata move together through the normal day-move service. The picker is intended for future dates outside the currently rendered calendar range, so a user does not have to navigate the calendar merely to move something farther ahead. Destination people-served values and the existing recalculate_multipliers behavior remain authoritative for item/Meal moves; manual multiplier overrides remain protected.

Mobile

Mobile uses tap-based move actions instead of relying on long-press drag/drop.

Supported actions:

  • Move on a recipe/manual item;
  • Move slot on non-empty meal slots;
  • Move Day for the selected day.

The move dialog supports:

  • current-week day chips;
  • date picker for another date;
  • target slot selection for item/slot moves;
  • top/end placement for individual items;
  • append/replace conflict choices for slot/day moves.

If a move targets a day outside the current working week, the selected date and working week context update after the move.

A whole-Meal move has one additional AI-plan rule: moving the intact Meal to the same Meal Slot on another date can carry its current saved AI Meal Plan, custom name, and Meal image when the destination is empty (or explicitly replaced) and multiplier recalculation does not change serving inputs. A merge, a move to a different Meal Slot, or changed serving inputs remains a material planning change and follows the normal AI-plan invalidation/confirmation rules.


Week context and mobile navigation

Mobile Meal Planner state is based on:

selectedDate = exact day being planned
workingWeekStart = configured week containing selectedDate

Behavior:

  • Previous/next week changes the working week.
  • Today returns to the current real-world date/week.
  • Tapping a day selects that day.
  • Swiping the week strip changes the working week.
  • Swiping the Day view changes the selected day.
  • Swiping from the last day of one configured week into the next day updates the working week context.
  • Show Week, Review Plan, and Create Shopping List use the currently selected/working week, not necessarily the real current week.

Show Week, Review Plan, and PDF/email sharing

Show Week

Show Week is a planning summary. It shows the working week and planned content in readable day/slot tiles.

It is not an editing surface.

Review Plan

Review Plan is a read-only review/share surface for the visible Admin range or the working Mobile week.

It shows only planned days/slots. A whole-Meal grouping is shown only when it adds information: a user-overridden Meal name is shown as the group name, and a persistent Meal image is shown when present. An automatic Recipe-derived Meal name is not repeated as a second group label. When a custom Meal name exists, the grouping does not redundantly list the Recipe names; the actual Recipe and Meal Item cards always remain below.

Review includes:

  • custom whole-Meal name when overridden;
  • whole-Meal image when present (uploaded or AI-generated);
  • recipe thumbnail/fallback image;
  • recipe name;
  • multiplier;
  • description;
  • manual meal item quantity/unit;
  • source link where available;
  • recipe PDF link where available.

PDF and email

Meal Planner can generate a shareable meal plan PDF that follows the Review Plan structure with day sections, slot labels, the same conditional whole-Meal grouping/custom name, the persistent whole-Meal image when present, recipe/manual item cards, recipe images, descriptions, quantities, and links where possible. The Meal image is embedded from Blackcap’s persisted Meal-image artifact; it is not merely a browser-only URL.

Review Plan also offers an Include recipes checkbox for both PDF download and email. When enabled, Blackcap appends the normal share-style Recipe rendering for every Recipe-backed Meal Planner entry in review order. Each appended Recipe starts on a new page and uses that specific Meal Planner entry's Recipe multiplier for ingredient quantities (for example, a 10x Meal Planner entry renders 1/2 cup as 5 cups). Directions and the stored Recipe are not modified. The same Recipe can therefore appear more than once when it is planned in multiple Meal Slots with different multipliers. Long Recipes may continue onto additional pages rather than clipping. Meal Items and unresolved Recipe Ideas do not create Recipe pages.

Meal Plan Review PDFs preserve extra image detail without adding separate email attachments. The normal page layout remains a compact 150-DPI raster, but Meal-level images and Recipe thumbnails are overlaid at the same visible size as independent PDF image objects. Blackcap caps both image types to a shared 1600-pixel longest edge before embedding. This keeps PDF size bounded while allowing substantially better zoom/detail than the surrounding page. If a stored Recipe image is smaller than 1600 pixels, Blackcap embeds the available source pixels rather than upscaling them. The same behavior applies to downloaded PDFs and the PDF attached by Review Plan email, including Recipe thumbnails on appended Include recipes pages.

Email PDF sharing uses an inline panel, not a browser prompt. It captures:

  • recipient email address(es);
  • optional message;
  • optional sender name.

This is intentionally email/PDF sharing only. There is no Blackcap-to-Blackcap meal-plan share/import flow.


Historical Meal Plan retention and Data Cleanup

Meal Planner has a dedicated retained-data purge domain named Meal Plans. The default scheduled retention is 730 days (2 years) after the Meal Slot's plan date. Data Cleanup can also select and purge older Meal Plan groups manually before the scheduled retention run when the user explicitly chooses them.

Purging one historical dated Meal Slot removes the domain together: its Meal Plan entries (including historical soft-deleted entries), whole-Meal identity/name/image metadata and persisted Meal image file, per-slot people-served override, saved AI Meal Plan, and AI Meal Plan Recipe-reference rows. The organization’s reusable Meal Slot configuration (Breakfast/Lunch/Dinner/etc.) is not deleted. AI Usage/What Happened evidence follows its own AI retention policy rather than the product Meal Plan retention period. See Data Retention & Scheduled Purging.


Shopping-list generation

Meal Planner creates shopping lists by handing selected meal-plan sources to the existing Shopping List services.

Supported selection behavior:

  • selected days;
  • selected slots;
  • multiple days/slots;
  • full visible/working week default when nothing is manually selected.

Admin and Mobile both default to the current working/configured week when nothing is selected. In Month view, Create Shopping List still defaults to the current configured week rather than the entire visible month.

Recipe-backed entries contribute recipe ingredients using the saved meal-plan multiplier.

Manual meal items contribute ingredient-style candidates when include_in_shopping is enabled. Items that are not confidently canonical-linked remain reviewable by the existing shopping/canonical validation flow.

Meal Planner does not directly manage:

  • barcode scanning;
  • purchased product capture;
  • inventory intake;
  • on-hand consumption;
  • Kitchen Inventory quantity adjustments;
  • grocery department cleanup.

Those responsibilities remain inside Shopping Lists, Shop a List, Kitchen Inventory, and Database Admin data-management workflows.


Recipe archive/delete dependency behavior

recipe_dependency_service.py checks recipe dependencies before archive/delete actions.

Rules:

  • A recipe used in a future Meal Planner entry cannot be archived.
  • A recipe used only in past Meal Planner entries, shopping lists, or sharing records can be archived after warning/confirmation.
  • A recipe associated with any Meal Planner entry or shopping list cannot be hard deleted.
  • Dependency checks are organization-scoped.

This protects future meal plans and prevents broken historical meal-plan/shopping-list references.


Data model

Migration 045_meal_planner.sql creates:

  • meal_plan_settings
  • meal_slots
  • meal_plan_entries
  • meal_plan_shopping_list_links

Migration 046_meal_slot_abbreviations.sql adds configurable meal slot abbreviations.

Migration 124_meal_plan_display_refresh_debounce.sql adds the organization-scoped meal_planner.display_refresh_debounce_seconds setting used to coalesce Current Meal Plan display pushes.

Migration 177_slow_sites_people_served_recipe_difficulty.sql adds per-date/Meal-Slot people-served overrides and multiplier provenance used when recipes are added or moved.

Migration 229_meal_level_lets_cook_plan_meal.py adds durable meal_slot_ai_plans, meal_slot_ai_plan_recipes, and lets_cook_session_meal_items records for saved Plan Meal output/source protection and Meal-level Let’s Cook state.

Migration 230_meal_identity_and_images.py adds meal_plan_meals, the persistent identity for one dated Meal Slot, including the user-overridden Meal name and whole-Meal image metadata. It also generalizes AI generated-image candidates with entity_type/entity_id so the existing image-generation pipeline can target either a Recipe or a Meal.

Migration 231_meal_component_preferences.py adds persistent provisional Component preferences to the dated whole-Meal identity.

All records are organization-scoped. Recipe references use (organization_id, recipe_id) so recipe IDs remain unique only within the owning organization.

No meal_plan_days table is currently required. A day is represented by entries grouped by organization_id + plan_date.


Service architecture

Core files:

inky_admin/blueprints/meal_planner.py
inky_admin/services/meal_planner_service.py
inky_admin/services/meal_planner_db_service.py
inky_admin/services/meal_planner_drag_service.py
inky_admin/services/meal_planner_review_service.py
inky_admin/services/meal_identity_service.py
inky_admin/services/meal_plan_ai_service.py
inky_admin/services/meal_plan_ai_schema.py
inky_admin/services/ai_image_service.py
inky_admin/services/meal_planner_shopping_list_service.py
inky_admin/services/display_content_refresh_service.py
inky_admin/services/recipe_dependency_service.py
inky_admin/templates/meal_planner.html
inky_admin/templates/mobile_meal_planner.html
inky_admin/static/css/meal_planner.css
inky_admin/static/css/mobile_meal_planner.css
inky_admin/static/js/meal_planner.js
inky_admin/static/js/mobile_meal_planner.js

Architecture pattern:

Blueprint route
  → service layer
  → meal planner DB/service helpers
  → centralized database service / repository layer
  → SQLite

Business logic should stay in services. Routes should remain thin, and templates should not own persistence or permission logic.


API / endpoints

Primary pages:

Method Path Purpose
GET /admin/meal-planner Admin Meal Planner.
GET /mobile/meal-planner Mobile Meal Planner.

Data and entry APIs:

Method Path Purpose
GET /admin/meal-planner/events Calendar range data.
GET /admin/meal-planner/day/<date> Day detail with slots and entries.
POST /admin/meal-planner/entries Create recipe-backed or manual entry.
PATCH/POST /admin/meal-planner/entries/<entry_id> Update entry details.
DELETE /admin/meal-planner/entries/<entry_id> Remove entry.
POST /admin/meal-planner/entries/<entry_id>/move Move one item.
POST /admin/meal-planner/slots/move Move a full slot.
POST /admin/meal-planner/days/move Move a full day.
GET /admin/meal-planner/recipe-search Organization-scoped recipe picker search.
GET /admin/meal-planner/slot-summary Rich whole-Meal summary including custom identity/image, entries, and current AI-plan summary.
POST/PATCH /admin/meal-planner/slot-people Set/reset the people-served override for one dated Meal Slot.
POST /admin/meal-planner/slot-people/bulk Apply people-served overrides to multiple dated Meal Slots.
PATCH/POST /admin/meal-planner/meal Set/reset the persistent whole-Meal custom name.
GET /admin/meal-planner/meal-image Serve the permission-checked persistent whole-Meal image.
POST /admin/meal-planner/meal-image/upload Upload/replace the whole-Meal image.
GET /api/ai/meal-image/options Read existing AI image Quality Profiles/AI Seed choices for a Meal.
POST /api/ai/meal-image/generate Queue an asynchronous whole-Meal AI image using the existing image-generation use case/profiles.
GET /admin/meal-planner/meal-plan Read the saved current/stale AI Meal Plan for one dated Meal Slot.
POST /admin/meal-planner/meal-plan Confirm/queue create or replan through the selected Plan Meal Quality Profile.
GET /admin/meal-planner/meal-plan/jobs/<job_id> Poll the asynchronous Plan Meal job.
DELETE /admin/meal-planner/meal-plan Delete only the saved AI Meal Plan.

Configuration APIs:

Method Path Purpose
GET/PATCH/POST /admin/meal-planner/settings Read/update Meal Planner settings.
POST /admin/meal-planner/slots Add meal slot.
PATCH/POST /admin/meal-planner/slots/<slot_id> Update/archive slot.
POST /admin/meal-planner/slots/reorder Save slot order.

Review and shopping APIs:

Method Path Purpose
GET /admin/meal-planner/review Build Review Plan data for start/end query dates.
GET /admin/meal-planner/review/pdf Download Review Plan PDF for start/end query dates; optional include_recipes=1 appends multiplier-aware Recipe pages.
POST /admin/meal-planner/review/email Email Review Plan PDF; optional boolean include_recipes uses the same appended multiplier-aware Recipe pages as download.
POST /admin/meal-planner/preview-shopping-list Preview shopping-list source set.
POST /admin/meal-planner/create-shopping-list Create shopping list from selected meal plan dates/slots.

Mobile uses the same JSON endpoints so behavior remains centralized.


Permissions

Meal Planner uses dedicated permissions:

  • meal_planner.view
  • meal_planner.manage
  • meal_planner.configure
  • meal_planner.move
  • meal_planner.delete
  • meal_planner.create_shopping_list

Permission checks are enforced server-side. Organization context is resolved from the authenticated user/session, not from client-supplied organization IDs.


Organization scope and security

Meal Planner data is organization-owned.

Expected behavior:

  • Org users see only their organization’s meal plan.
  • System admins see organization-scoped business data for their active organization context only.
  • Recipe lookup must resolve through (organization_id, recipe_id).
  • Recipe Discovery saves into the current organization.
  • Shopping-list generation creates organization-owned lists.
  • Move endpoints cannot cross organizations.
  • Configuration updates apply only to the active organization.
  • Direct endpoint calls with forged IDs should fail closed.

Testing checklist

Admin calendar

  • Week view renders.
  • Month view renders.
  • Week start day is respected.
  • Previous, next, and today controls work.
  • Day selection opens the Day view.
  • Collapsing the Day view gives the calendar more space.
  • Calendar slot abbreviations appear.
  • Hover tooltips show full slot/item names.

Admin Day view

  • Slots show in configured order.
  • Empty slots use the header/button area as the drop target.
  • Multiple entries in one slot display fully.
  • Recipe thumbnails appear when there is room.
  • Manual entries can be added/edited with quantity/unit/canonical fields.
  • Recipe-backed entries can be added with multiplier.
  • Recipe multiplier edit dialog saves immediately.
  • Entries can be removed.
  • Day view scroll handoff feels smooth.

Mobile planner

  • Mobile Meal Planner loads from /mobile/meal-planner.
  • Week-only view respects configured week start day.
  • Previous/next week controls work.
  • Week strip swipe works.
  • Today returns to the current date/week.
  • Day chips show planned counts.
  • Day swipe moves to previous/next day.
  • Swiping across a week boundary updates working week context.
  • Add Recipe works.
  • Add meal item works.
  • Recipe Discovery returns to the selected mobile date/slot.
  • Recipe thumbnails appear in Day view.
  • Show Week displays the working week, not always current week.

Move behavior

  • Admin item move works.
  • Admin slot move works.
  • Admin day move works.
  • Mobile item Move works.
  • Mobile Move slot works.
  • Mobile Move Day works.
  • Moving to a date outside the current week updates the selected/working week context.
  • Append/replace conflict behavior works.

Recipe Discovery

  • Launch from Admin Meal Planner slot.
  • Launch from Mobile Meal Planner slot.
  • Save recipe normally.
  • Cache build is queued.
  • Meal plan entry is created with the right date/slot.
  • User returns to the right Meal Planner context.
  • Standalone Recipe Discovery still works.

Shopping-list generation checks

  • Create from selected Admin days/slots.
  • Create from selected Mobile days/slots.
  • When nothing is selected, Admin defaults to the current configured week.
  • When nothing is selected, Mobile defaults to the current working week.
  • Recipe multipliers scale ingredients.
  • Manual meal items become ingredient candidates when included.
  • Uncanonicalized manual items remain reviewable.
  • Existing Shopping List, Edit Shopping List, Shop a List, Kitchen Inventory, and On Hand behavior handles execution.

Review and share

  • Review Plan shows only planned days/slots.
  • PDF includes images, descriptions, quantities, multipliers, and day/slot structure.
  • Email PDF panel opens inline.
  • Email PDF sends with meal-plan wording.
  • No Blackcap-to-Blackcap meal-plan sharing is exposed.

Meal Planner configuration checks

  • Configuration → Organization → Meal Planner loads.
  • First day of week saves and shows saved feedback.
  • Slot add/edit dialog works.
  • Slot abbreviation saves.
  • Slot drag/drop order saves.
  • Slot archive icon is centered and archives the slot.
  • Archived slots stop appearing for new planning.
  • Display refresh delay saves in the same Meal Planner panel and does not create a duplicate Meal Planner configuration page.
  • When the active display content is Current Meal Plan, a burst of recipe/manual-note edits produces one deferred display refresh after the configured quiet period.
  • Setting meal_planner.display_refresh_debounce_seconds to 0 restores immediate refresh behavior.

Recipe dependency behavior

  • Future meal plan references block archive.
  • Past meal plan references warn before archive.
  • Shopping list references warn before archive.
  • Meal-plan/shopping-list references block hard delete.
  • Cross-organization recipe IDs do not affect dependency checks.

Regression

  • Recipe Library still loads and searches.
  • Recipe Discovery still works standalone.
  • Recipe cache queue remains unchanged.
  • Recipe PDFs/images still render.
  • Shopping Lists still work.
  • Shop a List still works on Admin and Mobile.
  • Kitchen Inventory / On Hand remains shopping-list-managed.
  • Database Admin remains scoped/masked.
  • No large logic was added to inky_admin_app.py.

Deliberately not included

The first complete version intentionally avoids:

  • copying an entire week forward;
  • Blackcap-to-Blackcap meal-plan sharing/import;
  • inventory-aware reductions inside Meal Planner;
  • barcode/product capture inside Meal Planner;
  • long-press-only mobile drag/drop.

Those can be considered later, but the current design keeps planning fresh and lets Shopping Lists own shopping/inventory execution.

Display Content Flow Completion Notes

  • Recipe Library and Meal Planner now use page-local lightweight Send to Display(s) dialogs instead of redirecting to the Displays page. Recipe Library send is per recipe only; Meal Planner send targets the current day/week/month meal-plan content model.
  • Display content summaries now treat Default as the primary state and suppress redundant Current rows when Current effectively matches Default after normalizing meal-plan and recipe settings.

Home Today & Tomorrow workflow

The Home dashboard embeds a focused Today & Tomorrow meal-planner workflow. It is not a full replacement for the Meal Planner page, but both day panels are operational:

  • add recipes
  • add manual items
  • use Recipe Discovery
  • edit/delete entries
  • edit people served
  • drag entries within the same day
  • drag entries between today and tomorrow
  • create a shopping list from selected day(s) or selected slot(s)

The day-level shopping buttons are toggles. A selected day is styled as selected and clicking it again clears that day. Selecting individual meal slots for a day clears that day-level selection. If nothing specific is selected, Home defaults the shopping-list creation to both today and tomorrow.

The selected Recipe Quick Actions recipe can be dragged into a Today/Tomorrow meal slot. The selected recipe card also provides Add to Meal Plan, which asks for day and slot for users who prefer a button-driven flow. When recipe servings are known, the meal-plan multiplier is calculated from the destination slot’s people-served value. When servings are unknown, Home falls back to the selected quick-action multiplier.

Recipe Library and Home add-to-plan actions

Recipe Library recipe cards include a direct calendar action immediately after Select Recipe. The popup supports any date and active slot, calculates people-served scaling through the shared recipe multiplier services, and offers only valid multiplier choices, including discrete/whole-unit restrictions. Its multiplier editor uses the same circular minus button, multiplier pill, circular plus button, and friendly denominator guidance as the Meal Planner entry editor.

Home keeps a focused workflow with Today, Tomorrow, and Other. Today and Tomorrow retain slot-based scaling. Other accepts only dates after tomorrow, loads active slots for that date, and adds the recipe without expanding Home into the full Meal Planner. The server validates the future-date boundary using the organization time zone.

Shopping-list selection guidance

The Admin Meal Planner makes the shopping-list scope explicit:

  • With no Shop day/slot boxes selected, the button reads Create Weekly Shopping List and the displayed week is used.
  • With one or more boxes selected, the button reads Create Shopping List and only the selected days/meal slots are used.

The helper text updates as selections change, weeks are rerendered, or the page is restored through browser navigation. The server remains authoritative: explicit selections are honored, while an empty selection is resolved from the displayed week anchor and organization week-start behavior. Home keeps its separate Today/Today-and-Tomorrow default.

Recipe search results in Meal Planner also include a compact View PDF link when a valid cached recipe PDF exists. It opens through the existing permission-checked recipe PDF route and does not disturb the current search dialog.

Shopping readiness and complete-or-blocked lists

Meal Planner never knowingly creates an incomplete Shopping List from the selected Meal scope. A real Recipe is Shopping Ready when Blackcap has authoritative editable structured Recipe content with at least one usable ingredient. Display-cache state is intentionally separate: a Recipe whose PDF/image cache is still queued or building is allowed when its editable ingredients already exist.

Before Shopping review, Blackcap evaluates every selected Recipe and unresolved Recipe Suggestion on the server. An unresolved Recipe Suggestion blocks Shopping until it is converted to a Meal Item or resolved into an actual Recipe. A Recipe whose authoritative capture is still actively running also blocks temporarily; the Shopping dialog shows Preparing Recipes for Shopping… and automatically rechecks until the final ingredient list is available. A terminal capture failure or a Recipe with no usable ingredients and no active background work stops the wait and identifies the Recipe that needs attention. The final Shopping-list creation endpoint repeats the same readiness checks, so an API caller cannot bypass the rule.

Meal Slot ordering and recipe summary

Stored Meal Slot item order is authoritative everywhere Blackcap presents a slot. The first ordered item is the display anchor even when it is a manual Meal Item rather than a recipe. For example, an ordered slot containing Garlic Bread, Lasagna, and Salad is presented as Garlic Bread w/ Lasagna and Salad; recipes are not automatically promoted ahead of earlier manual items.

In Admin and Mobile Meal Planner, selecting a recipe name opens the shared Meal Slot Summary for the entire slot. The clicked recipe is highlighted, while all recipes and manual items remain visible in stored order. Recipe entries show existing metadata such as Total Time, Cleanup, Time & Effort, and Servings when available, plus the existing secure PDF action and a validated HTTP/HTTPS source link where one exists. Manual Meal Items do not receive meaningless blank recipe metadata.

Whole-Meal identity, name, and image

A populated dated Meal Slot also has a persistent Meal identity that is deliberately separate from its optional AI Meal Plan. Before the user customizes it, the Meal name is derived from the authoritative stored Recipe/Meal Item order, but Meal Planner and Home do not add a separate Meal grouping row merely to repeat that automatic concatenated name. A compact ✏️ beside the populated Meal Slot header lets a manager name the Meal without adding permanent visual clutter.

Once a custom name such as Thanksgiving Supper is saved, Meal Planner and Home add the Meal grouping layer between the Meal Slot header and the individual entries. Clicking that custom Meal name opens the same whole-Meal popup as clicking a Recipe, Meal Item, or item-count pill. The compact ✏️ moves beside the custom Meal name; editing is in place with 🙂 Add emoji, ✓ Save, and X Cancel, and the same Blackcap-safe emoji picker is available from both Meal Planner/Home and the whole-Meal popup. Saving an empty value restores automatic naming and removes the extra grouping row. Blackcap uses the custom name anywhere the whole Meal needs a concise identity—including Meal Planner summaries, Ready to Cook, review/share data, and Meal Plan display rendering—without renaming the underlying Recipes. Changing only the Meal name does not invalidate a saved AI Meal Plan.

The Meal Slot popup places a whole-Meal image/placeholder to the left of the date, Meal Slot name, and Meal name. Clicking the image opens the same choice pattern used by Recipe metadata: Upload Image or ✨ Generate AI Image when AI is available. The AI image dialog uses the browser modal top layer, so it remains above the Meal Slot popup while it is active. Uploaded images are normalized into durable Meal-owned storage. AI Meal images reuse the existing Recipe-image Quality Profiles, provider configuration, Organization/Personal AI Seed choices, asynchronous job/status workflow, candidate review, Use This Image, retry, and Generate Another behavior. There is no separate Meal-image quality configuration.

For AI generation, Blackcap sends the current Meal name plus every Recipe and Meal Item in the Meal as trusted visual context and asks for one coherent finished-meal photograph/table spread—not a collage or labeled grid. The listed foods remain authoritative; image generation does not rewrite Recipes or the AI Meal Plan. An accepted Meal image becomes persistent presentation metadata and is preferred by Meal Plan displays; if no Meal image exists, existing Recipe-image fallback behavior remains available. Changing the Meal image does not invalidate a saved AI Meal Plan.

The image has a ▶️ overlay that is the whole-Meal Let’s Cook selection action. There is no separate Cook Meal panel. The badge uses the same compact bottom-right treatment as Recipe image start badges on the Let’s Cook page. Pressing ▶️ navigates to Let’s Cook with that Meal preselected in Start cooking by recipe or meal; it does not start a session from the Meal popup. The user chooses the Cooking Display on Let’s Cook and then explicitly starts the session.

Whole-slot/day moves carry the Meal identity when the Meal moves into an empty or replaced destination. Appending individual items into an existing Meal preserves the destination Meal identity, and removing/moving the final individual entry clears the now-empty Meal identity so a later Meal in that calendar cell does not inherit an old custom name or image. Organization backup/restore and diagnostic cloning include Meal identity and Meal image files.

The summary deliberately does not sum recipe times or invent an aggregate cleanup/effort score because recipes in one slot may be prepared in parallel. The dialog supports keyboard activation, Escape/close behavior, focus return, and mobile scrolling.


Plan Meals — decide what to eat

Plan Meals (plural) is a separate first-class AI use case from Plan Meal. Plan Meals decides what existing Recipes, Recipe Suggestions/new Recipes, and Meal Items to add across multiple selected dates and Meal Slots; Plan Meal coordinates how to cook one already-populated Meal Slot. One never renames or repurposes the other.

Plan Meals uses one conservative Meal Item-versus-Recipe classification contract across OpenAI, Gemini, and Anthropic Claude. The AI provider owns the primary classification; Blackcap only overrides it when a food is strongly recognizable as a simple ready/basic-preparation Meal Item or as a preparation that clearly benefits from Recipe guidance. Find & Add does not change that classification. It only determines how a true Recipe candidate gets a source. For a model/profile without grounded web search, Blackcap hands the Recipe candidate to the configured server-side Recipe Discovery provider (Agent Search, Brave, or Tavily). Automatic Find & Add resolves at most one Recipe per Meal Slot, preferring the primary; other genuinely complex dishes can remain Recipe Ideas. When a captured page exposes only a generic title such as Recipe or Untitled Recipe, Blackcap preserves the specific planned/search title hint instead of saving the placeholder into the Recipe Library.

From Admin Meal Planner, the same transient plan/shop checkboxes used by Create Shopping List select dates/slots for Plan Meals. A single operation supports at most 7 distinct calendar days, including noncontiguous dates. If nothing is checked in a visible period of seven or fewer dates, Plan Meals initializes the whole visible period. If the visible period is longer than seven dates (normally Month view), Blackcap does not choose an arbitrary week or invoke AI; the user must select up to seven dates. More than seven explicitly selected dates are blocked before AI Seed confirmation. A successful Plan Meals or Shopping action clears the shared plan/shop selections.

The shared Plan Meals dialog uses the organization’s actual configured Meal Slots. Slot types can be selected in bulk across selected dates and then toggled for individual date/slot cells, making patterns such as Dinner-only on the first day and Lunch-only on the last day straightforward. Home uses the same dialog/service but exposes only Today and Tomorrow.

Dynamic AI Seed quote

Plan Meals pricing scales with the number of selected Meal Slots submitted to the provider, not the number of additions returned and not the number of calendar days. Each Plan Meals Quality Profile configures Base AI Seeds, Meal Slots Included, Additional Meal Slots per Block, Additional AI Seeds per Block, and a Find & Add AI Seed Surcharge. Blackcap calculates base + ceil(max(0, selected slots - included slots) / block size) × additional Seeds + Find & Add surcharge (when enabled) on the server and shows the exact result before confirmation. The Quality Profile editor includes a live 1/5/10/20/35-slot preview plus the configured Find & Add surcharge.

When Create Original Recipes with AI is selected, a compact Max AI recipes per Meal Slot selector offers 1–4 (default 1). A separate recipe is generated for each eligible unresolved Recipe Idea up to that cap; existing Recipes in the selected slot are protected. Optional Create Image uses a separate Quality Profile and can generate one image for each newly created Recipe. The Seed table displays a minimum (the planning charge) and a maximum (planning plus all permitted new recipes and their optional images); the number of eligible original-generation slots is computed from current server-side Meal Slot state. The confirmation checkbox authorizes the maximum and reserves the whole maximum once. Blackcap settles the validated planning portion, transfers held allocations to each actual recipe/image job without reserving those Seeds twice, and releases any unused allowance when the run finishes. Rejected provider responses release the unspent hold; failed optional image jobs do not create a second charge. Changing the 1–4 limit, selected profile, image setting, dates, or Meal Slots invalidates the previous quote/confirmation. The limit does not override recipe quality, required user permissions, existing slot content, or unavailable provider results; some complex sides can still remain Recipe Ideas when no complete result is available.

The Plan Meals dialog requests a trusted quote whenever selected dates/slots, Quality Profile, funding source, Inventory/taste context, Dietary Preferences, or Find & Add changes. Directly under the Quality Profile choices it explains the quote as base Seeds, included slots, additional slot blocks, any Find & Add surcharge, and the total. The Organization/Personal AI Seed cards then show available, required, and remaining balances, and the confirmation names the exact Seed amount. Submit recalculates from trusted server-side state and validates the approved quote token/Seed amount. If pricing or request context changed after approval, Blackcap rejects the stale quote and requires a fresh confirmation rather than silently reserving a different amount. The Standard profile starts with a provisional +4 AI Seed Find & Add surcharge based on the first matched production comparison; the surcharge is profile-configurable and should be tuned with Cost Alignment/reconciliation history rather than assumed permanent.

Planning options include:

  • Dietary Preferences & Restrictions — initialized from organization defaults but editable for this run without silently rewriting those defaults.
  • Consider Kitchen Inventory — offered when automatic Inventory tracking is enabled. With On Hand Only, Plan Meals keeps the existing compact available/not-available behavior. With Full Inventory Tracking, Blackcap also sends compact aggregate package quantity estimates (without Product/package identity). The provider is told not to favor a dish because an ingredient is on hand when a typical amount for the selected people would materially exceed the tracked estimate; the dish may still be selected for other reasons because a later Shopping List can supply the difference. Plan Meals never reserves/subtracts Inventory or creates Shopping items.
  • Use Recipe Library and recent Meal Plans as taste preferences — sends compact Recipe Library evidence together with how often each sampled Recipe has appeared on the Meal Planner, the Recipe’s Made It rating when one exists, and high-level frequency/recency summaries for Meal Items and unresolved Recipe Ideas. An absent rating is explicitly unrated/unknown, never a dislike signal. This remains taste context, not a Recipe-ID catalog from which the provider chooses. Existing Recipes already in selected Meal Slots are always supplied as immutable current Meal context.
  • Prefer recipes already in the Recipe Library — checked by default. Blackcap builds a compact, organization-scoped catalog of actual reusable Recipe candidates instead of sending complete Recipe objects. It pre-ranks up to 20 candidates per configured Meal Slot Recipe Type using exact Recipe Type fit first, then broader type/category/title fit, Made It rating when present, historical Meal Planner use, and—when duplicate minimization is enabled—a meaningful 30-day recency penalty; candidates are deduplicated before they are sent. Candidate rows carry the trusted Recipe ID/name, applicable configured Recipe Type(s), useful timing metadata when available, prior-use count/date, and optional ingredient names when Kitchen Inventory context is enabled. Missing ratings stay unknown/neutral. The provider is instructed to return existing_recipe with the exact supplied Recipe ID. Blackcap revalidates that Recipe against the active organization before adding it and, if a provider instead copies the exact unique supplied Recipe name while mislabeling it as a Meal Item/Recipe Idea/new source, safely repairs that representation back to the trusted existing Recipe; ambiguous duplicate names are not guessed. This is a strong preference, not a quota or hard constraint: a poor-fit library Recipe should not be forced merely to avoid a new one.
  • Try to minimize duplicated meals over the past month — sends a compact 30-day Meal Plan history immediately preceding the selected planning period and asks the provider to prefer variety across exact meals and substantially similar types of food. This is a soft preference rather than a hard exclusion, so dietary needs, the Planning Request, immutable content, or sensible staple repetition can take priority. When it is combined with Prefer Existing Recipes, recently used library Recipes are penalized before candidate selection but remain eligible when genuinely the best fit. Recipe Library rows are collected once and reused for taste evidence and existing-Recipe candidates; Meal Planner history is likewise shared where applicable rather than redundantly rebuilding/sending the same evidence.

The five Plan Meals context/source options use compact ⓘ tooltips rather than always-visible explanatory paragraphs, keeping the setup dialog shorter while preserving guidance for Kitchen Inventory, taste preferences, existing-Recipe reuse, recent-duplicate minimization, and Find & Add Complete Recipes.

  • Find & Add Complete Recipes — when enabled, Blackcap automatically turns new Recipe candidates into real Recipes when possible. Find & Add changes source acquisition only; it does not make a simple Meal Item into a Recipe. When Find & Add actually creates a new Recipe, Blackcap assigns the Recipe Type configured on the target Meal Slot (for example, a Recipe created for a Dessert slot configured as Dessert is saved as Dessert). If acquisition resolves to a Recipe that already existed in the organization library, Blackcap keeps that Recipe's existing type rather than silently retyping it. When Prefer Existing Recipes is also enabled, Find & Add is explicitly a fallback after suitable existing organization Recipes, other reasonable library Recipes, reusable Meal Items/Recipe Ideas where appropriate, and normal fit/variety constraints have been considered. A profile/model with grounded web search is encouraged to return a real Recipe URL and is labeled Grounded web search; Blackcap uses that URL only when it passes Recipe Search rules and can be captured. A profile without grounded search can still use Find & Add when server-side Recipe Discovery (Google Agent Search, Brave Search API, or Tavily Search API) is configured, in which case Blackcap resolves the missing URL after planning. Meal Items bypass Recipe Discovery. If neither the selected provider/model nor configured server-side Recipe Discovery can resolve Recipe sources, Find & Add is blocked before Seed reservation. When Find & Add is off, new dishes that need Recipes remain Recipe Ideas.
  • the normal Quality Profile, Organization/Personal AI Seed source, displayed Seed balance/cost, and explicit spend-confirmation checkbox. Quality Profiles and Seed sources use the same selectable tile treatment as Blackcap’s other AI workflows. The Plan Meals action remains disabled until the user explicitly checks the AI Seed/provider confirmation; changing the selected profile, funding source, planning scope, context flags, or temporary dietary settings clears that confirmation.

To reduce partial provider responses on larger selections, Blackcap supplies a compact required-Meal-Slot checklist with an explicit minimum_additions value plus request-specific structured-output bounds requiring the response to contain exactly the selected Meal Slot count. Provider schemas also constrain returned dates/Meal Slot references to the selected values. If a provider nevertheless omits a selected slot, leaves an otherwise-empty slot blank, or returns a populated Lunch/Dinner that still lacks a substantive main/primary and has no usable same-response main completion candidate, Blackcap performs one narrow repair interaction for only those affected selected slots before AI Seed settlement and before Find & Add source resolution. The repair request is included in provider token/cost/request-count evidence but does not reserve another AI Seed. A main-composition repair asks the provider for a complete replacement for that slot with a substantive role=primary addition rather than attempting to invent a primary meal locally. If the original/repair response already contains a valid same-response completion candidate for a blank or composition-incomplete slot, Blackcap can use that provider-supplied candidate without another repair. Final local validation remains authoritative and still rejects unselected scope, unresolved blank slots, or a Lunch/Dinner that remains without a substantive main after repair.

Plan Meals executes asynchronously. After submission, the setup controls switch to the standard AI progress checklist rather than freezing the page: Seed reservation, selected Meal Slot preparation, any enabled dietary/Recipe-preference/Inventory context review, provider submission/planning, plan validation, current-slot/source verification, optional Recipe source resolution, Meal Planner application, and completion. In complete-Recipe mode the source-resolution stage reports per-Recipe progress such as Capturing Recipe 2 of 4. That stage now uses a bounded direct-HTTP preview only: it does not launch Playwright/Chrome-Extension browser fallbacks inline while the Plan Meals job is still resolving other sources. Newly created Recipe cache builds are deferred until all selected Meal Slots have finished source resolution/application, then queued together so the heavy browser/cache worker does not contend with the planning job. Only stages relevant to the selected options are shown. Closing the dialog does not cancel the background job; reopening it while the job is active resumes the current status. The dialog header and ✕ Close control remain anchored while its body scrolls.

Plan Meals provider output is treated as untrusted structured data. The v3 response envelope uses the canonical plan-meals-v3 schema version and retains explicit meal-composition roles, existing-slot coverage, and same-response completion candidates while adding first-class existing_recipe selection, trusted recipe_id, and optional existing-candidate rejection evidence. The placement role field is deliberately limited to primary, side, or other; meal-composition labels belong in meal_roles (main_protein, vegetable, starch_grain, fruit, dairy). If a provider puts an unambiguous alias such as main, main_protein, side_dish, dessert, or snack in the placement field, Blackcap normalizes it locally and retains normalization evidence; arbitrary/unknown roles still fail validation. Legacy v1/v2 aliases are accepted only as an in-flight compatibility bridge and are canonicalized to v3 before local validation. OpenAI and Claude use the full response schema while Gemini receives the compatible guidance schema derived from the same addition contract; provider-specific structure never weakens Blackcap’s authoritative local scope/content/organization validation before any Meal Planner mutation.

Plan Meals is additive. Existing Recipes, Meal Items, and Suggestions are immutable to the operation. The provider may add complementary content or return no additions for an already-complete slot. Blackcap validates provider output server-side, re-reads each Meal Slot before applying it, skips safely on concurrent changes, prevents obvious duplicates, preserves existing relative order, and keeps a primary first when a missing primary is added. A retry is idempotent rather than duplicating the same additions.

For Lunch/Dinner slots, Plan Meals treats meal completeness as part of the same paid planning operation. The normal balance target is a substantive main/protein anchor plus vegetable coverage and starch/grain coverage when appropriate; low-carb/keto settings make starch/grain optional. One Recipe may satisfy multiple roles. The provider must label additions with meal roles and include fallback completion candidates in the same response whenever a required role could remain missing. Blackcap then validates coverage locally before applying the plan. If a role is still missing, it uses the provider's same-response candidate first and finally a conservative built-in Meal Item fallback (for example steamed broccoli or steamed rice) rather than making another provider request. The user therefore does not need to rerun Plan Meals or spend another AI Seed because the first response omitted a simple side. Completion source/role and the count of balance items added are retained in Plan Meals application/AI Usage evidence.

Complete Recipe acquisition

With complete-Recipe mode off, dishes that need Recipes become Recipe Suggestions. With it on, Blackcap performs unattended source selection per Recipe. A web-search-capable provider is encouraged to return a real public Recipe URL during the bounded Plan Meals request; that URL is preferred only when it passes active include/exclude rules and can actually be acquired. If the provider supplies no usable URL, the selected model has no grounded web-search capability, or capture later fails, configured server-side Recipe Discovery (Google Agent Search, Brave Search API, or Tavily Search API) automatically resolves that Recipe without changing the rest of the response. The fallback searches with Recipe name + ingredient hints, retries once with the Recipe name alone, prefers a non-slow allowed source, and can use an otherwise-valid slow source as a last resort before leaving a Recipe Idea. One response can therefore mix provider URLs and Recipe Discovery-selected URLs. If neither the selected profile/model nor configured server-side Recipe Discovery can resolve sources, Find & Add is blocked before Seed reservation. Meal Items never enter Recipe Discovery solely because Find & Add is enabled.

Meal Item versus Recipe Idea is based on whether reusable Recipe instructions materially help, not simply whether heat or multiple ingredients are involved. Ready-to-serve foods and simple preparation/assembly—such as sliced fruit, bread/toast, avocado toast, simple eggs, plain grains, baked potato, or plainly steamed/roasted/sautéed vegetables—default toward Meal Items. Dishes with meaningful technique, multi-step preparation, sauces/marinades/batters/dressings, or important ratios/timing remain Recipe candidates. Blackcap gives this guidance to the provider and applies a conservative local safeguard before Recipe Discovery so an obvious Meal Item does not consume a search/import unnecessarily.

For Recipe candidates, Blackcap validates public HTTP(S) URLs with its existing public-URL/SSRF protections, checks existing source/canonical Recipe identity first, and reuses the normal Recipe acquisition/write architecture. If the same source already exists, the existing Recipe is reused instead of duplicated. The AI-provided original dish name and ingredient/source/dietary context are retained as Plan Meals provenance even when the attached Recipe has a different canonical title, so later Recipe → Meal Item → Recipe Idea corrections recover the original planning intent.

Ordinary Recipe pages use the standard URL capture path with a Plan-Meals-specific performance guard. Before the provider request, the trusted planning snapshot includes Blackcap's active Recipe Search include/exclude patterns and currently known slow Recipe source domains. The AI is guided toward sources Blackcap can consume and away from historically slow publishers. Slow-site status is a preference rather than a hard prohibition: Blackcap prefers a non-slow allowed source but can use an otherwise-valid slow source when that avoids leaving an unnecessary Recipe Idea. For allowed domains Blackcap performs a bounded direct-HTTP structured preview; when that preview already contains a complete Recipe it can be written immediately. If the grounded URL is valid but the direct preview is blocked or incomplete, Blackcap does not wait for Playwright/Chrome-Extension fallbacks and does not immediately downgrade it to a Recipe Suggestion. It creates/reuses the normal URL-backed Recipe record through the same Recipe write service used by Add Recipe, links it to the Meal Plan, and defers the shared cache build until source resolution is finished. Full browser/cache fallback therefore runs at most in the normal background cache pipeline rather than once during Plan Meals and then again during cache generation. Supported social sources reuse the existing social/Chrome Extension architecture rather than a Plan-Meals-specific scraper. If the deployed environment cannot safely complete an automatic browser/Extension capture, or a social source requires another AI operation, the source is retained as a Recipe Suggestion for later resolution; Plan Meals itself still succeeds.

If a source later requires another AI operation, Blackcap does not run it automatically. The Suggestion remains durable and Plan Meals shows Review additional AI. The user separately chooses an applicable capture Quality Profile and Organization/Personal Seed source, sees the additional Seed availability/cost, explicitly approves that Seed spend, reviews the resulting Recipe draft, and imports it. That follow-on work creates its own normal AI Usage record under the actual capture use case and is correlated to the originating Plan Meals/Suggestion metadata rather than double-counted as Plan Meals usage. Sources that require an active interactive Chrome Extension tab remain Suggestions and are resolved through Recipe Discovery/Extension instead of using test-only browser automation in production.

A Recipe Suggestion that is waiting for follow-on capture retains the Dietary Preferences & Restrictions snapshot from the originating Plan Meals run. This matters when that run temporarily changed the family defaults. Before a follow-on AI Recipe is imported and replaces the Suggestion, Blackcap rechecks the draft against that original snapshot rather than substituting whatever the organization defaults happen to be later. If there is an obvious conflict, the Suggestion remains unresolved. The user can keep it as a Suggestion, resolve it through Recipe Discovery with an intentional temporary dietary change, or manually add a different Recipe. Manual Recipe and Meal Planner entry remains available even when it falls outside the organization baseline.

Correcting an over-promoted Recipe

Any planned Recipe can be converted to a Meal Item directly from the Meal Planner when automated planning made something simple more complicated than it needs to be. The replacement stays in the same Meal Slot and position and becomes a normal Meal Item for shopping/cooking behavior. Conversion never silently deletes the Recipe Library record.

Recipe-backed Meal Planner entries use the current Recipe Library title as their canonical visible name. Plan Meals nevertheless retains the AI provider's original proposed name and discovery context separately. When that Recipe is converted to a Meal Item, the Meal Item returns to the original Plan Meals name instead of inheriting the selected Recipe's title. The retained context includes the original ingredient hints, role, source hint/import correlation, dietary snapshot, and Plan Meals job correlation. If that Meal Item is later converted back to a Recipe Idea, Blackcap restores those saved hints/context while respecting the Meal Item's current visible name, so a user edit is not discarded. Migration 245 adds the durable original-name/context fields; older Plan Meals entries backfill the recoverable original name from their stored pre-245 title.

The week/day calendar uses the same canonical naming rule: a Recipe shows its Recipe Library title unless the user explicitly customized the whole Meal name. Truncated calendar/entry labels expose the full current name in the hover/focus tooltip rather than the generic “View whole Meal Slot summary” text.

Blackcap offers Also delete this Recipe from the Recipe Library? only when durable provenance proves all three conditions: the Recipe was newly created by Find & Add, the Meal Planner entry is tied to the exact Plan Meals job that created it, and that entry was created within the last 24 hours. The same guard applies when deleting the Meal Planner Recipe entry itself and when using drag-to-Delete. An older Find & Add Recipe, an existing/library Recipe reused by Plan Meals, or a manually added Recipe can still be removed from the Meal Planner or converted to a Meal Item, but Blackcap does not suggest deleting the underlying Recipe Library record. The normal Recipe archive/dependency safeguards remain authoritative if the user accepts a recent deletion offer. Migration 244 adds the exact Plan Meals job/Find & Add provenance fields used for this decision.

Dietary Preferences & Restrictions

Dietary defaults are stored at the organization level because a normal Blackcap organization represents a household/family. They describe what automated meal planning should normally favor for the group, not a hard prohibition on what users may store or schedule. A Recipe that falls outside the defaults can always be manually added to the Recipe Library or manually added to a Meal Slot.

Plan Meals prepopulates its Dietary Preferences & Restrictions from those organization defaults and allows the user to change them for the current run. Temporary changes apply only to that Plan Meals operation and do not silently update the organization. This makes it possible to handle guests, one-off meals, vacations, or an individual meal without changing the family baseline. The exact temporary snapshot used for the AI request is retained with Plan Meals AI Usage diagnostics.

Recipe Discovery follows the same model: organization defaults are preselected, but the user can temporarily change them for one discovery search/preview/save flow. This keeps Recipe Discovery and Plan Meals consistent while still leaving manual Recipe/Meal Planner entry under user control.

Organization-scoped dietary defaults use an extensible catalog rather than one boolean column per preference. Built-ins include Keto, Vegetarian, Vegan, Pescatarian, Low Carb, Dairy-Free, Gluten-Free, Nut-Free, Egg-Free, Shellfish-Free, Soy-Free, and Pork-Free, plus a bounded custom note for preferences such as “avoid mushrooms” or “prefer mild spice.” No option is preselected automatically.

These settings guide planning; they are not a medical allergen verification system. Existing Meal content always wins over automatic replacement, so a conflicting existing item is preserved and the planner should avoid compounding the conflict. When an exact Recipe is captured, Blackcap can reject obvious deterministic dietary conflicts or mark uncertain compliance for review rather than claiming certainty. The exact plan-time dietary settings are retained in the Plan Meals AI Usage snapshot even if organization defaults later change.

AI Usage and retained diagnostics

Plan Meals has its own AI use-case configuration, Quality Profiles, dynamic slot-block Seed pricing, provider/model/request IDs, token/usage/cost/latency accounting, success/failure reporting, summaries, filters, and What Happened view. AI Usage retains the pricing mode and curve inputs, selected day/Meal Slot counts, calculated block count, quoted/final Seed amount, Find & Add flag, Prefer Existing Recipes flag/candidate count, and Recipe source/readiness outcomes needed for provider-cost reconciliation. What Happened uses retained planning-time snapshots: selected dates/slots and immutable entries, the exact Dietary Preferences used, context flags, compact Inventory/taste context when enabled, the supplied existing-Recipe candidate catalog, accepted additions, source-resolution outcomes, and per-slot skips/conflicts. The Plan Meals details summarize Recipe sourcing (existing library Recipes, Meal Items, Recipe Ideas, and newly acquired Recipes) plus Existing-library reuse for applicable Recipe selections, while retained per-addition evidence includes the resulting sourcing type and any compact provider reason for bypassing suitable existing candidates. Provider input/output token usage continues to measure the extra candidate context for billing reconciliation and AI Seed Cost Alignment. Successful evidence is recognized from the retained accepted structured plan itself, so older successful Plan Meals rows remain readable even if they predate the explicit accepted evidence flag. Later Recipe Library, Inventory, Dietary, or Meal changes do not rewrite that history. Purging AI Usage diagnostic evidence does not delete current Recipes, Meal Items, or unresolved Recipe Suggestions.

Plan Meal and AI Meal Plans

A Meal Slot can optionally be planned with Plan Meal before cooking when there are at least two plan-worthy Recipe workloads. Two top-level Recipes qualify, and a top-level Recipe plus a discovered Component Recipe also qualifies because both contribute trusted Recipe steps that benefit from coordination. A single top-level Recipe by itself does not offer Plan Meal, and Meal Items such as salad, baked potato, or cranberry sauce never make an otherwise single-Recipe Meal eligible. Meal Items can still accompany an eligible multi-Recipe/Component plan. Plan Meal is an AI enhancement to Meal Planner; it is not required for Let’s Cook Meal. A meal can be planned the day it is created or days/weeks before it is cooked.

Execution intentionally differs by mode: without a current AI Meal Plan, Let’s Cook finishes one Recipe/Component stage before moving to the next stage in the stored deterministic sequence. With a current saved AI Meal Plan, Blackcap may interleave steps from multiple Recipe/Component stages according to the validated coordinated timeline. Meal Items are header-only context in both modes.

The Meal Slot popup keeps cooking independent from the optional Plan Meal area through the ▶️ control over the Meal image. ▶️ only selects the Meal for Let’s Cook and navigates there; it never starts the Meal from the popup. The Let’s Cook start panel shows either one Recipe or one Meal at a time, lets the user choose the Cooking Display, and hides the multiplier control in Meal mode. The Meal Planner's Meal name and item-count pill (for example, 2 Items) open this same Meal Slot popup.

Plan Meal uses the Meal Slot's current stored order as trusted context without rewriting that order. Before the provider request Blackcap resolves, server-side:

  • each Recipe and its independent Meal Planner multiplier;
  • exact same-organization Component Recipe matches;
  • deterministic Component quantity recommendations derived from the consuming Meal Recipe multiplier(s);
  • any explicit Component Recipe identity or batch override already saved for this dated Meal;
  • Recipe ingredients, instructions, and timing;
  • ordinary Meal Items and their notes as context-only sides;
  • the planning options below.

The provider does not decide Recipe quantities, servings, Component eligibility, Component yields, or Component multipliers.

Planning options

The Plan Meal dialog supports:

  • Serve At — optional. When supplied, Blackcap stores the target with the plan and calculates Suggested Start from the accepted Expected Total Meal Time.
  • Ovens Available — a per-plan numeric input, default 1.
  • Allow AI to adjust oven temperatures to coordinate dishes — optional and Off by default. When Off, source Recipe temperatures are authoritative. When enabled, an accepted plan may use a different planned oven temperature only when the source step actually supplied an oven temperature; the source and planned temperatures remain visible as provenance. The underlying Recipe is never edited.
  • Quality / AI Seeds — uses the same two-column radio-card interaction as Generate AI Image: Quality cards show the profile, provider/model, and Seed charge; separate Organization AI Seeds and Personal AI Seeds cards show availability and the selected profile’s charge. On narrow/mobile layouts the cards collapse to one column.
  • AI confirmation — Plan/Replan remains disabled until the user checks the provider/AI Seed confirmation. The confirmation text reflects the selected provider, charge, and Organization/Personal balance. Changing Quality or funding source clears the confirmation, and a failed request requires a fresh confirmation before retrying.
  • Asynchronous progress — Plan Meal queues an AI job and returns immediately, using the same background/polling pattern as Generate AI Image. While it runs, the setup controls switch to one persistent high-level checklist: Checking Meal details → Reserving AI Seeds → Preparing AI request → Planning with the provider → Validating Recipe steps → Coordinating Meal timeline → Saving Meal Plan. Completed stages remain visible with check marks, the current stage is highlighted, and upcoming stages stay visible so the user can see where Blackcap is without exposing model reasoning or duplicating the same stage in a separate spinner/status block. Success and failure are reported inline; the Meal Slot summary is refreshed only after a validated plan is saved. Closing and reopening the Plan Meal dialog while the job is active resumes the same progress view rather than creating another provider request.
  • Provisional Component handling — Plan Meal normally does not ask whether to make a Component, does not ask for a batch multiplier, and does not ask when to make it. Blackcap derives the normal batch from the consuming Meal Recipe multiplier(s) and conservatively includes unresolved Components in the AI request so the returned plan remains usable if they must be made. If exact-name discovery finds more than one matching Component Recipe, Plan Meal asks only which Recipe identity to use, using the same rich Component card used by Shopping and Let’s Cook. Final make/keep and batch decisions remain editable until Let’s Cook.

The accepted structured plan includes an Expected Total Meal Time. This is coordinated elapsed time for the whole meal and can be shorter than the sum of the individual Recipe Total Times because preparation, cooking, cooling, resting, and other inactive work can overlap.

When Serve At is provided, Blackcap displays the target and deterministic suggested start using the organization's standard 12-hour or 24-hour time format. In the detailed Meal Plan, every activity also shows its recommended wall-clock time plus a compact elapsed offset such as +1:15 from Meal start; the offset is guidance rather than an expectation that the cook hit the exact minute.

Plan Meal sends providers an explicit required-step coverage manifest in addition to the trusted snapshot. Every Recipe and Component Recipe source step must appear exactly once: providers are told not to merge, summarize, or omit even short informational/rest/chill/storage steps. The provider is also explicitly instructed to coordinate the whole Meal rather than finish one Recipe at a time. Component work may overlap with its parent and unrelated Recipes; only explicit source dependencies are hard blockers. When Serve At is supplied, providers are told to backward-schedule quality-sensitive finishing work as well as forward-schedule true prerequisites: hot mains, hot sides, sauces, mashed/crisp foods, and plating should normally finish close to serving rather than using every available minute of slack. The elapsed timeline must also stay compact: providers should move earlier independent work later or interleave useful work instead of inserting an avoidable multi-hour hole and turning a same-day dinner into a prior-day Suggested Start. A long gap should normally be backed by a trusted timer/rest/chill/cool interval or explicit dependency. Blackcap also applies a conservative no-cost compaction pass to pathological Serve At timelines: it preserves provider sequence, source order, explicit dependencies, and source-backed timer completion while shifting an earlier prefix later when the provider left more than four hours of otherwise unexplained slack. OpenAI receives per-Meal step-count bounds in its strict structured schema; Gemini keeps the same exact required-step checklist in the prompt but uses deliberately looser provider-side schema guidance because Gemini can reject otherwise valid dynamic array-cardinality constraints. Blackcap's strict local coverage validator remains authoritative for both providers.

Provider compatibility is handled at submission time without weakening Blackcap's accepted-plan validation. Original GPT-5 / GPT-5 mini / GPT-5 nano OpenAI Plan Meal profiles may keep the existing none value in Blackcap; the OpenAI adapter translates only the outgoing request to minimal, while newer GPT-5.x models retain none. Gemini Plan Meal uses a compact provider-only guidance schema that requires the expected top-level object and Meal Plan fields without sending the unusually deep strict contract that Gemini previously rejected. If Gemini still rejects that compact guidance schema with 400 INVALID_ARGUMENT, Blackcap retries once as application/json without provider-side schema constraints; the rejected schema request never produced a Meal Plan, and the successful response still has to pass Blackcap's full local schema, exact source-step coverage, and trusted-source validation. Harmless provider presentation wrappers (a single object inside a one-item JSON array or JSON string) are unwrapped, but malformed JSON is not repaired.

Plan Meal Quality Profiles keep Maximum Meal Plan output tokens as an explicit cost/control setting, but Blackcap no longer imposes a generic 20,000-token ceiling. The profile editor and backend validate against the selected provider/model capability: the current OpenAI GPT-5-family catalog allows up to 128,000 output/reasoning-budget tokens and the supported Gemini text catalog allows up to 65,536 output tokens. The configured value can remain lower; the model capability is only the allowed maximum. This is important for reasoning models because provider reasoning can consume part of the output allowance before the visible structured Meal Plan is emitted. Maximum input characters and output tokens are displayed with thousands separators in the Quality Profile editor while remaining numeric configuration values.

Timer values are source-authoritative in the same way Recipe content is source-authoritative. The provider is instructed to copy timer_seconds only from the exact source step's timer_candidates. During validation Blackcap canonicalizes that metadata to trusted Recipe data: an exact candidate is retained; a source step with exactly one timer uses that trusted duration even if the provider rounded/restated it; an invented timer or an ambiguous mismatch among multiple candidates is discarded to null. A trusted timer is also a hard scheduling-readiness constraint for that Recipe: the next source step cannot begin until the timer has actually elapsed. If the same source instruction performs active setup before a passive timer (for example mixing a marinade and coating chicken before a 3-hour chill), Blackcap treats the provider's active step end as the timer start and requires the complete trusted timer afterward. Pure timed actions such as a 30-minute bake are not double-counted when their planned elapsed step already spans the timer. If a provider schedules the next Recipe step too early, Blackcap first back-schedules that timer-bearing setup step without moving unrelated Recipe work; only any unresolved remainder is pushed later. The actual Let’s Cook timer controls continue to come from the trusted source Recipe step, never from an invented AI duration.

Provider timeline numbers are scheduling metadata rather than trusted Recipe instructions. Blackcap preserves each trusted Recipe's internal source order while normalizing harmless provider time arithmetic conflicts instead of discarding an otherwise valid paid response. If a provider puts a duration in estimated_end_minute, starts an explicit dependent step too early, or schedules a later same-Recipe step before a trusted timer is ready, Blackcap repairs the scheduling metadata while preserving source authority. Timer repair may move the timer-bearing preparation earlier than independent work from another Recipe, so the accepted sequence is re-sorted to match the repaired recommended-time order. Overlap remains encouraged across independent Recipes and during inactive bake/cook/rest/cool/chill windows, but a trusted timer cannot be shortened or bypassed. ingredient_refs are likewise descriptive provider metadata rather than Recipe authority: Plan Meal v9 tells providers to use only exact trusted ingredient_key values, and Blackcap deterministically rebuilds those references from each Recipe ingredient's trusted matched_step_keys when available. Provider ingredient names, guessed keys, or unknown values are discarded rather than rejecting an otherwise valid plan. Source Recipe text, timers, ingredients, temperatures, quantities, and step order remain authoritative.

Expected Total Meal Time is canonicalized from the normalized accepted timeline rather than treated as an independent provider authority. Blackcap uses trusted timer-aware completion, not merely the largest provider estimated_end_minute: a final 0 min + Timer 10 min rest therefore extends Meal completion by the trusted 10-minute timer, while a provider span that already includes the timer is not counted twice. This keeps Suggested Start correct across both Gemini-style passive steps and OpenAI-style elapsed spans.

Saved plan and detailed plan view

A successful Plan Meal is saved with the Meal Slot. The normal Meal Planner view shows a compact high-level summary and expected total; View Meal Plan shows the detailed ordered timeline without requiring the user to start cooking. 📋 Copy Meal Plan copies a human-readable version of the same plan—including expected/serve/start timing, the actual Quality Profile, provider and provider model used, and every numbered recommended step—to the clipboard so it can be shared or pasted back into diagnostics/analysis without screenshots. New plans persist this generation identity with the saved summary; older saved plans are decorated from their retained AI job when that metadata is still available.

The saved product Meal Plan is independent from temporary AI Usage diagnostic evidence. It remains available to cook even when its original AI Usage evidence later reaches retention, and a still-current saved plan remains executable if AI is subsequently disabled, a provider/model changes, or AI Seeds are unavailable.

Starting a selected Meal from Let’s Cook with a current saved AI plan, refreshing, resuming, moving to Next/Previous, checking ingredients, using timers, display updates, and voice actions do not make another provider request and do not consume AI Seeds. Meal Items remain passive Sides: context and are not execution controls.

The Let’s Cook Ready to cook meals surface also exposes a Meal Slot ▶️ selection action. It populates the same Start cooking by recipe or meal panel rather than starting immediately. The user may also choose a Meal manually from the enhanced Meal chooser. Only a Recipe or a Meal can be selected at once. Meal mode hides the ordinary Recipe multiplier and uses the per-Recipe multipliers already stored in Meal Planner.

The normal Meal chooser lists today and future Meal Slots only. A Meal with its own image shows that image; a Meal with an edited name shows that name. When a Meal has neither an edited name nor a Meal image, the chooser deliberately avoids the long concatenated automatic name and instead groups the individual Recipe/Meal Item names and available thumbnails beneath the Meal Slot. A past Meal is not offered in this normal chooser, but selecting ▶️ from that past Meal on Meal Planner or its Meal popup may still navigate to Let’s Cook with that exact dated Meal preselected.

Component settings for a dated Meal are persistent but provisional. The normal Component multiplier is derived from the consuming Recipe multiplier(s) until the user explicitly overrides it. Shopping can save a make/keep decision (and an override only when needed); AI Meal Planning conservatively schedules unresolved Component work without forcing those decisions; and Let’s Cook is the final checkpoint. The same rich Component card is used wherever a choice is actually required. Its action is consistently worded Make Component from scratch for and Shopping uses the same ✅ Continue action as Let’s Cook. In Let’s Cook the cook can still change make/keep and batch selection. For deterministic sequential cooking, the cook also chooses where the Component belongs in the Meal sequence. With a current AI Meal Plan, Blackcap uses the plan's coordinated timing for any Component that is still being made; changing it to already prepared safely removes that Component work without another provider request.

When the user presses ▶️ Start Let’s Cook in Meal mode, Blackcap passes those final component_choices to POST /api/lets-cook/meal-auto-start. A current saved AI Meal Plan is executed without another provider call, omitting Components finalized as already prepared; otherwise Blackcap uses deterministic sequential Meal execution and the selected Component placement. The final Let’s Cook choices are persisted back to the dated Meal for later reuse.

Protecting a current AI Meal Plan from edits

An AI Meal Plan represents a trusted snapshot. Blackcap therefore protects a current plan from being silently invalidated.

Before committing a material Meal Slot change, Blackcap checks for a current AI Meal Plan. This includes changes such as:

  • adding or removing a Recipe or Meal Item;
  • moving/reordering Meal Slot contents;
  • changing a Recipe multiplier;
  • moving the affected entry/slot/day in a way that changes the planned slot;
  • changing Component assumptions through a new plan.

The requested edit is not committed until the user confirms that the saved AI Meal Plan will become Plan Needs Update. The slot mutation and plan invalidation are committed together. Blackcap never silently replans or spends AI Seeds because of an edit.

Blackcap also watches Recipes referenced by current plans. A material Recipe edit made outside Meal Planner—such as changing its name/type, servings/yield, timing, ingredients, or instructions—requires the same confirmation before the Recipe mutation proceeds. Confirming marks every affected current AI Meal Plan stale. Cosmetic changes that do not change trusted planning content, such as imagery or category/layout presentation, do not unnecessarily invalidate a plan.

The same protection applies to alternate Recipe Library mutation surfaces, including bulk Recipe Type changes and Recipe archive actions when archival is otherwise permitted. Existing stronger archive rules still win—for example, a Recipe referenced by a future Meal Planner entry remains blocked rather than merely invalidating its AI plan. API clients receive the same 409 protection response and must explicitly resubmit with confirm_plan_invalidation.

A stale plan is not silently executed as current. Meal Planner offers Replan Meal while starting the Meal from the Let’s Cook page falls back to deterministic sequential cooking, and any old duration is presented as a previous AI estimate rather than current authoritative timing.

Delete AI Meal Plan

Delete AI Meal Plan removes only the saved AI planning result and its active source-reference protection. It does not delete the Meal Slot, its Recipes, or its Meal Items.

This is useful when the user already knows the Meal Slot needs substantial changes: delete the plan, edit contents/multipliers/Recipes normally, and run Plan Meal again when the Meal is ready. Replanning without first deleting remains supported; the existing good plan is replaced only after the new provider response validates successfully.

Anthropic Claude Plan Meal support

Plan Meal Quality Profiles can use compatible Anthropic Claude models in addition to OpenAI and Gemini. Blackcap's Claude catalog exposes a 64,000-token provider maximum for Haiku 4.5 and 128,000 for Claude Sonnet 5, Opus 5, and Fable 5.1. Claude 5 effort is configured through the same Quality Profile reasoning control; the provider's billed output total includes its thinking tokens, while AI Usage records the thinking subset separately for observability.

Original AI Recipes (0.7.3-alpha development)

An ✨ Create AI Recipe action on Meal Planner opens the shared original generation and review flow and saves a new Recipe to Recipe Library. After saving, manually choose that Recipe for the intended Meal Slot. This is separate from Plan Meals' automated selection.

Not yet implemented: selecting original recipe generation as an automated Plan Meals strategy; charging and confirming per-recipe additional Seeds in the Plan Meals quote; automatically persisting and associating every resulting new Recipe with the selected Meal Slot. Those actions require atomic plan application and distinct charges and must not be represented as complete in this build.

0.7.3-alpha — Create Recipe with AI in Plan Meals

Enable Create Original Recipes with AI to reveal its dedicated Quality Profile panel and the compact Max AI recipes per Meal Slot selector (1–4, default 1). The trusted upper estimate multiplies eligible Meal Slots by that limit and the selected Create Recipe profile's unit cost; actual generation is capped at that number of unresolved Recipe Ideas per slot. The estimate is conservative even when Library reuse or Find & Add means fewer creations are necessary. For example, four eligible slots, a maximum of two recipes each, and a 2-Seed Create Recipe profile adds up to 16 maximum recipe Seeds on top of Plan Meals. The approval checkbox reserves the entire maximum once; generated recipe/image jobs receive transferred portions of this same hold, and unused amounts are released on completion. Each child retains its own actual charge, AI Usage event, job identity, and failure handling. Existing Recipe reuse and successful Find & Add sources take precedence, and failed originals remain Recipe Ideas.

The completed Plan Meals dialog reports actual AI-created Recipes, AI-generated Images saved, and image-generation failures when applicable; these are outcome counts, not the quoted maximum. AI-created original Recipes have no source webpage URL, whether generated directly or during Plan Meals. If a Recipe Idea contained a suggested URL, creating an original Recipe does not transfer that URL to the saved Recipe. View Source remains available for genuine imported website Recipes.

0.7.3-alpha — Optional Create Image, cost confirmation and Discovery follow-up

Enable Create Original Recipes with AI to select an independent Create Recipe Quality Profile and choose 1–4 AI Recipes per Meal Slot (default 1). The Profile tiles show provider/model, output and reasoning settings. Also generate an AI image for each new original Recipe remains optional/off by default with a separate Create Image Quality Profile. The conservative maximum counts all eligible Meal Slots times the selected recipe cap, and up to one optional image per generated recipe; the minimum is the Plan Meals charge alone. The approved maximum is reserved immediately once, so the user needs that balance at submission. Blackcap charges only validated planning and actual child generations, transfers each child allocation from the same hold, and releases unused Seeds at completion. No additional child reservation is taken from the available account balance. Provider or validation failures cannot bypass the maximum; a failed component can remain a Recipe Idea.

If Prefer recipes already in the Recipe Library and Create Original Recipes with AI are both enabled, Blackcap prefers suitable existing Recipes first, then attempts other enabled sources, and creates a new original only when the slot still requires a Recipe. Existing Recipes already occupying Meal Slots remain untouched regardless of the options. With Library preference disabled, the planner may still choose an existing Recipe where appropriate; selection does not compel unnecessary duplication. If generation actually fails, the unresolved Recipe Idea remains available; Recipe Discovery → ✨ Create Recipe opens the same Create Recipe flow and can assign the completed result to that idea's Meal Slot. An optional image failure does not invalidate the successfully saved Recipe.

For constrained devices, the Plan Meals dialog shows immediately while configuration loads, avoids fetching unrelated page context on modal open, and debounces re-quoting when new creation options change. Original recipe and image generation runs sequentially to minimize Pi worker/memory pressure.

Recovering a delayed original Recipe (0.7.3-alpha)

Plan Meals original generation and interactive Create Recipe use the same provider and AI Seed ledger but different recoverable job ownership. Plan Meals waits if another durable worker is already processing its child Create Recipe request. A successfully created original replaces its matching unresolved Recipe Idea in the Meal Slot rather than being mistaken for a duplicate. If a previous release left a completed AI result attached to an unresolved Recipe Idea, opening Recipe Discovery from that idea and selecting ✨ Create Recipe first checks for the exact, current-user-owned prior result. A completed result is saved and assigned without another provider request or AI Seed charge. A still-running result is reported as pending rather than automatically resubmitted. Only if no previous usable result exists does the normal Create Recipe dialog open.

AI-created Recipe and Image completion counts (0.7.3-alpha)

The completed Plan Meals pop-up shows the number of AI-created Recipes and successfully saved AI-generated Images. When optional image creation was selected, it shows zero images if none were saved and indicates how many failed. These are actual results from the Plan Meals job, not the maximum authorized in the pricing quote. An image-generation failure leaves the Recipe intact; the workflow retains the specific image job error for regression diagnostics. If a recovery worker owns the image job, Plan Meals waits for the same durable job rather than generating a duplicate image.

On this page