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 Troubleshooting

Audience: User, Org Admin, System Admin, Deployment Administrator, Developer, Support Related: Overview ยท Providers And Connections ยท Seeds And Usage

Check provider connection state, use-case capability, model/profile configuration, Seed balance and reservation state, provider error details, validation failures, and asset retention. Never place provider keys or full private prompts in support output.

Support Chat structured-response errors

If Support Chat reports that a provider returned a structured response Blackcap could not parse, do not assume the user's punctuation or special characters are the cause. Blackcap requests strict JSON-schema output and user/documentation text is transmitted as normal provider input rather than manually concatenated JSON.

For OpenAI, first check the Support Chat AI Usage row for the failure category and provider request/response IDs, then check the application log for the corresponding safe diagnostics. In particular, distinguish:

  • context_limit with incomplete_reason=max_output_tokens: the model used the configured output budget before completing its JSON object. Increase the Support Chat Maximum Output Tokens setting or lower reasoning effort and retry.
  • invalid_response with a JSON error line/column: the provider returned text that was not valid JSON even after harmless wrapper handling. Use the provider response ID when investigating the upstream request.
  • safety_rejection: the provider declined the request; this is not a JSON escaping problem.

Blackcap accepts harmless UTF-8 BOM, Markdown code-fence, and surrounding presentation wrappers, but it deliberately does not guess how to repair malformed quotes or escapes because doing so could change the model's intended response.

A model appears in the provider catalog but does not work

A provider's model-list API is not always proof that the same credential can use that model on every API surface. Blackcap therefore combines its curated capability catalog with the provider's live model inventory and, for inexpensive text use cases, an endpoint-specific capability probe.

In Configuration โ†’ Platform โ†’ AI, open the provider details to compare the models Blackcap knows about with the models verified for that credential. A known-but-unusable model remains readable but is marked Unavailable with a red diagonal slash. Use-case badges show whether Blackcap expects the model to serve ๐Ÿ–ผ๏ธ Recipe Image, ๐ŸŽฌ Social Recipe, ๐Ÿ›Ÿ Support Chat, or ๐ŸŽ™๏ธ Transcription.

If a text model is unexpectedly unavailable:

  1. Use the provider Test action to force a fresh availability check instead of waiting for the cache to expire.
  2. Confirm the quality profile uses a model marked usable for that specific use case.
  3. Check the application log for the safe provider failure category and HTTP status. A model may be visible in the provider inventory but still return 404/model-unavailable on the endpoint Blackcap uses.
  4. Do not expect Blackcap to silently fall back to another model. The quality profile's selected model is authoritative so provider/model changes remain explicit and auditable.

Changing the provider connection or model on a quality profile preserves the other compatible profile settings. Blackcap should not reset unrelated output, timeout, Support Chat, or social-media limits merely because the model selection changed.

Plan Meal provider output is rejected after a successful HTTP response

Plan Meal distinguishes an incomplete provider response from malformed completed JSON. If Gemini reaches the configured output ceiling, Blackcap reports that the configured output limit was reached instead of a generic parse failure. OpenAI likewise surfaces an incomplete max_output_tokens condition separately. Increase the Plan Meal profile's Maximum Meal Plan output tokens (up to the selected model's capability) or lower reasoning effort if appropriate. The model-specific ceiling is currently 128,000 for Blackcap's GPT-5-family catalog and 65,536 for supported Gemini text models; Blackcap does not impose the former generic 20,000 cap.

A provider HTTP 200 means only that the provider completed its request; Blackcap still validates the returned Meal Plan against the trusted Meal Slot snapshot before saving it.

For Plan Meal, source Recipe timers are authoritative. The provider is asked to copy timer_seconds only from the exact source step's timer_candidates. Blackcap canonicalizes that field against the trusted source: an exact value is retained, a single known source timer is restored if the provider rounded/restated it, and invented or ambiguous timer values are discarded. Trusted timers are also scheduling constraints. The next source step in that same Recipe cannot start before the timer is ready. When a source instruction contains active setup before a passive timer (for example preparing a marinade and coating chicken before a 3-hour chill), the active setup must finish first and the complete trusted timer begins afterward. Pure timed actions such as a 30-minute bake are not double-counted when the planned step already spans that interval. If provider scheduling violates timer readiness, Blackcap back-schedules the timer-bearing preparation when possible and then re-sequences the accepted recommendations by repaired time; independent Recipe work can still occur during the waiting interval. Letโ€™s Cook continues to use the source Recipe timer candidates rather than an AI-invented duration.

ingredient_refs are not trusted Recipe content. Providers must use exact ingredient_key values from the supplied Recipe and should return [] rather than names or guesses. Blackcap then canonicalizes ingredient references from its own trusted ingredient-to-step mapping (matched_step_keys) when that mapping exists, or retains only exact keys that exist in the same Recipe for older data. Unknown names/keys are discarded instead of failing a paid provider response. Ingredient quantities and source text remain entirely Recipe-authoritative.

Gemini Plan Meal uses a compact provider guidance schema so the provider returns the expected top-level object and fields without receiving Blackcap's deeper strict validation contract. The request includes an explicit required source-step manifest. Dynamic per-Meal minItems/maxItems bounds stay in the strict OpenAI/local schema rather than the Gemini guidance schema because Gemini can reject those otherwise valid settings with a generic 400 INVALID_ARGUMENT. If Gemini rejects the compact guidance schema anyway, Blackcap retries once as JSON MIME without a provider schema; the returned object still has to satisfy Blackcap's exact required-step coverage and trusted-source validation. Providers are told not to combine or omit source steps, to interleave independent Recipe/Component work instead of serializing entire Recipes, andโ€”when a Serve At time is suppliedโ€”to delay quality-sensitive finishing work until reasonably near serving rather than completing hot sides hours early. Plan Meal v9 additionally requires correct timer readiness, source-backed ingredient-key metadata, plus a compact elapsed timeline: avoidable multi-hour holes must be removed by moving earlier independent work later or interleaving useful work, and relative minute offsets must never be derived by subtracting wall-clock times across midnight. Blackcap also conservatively compacts pathological Serve At slack after source validation without shortening trusted timers or violating explicit dependencies. A Component relationship alone does not block its parent or unrelated Recipes unless an explicit dependency says so. Blackcap may unwrap a harmless one-item JSON array or JSON-encoded string containing one object, but it does not repair malformed JSON.

Quality Profile disabled after two failures

If a Quality Profile fails two terminal AI requests consecutively, Blackcap disables it automatically and shows Failed twice in the profile's Disable Reason column. This is a cost-safety feature: it prevents a broken provider/model/profile configuration from repeatedly spending provider money without returning usable results.

Use the profile's ๐Ÿ“Š action to open AI Usage filtered to that profile. Review the friendly failure reason and, for System Admins, the provider request ID/token/cost diagnostics. Correct the connection, model, output-token ceiling, effort, or other profile setting, then explicitly enable the profile. Manual enable/disable resets the failure streak and clears the automatic reason.

Anthropic Claude

Claude connections are configured under Configuration โ†’ Platform โ†’ AI with provider type Anthropic Claude. Blackcap supports Claude for Support Chat, Recipe Photo, and Plan Meal profiles. Recipe/Meal image generation and direct social-video review remain OpenAI/Gemini capabilities.

For Claude structured-output failures, first verify that the configured credential can see the selected model. max_tokens is a hard ceiling shared by Claude's thinking and visible response, so a high-effort Plan Meal may need a larger output ceiling. A max_tokens stop is reported to AI Usage with a friendly output-limit failure reason rather than a generic provider error. Authentication, rate-limit, timeout, unavailable-provider, unsupported-settings, refusal, and invalid-response failures are similarly normalized with user-facing text.

On this page