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

Recipe Import and Discovery

Audience: User, Org Admin, Developer, Support Related: Overview · Editing And Cache · Social Import · Recipe Import

Normal recipe import accepts supported URLs and extracts structured data using deterministic sources first, including JSON-LD and page content, with rendering or slower-site handling when required. Recipe Discovery searches configured providers and returns candidate pages for capture.

Imported recipes should preserve source attribution, identify incomplete content, and move through review or editing rather than silently inventing missing ingredients or instructions.

Mobile URL, QR, and photo capture

Admin and Mobile can feed several capture inputs into the normal recipe pipeline:

  • paste a recipe URL directly;
  • photograph or upload a printed recipe page that contains a footer URL;
  • scan a QR code that resolves to a recipe URL;
  • upload one or more recipe photos/screenshots for image-based capture.

URL scanning uses a bounded sequence: pyzbar/libzbar as the fast QR path, OpenCV QR detection as a fallback, then OCR for printed URLs when the image is not QR-based. Raspberry Pi and GCP deployment scripts install libzbar0, and both dependency files include pyzbar.

Mobile uploads are resized and compressed before upload to reduce failures when a phone sleeps or has a slow connection. The full image is preserved rather than cropped by default. Multiple capture images can be combined into one recipe. Image-captured recipes remain organization-scoped and flow through the shared recipe, editable-content, indexing, and cache services.

Image capture is different from refreshing a public recipe source. Do not claim that an image-only recipe can be refreshed from a website unless it also has a valid source URL and the current workflow explicitly supports that action.

Recipe Photo Extraction profiles can use compatible OpenAI, Gemini, or Anthropic Claude vision models. When Recipe Photo Extraction AI is used, the durable AI Usage record can retain a bounded What Happened snapshot even if the user never accepts the AI result. That snapshot contains the provider-prepared photo input, Blackcap's built-in OCR recipe/raw OCR text, and the provider's structured recipe response before Blackcap applies user-field overlays, duplicate handling, or later recipe processing. The evidence follows the AI Usage record's lifecycle rather than the temporary capture-review directory. See AI Seeds and Usage.

Manual and recipe-photo duplicate identity

Manual recipes and image-only OCR captures do not have a stable source URL, so Blackcap uses their original ingredient and instruction content as a conservative source fingerprint. Recipe title and recipe ID are deliberately excluded from this identity: two recipes called Baked Chicken remain separate when their bodies differ, while re-entering or re-photographing the same recipe can update the existing recipe. Ingredient order, common unit/fraction spelling, punctuation, and small OCR character errors are normalized or compared at a very-high-confidence threshold. Fuzzy matching is disabled for very short recipes, and normalized numeric/fraction tokens must agree so a real quantity change is not silently treated as the same recipe.

The first manual/OCR ingredient and instruction values remain the fingerprint basis after later edits, AI review, unit conversion, or another matching capture. They are persisted as recipe_edit_content.original_ingredients_text and recipe_edit_content.original_instructions_text. Blackcap does not persist a separate fingerprint column: it normalizes those original values and computes the versioned SHA-256 fingerprint (manual-ocr-content-v1) when duplicate matching is needed. Older records can fall back to their effective editable/recipe content when the original fields are empty.

Exact normalized fingerprints are accepted immediately. For the OCR-specific fuzzy path, Blackcap requires a sufficiently descriptive body, comparable ingredient/instruction token counts, high token overlap, at least 0.965 sequence similarity in each section, and identical normalized numeric/fraction tokens in both ingredients and instructions. Ingredient order is ignored; instruction order is preserved. This deliberately favors an occasional duplicate over incorrectly merging two legitimately different recipes.

This additional content-fingerprint check is intentionally restricted to manual recipe creation and recipe-photo/OCR finalization. URL-backed, social, discovery, shared, and other recipe creation paths keep their existing source-identity behavior and do not run this matcher. Database Admin exposes the original identity text in Recipe Edit Content and the recipe source_type in Recipes; API Tester documents the same behavior on Manual Recipe Add and the executable Recipe Photo review/finalization calls.

A URL detected from photographed text or a QR code is not trusted simply because image processing found it. Before Mobile Add Recipe exposes the detected URL for use, Blackcap applies the same supported-source classification and public-network URL validation used for typed URLs. Non-HTTP(S) schemes, credential-bearing URLs, localhost/private/reserved destinations, and unsafe ports are rejected. URL/QR detection is a distinct capability from recipe import: detecting a URL fills/reports the URL and the user can then choose what to do next.

Recipe Type and Component yield during capture

Recipe Type is a primary choice during recipe creation and capture. Ordinary recipe types keep the existing servings-oriented behavior. When the user selects Component, the creation/review UI instead asks for a compact structured Yield quantity and unit, such as 2 cups. Yield may be left blank when it is not known yet; the recipe remains a valid Component but future Component batch planning will require a manual multiplier.

The user-selected Recipe Type is authoritative across asynchronous capture. Recipe-photo staging, social imports, Chrome Extension capture, and Recipe Discovery preserve an explicit Component selection and its structured yield through final save. Provider/OCR values such as Serves 8 are not allowed to replace that Component yield or to turn the Component into an eight-serving recipe. No AI call is made to guess missing Component yield.

For non-Component recipes, current extraction and servings behavior remains unchanged.

Total Time normalization during creation

Recipe creation uses one deterministic Total Time policy after captured/provider time fields have been normalized. An explicit valid Total Time is always authoritative, including an explicit zero. When Total Time is absent, Blackcap derives and stores it from non-overlapping canonical buckets: Prep; Cook or, when Cook is absent, Bake; Rest + Chill + Marinade when any of those specific passive buckets are present, otherwise Inactive; and Additional. Blank or invalid durations are ignored. Arbitrary provider-specific other_times remain preserved as source metadata but are not summed until Blackcap has a canonical semantic mapping for them.

The rule is shared by manual/API writes, website/JSON-LD capture, Chrome Extension capture, social extraction, photo/OCR/AI capture, shared imports, and supported file imports. AI providers are not asked to perform the arithmetic. The derived value is persisted so Recipe Library filters, Meal Planner, recipe details, search, and later workflows all see the same Total Time.

Optional Cookbook Categories during capture

When an organization has Cookbook Categories, creation/capture surfaces can optionally select zero, one, or multiple categories. The selection uses stable public category IDs and is validated against the receiving organization before assignment. Selecting a child does not automatically assign its ancestors. Category selection is user-authored metadata: it persists across URL/photo/social review and AI reruns without being sent to the extraction provider. If no categories are configured, the control stays out of the way and recipe creation behaves as before. Recipe-add/category action controls are hidden entirely when the active organization has zero configured Cookbook Categories; Configuration remains available so an administrator can create the first category.

Recipe Discovery workflow

Recipe Discovery is a web-recipe import workflow for both the Admin UI and Mobile UI. It lets a user search for recipes, review Blackcap-styled result cards, preview extracted recipe content, edit the preview, choose a layout, and save the result into the current organization’s Recipe Library.

Recipe Discovery intentionally does not embed arbitrary recipe websites. Many recipe sites block iframes, mobile iframe UX is poor, and Blackcap’s import preview is the safer workflow.

Current workflow

  1. Open Recipe Discovery from Admin, Mobile, or a Meal Planner slot.
  2. Enter search text and optionally choose a recipe type.
  3. Add “ingredients on hand” as chips using inventory, typeahead, or freeform text.
  4. Search results come from the configured Recipe Discovery provider and are rendered as native Blackcap result cards. The browser Programmable Search mode and the server-side Google Agent Search, Brave Search, and Tavily Search modes share the same preview/save workflow.
  5. Select Preview on a specific recipe result.
  6. Blackcap asynchronously extracts recipe metadata, ingredients, instructions, thumbnail, source URL, header info, and automatic cleanup estimate metadata.
  7. Edit the preview if needed.
  8. Choose or confirm the recipe type and layout in Preview/Edit.
  9. Save the recipe.
  10. Blackcap saves the recipe, indexes ingredients/search content, and queues the normal async cache build. The cache build can refresh total-time, nutrition, and cleanup-rating metadata shown on recipe cards.

Manual URL preview remains available even when search is disabled or Google is unavailable.

Dietary Preferences & Restrictions

Recipe Discovery starts with the current organization’s Dietary Preferences & Restrictions because an organization normally represents a household/family and the default discovery behavior should find Recipes that fit the people who routinely eat together. The organization settings are preselected in both Admin and Mobile Recipe Discovery.

The user can open Change for this Recipe Discovery and temporarily add/remove dietary selections or edit the custom dietary note. Those changes apply only to the current Recipe Discovery flow and do not rewrite the organization defaults. The active temporary snapshot is carried consistently through search, URL preview, ingredient conflict checking, and save; it is not allowed to revert to the organization defaults midway through the operation.

Dietary settings shape the Google search query itself (for example, Vegetarian adds vegetarian context and explicit exclusions for obvious meat/shellfish terms), and Blackcap also filters Google result titles/snippets that obviously conflict with the active settings before presenting them as Recipe Discovery candidates. Blackcap then checks the captured Recipe ingredients again before save. This is guidance rather than an absolute Recipe Library restriction: a Recipe outside the organization defaults can still be manually added through Blackcap’s normal recipe-entry workflows. Likewise, the organization default does not prevent a user from manually putting such a Recipe into Meal Planner. If a one-off Recipe Discovery search should intentionally look outside the household baseline, temporarily change the discovery settings for that run rather than changing the family defaults.

Dietary checks are deliberately conservative and do not claim medical allergen safety. Package labels, substitutions, cross-contamination, and other medical-safety verification remain the user’s responsibility.

Meal Planner return context

Recipe Discovery can be launched from a Meal Planner slot in either Admin or Mobile. When launched for a Plan Meals Recipe Idea, Blackcap carries the durable Suggestion context into Recipe Discovery: the suggested Recipe name pre-fills Search, atomic ingredient hints become individual ingredient chips, any safe retained source URL pre-fills Manual URL Fallback, and the exact Dietary Preferences & Restrictions snapshot used for that Plan Meals run becomes the Recipe Discovery baseline. This is important when Plan Meals temporarily changed the organization/family defaults; Recipe Discovery must search and validate against the same restrictions rather than silently reverting to today's organization defaults. The resolution link itself is intentional navigation and therefore does not trigger the generic unresolved-Suggestion leave warning. When the URL includes meal_plan_date, meal_slot_id, and return_to, the save flow keeps the normal Recipe Discovery behavior and then creates or replaces the Meal Planner entry for the selected date/slot.

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

Save behavior with Meal Planner context:

  1. Save the recipe into the current organization as usual.
  2. Write editable content, ingredients, and search index data as usual.
  3. Queue the normal recipe cache/PDF/image build.
  4. Create a recipe-backed Meal Planner entry for the supplied date and slot.
  5. Return the user to the appropriate Meal Planner page with the selected date still in context.

The context is optional. Standalone Recipe Discovery continues to save only to the Recipe Library.

Search provider recommendation

The implemented provider foundation supports:

  • manual_only — safe fallback. Users paste a recipe URL and use the same preview/edit/save workflow.
  • google_embedded_cse — Google Programmable Search / Search Element mode. Interactive Recipe Discovery uses the browser Search Element with only the Google Search Engine ID / cx; no API key is required for that browser-rendered search.
  • google_agent_search — server-side Google Agent Search basic website search. Blackcap owns the include/exclude URL rules, mirrors enabled rules into the Agent Search data store when configured to do so, and filters returned URLs locally before presenting or acquiring them.
  • brave_search — server-side Brave Search API. Blackcap translates enabled source rules into an inline Brave Goggle where possible, preserving compatible include-path patterns so non-recipe sections are less likely to consume provider result slots, then re-applies the complete Blackcap URL rules locally. Brave receives a concise provider-specific recipe query rather than the longer Google roundup/-intitle: tuning string. Interactive searches can build a result pool up to the configured Recipe Discovery Result Limit from Brave's native 20-result pages, de-duplicate overlapping URLs, and page the pool locally 10 at a time. Brave result thumbnails are used directly when returned.
  • tavily_search — server-side Tavily Search API. Blackcap sends each include rule to Tavily using the narrowest safe domain/path prefix, sends only true whole-domain exclusions upstream, requests up to 20 results per Tavily API call, and re-applies the complete Blackcap URL rules locally. When Recipe Discovery Result Limit is above 20, Blackcap can make multiple Tavily calls (up to five for a 100-result pool), partitioning curated source filters to broaden coverage before de-duplicating the combined results. Path-specific exclusions are deliberately kept local so a rule such as *.example.com/category/* can never be widened into an exclusion for all of example.com. Tavily also receives a concise natural-language recipe query rather than the Google-specific -intitle: / quoted-negative operator string used by CSE-style search. Interactive Recipe Discovery de-duplicates tracking/fragment variants of the same recipe URL and pages the returned Tavily candidate pool locally at Blackcap's normal page size, so moving between Tavily result pages does not spend another search credit. Tavily's richer extracted content is kept internally long enough for duplicate detection, but the visible search-result description is cleaned of Markdown/title repetition and shortened before being returned to the browser.

The backend does not scrape Google search-result HTML. When google_embedded_cse is selected, Google renders normal Recipe Discovery search results in the browser and Blackcap reads the rendered result metadata to build its own native result cards. The backend receives the selected Recipe URL for preview/extraction. For server-side curated search, Blackcap can use Google Agent Search, Brave Search API, or Tavily Search API with the same platform-owned include/exclude URL rules. Google Agent Search authenticates with Application Default Credentials/IAM; Brave and Tavily use encrypted platform API-key settings. The retired Google Custom Search JSON API and Agent Search searchLite API-key paths are no longer part of Recipe Discovery.

For interactive google_agent_search, Blackcap also performs a best-effort Agent Search image search and maps returned image thumbnails back to matching Recipe result page URLs. Google requires Enterprise edition features for text-to-image website search, and image search is not supported for blended-search apps. If image search is unavailable or not enabled, Recipe Discovery still returns the normal text results and simply renders the compact result card without an empty thumbnail placeholder. Background Plan Meals source resolution does not make the additional image-search request.

The UI keeps the Google source hidden when native result cards load successfully. It opens the Google source/verification area only when robot verification is detected or results fail to load. The source area can be closed after verification.

Older google_hosted_cse, google_programmable_search, google_cse, and google_hosted setting values are normalized to google_embedded_cse for compatibility.

Platform settings

Recipe Discovery settings live under Configuration → Platform → Recipe Discovery.

Setting key Scope Purpose
recipe_discovery.search_provider_type Platform Primary search method and on/off control: manual_only, google_embedded_cse, google_agent_search, brave_search, or tavily_search. Manual URL Only disables search while keeping direct URL preview available. The Configuration UI shows only fields for the selected provider.
recipe_discovery.google_cse_id Platform Google Search Engine ID / cx used by the existing browser-rendered Programmable Search option.
recipe_discovery.google_agent_search_project_id Platform Google Cloud project containing the Agent Search website data store.
recipe_discovery.google_agent_search_location Platform Agent Search location; basic website search normally uses global.
recipe_discovery.google_agent_search_collection_id Platform Agent Search collection, normally default_collection.
recipe_discovery.google_agent_search_data_store_id Platform Basic website-search data store used for curated Recipe Search and target-site rule synchronization.
recipe_discovery.google_agent_search_app_id Platform Agent Search application/engine ID used to serve searches. Google recommends app/engine search; Blackcap falls back to the data store when blank.
recipe_discovery.google_agent_search_serving_config_id Platform Agent Search serving configuration, normally default_search.
recipe_discovery.brave_search_api_key Platform Encrypted Brave Search API subscription token. Never included in portable Recipe Search exports.
recipe_discovery.brave_search_country Platform Two-letter country used for Brave Search localization; defaults to US.
recipe_discovery.brave_search_language Platform Brave Search language code; defaults to en.
recipe_discovery.tavily_search_api_key Platform Encrypted Tavily Search API key. Never included in portable Recipe Search exports.
recipe_discovery.tavily_search_depth Platform Tavily basic, fast, ultra-fast, or advanced search depth. Basic/Fast/Ultra-fast use one credit; Advanced uses two. Basic is the development default.
recipe_discovery.tavily_search_language Platform Tavily result language; defaults to en.
recipe_discovery.use_for_ai_plan_meals Platform When enabled, Find & Add prefers usable provider-supplied grounded Recipe URLs, then uses the selected server-side Recipe Discovery provider per Recipe when a URL is absent, rejected, uncapturable, or the selected provider/model has no grounded web-search capability.
recipe_discovery.search_result_limit Platform Maximum total Recipe Discovery result pool, capped at 100 and displayed 10 per page. Tavily and Brave each expose at most 20 web results per provider request/page; larger pools therefore use additional provider requests. Tavily distributes curated source filters across calls, while Brave advances native search offsets. Blackcap de-duplicates the combined pool before applying the full local URL rules.
recipe_discovery.extraction_timeout_seconds Platform Reserved extraction timeout setting for provider/extractor tuning.
recipe_discovery.positive_terms Platform Newline-separated search terms appended to queries.
recipe_discovery.excluded_phrases Platform Newline-separated phrases converted to negative quoted search terms.
recipe_discovery.excluded_title_terms Platform Newline-separated terms converted to negative intitle: filters.

Use Restore Search Defaults on that configuration page to restore the built-in query tuning defaults without changing provider credentials, Recipe Search rules, the AI Plan Meals checkbox, result limit, or extraction timeout. The same page provides Export Recipe Websites CSV, Test Server Search, Recipe Search rule management, Export Search Config, Import Search Config, and the Add New Recipe Source Wizard.

Google Agent Search uses Application Default Credentials (ADC) and IAM only. On Google Cloud, grant the Blackcap runtime service account Discovery Engine access in the Agent Search project; the predefined Discovery Engine Admin role is the simplest role that covers serving search plus Blackcap's create/list/delete target-site synchronization. The VM should use the cloud-platform OAuth access scope so IAM controls access. Blackcap stores no Agent Search API key, and migration 246 removes the retired Agent Search API-key/auth-mode settings and the old Custom Search JSON API key from existing installations. Migration 250 removes the older recipe_discovery.search_provider_enabled master toggle: recipe_discovery.search_provider_type is now the sole enablement/selection setting, with manual_only disabling search and any concrete provider enabling it.

Set Google Agent Search App ID to the application ID shown on Google Cloud's AI Applications page. Blackcap uses the app/engine serving config when this field is present, matching the serving-resource model used by Agent Search, while continuing to use Data Store ID for include/exclude target-site management. If the App ID is blank, Blackcap remains backward compatible by serving search directly from the configured data store.

Migration 243 adds Blackcap-owned Recipe Search include/exclude rules. Rules use Google/CSE-style URL patterns, exclusions take precedence, and Blackcap enforces the rules locally on every server-search result even when the selected provider also enforces them. Brave and Tavily receive the current compatible rules on every search request, so there is no persistent remote sync to manage. Tavily include rules preserve a fixed path prefix where possible, while path-specific exclude rules stay local rather than being widened to whole-domain exclusions. When Google Agent Search is selected and configured, Blackcap automatically mirrors enabled rules as target sites after rule changes and when Recipe Discovery provider settings are saved; there is no separate auto-sync toggle. Agent Search basic website search currently limits this to 50 include patterns and 50 exclude patterns. Blackcap refuses to partially synchronize when either limit would be exceeded. When a Blackcap rule has an exact path with no path wildcard (for example *.thepioneerwoman.com/food-cooking/recipes/), Agent Search synchronization sends it as an exact target site instead of allowing Google to broaden the path. A leading *. host wildcard is a Blackcap host-normalization convenience and is removed only from that exact Google request. Path-glob rules such as *.thepioneerwoman.com/food-cooking/recipes/* remain non-exact target sites. This allows a landing-page exclusion and its broader child-page include to coexist while preserving Blackcap's local rule semantics.

The Add New Recipe Source Wizard creates a disabled include-rule draft and tests it against the selected server-side provider. Agent Search temporarily synchronizes the draft target site; Brave and Tavily apply the draft filtering at request time. The wizard runs real searches, shows returned URLs, and lets the administrator add disabled exclude-rule drafts for noisy sections. Each returned URL also has a Preview action that opens the normal cancellable Recipe Discovery extraction in a modal; a successfully extracted Recipe can be added directly to the current organization's Recipe Library without leaving Configuration. Neither the draft include nor its draft exclusions affect production Recipe Discovery or Plan Meals. Activate Source enables the source and its associated exclusions; Agent Search then performs its authoritative target-site synchronization, while Brave and Tavily need no persistent remote rule sync. Cancelling removes newly-created drafts.

The Curated Recipe Search Rules panel is collapsed by default and shows the number of include rules in its collapsed summary. Expanding it shows rules sorted by URL pattern, with the Include rule before an Exclude rule when both use the same pattern. The rule list has a first-class Website filter populated from configured rule domains (including matching subdomains), text search across URL pattern/notes, Include/Exclude and enabled/draft-status filters, and 25/50/100 rows-per-page controls. Pagination is client-side over the already-loaded rule set, uses First/Previous/centered pages/Next/Last navigation, and preserves the active filter state across ordinary rule saves for the browser session. This keeps hundreds of curated rules manageable without changing rule-save semantics or adding extra server requests.

Export Search Config produces a portable JSON configuration containing include/exclude rules, their enabled states/notes, non-secret Recipe Search provider settings, query tuning, Plan Meals usage choice, and Agent Search resource identifiers. Brave/Tavily API keys are intentionally excluded. Import Search Config can replace or merge the rules on another Blackcap instance. Google Application Default Credentials are host/runtime identity and are deliberately not exported.

When Use Recipe Discovery Search for AI Plan Meals is disabled, Find & Add continues to use the Recipe URLs recommended by the selected AI provider. When enabled, Blackcap treats Find & Add as an unattended Recipe-selection workflow. It still records provider-recommended URLs for source-site analytics, then checks each Recipe candidate's primary URL and alternatives against the active include/exclude rules. Allowed provider URLs are used directly. A Recipe candidate with no provider URL, only rejected provider URLs, or a provider URL that later fails actual Recipe capture is automatically handed to the configured server-side Recipe Discovery provider. Automated Recipe Discovery uses the configured result depth (the same depth as interactive Recipe Discovery) and first searches with the Recipe name plus ingredient hints; if that produces no allowed source, it retries once with the Recipe name alone so over-specific hints do not unnecessarily leave a Recipe Idea unresolved. Blackcap selects the first allowed search result that can be acquired as a Recipe, while Meal Items remain Meal Items and never enter Recipe Discovery solely because Find & Add is enabled. A single Plan Meals response may therefore use provider URLs for some Recipes and Recipe Discovery-selected URLs for others. If both direct provider acquisition and both Recipe Discovery attempts fail, only that affected Recipe remains a Recipe Idea. A web-search-capable OpenAI or Gemini profile is still instructed to return real grounded Recipe URLs during its bounded Plan Meals request, because a provider URL can avoid a second search when it is allowed and capturable. Models/profiles without grounded web search—including Claude—can still use Find & Add when any supported server-side Recipe Discovery provider is configured; they return the Recipe intent and Blackcap resolves the URL afterward. Find & Add changes source acquisition, not Meal Item-versus-Recipe classification: OpenAI, Gemini, and Anthropic use the same conservative classification rules, and a provider-declared Meal Item is only overridden when Blackcap has strong deterministic evidence. Automatic source resolution handles at most one Recipe candidate per Meal Slot (preferring the primary); additional genuinely complex dishes remain Recipe Ideas instead of being silently imported as extra Recipes. During capture, generic parsed titles such as Recipe, Recipes, or Untitled Recipe yield to the specific planned/search-result title hint, while a genuinely specific source title remains authoritative. Blackcap never requires a model to invent a URL.

The existing browser Programmable Search Element remains available for interactive Recipe Discovery using only its Search Engine ID. Programmatic curated search can use Google Agent Search (ADC/IAM), Brave Search API, or Tavily Search API. Blackcap remains the final authority for include/exclude eligibility across all three.

Organization-scoped layout defaults continue to come from recipe.default_layout.

Query tuning

Recipe Discovery builds the provider query from:

  • search text
  • selected recipe type, unless “Any”
  • ingredient chips
  • the active Recipe Discovery Dietary Preferences & Restrictions (organization defaults unless temporarily changed for this run)
  • configured positive terms
  • configured excluded phrases
  • configured excluded title terms

The defaults bias searches toward specific recipe detail pages by adding terms such as recipe, ingredients, and instructions, and filtering common roundup/list/menu pages such as recipe roundup, recipe collection, dinner ideas, menus, and title terms like recipes, roundup, collection, ideas, and dinners.

Ingredient chips

The Ingredients on hand control is shared by Admin and Mobile.

It supports three ways to add chips:

  1. Kitchen Inventory picker — small icon button next to the label opens a compact popup of on-hand inventory matches. Selecting an item adds a chip and closes the popup.
  2. Ingredient typeahead — suggestions come from the existing org-scoped ingredient index.
  3. Freeform entry — if the ingredient is not in Kitchen Inventory or existing recipes, users can still keep it as a search chip.

Users can add chips with Enter, Tab, or comma. Chips can be removed with the chip’s remove button.

Kitchen Inventory suggestions are optional and require the user to have inventory view permission. The endpoint uses the inventory service layer; no direct SQL is added.

Admin workflow

The Admin UI adds Recipe Discovery to the Everyday navigation. The larger-screen layout uses a viewport-aware three-panel workspace:

  1. Search Criteria — search text, recipe type, ingredient chips, inventory picker, and manual URL fallback.
  2. Search Results — native Blackcap cards rendered from the configured search provider, with compact page controls.
  3. Preview/Edit — editable extracted recipe data, recipe type, layout, save/start/return actions, and progress feedback.

Panel behavior:

  • Preview/Edit starts collapsed.
  • Searching collapses Search Criteria and expands Search Results.
  • Selecting a result collapses Search Results and expands Preview/Edit.
  • Search Results and Preview/Edit have independent panel scrolling.
  • The page header can scroll away to maximize usable workspace.

Mobile workflow

The Mobile UI adds Recipe Discovery to the mobile Views menu. It uses a step-based flow:

  1. Search Criteria / Manual URL
  2. Search Results
  3. Preview / Edit / Save

Mobile behavior:

  • Layout is chosen in Preview/Edit, not in the Search step.
  • Recipe type and layout are shown side-by-side in Preview/Edit where space allows.
  • Save and Start Over sit together in the Preview/Edit action area.
  • Save success/failure messages appear below the action buttons.
  • Save is disabled after a successful save until the user changes preview content again.
  • Search result pagination supports page chips, previous/next, and horizontal swipe.
  • Page chips adapt to the available width and keep the current page visible.

Layout behavior

Recipe Discovery exposes friendly layout labels:

  • Full Width → single_page
  • Split Columns → two_page

The selector defaults to the current organization’s default recipe layout. Changing the selector affects only the recipe being saved from the current preview.

Endpoints

Method Path Purpose
GET /admin/recipe-discovery Admin Recipe Discovery page.
GET /mobile/recipe-discovery Mobile Recipe Discovery page.
POST /recipes/discovery/search Provider-backed recipe search.
GET /recipes/discovery/inventory-ingredients Optional org-scoped Kitchen Inventory ingredient suggestions.
POST /recipes/discovery/preview Canonical async preview/extraction endpoint for either a selected result or a manually pasted URL.
POST /recipes/discovery/preview-url Retired. Returns HTTP 410 Gone with /recipes/discovery/preview as the canonical successor; it no longer invokes a preview handler.
GET /recipes/discovery/preview-status/<job_id> Poll preview job status/result.
POST /recipes/discovery/save Save edited preview into the Recipe Library and queue cache build.

All endpoints require recipes.create. Kitchen Inventory suggestions additionally require inventory.view; if missing, the page remains usable without inventory suggestions. Optional Meal Planner context parameters are validated against the current organization before a meal-plan entry is created.

Cleanup metadata

Recipe Discovery participates in the same cleanup-rating pipeline as URL import and cache rebuild. Preview/save can generate an automatic 🛁 cleanup estimate from the extracted recipe body, and the queued cache build can refresh that estimate after editable content is materialized. See Recipe Cleanup Rating for thresholds, display behavior, Made It feedback, and cache rebuild behavior.

Data model

Recipe Discovery preview extraction still does not require a permanent preview-draft table. It uses the existing durable background_jobs table through background_job_service with job type recipe_discovery_preview; the extraction result is stored in the job result JSON. Saved recipes continue through the centralized recipe services, editable recipe content, ingredient/search indexing, and cache queue.

Migration 242 adds the platform-scoped recipe_source_site_stats table for Recipe website analytics. It stores one normalized domain, one example full URL with query string/fragment removed, total touches, AI Plan Meals recommendation touches, other URL-backed Add Recipe touches, and first/last involvement timestamps. Existing URL-backed Recipes are backfilled once as historical Other Add Recipe touches. Historical AI-provider recommendations cannot be reconstructed and begin accumulating after migration 242.

An AI-recommended source that is later actually imported can legitimately increment both buckets: the AI touch records what the provider recommended, while the Add Recipe touch records what Blackcap actually ingested. The Recipe Discovery Configuration page summarizes these counts and exports the complete platform table as blackcap_recipe_source_sites.csv; first/last timestamps in that export use the Default organization timezone and time-format preference. The export also includes Included in Recipe Discovery, a Yes/No DNS-level coverage check against enabled include rules. That check ignores rule paths, treats www. as equivalent to the apex host, and treats a leading *. include host as covering the apex plus its subdomains.

Migration 243 adds the platform-scoped recipe_search_rules table. It stores the Blackcap-owned curated-search policy separately from observed Recipe website statistics: include/exclude rule type, original and normalized URL pattern, enabled/draft state, source/notes, and created/updated timestamps. Observed sites never become searchable automatically; an administrator must explicitly create or activate an include rule.

A future hosted deployment could add a temporary preview draft table if previews need longer-lived collaboration, multi-user resume, or cleanup reporting.

Security and SSRF protections

Recipe Discovery URL preview validates URLs before fetch:

  • only http and https schemes are allowed
  • missing host names are rejected
  • DNS is resolved before fetch
  • localhost, private, link-local, multicast, reserved, and unspecified IP targets are blocked by default
  • extracted content is edited as text fields, not executed as page HTML
  • Browser Programmable Search uses only its Search Engine ID and Google Agent Search uses host Application Default Credentials/IAM. Brave and Tavily API keys are stored as encrypted platform secrets. Portable Recipe Search exports carry only non-secret provider/resource identifiers and rules; API keys are never exported.
  • Google Agent Search target-site synchronization uses Application Default Credentials/IAM rather than exporting or storing an OAuth bearer token in Blackcap configuration
  • Blackcap re-applies enabled include/exclude URL rules to every server-search result before it can become a Recipe acquisition candidate
  • only the non-secret Google Search Engine ID is exposed to JavaScript for the normal embedded Search Element

One deferred hardening item is redirect-chain revalidation. The current shared parser fetch may follow redirects after initial validation. For hosted/SaaS deployment, the shared fetch helper should validate the final redirect target before downloading content.

Cache behavior

Save creates or updates the recipe through the existing recipe service path, writes editable content, rebuilds ingredient/search indexes, and queues the standard recipe cache build asynchronously. The current Recipe Discovery review form is authoritative at save time: title, description, Recipe Type, ingredients, instructions, notes, image/source URL, Component yield, and Cookbook Categories are read from the live edited fields when Save is pressed rather than reusing the original provider preview. If the user changed the body, the recipe is marked manually edited and later cache rebuilds render from the saved database-backed editable content instead of recrawling the source and replacing those edits.

The save endpoint does not synchronously build PDF/PNG assets.

Files added

  • inky_admin/blueprints/recipe_discovery.py
  • inky_admin/services/recipe_discovery_service.py
  • inky_admin/services/recipe_search_provider_service.py
  • inky_admin/services/web_recipe_extraction_service.py
  • inky_admin/services/recipe_discovery_search_defaults.py
  • inky_admin/templates/recipe_discovery.html
  • inky_admin/templates/mobile_recipe_discovery.html
  • inky_admin/static/css/recipe_discovery.css
  • inky_admin/static/js/recipe_discovery.js
  • importing-and-discovery.md
  • database/migrations/043_recipe_discovery_embedded_cse.sql
  • database/migrations/044_recipe_discovery_search_tuning.sql

Files updated

  • inky_admin/blueprints/__init__.py
  • inky_admin/services/config_setting_map.py
  • inky_admin/services/config_ui_service.py
  • inky_admin/services/security_service.py
  • inky_admin/services/background_job_service.py
  • inky_admin/templates/base_admin.html
  • inky_admin/templates/config_index.html
  • inky_admin/templates/config_scoped_settings.html
  • inky_admin/templates/includes/mobile_header.html
  • inky_menu_config.ini.example

Restart

sudo systemctl restart inky_admin.service

Testing checklist

  • Search text returns provider results when provider is configured.
  • Recipe type is included in the constructed provider query when not “Any”.
  • Ingredient chips are included in the constructed provider query.
  • Inventory picker adds chips and closes.
  • Existing ingredient typeahead adds chips.
  • Freeform ingredients can be added with Enter, Tab, or comma.
  • Provider disabled/not configured shows a clear message and keeps manual URL available.
  • No results state is clear.

Search results

  • Native Blackcap result cards render from the configured Recipe Discovery provider.
  • Search Results panel scrolls independently.
  • Result cards show title, source/domain, snippet, thumbnail when available, Preview, and Open Source.
  • Preview queues extraction for the selected recipe URL.
  • Page controls work on Admin.
  • Page controls and swipe work on Mobile.
  • Google source opens for verification/fallback and can be closed after verification.

Layout

  • Layout defaults from organization recipe configuration.
  • Layout is selected in Preview/Edit.
  • Saved recipe uses selected layout.

Preview / extraction

  • Preview job is created and appears as queued/running/completed.
  • Metadata/header info, ingredients, instructions, image URL, and source URL populate when extraction succeeds.
  • Partial extraction remains editable.
  • Failed extraction produces editable fallback fields.
  • Invalid/private URLs are blocked.

Save

  • Save creates recipe in current organization.
  • Edited title/content are saved.
  • Recipe type and layout are saved.
  • Editable ingredients and instructions are saved.
  • Ingredient/search indexes update.
  • Cache build is queued asynchronously.
  • Recipe appears in Recipe Library after save.
  • Saved recipe is not marked edited unless the discovered content was actually changed before save.

Meal Planner context

  • Admin Meal Planner launches Recipe Discovery with date/slot context.
  • Mobile Meal Planner launches Recipe Discovery with date/slot context.
  • Save creates the recipe and queues cache normally.
  • Save also creates the Meal Planner entry when context is present.
  • Return context goes back to Admin or Mobile Meal Planner as appropriate.
  • Standalone Recipe Discovery still saves without creating a Meal Planner entry.

Mobile

  • Search → Results → Preview/Edit → Save flow works.
  • Browser back returns preview to results and results to search criteria where practical.
  • Start Over returns to a blank search screen.
  • Save success/failure message appears below Preview/Edit buttons.
  • Save stays disabled after a successful save until content changes.
  • Touch targets are usable.

Admin

  • Recipe Discovery appears in Admin navigation.
  • Three-panel workflow works on desktop.
  • Search refinement works.
  • Preview/edit/save works without full page reload.
  • Header panels scroll away and inner panels scroll independently.

Security / scope

  • Users without recipes.create are blocked.
  • Recipes save only into the current organization.
  • Ingredient suggestions come from org-scoped index results.
  • Kitchen Inventory suggestions respect inventory permissions and organization scope.
  • No direct SQL calls are introduced for Recipe Discovery.
  • Recipe Search API keys are secret/encrypted at rest, are not exposed to the browser, and are not included in Recipe source-site/Search Config exports or request error messages.
  • Recipe Search include/exclude rules are platform-scoped, with exclusions taking precedence and disabled wizard drafts ignored by production search.

Regression

  • Existing Add Recipe still works.
  • Chrome Extension recipe push still works.
  • Recipe cache queue still works.
  • Recipe Library still works.
  • Shopping lists and Shop a List are unaffected.

Slow-site capture and recipe metadata

Platform slow recipe websites

System Admins can manage the platform-scoped Slow Recipe Websites configuration from Platform Configuration. The slow-site threshold defaults to 50 seconds and is stored as the platform setting slow_recipe_sites.threshold_seconds.

When a recipe cache build for a source URL exceeds the threshold, Blackcap records the normalized source domain in slow_recipe_source_sites. The list is persistent and survives normal performance-metric purges. Auto detection updates sample count, average duration, maximum duration, last duration, detection timestamps, and the last full recipe URL that triggered the slow-site detection. Manual entries can be added from a domain or full URL; a full URL is also stored as the retry test URL. Removal is soft-delete style by setting the status to removed; a future slow cache build can reactivate the domain.

Domain normalization lowercases the host, strips the port and a leading www., and ignores path/query/fragment for the domain key. The full recipe URL is stored separately for retry testing when available. Other subdomains are preserved so recipes.example.com remains distinct from example.com.

Slow-site retry testing

The Slow Recipe Websites configuration page includes a Retry action when Blackcap has a stored full recipe URL for the domain. Retry now starts a tracked background job and returns immediately so the Platform Configuration page does not sit waiting on a recipe import/cache build. The slow-site row is marked queued / running while the job is active and is updated when the retry finishes.

The background retry runs a test cache build against the stored full URL. If the current organization already has an active recipe for the same full URL and the recipe has not been manually edited, Blackcap uses that recipe for the test. Otherwise, it creates a temporary web-backed recipe for the stored URL, runs the cache build, and archives the temporary recipe after the test completes.

If the retry cache build succeeds and completes below the configured slow-site threshold, Blackcap marks the slow-site row removed, which re-enables URL-only Quick Add for that domain. If the build fails or still meets/exceeds the threshold, the domain stays active and remains blocked for URL-only Quick Add. Retry outcomes are stored on the slow-site row with the last retry time, duration, status, message, recipe id, and whether an existing recipe was used. The retry background job is visible in Background Operations under Recipe Cache work. No separate purge is required for retry metadata; it is part of the persistent slow-site row. Temporary retry recipes are archived immediately after the retry and then follow the normal recipe/archive retention behavior.

Slow-site capture behavior

URL-only quick add is blocked for active slow-site domains in the Chrome Extension, Admin URL add, and Mobile URL add flows. The user is guided to use full page capture so Blackcap can use recipe details already present in the browser. Full active-page capture is not blocked.

Recipe Discovery is not blocked. It receives a warning that the site is expected to take longer, then continues normally.

Meal Planner people served

Meal Planner settings now include Default people served, organization-scoped and defaulting to 3. Meal slots can override people served for a specific day/slot, and the toolbar bulk editor can apply a people count across a date range and selected meal slots.

When a recipe is added to a meal slot, Blackcap calculates the multiplier from:

people_to_serve / recipe_servings

The calculated multiplier is stored on the meal plan entry with source calculated_from_people so display rendering, Let’s Cook, and shopping-list generation use the same value. Manual multiplier edits switch the entry back to source manual; bulk people updates recalculate calculated entries by default and only overwrite manual entries when explicitly requested.

Servings parsing supports numeric values, text like Serves 4, and ranges. Ranges use the midpoint as a practical first pass. Non-serving yields such as 1 loaf or 1 pie are treated as unknown servings and fall back to 1x.

Whole-batch scaling

Whole-batch recipes use integer multipliers:

max(1, ceil(people_to_serve / recipe_servings))

The first-pass heuristic detects titles/yields containing words such as cake, pie, bread, loaf, rolls, muffins, cookies, bars, tart, cheesecake, brownie, or batch. Recipe metadata can later carry an override using the label Whole-batch scaling.

Recipe difficulty

Difficulty is derived from cleanup score, active time, and ingredient count when at least two inputs are available. The labels are:

  • 🟢 Easy
  • 🟡 Moderate
  • 🟠 Involved
  • 🔴 Ambitious

Scoring components are 0–3 points each:

  • Cleanup: low score to high score
  • Active time: <=15, 16–30, 31–60, >60 minutes
  • Ingredient count: <=6, 7–12, 13–20, >20

Totals map to Easy 0–2, Moderate 3–4, Involved 5–6, and Ambitious 7–9.

Time and effort search filters

Recipe search surfaces a compact Time & Effort filter instead of adding separate cluttered facets. Current options include quick meals, easy recipes, moderate-or-easier, involved/ambitious, under 30 minutes, and under 60 minutes. Difficulty pills appear alongside existing recipe metadata pills where space allows.

Preview hover scrolling

The editable Ingredients and Steps preview fields accept mouse-wheel and trackpad scrolling as soon as the pointer is over them; no click or focus transfer is required. Blackcap uses the browser's variable wheel delta rather than a fixed wheel increment. When the hovered field can scroll in the requested direction, that field consumes the movement. At its top or bottom boundary, continued outward scrolling is handed back to the surrounding preview/page instead of trapping the user in the nested field. Normal text-editing focus and caret behavior are unchanged.

On this page