Recipe Editing and Cache Artifacts

Audience: User, Org Admin, Developer, Support Related: Overview · Importing And Discovery · Eink Rendering · Recipe Import

Recipe content can be edited from Admin and Mobile. Blackcap stores structured editable content and regenerates the recipe PDF and display/preview images when the effective recipe content, units, orientation, layout, or render profile changes.

Source refresh and editable-content rebuild are distinct operations. Refreshing an edited web recipe must not overwrite user changes without an explicit decision. Cache status and repair tools identify missing, stale, or failed artifacts.

Editable content and effective units

Admin and Mobile can edit recipe title, description, ingredients, instructions, and notes. Blackcap preserves the original imported/captured source and stores the current editable content through the recipe service/database layer. Legacy recipe_cache/*.editable.json files are not the authoritative fallback for a missing database record.

Editable content can retain source text plus optional converted/presentation fields. Organization Preferred Recipe Units controls whether shared effective-content services prefer As Written, US, or Metric units for rendering, sharing, Let’s Cook, and shopping-list generation. Conversion must remain conservative: clear equivalent pairs can be reordered, while ambiguous package/count descriptions such as 1 can, 1 package, or to taste remain unchanged.

Saving content may mark PDF, PNG, display, ingredient-index, and search artifacts stale or queue their rebuild through the established service/background-job path. A source refresh must not silently replace user edits.

Made It photos and notes

The Mobile Made It flow can store a personal finished-dish photo, rating, notes, and cleanup feedback without replacing the recipe’s source thumbnail. Images are resized and saved as optimized JPEG files through the shared image utility. The normal path is an organization recipe-cache artifact such as:

<recipe-cache>/<recipe_id>_made_it.jpg

The database stores the managed relative path and timestamps. Admin and Mobile can display the photo, and email-ready recipe sharing may include it. Backups include managed Made It artifacts when they fall within the selected backup scope. Recipe archive/delete should preserve the artifact until the normal permanent-purge policy removes the recipe and its dependent files.

Blackcap can estimate and display how much cleanup a recipe is likely to create. The goal is not to count every dish perfectly, but to give the cook a quick forecast of washing-up effort before choosing or planning a recipe.

The feature is intentionally split into two kinds of information:

• cleanup rating: the user-facing level shown on recipe cards, such as Very Low, Low, Medium, High, or Very High;
• cleanup details: supporting data such as estimated pots, pans, bowls, tools, mess factors, and cleanup reducers.

The rating can be automatically estimated or manually corrected from Made It feedback. Manual/Made It ratings should override the displayed level, but should not discard the useful automatic details gathered during import or cache rebuild.

Rating levels

Cleanup ratings use five levels:

The display colors and thresholds are organization-scoped and configurable under Configuration → Organization → Recipe Info.

Automatic cleanup estimate

Blackcap estimates cleanup from recipe text during recipe import/capture and during recipe cache rebuild.

The estimator looks at the recipe title, description, ingredients, instructions, and notes. It can infer signals such as:

• cookware count: pots, pans, sheet pans, baking dishes, skillets, Dutch ovens;
• bowls and prep vessels: mixing bowls, marinade bowls, batter bowls;
• tools: blender, food processor, mixer, whisk, grater, thermometer, colander;
• mess factors: raw meat, greasy frying, sticky sauces, breading, melted cheese, baked-on foods;
• cleanup reducers: one-pot, sheet-pan, no-cook, parchment-lined, foil-lined, slow-cooker style containment.

The automatic result is stored as recipe metadata, including fields such as:

cleanup_score
cleanup_difficulty
cleanup_source
cleanup_confidence
cleanup_estimated_pots
cleanup_estimated_pans
cleanup_estimated_bowls
cleanup_estimated_tools_count
cleanup_tools
cleanup_mess_factors
cleanup_reducers
cleanup_summary

The generated tooltip uses the rating plus the supporting details when available.

Recipe cache rebuild behavior

Recipe cache rebuilds now refresh cleanup metadata because the cache rebuild is already the normal way to regenerate derived recipe display data.

A cache rebuild should:

1. load or rebuild the editable recipe content;
2. recalculate automatic cleanup details from the current recipe body;
3. persist the refreshed metadata back to the recipe row and editable metadata;
4. let Recipe Library cache-status polling update the visible recipe card without a full page refresh.

Manual/Made It cleanup ratings are preserved across later cache rebuilds. In that case the rebuild may still preserve or refresh the automatic supporting details, but it should not overwrite cleanup_source = made_it or the user-corrected rating.

The renderer version should be bumped whenever cache rebuild output or derived metadata behavior changes enough that existing cached recipes should be marked stale.

Made It cleanup feedback

The mobile Made It flow includes a compact cleanup slider. It appears for every recipe, even if the recipe does not already have a cleanup rating.

Behavior:

• the slider is initialized from the current cleanup rating when present;
• moving the slider updates the selected cleanup level;
• saving Made It writes the cleanup rating as manual/Made It feedback;
• cleanup_source is set to made_it;
• the automatic details such as pots, pans, tools, mess factors, and cleanup reducers are preserved;
• future cache rebuilds should not overwrite the Made It rating.

This makes Made It the real-world correction path while keeping the automatic estimate useful for context.

UI surfaces

Cleanup rating appears as a compact 🛁 pill wherever recipe-card metadata is shown, including:

• Admin Home selected recipe card;
• Recipe Library cards/search results;
• Meal Planner recipe add/search tiles where recipe metadata pills are shown;
• Mobile selected recipe card.

The pill tooltip should explain the score and supporting details when available. Example:

Medium cleanup · score 4/10. Estimated dishes: 1 pot, 1 pan, cutting board. Mess factors: raw meat. Cleanup helpers: foil-lined.

If Made It supplied the rating, the tooltip should make that clear while retaining the original automatic details:

Cleanup manually rated Low during Made It. Estimated dishes: 1 pan, 1 bowl, whisk. Cleanup helpers: one-pot.

Configuration

Open Configuration → Organization → Recipe Info.

The cleanup configuration includes:

• threshold scores for Very Low, Low, Medium, and High;
• Very High is anything above the High max score;
• background, text, and border colors for each level;
• Cleanup Preset values that apply immediately when selected.

The Time Pill configuration remains separate and is labeled Time Pill Format with Time Preset.

Changing cleanup thresholds or colors affects display mapping immediately for stored scores. Rebuilding recipe cache recalculates missing/stale automatic cleanup estimates.

Database notes

Cleanup metadata is stored with the recipe metadata/legacy JSON and mirrored through editable recipe metadata. It is not a separate table.

Database Admin can inspect recipe rows and editable recipe metadata, but normal cleanup rating changes should happen through:

• automatic recipe import/capture;
• recipe cache rebuild;
• Mobile Made It feedback;
• future Recipe Info editing if a direct admin correction UI is added.

Testing checklist

• Import a recipe and confirm a cleanup pill appears on recipe cards.
• Rebuild cache for an older recipe and confirm cleanup metadata is generated.
• Rebuild cache for a non-default organization recipe and confirm cleanup metadata is generated in that organization.
• Confirm metric/US/as-written unit settings do not prevent cleanup metadata from being generated.
• Change cleanup thresholds and confirm the displayed pill level remaps without rebuilding.
• Change cleanup colors and confirm the pill colors update.
• Use Made It to set cleanup on a recipe that has no cleanup rating.
• Use Made It to adjust cleanup on a recipe that already has automatic cleanup details.
• Confirm Made It preserves pots/pans/tools/mess-factor details.
• Rebuild cache after Made It and confirm the Made It rating is preserved.
• Confirm Recipe Library updates the total-time and cleanup pills after cache rebuild without a full page refresh.