# Instructions for an agent: turn a recipe or process into a Sequence file

You are given a document, a URL or plain text that describes a recipe or a multi-step process. Your job is to produce a `.seq` file that the **Sequence** Android app imports without errors, and that runs well: the steps are in a sensible order, anything that needs waiting is a timer, and images and video links are included only where they help and are allowed.

The app is offline-first and the import is strict. A file that fails validation is refused with an error, not repaired. Read sections 2 to 5 before writing anything.

This guide is published by FlashAPEX, who make Sequence, at https://flashapex.co.uk/sequence/sequence-ai-guide.md. It describes the file format of the current version of the app; if the person gives you an older copy, prefer that address.

---

## 1. Workflow

1. **Read the source completely.** If it is a URL, fetch it. If it is a page with several recipes or alternatives, pick the one the person asked for; if unclear, ask.
2. **Extract the process** as an ordered list of actions. Note, for each: the action, quantities and temperatures, anything the person must have to hand, anything dangerous, anything that needs time (waiting, baking, curing, resting, soaking) and whether the person must wait for it or can carry on.
3. **Decide the structure** (section 4): steps, timers, checklists, notes, tools, warnings, links, images.
4. **Write `sequence.json`** (section 2 and 3).
5. **Collect images only if allowed** (section 6). If any are included, build a ZIP package; otherwise write plain JSON.
6. **Validate with the checklist in section 8** (or run the script in section 9), fix, and only then deliver.
7. **Tell the person what you did and what you left out** (which images or timers you did not include and why, and anything you inferred rather than read).

Never invent facts. Do not make up quantities, temperatures, times, tool names or links that the source does not give. If the source is vague ("bake until golden"), either write exactly that or, only if it is a normal wait, give a time and say so in the step notes ("about 25 minutes, until golden"). Mark anything you inferred in your final message.

---

## 2. File format

A sequence is one JSON object. Property names are camelCase; enum values are lower-case strings. Use UTF-8 without a BOM, and keep real characters (`°`, `é`, `½`) rather than escapes.

```json
{
  "format": "sequence",
  "schemaVersion": 2,
  "id": "9b2f6c1e-5d3a-4c7e-8a41-0f6d2b7c9e10",
  "title": "Sunday roast",
  "description": "Everything out of the oven together",
  "category": "cooking",
  "tags": [],
  "createdUtc": "2026-10-02T10:00:00Z",
  "modifiedUtc": "2026-10-02T10:00:00Z",
  "steps": [ ],
  "groups": [ ]
}
```

| Field | Rules |
|---|---|
| `format` | Always `"sequence"`. |
| `schemaVersion` | Always `2` (current). |
| `id` | A new random GUID (lower-case, hyphenated). |
| `title` | Required, not blank. Short and specific (under about 80 characters). |
| `description` | Optional, one or two sentences. Leave the property out if there is nothing useful. |
| `category` | Optional. One of `cooking`, `repair`, `maintenance`, `cleaning`, `assembly`, `setup`, `fitness`, `other`. Use the lower-case key exactly. Leave it out if none fits well; use `other` only for a genuine "something else". The app keeps any other value (up to 40 characters) without complaint, but only these eight are categories it offers, so never make one up. |
| `tags` | Always include as `[]` (the app does not use it for filing any more). |
| `createdUtc`, `modifiedUtc` | ISO 8601 UTC with a trailing `Z`, e.g. `2026-10-02T10:00:00Z`. Use the current time for both. |
| `steps` | At least one step. |
| `groups` | Always include; `[]` if you have none. |
| `cover` | Optional image (section 6). Leave out if none. |
| `loopable` | Optional. `true` when the whole sequence is naturally done several times in a row (exercise intervals, coats of paint, batches); the app then asks how many times (up to 20) when it starts, for people with Sequence Pro. Leave it out otherwise; never write `false`. For a few steps done once per wheel or room, use a repeat block instead. |

Do not add folder information. Folders are the person's own filing on their device and are never part of a sequence file.

### Step

```json
{
  "id": "…guid…",
  "title": "Preheat the oven to 200°C",
  "notes": "Fan oven. Put the middle shelf in first.",
  "checklist": [],
  "requireChecklist": false,
  "gate": { "durationSeconds": 900, "blocking": true, "autoStart": true },
  "cues": [],
  "background": [],
  "tools": ["Roasting tin", "Oven gloves"],
  "callouts": [ { "id": "…guid…", "kind": "warning", "text": "The tin will be very hot." } ],
  "links": [ { "id": "…guid…", "title": "How to carve a chicken (video)", "url": "https://example.com/carve" } ],
  "pictures": [ { "id": "…guid…", "path": "media/<id>.jpg", "caption": "Shelf position" } ]
}
```

Always include `id`, `title`, `checklist`, `requireChecklist`, `cues` and `background` (use `[]` and `false` when empty). Everything else is optional **and must be left out entirely when empty** (do not write `"tools": []`, `"gate": null` or `"notes": ""`).

| Field | Meaning and limits |
|---|---|
| `title` | The action, imperative, short: "Chicken in", "Peel the adhesive strips". Required. |
| `notes` | One short paragraph of detail: quantities, how to tell it is done. Plain text. |
| `checklist` | `[{ "id", "text" }]`: things to check or do while carrying out this step ("Pedal firm", "No leaks", "Seams sealed"). Use for lists of three or more discrete items, not for prose. **Never put ingredients, parts or materials here**: they go in `tools` (section 4). |
| `requireChecklist` | `true` only if every item must be ticked before the step can be completed, and only when the checklist is not empty (`true` with an empty checklist imports, but with a warning). |
| `gate` | A timer on this step that runs while it is current (section 3). |
| `cues` | Timers that hold a **later** step (section 3). |
| `background` | Labelled timers that start when the step is completed (section 3). |
| `tools` | The "Items required" chips: equipment, ingredients, parts and materials for this step, one per entry, with the quantity for ingredients and parts ("500 g chicken breast", "8 tortillas"). The app gathers every step's tools into the Overview's "Items required" list, which the person ticks off before starting; checklist items are not included in it. At most 12, each at most 80 characters. |
| `callouts` | Notes and warnings shown as cards. `kind` is `"info"` or `"warning"`. At most 5, each text at most 300 characters. Use `warning` for anything unsafe, irreversible or easy to get wrong (hot, sharp, allergen, "do not skip"); `info` for tips. |
| `links` | Web links that open in the browser. At most 10 per step. See section 7. |
| `pictures` | Images for the step. At most 6 per step. See section 6. |
| `estimatedSeconds` | About how long the person spends doing the step, **not counting its timers**, in seconds (between 1 and 604800). Include it whenever you can judge it ("Peel the potatoes": `300`); leave it out when you can't. The app adds the estimates and the timers up to show how long the whole sequence takes, and says "At least" while some steps have none. |

### Timer shapes

```json
"gate":       { "durationSeconds": 900, "blocking": true, "autoStart": true }
"cues":       [ { "id": "…guid…", "targetStepId": "…guid of a LATER step…", "delaySeconds": 1200, "anchor": "complete" } ]
"background": [ { "id": "…guid…", "label": "Chicken ready", "durationSeconds": 3600 } ]
```

`anchor` is `"complete"` (the default; the cue starts when this step is completed) or `"start"` (it starts when this step becomes current).

Two optional fields (leave them out unless they are needed):

- `"alert"` on a gate, a cue or a background timer: how it sounds when it ends. `"chime"` is one short sound, `"silent"` is a notification with no sound. Leave it out for the default alarm, which rings until the person answers it. Do not write `"alert": "alarm"`.
- `"advance": true` on a gate: when the gate ends, the step completes itself and the next step starts (it never ends the run: the last step waits for Finish). Use it for routines that run by the clock, together with `"autoStart": true` on every gate and usually `"alert": "chime"`. A step with `"requireChecklist": true` does not move on until its checklist is ticked, so do not combine the two.

The file only says *how* a timer sounds. Which alarm or chime sound plays is a setting on the person's phone: there is no field for a sound file, and nothing to embed.

### Groups ("finish together")

```json
{ "id": "…guid…", "name": "Oven", "members": [
  { "stepId": "…guid…", "label": "Chicken",  "durationSeconds": 3600 },
  { "stepId": "…guid…", "label": "Potatoes", "durationSeconds": 2400 },
  { "stepId": "…guid…", "label": "Veg",      "durationSeconds": 1200 } ] }
```

See section 3 for when to use one.

### Repeats (optional)

When the same steps are done once for each of several things (each wheel, each room), write them once and add a repeat block. Leave `repeats` out when there are none.

```json
"repeats": [ { "id": "…guid…", "firstStepId": "…guid…", "lastStepId": "…guid…", "items": ["RR", "LR", "RF", "LF"] } ]
```

The steps from `firstStepId` to `lastStepId` (in file order, inclusive; may be the same step) run once per item. Write `{item}` in a step's title, notes, checklist, tools, callouts or link titles where the item belongs ("Bleed the {item} caliper"); a title without `{item}` gets " (RR)" added. A cue inside the block that targets a step in the same block holds that round's copy. Rules: 2 to 20 items, each 1 to 40 characters; blocks must not overlap; a repeated step must not be in a group; with repeats written out the sequence has at most 300 steps.

### Identifiers

Every `id` in the file must be a **unique** lower-case GUID: steps, checklist items, cues, background timers, groups, callouts, links, pictures and the cover. A duplicate anywhere in the file is an error. Generate them with a proper GUID generator (never hand-write patterns like `…0001`). References (`targetStepId`, a group member's `stepId`) must be the `id` of a step in this file.

---

## 3. Choosing the right timer

Time is the main reason this app exists. Get it right.

| The source says | Use | Why |
|---|---|---|
| "Preheat the oven for 15 minutes" and nothing else can sensibly happen until then | **Gate**, `blocking: true`, `autoStart: true` on that step | The step cannot be completed until the time is up. |
| "Leave to cool for 10 minutes" / "let the glue cure" as a step the person waits through | **Gate** on that step. `blocking: true` if they truly must wait. | Same. |
| A time that is a useful reminder but the person may continue (stir halfway, check progress) | Gate with `blocking: false` | Alerts without blocking. |
| "Put the chicken in (1 hour). While it cooks, do other things." | **Background** timer on the "chicken in" step: `label: "Chicken ready"`, `durationSeconds: 3600` | Starts when the step is completed; blocks nothing; alerts with its label. |
| "Add the potatoes 20 minutes after the chicken goes in" | **Cue** on the chicken step targeting the potatoes step, `delaySeconds: 1200`, `anchor: "complete"` | Holds the later step until its time. |
| Several things must all be ready at the same time but take different times (60, 40 and 20 minutes) | A **group** (below) | The app computes the cues and timers for you. |
| An exercise routine or anything timed step after step ("30 s squats, 15 s rest, …") | A **gate** on each step with `blocking: true`, `autoStart: true`, `"advance": true` and `"alert": "chime"` | Each step chimes and moves on by itself. |
| Work that can be done during a wait ("prepare the chicken while the oven heats", "change the filter while the oil drains") | Short work: say so in the **notes** of the step with the wait. Longer work: its own step, with a **cue** from the step that starts the wait holding the step that must wait | The person uses the waiting time, and the app still stops them going on too early. See "Use the waiting time" in section 4. |

Rules the validator enforces:

- Every duration is a whole number of **seconds**, at least 1 and at most 604,800 (7 days). Convert: 1 h 15 min = 4500.
- A cue's target must be a step **after** the step that owns the cue.
- A blocking gate on the **last** step is only a warning, but avoid it.

### Using a group

Use a group only when several items are cooked or processed in parallel and should finish together. The author gives each member's own duration and the app turns it into cues and background timers.

- **Longest first in step order.** The longest member's step comes first in `steps`, then the next longest, and so on; equal durations may be in either order. A group where a member's step comes after a shorter member's step is an error. List the `members` in that same order too, so the file reads naturally (the app checks the order of the steps, not of the list).
- Each member's `stepId` must be a step in the file, and a step can be in **only one** group.
- **Do not also write cues or background timers for group members.** The group already creates them.
- **Hold the step after the group until everything is ready.** Otherwise the person reaches "Take it all out" while the food is still cooking. Add one cue from the **last** member's step (the shortest) to the step after the group, with that member's duration and `"alert": "silent"` (the group already sounds an alert when each item is ready).
- Use two or more members (the app does not enforce a minimum, but a group of one does nothing useful).

If the source only gives one long cooking time, do not use a group; use a background timer.

### What not to do

- Do not turn every time mention into a timer. A timer should be something the person needs to be told about.
- Do not guess times the source does not give.
- Do not create gates on steps that are short actions with no waiting.

---

## 4. Turning a document into steps

- **One action per step.** If a source sentence contains "and then", it is probably two steps. If two actions always happen together (stir and season), keep them as one.
- **Order matters.** Use the order the source implies. Steps that happen in parallel are written in the order they start; use cues/groups to express the overlap.
- **Ingredients go in `tools`, not a checklist.** For a recipe or any cooking sequence, every ingredient goes in `tools`, one entry each with its quantity ("500 g chicken breast", "1 red pepper", "A little oil"), alongside the equipment. Do not put ingredients in a `checklist`: the Overview's "Items required" list, which the person ticks off before starting and which shows "Ready to start" once everything is ticked, is built only from `tools`, so ingredients in a checklist never appear there. The same goes for parts and materials in any other kind of sequence (screws, dowels, brake fluid).
  - Put each ingredient on the step that first uses it. If the source lists them all up front, a first "Gather the ingredients" step may hold them in its `tools` (with an empty `checklist`).
  - At most 12 tools per step: if a recipe needs more on one step, split them across steps by where they are used, or into two gather steps ("Gather the dry ingredients", "Gather the wet ingredients").
  - Name an ingredient once, on its first step, with the total quantity. The same name on several steps is listed once, but a name with a different quantity ("100 g butter" and "50 g butter") is listed twice.
- **Put the right information in the right place.**
  - What to do, briefly: `title`.
  - How, how much, how to tell it is done: `notes`.
  - Danger or a common mistake: a `warning` callout.
  - A helpful extra: an `info` callout.
  - Equipment, ingredients, parts and materials needed for the step: `tools`.
  - Things to check while doing the step: `checklist`.
  - Further reading or a video: `links`.
- **Keep it scannable.** Step titles of two to six words. Notes of one to three sentences. The person reads this with their hands full, often with the phone propped up.

### Structure and wording

Write the sequence the way a good teacher would talk someone through the job beside them. Before writing JSON, list the steps in order with what the person does, what they wait for and what they can do while waiting; then check the list against these rules.

- **Each title is the action that starts the step**, beginning with a verb: "Turn the oven on to 200 °C", "Put the chicken in", "Drain the oil". Not a noun or a state ("Oven", "Preheating", "Chicken").
- **Use the waiting time.** When a step starts a wait (an oven heating up, oil draining, filler drying), say what to do during it:
  - If the work is short and fits inside the wait, put it in that step's notes, starting "While it …": *Turn the oven on to 200 °C* — "While it heats up, get the chicken ready: pat it dry, rub it with oil, season it and put it in the roasting tin." with a 15-minute blocking gate.
  - If the work is a job of its own, make it the next step, and hold the step that must wait with a **cue** from the step that started the wait: *Drain the oil* (cue: hold *Refit the sump plug* for 10 minutes) → *Change the filter* → *Refit the sump plug*.
  - The step that ends the wait comes next and says so: "Put the chicken in".
- **Prepare just before it is needed.** A preparation step comes right before the step that uses it, timed to fit a hold where possible: *Peel and par-boil the potatoes* sits between *Put the chicken in* and *Put the potatoes in*, during the 35 minutes the potatoes are held.
- **One wait per step.** A step should not ask the person to do something, wait, then do something else, unless the second part is tiny. Split it, or put the waiting into its own step ("Let it stand, then mix again").
- **Say how to tell it's done**, with a sign the person can see, feel or measure: "until the juices run clear, or 75 °C in the thickest part", "when a fingertip leaves only a slight mark". Give a time as well when the source has one.
- **Be concrete.** "Boil for 8 minutes", "a band about 5 cm wide", "about 7 Nm". Avoid "some", "a while", "as needed" unless the source gives nothing better.
- **Safety where it matters.** A `warning` callout for heat, sharp edges, chemicals, electricity, lifting a vehicle, or anything that cannot be undone. Put it on the step where the danger is, not at the start.
- **End with the finished result.** The last step is the outcome ("Carve and serve", "Test the pedal"), with a checklist of the final checks when getting it wrong is dangerous or costly (set `requireChecklist` for safety checks). Disposal or clean-up goes in that step's notes or a short step of its own.
- **Repeat, don't copy.** When the same steps are done for each of several things (each wheel, each coat, each fold), write them once and add a repeat block rather than near-identical steps.
- **Times for every step.** Give each step an `estimatedSeconds` for the work itself, not counting its timers, whenever you can judge it (section 2). The app adds them up with the timers to show how long the whole job takes and when it will be done.
- **Oven temperatures:** for a conventional oven temperature, give the fan and gas mark equivalents in the title or notes, as UK recipes do: "Turn the oven on to 200 °C" with notes "Fan 180 °C, gas mark 6." Fan is 20 °C lower. Gas marks: 140 °C = 1, 150 = 2, 160–170 = 3, 180 = 4, 190 = 5, 200 = 6, 220 = 7, 230 = 8, 240 = 9.
- **Words to use.** Second person and imperative ("Turn", "Put", "Leave"). Plain everyday words, short sentences, no filler ("Now you will want to…"). Write numbers as digits with their units (`°C`, `g`, `min`).
- **Keep units as the source gives them.** Add a conversion only if the source gives it, apart from oven temperatures (fan and gas mark, above). Use real symbols (`°C`, `½`).
- **Do not copy long passages.** Summarise the method in your own words. Keep the source's title if it is the name of the thing being made.
- **Language:** write in the language of the source.
- **Size:** most sequences are 5 to 30 steps. If the source is far longer, tell the person and offer to split it into several sequences.
- **Ten steps in the free version.** The free version of Sequence (Lite) shows and runs only the first 10 steps of a file like this one (a repeat counts once per item); Sequence Pro runs any length. If the job fits in 10 steps without cramming two actions into one, keep it to 10. If it needs more, write it properly anyway and mention in your final message that it has more than 10 steps, so the person knows Lite will stop after step 10 (or can ask you to split it into two sequences of 10 or fewer).

---

## 5. Worked example (plain JSON, no images)

Recipe: "Roast chicken, potatoes and veg for 4. Heat the oven to 200°C (fan 180°C, gas 6), about 15 min. Prepare the chicken while it heats. Chicken 1.5 kg, 80 min; potatoes par-boiled, then 45 min; carrots and parsnips 30 min. Rest the chicken 10 min, then carve."

```json
{
  "format": "sequence",
  "schemaVersion": 2,
  "id": "9b2f6c1e-5d3a-4c7e-8a41-0f6d2b7c9e10",
  "title": "Roast chicken dinner",
  "description": "Chicken, potatoes and veg ready together, for 4.",
  "category": "cooking",
  "tags": [],
  "createdUtc": "2026-10-02T10:00:00Z",
  "modifiedUtc": "2026-10-02T10:00:00Z",
  "steps": [
    { "id": "4a1c0b52-7d0e-4f0a-9d63-1c2e8a5b7f01", "title": "Turn the oven on to 200 °C",
      "notes": "Fan 180 °C, gas mark 6. While it heats up, get the chicken ready: pat it dry, rub it with oil, season it and put it in the roasting tin.",
      "checklist": [], "requireChecklist": false,
      "gate": { "durationSeconds": 900, "blocking": true, "autoStart": true },
      "cues": [], "background": [],
      "tools": ["1.5 kg whole chicken", "Roasting tin", "Olive oil", "Salt and pepper"],
      "estimatedSeconds": 600 },
    { "id": "6c3e2d74-9f20-4b2c-9f85-3e4a0c7d9b03", "title": "Put the chicken in",
      "notes": "Middle shelf.",
      "checklist": [], "requireChecklist": false, "cues": [], "background": [],
      "estimatedSeconds": 120 },
    { "id": "c2948dda-f586-4182-b5eb-94a062d3f109", "title": "Peel and par-boil the potatoes",
      "notes": "Cut into even chunks, boil for 8 minutes, drain and shake to rough up the edges. While they boil, heat the vegetable oil in a second tin in the oven.",
      "checklist": [], "requireChecklist": false, "cues": [], "background": [],
      "tools": ["1 kg roasting potatoes", "Large saucepan", "Colander", "3 tbsp vegetable oil", "Second roasting tin"],
      "estimatedSeconds": 1200 },
    { "id": "7d4f3e85-a031-4c3d-a096-4f5b1d8eac04", "title": "Put the potatoes in",
      "notes": "Tip them into the hot oil, turn them over and put them on the top shelf.",
      "checklist": [], "requireChecklist": false, "cues": [], "background": [],
      "callouts": [ { "id": "5b2d1c63-8e1f-4a1b-8e74-2d3f9b6c8a02", "kind": "warning", "text": "The oil is very hot: use oven gloves and tip the potatoes in away from you." } ],
      "estimatedSeconds": 300 },
    { "id": "d3a59eeb-0697-4293-86fc-a5b173e4a20a", "title": "Prepare the veg",
      "notes": "Peel the carrots and parsnips, cut them into batons, toss them in oil and season.",
      "checklist": [], "requireChecklist": false, "cues": [], "background": [],
      "tools": ["4 carrots", "3 parsnips", "Baking tray"],
      "estimatedSeconds": 600 },
    { "id": "8e504f96-b142-4d4e-b1a7-506c2e9fbd05", "title": "Put the veg in",
      "checklist": [], "requireChecklist": false,
      "cues": [ { "id": "e4b6affc-17a8-43a4-97ad-b6c284f5b30b", "targetStepId": "9f615aa7-c253-4e5f-82b8-617d3fa0ce06", "delaySeconds": 1800, "anchor": "complete", "alert": "silent" } ],
      "background": [],
      "estimatedSeconds": 60 },
    { "id": "9f615aa7-c253-4e5f-82b8-617d3fa0ce06", "title": "Rest the chicken",
      "notes": "Everything is ready: the chicken is done when the juices run clear. Cover it loosely with foil, and keep the potatoes and veg warm in the turned-off oven.",
      "checklist": [], "requireChecklist": false,
      "gate": { "durationSeconds": 600, "blocking": true, "autoStart": true },
      "cues": [], "background": [],
      "tools": ["Foil"],
      "estimatedSeconds": 300 },
    { "id": "a0726bb8-d364-4f60-93c9-728e40b1df07", "title": "Carve and serve",
      "checklist": [], "requireChecklist": false, "cues": [], "background": [],
      "tools": ["Carving knife and board"],
      "estimatedSeconds": 600 }
  ],
  "groups": [
    { "id": "b1837cc9-e475-4071-a4da-839f51c2e008", "name": "Oven", "members": [
      { "stepId": "6c3e2d74-9f20-4b2c-9f85-3e4a0c7d9b03", "label": "Chicken",  "durationSeconds": 4800 },
      { "stepId": "7d4f3e85-a031-4c3d-a096-4f5b1d8eac04", "label": "Potatoes", "durationSeconds": 2700 },
      { "stepId": "8e504f96-b142-4d4e-b1a7-506c2e9fbd05", "label": "Veg",      "durationSeconds": 1800 } ] }
  ]
}
```

Notes on the example:

- The first step's title is the action ("Turn the oven on"), and its notes use the 15-minute wait to prepare the chicken.
- The potatoes and veg are prepared in their own steps just before they go in, inside the time the group holds them back.
- No cues or background timers on the three group steps (the group makes them); the longest member is the first of the three.
- The one hand-written cue holds "Rest the chicken" until the veg (the last item in) is ready, silently, because the group already alerts.
- Every step has an `estimatedSeconds`; the timers are not counted in it.
- The gate on "Rest the chicken" is not on the last step, and the last step is the finished result.

---

## 6. Images

Images are optional. Include them only when they genuinely help (where a part is, what "done" looks like) and only when you are **allowed** to.

### Permission and sourcing

- Use an image only if (a) the person supplied it, (b) it is in the document you were given and the person is clearly entitled to reuse it, or (c) it is clearly licensed for reuse (public domain, CC0, or a Creative Commons licence you can comply with). Do not take images from a website just because you can fetch them. When in doubt, **do not embed it**: put a link to the page in the step's `links` instead (section 7).
- Never create misleading images or pass off a generated image as a photo of the real thing.
- If you embed a licensed image, put the attribution in its `caption` ("Photo: A. Name, CC BY 4.0") and mention it in your final message.
- Never embed anything with a person's face or private information you were not given permission to share.

### Format and limits

| Rule | Value |
|---|---|
| Formats | JPEG (`.jpg`; `.jpeg` is also accepted), PNG (`.png`) or WebP (`.webp`). The app identifies the type by the file's first bytes, so a mislabelled file is refused. Convert anything else (GIF, SVG, AVIF, HEIC) first. |
| Pixels | At most 8,192 on either side and about 16.7 megapixels (4096 × 4096) in all; a bigger picture is refused even if its file is small. |
| Size of each image | At most 4 MB. Resize so the longest edge is about 1600 px and save JPEG at quality about 80 for photos; this normally gives 100 to 400 KB. |
| Per step | At most 6. |
| Per sequence | At most 40 including the cover. Keep the images under 15 MB in total: that is the most the app lets a sequence hold when it is edited, so a bigger one imports but the person cannot add any more pictures to it. |
| Package | At most 25 MB in total; a larger file is refused. |
| Without images | A plain JSON `.seq` may be at most 5 MB (far more than any real sequence needs). |
| Caption | Optional, at most 120 characters. Describe what is shown ("Connector location"), not "image 1". |
| Metadata | Strip EXIF (especially GPS location) when you re-encode. |

### How to include an image

1. Give it a new GUID `imageId`.
2. Add to the step: `{ "id": "<imageId>", "path": "media/<imageId>.<ext>", "caption": "…" }` under `pictures`. `<ext>` is `jpg`, `png` or `webp` and must match the real format.
3. For a **cover** (the picture on the Library row; optional, one per sequence), add `"cover": { "id": "<imageId>", "path": "media/<imageId>.<ext>" }` at the top level. Use a clear, representative picture.
4. Put the image bytes in the package at exactly that path.

`path` only names the entry inside the package. The app finds its own copy by id and never opens a path from a file, so the path must follow the pattern exactly: `media/`, then ASCII letters, digits, `-`, `_`, `.` only, ending in `.jpg`, `.jpeg`, `.png` or `.webp`, and at most 120 characters in all.

### The package

If the sequence has **any** image, the `.seq` must be a ZIP containing:

```
sequence.json                 the JSON described above (UTF-8, no BOM)
media/<imageId>.<ext>         one entry per image
```

- The app **refuses** a ZIP containing any entry other than `sequence.json` and correctly named `media/<name>.<ext>` files (plain folder entries are ignored). Never add a README, thumbnails or other files, and never use `..` or absolute paths. At most 49 entries.
- Every image referenced in `sequence.json` should be present in the ZIP (a missing one only produces a warning and the image will not show), and every file in `media/` should be referenced (the importer does not check this, but unreferenced files waste space).
- Store images uncompressed (they are already compressed); the JSON can be deflated.
- A sequence **without** images is **not** a ZIP: write plain JSON.

Name the file after the title with only letters, digits, spaces, `-` and `_` (for example `Roast chicken dinner.seq`). Use the `.seq` extension for both forms.

---

## 7. Video and other links

The app does not play video itself, and has no internet access of its own. Videos and web pages are included as **links**, which open in the person's browser or video app, so they need a connection. Say so in the title if it helps.

- Use `links` on the step the video explains: `{ "id", "title", "url" }`.
- `url` must start with `http://` or `https://`, have a host, contain no username or password, and be at most 2,048 characters. Prefer `https://`. Anything else (other schemes, `file:`, `javascript:`, bare text) is a validation error.
- `title` at most 100 characters; say what it is: "Video: removing the back cover", "Manufacturer's torque table (PDF)".
- At most 10 links per step. Prefer one or two good ones.
- **Only link to things you have seen.** Never construct or guess a URL. Use a URL from the source document or one you opened and confirmed is the right content. If the source mentions a video without a link, do not invent one; mention it in the step's notes or in your final message.
- Timestamp links (for example a YouTube URL with `?t=95`) are fine and helpful when the source gives them.
- Do not add tracking parameters; strip `utm_*` and similar from copied URLs.
- Link to the original source page in the **first** step's `links` (title "Source: …") when you based the sequence on a web page, so the person can credit and check it.

---

## 8. Validation checklist

The app refuses the file if any item marked **(refused)** fails. The others are what makes a good file: the app may accept the file without them, but do not deliver one that misses them.

**Document**
- [ ] **(refused)** `format` is `"sequence"`, `schemaVersion` is `2` (a higher version is refused as "made by a newer app"), `id` is a GUID.
- [ ] **(refused)** `title` is not blank. At least one step.
- [ ] **(refused)** Every `estimatedSeconds`, if present, is between 1 and 604800 (7 days).
- [ ] `loopable`, if present, is `true` (never `false`).
- [ ] **(refused)** `category`, if present, is at most 40 characters. It should be one of the eight keys.
- [ ] **(refused)** Text lengths: titles (sequence, step, group, group member labels, background labels) at most 200 characters; `description` at most 5,000; step `notes` at most 10,000; each checklist item at most 500; each tag at most 50.
- [ ] **(refused)** Dates are valid ISO 8601. Write them in UTC ending in `Z`.

**IDs**
- [ ] **(refused)** Every `id` in the whole file is a valid GUID, not empty (`0000…`) and **unique**.
- [ ] **(refused)** Every `targetStepId` and group `stepId` matches a step `id`.
- [ ] **(refused)** Each repeat's `firstStepId` and `lastStepId` match steps, first not after last; 2 to 20 non-blank items of at most 40 characters; repeats don't overlap or include group steps.

**Timers**
- [ ] **(refused)** Every duration is a whole number from 1 to 604800.
- [ ] **(refused)** Each cue's target step comes **after** the step that owns it.
- [ ] **(refused)** In each group, a member's step never comes after the step of a shorter member; each step is in at most one group.
- [ ] No hand-written cues or background timers duplicate what a group already does.
- [ ] `requireChecklist` is true only when `checklist` has items (otherwise a warning).
- [ ] `alert`, where present, is `"chime"` or `"silent"` (left out for the default alarm); `advance` appears only on a gate, and only as `true`.
- [ ] Ingredients, parts and materials are in `tools` (with quantities), not in a `checklist`, so they appear in the Overview's "Items required" list.

**Optional content**
- [ ] **(refused)** Per step: at most 12 tools (each ≤ 80 chars), 5 callouts (each ≤ 300), 10 links (title ≤ 100, URL ≤ 2048, `http`/`https` with a host), 6 pictures (caption ≤ 120).
- [ ] Empty optional properties are left out, not written as empty.
- [ ] **(refused)** At most 40 images in total, each ≤ 4 MB, at most 8192 px a side and 16.7 megapixels, and really JPEG/PNG/WebP; a package of at most 25 MB; plain JSON of at most 5 MB.
- [ ] The images add up to under 15 MB, so the person can still edit the sequence's pictures.
- [ ] **(refused)** If there are images: it is a ZIP containing only `sequence.json` and `media/<id>.<ext>` entries. Every picture in the JSON has its file (a missing one is only a warning, and the picture does not show). If there are none: plain JSON.

**Content**
- [ ] The steps, quantities and times match the source. Nothing invented.
- [ ] Every title starts with a verb, waits say what to do meanwhile, preparation comes just before it is needed, and the last step is the finished result (section 4, "Structure and wording").
- [ ] Every step whose length you can judge has an `estimatedSeconds`.
- [ ] Warnings are real warnings. No images embedded without permission.

---

## 9. Optional: a script to check and package

If you can run Python, this checks the main rules and builds the file. It does not replace the checklist; it catches the common mistakes.

```python
import json, re, sys, uuid, zipfile, pathlib

GUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
CATEGORIES = {"cooking","repair","maintenance","cleaning","assembly","setup","fitness","other"}
MAX_SECONDS = 7 * 24 * 3600
ALERTS = {"chime","silent"}

def problems(doc, media):
    p, ids = [], []
    def gid(v, what):
        if not isinstance(v, str) or not GUID.match(v) or v == "0"*8+"-0000-0000-0000-"+"0"*12:
            p.append(f"bad id on {what}: {v!r}")
        ids.append(v)
    if doc.get("format") != "sequence": p.append("format must be 'sequence'")
    if doc.get("schemaVersion") != 2: p.append("schemaVersion must be 2")
    gid(doc.get("id"), "document")
    if not str(doc.get("title", "")).strip(): p.append("title is blank")
    def length(text, most, what):
        if len(text or "") > most: p.append(f"{what} is longer than {most} characters")
    length(doc.get("title"), 200, "title"); length(doc.get("description"), 5000, "description")
    for t in doc.get("tags", []): length(t, 50, "a tag")
    if doc.get("category") and (doc["category"] not in CATEGORIES): p.append("unknown category key (the app keeps it, but use one of the eight)")
    steps = doc.get("steps") or []
    if not steps: p.append("no steps")
    order = {}
    for i, s in enumerate(steps):
        gid(s.get("id"), f"step {i+1}"); order.setdefault(s.get("id"), i)
    def dur(v, what):
        if not isinstance(v, int) or not (1 <= v <= MAX_SECONDS): p.append(f"duration out of range on {what}: {v!r}")
    for i, s in enumerate(steps):
        n = f"step {i+1}"
        if not str(s.get("title", "")).strip(): p.append(f"{n}: blank title")
        length(s.get("title"), 200, n + " title"); length(s.get("notes"), 10000, n + " notes")
        for c in s.get("checklist", []): gid(c.get("id"), n + " checklist"); length(c.get("text"), 500, n + " checklist item")
        for b in s.get("background", []): length(b.get("label"), 200, n + " background label")
        if s.get("requireChecklist") and not s.get("checklist"): p.append(f"{n}: requireChecklist with no items (a warning in the app)")
        if s.get("gate"): dur(s["gate"].get("durationSeconds"), n + " gate")
        if "estimatedSeconds" in s: dur(s["estimatedSeconds"], n + " estimatedSeconds")
        for t in [s.get("gate") or {}] + s.get("cues", []) + s.get("background", []):
            if t.get("alert", "chime") not in ALERTS: p.append(f"{n}: alert must be one of {sorted(ALERTS)} or left out")
        for c in s.get("cues", []):
            gid(c.get("id"), n + " cue"); dur(c.get("delaySeconds"), n + " cue")
            if order.get(c.get("targetStepId"), -1) <= i: p.append(f"{n}: cue target missing or not later")
        for b in s.get("background", []): gid(b.get("id"), n + " background"); dur(b.get("durationSeconds"), n + " background")
        if len(s.get("tools", [])) > 12 or any(len(t) > 80 for t in s.get("tools", [])): p.append(f"{n}: tools limit")
        if len(s.get("callouts", [])) > 5: p.append(f"{n}: too many callouts")
        for c in s.get("callouts", []):
            gid(c.get("id"), n + " callout")
            if c.get("kind") not in ("info", "warning") or len(c.get("text", "")) > 300: p.append(f"{n}: bad callout")
        if len(s.get("links", [])) > 10: p.append(f"{n}: too many links")
        for l in s.get("links", []):
            gid(l.get("id"), n + " link")
            if not re.match(r"^https?://[^/@\s]+(/|$|\?|#)", l.get("url", "")) or len(l["url"]) > 2048 or len(l.get("title", "")) > 100:
                p.append(f"{n}: bad link {l.get('url')!r}")
        if len(s.get("pictures", [])) > 6: p.append(f"{n}: too many pictures")
        for pic in s.get("pictures", []): check_pic(pic, n, media, gid, p)
    if doc.get("cover"): check_pic(doc["cover"], "cover", media, gid, p)
    seen_steps = set()
    for g in doc.get("groups", []):
        gid(g.get("id"), "group"); length(g.get("name"), 200, "group name")
        ms = g.get("members", [])
        if len(ms) < 2: p.append("group has fewer than 2 members (advice, not an app rule)")
        for m in ms:
            if m.get("stepId") not in order: p.append("group member step missing")
            if m.get("stepId") in seen_steps: p.append("step in more than one group")
            seen_steps.add(m.get("stepId")); dur(m.get("durationSeconds"), "group member"); length(m.get("label"), 200, "group member label")
        placed = sorted((order[m["stepId"]], m.get("durationSeconds", 0)) for m in ms if m.get("stepId") in order)
        if any(b[1] > a[1] for a, b in zip(placed, placed[1:])): p.append("group: a member's step comes after a shorter member's step (put the longest first)")
    dup = {i for i in ids if ids.count(i) > 1}
    if dup: p.append(f"duplicate ids: {sorted(dup)}")
    return p

def check_pic(pic, where, media, gid, p):
    gid(pic.get("id"), where + " picture")
    path = pic.get("path", "")
    if not re.match(r"^media/[A-Za-z0-9._-]+\.(jpg|jpeg|png|webp)$", path, re.I) or ".." in path or len(path) > 120: p.append(f"{where}: bad picture path {path!r}")
    elif path not in media: p.append(f"{where}: no file for {path}")
    if len(pic.get("caption") or "") > 120: p.append(f"{where}: caption too long")

def magic_ok(path, data):
    ext = path.rsplit(".", 1)[-1].lower()
    return ((ext in ("jpg", "jpeg") and data[:3] == b"\xff\xd8\xff") or (ext == "png" and data[:8] == b"\x89PNG\r\n\x1a\n")
            or (ext == "webp" and data[:4] == b"RIFF" and data[8:12] == b"WEBP"))

def build(doc, media_files, out_path):
    """media_files: {'media/<id>.jpg': bytes}. Writes plain JSON if there are none, else a ZIP."""
    text = json.dumps(doc, ensure_ascii=False, indent=2)
    bad = problems(doc, media_files)
    for path, data in media_files.items():
        if not magic_ok(path, data): bad.append(f"{path}: content does not match its extension")
        if len(data) > 4 * 1024 * 1024: bad.append(f"{path}: over 4 MB")
    unused = set(media_files) - {x["path"] for s in doc["steps"] for x in s.get("pictures", [])} - ({doc["cover"]["path"]} if doc.get("cover") else set())
    if unused: bad.append(f"unreferenced media: {sorted(unused)}")
    if sum(map(len, media_files.values())) > 15 * 1024 * 1024: bad.append("over 15 MB of images (imports, but the person cannot add more pictures)")
    if len(doc["steps"]) and sum(len(s.get("pictures", [])) for s in doc["steps"]) + (1 if doc.get("cover") else 0) > 40: bad.append("over 40 images")
    if len(text.encode("utf-8")) > 5 * 1024 * 1024: bad.append("sequence.json over 5 MB")
    if bad:
        sys.exit("NOT WRITTEN:\n- " + "\n- ".join(bad))
    out = pathlib.Path(out_path)
    if not media_files:
        out.write_text(text, encoding="utf-8")  # no BOM
    else:
        with zipfile.ZipFile(out, "w") as z:
            z.writestr("sequence.json", text.encode("utf-8"), compress_type=zipfile.ZIP_DEFLATED)
            for path, data in sorted(media_files.items()):
                z.writestr(path, data, compress_type=zipfile.ZIP_STORED)
        if out.stat().st_size > 25 * 1024 * 1024:
            out.unlink()
            sys.exit("NOT WRITTEN: the package is over 25 MB")
    print("written", out, out.stat().st_size, "bytes")
```

Generate GUIDs with `str(uuid.uuid4())`.

---

## 10. What to tell the person afterwards

Keep it short:

- The file name and where it is, and that it opens with Sequence (share it to the phone, or open it from Files).
- How many steps (and, if more than 10, that the free version runs only the first 10), and which timers you created and why (for example "gate on preheat, a group for the three oven items"), including any that chime, are silent or move on by themselves.
- What you **inferred** rather than read from the source.
- What you **left out** and why: images you were not allowed to embed (and the links you added instead), videos without a usable link, parts of the source you could not follow.
- Attribution for any licensed image or for the source page.

If the source could not be fetched, was not a process, or was ambiguous in a way that changes the result (which of two recipes, metric or imperial), ask before producing a file.
