Ingredient substitutions: treat interchangeable ingredients as in stock for pantry recipes

[dubadub]

From a trialing user (Discord, 2026-08-11), as a follow-on to global aisle aliases (see the alias issue). Aliases cover same item, different name (bell pepper / capsicum); this is about different items that substitute for each other in a recipe:

I could use butter or oil for certain cooking process. If I'm out of butter, but do have oil, I would want the API to count that ingredient as in stock!

Sketch from the conversation: some way to declare substitutions — either in the .cook file itself (e.g. an @butter|oil{}-style alternative) or in workspace config — so that pantry recipes counts a recipe as cookable when any acceptable substitute is in the pantry, and the shopping list / recipe display can show the alternative.

Needs discussion on where the declaration lives (recipe syntax would require a spec update; a workspace-level substitutions config would not) and how it interacts with aisle aliases.

[daviddehoog]

I suggest both might be desirable, for different purposes.

Declaring substitutions in recipes makes a lot of sense. It seems logical to be able to define workable ingredient substitutions at the recipe level. This is pretty common practice in written recipes and it would be consistent with the aim of keeping all the recipe information in a single text file.

It would need some logic in the scaling, pantry checking and shopping list generation to handle the alternatives. One edge case that comes to mind is partial amounts. Using the butter or oil substitution example: you need 60g of butter or 30mL of oil, and you have 30g of butter in the pantry and 120mL of oil. Should the shopping list say nothing and expect the user to work out that they are using all the butter and 15mL of oil ? Further, what if those 30g of butter were actually allocated to another recipe on the shopping list and the user was meant to use all oil in this one, instead ? It wouldn't currently be possible to see how the shopping list had been assembled, scaled and calculated - or to necessarily reproduce the calculation at a later date. This could be a frustrating user experience.

There might also be value in a ‘global’ or ‘workspace’ solution that applies substitutions to recipe files when they are viewed or parsed. These would be configured by the user to reflect their needs or preferences. For example, a user with an allergy to peanuts is unlikely to want to use peanut oil. The user could configure a workspace alias to substitute ‘canola oil’ (or another type!) for peanut oil in any recipes parsed through the CLI or displayed in the web interface, with that substitution flowing through to the shopping list.

It may also help with ingredients which are seasonally available (like “berries, fresh if available or frozen”). The user could update the global alias depending on produce availability. (Note, I’m not suggesting making cooklang seasonally aware!)

This would complement the existing aisle.conf arrangement, in that the aliases there could be used to connect ‘oil, canola’, ‘canola oil’ to the right aisle or store, as at present. This is where a user sets shopping preferences, like ‘oil’ or ‘cooking oil’ to the products or brands the user prefers.

It would significantly increase the potential for misconfiguration, though, in particular missing or circular aliasing, with the definitions spread across multiple files.