recipe: a recipe can build on a preset, on the command line and on the batch screen

extends: preset:<id> names a preset and with: fills its parameters, written
the way the flags take them. The preset's targets come first and the file's
own after them, so the file is the same run as "tfg preset eject" with the
extra targets typed under it, byte for byte - PR5 in a second form, and a
guard runs both roads and compares the files. A target whose id the preset
already uses is refused at the file's own line, with without extends is
refused, and extends names a preset and nothing else yet. A file with
extends and no targets of its own is legal: it is a preset run committed
to a repository. The owner's three decisions, in
docs/EXTENDS-WITH-2026-09-22.md: the window in the same change, the
recipe hash of the file as written, the clash addressed at the file's
target.

The recipe package cannot expand a preset - the layer rule lets preset
import recipe and not the other way - so reading such a file is two steps
with the expansion between them. recipe.ExtensionOf says what the file
builds on, recipe.ParseExtending reads it with the expansion in front of
its targets, and preset.ReadRecipe joins the two; a guard holds cli and
gui to reading files through that door. The merge is at the raw level,
before validation, so every rule about targets runs once where it lives,
and a refusal about the file's target carries its position in the file,
not in the merged list. recipe.CheckBase holds every preset to
contributing a version and targets and nothing else, asked of each
registered preset by a guard before any recipe builds on one.

Refusals from the preset side become recipe problems addressed to extends
or with.<name>, in four parts - which found a refused value arriving with
no remedy, now carried from the declaration. The manifest records the
preset under run.preset as a --preset run does, validate --json carries
the same block, and the batch screen gains a section: a switch, the
preset, and its parameters drawn from the declaration the preset screen
already draws. Parity 122 of 130. Five guards, nine mutations, one more
stored screen.

Noticed on the way and recorded as O231, not changed: the batch screen's
label switch starts off while the other two surfaces have the label on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: donislawdev

CHANGELOG.md

@@ -14,6 +14,27 @@ because it turns other people's test suites red.
 
 ## [Unreleased]
 
+### Added
+
+- **A recipe can build on a preset.** Two keys the recipe reader used to
+  refuse as not built yet now work: `extends: preset:<id>` names the preset
+  and `with:` fills its parameters, written the way the flags take them
+  (`limit: 5mb`, `spread: 1B,1kb,1mb`, `format: png`). The preset's files
+  come first and the recipe's own `targets` are added after them, so the
+  file is the same run as `tfg preset eject` with the extra targets typed
+  under it, byte for byte, and shorter. A target whose `id` the preset
+  already uses is refused rather than replaced, `with` without `extends` is
+  refused, and `extends` names a preset and nothing else yet - not another
+  file. A recipe with `extends` and no `targets` of its own is legal, which
+  is how a preset run is committed to a repository. The manifest records the
+  preset under `run.preset` with the parameters left out listed as
+  `defaulted`, as a `--preset` run does, and `run.recipe_hash` is the hash
+  of the file as written. `tfg validate --json` carries the same `preset`
+  block. On the desktop window, the batch screen has a section "Build on a
+  preset": a switch, the preset, and its parameters drawn under it. A preset
+  flag beside a recipe file (`tfg generate r.yaml --limit 5mb`) is refused
+  with a sentence saying the value goes under `with`.
+
 ### Changed
 
 - **The line before the second start says what was checked, not what was

README.md

@@ -428,6 +428,8 @@ tfg generate fixtures.yaml
 | `seed` | the number that makes a run repeatable. Same seed, same bytes |
 | `defaults.label` | write the self describing label inside each file. Default `true` |
 | `targets` | the list of things to produce. See below |
+| `extends` | a preset to build on, as `preset:size-boundaries`. Its files come first and your `targets` are added after them. See [Building on a preset](#building-on-a-preset) |
+| `with` | the preset's parameters, written the way the flags take them: `limit: 5mb`, `spread: 1B,1kb,1mb`, `format: png`. One left out stands in from its default, and the manifest says so |
 | `output.dir` | where the files and the manifest go. A relative path is read from the directory you run in, not from the one the recipe sits in |
 | `output.manifest` | manifest file name. Default `manifest.json` |
 
@@ -483,11 +485,39 @@ A reason names **the rule in play**, not the verdict. That is why the same
 reason can sit under either outcome - a file one byte under a limit is
 `accept`, and the rule it is about is still `size_limit`.
 
+### Building on a preset
+
+A recipe can start from a preset's set and add its own files:
+
+```yaml
+version: 1
+seed: 7
+extends: preset:size-boundaries
+with:
+  limit: 5mb
+  format: png
+targets:
+  - id: our-legacy-format
+    format: tiff
+    count: 1
+    size: 3mb
+```
+
+This is the same run as `tfg preset eject size-boundaries --limit 5mb --format png`
+with the extra target typed under it, byte for byte. The file is shorter, it
+says which question the set answers, and the manifest records the preset under
+`run.preset` with the parameters you left out listed as `defaulted`. A target
+whose `id` the preset already uses is refused, never silently replaced. A
+recipe with `extends` and no `targets` of its own is legal, and it is how a
+preset run is committed to a repository. The `--limit` and other preset flags
+do not apply beside a recipe file, and the recipe's `with` is where they go.
+
 ### Not built yet
 
 These keys are recognised and **refused with a message saying so**, never
-ignored quietly: `extends`, `with`, `policy`, `engine`, `defaults.fill`,
-`fill` on a target, `mutations`, `output.split_threshold`.
+ignored quietly: `policy`, `engine`, `defaults.fill`, `fill` on a target,
+`output.split_threshold`. `extends` names a preset and nothing else yet, so a
+recipe cannot build on another file.
 
 ## 📁 Formats in detail
 

internal/cli/generate.go

@@ -186,7 +186,7 @@ func generate(ctx context.Context, args []string, out, errOut io.Writer) int {
 
 // targetsFromRecipe reads the recipe and settles what the flags override.
 func targetsFromRecipe(path string, g *generateOpts, given map[string]bool, opt *engine.Options, errOut io.Writer) ([]engine.Target, int) {
-	rec, hash, code := loadRecipe(path, errOut)
+	read, hash, code := loadRecipe(path, errOut)
 	if code != ExitOK {
 		return nil, code
 	}
@@ -200,7 +200,15 @@ func targetsFromRecipe(path string, g *generateOpts, given map[string]bool, opt
 		return nil, ExitUsage
 	}
 
-	return targetsFromParsedRecipe(rec, hash, g, given, opt), ExitOK
+	// A file that builds on a preset is recorded the way a --preset run is,
+	// and says the same things out loud - which of the preset's numbers were
+	// invented because the file did not give them. Nil for a file that stands
+	// alone, and the manifest field stays absent.
+	for _, note := range read.Notes() {
+		fmt.Fprintf(errOut, "note: %s\n", note)
+	}
+	opt.Preset = record(read.Expansion)
+	return targetsFromParsedRecipe(read.Recipe, hash, g, given, opt), ExitOK
 }
 
 // targetsFromParsedRecipe settles what the flags take away from a recipe that

internal/cli/preset.go

@@ -28,7 +28,13 @@ import (
 // which is the output contract and no business of an input concept. The drift
 // this invites is watched behaviourally instead - a guard runs the same preset
 // from both surfaces and compares the records they produce.
+//
+// Nil in, nil out: a recipe file that stands alone has no preset to record,
+// and the manifest field is absent rather than empty for it.
 func record(e *preset.Expansion) *manifest.Preset {
+	if e == nil {
+		return nil
+	}
 	return &manifest.Preset{
 		ID:         e.Preset.ID,
 		Parameters: map[string]string(e.Settled),
@@ -270,9 +276,12 @@ func explainUndefinedFlag(fs *flag.FlagSet, args []string, errOut io.Writer) boo
 	if name == "" {
 		return false
 	}
+	// The second sentence names both roads, because since 2026-09-22 a
+	// recipe file can build on the preset too - and beside a file the flag
+	// does not exist either, the file's with section is where the value goes.
 	fmt.Fprintf(errOut,
-		"tfg: --%s is a parameter of the preset %s, so it only exists beside it. Add --preset %s, or drop --%s.\n",
-		name, owner, owner, name)
+		"tfg: --%s is a parameter of the preset %s, so it only exists beside it. Add --preset %s, put %s under with: in a recipe that extends it, or drop --%s.\n",
+		name, owner, owner, name, name)
 	return true
 }
 

internal/cli/presetcmd.go

@@ -241,8 +241,11 @@ func describePreset(e *preset.Expansion, b budget, out io.Writer) {
 			fmt.Fprintf(out, "  - %s\n", c)
 		}
 	}
-	fmt.Fprintf(out, "\nRun \"tfg preset eject %s\" for the recipe, or \"tfg generate --preset %s\" to produce the files.\n",
-		p.ID, p.ID)
+	// Three roads to the same set, and all three are named: the third
+	// arrived on 2026-09-22 and a setting nobody knows they can reach is a
+	// setting that is not there.
+	fmt.Fprintf(out, "\nRun \"tfg preset eject %s\" for the recipe, \"tfg generate --preset %s\" to produce the files, or write \"extends: preset:%s\" in a recipe of your own.\n",
+		p.ID, p.ID, p.ID)
 }
 
 func presetEject(args []string, out, errOut io.Writer) int {

internal/cli/recipecmd.go

@@ -12,17 +12,28 @@ import (
 
 	"github.com/donislawdev/TestingFilesGenerator/internal/core"
 	"github.com/donislawdev/TestingFilesGenerator/internal/engine"
+	"github.com/donislawdev/TestingFilesGenerator/internal/manifest"
+	"github.com/donislawdev/TestingFilesGenerator/internal/preset"
 	"github.com/donislawdev/TestingFilesGenerator/internal/recipe"
 )
 
-func loadRecipe(path string, errOut io.Writer) (*recipe.Recipe, string, int) {
+// loadRecipe reads a recipe file for a run, through the door that knows
+// presets: a file that builds on one comes back with the preset it built on,
+// so the run can record which numbers were the preset's own.
+//
+// The hash is of the file as written, whether or not it builds on a preset.
+// It answers the question a pipeline asks - was this manifest made from the
+// recipe committed here - and the manifest's preset record, with the tool's
+// version beside it, says the rest. The owner's decision of 2026-09-22, in
+// docs/EXTENDS-WITH-2026-09-22.md section 2.4.
+func loadRecipe(path string, errOut io.Writer) (*preset.Read, string, int) {
 	src, err := readRecipe(path)
 	if err != nil {
 		said, code := recipeReadFailure(path, err)
 		fmt.Fprintf(errOut, "tfg: %s\n", said)
 		return nil, "", code
 	}
-	rec, err := recipe.Parse(src, path)
+	read, err := preset.ReadRecipe(src, path)
 	if err != nil {
 		fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 		return nil, "", classify(err)
@@ -32,7 +43,7 @@ func loadRecipe(path string, errOut io.Writer) (*recipe.Recipe, string, int) {
 		fmt.Fprintf(errOut, "tfg: %s\n", describeError(err))
 		return nil, "", classify(err)
 	}
-	return rec, hash, ExitOK
+	return read, hash, ExitOK
 }
 
 // validate runs the checks a run would run and writes nothing at all, so it
@@ -66,10 +77,11 @@ func validate(ctx context.Context, args []string, out, errOut io.Writer) int {
 		return ExitUsage
 	}
 
-	rec, hash, code := loadRecipeReporting(path, *asJSON, errOut)
+	read, hash, code := loadRecipeReporting(path, *asJSON, errOut)
 	if code != ExitOK {
 		return code
 	}
+	rec := read.Recipe
 
 	// The schema and the semantics both passed. Planning is what proves the
 	// rest: a size below the minimum of its format, a format nobody
@@ -85,18 +97,31 @@ func validate(ctx context.Context, args []string, out, errOut io.Writer) int {
 		return planningRefusal(err, path, *asJSON, errOut)
 	}
 
+	// A file that builds on a preset says so here the way the manifest will
+	// say it, so a pipeline reading this report and one reading the manifest
+	// see one record. The notes go where they go on a run: to a person, on
+	// standard error, because a number the preset invented is something to
+	// know before the files exist as well as after.
+	for _, note := range read.Notes() {
+		fmt.Fprintf(errOut, "note: %s\n", note)
+	}
+
 	if *asJSON {
 		return writeJSON(out, errOut, validateReport{
 			Recipe: path, Valid: true, RecipeHash: hash,
 			Targets: len(rec.Targets), Files: len(planned),
 			TotalBytes: engine.TotalBytes(planned),
+			Preset:     record(read.Expansion),
 			Problems:   []validateProblem{},
 		}, ExitOK)
 	}
 
 	fmt.Fprintf(out, "%s is valid: %s, %s, %s total\n%s\n",
 		path, core.Count(len(rec.Targets), "target", "targets"), core.Count(len(planned), "file", "files"),
 		core.ExactBytes(engine.TotalBytes(planned)), hash)
+	if read.Expansion != nil {
+		fmt.Fprintf(out, "built on preset %s\n", read.Expansion.Preset.ID)
+	}
 	return ExitOK
 }
 
@@ -138,13 +163,17 @@ func planningOptions(rec *recipe.Recipe) engine.Options {
 // rather than as one blob of prose, because RC7 already reports them all at
 // once and a script should not have to split the message back apart.
 type validateReport struct {
-	Recipe     string            `json:"recipe"`
-	Valid      bool              `json:"valid"`
-	RecipeHash string            `json:"recipe_hash,omitempty"`
-	Targets    int               `json:"targets,omitempty"`
-	Files      int               `json:"files,omitempty"`
-	TotalBytes int64             `json:"total_bytes,omitempty"`
-	Problems   []validateProblem `json:"problems"`
+	Recipe     string `json:"recipe"`
+	Valid      bool   `json:"valid"`
+	RecipeHash string `json:"recipe_hash,omitempty"`
+	Targets    int    `json:"targets,omitempty"`
+	Files      int    `json:"files,omitempty"`
+	TotalBytes int64  `json:"total_bytes,omitempty"`
+	// Preset is the preset the recipe builds on, in the shape the manifest
+	// records it - id, settled parameters, and which of them stood in from
+	// their defaults. Absent when the recipe stands alone.
+	Preset   *manifest.Preset  `json:"preset,omitempty"`
+	Problems []validateProblem `json:"problems"`
 }
 
 // validateProblem carries the three parts every refusal in this tool has: what
@@ -212,7 +241,7 @@ func addressOf(err error) string {
 // loadRecipeReporting is loadRecipe with the option of a machine readable
 // refusal. A recipe with five problems has to arrive as five entries, not as
 // one string a script would have to take apart.
-func loadRecipeReporting(path string, asJSON bool, errOut io.Writer) (*recipe.Recipe, string, int) {
+func loadRecipeReporting(path string, asJSON bool, errOut io.Writer) (*preset.Read, string, int) {
 	if !asJSON {
 		return loadRecipe(path, errOut)
 	}
@@ -222,7 +251,7 @@ func loadRecipeReporting(path string, asJSON bool, errOut io.Writer) (*recipe.Re
 		return nil, "", writeJSON(errOut, errOut, validateReport{Recipe: path, Valid: false,
 			Problems: []validateProblem{{What: said}}}, code)
 	}
-	rec, err := recipe.Parse(src, path)
+	read, err := preset.ReadRecipe(src, path)
 	if err != nil {
 		report := validateReport{Recipe: path, Valid: false, Problems: []validateProblem{}}
 		var invalid *recipe.ValidationError
@@ -240,7 +269,7 @@ func loadRecipeReporting(path string, asJSON bool, errOut io.Writer) (*recipe.Re
 		return nil, "", writeJSON(errOut, errOut, validateReport{Recipe: path, Valid: false,
 			Problems: []validateProblem{{What: err.Error()}}}, classify(err))
 	}
-	return rec, hash, ExitOK
+	return read, hash, ExitOK
 }
 
 // recipeCmd groups the operations that work on a recipe file itself rather