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

๐Ÿค– AI Seeds and Usage

Audience: User, Org Admin, System Admin, Developer Related: Overview ยท Providers And Connections ยท Ai Image Generation ยท Data Retention

AI Seeds are Blackcapโ€™s product currency for AI use. They are distinct from API Tokens. Usage flows reserve Seeds before provider work, commit actual usage when successful, and release or reconcile reservations when work fails or is abandoned.

The system supports organization AI Seeds, global personal AI Seeds, monthly allotments, provider-reported tokens, use-case pricing, usage reporting, and generated-asset retention. Legacy code-facing names may remain internally until migrated, but user-facing documentation and UI use AI Seeds.

What AI Seeds are

AI Seeds are Blackcap's credits for AI features. Each AI action shows its AI Seed cost before confirmation. Blackcap shows this explanation anywhere the term appears through an accessible help tooltip.

AI Seeds are not API Tokens. API Tokens continue to authenticate software integrations. Provider-reported tokens are usage measurements supplied by OpenAI or Gemini and do not determine the Blackcap AI Seed charge.

Organization and personal balances

  • Organization AI Seeds are shared by authorized users in the active organization.
  • My AI Seeds belong globally to the signed-in user and remain available across every organization that user may access.
  • A finite monthly organization allotment expires at the next subscription-cycle boundary and does not roll over.
  • Additional organization or personal grants do not expire unless a future grant explicitly includes an expiration.
  • The Default organization is Unlimited. A System Adminโ€™s personal AI Seed source is also unlimited, but organization funding still uses the selected organizationโ€™s actual finite or unlimited balance. Unlimited use still records the quality profile's configured AI Seed usage and provider usage; it simply does not debit a finite balance. This lets AI Usage compare product-credit consumption with provider cost even for System Admin/Unlimited activity.

The user selects the spending source before every metered generation. Blackcap never silently switches to the other source when the selected balance is insufficient.

Generate an image

AI image generation is available for manually entered recipes and as an optional stage of Create Recipe with AI and Plan Meals with AI-created originals. Manual image generation remains a separately confirmed workflow; automatic creation uses its selected Create Image Quality Profile and the user-approved generation budget.

  1. Create or edit a manual recipe and save enough information to identify the dish: a title plus a description or ingredients.
  2. Select Generate Image with AI. On a new manual recipe, use Save & Generate Image.
  3. Choose a configured quality profile. Blackcap initially seeds Medium at 1 AI Seed and High at 10 AI Seeds, but a System Admin may change those prices.
  4. Choose Organization AI Seeds or My AI Seeds.
  5. Optionally add image notes such as composition, serving style, or camera angle.
  6. Submit the job. The dialog shows honest stages rather than invented percentages.
  7. Return later if needed. Queued and completed candidates are durable across navigation and application restarts.
  8. Review the generated image beside the existing recipe image, when present.
  9. Select Use this image, keep the current image, reject the candidate, or generate another image.

Generating another image creates another provider request and consumes the configured AI Seed price. Accepting an already generated image does not charge again.

Plan Meals maximum reservation and actual spend

When Create Original Recipes with AI is enabled in Plan Meals, the user chooses Max AI recipes per Meal Slot (1โ€“4, default 1) and may enable one image per new original Recipe. The pricing table shows Min for the planning-only charge and Max for the worst-case planning plus allowable recipe/image generation. The user authorizes Max; Blackcap reserves that amount once in the selected Organization or Personal balance. Child recipe and image jobs take allocations from this original hold, and the remaining unused Seeds are released when the run concludes. Separate AI Usage entries record the planning, recipe and image operations, but they do not mean the account was reserved multiple times. The Plan Meals completion dialog shows the number of AI-created Recipes and saved AI-generated Images, with image failures when applicable.

Privacy and safety

Blackcap sends only the recipe details needed to create the image: title, description, relevant ingredients, cuisine or preparation context, and optional image notes. It does not send user contact details, organization secrets, API Tokens, provider credentials, or unrelated recipe-library data.

Returned files are checked for supported image type, file signature, decoded dimensions, maximum byte size, and Pillow readability before storage. Provider safety failures are normalized into a user-safe message; raw provider responses and credentials are not displayed.

Candidate retention

An unused candidate remains available for the platform-configured retention period, initially seven days. Accepted images follow normal recipe artifact retention. The use case's AI Data Retention period also governs terminal AI jobs, AI Usage rows, completed job-linked Seed reservations/ledger entries, and retained diagnostic evidence. Current Seed balances are not reconstructed from this history: live Seed Accounts and active/unexpired balance buckets remain protected. Expired buckets and accounting rows that cannot be attributed to one use case use the longest configured AI Data Retention period as a conservative fallback.

Where balances are shown and managed

Organization AI Seeds appear on the Organizations results list, Organization Details, and Current Organization. A bounded monthly allotment uses the purple blackcap-fruit meter and exact text; additional balances and reservations are also shown. The Organizations page can filter by no allotment, no active period, exhausted, less than 10% or 25% remaining, additional balance, reservations, and Unlimited. The Default organization is labeled Unlimited.

Global personal AI Seeds appear on the Users list and the signed-in userโ€™s Account page. Personal balances do not use a percentage meter because they are not a bounded monthly entitlement. System Admins may adjust a userโ€™s global personal balance from Users. Org Admins may view an active organization memberโ€™s available and reserved global balance, but cannot edit it or see usage from organizations they do not administer.

The Account page separates My Personal AI Seeds from Organization AI Seeds and shows recent personal-funded usage. It is read-only and does not include purchasing controls.

AI Usage reporting

Authorized administrators use Administration โ†’ AI Usage. Org Admins may report across one or all organizations they administer. System Admins may report across all organizations or one selected organization. The report uses server-side paging, sticky headers, an anchored Actions column, and the selected authorization scope.

Filters and sorting

The report can filter by date range, organization, user, provider, connection, use case, quality profile, result, and AI Seed source. System Admins can also enter minimum/maximum Estimated Provider Cost values to isolate expensive requests. Latency and estimated cost can be sorted lowest-to-highest or highest-to-lowest.

The selectors are faceted rather than independent. Selecting an organization narrows the user list to users associated with that organization. Regression-test and diagnostic-clone identities are omitted from the normal user selector. Provider, connection, and profile narrow one another in every direction, so an incompatible selection is not left behind when another facet changes.

What each usage row records

Each completed or meaningfully attempted provider operation records the use case, quality-profile key/name, provider connection, provider/model actually used, outcome, latency, configured AI Seed usage, and normalized provider usage when available. The Provider cell stays compact; the exact model is available from its tooltip/details. Provider request identifiers are visually truncated but can be copied from the row action for support/correlation. Whether a vendor's own dashboard can search that identifier depends on the provider.

Provider token details keep the label and value together. Input, cached input, output, reasoning/thinking, and image/media token counts appear only when that provider actually reports them; Blackcap does not display a meaningless Image: โ€” row merely because the use case generated an image.

Configured AI Seed usage is tracked even when the funding account is Unlimited. For example, if a profile is configured for 10 AI Seeds, AI Usage records 10 Seeds used even though an Unlimited account has no finite balance deduction. Failed requests follow the existing reservation/settlement rules, while provider usage and estimated cost can still be recorded when the provider already performed billable work before Blackcap encountered a downstream failure.

Estimated provider cost

Blackcap stores an Estimated Provider Cost for AI use cases when enough actual request data is available. The estimate uses the provider/model actually used, normalized provider token/media usage and request settings, plus the versioned provider-pricing snapshot in effect at the time. Historical usage therefore does not silently change when public provider pricing changes later. It is a planning/reconciliation estimate, not an invoice.

The Quality Profile editor also shows a forward-looking estimate before use: image profiles use size/quality pricing, Support Chat shows per-turn/conversation envelopes, and Social Recipe Extraction shows realistic per-import estimates (including transcription/media assumptions where applicable). AI Usage is preferable for completed work because it can use the actual request's recorded usage.

System Admins see Total estimated provider cost plus use-case summaries for ๐Ÿ–ผ๏ธ Recipe Image Generation, ๐ŸŽฌ Social Recipe Extraction, ๐Ÿ“ท Recipe Photo Extraction, ๐Ÿงบ Inventory Photo Analysis, ๐Ÿฝ๏ธ Plan Meal, ๐Ÿ—“๏ธ Plan Meals, and ๐Ÿ›Ÿ Support Chat. Recipe Image Generation, Social Recipe Extraction, Recipe Photo Extraction, Inventory Photo Analysis, Plan Meal, and Plan Meals use the same request/success/failure, AI Seed, latency, and estimated-provider-cost summary pattern. Support Chat remains intentionally different because it additionally reports session/effectiveness metrics such as sessions, AI requests, successes/failures, resolved without support, escalations, provider failures, abandoned sessions, average turns, average latency, AI Seeds used, and estimated provider cost.

For System Admins, every use-case summary includes ๐Ÿ“Š Profile Summary. The popup compares all quality profiles for that use case while honoring the current AI Usage organization/date/user/provider/connection/outcome/funding-source/cost filters and intentionally ignoring the current Quality Profile filter. Profiles are shown in the same configured sort_order used by the Use Case Profile configuration; historical profiles that no longer exist are appended afterward. Fixed-price use cases show the profile's currently configured AI Seed price. Plan Meals is dynamic: its base price is only the start of the slot-block curve, while actual charged Seeds are retained per invocation for workload analysis. Historical request count, average latency, and average estimated provider cost remain available. The button and endpoint are System Admin-only, and average estimated provider cost is never returned to an Org Admin.

The System Admin header also includes โš–๏ธ AI Seed Cost Alignment. Fixed-price use cases are compared against their configured Seed charge while Plan Meals is analyzed separately using its actual Seeds charged, selected Meal Slot workload buckets, Quality Profile, provider/model, and Find & Add on/off state. For fixed-price rows, effective provider cost per successful priced request includes known provider spend from failed attempts whose Seed reservation was released. For Plan Meals, cost per Seed is computed from comparable slot-count groups so a 35-slot plan is not evaluated as if it had the profile's one-request base price. The lowest effective cost per AI Seed among groups with enough observations becomes the conservative reference; materially higher groups are marked Watch or Review. Plan Meals also pairs comparable Find & Add enabled/disabled groups where possible and shows the configured surcharge beside an observed equivalent surcharge derived from the matched cost difference. This is a relative pricing-consistency check, not an assumed dollar value or margin for one AI Seed. The analysis honors organization/user/provider/source/date/outcome scope but ignores Use Case, Profile, sorting, and estimated-cost range filters so it can compare profiles across use cases without a cost-range filter biasing the benchmark.

Row actions and retained artifacts

Support Chat usage can show ๐Ÿ›Ÿ View support chat while the retained transcript is available. Generated-image usage can show ๐Ÿ–ผ๏ธ View generated image while the generated candidate file is retained. ๐Ÿ“ท Recipe Photo Extraction, ๐ŸŽฌ Social Recipe Extraction, ๐Ÿงบ Inventory Photo Analysis, ๐Ÿฝ๏ธ Plan Meal, and ๐Ÿ—“๏ธ Plan Meals rows use the ๐Ÿ”ฌ Analyze action to open ๐Ÿ”Ž What Happened to anyone authorized to view AI Usage for that organization. The viewer is deliberately independent of whether the user later accepted/imported the provider result.

For Recipe Photo Extraction, What Happened places the provider-prepared photo input plus Blackcap's built-in OCR result on the left and the parsed provider recipe response on the right. Inventory Photo Analysis has two intentionally separate capture modes: single-Product photo review and Kitchen Inventory overview-photo review. Both use temporary Inventory staging rather than durable Product media. If AI is explicitly invoked, What Happened retains the bounded image Blackcap actually submitted to the provider plus the known logical-item/Product/Package context on the left and records the capture mode in AI Usage metadata. The right side shows Blackcap's validated findings, confidence/reason, the current review decision, and the exact structured provider response in expandable raw details. In Product mode, the finding stays constrained to its staged logical item. In overview mode, one image can produce several findings, each can match an existing logical item or propose a new one, and each must be independently reviewed with an explicit package choice and fullness before applying. The provider result is suggestion-only; only an explicit reviewed apply routes through normal Inventory Product/package/quantity services. The AI Usage evidence copy follows the normal AI Usage retention/purge lifecycle even though the ordinary staged Inventory photo is deleted after review. For Social Recipe Extraction, the left side shows the retained source URL, caption/description, transcript and supplemental written evidence used for the AI request, with a best-effort iframe viewer. Blackcap does not retain the social video for AI Usage; if the provider blocks framing, the original social URL remains available as the fallback. The right side shows the provider's structured recipe result before Blackcap's deterministic/AI merge and measurement reconciliation.

Adapt Recipe ๐Ÿช„ also reports a dedicated usage summary and an organization-authorized ๐Ÿ”ฌ What Happened view: source recipe/measurements, dietary settings and requested change, provider-generated changes and new ingredients/steps, and estimated timing/nutrition. The evidence is retained with AI Usage (not with permanent recipe history).

What Happened structured evidence is stored on the durable AI Usage event, and retained Recipe Photo evidence files are tied to that event's organization/job. It has no separate seven-day expiry: it remains only as long as the corresponding AI Usage data remains and is removed by the same owning-organization purge lifecycle. Diagnostic-clone AI Usage copies deliberately omit source-organization What Happened evidence and artifact paths. Generic Database Admin hides the private evidence JSON; the organization-authorized What Happened action is the supported viewer.

Unused/rejected generated-image candidates still follow the configured AI asset-retention period (initially seven days); accepted images move into the recipe image/cache workflow and are not removed by the unused-candidate purge. Terminal AI operational history itself follows the owning use case's AI Data Retention period: due jobs, usage, completed reservations/ledger history, and retained evidence are removed together. If an artifact/transcript is removed earlier by its own cleanup while the AI Usage row is still retained, the corresponding action reports the history as unavailable instead of turning the missing artifact into an application error. Old orphan reservations and accounting rows that no longer have a usable job/use-case owner fall back to the longest configured AI Data Retention period; current Seed balances and live accounts/buckets remain protected. Authorized administrators can also use Administration โ†’ Data Cleanup โ†’ AI Operational History to remove a terminal job before its retention date. That manual path uses the same dependency rules and can expose a separate safe-orphan accounting aggregate, but it never treats age alone as permission to delete a live Seed Account, current balance bucket, or active/recovery AI job.

System Admin rows also provide ๐Ÿ“‹ Copy Provider Request ID when Blackcap received a provider request identifier. Estimated provider cost in row details, What Happened metadata, summaries, profile comparisons, and reconciliation remains System Admin-only.

Provider-owned correlation identifiers, detailed provider token counts, and estimated provider cost are System Admin-only. The UI's Provider ID prefers provider_request_id and falls back to a durable response/message ID recovered from the AI Job when the provider did not retain an HTTP request ID on the final response object. The copy action uses the same displayed identifier. The Provider Billing Reconciliation CSV is also System Admin-only and accepts the same report scope and cost-range filtering. Billing-context metadata is retained in the underlying usage record/export for reconciliation but is intentionally not repeated as a visible AI Usage table column on a single Blackcap instance.

Reconciliation captures every diagnostic Blackcap can know at request time or receive from the provider: billing instance name/ID/environment, Blackcap client request ID, provider request/response IDs, retry lineage, reservation ID, AI job entity type/ID, Support Chat session/message IDs, prompt/corpus versions, all AI Seed accounting fields (including refunds), normalized input/cached/output/reasoning/image token counts, and the raw safe provider-usage payload. Recipe Photo, Social Recipe, Support Chat, and generated-image writers persist their request context into the usage event; reporting can also recover billing/correlation/entity values and generated-image token diagnostics from retained AI job/candidate snapshots for older rows. Historical rows can remain blank when they predate that capture and their correlated job/artifact has already been purgedโ€”Blackcap does not fabricate values retroactively.

Some blanks are intentionally not applicable: retry_of_job_id is empty when the request was not a retry; recipe_id is empty for Support Chat and Social Recipe Extraction because those provider requests are not scoped to an existing recipe, while Recipe Photo uses its staged capture ID in the legacy recipe-compatible column until a real recipe exists; failure_category is empty on successful requests; Support Chat is text-only so image tokens do not apply; and image/media token counts can remain empty when a provider does not report a separate image-token measure. The exported entity_type/entity_id provide the correct non-recipe correlation (for example support_chat or social_recipe_import). Gemini modality details are normalized into the image-token field when its usage response provides them. Cached-input and reasoning token counts are also included when available.

Authenticated administration clients and the API Tester can use GET /api/admin/ai/usage for the same authorized report as JSON. API Tester also exposes the System Admin-only quality-profile summary, organization-authorized What Happened JSON for Recipe Photo/Social Recipe/Inventory Photo Analysis/Plan Meal, the Support Chat transcript action, and documents the binary generated-image/Recipe Photo evidence routes. See AI Administration, AI Seeds, and Usage Reporting for the permission matrix, API Tester entries, Database Admin resources, and regression coverage.


Plan Meals AI use case

Restart-safe reservation and provider accounting

AI Seed reservations follow the durable AI job rather than the lifetime of a Python thread. A request reserves once before provider submission, but reservation is not a charge. Blackcap consumes AI Seeds only after the use case has received and accepted a valid provider response. Provider submission, a provider operation ID, or a durable response checkpoint by itself does not settle the reservation. If the request fails, times out, is interrupted, becomes outcome_unknown, returns an invalid response, or fails feature-level validation, the reservation is automatically released back to the same Organization or Personal AI Seed account. Provider interaction/usage evidence is still retained for provider-cost reconciliation even when the user is not charged Seeds. Once feature-level validation accepts the response, the reservation is settled idempotently; a later Blackcap-only persistence or post-processing failure does not refund that already-valid AI response.

AI Usage continues to record the job/provider/model/provider IDs, normalized token/usage details, Seed reservation/settlement data, and use-case diagnostics. ai_job_provider_interactions supplies the lower-level provider-operation trail needed to distinguish never-submitted, pending/retrievable, response-checkpointed, failed, and outcome_unknown work during reconciliation.

Plan Meals is a separate first-class structured-data AI use case from Plan Meal. It decides what food to add across explicitly selected Meal Planner dates/Meal Slots (maximum seven distinct dates) while treating all existing entries as immutable. Its configured Quality Profile determines provider/model, reasoning/output controls, grounded-search capability, and a dynamic AI Seed curve. The curve has five first-class fields: Base AI Seeds, Meal Slots Included, Additional Meal Slots per Block, Additional AI Seeds per Block, and Find & Add AI Seed Surcharge. Pricing uses selected Meal Slots sent to the provider, not returned additions or calendar days, and the server produces a trusted quote before the user approves spending. Submit recalculates the quote and refuses a stale approved amount. The Find & Add surcharge is applied only when that option is enabled and is configurable per Quality Profile.

One Plan Meals provider request consumes only the selected Plan Meals profileโ€™s configured AI Seeds. The optional Planning Request is retained verbatim (after trimming, maximum 1,000 characters) in the trusted snapshot and can express cuisine, Meal Slot/date, ingredient, theme, effort, or occasion guidance. It changes the trusted quote fingerprint/approval context but does not change the Plan Meals Seed pricing curve. Named Meal Slot/date guidance applies only to matching selected slots and never removes other selected slots from the planning scope; unmentioned selected slots are still planned normally. Weekday names are sent as authoritative date mappings, and an otherwise-empty selected slot must receive a meaningful addition or the response is rejected as invalid. Dietary Preferences & Restrictions and immutable existing content remain higher-priority constraints. Optional Recipe Library and recent Meal Plans taste context is compact: sampled Recipes include Meal Planner frequency and a Made It rating only when one exists, while Meal Items and unresolved Recipe Ideas are summarized by frequency/recency. Missing Recipe ratings are explicitly neutral/unknown rather than negative evidence. A separate Try to minimize duplicated meals over the past month option adds one compact 30-day Meal Plan history and asks the provider to minimize exact or substantially similar recent meals as soft variety guidance, not a hard exclusion. When both history-aware options are enabled, that Meal Plan history context is represented once and shared across both purposes. Optional Kitchen Inventory is compact context. In On Hand Only mode it remains availability-only. In Full Inventory Tracking it additionally includes aggregate package quantity estimates when known, with incomplete/unknown package quantities marked as such; the provider is instructed not to favor a dish on the basis of on-hand stock when its typical required amount would materially exceed the estimate. The exact planning-time Dietary Preferences are explicit provider constraints. Context disabled by the user is omitted.

That single provider response also carries meal-balance coverage plus completion candidates for Lunch/Dinner. Blackcap deterministically checks the final main/protein, vegetable, and (when appropriate) starch/grain coverage before writing the Meal Planner. Missing simple roles are filled from candidates already returned in the paid response, with conservative local Meal Item fallbacks as a final zero-AI safety net. This completeness repair does not submit a second Plan Meals provider request and does not reserve additional AI Seeds.

When Find & Add Complete Recipes is enabled, grounded web search is useful but is not an absolute profile requirement when server-side Recipe Discovery is configured. A web-search-capable OpenAI/Gemini profile is encouraged to return real grounded Recipe URLs during the bounded Plan Meals request. Blackcap revalidates those URLs against active include/exclude rules and acquisition/capture behavior before using them. A Claude profile or another OpenAI/Gemini model without grounded web search can still run Find & Add when Google Agent Search, Brave Search API, or Tavily Search API is configured; it supplies the Recipe intent and Blackcap resolves the source afterward rather than asking the model to invent a URL. If neither the provider/model nor server-side Recipe Discovery can resolve Recipe sources, Find & Add is blocked before Seed reservation.

Source resolution is per Recipe. Provider URLs and bounded alternatives are preferred when allowed and capturable. Otherwise Blackcap uses Recipe Discovery with the configured result depth, first with Recipe name + ingredient hints and then one broader name-only retry. Non-slow allowed sites are preferred, but an otherwise valid slow site can be used as a last resort rather than unnecessarily leaving a Recipe Idea. Meal Items bypass source lookup. The selected source is then acquired through the normal Recipe write/cache path; social/capture work that genuinely requires another AI operation remains a Recipe Suggestion and requires its own later Profile/Seed confirmation and AI Usage event. Plan Meals AI Usage retains source-selection metrics such as provider verification/rejection, search requests, broad retries, slow-source fallback, resolved/unresolved counts, and the Plan Meals workload/pricing fields needed for Seed Cost Alignment.Authorized Plan Meals What Happened evidence records the planning-time selected dates/slots/current entries, the exact Dietary Preferences/custom note, context flags and compact context used, accepted provider additions, Recipe-source outcomes, created Recipes/Meal Items/Suggestions, and per-slot conflicts/skips. It also exposes the slot-block pricing decision: selected Meal Slot/day counts, base/included/block settings, calculated block count, quoted/final Seed cost, Find & Add setting/surcharge, and Recipe Shopping-readiness/source-resolution counts. The System Admin Provider Billing Reconciliation CSV exports those same structured pricing/workload fields alongside provider tokens, reasoning/cached-input usage, provider IDs, latency, and estimated provider cost. For the history-aware options it also exports the preference-context counts, recent-history Meal Slot/entry counts, and the duplicate-minimization flag so their input-cost impact can be compared over time. It preserves the pricing-snapshot version recorded with the original usage event, identifies the current reconciliation snapshot separately, and recomputes token-cost components using that current snapshot. When the provider exposes grounding evidence, it also records the web-search query count, captured grounding-source count, bounded query list, and search-tool list-price exposure before free allowances. That distinction matters because provider grounding/search can be priced separately from tokens and account-wide free allowances cannot be inferred from one request. The viewer treats a retained non-empty accepted plan as successful evidence even for older Plan Meals events created before the explicit acceptance flag was added. This diagnostic snapshot follows AI Usage retention. Active Meal Planner content, including unresolved Suggestions, is separate durable product data and survives AI Usage purge.

Plan Meal AI use case

Plan Meal is a first-class structured-data AI use case. System Admin AI Configuration supplies its provider/model, Quality Profiles, AI Seed pricing, and profile limits just like the other configured AI uses.

For Plan Meal, Maximum Meal Plan output tokens is bounded by the selected provider/model rather than a Blackcap-wide 20,000-token ceiling. Current GPT-5-family profiles can be configured up to 128,000 and supported Gemini text profiles up to 65,536. The configured profile can intentionally use a smaller value for cost control; reasoning effort remains a separate qualitative control where the provider supports it. Because some reasoning providers count internal reasoning against the same generation allowance, a too-small output ceiling can spend reasoning cost and still end before the structured Meal Plan is complete.

AI Seeds are consumed only when Blackcap actually requests a new plan:

Action Provider request AI Seeds
Plan Meal Yes Configured profile cost
Replan Meal Yes Configured profile cost
View Meal Plan No 0
Cook Meal using a current saved AI plan No 0
Next/Previous/checkoff/timers No 0
Refresh/resume No 0

A Plan Meal request records the normal provider/model/profile, AI Seed reservation/settlement, normalized token/usage values, latency, estimated provider cost where available, success/failure information, organization/user correlation, and provider request/response identifiers supplied by the provider.

What Happened

Authorized AI Usage rows for Plan Meal provide What Happened. The retained diagnostic view uses the historical planning snapshot rather than rebuilding it from current Recipes.

The input side includes the Recipes, selected Components, Recipe/Component multipliers, Meal Items/notes, Serve At, oven count, and temperature-coordination choice that were actually sent as trusted planning context. The output side shows the accepted Expected Total Meal Time, high-level summary, and validated interleaved structured timeline including timing/timer and temperature provenance when applicable.

Provider credentials, hidden system instructions, unrelated organization data, and other secrets are never included.

Plan Meal diagnostic evidence follows the owning AI Usage record's retention. The user-facing saved Meal Plan is a separate product record and can outlive that diagnostic evidence; purging AI Usage evidence must not delete a Meal Plan the user still expects to cook.

Quality Profile consecutive-failure safeguard

Every terminal AI Usage event participates in the Quality Profile failure streak. A successful event resets the streak for an enabled profile. When the same Quality Profile records two failures in a row, Blackcap automatically disables it and records the exact Disable Reason Failed twice. If that profile was the use-case default, Blackcap promotes the next enabled profile by configured profile order so an invalid default is not silently left selected.

The Configuration โ†’ Platform โ†’ AI Quality Profile table places Disable Reason immediately to the right of Status. Its ๐Ÿ“Š action opens AI Usage already filtered to that use case/profile so the System Admin can review the user-friendly failure messages and provider diagnostics. Explicitly enabling or disabling the profile clears the automatic disable reason and resets the streak, allowing a corrected configuration to be tested deliberately.

AI Usage stores both a normalized failure_category for machine/report grouping and a user-friendly failure_reason for diagnosis. The UI displays the friendly reason; legacy rows without one fall back to a humanized category.

For Anthropic Claude, provider_output_tokens is the inclusive billed output total. provider_reasoning_tokens is an informational subset reported by Anthropic and is not added to the output count a second time when Blackcap estimates cost.

Create SQL Query

Database Admin's โœจ Create Query / Modify Query is an implemented structured-text AI use case for System Admins. It is durable and asynchronous, uses its own Economy/Standard/Enhanced Quality Profiles, and requires an explicit Organization or Personal AI Seed source plus spend confirmation. With an empty SQL editor, Blackcap sends the user's natural-language request and the exact protected-column-safe Markdown schema document produced by Export Schema. Once SQL exists in the editor, the action changes to โœจ Modify Query: Blackcap sends the current SQL plus the requested change and links the turn to the prior SQL AI job when available. OpenAI (previous_response_id) and Gemini (previous_interaction_id) can continue their stored provider conversation when the same provider connection/model is selected and the schema fingerprint is unchanged, avoiding retransmission of the full schema on that turn; otherwise Blackcap safely sends the complete original/current/new request context plus the schema again. Gemini documents server-side continuation as a way to improve context caching and reduce token cost. OpenAI continuation reduces the transmitted request size but prior chain input remains billable, so Blackcap also uses a stable schema-based prompt-cache key and keeps the full schema at a stable prompt prefix to improve cached-input reuse on compatible models. Each turn is tracked with a durable chain ID, iteration number, previous job, original request, current SQL, new request, and whether provider-side context was reused. The SQL Console keeps a convenient iteration history for the current browser session and ๐Ÿงน Clear resets the editor plus that drafting history; AI Usage remains the durable audit record. The accepted provider response must contain one valid read-only SELECT; Blackcap never executes it automatically and only places it into the SQL Console editor for review. AI Seeds settle only after the response passes SQL validation. AI Usage โ†’ What Happened records the requests, prior/current query context, generated query, iteration linkage, and safe schema/provider metadata. AI SQL profiles use a larger 300,000โ€“500,000 character full-schema input budget so the live Export Schema document is not constrained by the smaller meal-planning prompt limit; older SQL profiles are normalized to at least 300,000 characters when loaded.

Combine Recipes Seed charges (0.7.3-alpha development)

The selected Adapt Recipe Quality Profile determines the price for each of the two initial AI operations. The initial quote reserves twice that per-operation cost using two separate durable job reservations. Comparison may settle independently. Only an approved new final generation uses the held second reservation; otherwise it is released. New AI attempts need new explicit Seed confirmation and new reservations. AI Usage events carry distinct descriptive labels for original generation, Recipe comparison and combined generation, but are currently grouped under the existing Adapt Recipe use-case key. Verify settlement, usage reporting and expiration on SQLite and PostgreSQL before production use.

Create Recipe has its own create_recipe Quality Profiles and AI Usage grouping, independent from adapt_recipe. The selected Create Recipe profile controls provider/model, Seed quote, reservation and settlement for original-recipe generation.

Multi-step Combine Recipes and Plan Meals originals (0.7.3-alpha)

Combine Recipes' two provider requests continue to have two individual ledger-backed usage events. AI Usage labels these as steps of one workflow, and What Happened joins their retained comparison, user selections, and generated Recipe, checking organization/user ownership before looking up the sibling. A canceled or skipped second request has no corresponding billable provider event. The CSV reconciliation retains one entry per provider transaction. Plan Meals original Recipes are separately metered Create Recipe child jobs linked to the Plan Meals parent job. The upfront displayed estimate is Plan Meals Seeds plus one Create Recipe per eligible Meal Slot; the ledger charges only actually submitted/settled requests.

0.7.3-alpha original generation and combinations

The Create Recipe use case has its own Quality Profiles, distinct from Adapt Recipe and Plan Meals. Bulk Adapt uses one AI request for up to 25 recipes; its purple estimate separates the included base Recipes from additional billed recipe blocks. One confirmed batch yields one charge regardless of how many of its results are eventually saved.

Combine Recipes is a two-request workflow: compare the original and secondary recipes, then optionally generate a result from the user-selected compatible attributes. AI Usage keeps one record for each paid provider request to preserve costs and Seed auditability, but What Happened presents the paired steps with request inputs on the left, output/selected attributes on the right, followed by the final generation result. Declined or unused generation reserves are released rather than settled.

Plan Meals Create Recipe estimates up to the chosen 1โ€“4 original Recipes per eligible Meal Slot (default one) and optionally one image per new Recipe. The quote shows planning-only minimum and planning + all possible child requests maximum. The parent reserves the full approved maximum once. Child Create Recipe/Image jobs receive allocations from this hold instead of reserving the same Seeds again; only validated work is charged, with unused allocations released. A partially completed run should be reconciled using the initial parent reservation ledger entry, the final parent planning charge, and distinct child job chargesโ€”not by assuming the entire maximum was spent. Raw provider evidence is available only via authorized retained AI Usage details.

On this page