aedeny/the-cook-book

    CKL Notation Reference

    CKL Notation Reference

    This page explains every element of the CKL notation. It is organized by what each part represents in cooking, not by syntax category.

    How a Recipe Is Structured

    Every CKL recipe follows a natural order:

    1. Declare what you need — servings, ingredients, equipment

    2. Describe what you do — actions in sequence

    3. State what must be true — safety conditions and checks

    This mirrors how a professional cook thinks: gather your mise en place, execute the procedure, verify the result.

    ---

    Part 1: What You Need (Declarations)

    Servings

    How many portions the recipe produces.

    servings 4

    This number is required. It sets the baseline for all ingredient quantities.

    Ingredients

    Each ingredient is declared with a name and an exact quantity. No vague measurements.

    ingredient "chicken breast" 500g
ingredient "olive oil" 30ml
ingredient "salt" 5g
    • The name is in quotes
    • The quantity is a number immediately followed by a unit (g, kg, ml, l)
    • Every ingredient used later in the recipe must be declared here first
    Why this matters: If you reference an ingredient that hasn't been declared, the validator catches it. This prevents the common recipe problem of mentioning an ingredient in step 5 that was never listed at the top.

    Equipment

    Cooking equipment is declared before use. CKL supports these types:

    pan "cast iron skillet" 30cm
pot "dutch oven" 5l
oven "convection oven"
bowl "mixing bowl" 3l
knife "chef's knife"
    • pan — flat cooking surface (skillets, sauté pans)
    • pot — deep cooking vessel (stock pots, dutch ovens)
    • oven — enclosed heating environment
    • bowl — unheated preparation vessel
    • knife — cutting tool (required when using cut statements)

    Size is optional but encouraged for reproducibility.

    Why this matters: A recipe that says "heat pan to 200C" without first declaring the pan will fail validation. This encodes the real-world principle that you need to know what equipment is required before you start cooking.

    ---

    Part 2: What You Do (Actions)

    Heat

    Sets equipment to a specific temperature.

    heat pan to 180C
heat oven to 200C
    • Temperature is always in Celsius
    • The equipment must be declared earlier in the recipe
    • For searing, the pan typically needs to be at 180°C or higher for the Maillard reaction to occur

    Apply

    Adds an ingredient to equipment. This is the fundamental action of cooking — putting food into or onto a cooking surface.

    apply "olive oil" to pan
apply "chicken breast" to pan
    • The ingredient name must match a declared ingredient exactly
    • The equipment must be declared
    Cooking principle encoded: If you apply an ingredient to equipment that hasn't been heated, the validator will warn you. This captures the real-world rule that searing requires high heat — putting chicken on a cold pan steams it instead of browning it.

    Wait

    Pause for a specific duration. Used for cooking times.

    wait 6min
    • Duration is a number followed by min
    • Used when food needs time on heat to cook

    Deglaze

    Dissolves the caramelized fond (browned bits) from the bottom of a pan by adding liquid.

    deglaze pan with "white wine"
    • The liquid must be a declared ingredient
    • The pan must be hot — deglazing a cold pan doesn't dissolve the fond
    Cooking principle encoded: If the pan hasn't been heated, the validator will warn you. This captures the physical reality that fond only dissolves when liquid hits a hot surface.

    Reduce

    Concentrates a liquid by evaporation, develops flavors through extended cooking, or both. Every reduce statement specifies a duration and a target — the desired end state of the liquid.

    reduce 3min until au_sec
reduce 5min until nappe
reduce 90min until melded

    Reduction Targets

    | Target | Meaning | Typical Use |

    | -------------- | ------------------------------------------------------ | --------------------------------------- |

    | au_sec | Reduced nearly dry; alcohol evaporated, fond dissolved | Wine reductions, post-deglaze (2–5 min) |

    | nappe | Coats the back of a spoon; classic sauce consistency | Stock reductions, pan sauces |

    | thickened | Noticeably reduced volume and increased viscosity | Tomato sauces, roux-based liquids |

    | concentrated | Significant reduction with intensified flavor | Flavor-intensity focus |

    | melded | Flavors fully integrated through extended cooking | Long braises and simmers (60+ min) |

    | glossy | Shiny, emulsified, cohesive appearance | Butter-mounted sauces |

    • Duration in minutes
    • Target must be one of the six listed values (enforced by lint rule E501)
    • melded is the correct target when the goal is not volume reduction but deep flavor integration — e.g. a 90-minute bolognese or a 2-hour braise

    Rest

    Allows food to rest after cooking. Critical for proteins — resting lets juices redistribute so they don't pour out when you cut.

    rest 5min
    • Duration in minutes
    • For meat, a general guideline is 1 minute per 100g, plus carryover cooking adds 2–5°C

    Until

    A condition that must be met before continuing. Used primarily for internal temperature checks.

    until internal_temp >= 74C
    • The condition specifies a measurable physical state
    • For poultry, 74°C is the minimum safe internal temperature
    • For ground meat, the minimum is 71°C
    Why this matters: This is where CKL enforces food safety automatically. A recipe that says until internal_temp >= 60C for chicken will fail validation — 60°C is not safe for poultry. The validator knows this because the ingredient database tags chicken as poultry with a minimum safe temperature of 74°C.

    ---

    Part 2b: What You Prepare (Mechanical Actions)

    These actions model physical food preparation before or between heating steps.

    Cut

    Reduces the size of an ingredient. Every cut specifies a style and optionally a target size.

    cut "onion" style dice size 5mm
cut "garlic" style mince
cut "potatoes" style grate
    • The ingredient must be declared
    • Style is required: dice, slice, mince, chop, julienne, grate, crush, pound, brunoise, chiffonade
    • Size is optional: a number followed by mm or cm

    Mix

    Distributes components within equipment until a target state is reached.

    mix bowl until combined
mix pot until smooth
    • The equipment must be declared
    • Target state is required: combined, uniform, smooth, cohesive, emulsified, homogeneous

    Shape

    Forms a cohesive mixture into a geometric shape.

    shape bowl into balls size 3cm
shape bowl into patties
    • The equipment must be declared
    • Form is required: balls, patties, logs, rounds, discs, sheets, strips, dumplings
    • Size is optional
    • The validator warns if shaping without prior mixing (W201)

    Coat

    Applies a dry material to the surface of an ingredient. Used for breading and dredging.

    coat "chicken breast" with "flour"
coat "chicken breast" with "eggs"
coat "chicken breast" with "breadcrumbs"
    • Both the ingredient and coating must be declared
    • Multiple sequential coats model multi-stage breading

    Drain

    Removes free liquid from equipment contents.

    drain pot
    • The equipment must be declared
    • Used after boiling pasta, cooking legumes, or blanching

    Soak

    Submerges a dry ingredient in liquid for a specified duration.

    soak "chickpeas" in "water" 480min
    • Both the ingredient and liquid must be declared
    • Duration is required: a number followed by min

    Knead

    Develops structure through repeated folding and pressing.

    knead bowl until elastic
    • The equipment must be declared
    • Target state is required: elastic, smooth, tacky

    Bowl

    A new equipment type for unheated preparation vessels. Unlike pan, pot, and oven, bowls do not require heating before use.

    bowl "mixing bowl" 3l

    ---

    Part 2c: Multi-Stage Cooking

    Some recipes require preparing separate components independently before combining them. A classic example is tiramisu, where the zabaione-mascarpone base and whipped cream are prepared in separate bowls, then folded together.

    CKL supports this with two keywords: stage and combine.

    Stage

    Declares a named preparation stage with its own equipment. The stage name becomes a valid equipment reference for all subsequent statements.

    stage zabaione bowl "mixing bowl" 3l
    • stage is followed by a name (the identifier you'll use later, e.g. zabaione)
    • Then an equipment declaration (type, quoted name, optional size) — exactly like a regular equipment statement
    • The name can be used anywhere an equipment type would be used: apply, mix, heat, etc.

    Once declared, use the stage name as equipment:

    stage zabaione bowl "mixing bowl" 3l
apply "egg yolks" to zabaione
apply "sugar" to zabaione
mix zabaione until smooth
    Why this matters: Without stages, you can only have one piece of each equipment type. Stages solve the "multiple bowls" problem — each stage binds a unique name to its own equipment instance, so you can work with several bowls, pans, or pots simultaneously.

    Combine

    Merges the results of two or more named stages into a target.

    combine zabaione whipped_cream in cream_mix
    • Lists two or more source stage names
    • in introduces the target — must be a previously declared stage name or equipment type
    • After combining, use the target name for further actions (e.g. mix cream_mix until combined)

    Complete Multi-Stage Example

    # Prepare zabaione base
stage zabaione bowl "mixing bowl" 3l
apply "egg yolks" to zabaione
apply "sugar" to zabaione
mix zabaione until smooth
apply "mascarpone" to zabaione
mix zabaione until smooth

# Prepare whipped cream separately
stage whipped_cream bowl "mixing bowl" 2l
apply "heavy cream" to whipped_cream
apply "vanilla extract" to whipped_cream
mix whipped_cream until stiff

# Fold whipped cream into zabaione
stage cream_mix bowl "mixing bowl" 5l
combine zabaione whipped_cream in cream_mix
mix cream_mix until combined

    This reads naturally: prepare the zabaione, prepare the whipped cream, then combine them. Each stage has its own bowl, and the combine statement makes the merge explicit and traceable.

    ---

    Part 3: Units

    Mass

    • g — grams
    • kg — kilograms

    Volume

    • ml — milliliters
    • l — liters

    Temperature

    • C — Celsius (the only supported temperature unit)

    Time

    • min — minutes

    Length

    • cm — centimeters (equipment sizes, cut sizes)
    • mm — millimeters (fine cut sizes)

    All units are attached directly to their number with no space: 500g, 180C, 6min, 5mm.

    ---

    Part 4: Comments

    Lines starting with # are comments. They are ignored by the validator but useful for human notes.

    # Season the skillet before first use
pan "cast iron skillet" 30cm

# Chicken should be at room temperature
ingredient "chicken breast" 600g

    ---

    Complete Example

    Here is a full recipe that demonstrates all elements:

    servings 4

# Ingredients — everything measured precisely
ingredient "chicken breast" 600g
ingredient "olive oil" 30ml
ingredient "salt" 5g
ingredient "black pepper" 2g
ingredient "butter" 20g
ingredient "garlic" 10g
ingredient "thyme" 3g

# Equipment — declared before use
pan "cast iron skillet" 30cm

# Procedure — actions in sequence
heat pan to 180C
apply "olive oil" to pan
apply "salt" to pan
apply "black pepper" to pan
apply "chicken breast" to pan
wait 6min
apply "butter" to pan
apply "garlic" to pan
apply "thyme" to pan
wait 6min

# Safety — chicken must reach 74°C
until internal_temp >= 74C

# Resting — juices redistribute
rest 5min

    This recipe will pass validation because:

    • All ingredients are declared before use
    • Equipment is declared before heating
    • The pan is heated before ingredients are applied
    • Poultry reaches the safe minimum temperature (74°C)
    • A rest period is included