# Recipe Book — What's Actually In It (FVW v8 §11)

> **Question**: "I thought there were more than 3 files in a recipe book"
> **Short answer**: You're right. It's **not 3 files, it's 10 items in the `recipe-book/` folder** (3 main + 5 provenance + 2 workflow artefacts). Plus, at the **app level**, an FVW v8 app has **8 mandatory artefacts in 9 folders**, not just 3.
> **Where I went wrong**: in the gallery investigation, I summarised the recipe book as "3-file model (recipe.md + codex.md + rules.md)" — that was just the 3 main files, not the full structure.

---

## 0. TL;DR

The recipe book is **10 items** in `recipe-book/`:

| Group | Count | Files |
|---|---|---|
| **3 main files** | 3 | `recipe.md`, `codex.md`, `rules.md` |
| **5 provenance files** | 5 | `module-meta.json`, `ingredients.json`, `diffs/`, `trace-atlas/`, `dna/` |
| **2 workflow artefacts** | 2 | `plan.md` (per rules.md item 6), `coverage-matrix.md` (per rules.md item 9) |
| **Total** | **10** | |

But the **3 main files** have **internal structure** too:

| Main file | Internal sections / contents |
|---|---|
| `recipe.md` | A. Product Description, B. Structural Contract (incl. Reconstruction Mode Declaration), C. Reconstruction Notes. Maps to R1-R6 + P1-P4 = 10 contract items. |
| `codex.md` | C1 behaviour inventory, C2 state machine, C3 side effects, C4 input validation, C5 failure modes, C6 user simulation, C7 reproducibility, C8 shape matrix (added §30). 8 contract items. |
| `rules.md` | 9 universal things: capability declaration, do-not-proceed rule, contract primacy, anti-drift enforcement (4 checks), user-simulator requirement, plan-as-law, workflow pipeline, user removal, coverage matrix instructions. |

So if you count the *contents* of the 3 main files, you get 10 + 8 + 9 = **27 contract items** in the recipe book. Or, if you just count files, **10 files** in `recipe-book/`.

---

## 1. Where the "3 files" misconception comes from

It's not a misconception — it's a *short summary*. From `fvw v8 §11.0` (line 35-36):

> The v8 Recipe Book has **3 main files** + **5 supporting artefacts** + **2 workflow artefacts** (per §11.9) = **10 items** total.

So §11 itself says "3 main files" + "5 supporting" + "2 workflow" = 10. The "3 main files" is just the most commonly cited subset. The 5 provenance + 2 workflow are less famous.

I oversimplified in my earlier summary. My bad.

---

## 2. The 3 main files, in detail

### 2.1 `recipe.md` — describes the product (engine-agnostic)

3 internal sections, mapping to 10 contract items (R1-R6 + P1-P4):

| Section | What it contains | Contract items |
|---|---|---|
| **A. Product Description** | What the module is, UI structure, layout, wireframes, CSS snapshot, geometry, source-line citations, pedagogical section | R1 (source-line citations), R3 (visual wireframe), R4 (CSS snapshot from source), P1 (pedagogical section) |
| **B. Structural Contract** | Inputs/outputs, interface contract, module boundaries, swap-test instructions, portability contract, **Reconstruction Mode Declaration** (per §33: mode + runtime + file extensions + state management + theme tokens) | R2 (app-shell context), R5 (interface contract), R6 (swap-test), P4 (portability) |
| **C. Reconstruction Notes** | Evidence, coverage matrix entries, visual anchors, behavioural anchors | (organisational; P2 debugging-friendly) |

Plus P3 (versioning structure) lives in `diffs/` provenance, not in `recipe.md` itself.

### 2.2 `codex.md` — describes behaviour (pure, no stack terms)

8 contract items (C1-C8):

| # | Item | What |
|---|---|---|
| C1 | Behaviour inventory from source handlers | What the module does |
| C2 | State machine with transitions | All states + transitions |
| C3 | Side effect list | External side effects |
| C4 | Input validation contract | What's valid input |
| C5 | Failure modes | What can go wrong + recovery |
| C6 | User simulation list | What user actions to test |
| C7 | Reproducibility test | The C7 reproducibility test |
| C8 | Shape matrix (added §30) | Shape-polymorphic surfaces |

C8 was added in v8.0 §30 for shape-polymorphic surfaces. The full C1-C8 contract is declared in §22 (Behaviour-First Codex) — but §30 added C8.

### 2.3 `rules.md` — workflow (9 universal things)

Each module's `rules.md` instantiates these 9 things with module-specific content. The doctrine defines the 9; the module fills them in. The 9 are:

| # | Thing | What it says |
|---|---|---|
| 1 | **Capability declaration** | I CAN: ...; I CANNOT: ...; External validation required for: ... Includes the Reconstruction Mode Declaration (per §33). |
| 2 | **Do-not-proceed rule** | If [check] fails, stop and write blocker.md. Don't skip, work around, or guess. |
| 3 | **Contract primacy** | This module's contract is `recipe.md` + `codex.md`. Scaffolding files are NOT the contract. If contract and source disagree, fix the contract. |
| 4 | **Anti-drift enforcement (4 numbered checks)** | For this module: (1) Recipe → Source Check, (2) Visual Diff Check, (3) Behavioural Check, (4) Contract Check. If any fails, STOP. |
| 5 | **User-simulator requirement** | User actions to simulate (per C6 in codex.md). I CAN simulate because: ... OR I CANNOT — request external simulator. |
| 6 | **Plan-as-law doctrine** | Plan is at `recipe-book/plan.md`. Atomic steps, capability per step, expected output per step, fallback per step. Follow the plan exactly; if a step is wrong, update the plan, not the implementation. |
| 7 | **Workflow pipeline** | At every atomic step: read the relevant section, execute, run the 4 anti-drift checks, continue or STOP. |
| 8 | **User removal** | User MUST NOT be required to check fidelity, compare visuals, detect drift, validate behaviour, enforce contract. Autonomous or blocker.md. |
| 9 | **Coverage matrix instructions** | Coverage matrix at `recipe-book/coverage-matrix.md`. Columns: source feature, source-line evidence, recipe/codex claim, implementation status, test status. Empty cells = FAIL. |

---

## 3. The 5 provenance files (in `recipe-book/`)

These are NOT the contract. They're scaffolding for governance, traceability, and gallery integration.

| File | Purpose |
|---|---|
| `module-meta.json` | Module identity (`name`, `version`, `description`), `category` (e.g. "core-panels", "chrome-component"), `gallery_linkage` (which gallery entries reference this module), `isolation_class` (per §11.10 — A/B/C/D) |
| `ingredients.json` | Provenance scaffolding: data shapes (TypeScript interfaces, JSON schemas), dependencies (npm packages, internal modules), environment requirements (Node version, browser support) |
| `diffs/` | Version diffs — one file per version transition (e.g. `v0.4.0-to-v0.5.0.md`). Tracks what changed in the module. P3 versioning structure. |
| `trace-atlas/` | Lineage, forks, shadows. `lineage.json` (origin, created_by, created, supersedes, extends), `forks/` (one folder per fork), `shadows/` (one folder per shadow = snapshot of the module at a point in time) |
| `dna/` | DNA artefacts: the module's identity hash, cross-references to constitutional basis, invariants (things that must always be true) |

---

## 4. The 2 workflow artefacts (in `recipe-book/`)

These are referenced from `rules.md` but live as their own files:

| File | Purpose | Referenced by |
|---|---|---|
| `plan.md` | The atomic-step plan for this module. Per-step capability, expected output, fallback. | rules.md item 6 (Plan-as-law) |
| `coverage-matrix.md` | The source-feature-to-implementation-to-test status matrix. Empty cells = FAIL. | rules.md item 9 (Coverage matrix instructions) |

So the workflow chain is:
- `rules.md` says "follow the plan" → reads `plan.md`
- `rules.md` says "update the matrix" → writes to `coverage-matrix.md`

---

## 5. The 8 mandatory artefacts at the **app level** (FVW v8 §1.1, §2)

A separate (and bigger) concept: an FVW v8 app has **8 mandatory artefacts in 9 folders** (the 9th folder is `shadow/` for reversibility, which is not an "artefact" per se).

```
my-freshvibe-app/
├── app-pact/            (Artefact 1: rules, constraints, guarantees)
├── app-codex/           (Artefact 2: UI + behaviour structure)
├── app-fragments/       (Artefact 3: modular building blocks)
├── app-dna/             (Artefact 4: identity, lineage, versioning)
├── app-trace-atlas/     (Artefact 5: UI → behaviour → module → file → test)
├── app-overlays/        (Artefact 6: customisation layers)
├── app-vp/              (Artefact 7: Validity + Protection tests)
├── app-recipe/          (Artefact 8: the portable package — contains recipe-book/)
├── shadow/              (reversibility — for old code restoration)
└── src/                 (the rendered app)
```

So the 8 artefacts at the app level correspond to 9 folders. The 8th artefact (`app-recipe/`) **contains the recipe book** (the 10 items from §2 above).

The mandatory content per artefact:

| # | Folder | Required content |
|---|---|---|
| 1 | `app-pact/` | `app-pact.md` + `invariants.md` + `anti-drift.md` (or reference to §08) |
| 2 | `app-codex/` | `app-codex.md` + `surfaces.md` + `behaviours.md` + per-surface/per-behaviour files |
| 3 | `app-fragments/` | `fragments.md` index + per-fragment folders |
| 4 | `app-dna/` | `app.dna.json` (v0.1.0, FVW v4 schema) |
| 5 | `app-trace-atlas/` | `atlas.json` (one entry per UI surface) |
| 6 | `app-overlays/` | `overlays.md` (placeholder when 0 overlays exist) |
| 7 | `app-vp/` | Validity + Protection tests + API contracts |
| 8 | `app-recipe/` | `recipe.md` + `metadata.json` + `snapshot/` |

---

## 6. The 4 isolation classes (FVW v8 §11.10)

Each module has an isolation class A/B/C/D (declared in `module-meta.json`). Per `rules.md` item 1 (capability declaration), the class determines what the implementer can do autonomously vs what needs external validation. The class also affects which of the 4 anti-drift checks apply.

(Not exploring the A/B/C/D details here — that's a separate read.)

---

## 7. What the gallery's `ai-toast` actually shipped

For comparison, here's what `ai-toast` (the only gallery module that's actually been extracted) put in its `recipe-book/`:

```
modules/ai-toast/recipe-book/
├── codex.md
├── recipe.md
└── rules.md
```

**Only 3 files.** The 5 provenance files (`module-meta.json`, `ingredients.json`, `diffs/`, `trace-atlas/`, `dna/`) are **NOT in `recipe-book/`** for ai-toast — they live at the module root:

```
modules/ai-toast/
├── module.json          (constitutional, not in recipe-book/)
├── module-meta.json     (provenance, at root, not in recipe-book/)
├── facets.json          (visibility slices, at root, not in recipe-book/)
├── package.json         (npm metadata, at root)
├── tsconfig.json
├── node_modules →
├── recipe-book/
│   ├── recipe.md
│   ├── codex.md
│   └── rules.md
├── src/
│   ├── .private/        (empty)
│   └── default/
└── test-cases/
    └── no-throw.test.ts
```

So `ai-toast` shipped **8 things total**: 3 recipe-book files + 5 root-level metadata files. Missing from the FVW v8 §11 spec: `ingredients.json`, `diffs/`, `trace-atlas/` (folder), `dna/` (folder), `plan.md`, `coverage-matrix.md`. That's 6 of the 10 §11 items missing in the only shipped example.

The shipped `ai-toast` is a **minimal** v8 recipe book — it has the 3 main files but skips the 5 provenance + 2 workflow artefacts. This is consistent with `STATUS.md` saying the module is "sourced from `@freshvibe/ai-shell` v0.3.0 (with 0 modifications)" — i.e. it was a verbatim lift, not a v8 recipe book reconstruction. The full v8 10-item structure would be needed if/when someone rebuilds ai-toast from a recipe book rather than copying source.

---

## 8. The numbers, at a glance

| Count | What |
|---|---|
| **3 main files** | `recipe.md`, `codex.md`, `rules.md` |
| **5 provenance files** | `module-meta.json`, `ingredients.json`, `diffs/`, `trace-atlas/`, `dna/` |
| **2 workflow artefacts** | `plan.md`, `coverage-matrix.md` |
| **10 items total** | in `recipe-book/` |
| **10 contract items in `recipe.md`** | R1-R6 + P1-P4 |
| **8 contract items in `codex.md`** | C1-C8 (C8 added §30) |
| **9 universal things in `rules.md`** | capability + do-not-proceed + contract primacy + anti-drift + user-simulator + plan-as-law + workflow pipeline + user removal + coverage matrix |
| **27 contract items** | across the 3 main files |
| **8 mandatory app artefacts** | `app-pact` + `app-codex` + `app-fragments` + `app-dna` + `app-trace-atlas` + `app-overlays` + `app-vp` + `app-recipe` |
| **9 top-level folders** | the 8 artefacts + `shadow/` for reversibility |
| **4 isolation classes** | A, B, C, D (per module) |

---

## 9. Summary

You were right. The "3 files" summary I gave you before was an oversimplification. The full picture is:

- **Recipe book at module level**: 10 items in `recipe-book/` (3 main + 5 provenance + 2 workflow)
- **App at FVW v8 level**: 8 mandatory artefacts in 9 folders
- **27 contract items** distributed across the 3 main recipe-book files
- **4 isolation classes** for module autonomy levels
- **The shipped `ai-toast` only has 3 files** (the minimal subset), missing 6 of the 10 items

Where the "3 files" framing comes from: §11.0 says "**3 main files** + 5 supporting artefacts + 2 workflow artefacts = 10 items". The 3 main files (`recipe.md`, `codex.md`, `rules.md`) are the most-cited subset because they're the *contract* — the other 7 are scaffolding/provenance/workflow.

So the doctrine does say "3 main files" — but that's a *subset* of the recipe book, not the whole thing. The whole thing is 10.

---

*Read from `avidtech6/freshvibestudio/pact/freshvibe-way-v8/11-recipe-book.md` (495 lines, the unified §11) and `02-folder-layout.md` (the 8 mandatory artefacts at app level). Cross-checked with the shipped `ai-toast/recipe-book/` (3 files) and `modules/ai-toast/` root (8 files total).*