diff --git a/.gitignore b/.gitignore
index 6427ad9..5458dae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -38,12 +38,14 @@
 !/workflow/README.md
 !/workflow/build_suite.py
 !/workflow/build_catalogue.py
+!/workflow/edit_recipe.py
 !/workflow/verify_collection.py
 !/workflow/catalogue.css
 !/workflow/selection.example.json
 !/workflow/evaluation-template.json
 !/tests/
 !/tests/test_workflow.py
+!/tests/test_edit_recipe.py
 !/tests/test_review.py
 !/tests/test_review_import.py
 
diff --git a/AGENTS.md b/AGENTS.md
index 7d536ca..2ebe434 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,6 +28,7 @@ You are authorized to make any changes to RapidRAW and its MCP integration that
 - Reuse verified model assets through the companion editor's model cache, on the same volume as the workspaces for clone savings. Keep isolated workspaces, but use independent filesystem clones for large local fixture and source copies where supported. Do not use hard links for editable photographs or replace review assets with symlinks.
 - Reuse a build target for the same toolchain and configuration. Prefer non-incremental builds without debug symbols for validation; opt into larger development caches only when needed.
 - Keep accepted edits, recipes, original sources, review decisions, and reproducibility manifests. Prune only known rebuildable caches after confirming no active writer; completed experiments should be archived with checksum verification before local removal.
+- Keep the ignored workspace organised by kind (shoots, styles, experiments, publication, records, archive, cache, scratch); never leave loose files at its root. Start each new run with the workspace's scaffold helper so it has a dated folder and a README stating its purpose and status. Take finished experiments offline with the review CLI's `archive` command before removing their media, and move folders that review datasets use with `relocate`, so decisions and asset revisions survive.
 - Put archive and retention records in the ignored workspace. Keep current review references usable and verify them after any storage migration.
 
 ## Product manager review of public-facing material
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7c75aba..9af4621 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,19 @@
 ### Editing guidance
 
 - Rewrite `photo-edit-master` around concrete editing decisions: lessons from master photographers and darkroom printing, an eight-step workflow with starting ranges for crop, light shaping, colour and finish, a subject and inverted-environment mask pair, and common failures. Candidates are now checked twice before delivery: technical defects to fix, then artistic questions to answer for the photograph.
-- Rewrite the wildlife reference with picture types, standard moves, difficult light, cleanup and documentary honesty, including how to choose a depth-based or AI subject selection and what each tends to miss.
+- Rewrite the wildlife reference with picture types, standard moves, difficult light, cleanup and documentary honesty, including how to choose a depth-based or AI subject selection and what each tends to miss, and how to keep subject and environment masks on one shared edge to avoid halos.
+- Add a four-frame wildlife style comparison and guidance for keeping the subject's support visible, preserving bright light sources, correcting smooth flare ghosts, and checking mask edges at full size.
+- Guide style learning from returned human edits and blind comparisons, keeping one current personal profile with separate evidence for each round.
+
+### Review application
+
+- Add append-only variant publishing: `review/cli.py add-variant` and `add-variants` and the `POST /api/datasets/:id/variants` endpoints add a revision without replacing an existing version, so earlier decisions and the images already reviewed stay intact. Re-using a variant ID is refused.
+- Add `review/cli.py relocate` to rewrite media paths after folders move, saving a state backup and carrying feedback across when the reviewed bytes are unchanged. Add `archive` and `unarchive` to take a finished collection's media offline without clearing its decisions or asset revisions.
+- Add pinned notes to Photo reviewer: pin a note to a point on the photograph, with its position and zoom, and return to it later. Pins save with the version's feedback and are validated by the server, which accepts only known pin fields. **Pin center** or `P` pins the center of the view from the keyboard.
+
+### Editing workflow
+
+- Add `workflow/edit_recipe.py`, a declarative recipe format and executor for RapidRAW MCP sessions: ordered steps with tracked revisions, named mask references, recipes that extend and override a parent recipe, revision guards taken from the engine's tool schemas instead of a hardcoded list, parameters checked before a run starts, a client that reports errors instead of hanging, and a helper that renders the edit beside a global-only copy through the engine's non-mutating `render_compare`.
 
 ### Workspace and documentation
 
diff --git a/README.md b/README.md
index 8beccfd..91eb3c1 100644
--- a/README.md
+++ b/README.md
@@ -122,7 +122,7 @@ The skill uses selective reading: a shared workflow plus the reference relevant
 
 ## One workspace for review and personal style
 
-The [local review application](review/README.md) brings edit comparisons, style exploration, denoise review, and detail inspection into one extensible workspace. Agents publish rendered candidates; photographers compare them and save feedback and selections for the next iteration. Start it from this repository with Python 3.10+ on macOS or Linux:
+The [local review application](review/README.md) brings edit comparisons, style exploration, denoise review, and detail inspection into one extensible workspace. Agents publish rendered candidates, and later revisions beside them without replacing earlier versions; photographers compare them, pin notes to exact points on a photograph, and save feedback and selections for the next iteration. Start it from this repository with Python 3.10+ on macOS or Linux:
 
 ```sh
 python3 review/server.py --workspace .local/review --media-root . --port 8765
diff --git a/docs/continuing-edits.md b/docs/continuing-edits.md
index f3f423d..50bebe0 100644
--- a/docs/continuing-edits.md
+++ b/docs/continuing-edits.md
@@ -20,6 +20,6 @@ Load the core editing guidance, the applicable genre, and the execution referenc
 
 Review an overview after a meaningful group of edits. Inspect changed local corrections at matched native detail and check their relationship to the whole image. Use multi-view diagnostics to resolve a specific uncertainty. Keep the accepted reference and inspect the actual exported file before delivery.
 
-Publish candidates through the [shared review app](../review/README.md). Inspect rendered files directly for photographic decisions; operate the browser when interaction, feedback, alignment, or display behavior needs checking. Showing an existing comparison does not itself require another interface audit.
+Publish candidates through the [shared review app](../review/README.md), adding each revision as a new variant so earlier versions and the decisions made on them stay reviewable, and read any pinned notes on the previous version (`feedback-export` lists them under each variant's `pins`) before revising. Inspect rendered files directly for photographic decisions; operate the browser when interaction, feedback, alignment, or display behavior needs checking. Showing an existing comparison does not itself require another interface audit.
 
 For RapidRAW response formats, selected schema reads, and connection recovery, follow the companion's [MCP guide](https://github.com/sheldonxxxx/RapidRAW/blob/main/mcp/README.md). This workflow does not prescribe a smaller preview size, fewer necessary detail checks, a particular model, or additional agents.
diff --git a/docs/ecosystem.md b/docs/ecosystem.md
index adf39f1..55f40e6 100644
--- a/docs/ecosystem.md
+++ b/docs/ecosystem.md
@@ -25,7 +25,7 @@ The shared boundary is **an intention, rendered files, provenance, and feedback*
 1. **Read the photograph.** Photo Edit Master identifies the strongest quality, chooses a direction, and names relationships to protect.
 2. **Prepare only when needed.** For native Insta360 input, the toolkit supplies an appropriate Studio or SDK route. Ordinary photographs can go straight to their editor.
 3. **Render a candidate.** RapidRAW or another editor performs the edit. Keep the original and the editor's editable state or processing recipe.
-4. **Publish a review case.** Register a browser-readable baseline and candidates through the [Lightweft manifest, CLI, or API](../review/README.md). Use stable case and variant IDs; mark changed framing honestly.
+4. **Publish a review case.** Register a browser-readable baseline and candidates through the [Lightweft manifest, CLI, or API](../review/README.md). Use stable case and variant IDs; mark changed framing honestly. Publish each revision beside earlier versions with `add-variant` or `add-variants`, which never replace a published version, and read the reviewer's pinned notes (`feedback-export` lists them under each variant's `pins`) before the next pass.
 5. **Refine from feedback.** The photographer compares results, chooses a direction, and leaves notes. The agent reads that feedback and makes the next edit in its owning tool.
 6. **Deliver from the processing tool.** Export the final photograph and verify dimensions, colour, and relevant metadata. Review selections are feedback, not final-image exports.
 
diff --git a/review/README.md b/review/README.md
index 8484e81..92e02e5 100644
--- a/review/README.md
+++ b/review/README.md
@@ -114,6 +114,21 @@ Select **Personal style study** in the collection selector, or open <http://127.
 
 Hide finished experiments with the collection selector's **Disable** button; disabled collections stay in the workspace but are hidden unless **Show disabled** is on. Re-enable them from the viewer or with `python3 review/cli.py enable <id> --workspace .local/review --media-root .` (`disable` hides them the same way). Disabling preserves feedback and bumps the dataset version. The toggle changes collection metadata only, so it also works while a render is temporarily missing.
 
+Move media folders without losing decisions. Move the folder, then run `python3 review/cli.py relocate --map old/folder=new/folder --workspace .local/review --media-root .` (repeat `--map` for several folders; add `--dry-run` first to count the paths that would change). The command rewrites every stored media path that starts with a mapped folder, recomputes each variant's asset revision at the new location, and carries feedback across only when the bytes at the new path are the ones that were reviewed. A variant whose media changed is left to the normal stale-decision rule. It refuses to write if any relocated media is missing, and it saves the previous state under `backups/` in the workspace first.
+
+Retire the media of a finished collection with `python3 review/cli.py archive <id> --to <archive name> --workspace .local/review --media-root .`. Run it before moving the media away. Archiving disables the collection and marks its media as intentionally offline, so opening it later keeps its decisions and asset revisions instead of clearing them for missing renders. `unarchive <id>` brings it back once the media is restored at the same paths; use `relocate` first if it returns somewhere else.
+
+Add a revision without touching the existing versions, so earlier decisions and the images already reviewed stay intact:
+
+```sh
+python3 review/cli.py add-variant style-study example --id warm-v2 \
+  --image .local/renders/example-warm-v2.jpg --full .local/renders/example-warm-v2-full.jpg \
+  --label "Warm light, softer shadows" --parent warm-v1 --select \
+  --workspace .local/review --media-root .
+```
+
+Here `style-study` is the dataset ID and `example` the case ID. `add-variant` only appends. A variant ID that already exists is refused with a request to publish under a new ID, and nothing else in the dataset changes: feedback on other variants is preserved and the dataset version increments once. The new variant defaults to role `candidate` and is placed after the last existing candidate (or at the end if the case has none); `--select` makes it the case's selected variant. The CLI applies the addition to the current dataset version; the API calls below take it explicitly. `add-variants <dataset> <file.json>` applies several additions atomically from `{"additions": [{"caseId": "...", "variant": {...}, "select": true}]}`.
+
 For large photographs, each variant can point `image` to a smaller review preview and `full` to the full export. Both files must exist when imported. Use browser-compatible formats such as JPEG, PNG, or WebP; TIFF and AVIF display support depends on the browser. RAW decoding and edit rendering belong to your editor.
 
 ## Review and build a style
@@ -141,12 +156,15 @@ The comparison surface offers side-by-side and single-image views, an aligned be
 | Left / Right arrow | Previous / next photograph |
 | Hold Space | Temporarily show the other version |
 | B | Swap comparison sides |
+| P | Pin the center of the current view (Photo reviewer) |
 | 1 / 2 / 3 / 4 | Open Photo reviewer / Style builder / Detail lab / 360 review |
 | Scroll / trackpad pinch over the photograph | Zoom around the pointer |
 | Drag at any numeric zoom | Pan the compared images together |
 
 Feedback saves automatically to the workspace, with a browser draft available if saving fails. The save status shows whether the workspace has received it. On a concurrent update, loading the newer version retains a separate recovery draft and opens the earlier feedback as JSON for reconciliation. Exports provide copy, select, and download controls so in-app browsers need not rely on downloads. “Follow agent updates” refreshes published candidates while there are no unsaved edits. Feedback can also be imported as JSON.
 
+To leave feedback about one place in a photograph, choose **Pin note** above the image in Photo reviewer, then click the spot, or choose **Pin center** (or press `P`) to pin the center of the current view without a pointer. The note appears in the **Pinned notes** list beside the photograph; **Go to** returns the view to that point at the zoom it was pinned at (100% when it was pinned from Fit). Pins belong to the version being reviewed and save with the rest of the feedback. A new revision starts without pins, so read the previous version's pins before revising and address each one.
+
 Use the edit reviewer to compare source or base against candidates, inspect the whole photograph, and record the gain, cost, and requested revision. Fine-detail checks belong to the same decision: a successful export or an agent's preferred candidate does not establish user acceptance.
 
 In Style builder, select a look from the wrapping card grid below the photograph, compare it with the chosen base, and use Accept, Refine, or Pass with one feedback note. Selecting a thumbnail only changes the viewed look; it does not record acceptance. Feedback saves automatically for each version. Inspection checks are tucked into a disclosure, and any earlier structured style notes remain readable. Naming styles and saving reusable artifacts are separate from this comparison flow. Keep personal style separate from the shared [master editing philosophy](../skills/photo-edit-master/SKILL.md). Use the [style builder skill](../skills/photo-style-builder/SKILL.md) for the collaborative workflow.
@@ -205,6 +223,8 @@ Set `aligned: true` only when the compared images represent the same framing and
 | `PUT /api/datasets/:id` | Create with `{ "version": 0, "dataset": manifest }`, or replace using the current version |
 | `PUT /api/datasets/:id/disabled` | Hide or show a collection with `{ "version": currentVersion, "disabled": true or false }` |
 | `PUT /api/datasets/:id/cases/:caseId/disabled` | Disable or enable a photograph with `{ "version": currentVersion, "disabled": true or false }`; disabling preserves feedback |
+| `POST /api/datasets/:id/variants` | Append variants with `{ "version": currentDatasetVersion, "additions": [{ "caseId": "...", "variant": {...}, "select": false }] }`; an existing variant ID returns HTTP 409 and no change is applied. Returns HTTP 201 |
+| `POST /api/datasets/:id/cases/:caseId/variants` | Append one variant with `{ "version": currentDatasetVersion, "variant": {...}, "select": false }` |
 | `PUT /api/datasets/:id/feedback` | Save feedback with `{ "version": currentVersion, "feedback": feedback }` |
 | `GET /api/datasets/:id/feedback/export` | Download agent-readable feedback |
 | `POST /api/profiles` | Save `{ name, kind, datasetId, caseId, variantId, description, preferences, assetRevision? }`; `kind` is `profile` or `preset`; include the selected variant's revision to guard against a stale selection |
@@ -213,7 +233,7 @@ Set `aligned: true` only when the compared images represent the same framing and
 
 Use the local server URL as the API base and send `Content-Type: application/json` with mutations. Cross-origin browser requests are rejected. A stale dataset version returns HTTP 409. The CLI is the simplest way to register exports from an agent with local filesystem access; no MCP connection is required for Review.
 
-Feedback is keyed by case ID and then variant ID. Entries include `decision` (`accepted`, `revise`, `rejected`, or empty), `note`, `checks`, `style`, and asset revision metadata. Style notes contain `direction`, `keep`, `avoid`, and `scope`. The decision and technical check status are independent: checks record what was inspected, not an automatic image-quality assessment. When an asset or its review context changes, earlier feedback becomes stale and its decision and checks are cleared while notes remain available.
+Feedback is keyed by case ID and then variant ID. Entries include `decision` (`accepted`, `revise`, `rejected`, or empty), `note`, `checks`, `style`, and asset revision metadata. Style notes contain `direction`, `keep`, `avoid`, and `scope`. `pins` holds pinned notes: a list of up to 200 `{ id, x, y, note, zoom?, compareWith?, createdAt? }`, where `x` and `y` are 0–1 fractions of the image width and height (so they locate the same point on a preview and on the full export), `zoom` is the magnification the reviewer was using (1 is one image pixel per screen pixel), and `compareWith` lists other versions of the same photograph that were being compared. Agents should read pins before the next revision and address each one. The decision and technical check status are independent: checks record what was inspected, not an automatic image-quality assessment. When an asset or its review context changes, earlier feedback becomes stale and its decision and checks are cleared while notes remain available.
 
 Agents should read the current version and saved feedback before editing a manifest or preparing the next candidate. Publish a new variant for a revision, preserve accepted versions, and supply truthful provenance. On a version conflict, reread and reconcile with the latest feedback; do not blindly overwrite it. An internal agent ranking must remain distinct from the photographer's saved decision.
 
diff --git a/review/cli.py b/review/cli.py
index c8831c3..7913341 100644
--- a/review/cli.py
+++ b/review/cli.py
@@ -32,7 +32,7 @@ def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
     sub = parser.add_subparsers(dest='command', required=True)
     commands = {}
-    for name in ('import', 'list', 'show', 'feedback-export', 'feedback-import', 'disable', 'enable'):
+    for name in ('import', 'list', 'show', 'feedback-export', 'feedback-import', 'disable', 'enable', 'archive', 'unarchive', 'relocate', 'add-variant', 'add-variants'):
         command = sub.add_parser(name)
         command.add_argument('--workspace', type=Path, default=Path('.local/review'))
         command.add_argument('--media-root', type=Path, required=True)
@@ -42,8 +42,27 @@ def main(argv=None):
     imported.add_argument('--id', required=True, dest='dataset_id')
     imported.add_argument('--title')
     imported.add_argument('--path-map', action='append', default=[], metavar='OLD=NEW')
-    for name in ('show', 'feedback-export', 'feedback-import', 'disable', 'enable'):
+    for name in ('show', 'feedback-export', 'feedback-import', 'disable', 'enable', 'archive', 'unarchive', 'add-variant', 'add-variants'):
         commands[name].add_argument('dataset_id')
+    commands['archive'].add_argument('--to', dest='archived_to', help='Where the media went, for example the archive file name')
+    relocated = commands['relocate']
+    relocated.add_argument('--map', action='append', default=[], required=True, metavar='OLD=NEW', help='Folder that moved, relative to the media root; repeatable')
+    relocated.add_argument('--dry-run', action='store_true', help='Count the paths that would change without writing')
+    relocated.add_argument('--allow-missing', action='store_true', help='Write even when some relocated media is missing')
+    single = commands['add-variant']
+    single.add_argument('case_id')
+    single.add_argument('--id', required=True, dest='variant_id', help='New variant id; an existing id is refused')
+    single.add_argument('--image', required=True, help='Review image path relative to the media root')
+    single.add_argument('--full', help='Full export path relative to the media root')
+    single.add_argument('--label')
+    single.add_argument('--role', default='candidate', choices=('baseline', 'candidate', 'reference'))
+    single.add_argument('--description')
+    single.add_argument('--parent', help='Variant id this render was derived from (metadata.parentVariantId)')
+    single.add_argument('--recipe')
+    single.add_argument('--recipe-format')
+    single.add_argument('--metadata', help='JSON object merged into the variant metadata')
+    single.add_argument('--select', action='store_true', help='Open this variant as the selected candidate')
+    commands['add-variants'].add_argument('source', type=Path, help='JSON file: {"additions": [{"caseId", "variant", "select"?}, ...]}')
     commands['feedback-export'].add_argument('--output', type=Path)
     commands['feedback-import'].add_argument('source', type=Path)
     commands['feedback-import'].add_argument('--version', type=int, required=True, help='Current destination dataset version; stale versions are rejected')
@@ -82,6 +101,36 @@ def main(argv=None):
                 raise ValueError('Feedback export must have matching datasetId and schemaVersion 1')
             result = store.put_feedback(args.dataset_id, data.get('feedback'), args.version)
             print(json.dumps({'id': args.dataset_id, 'version': result['version']}))
+        elif args.command in ('add-variant', 'add-variants'):
+            if args.command == 'add-variant':
+                variant = {'id': args.variant_id, 'label': args.label or args.variant_id, 'role': args.role, 'image': args.image}
+                for key, value in (('full', args.full), ('description', args.description), ('recipe', args.recipe), ('recipeFormat', args.recipe_format)):
+                    if value:
+                        variant[key] = value
+                metadata = json.loads(args.metadata) if args.metadata else {}
+                if args.parent:
+                    metadata['parentVariantId'] = args.parent
+                if metadata:
+                    variant['metadata'] = metadata
+                additions = [{'caseId': args.case_id, 'variant': variant, 'select': args.select}]
+            else:
+                data = json.loads(args.source.read_text(encoding='utf-8'))
+                additions = data.get('additions') if isinstance(data, dict) else data
+            result = store.add_variants(args.dataset_id, additions)
+            print(json.dumps({'id': args.dataset_id, 'added': len(additions), 'version': result['version']}))
+        elif args.command == 'archive':
+            result = store.set_archived(args.dataset_id, True, args.archived_to)
+            print(json.dumps({'id': args.dataset_id, 'archived': True, 'disabled': True, 'version': result['version']}))
+        elif args.command == 'unarchive':
+            result = store.set_archived(args.dataset_id, False)
+            print(json.dumps({'id': args.dataset_id, 'archived': False, 'disabled': result['dataset'].get('disabled', False), 'version': result['version']}))
+        elif args.command == 'relocate':
+            maps = []
+            for value in args.map:
+                if '=' not in value or not all(value.split('=', 1)):
+                    raise ValueError('--map must be OLD=NEW')
+                maps.append(tuple(value.split('=', 1)))
+            print(json.dumps(store.relocate(maps, dry_run=args.dry_run, allow_missing=args.allow_missing)))
         elif args.command in ('disable', 'enable'):
             result = store.set_disabled(args.dataset_id, args.command == 'disable')
             print(json.dumps({'id': args.dataset_id, 'disabled': result['dataset'].get('disabled', False), 'version': result['version']}))
diff --git a/review/server.py b/review/server.py
index f6dad06..e8d5c8b 100644
--- a/review/server.py
+++ b/review/server.py
@@ -56,6 +56,11 @@ def string_value(value, label, limit=10000):
     return value
 
 
+# Keep MAX_PINS equal to MAX_PINS in web/pins.js (tests/test_review.py checks it).
+MAX_PINS = 200
+PIN_FIELDS = {'id', 'x', 'y', 'zoom', 'note', 'compareWith', 'createdAt'}
+
+
 def relative_path(value):
     if not isinstance(value, str) or not value or len(value) > 4096:
         raise ReviewError('Media path must be a nonempty relative path')
@@ -183,6 +188,10 @@ def validate_dataset(self, dataset, require_files=True):
         if 'disabled' in d and not isinstance(d['disabled'], bool):
             raise ReviewError('dataset.disabled must be boolean')
         d.setdefault('disabled', False)
+        if 'archived' in d and not isinstance(d['archived'], bool):
+            raise ReviewError('dataset.archived must be boolean')
+        if 'archivedTo' in d:
+            string_value(d['archivedTo'], 'dataset.archivedTo', 4096)
         if 'metadata' in d:
             object_value(d['metadata'], 'dataset.metadata')
         cases = d.get('cases')
@@ -280,20 +289,26 @@ def validate_dataset(self, dataset, require_files=True):
                     self.validate_asset(entry.get('image'), require_file=require_files)
         return d
 
-    def variant_revision(self, case, variant):
-        material = {k: v for k, v in variant.items() if k not in ('assetRevision', 'unavailable', 'defaultView')}
+    @staticmethod
+    def variant_assets(case, variant):
         assets = [variant[k] for k in ('image', 'full', 'recipe') if variant.get(k)]
+        for region in case.get('regions', []):
+            assets.extend(entry['image'] for entry in region.get('images', []) if entry['variantId'] == variant['id'])
+        return assets
+
+    def variant_revision(self, case, variant, resolve=None):
+        """Hash the variant's recipe material; `resolve` maps a stored path to where its bytes live now."""
+        material = {k: v for k, v in variant.items() if k not in ('assetRevision', 'unavailable', 'defaultView')}
         region_material = []
         for region in case.get('regions', []):
             entries = [entry for entry in region.get('images', []) if entry['variantId'] == variant['id']]
             if entries:
                 region_material.append({**region, 'images': entries})
-                assets.extend(entry['image'] for entry in entries)
         missing = []
         hashes = {}
-        for path in assets:
+        for path in self.variant_assets(case, variant):
             try:
-                hashes[path] = self.digest(path)
+                hashes[path] = self.digest(resolve(path) if resolve else path)
             except ReviewError:
                 hashes[path] = 'unavailable'
                 missing.append(path)
@@ -302,6 +317,12 @@ def variant_revision(self, case, variant):
         return revision, missing
 
     def refresh(self, record, previous=None):
+        if record['dataset'].get('archived'):
+            # Media is intentionally offline: keep revisions and feedback untouched.
+            for case in record['dataset']['cases']:
+                for variant in case['variants']:
+                    variant['unavailable'] = self.variant_assets(case, variant)
+            return False
         changed = False
         before = previous or record
         old_revisions = {(c['id'], v['id']): v.get('assetRevision') for c in before['dataset']['cases'] for v in c['variants']}
@@ -329,7 +350,7 @@ def envelope(self, record):
     def workspace_summary(self):
         with self.locked():
             state = self.read()
-            return {'workspaceId': self.workspace_id, 'datasets': [{'id': r['dataset']['id'], 'title': r['dataset']['title'], 'description': r['dataset'].get('description', ''), 'count': len(r['dataset']['cases']), 'version': r['version'], 'disabled': bool(r['dataset'].get('disabled', False))} for r in state['datasets'].values()], 'profiles': [self.public_profile(p) for p in state['profiles']]}
+            return {'workspaceId': self.workspace_id, 'datasets': [{'id': r['dataset']['id'], 'title': r['dataset']['title'], 'description': r['dataset'].get('description', ''), 'count': len(r['dataset']['cases']), 'version': r['version'], 'disabled': bool(r['dataset'].get('disabled', False)), 'archived': bool(r['dataset'].get('archived', False))} for r in state['datasets'].values()], 'profiles': [self.public_profile(p) for p in state['profiles']]}
 
     def get_dataset(self, dataset_id):
         valid_id(dataset_id)
@@ -389,6 +410,127 @@ def set_disabled(self, dataset_id, disabled, version=None):
             self.write(state)
             return self.envelope(next_record)
 
+    def set_archived(self, dataset_id, archived, archived_to=None):
+        """Mark a collection's media as intentionally offline (or back online) without touching decisions."""
+        valid_id(dataset_id)
+        if not isinstance(archived, bool):
+            raise ReviewError('archived must be boolean')
+        with self.locked():
+            state = self.read()
+            record = state['datasets'].get(dataset_id)
+            if record is None:
+                raise ReviewError('Dataset not found', 404)
+            if self.refresh(record):
+                record['version'] += 1
+                self.write(state)
+            next_record = copy.deepcopy(record)
+            dataset = next_record['dataset']
+            if archived:
+                dataset['archived'] = True
+                dataset['disabled'] = True
+                if archived_to:
+                    dataset['archivedTo'] = archived_to
+                self.validate_dataset(dataset, require_files=False)
+                next_record['version'] += 1
+                self.refresh(next_record, record)
+            else:
+                dataset.pop('archived', None)
+                dataset.pop('archivedTo', None)
+                missing = [p for case in dataset['cases'] for v in case['variants'] for p in self.variant_revision(case, v)[1]]
+                if missing:
+                    raise ReviewError(f'Restore the media before unarchiving; {len(missing)} files are missing, e.g. {missing[0]}', 409)
+                next_record['version'] += 1
+                self.refresh(next_record, record)
+            state['datasets'][dataset_id] = next_record
+            self.write(state)
+            return self.envelope(next_record)
+
+    def relocate(self, mapping, dry_run=False, allow_missing=False):
+        """Rewrite stored media paths after folders moved, carrying feedback over for unchanged bytes."""
+        pairs = sorted(((relative_path(old), relative_path(new)) for old, new in mapping), key=lambda pair: -len(pair[0]))
+        if not pairs:
+            raise ReviewError('Give at least one OLD=NEW folder mapping')
+        root = str(self.media_root)
+
+        def rewrite(value):
+            for old, new in pairs:
+                for before, after in ((old, new), (f'{root}/{old}', f'{root}/{new}')):
+                    if value == before or value.startswith(before + '/'):
+                        return after + value[len(before):]
+            return value
+
+        def rewrite_tree(node):
+            count = 0
+            if isinstance(node, dict):
+                items = node.items()
+            elif isinstance(node, list):
+                items = enumerate(node)
+            else:
+                return 0
+            for key, value in list(items):
+                if isinstance(value, str):
+                    changed = rewrite(value)
+                    if changed != value:
+                        node[key] = changed
+                        count += 1
+                else:
+                    count += rewrite_tree(value)
+            return count
+
+        def resolve(path):
+            moved = rewrite(path)
+            return moved if os.path.lexists(self.media_root / moved) else path
+
+        with self.locked():
+            state = self.read()
+            report = {'datasets': 0, 'strings': 0, 'profileStrings': 0, 'carried': 0, 'unverified': 0, 'missing': [], 'dryRun': dry_run}
+            for dataset_id, record in list(state['datasets'].items()):
+                next_record = copy.deepcopy(record)
+                count = rewrite_tree(next_record['dataset'])
+                if not count:
+                    continue
+                report['datasets'] += 1
+                report['strings'] += count
+                if dry_run:
+                    continue
+                next_record['version'] = record['version'] + 1
+                if next_record['dataset'].get('archived'):
+                    self.refresh(next_record, record)
+                else:
+                    previous = copy.deepcopy(record)
+                    old_cases = {c['id']: c for c in previous['dataset']['cases']}
+                    for case in next_record['dataset']['cases']:
+                        old_case = old_cases[case['id']]
+                        old_variants = {v['id']: v for v in old_case['variants']}
+                        for variant in case['variants']:
+                            old_variant = old_variants[variant['id']]
+                            stored = old_variant.get('assetRevision')
+                            current, _ = self.variant_revision(old_case, old_variant, resolve)
+                            if not stored or current != stored:
+                                report['unverified'] += 1
+                                continue
+                            fresh, _ = self.variant_revision(case, variant)
+                            old_variant['assetRevision'] = fresh
+                            item = previous['feedback'].get(case['id'], {}).get(variant['id'])
+                            if item and item.get('assetRevision') == stored:
+                                item['assetRevision'] = fresh
+                            report['carried'] += 1
+                    self.refresh(next_record, previous)
+                    for case in next_record['dataset']['cases']:
+                        for variant in case['variants']:
+                            report['missing'].extend(variant.get('unavailable') or [])
+                state['datasets'][dataset_id] = next_record
+            report['profileStrings'] = sum(rewrite_tree(profile) for profile in state['profiles'])
+            if report['missing'] and not allow_missing:
+                raise ReviewError(f"{len(report['missing'])} relocated media files are missing, e.g. {report['missing'][0]}; nothing was written")
+            if not dry_run and (report['datasets'] or report['profileStrings']):
+                backups = self.workspace / 'backups'
+                stamp = datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')
+                atomic_write(backups / f'state.before-relocate-{stamp}.json', self.state_path.read_bytes())
+                self.write(state)
+            report['missing'] = report['missing'][:20]
+            return report
+
     def set_case_disabled(self, dataset_id, case_id, disabled, version=None):
         valid_id(dataset_id)
         valid_id(case_id, 'case.id')
@@ -416,6 +558,53 @@ def set_case_disabled(self, dataset_id, case_id, disabled, version=None):
             self.write(state)
             return self.envelope(next_record)
 
+    def add_variants(self, dataset_id, additions, version=None):
+        """Append variants to existing cases without touching published ones.
+
+        ``additions`` is a list of ``{caseId, variant, select?}``. A variant id that
+        already exists is refused: a revision must be published under a new id so
+        earlier renders and the decisions made on them stay reviewable. The whole
+        batch is applied in one version bump or not at all.
+        """
+        valid_id(dataset_id)
+        if not isinstance(additions, list) or not additions or len(additions) > 10000:
+            raise ReviewError('additions must be a non-empty list')
+        with self.locked():
+            state = self.read()
+            record = state['datasets'].get(dataset_id)
+            if record is None:
+                raise ReviewError('Dataset not found', 404)
+            if self.refresh(record):
+                record['version'] += 1
+                self.write(state)
+            if version is not None and (type(version) is not int or version != record['version']):
+                raise ReviewError('Workspace changed; reload before saving', 409)
+            dataset = copy.deepcopy(record['dataset'])
+            cases = {case['id']: case for case in dataset['cases']}
+            for item in additions:
+                object_value(item, 'addition')
+                case = cases.get(valid_id(item.get('caseId'), 'caseId'))
+                if case is None:
+                    raise ReviewError(f"Case not found: {item.get('caseId')}", 404)
+                variant = copy.deepcopy(object_value(item.get('variant'), 'variant'))
+                vid = valid_id(variant.get('id'), 'variant.id')
+                if any(existing['id'] == vid for existing in case['variants']):
+                    raise ReviewError(f"Variant {vid} already exists in case {case['id']}; publish the revision under a new id", 409)
+                for key in ('assetRevision', 'unavailable'):
+                    variant.pop(key, None)
+                variant.setdefault('role', 'candidate')
+                variant.setdefault('label', vid)
+                last_candidate = max((i for i, existing in enumerate(case['variants']) if existing.get('role') == 'candidate'), default=-1)
+                case['variants'].insert(last_candidate + 1 if last_candidate >= 0 else len(case['variants']), variant)
+                if item.get('select'):
+                    case['selectedVariantId'] = vid
+            validated = self.validate_dataset(dataset)
+            next_record = {'dataset': validated, 'feedback': {}, 'version': record['version'] + 1}
+            self.refresh(next_record, record)
+            state['datasets'][dataset_id] = next_record
+            self.write(state)
+            return self.envelope(next_record)
+
     def put_feedback(self, dataset_id, feedback, version):
         object_value(feedback, 'feedback')
         with self.locked():
@@ -452,6 +641,8 @@ def put_feedback(self, dataset_id, feedback, version):
                         for key, value in style.items():
                             string_value(key, 'style field', 100)
                             string_value(value, 'style preference')
+                    if 'pins' in item:
+                        item['pins'] = self.clean_pins(item['pins'], cid, cases[cid], vid)
                     if 'rating' in item and (type(item['rating']) not in (int, float) or not math.isfinite(item['rating']) or not 0 <= item['rating'] <= 5):
                         raise ReviewError('Rating must be between 0 and 5')
                     if item['decision'] == 'accepted' and cases[cid][vid].get('unavailable'):
@@ -469,6 +660,37 @@ def put_feedback(self, dataset_id, feedback, version):
             self.write(state)
             return self.envelope(record)
 
+    @staticmethod
+    def clean_pins(pins, case_id, variants, variant_id):
+        """Pinned notes: a note at a point on the photograph, in image-relative coordinates."""
+        if not isinstance(pins, list) or len(pins) > MAX_PINS:
+            raise ReviewError(f'Pinned notes must be a list of at most {MAX_PINS} pins')
+        clean, seen = [], set()
+        for raw in pins:
+            pin = copy.deepcopy(object_value(raw, 'pin'))
+            unknown = sorted(set(pin) - PIN_FIELDS)
+            if unknown:
+                raise ReviewError(f'Unknown pin field: {unknown[0]}')
+            string_value(pin.get('id'), 'pin id', 100)
+            if not pin['id'] or pin['id'] in seen:
+                raise ReviewError('Each pin needs its own id')
+            seen.add(pin['id'])
+            for axis in ('x', 'y'):
+                value = pin.get(axis)
+                if type(value) not in (int, float) or not math.isfinite(value) or not 0 <= value <= 1:
+                    raise ReviewError('Pin position must be between 0 and 1')
+            if 'zoom' in pin and (type(pin['zoom']) not in (int, float) or not math.isfinite(pin['zoom']) or not 0 < pin['zoom'] <= 16):
+                raise ReviewError('Pin zoom must be between 0 and 16')
+            string_value(pin.setdefault('note', ''), 'pin note')
+            if 'createdAt' in pin:
+                string_value(pin['createdAt'], 'pin creation time', 64)
+            if 'compareWith' in pin:
+                others = pin['compareWith']
+                if not isinstance(others, list) or len(others) > 8 or any(o not in variants or o == variant_id for o in others):
+                    raise ReviewError('Pin comparison must name other versions of the same photograph')
+            clean.append(pin)
+        return clean
+
     @staticmethod
     def public_profile(profile):
         return {key: value for key, value in profile.items() if key != 'recipeFile'}
@@ -795,6 +1017,16 @@ def dispatch(self):
             if match[2]:
                 return self.json_response(store.put_feedback(match[1], payload.get('feedback'), payload.get('version')))
             return self.json_response(store.put_dataset(match[1], payload.get('dataset'), payload.get('version', 0)))
+        if self.command == 'POST':
+            match = re.fullmatch(r'/api/datasets/([^/]+)/variants', path)
+            if match:
+                payload = self.read_json()
+                return self.json_response(store.add_variants(match[1], payload.get('additions'), payload.get('version')), status=201)
+            match = re.fullmatch(r'/api/datasets/([^/]+)/cases/([^/]+)/variants', path)
+            if match:
+                payload = self.read_json()
+                addition = {'caseId': match[2], 'variant': payload.get('variant'), 'select': bool(payload.get('select'))}
+                return self.json_response(store.add_variants(match[1], [addition], payload.get('version')), status=201)
         if self.command == 'POST' and path == '/api/profiles':
             return self.json_response(store.create_profile(self.read_json()), status=201)
         raise ReviewError('Method not allowed', 405)
diff --git a/review/tests/compare.test.mjs b/review/tests/compare.test.mjs
index 8bcde87..831d31e 100644
--- a/review/tests/compare.test.mjs
+++ b/review/tests/compare.test.mjs
@@ -84,3 +84,72 @@ test('zoom rejects invalid values and bounds extreme magnification', () => {
   value.setZoom(.00001);
   assert.equal(value.zoom, .001);
 });
+
+test('pin coordinates are image-relative, reject outside points, and recall their zoom', async () => {
+  const {imagePoint, createPin, markerOffset, viewFor, withoutPin, withNote} = await import('../web/pins.js');
+  const rect = {left: 100, top: 50, width: 800, height: 400};
+  assert.deepEqual(imagePoint(rect, 500, 250), {x: .5, y: .5});
+  assert.equal(imagePoint(rect, 99, 250), null);
+  assert.equal(imagePoint({left: 0, top: 0, width: 0, height: 0}, 0, 0), null);
+  const pin = createPin({x: .25, y: .75, zoom: 2, compareWith: ['base']}, 'p1');
+  assert.deepEqual({id: pin.id, x: pin.x, y: pin.y, zoom: pin.zoom, compareWith: pin.compareWith}, {id: 'p1', x: .25, y: .75, zoom: 2, compareWith: ['base']});
+  assert.equal(createPin({x: 0, y: 0, zoom: null}, 'p2').zoom, undefined);
+  assert.deepEqual(markerOffset(pin, {left: 10, top: 20, width: 400, height: 200}), {left: 110, top: 170});
+  assert.deepEqual(viewFor(pin), {zoom: 2, center: {x: .25, y: .75}});
+  assert.equal(viewFor(createPin({x: .1, y: .2}, 'p3')).zoom, 1);
+  assert.deepEqual(withoutPin([pin, {id: 'q'}], 'p1').map(item => item.id), ['q']);
+  assert.equal(withNote([pin], 'p1', 'fix').at(0).note, 'fix');
+});
+
+test('focusing a pin centres the view on it at the recorded zoom', async () => {
+  const {createPin} = await import('../web/pins.js');
+  const value = viewer();
+  value.focusPin(createPin({x: .3, y: .6, zoom: .5}, 'p'));
+  close(value.zoom, .5);
+  assert.deepEqual(value.center, {x: .3, y: .6});
+  value.focusPin(createPin({x: .8, y: .2}, 'q'));
+  close(value.zoom, 1);
+});
+
+test('pinning from the keyboard uses the view center and the recorded zoom', () => {
+  const value = viewer();
+  const added = [];
+  Object.assign(value, {left: {id: 'base'}, right: {id: 'edit'}, pinButton: {hidden: true}, pinCenterButton: {hidden: true}, renderPins() {}});
+  value.setPins('edit', [], {onAdd: pin => added.push(pin)});
+  assert.equal(value.pinCenterButton.hidden, false);
+  value.pinCenter();
+  assert.deepEqual([added[0].x, added[0].y, added[0].zoom, added[0].compareWith], [.5, .5, undefined, ['base']]);
+  value.center = {x: .3, y: .6}; value.zoom = 2;
+  value.pinCenter();
+  assert.deepEqual([added[1].x, added[1].y, added[1].zoom], [.3, .6, 2]);
+  value.setPins('edit', [], null);
+  assert.equal(value.pinCenterButton.hidden, true);
+  value.pinCenter();
+  assert.equal(added.length, 2);
+});
+
+test('pins at the server limit remain intact and refuse further pointer or keyboard additions', () => {
+  const value = viewer(), added = [];
+  Object.assign(value, {pinButton: {}, pinCenterButton: {}, renderPins() {}});
+  const pins = Array.from({length: 200}, (_, i) => ({id: String(i), x: .5, y: .5, note: `Note ${i}`}));
+  value.setPins('edit', pins, {onAdd: pin => added.push(pin)});
+  value.pinCenter();
+  value.addPinAt(300, 200, {});
+  assert.equal(value.pinButton.disabled, true);
+  assert.equal(value.pinCenterButton.disabled, true);
+  assert.deepEqual(value.pins, pins);
+  assert.equal(added.length, 0);
+  value.setPins('edit', pins.slice(1), {onAdd: pin => added.push(pin)});
+  assert.equal(value.pinButton.disabled, false);
+});
+
+test('pointer pins belong to the reviewed photo and never use an unaligned reference frame', () => {
+  const value = viewer(), added = [], candidate = {id: 'edit'}, original = {id: 'base'};
+  Object.assign(value, {pinButton: {disabled: false}, pinVariant: 'edit', note: {}, left: original, right: candidate,
+    pinHandlers: {onAdd: pin => added.push(pin)},
+    paneAt: (_x, _y, item) => ({item, img: {naturalWidth: 300, getBoundingClientRect: () => ({left: 100, top: 50, width: 300, height: 450})}})});
+  value.addPinAt(175, 275, original);
+  assert.equal(added.length, 0);
+  value.addPinAt(175, 275, candidate);
+  assert.deepEqual([added[0].x, added[0].y, added[0].compareWith], [.25, .5, ['base']]);
+});
diff --git a/review/web/app.js b/review/web/app.js
index 864e6f2..3b1f90d 100644
--- a/review/web/app.js
+++ b/review/web/app.js
@@ -269,7 +269,7 @@ async function showLibrary() {
 }
 function shortcuts() {
   dialog('A few useful shortcuts', el('div', {class: 'shortcut-list'},
-    [['← / →', 'Previous / next photograph'], ['Space (hold)', 'Temporarily show the other version'], ['B', 'Swap the comparison sides'], ['1 / 2 / 3 / 4', 'Reviewer / Style builder / Detail lab / 360 review'], ['Scroll / pinch', 'Zoom around the pointer'], ['Drag', 'Pan both images together at any numeric zoom']].map(([key, description]) => el('p', {}, el('kbd', {}, key), el('span', {}, description)))));
+    [['← / →', 'Previous / next photograph'], ['Space (hold)', 'Temporarily show the other version'], ['B', 'Swap the comparison sides'], ['P', 'Pin a note at the center of the view'], ['1 / 2 / 3 / 4', 'Reviewer / Style builder / Detail lab / 360 review'], ['Scroll / pinch', 'Zoom around the pointer'], ['Drag', 'Pan both images together at any numeric zoom']].map(([key, description]) => el('p', {}, el('kbd', {}, key), el('span', {}, description)))));
 }
 function buildShell() {
   saveStatus = el('span', {class: 'save-status', role: 'status'}, 'Connecting…');
@@ -321,6 +321,7 @@ document.addEventListener('keydown', event => {
   if (event.key === 'ArrowRight') {event.preventDefault(); navigate(1);}
   if (event.key === 'ArrowLeft') {event.preventDefault(); navigate(-1);}
   if (event.key.toLowerCase() === 'b') activePanel?.viewer?.swap();
+  if (event.key.toLowerCase() === 'p') activePanel?.viewer?.pinCenter?.();
   if (['1', '2', '3', '4'].includes(event.key)) {ui.panel = panels[Number(event.key) - 1].id; renderTabs(); renderPanel();}
 });
 document.addEventListener('keyup', event => {if (event.code === 'Space') activePanel?.viewer?.setBlink(false);});
diff --git a/review/web/compare.js b/review/web/compare.js
index 363366b..b27e344 100644
--- a/review/web/compare.js
+++ b/review/web/compare.js
@@ -1,4 +1,5 @@
 import { el, button, select, media } from './dom.js';
+import { MAX_PINS, imagePoint, createPin, markerOffset, viewFor } from './pins.js';
 
 /** Shared image surface. Panels choose sources; this owns viewing behaviour. */
 export class CompareViewer {
@@ -7,6 +8,7 @@ export class CompareViewer {
     this.mode = ['single', 'side', 'wipe'].includes(defaultView) ? defaultView : left.id === right.id ? 'single' : aligned ? 'wipe' : 'side';
     this.zoom = native ? 1 : 'fit'; this.center = {x: .5, y: .5};
     this.division = 50; this.swapped = false; this.blink = false; this.loaded = new Map();
+    this.pins = []; this.pinMode = false;
     this.root = el('section', {class: 'compare-viewer', 'aria-label': 'Photo comparison'});
     this.modeSelect = select('Comparison view', [{value: 'wipe', label: 'Before / after'}, {value: 'side', label: 'Side by side'}, {value: 'single', label: 'Single image'}], this.mode, value => { this.mode = value; this.renderSurface(); });
     this.fitButton = button('Fit', () => this.setZoom('fit'), {title: 'Fit photograph to view'});
@@ -21,8 +23,10 @@ export class CompareViewer {
       try { if (document.fullscreenElement) await document.exitFullscreen(); else await this.root.requestFullscreen(); }
       catch { this.note.textContent = 'Fullscreen is unavailable in this browser.'; }
     }, {class: 'icon-button', title: 'Fullscreen', 'aria-label': 'Fullscreen comparison'});
+    this.pinButton = button('Pin note', () => this.setPinMode(!this.pinMode), {title: 'Pin a note to a point on the photograph', 'aria-pressed': 'false', hidden: true});
+    this.pinCenterButton = button('Pin center', () => this.pinCenter(), {title: 'Pin a note at the center of the current view · P', hidden: true});
     this.toolbar = el('div', {class: 'viewer-toolbar'}, el('div', {class: 'control-group'}, this.modeSelect, zoomControl),
-      el('div', {class: 'control-group'}, button('⇄ Swap', () => this.swap(), {title: 'Swap sides · B'}),
+      el('div', {class: 'control-group'}, this.pinButton, this.pinCenterButton, button('⇄ Swap', () => this.swap(), {title: 'Swap sides · B'}),
         button('Center', () => { this.center = {x: .5, y: .5}; this.position(); }), this.fullscreenButton));
     this.surface = el('div', {class: 'compare-surface'});
     this.note = el('span', {}, 'Loading images…');
@@ -117,6 +121,7 @@ export class CompareViewer {
       }, el('span', {'aria-hidden': 'true'}, '↔'));
       this.surface.append(this.marker);
     } else { this.marker = null; }
+    this.renderPins();
     this.updateCapability(); this.position();
   }
   updateCapability() {
@@ -220,6 +225,10 @@ export class CompareViewer {
       pane.scale = scale;
       const x = this.zoom === 'fit' ? .5 : this.center.x, y = this.zoom === 'fit' ? .5 : this.center.y;
       Object.assign(pane.img.style, {width: `${w * scale}px`, height: `${h * scale}px`, left: `${width / 2 - x * w * scale}px`, top: `${height / 2 - y * h * scale}px`});
+      for (const marker of pane.markers || []) {
+        const at = markerOffset(marker.pin, {left: width / 2 - x * w * scale, top: height / 2 - y * h * scale, width: w * scale, height: h * scale});
+        Object.assign(marker.node.style, {left: `${at.left}px`, top: `${at.top}px`});
+      }
     }
     if (this.marker && this.panes[1]) {
       // B is the full backing image; A occupies the left side of the divider.
@@ -256,7 +265,8 @@ export class CompareViewer {
     if (pointerId != null && this.marker?.hasPointerCapture(pointerId)) this.marker.releasePointerCapture(pointerId);
   }
   pointerDown(e) {
-    if (e.target.closest('[role="slider"]')) return;
+    if (e.target.closest('[role="slider"]') || e.target.closest?.('.pin-marker')) return;
+    this.pinDown = this.pinMode && e.button === 0 && this.pointers.size === 0 ? {pointerId: e.pointerId, x: e.clientX, y: e.clientY, target: e.target} : null;
     if (e.pointerType === 'touch') {
       if (this.pointers.size >= 2) return;
       this.pointers.set(e.pointerId, {x: e.clientX, y: e.clientY});
@@ -291,6 +301,11 @@ export class CompareViewer {
     this.position(); e.preventDefault();
   }
   pointerUp(e) {
+    const down = this.pinDown;
+    if (down?.pointerId === e.pointerId) {
+      this.pinDown = null;
+      if (e.type === 'pointerup' && Math.hypot(e.clientX - down.x, e.clientY - down.y) < 6) this.addPinAt(e.clientX, e.clientY, down.target);
+    }
     if (this.pointers.has(e.pointerId)) {
       this.pointers.delete(e.pointerId);
       this.touchScroll = null;
@@ -312,5 +327,58 @@ export class CompareViewer {
       if (this.surface.hasPointerCapture(pointerId)) this.surface.releasePointerCapture(pointerId);
     }
   }
+  /** Enable pinned notes for `variantId`: `pins` are its saved pins; `handlers.onAdd(pin)` receives a new one. */
+  setPins(variantId, pins, handlers) {
+    this.pinVariant = variantId; this.pins = pins || []; this.pinHandlers = handlers;
+    this.pinButton.hidden = this.pinCenterButton.hidden = !handlers;
+    this.pinButton.disabled = this.pinCenterButton.disabled = this.pins.length >= MAX_PINS;
+    if (this.pinMode && this.pinButton.disabled) this.setPinMode(false);
+    this.renderPins();
+  }
+  setPinMode(value) {
+    this.pinMode = value && !this.pinButton.hidden && !this.pinButton.disabled;
+    this.pinButton.setAttribute('aria-pressed', String(this.pinMode));
+    this.surface.classList.toggle('pin-mode', this.pinMode);
+  }
+  renderPins() {
+    for (const pane of this.panes || []) {
+      for (const marker of pane.markers || []) marker.node.remove();
+      pane.markers = [];
+      if (pane.item.id !== this.pinVariant) continue;
+      this.pins.forEach((pin, index) => {
+        const node = el('button', {type: 'button', class: 'pin-marker', title: pin.note || `Pin ${index + 1}`,
+          'aria-label': `Pinned note ${index + 1}${pin.note ? `: ${pin.note}` : ''}`,
+          onClick: e => { e.stopPropagation(); this.pinHandlers?.onSelect?.(pin); }}, String(index + 1));
+        pane.box.append(node); pane.markers.push({pin, node});
+      });
+    }
+    this.position();
+  }
+  addPinAt(clientX, clientY, target) {
+    if (!this.pinHandlers?.onAdd || this.pinButton.disabled) return;
+    const pane = this.paneAt(clientX, clientY, target);
+    if (pane?.item.id !== this.pinVariant) {
+      this.note.textContent = 'Pin notes on the version being reviewed.';
+      return;
+    }
+    const point = pane?.img.naturalWidth ? imagePoint(pane.img.getBoundingClientRect(), clientX, clientY) : null;
+    if (!point) return;
+    const other = [this.left, this.right].find(item => item.id !== this.pinVariant);
+    this.pinHandlers.onAdd(createPin({...point, zoom: this.zoom === 'fit' ? null : this.zoom, compareWith: other ? [other.id] : []}));
+  }
+  /** Keyboard route: pin the point at the center of the current view (the image center at Fit). */
+  pinCenter() {
+    if (!this.pinHandlers?.onAdd || this.pinCenterButton.disabled) return;
+    const center = this.zoom === 'fit' ? {x: .5, y: .5} : this.center;
+    const other = [this.left, this.right].find(item => item.id !== this.pinVariant);
+    this.pinHandlers.onAdd(createPin({x: Math.min(1, Math.max(0, center.x)), y: Math.min(1, Math.max(0, center.y)),
+      zoom: this.zoom === 'fit' ? null : this.zoom, compareWith: other ? [other.id] : []}));
+  }
+  /** Show the pinned point at the zoom it was pinned at (100% when pinned from Fit). */
+  focusPin(pin) {
+    const view = viewFor(pin);
+    this.center = view.center;
+    this.setZoom(view.zoom);
+  }
   stopDrag() { this.drag = null; this.surface.classList.remove('panning'); }
 }
diff --git a/review/web/panels/reviewer.js b/review/web/panels/reviewer.js
index 87e7248..4054365 100644
--- a/review/web/panels/reviewer.js
+++ b/review/web/panels/reviewer.js
@@ -1,7 +1,7 @@
 import {el} from '../dom.js';
 import {isSphere} from '../sphere-geometry.js';
 import {sphereReview} from './sphere.js';
-import {comparison, feedback, contextCard, artifacts, heading, regionCards} from './shared.js';
+import {comparison, feedback, contextCard, artifacts, heading, regionCards, pins} from './shared.js';
 
 export function reviewer(ctx) {
   if (isSphere(ctx.left) && isSphere(ctx.right)) return sphereReview(ctx);
@@ -9,6 +9,6 @@ export function reviewer(ctx) {
   const element = el('div', {class: 'panel-layout'},
     el('div', {class: 'view-column'}, heading(ctx), viewer.root,
       (ctx.photo.regions?.length > 0) && el('section', {class: 'below-view'}, el('div', {class: 'section-heading'}, el('h3', {}, 'Closer looks'), el('span', {class: 'muted'}, `${ctx.photo.regions.length} detail regions`)), regionCards(ctx, ctx.inspectRegion))),
-    el('aside', {class: 'inspector', 'aria-label': 'Photo review'}, contextCard(ctx), feedback(ctx), artifacts(ctx)));
+    el('aside', {class: 'inspector', 'aria-label': 'Photo review'}, contextCard(ctx), feedback(ctx), pins(ctx, viewer), artifacts(ctx)));
   return {element, viewer, destroy: () => viewer.destroy()};
 }
diff --git a/review/web/panels/shared.js b/review/web/panels/shared.js
index 34e9715..bddf96a 100644
--- a/review/web/panels/shared.js
+++ b/review/web/panels/shared.js
@@ -1,5 +1,6 @@
 import {el, button, field, media} from '../dom.js';
 import {CompareViewer} from '../compare.js';
+import {MAX_PINS, withNote, withoutPin} from '../pins.js';
 
 export function source(variant, region) {
   const detail = region?.images?.find(image => image.variantId === variant.id);
@@ -73,3 +74,28 @@ export function heading(ctx) {
       class: 'photo-disabled-toggle', 'aria-pressed': disabled ? 'true' : 'false',
       title: disabled ? 'Enable this photograph in the collection' : 'Keep this photograph in the collection but mark it as disabled'}));
 }
+/** Pinned notes for the reviewed version: a list beside the viewer's pin markers. */
+export function pins(ctx, viewer) {
+  const list = el('ol', {class: 'pin-list'});
+  const current = () => ctx.review().pins || [];
+  const save = next => { ctx.update({pins: next}); draw(); };
+  function draw() {
+    const items = current();
+    viewer.setPins(ctx.right.id, items, {
+      onAdd: pin => { if (current().length >= MAX_PINS) return; save([...current(), pin]); list.querySelector('li:last-child textarea')?.focus(); },
+      onSelect: pin => viewer.focusPin(pin)});
+    list.replaceChildren(...items.map((pin, index) => {
+      const note = el('textarea', {rows: 2, placeholder: 'What should change at this point?', 'aria-label': `Note for pin ${index + 1}`,
+        onInput: e => ctx.update({pins: withNote(current(), pin.id, e.target.value)}), onBlur: () => viewer.setPins(ctx.right.id, current(), viewer.pinHandlers)});
+      note.value = pin.note || '';
+      return el('li', {class: 'pin-item'}, el('div', {class: 'pin-item-head'}, el('span', {class: 'pin-number'}, String(index + 1)),
+        el('span', {class: 'muted'}, `${Math.round(pin.x * 100)}%, ${Math.round(pin.y * 100)}%${pin.zoom ? ` · ${Math.round(pin.zoom * 100)}%` : ''}`),
+        button('Go to', () => viewer.focusPin(pin)), button('Remove', () => save(withoutPin(current(), pin.id)), {'aria-label': `Remove pin ${index + 1}`})), note);
+    }));
+    empty.textContent = items.length >= MAX_PINS ? `This version has ${MAX_PINS} pinned notes. Remove one before adding another.` : 'Choose Pin note above the photograph, then click the spot on the version being reviewed. Pins keep their position and zoom for the next edit.';
+    empty.hidden = items.length > 0 && items.length < MAX_PINS;
+  }
+  const empty = el('p', {class: 'field-hint'}, 'Choose Pin note above the photograph, then click the spot you want changed. Pins keep their position and zoom for the next edit.');
+  draw();
+  return el('section', {class: 'inspector-section'}, el('h3', {}, 'Pinned notes'), empty, list);
+}
diff --git a/review/web/pins.js b/review/web/pins.js
new file mode 100644
index 0000000..f23f403
--- /dev/null
+++ b/review/web/pins.js
@@ -0,0 +1,30 @@
+/** Pinned notes: a note attached to a point on the photograph, in image-relative coordinates. */
+export const MAX_PINS = 200;
+
+/** Normalised (0-1) image coordinates of a pointer position, or null when outside the image. */
+export function imagePoint(rect, clientX, clientY) {
+  if (!rect.width || !rect.height) return null;
+  const x = (clientX - rect.left) / rect.width, y = (clientY - rect.top) / rect.height;
+  return x >= 0 && x <= 1 && y >= 0 && y <= 1 ? {x: round(x), y: round(y)} : null;
+}
+const round = value => Math.round(value * 1e5) / 1e5;
+
+export function createPin({x, y, zoom, compareWith}, id = globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`) {
+  const pin = {id, x, y, note: '', createdAt: new Date().toISOString()};
+  if (Number.isFinite(zoom) && zoom > 0) pin.zoom = round(zoom);
+  if (compareWith?.length) pin.compareWith = [...compareWith];
+  return pin;
+}
+
+/** Marker offset inside the pane for an image drawn at (left, top) with the given pixel size. */
+export function markerOffset(pin, {left, top, width, height}) {
+  return {left: left + pin.x * width, top: top + pin.y * height};
+}
+
+/** View that shows the pinned point: its recorded magnification, or 100% when it was pinned at Fit. */
+export function viewFor(pin) {
+  return {zoom: pin.zoom ?? 1, center: {x: pin.x, y: pin.y}};
+}
+
+export const withoutPin = (pins, id) => pins.filter(pin => pin.id !== id);
+export const withNote = (pins, id, note) => pins.map(pin => pin.id === id ? {...pin, note} : pin);
diff --git a/review/web/styles.css b/review/web/styles.css
index c65adf8..d90e1f6 100644
--- a/review/web/styles.css
+++ b/review/web/styles.css
@@ -750,3 +750,13 @@ textarea:disabled {
     margin-left:0;
   }
 }
+
+.pin-mode{cursor:crosshair}
+.pin-marker{position:absolute;z-index:4;width:24px;height:24px;min-height:0;padding:0;margin:-12px 0 0 -12px;border-radius:50%;box-shadow:0 1px 6px #0008;background:var(--accent);border:2px solid #17301d;color:#17301d;font-size:10px;font-weight:700}
+.pin-marker:enabled:hover{background:#fff;border-color:#17301d}
+.pin-list{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:12px}
+.pin-item{display:flex;flex-direction:column;gap:6px}
+.pin-item-head{display:flex;align-items:center;gap:8px}
+.pin-item-head button{font-size:10px;min-height:24px;padding:3px 8px}
+.pin-item-head .muted{flex:1}
+.pin-number{display:grid;place-items:center;width:20px;height:20px;border-radius:50%;background:var(--accent);color:#17301d;font-size:10px;font-weight:700}
diff --git a/scripts/check_public_repo.py b/scripts/check_public_repo.py
index 6d42f91..aecd904 100644
--- a/scripts/check_public_repo.py
+++ b/scripts/check_public_repo.py
@@ -11,9 +11,9 @@
 ROOT = Path(__file__).resolve().parents[1]
 EXACT = {
     '.gitignore', '.gitattributes', 'AGENTS.md', 'README.md', 'CONTRIBUTING.md', 'LICENSE',
-    '.github/workflows/validate.yml', 'scripts/check_public_repo.py', 'tests/test_workflow.py',
+    '.github/workflows/validate.yml', 'scripts/check_public_repo.py', 'tests/test_workflow.py', 'tests/test_edit_recipe.py',
     'skills/photo-edit-master/SKILL.md', 'workflow/README.md', 'workflow/build_suite.py',
-    'workflow/build_catalogue.py', 'workflow/verify_collection.py', 'workflow/catalogue.css',
+    'workflow/build_catalogue.py', 'workflow/edit_recipe.py', 'workflow/verify_collection.py', 'workflow/catalogue.css',
     'workflow/selection.example.json', 'workflow/evaluation-template.json',
     'assets/readme-hero.svg',
     'docs/getting-started.md', 'docs/ecosystem.md', 'docs/continuing-edits.md',
diff --git a/skills/photo-edit-master/SKILL.md b/skills/photo-edit-master/SKILL.md
index bbdf2c4..00cee41 100644
--- a/skills/photo-edit-master/SKILL.md
+++ b/skills/photo-edit-master/SKILL.md
@@ -73,11 +73,14 @@ Build the brightness hierarchy with local adjustments. For any subject against a
 | Environment (the same mask, inverted) | −0.3 to −1.0 EV; saturation −10 to −30; clarity −5 to −20; slightly cooler | Quiet, depth, separation |
 | Key area (eye, face, point of contact) | Small radial or brush: +0.1 to +0.4 EV | The first place the eye lands |
 | Frame edges | Vignette −10 to −35, or radial/linear burns −0.3 to −0.8 EV | Keeps the eye inside |
-| Sky / far background / bright foreground | Linear gradient −0.3 to −1.0 EV | Balance the frame; add depth |
+| Sky / far background / bright foreground | Linear gradient −0.3 to −1.0 EV, with a wide soft transition so no band shows | Balance the frame; add depth |
 | Light path (rim light, sunlit water) | Brush or gradient +0.1 to +0.4 EV, warmer | Tells where the light comes from |
+| Pale mass under or behind the subject (ice mound, rock, sand) | Feathered radial, about +0.4 EV worked on one frame (try +0.3 to +0.5) | Carries the eye to the subject without a visible mask |
 
 The ranges are starting points in common slider units: EV for exposure, −100 to 100 for the rest. Judge the result, not the number. Stronger moves are fine when edges stay clean. Build masks from the same subject selection so subject and environment share one boundary, then inspect both overlays for halos and missed areas (between feathers, legs, branches).
 
+Keep whatever the subject stands on or touches attached to it. A deep environment cut that swallows the perch, the ice under the feet or the water contact makes the subject float. After any deep cut, look at the support first.
+
 Create depth with atmosphere: far planes lighter and lower in contrast in mist, or darker in a spotlit scene. Separate near, middle and far planes with gradients or depth masks.
 
 ### 5. Colour
@@ -93,14 +96,15 @@ Create depth with atmosphere: far planes lighter and lower in contrast in mist,
 - Denoise before sharpening. Use dedicated denoise for high-ISO dusk and blue-hour files; sliders don't match it. Full-strength AI denoise can make feathers, fur and skin look waxy in close portraits; use a partial strength there and inspect at 100%.
 - Add texture and sharpening to the subject, not the background. Soft backgrounds should stay soft.
 - Glow, grain and lens blur only when they support the key. Keep them subtle enough to go unnoticed.
+- Avoid pulling highlights or whites hard on a clipped light source such as a low sun; on a test frame it became a flat grey disc with a visible ring. Lower overall exposure and add contrast instead, so the source stays bright.
 
 ### 7. Clean up
 
-Remove or subdue distractions yourself; don't wait to be asked. Candidates are bright specks, cut-off objects at the edges, stray branches crossing the subject, sensor dust, and litter or people that don't belong to the story. Keep whatever explains the moment (habitat, water droplets, prey, snow). Respect explicit keep instructions. Prefer an honest crop over an inpaint when the crop also improves the composition. Inspect every repair at 100%.
+Remove or subdue distractions yourself; don't wait to be asked. Match the method to the defect: a smooth, low-contrast flare ghost in clear sky can be neutralised with a feathered radial correction (exposure, tint, saturation) and no inpainting; inpaint structured objects. Candidates are bright specks, cut-off objects at the edges, stray branches crossing the subject, sensor dust, and litter or people that don't belong to the story. Keep whatever explains the moment (habitat, water droplets, prey, snow). Respect explicit keep instructions. Prefer an honest crop over an inpaint when the crop also improves the composition. Inspect every repair at 100%.
 
 ### 8. Deliver alternatives
 
-For a new photograph, deliver **two or three genuinely different interpretations**. Use the lead interpretation plus variations in key, colour or crop (for example *natural*, *dramatic*, *monochrome*). Name each one by its idea. When the user has an accepted style or asks for one version, deliver one strong candidate and keep alternatives internal.
+For a new photograph, deliver **two or three genuinely different interpretations**. Use the lead interpretation plus variations in key, colour or crop (for example *natural*, *dramatic*, *monochrome*). Name each one by its idea, and pick the styles that suit the photograph rather than a fixed set: [style and method notes](references/style-and-method-notes.md) records a four-frame wildlife comparison: what each style did and which settings failed. When the user has an accepted style or asks for one version, deliver one strong candidate and keep alternatives internal.
 
 ## Check before delivering
 
@@ -135,6 +139,10 @@ Fix defects before delivering. Treat the artistic questions as a conversation wi
 - **Colour casts presented as "style"**, such as teal water, cyan snow or magenta shadows.
 - **Every photo the same.** One grade applied to a whole series regardless of light.
 - **Over-cleaning.** Removing the habitat, droplets or prey that tell the story.
+- **Floating subject.** An environment cut deep enough that the perch, ice or water contact disappears.
+- **Grey plate for a sun.** Highlights and whites pulled hard on a blown source.
+- **Rim at 100%.** A pale halo around dark edges (wing tips, head) when a subject lift and environment cut are far apart (about 1 EV left one on a test frame) and the mask edge is soft. Shrink the difference and tighten the selection (grow −10, feather 4 worked there), then recheck at 100%.
+- **Monochrome that drops the accent.** The colour version depended on a beak, a light or an eye that grey can't carry.
 
 ## Genre guidance
 
@@ -148,6 +156,8 @@ Read the reference that matches the photograph's central relationship:
 - [Collections](references/collections.md): selecting and sequencing a book, essay or batch.
 - [Spherical photographs](references/spherical.md): 360° images and views selected from them.
 
+Also see [style and method notes](references/style-and-method-notes.md) for a wildlife style comparison.
+
 ## Personal style and feedback
 
 When a user profile, accepted edits or review comments exist, follow `photo-style-builder` and apply them **as moves**. "Too bright, keep the blue hour" means lower environment exposure and cooler white balance on the next edit, not a sentence saved to a profile. If a correction repeats, add it as one of that user's questions before delivery, kept in their profile rather than in this skill. When the user returns hand-edited versions, study what they changed (crop, masks, vignette, colour) and do that by default next time.
diff --git a/skills/photo-edit-master/references/style-and-method-notes.md b/skills/photo-edit-master/references/style-and-method-notes.md
new file mode 100644
index 0000000..cbea568
--- /dev/null
+++ b/skills/photo-edit-master/references/style-and-method-notes.md
@@ -0,0 +1,65 @@
+# Style and method notes
+
+What happened when the same photograph was edited several different ways. Use these notes to choose a style on purpose, set first values, and recognise a failing edit early. Numbers are in RapidRAW MCP units (EV for exposure, −100 to 100 for other sliders); they describe what worked on specific frames and are starting points, not targets.
+
+The comparison covered four RAW frames from one wildlife trip: a small white bird on a dark, out-of-focus field; two large birds far away on pale ice at blue hour; a raptor touching calm water at dusk; and a crane flying across the low sun. Each was edited in three deliberately different styles beside an unedited render, and every candidate was checked at 100%.
+
+This is a small, informal comparison: four frames, one trip, one editor's judgement, one editing application. Treat the findings as hypotheses to test on your own frame, not rules.
+
+## Choosing a style
+
+Style names: *natural luminous* is a gentle subject lift with a mild environment cut; *low-key* is a deep environment cut; *warm over cool* is warm highlights over cool shadows; *muted with accent* is a desaturated environment that leaves the subject's own colour.
+
+| Situation | Styles worth trying | What stood out |
+| :-- | :-- | :-- |
+| Bright subject on a dark, soft field | Natural luminous, low-key, monochrome | A mild environment cut already separates the subject. Deeper cuts add drama but start to cost the subject's support (see below). |
+| Tiny subjects in an empty, single-colour scene | Cropped natural, near-monochrome fog, warm over cool | On the sparse ice frame the crop did more than any slider. Settle the aspect (16:9, 2:1) before the tone work. |
+| Dark subject over water with colour accents | Natural, muted environment with accent colour, monochrome | Accent colour (beak, feet) disappears in monochrome; choose monochrome only when the picture works as pattern and gesture. |
+| Backlit subject against a blown source | Dark silhouette, luminous glow, monochrome | The source cannot be recovered; the style depends on whether it is a light or a hole. |
+
+## Findings
+
+### Separation: how much environment cut is enough
+
+- A white bird on dark bokeh separated with environment −0.3 EV, highlights −30, a light vignette (−18) and the subject +0.1 EV. This stayed natural.
+- Environment −1.3 EV with subject +0.4 gave a striking low-key result, but the perch and feet sank into black and the bird floated. The subject mask covers the animal, not what it stands on, so the support took the environment cut. After a deep cut, check that everything physically holding the subject still reads as attached.
+- Trying to widen the AI subject selection to include the perch (large region plus perch points) inverted the selection onto the background. If a support must be protected, use a brush correction on the environment mask, or keep the cut moderate and add depth with a gradient and vignette.
+- A subject lift and environment cut that together exceeded about 1 EV left a pale rim around dark wings at 100%. Reducing the difference to about 0.7 EV helped but did not clear it; setting grow −10 and feather 4 on the subject selection of both the subject and environment masks removed it. Check the rim at 100% along wing tips and the head, not at preview size.
+
+### Monochrome
+
+- Monochrome suited white-on-dark and dark-on-water frames: texture and ripple pattern became the picture, and a little grain (amount 15–28, size 25–30) made it feel photographic. Lifted blacks (+10 to +12) gave a film feel on the white bird frame.
+- It removed the eye colour and the beak/feet accents that carried the colour version. Pick it knowingly.
+- On a backlit silhouette the monochrome version was preferred on that frame, but only after the sun was handled as in the next section.
+
+### Backlit subject and a blown sun
+
+- Pulling highlights (−70) and whites (−40) on a clipped sun turns it into a flat grey plate with a visible ring. Keep highlights near 0 and lower overall exposure (−0.8 to −0.9) with strong contrast (+28), so the sun stays a source and the rim light on the wing edges stays bright.
+- A dark sky hides faint flare ghosts. A luminous, lifted treatment makes them more visible, so clean them in that style.
+- Smooth, low-contrast ghost discs in a clear sky do not need inpainting. A feathered radial correction centred on each disc (radius about 15% larger than the visible disc, feather 0.9, exposure −0.2 to −0.25, tint +6, saturation −25) made them effectively invisible at 100%. Use inpainting for structured objects, not for smooth gradients.
+- Glow and halation (about 10–35 for glow, 25 for halation) suit the luminous style; the silhouette style needed none.
+
+### Blue hour and empty scenes
+
+- A very dark, very blue frame came alive with a crop (about 40% of the frame, 16:9), exposure +1.3 EV, shadows +35, dehaze +8 and a light vignette. Denoise first (dedicated denoise, 0–100 scale, about 80 for ISO 2500); a heavy crop shows noise as well as softness, so treat the result as a screen picture rather than a print.
+- Near-monochrome fog (saturation −72, contrast −8, exposure +1.7, a wide 2:1 crop) turned the same scene into a minimal image in which the subjects read as ink marks. The flat contrast is the style; do not add contrast back.
+- Colour grading only tints what the white balance leaves behind. With a strong blue cast, warm highlights and cool shadows in the grade were barely visible until the white balance temperature itself moved warm (+18) and left the scene less blue. Set white balance for the amount of cast you want to keep, then grade.
+- Light contouring helped: a feathered radial dodge (+0.4 EV) on the pale mound under the birds and a gradient burn (−0.55 EV) along the foreground pulled the eye to the subjects without any visible mask.
+
+### Masks and gradients
+
+- Inspect a gradient's selection before judging the tone change. A hard transition or a burn on the wrong side of the frame can look like a tonal failure when the selection itself is the problem.
+- A subject selection can include gaps between spread wing feathers and lift the background inside them, leaving bright wedges between dark primaries. Exclude those gaps from the subject selection, include them in the environment, and recheck at 100%.
+
+For RapidRAW's linear-mask controls and gap corrections, use its [craft guide](https://github.com/sheldonxxxx/RapidRAW/blob/main/skills/rapidraw-mcp/references/craft-moves.md#linear-gradients).
+
+### Detail
+
+- Dedicated denoise at 100 (ISO 3200) left near-black plumage over-smoothed and etched-looking at 100% zoom. Use 60–70 for close plumage, and add grain if it looks waxy.
+
+## What not to do
+
+- Do not draw conclusions from the preview alone; the halo, the lost support and the sun's ring only showed at larger sizes.
+- Do not pull highlights on a clipped light source.
+- Do not convert to monochrome without checking what colour was carrying.
+- Do not widen a subject selection with a large region plus several points on a thin support; check the mask before building on it.
diff --git a/skills/photo-edit-master/references/wildlife.md b/skills/photo-edit-master/references/wildlife.md
index dbabf79..3685ff0 100644
--- a/skills/photo-edit-master/references/wildlife.md
+++ b/skills/photo-edit-master/references/wildlife.md
@@ -18,6 +18,12 @@ Use with the workflow in `SKILL.md` when an animal's presence, behaviour or rela
 
    Look at the mask before grading: on black-and-white birds, AI selections often drop the white shoulder or tail, the beak, the eye or the prey, and a depth band can lose a tail or far wingtip. Add include points or brush them in, then duplicate the finished selection inverted for the environment.
 
+   Keep the edge honest. When the subject is lifted and the surroundings are darkened, any band between the two masks receives neither edit and reads as a halo, worst where the source already has a soft or out-of-focus patch next to the subject. Pull the subject mask slightly inside the animal (a small negative grow and a few pixels of feather; the scale depends on the editor) rather than letting it spill onto the background; an edit that stops just inside the edge is less conspicuous than one that stops outside it. Build the environment as the inverse of that same mask so the two share one boundary. If a rim still shows at 100%, burn a narrow band along that stretch of edge instead of widening the subject mask.
+
+   Common mask mistakes: inverting a mask inverts everything it contains, so "region A except the subject" is A added with the subject subtracted, not an inverted mask. A linear gradient applies its adjustment on one side of its line only; check the overlay before grading. Compare the finished edit with a render that has only the global adjustments applied and look at every outline where the two differ.
+
+   Check the lifted subject's brightest parts at 100% with the clipping view: sunlit folds and whites clip first. Measure the subject against the brightest background area (snow, sky); the animal should stay the brightest element, so ease the environment before darkening it hard, since a heavy darkening merges trees and sky into one flat mass.
+
    On the subject: exposure up, shadows up, a little texture, a little warmth. On the environment: exposure down, saturation down, clarity down, slightly cooler. Adjust both until the animal separates at thumbnail size.
 2. **Eye.** If the eye is visible and sharp, give it a small dodge (+0.2 to +0.4 EV on a small radial or brush) and keep the catchlight. Never paint in a catchlight that isn't there.
 3. **Edges.** Burn corners and bright edge clutter. A vignette of −15 to −30 suits most wildlife frames; use radial burns instead when the subject is off-centre.
diff --git a/skills/photo-style-builder/SKILL.md b/skills/photo-style-builder/SKILL.md
index 16c7037..b1eddae 100644
--- a/skills/photo-style-builder/SKILL.md
+++ b/skills/photo-style-builder/SKILL.md
@@ -13,12 +13,16 @@ For a returning photographer, an existing profile, or feedback from earlier edit
 
 Update the evidence after feedback and distinguish a repeated execution failure from a new preference. Explore alternatives only when a consequential preference remains unresolved or the user requests them. Better first deliveries are the objective; acceptance by the photographer is the evidence, not a guarantee supplied by the skill.
 
+When the photographer returns editable versions of earlier work, compare the exact source and prior edit with each human revision before updating the profile. Treat framing, local light, texture, and cleanup as evidence alongside colour. Use the editor-specific skill to learn which operations produced the visible improvement; keep scene-specific settings and personal examples in the private workspace. A returned edit is evidence of the photographer's chosen treatment, but does not by itself settle book inclusion or make every operation a general preference.
+
 ## Begin from the photograph
 
 Establish or reuse a convincing image-specific base: meaningful attention, coherent light and colour, appropriate detail, and preserved context. When available, use photo-edit-master for that judgment and the appropriate execution tool for edits. A base is a defensible starting interpretation, not a compulsory neutral look. Keep its render and editable state available throughout exploration.
 
 Read any workspace profile and the user's current brief before proposing directions. Distinguish preferences they have accepted from agent hypotheses. If the user values an existing edit, retain that version as the reference for its successful qualities. Never replace it merely because a newer version exists.
 
+If the photographer asks for a skill-only blind round, use the skills and new original photographs without opening the private profile, earlier edits, human exports, prior review cases, visual anchors, or memory and prior conversation notes about those edits. Judge each new first candidate against its own original and the skill's principles, save that candidate with editable state and operation provenance before feedback, and defer comparison with older work until the photographer requests it. If review is needed, use a separate blind collection containing only the new original and candidate. This explicit evaluation mode overrides the normal reference-reading and collection-reuse steps elsewhere in this skill.
+
 When film colour or tone could support the photograph, read [choosing a film emulation](references/film-emulation.md). Use its conditional recommendations to suggest an available look, explain the visible reason and tradeoff, and decide what to compare. Keep this optional in ordinary editing; a film treatment must earn its place against the base.
 
 ## Explore through visible alternatives
@@ -45,6 +49,8 @@ Use photo-edit-master's collection judgment when available. Review accepted imag
 
 **Edit profile:** save qualitative, image-independent preferences, their intended use, important limits, and the accepted examples that support them. Express how the user wants light, colour, contrast, texture, and atmosphere to relate, using only the dimensions that matter. Separate supported preferences from unresolved ideas and say when a preference needs adaptation to subject or illumination. A profile guides image-specific judgment; it is not a universal exposure, crop, mask, or denoise prescription. Keep the profile in the user's workspace, independent of the shared master skill.
 
+Keep one current profile per photographer and intended scope at a stable workspace path. Update it in place as evidence changes, with an internal revision or date, rather than creating another numbered profile after every review. Before revising a profile used for a delivered edit, retain a recoverable snapshot of that revision, including for edits awaiting review. Keep those snapshots and exact edit comparisons as historical evidence, not competing current guidance.
+
 **Editor preset:** save an actual recipe exported from the editor and checked against the rendered candidate. Record the editor and version, source candidate, scope of included adjustments, and known applicability limits. Do not invent slider values, relabel prose as an executable preset, or carry scene-specific crops, masks, retouching, or adaptive settings into a general preset without a supported and validated reuse method. If the editor cannot export a suitable reusable recipe, save an edit profile and explain that limitation.
 
 Save on the user's requested scope or explicit acceptance; keep drafts identifiable when exploration is unfinished. When generalising beyond one photograph, test representative images if they are available and useful, and report which situations remain untested. Reopen the saved artifact, confirm its provenance and intended scope, and report the version the user selected separately from any agent recommendation.
diff --git a/skills/photo-style-builder/references/taste-learning.md b/skills/photo-style-builder/references/taste-learning.md
index c0bb809..c426852 100644
--- a/skills/photo-style-builder/references/taste-learning.md
+++ b/skills/photo-style-builder/references/taste-learning.md
@@ -2,6 +2,8 @@
 
 Learning should change the next edit. A profile that describes preferences but does not affect rendered decisions has not completed that work. Use this loop for revisions and new photographs alike, alongside image-specific judgment and the editor's execution workflow.
 
+For a photographer-requested skill-only blind round, use the skill text and new original photographs alone. Do not load the private profile, previous renders or recipes, human exports, prior review cases, or accepted anchors during planning, first edits, or their internal quality checks. Preserve each first candidate and the skill revision before feedback. Apply the evidence-reading and retrospective comparison sections below only after the photographer explicitly requests that analysis.
+
 ## Ground preferences in evidence
 
 Read the current brief and relevant review comments before editing. Reconcile each decision with its exact rendered version. Retain stable photograph and variant IDs, asset revision or file hash, feedback text, decision, and the accepted comparison where available. Conversation endorsements are valid evidence; identify them as such instead of inventing review checkmarks. Selection approval, artistic approval, rendered acceptance, and book inclusion are different decisions. An explicit hold or removal controls inclusion without erasing historical feedback.
@@ -17,6 +19,14 @@ For each consequential preference, retain compact fields in the private workspac
 
 Keep this proportional to the work. Link existing review records rather than duplicating every comment. Keep personal photographs, quotations, recipes, and taste profiles outside shared skill files.
 
+### Learn from a human-edited handoff
+
+Match each returned edit to the exact source and the version the photographer received. Verify identity before interpreting differences; keep missing returns separate from explicit rejection or exclusion. Compare native renders at whole-image or intended delivery size and relevant detail, using the same region when judging texture or retouching across different crops. Read editable state as evidence of *how* the result was made, then check the pixels to learn *why* it works. A slider or mask count alone cannot establish a taste preference.
+
+Record the few relationships that recur across unlike scenes, plus counterexamples. A closer crop in one frame and a wider crop in another can both express the same preference for deliberate subject placement. Likewise, subject detail and a quieter background may come from paired selections, controlled global tone, or a crop. Identify the successful decision and its limit rather than copying the operation or its numeric strength.
+
+Separate a human-authored revision, an explicitly accepted rendered version, and inclusion in a collection or book. Save exact file or variant provenance in the private evidence; update the qualitative profile only with supported interpretations. On the next applicable edit, compare the first delivered render with a matching human example and the earlier miss to test whether the lesson changed the result.
+
 ## Turn feedback into changed decisions
 
 Current explicit instructions control. Next use accepted examples and repeated corrections relevant to this image, then broader supported preferences, then general editorial judgment. A specific request for a brighter photograph can coexist with darkness in twilight scenes. A request to try monochrome on one image does not establish a monochrome collection style.
@@ -57,4 +67,4 @@ After a rule changes, replay the decision against a relevant accepted and reject
 
 Use the next applicable new photograph or batch to evaluate transfer. Preserve the first delivered rendition and the profile version used. After review, distinguish accepted first deliveries, artistic revisions, selection removals, holds, and unanswered cases. Report counts only from explicit decisions; do not score an unreviewed edit as accepted or fold source-selection rejection into artistic acceptance. Small samples and retrospective checks cannot establish a reliable success rate.
 
-When the same defect recurs, record the recurrence, inspect why the pre-delivery comparison missed it, and change the decision or checking process. Keep a new preference provisional until supported, and retain old accepted references when a later experiment fails. The profile should grow more useful and more selective, not merely longer.
+When the same defect recurs, record the recurrence, inspect why the pre-delivery comparison missed it, and change the decision or checking process. Keep a new preference provisional until supported, and retain old accepted references when a later experiment fails. Revise the one current profile at its stable path and keep detailed per-round evidence separately. The profile should grow more useful and more selective, not merely longer.
diff --git a/tests/test_edit_recipe.py b/tests/test_edit_recipe.py
new file mode 100644
index 0000000..51677bb
--- /dev/null
+++ b/tests/test_edit_recipe.py
@@ -0,0 +1,270 @@
+"""Recipe executor tests against a fake MCP engine."""
+import contextlib
+import copy
+import io
+import json
+from pathlib import Path
+import sys
+import tempfile
+import time
+import unittest
+
+REPO = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO / 'workflow'))
+import edit_recipe
+
+
+REVISION_TOOLS = {'set_adjustments', 'mask_create', 'mask_generate', 'mask_duplicate', 'mask_update', 'set_metadata', 'save_version'}
+
+
+class FakeEngine:
+    def revision_tools(self):
+        return REVISION_TOOLS
+
+    def __init__(self):
+        self.revision = 0
+        self.calls = []
+        self.masks = []
+        self.fail_render = False
+
+    def __call__(self, tool, args):
+        self.calls.append((tool, copy.deepcopy(args)))
+        if tool == 'get_session':
+            return {'revision': self.revision, 'adjustments': {'masks': copy.deepcopy(self.masks)}}
+        if 'expected_revision' in args and args['expected_revision'] != self.revision:
+            raise edit_recipe.RecipeError('REVISION_CONFLICT')
+        if tool == 'render_compare':
+            return {'images': ['x.jpg']}
+        if tool == 'render':
+            if self.fail_render:
+                raise edit_recipe.RecipeError('render failed')
+            return {'images': ['x.jpg']}
+        self.revision += 1
+        if tool in ('mask_generate', 'mask_create', 'mask_duplicate'):
+            mask = {'id': f'mask-{len(self.masks) + 1}', 'adjustments': dict(args.get('adjustments', {})),
+                    'subMasks': [{'id': f'sub-{len(self.masks) + 1}-0'}]}
+            self.masks.append(mask)
+            return {'revision': self.revision, 'mask_id': mask['id']}
+        if tool == 'mask_update':
+            mask = next(m for m in self.masks if m['id'] == args['mask_id'])
+            mask['adjustments'].update(args.get('patch', {}).get('adjustments', {}))
+        return {'revision': self.revision}
+
+
+RECIPE = {
+    'steps': [
+        {'id': 'base', 'tool': 'set_adjustments', 'args': {'mode': 'replace', 'patch': {'exposure': -0.1}}},
+        {'as': 'subject', 'tool': 'mask_generate', 'args': {'kind': 'subject', 'adjustments': {'exposure': 0.6}}},
+        {'as': 'environment', 'tool': 'mask_duplicate', 'args': {'mask_id': {'$mask': 'subject'}, 'invert': True}},
+        {'tool': 'mask_update', 'args': {'mask_id': {'$mask': 'environment'}, 'patch': {'adjustments': {'exposure': {'$param': 'dark'}}}}},
+        {'tool': 'mask_update', 'args': {'mask_id': {'$mask': 'subject'}, 'submask_operations': [
+            {'op': 'edit', 'submask_id': {'$submask': {'mask': 'subject', 'index': 0}}}]}},
+    ]
+}
+
+
+class RecipeTests(unittest.TestCase):
+    def write(self, directory, name, recipe):
+        path = Path(directory) / name
+        path.write_text(json.dumps(recipe))
+        return path
+
+    def test_run_tracks_revisions_and_resolves_references(self):
+        engine = FakeEngine()
+        result = edit_recipe.run(copy.deepcopy(RECIPE), engine, 'S', {'dark': -0.7})
+        self.assertEqual(result['masks'], {'subject': 'mask-1', 'environment': 'mask-2'})
+        self.assertEqual(result['revision'], 5)
+        updates = [args for tool, args in engine.calls if tool == 'mask_update']
+        self.assertEqual(updates[0]['mask_id'], 'mask-2')
+        self.assertEqual(updates[0]['patch']['adjustments']['exposure'], -0.7)
+        self.assertEqual(updates[1]['submask_operations'][0]['submask_id'], 'sub-1-0')
+        self.assertEqual([e['revision'] for e in result['log']], [1, 2, 3, 4, 5])
+
+    def test_missing_parameter_is_an_error(self):
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'dark'):
+            edit_recipe.run(copy.deepcopy(RECIPE), FakeEngine(), 'S')
+
+    def test_validate_rejects_unknown_mask_reference_and_managed_args(self):
+        bad = {'steps': [{'tool': 'mask_update', 'args': {'mask_id': {'$mask': 'ghost'}}}]}
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'ghost'):
+            edit_recipe.validate(bad)
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'managed'):
+            edit_recipe.validate({'steps': [{'tool': 'render', 'args': {'session_id': 'x'}}]})
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'only for steps that create'):
+            edit_recipe.validate({'steps': [{'as': 'x', 'tool': 'render'}]})
+
+    def test_extends_replaces_steps_by_id_and_appends_others(self):
+        with tempfile.TemporaryDirectory() as directory:
+            self.write(directory, 'parent.json', RECIPE)
+            child = {'extends': 'parent.json', 'steps': [
+                {'id': 'base', 'tool': 'set_adjustments', 'args': {'mode': 'replace', 'patch': {'exposure': 0.2}}},
+                {'tool': 'render', 'args': {'long_edge': 1600}},
+            ]}
+            recipe = edit_recipe.load(self.write(directory, 'child.json', child))
+        self.assertEqual(len(recipe['steps']), len(RECIPE['steps']) + 1)
+        self.assertEqual(recipe['steps'][0]['args']['patch'], {'exposure': 0.2})
+        self.assertEqual(recipe['steps'][-1]['tool'], 'render')
+        self.assertNotIn('extends', recipe)
+
+    def test_extends_cycle_is_rejected(self):
+        with tempfile.TemporaryDirectory() as directory:
+            self.write(directory, 'a.json', {'extends': 'b.json', 'steps': []})
+            self.write(directory, 'b.json', {'extends': 'a.json', 'steps': []})
+            with self.assertRaisesRegex(edit_recipe.RecipeError, 'extends itself'):
+                edit_recipe.load(Path(directory) / 'a.json')
+
+    def test_stop_after_halts_at_the_named_step(self):
+        engine = FakeEngine()
+        result = edit_recipe.run(copy.deepcopy(RECIPE), engine, 'S', {'dark': 0}, stop_after='base')
+        self.assertEqual(len(result['log']), 1)
+
+    def test_reference_render_switches_masks_off_without_touching_the_session(self):
+        engine = FakeEngine()
+        edit_recipe.run(copy.deepcopy(RECIPE), engine, 'S', {'dark': -0.7})
+        before, revision = copy.deepcopy(engine.masks), engine.revision
+        engine.calls.clear()
+        result = edit_recipe.render_without_mask_adjustments(engine, 'S', {'long_edge': 1600})
+        self.assertEqual(result, {'images': ['x.jpg']})
+        tool, args = engine.calls[-1]
+        self.assertEqual(tool, 'render_compare')
+        self.assertEqual(args['long_edge'], 1600)
+        self.assertEqual([v['label'] for v in args['variants']], ['Edit', 'Global only'])
+        self.assertNotIn('disabled_masks', args['variants'][0])
+        self.assertEqual(args['variants'][1]['disabled_masks'], ['mask-1', 'mask-2'])
+        self.assertEqual({tool for tool, _ in engine.calls}, {'get_session', 'render_compare'})
+        self.assertEqual((engine.masks, engine.revision), (before, revision))
+
+    def test_reference_render_can_limit_masks_and_rejects_empty_or_oversized_sets(self):
+        engine = FakeEngine()
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'no masks'):
+            edit_recipe.render_without_mask_adjustments(engine, 'S')
+        edit_recipe.run(copy.deepcopy(RECIPE), engine, 'S', {'dark': 0})
+        edit_recipe.render_without_mask_adjustments(engine, 'S', mask_ids={'mask-2'})
+        self.assertEqual(engine.calls[-1][1]['variants'][1]['disabled_masks'], ['mask-2'])
+        engine.masks = [{'id': f'm{i}', 'adjustments': {}} for i in range(edit_recipe.MAX_DISABLED_MASKS + 1)]
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'at most'):
+            edit_recipe.render_without_mask_adjustments(engine, 'S')
+
+    def test_expected_revision_goes_to_exactly_the_tools_the_engine_names(self):
+        engine = FakeEngine()
+        recipe = {'steps': [
+            {'tool': 'set_metadata', 'args': {'rating': 3}},
+            {'tool': 'save_version', 'args': {'label': 'first'}},
+            {'tool': 'render', 'args': {'long_edge': 800}},
+        ]}
+        edit_recipe.run(recipe, engine, 'S')
+        sent = {tool: 'expected_revision' in args for tool, args in engine.calls if tool != 'get_session'}
+        self.assertEqual(sent, {'set_metadata': True, 'save_version': True, 'render': False})
+        engine.calls.clear()
+        edit_recipe.run(recipe, engine, 'S', revision_tools=set())
+        self.assertFalse(any('expected_revision' in args for _, args in engine.calls))
+
+    def test_a_call_that_cannot_name_its_revision_tools_is_refused(self):
+        calls = []
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'revision_tools'):
+            edit_recipe.run(copy.deepcopy(RECIPE), lambda tool, args: calls.append(tool), 'S', {'dark': 0})
+        self.assertEqual(calls, [])
+
+    def test_missing_parameters_fail_before_the_first_engine_call(self):
+        self.assertEqual(edit_recipe.required_parameters(RECIPE), ['dark'])
+        engine = FakeEngine()
+        with self.assertRaisesRegex(edit_recipe.RecipeError, r"missing parameters \['dark'\]"):
+            edit_recipe.run(copy.deepcopy(RECIPE), engine, 'S', {})
+        self.assertEqual(engine.calls, [])
+
+    def test_cli_reports_parameters_and_rejects_a_run_missing_them_without_starting_a_client(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = self.write(directory, 'r.json', RECIPE)
+            with contextlib.redirect_stdout(io.StringIO()) as out:
+                self.assertEqual(edit_recipe.main(['validate', str(path)]), 0)
+            self.assertIn('parameters: dark', out.getvalue())
+            with contextlib.redirect_stderr(io.StringIO()) as err:
+                self.assertEqual(edit_recipe.main(['run', str(path), '--session', 'S', '--client', 'definitely-not-a-command']), 1)
+            self.assertIn('missing parameters', err.getvalue())
+    def test_cli_validate_and_flatten(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = self.write(directory, 'r.json', RECIPE)
+            self.assertEqual(edit_recipe.main(['validate', str(path)]), 0)
+            self.assertEqual(edit_recipe.main(['flatten', str(path)]), 0)
+            bad = self.write(directory, 'bad.json', {'steps': [{}]})
+            self.assertEqual(edit_recipe.main(['validate', str(bad)]), 1)
+
+
+FAKE_CLIENT = r"""
+import json, sys, time
+mode = sys.argv[1]
+print('startup noise that is not JSON', flush=True)
+if mode == 'no-ready':
+    sys.stderr.write('cannot connect to engine\n'); sys.stderr.flush(); time.sleep(30)
+print(json.dumps({'ready': True}), flush=True)
+for line in sys.stdin:
+    request = json.loads(line)
+    if request.get('close'):
+        break
+    if 'list_tools' in request:
+        tools = [{'name': 'rapidraw_set_adjustments', 'inputSchema': {'properties': {'expected_revision': {}, 'patch': {}}}},
+                 {'name': 'rapidraw_render', 'inputSchema': {'properties': {'long_edge': {}}}},
+                 {'name': 'rapidraw_save_version', 'inputSchema': {'properties': {'expected_revision': {}}}}]
+        print(json.dumps({'isError': False, 'data': {'tools': [] if mode == 'no-tools' else tools}}), flush=True)
+        continue
+    if mode == 'hang':
+        time.sleep(30)
+    if mode == 'crash':
+        sys.stderr.write('engine exploded\n'); sys.stderr.flush(); sys.exit(3)
+    print('log line before the reply', flush=True)
+    if request['tool'] == 'bad':
+        print(json.dumps({'isError': True, 'message': 'nope'}), flush=True)
+    else:
+        print(json.dumps({'isError': False, 'data': {'echo': request['arguments'], 'timeout': request['timeout_ms']}}), flush=True)
+"""
+
+
+class StdioClientTests(unittest.TestCase):
+    def client(self, mode, **options):
+        directory = tempfile.TemporaryDirectory()
+        self.addCleanup(directory.cleanup)
+        script = Path(directory.name) / 'client.py'
+        script.write_text(FAKE_CLIENT)
+        client = edit_recipe.StdioClient([sys.executable, str(script), mode], **options)
+        self.addCleanup(client.kill)
+        return client
+
+    def test_calls_skip_non_json_lines_and_report_tool_errors(self):
+        client = self.client('echo')
+        self.assertEqual(client('get_session', {'a': 1}, wait=5), {'echo': {'a': 1}, 'timeout': 5000})
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'bad failed'):
+            client('bad', {})
+        client.close()
+
+    def test_revision_tools_come_from_the_engine_schemas_once(self):
+        client = self.client('echo')
+        self.assertEqual(client.revision_tools(), {'set_adjustments', 'save_version'})
+        self.assertEqual(client.revision_tools(), {'set_adjustments', 'save_version'})
+        client.close()
+
+    def test_an_empty_tool_list_is_an_error_not_an_empty_set(self):
+        client = self.client('no-tools')
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'no tool list'):
+            client.revision_tools()
+
+    def test_a_client_that_never_becomes_ready_times_out_with_its_stderr(self):
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'ready signal within 1 s.*cannot connect to engine'):
+            self.client('no-ready', ready_timeout=1)
+
+    def test_a_hung_request_times_out_instead_of_blocking(self):
+        client = self.client('hang')
+        client.reply_grace = 0
+        started = time.monotonic()
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'no reply to slow within 1 s'):
+            client('slow', {}, wait=1)
+        self.assertLess(time.monotonic() - started, 10)
+        self.assertIsNotNone(client.process.poll())
+
+    def test_a_crashed_client_reports_its_last_stderr_lines(self):
+        client = self.client('crash')
+        with self.assertRaisesRegex(edit_recipe.RecipeError, 'closed before its reply to x.*engine exploded'):
+            client('x', {}, wait=5)
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/tests/test_review.py b/tests/test_review.py
index 2c81033..a6367cf 100644
--- a/tests/test_review.py
+++ b/tests/test_review.py
@@ -5,6 +5,7 @@
 import json
 import os
 from pathlib import Path
+import re
 import subprocess
 import sys
 import tempfile
@@ -14,6 +15,7 @@
 
 REPO = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(REPO / 'review'))
+import server
 from server import ReviewError, ReviewServer, ReviewStore
 
 
@@ -180,6 +182,69 @@ def test_disable_toggle_works_while_media_is_missing(self):
         enabled = self.store.set_disabled('test', False)
         self.assertFalse(enabled['dataset']['disabled'])
 
+    def move_media(self, folder):
+        target = self.media / folder
+        target.mkdir()
+        for name in ('base.jpg', 'edit.jpg', 'detail.png', 'recipe.json'):
+            (self.media / name).rename(target / name)
+
+    def test_relocate_rewrites_paths_and_carries_feedback(self):
+        saved = self.store.put_feedback('test', self.feedback(checks={'overview': True}), self.record['version'])
+        old_revision = saved['dataset']['cases'][0]['variants'][1]['assetRevision']
+        self.move_media('moved')
+        dry = self.store.relocate([('base.jpg', 'moved/base.jpg')], dry_run=True)
+        self.assertEqual((dry['datasets'], dry['dryRun']), (1, True))
+        report = self.store.relocate([('base.jpg', 'moved/base.jpg'), ('edit.jpg', 'moved/edit.jpg'), ('detail.png', 'moved/detail.png'), ('recipe.json', 'moved/recipe.json')])
+        self.assertEqual(report['carried'], 2)
+        self.assertEqual(report['missing'], [])
+        fresh = self.store.get_dataset('test')
+        candidate = fresh['dataset']['cases'][0]['variants'][1]
+        self.assertEqual((candidate['image'], candidate['recipe']), ('moved/edit.jpg', 'moved/recipe.json'))
+        self.assertEqual(fresh['dataset']['cases'][0]['regions'][0]['images'][0]['image'], 'moved/detail.png')
+        self.assertNotEqual(candidate['assetRevision'], old_revision)
+        self.assertEqual(fresh['feedback']['one']['candidate']['decision'], 'accepted')
+        self.assertFalse(candidate['unavailable'])
+        self.assertEqual(fresh['version'], saved['version'] + 1)
+        self.assertEqual(len(list((self.store.workspace / 'backups').glob('state.before-relocate-*.json'))), 1)
+
+    def test_relocate_refuses_when_media_is_missing_and_writes_nothing(self):
+        saved = self.store.put_feedback('test', self.feedback(), self.record['version'])
+        self.move_media('moved')
+        before = self.store.state_path.read_bytes()
+        with self.assertRaisesRegex(ReviewError, 'missing'):
+            self.store.relocate([('base.jpg', 'moved/base.jpg'), ('edit.jpg', 'elsewhere/edit.jpg'), ('detail.png', 'moved/detail.png'), ('recipe.json', 'moved/recipe.json')])
+        self.assertEqual(self.store.state_path.read_bytes(), before)
+        self.assertEqual(self.store.get_dataset('test')['version'], saved['version'] + 1)
+
+    def test_relocate_does_not_vouch_for_changed_media(self):
+        self.store.put_feedback('test', self.feedback(), self.record['version'])
+        self.move_media('moved')
+        (self.media / 'moved' / 'edit.jpg').write_bytes(b'different render')
+        self.store.relocate([('base.jpg', 'moved/base.jpg'), ('edit.jpg', 'moved/edit.jpg'), ('detail.png', 'moved/detail.png'), ('recipe.json', 'moved/recipe.json')])
+        fresh = self.store.get_dataset('test')
+        self.assertEqual(fresh['feedback']['one']['candidate']['decision'], '')
+
+    def test_archive_keeps_decisions_while_media_is_offline_and_unarchive_restores(self):
+        saved = self.store.put_feedback('test', self.feedback(), self.record['version'])
+        revision = saved['dataset']['cases'][0]['variants'][1]['assetRevision']
+        archived = self.store.set_archived('test', True, 'archive/202610/test.tar.zst')
+        self.assertTrue(archived['dataset']['archived'] and archived['dataset']['disabled'])
+        self.assertEqual(archived['dataset']['archivedTo'], 'archive/202610/test.tar.zst')
+        self.move_media('offline')
+        offline = self.store.get_dataset('test')
+        self.assertEqual(offline['feedback']['one']['candidate']['decision'], 'accepted')
+        self.assertEqual(offline['dataset']['cases'][0]['variants'][1]['assetRevision'], revision)
+        self.assertTrue(offline['dataset']['cases'][0]['variants'][1]['unavailable'])
+        self.assertTrue(self.store.workspace_summary()['datasets'][0]['archived'])
+        with self.assertRaisesRegex(ReviewError, 'Restore the media'):
+            self.store.set_archived('test', False)
+        for name in ('base.jpg', 'edit.jpg', 'detail.png', 'recipe.json'):
+            (self.media / 'offline' / name).rename(self.media / name)
+        restored = self.store.set_archived('test', False)
+        self.assertNotIn('archived', restored['dataset'])
+        self.assertEqual(restored['feedback']['one']['candidate']['decision'], 'accepted')
+        self.assertEqual(restored['dataset']['cases'][0]['variants'][1]['assetRevision'], revision)
+
     def test_photo_disable_toggle_preserves_feedback_and_defaults_other_cases(self):
         saved = self.store.put_feedback('test', self.feedback(), self.record['version'])
         disabled = self.store.set_case_disabled('test', 'one', True, saved['version'])
@@ -253,6 +318,26 @@ def test_region_geometry_and_feedback_reference_validation(self):
         with self.assertRaisesRegex(ReviewError, 'booleans'):
             self.store.put_feedback('test', feedback, self.record['version'])
 
+    def test_pinned_notes_are_validated_and_survive_round_trips(self):
+        pin = {'id': 'p1', 'x': 0.25, 'y': 0.75, 'zoom': 1, 'note': 'Halo at the wing edge', 'compareWith': ['baseline']}
+        feedback = self.feedback()
+        feedback['one']['candidate']['pins'] = [pin]
+        saved = self.store.put_feedback('test', feedback, self.record['version'])
+        self.assertEqual(saved['feedback']['one']['candidate']['pins'], [pin])
+        for bad in (
+            [{'id': 'a', 'x': 1.2, 'y': 0.5}], [{'id': 'a', 'x': 0.5, 'y': float('nan')}], [{'id': 'a', 'x': 0.5}],
+            [{'id': 'a', 'x': 0.5, 'y': 0.5, 'zoom': 0}], [{'id': 'a', 'x': 0.5, 'y': 0.5, 'note': 4}],
+            [{'id': 'a', 'x': 0.5, 'y': 0.5}, {'id': 'a', 'x': 0.1, 'y': 0.1}], [{'x': 0.5, 'y': 0.5}],
+            [{'id': 'a', 'x': 0.5, 'y': 0.5, 'compareWith': ['candidate']}],
+            [{'id': 'a', 'x': 0.5, 'y': 0.5, 'compareWith': ['missing']}],
+            [{'id': str(i), 'x': 0.5, 'y': 0.5} for i in range(201)], 'pin',
+            [{'id': 'a', 'x': 0.5, 'y': 0.5, 'blob': 'x' * 5000}], [{'id': 'a', 'x': 0.5, 'y': 0.5, 'createdAt': 5}],
+        ):
+            feedback = self.feedback()
+            feedback['one']['candidate']['pins'] = bad
+            with self.assertRaises(ReviewError, msg=repr(bad)[:80]):
+                self.store.put_feedback('test', feedback, saved['version'])
+
     def test_styles_preserve_provenance_and_exact_preset_snapshot(self):
         payload = {'name': 'Soft winter', 'kind': 'preset', 'datasetId': 'test', 'caseId': 'one', 'variantId': 'candidate', 'preferences': {'keep': 'Gentle highlight falloff'}}
         recipe = (self.media / 'recipe.json').read_bytes()
@@ -297,6 +382,79 @@ def write():
             thread.join()
         self.assertEqual(sorted(outcomes), [2, 409, 409, 409])
 
+    def test_pin_limit_matches_the_browser_constant(self):
+        script = (REPO / 'review/web/pins.js').read_text()
+        self.assertEqual(int(re.search(r'MAX_PINS = (\d+)', script)[1]), server.MAX_PINS)
+
+    def test_pin_fields_are_whitelisted(self):
+        pin = {'id': 'p', 'x': 0.5, 'y': 0.5, 'zoom': 2, 'note': 'n', 'compareWith': [], 'createdAt': '2026-10-02T00:00:00Z'}
+        feedback = self.feedback()
+        feedback['one']['candidate']['pins'] = [pin]
+        saved = self.store.put_feedback('test', feedback, self.record['version'])
+        self.assertEqual(saved['feedback']['one']['candidate']['pins'], [pin])
+
+    def test_add_variants_is_append_only_and_preserves_feedback(self):
+        (self.media / 'edit-r2.jpg').write_bytes(b'revision two bytes')
+        saved = self.store.put_feedback('test', self.feedback(), self.record['version'])
+        before = copy.deepcopy(saved['dataset']['cases'][0]['variants'])
+        added = self.store.add_variants('test', [{'caseId': 'one', 'select': True, 'variant': {'id': 'candidate-r2', 'label': 'Revision 2', 'image': 'edit-r2.jpg', 'metadata': {'parentVariantId': 'candidate'}}}], saved['version'])
+        case = added['dataset']['cases'][0]
+        self.assertEqual([v['id'] for v in case['variants']], ['baseline', 'candidate', 'candidate-r2'])
+        self.assertEqual(case['variants'][2]['role'], 'candidate')
+        self.assertEqual(case['selectedVariantId'], 'candidate-r2')
+        self.assertEqual(added['version'], saved['version'] + 1)
+        for old, new in zip(before, case['variants']):
+            self.assertEqual(old, new)
+        self.assertEqual(added['feedback'], saved['feedback'])
+
+    def test_add_variants_inserts_after_last_candidate_before_references(self):
+        (self.media / 'ref.jpg').write_bytes(b'reference bytes')
+        (self.media / 'new.jpg').write_bytes(b'new bytes')
+        data = copy.deepcopy(self.dataset)
+        data['cases'][0]['variants'].append({'id': 'reference', 'label': 'Reference', 'role': 'reference', 'image': 'ref.jpg'})
+        record = self.store.put_dataset('test', data, self.record['version'])
+        added = self.store.add_variants('test', [{'caseId': 'one', 'variant': {'id': 'candidate-b', 'image': 'new.jpg'}}], record['version'])
+        self.assertEqual([v['id'] for v in added['dataset']['cases'][0]['variants']], ['baseline', 'candidate', 'candidate-b', 'reference'])
+
+    def test_add_variants_refuses_replacement_and_applies_batches_atomically(self):
+        (self.media / 'new.jpg').write_bytes(b'new bytes')
+        with self.assertRaises(ReviewError) as caught:
+            self.store.add_variants('test', [{'caseId': 'one', 'variant': {'id': 'candidate', 'image': 'new.jpg'}}])
+        self.assertEqual(caught.exception.status, 409)
+        with self.assertRaisesRegex(ReviewError, 'Case not found'):
+            self.store.add_variants('test', [{'caseId': 'one', 'variant': {'id': 'ok', 'image': 'new.jpg'}}, {'caseId': 'missing', 'variant': {'id': 'x', 'image': 'new.jpg'}}])
+        with self.assertRaises(ReviewError):
+            self.store.add_variants('test', [{'caseId': 'one', 'variant': {'id': 'ok', 'image': 'new.jpg'}}, {'caseId': 'one', 'variant': {'id': 'gone', 'image': 'does-not-exist.jpg'}}])
+        current = self.store.get_dataset('test')
+        self.assertEqual([v['id'] for v in current['dataset']['cases'][0]['variants']], ['baseline', 'candidate'])
+        self.assertEqual(current['version'], self.record['version'])
+        with self.assertRaises(ReviewError) as stale:
+            self.store.add_variants('test', [{'caseId': 'one', 'variant': {'id': 'ok', 'image': 'new.jpg'}}], self.record['version'] + 5)
+        self.assertEqual(stale.exception.status, 409)
+
+    def test_cli_add_variant_and_batch(self):
+        source = self.root / 'dataset.json'
+        source.write_text(json.dumps(self.dataset))
+        (self.media / 'r2.jpg').write_bytes(b'r2')
+        (self.media / 'r3.jpg').write_bytes(b'r3')
+        args = ['--workspace', str(self.root / 'cli-state'), '--media-root', str(self.media)]
+
+        def run(*command, ok=True):
+            result = subprocess.run([sys.executable, str(REPO / 'review/cli.py'), *command, *args], text=True, capture_output=True)
+            self.assertEqual(result.returncode == 0, ok, result.stderr)
+            return json.loads(result.stdout) if ok else result.stderr
+
+        run('import', str(source), '--id', 'test')
+        self.assertEqual(run('add-variant', 'test', 'one', '--id', 'candidate-r2', '--image', 'r2.jpg', '--parent', 'candidate', '--label', 'R2', '--select')['added'], 1)
+        self.assertIn('already exists', run('add-variant', 'test', 'one', '--id', 'candidate-r2', '--image', 'r2.jpg', ok=False))
+        batch = self.root / 'batch.json'
+        batch.write_text(json.dumps({'additions': [{'caseId': 'one', 'variant': {'id': 'candidate-r3', 'image': 'r3.jpg'}}]}))
+        run('add-variants', 'test', str(batch))
+        case = run('show', 'test')['dataset']['cases'][0]
+        self.assertEqual([v['id'] for v in case['variants']], ['baseline', 'candidate', 'candidate-r2', 'candidate-r3'])
+        self.assertEqual(case['variants'][2]['metadata'], {'parentVariantId': 'candidate'})
+        self.assertEqual(case['selectedVariantId'], 'candidate-r2')
+
     def test_native_cli_import_and_feedback_roundtrip(self):
         source = self.root / 'dataset.json'
         source.write_text(json.dumps(self.dataset))
@@ -328,6 +486,27 @@ def run(*command):
         self.assertIs(run('show', 'test')['dataset']['disabled'], True)
         self.assertIs(run('enable', 'test')['disabled'], False)
 
+    def test_cli_relocate_and_archive(self):
+        source = self.root / 'dataset.json'
+        source.write_text(json.dumps(self.dataset))
+        args = ['--workspace', str(self.root / 'cli-state'), '--media-root', str(self.media)]
+
+        def run(*command, ok=True):
+            result = subprocess.run([sys.executable, str(REPO / 'review/cli.py'), *command, *args], text=True, capture_output=True)
+            self.assertEqual(result.returncode == 0, ok, result.stderr)
+            return json.loads(result.stdout) if ok else result.stderr
+
+        run('import', str(source), '--id', 'test')
+        self.move_media('moved')
+        maps = [item for name in ('base.jpg', 'edit.jpg', 'detail.png', 'recipe.json') for item in ('--map', f'{name}=moved/{name}')]
+        self.assertEqual(run('relocate', *maps, '--dry-run')['datasets'], 1)
+        self.assertEqual(run('relocate', *maps)['missing'], [])
+        self.assertEqual(run('show', 'test')['dataset']['cases'][0]['variants'][0]['image'], 'moved/base.jpg')
+        self.assertIs(run('archive', 'test', '--to', 'a.tar.zst')['archived'], True)
+        self.assertIs(run('list')['datasets'][0]['archived'], True)
+        self.assertIs(run('unarchive', 'test')['archived'], False)
+        self.assertIn('OLD=NEW', run('relocate', '--map', 'bad', ok=False))
+
     def test_cli_dispatches_embedded_html_to_inert_importer(self):
         from cli import load_dataset
         raw = (self.media / 'base.jpg').read_bytes()
@@ -453,6 +632,18 @@ def test_http_photo_disable_endpoint_guards_versions(self):
         status, _, body = self.request('PUT', '/api/datasets/test/cases/one/disabled', {'disabled': False, 'version': 2})
         self.assertEqual((status, json.loads(body)['dataset']['cases'][0]['disabled']), (200, False))
 
+    def test_http_add_variant_endpoints_refuse_replacement(self):
+        (self.media / 'a.jpg').write_bytes(b'a')
+        (self.media / 'b.jpg').write_bytes(b'b')
+        status, _, body = self.request('POST', '/api/datasets/test/cases/one/variants', {'version': 1, 'select': True, 'variant': {'id': 'a', 'image': 'a.jpg'}})
+        self.assertEqual(status, 201)
+        record = json.loads(body)
+        self.assertEqual((record['version'], record['dataset']['cases'][0]['selectedVariantId']), (2, 'a'))
+        self.assertEqual(self.request('POST', '/api/datasets/test/cases/one/variants', {'version': 2, 'variant': {'id': 'a', 'image': 'b.jpg'}})[0], 409)
+        self.assertEqual(self.request('POST', '/api/datasets/test/cases/one/variants', {'version': 1, 'variant': {'id': 'b', 'image': 'b.jpg'}})[0], 409)
+        status, _, body = self.request('POST', '/api/datasets/test/variants', {'version': 2, 'additions': [{'caseId': 'one', 'variant': {'id': 'b', 'image': 'b.jpg'}}]})
+        self.assertEqual((status, json.loads(body)['version']), (201, 3))
+
     def test_http_profile_and_preset_export(self):
         payload = {'name': 'Winter', 'kind': 'preset', 'datasetId': 'test', 'caseId': 'one', 'variantId': 'candidate'}
         status, _, body = self.request('POST', '/api/profiles', payload)
diff --git a/workflow/README.md b/workflow/README.md
index 2db0513..6631b88 100644
--- a/workflow/README.md
+++ b/workflow/README.md
@@ -73,12 +73,49 @@ Use the [unified review application](../review/README.md) for ongoing edit, styl
 
 Never publish generated catalogues, manifests, or populated evaluations from a personal library. They can contain paths, identifiers, capture metadata, and photographs.
 
+## Describe an edit as a recipe
+
+Keep an edit as reviewable data: replay it, diff a new pass against the last, and store the exact steps beside the render. An edit recipe here is a Lightweft step list that drives the engine's tools; it is separate from the editor's own saved recipes and presets. `edit_recipe.py` keeps the edit as data instead of a one-off script. A recipe is JSON: ordered steps, each one RapidRAW MCP tool call. The executor adds the session ID, tracks the revision each mutation returns, and substitutes names for IDs the engine generates:
+
+```json
+{
+  "version": 1,
+  "steps": [
+    {"id": "base", "tool": "set_adjustments", "args": {"mode": "replace", "patch": {"exposure": -0.1, "contrast": 16}}},
+    {"as": "subject", "tool": "mask_generate",
+     "args": {"kind": "subject", "name": "Subject", "parameters": {"grow": -30, "feather": 2}, "adjustments": {"exposure": 0.6}}},
+    {"as": "environment", "tool": "mask_duplicate",
+     "args": {"mask_id": {"$mask": "subject"}, "name": "Environment", "invert": true}},
+    {"tool": "mask_update",
+     "args": {"mask_id": {"$mask": "environment"}, "patch": {"adjustments": {"exposure": {"$param": "environment_exposure"}}}}}
+  ]
+}
+```
+
+`"as"` names a mask the step creates and `{"$mask": "name"}` refers to it later. `{"$submask": {"mask": "name", "index": 0}}` resolves a submask ID from the live session, and `{"$param": "name"}` takes a value from the run. A recipe can use `extends` to load another file: the child's steps are appended and a step with the same `id` replaces the parent's, so a new pass is a small, reviewable difference. Tool names and argument shapes are the RapidRAW MCP server's; see its tool schemas.
+
+```sh
+python3 workflow/edit_recipe.py validate recipes/example.json
+python3 workflow/edit_recipe.py flatten recipes/example.json
+python3 workflow/edit_recipe.py run recipes/example.json --session SESSION_ID \
+  --param environment_exposure=-0.7 --log run-log.json \
+  --client node /path/to/rapidraw-mcp/scripts/mcp-client.mjs --server /path/to/RapidRAW/mcp/dist/index.js \
+  --binary /path/to/RapidRAW/src-tauri/target/release/rapidraw-mcp --workspace /path/to/client-workspace
+```
+
+**Run it.** `--client` must come last: everything after it is the command that starts the persistent client from the [rapidraw-mcp skill](https://github.com/sheldonxxxx/RapidRAW/tree/main/skills/rapidraw-mcp), and its flags (`--server`, `--binary`, `--workspace`) belong to that client. Open the photograph first and pass its session ID. From Python, `edit_recipe.run(recipe, call, session_id)` accepts any `call(tool, arguments)` that returns structured data and raises on error. The executor adds `expected_revision` to every tool whose input schema accepts it. The bundled client reads those schemas from the engine; another `call` provides a `revision_tools()` method, or pass `revision_tools=` to `run`. The returned log lists every step with the revision it produced, so the edit that produced a render can be stored beside it.
+
+**Failure behaviour.** `validate` lists the `--param` names a recipe needs, and `run` refuses to start until each one is supplied, so a missing value cannot stop an edit halfway. The client is read with deadlines: a client that never becomes ready, hangs on a request or exits reports its last stderr lines as an error instead of blocking.
+
+**Compare with and without masks.** `render_without_mask_adjustments` asks the engine's `render_compare` for the edit beside a copy with its masks switched off. Every kind of mask adjustment is excluded, and the session, its revision and its history are untouched, so there is nothing to restore. `render_compare` switches off at most 32 masks; pass `mask_ids` to choose which.
+
 ## Verify changes to these tools
 
 First install and activate the [development prerequisites](../CONTRIBUTING.md#develop-and-test), including Pillow for public showcase checks. Then run from the repository root:
 
 ```sh
 python3 -m unittest discover -s tests -p 'test_workflow.py' -v
+python3 -m unittest tests.test_edit_recipe -v
 python3 scripts/check_public_repo.py --working-tree
 ```
 
diff --git a/workflow/edit_recipe.py b/workflow/edit_recipe.py
new file mode 100644
index 0000000..1f0fe0e
--- /dev/null
+++ b/workflow/edit_recipe.py
@@ -0,0 +1,395 @@
+#!/usr/bin/env python3
+"""Declarative editing recipes for a RapidRAW MCP session.
+
+A recipe is a JSON document describing an edit as ordered steps, so a photograph's
+edit is data that can be reviewed, versioned, diffed and replayed, instead of a
+script that was patched pass after pass.
+
+```json
+{
+  "version": 1,
+  "extends": "base-recipe.json",
+  "steps": [
+    {"tool": "set_adjustments", "args": {"mode": "replace", "patch": {"exposure": -0.1}}},
+    {"as": "subject", "tool": "mask_generate",
+     "args": {"kind": "subject", "name": "Subject", "parameters": {"grow": -30, "feather": 2},
+              "adjustments": {"exposure": 0.6}}},
+    {"as": "environment", "tool": "mask_duplicate",
+     "args": {"mask_id": {"$mask": "subject"}, "name": "Environment", "invert": true}},
+    {"tool": "mask_update",
+     "args": {"mask_id": {"$mask": "environment"}, "patch": {"adjustments": {"exposure": -0.7}}}}
+  ]
+}
+```
+
+* Each step is one MCP tool call. `session_id` is added for you, and so is
+  `expected_revision` for every tool whose input schema accepts it. The engine says
+  which: the stdio client reads the tool schemas, and another `call` supplies the
+  same through a `revision_tools()` method or the `revision_tools` argument of
+  `run()`. The revision returned by each step feeds the next.
+* `"as": "name"` records the mask the step created. `{"$mask": "name"}` in any later
+  argument is replaced by that mask's ID.
+* `{"$submask": {"mask": "name", "index": 0}}` resolves to the ID of a submask by
+  position, read from the live session when needed.
+* `extends` loads another recipe first; the child's steps are appended, and a step
+  with the same `"id"` replaces the parent's step in place, so a new pass is a small
+  diff against the last one. The parent path is relative to the child.
+* `{"$param": "name"}` is replaced from `--param name=value` (JSON values) or the
+  `params` mapping, so one recipe can serve a family of photographs.
+
+The engine stays authoritative: this module only sequences calls and resolves
+references. Tool names and argument shapes are those of the RapidRAW MCP server.
+
+`run()` takes an injected `call(tool, arguments) -> dict` returning the tool's
+structured data and raising on error, so it works with any MCP client. The command
+line offers `validate` and `flatten` (no engine needed) and `run`, which drives the
+bundled stdio client from the rapidraw-mcp skill.
+"""
+from __future__ import annotations
+
+import argparse
+import collections
+import copy
+import json
+import queue
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+RESERVED_ARGS = {'session_id', 'expected_revision'}
+MAX_DISABLED_MASKS = 32
+
+
+class RecipeError(ValueError):
+    pass
+
+
+def load(path, _seen=()):
+    """Read a recipe, resolving `extends` into one flat document."""
+    path = Path(path).resolve()
+    if path in _seen:
+        raise RecipeError(f'recipe extends itself: {path}')
+    try:
+        recipe = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as error:
+        raise RecipeError(f'cannot read recipe {path}: {error}') from error
+    if not isinstance(recipe, dict) or not isinstance(recipe.get('steps'), list):
+        raise RecipeError(f'{path}: a recipe is an object with a "steps" array')
+    parent = recipe.get('extends')
+    if parent:
+        base = load(path.parent / parent, _seen + (path,))
+        recipe = _extend(base, recipe)
+    recipe.pop('extends', None)
+    validate(recipe, path)
+    return recipe
+
+
+def _extend(base, child):
+    steps = copy.deepcopy(base['steps'])
+    positions = {step['id']: i for i, step in enumerate(steps) if 'id' in step}
+    for step in child['steps']:
+        if 'id' in step and step['id'] in positions:
+            steps[positions[step['id']]] = copy.deepcopy(step)
+        else:
+            if 'id' in step:
+                positions[step['id']] = len(steps)
+            steps.append(copy.deepcopy(step))
+    merged = {**base, **{k: v for k, v in child.items() if k != 'steps'}}
+    merged['steps'] = steps
+    return merged
+
+
+def validate(recipe, source='recipe'):
+    names, ids = set(), set()
+    for index, step in enumerate(recipe['steps']):
+        where = f'{source} step {index}'
+        if not isinstance(step, dict) or not isinstance(step.get('tool'), str):
+            raise RecipeError(f'{where}: needs a "tool" name')
+        args = step.get('args', {})
+        if not isinstance(args, dict):
+            raise RecipeError(f'{where}: "args" must be an object')
+        if RESERVED_ARGS & set(args):
+            raise RecipeError(f'{where}: {sorted(RESERVED_ARGS & set(args))} are managed by the executor')
+        if 'id' in step:
+            if step['id'] in ids:
+                raise RecipeError(f'{where}: duplicate step id {step["id"]!r}')
+            ids.add(step['id'])
+        for ref in _references(args, '$mask'):
+            if ref not in names:
+                raise RecipeError(f'{where}: mask {ref!r} is not created by an earlier step')
+        for ref in _references(args, '$submask'):
+            if not isinstance(ref, dict) or ref.get('mask') not in names or not isinstance(ref.get('index'), int):
+                raise RecipeError(f'{where}: $submask needs an earlier mask name and an integer index')
+        if step.get('as'):
+            if step['tool'] not in {'mask_create', 'mask_generate', 'mask_duplicate'}:
+                raise RecipeError(f'{where}: "as" is only for steps that create a mask')
+            names.add(step['as'])
+
+
+def required_parameters(recipe):
+    """Names every `{"$param": name}` in the recipe, so a run can fail before its first call."""
+    return sorted({name for step in recipe['steps'] for name in _references(step.get('args', {}), '$param')})
+
+
+def _references(value, key):
+    if isinstance(value, dict):
+        if set(value) == {key}:
+            yield value[key]
+            return
+        for item in value.values():
+            yield from _references(item, key)
+    elif isinstance(value, list):
+        for item in value:
+            yield from _references(item, key)
+
+
+def _substitute(value, resolve):
+    if isinstance(value, dict):
+        if len(value) == 1:
+            (key, inner), = value.items()
+            if key in ('$mask', '$submask', '$param'):
+                return resolve(key, inner)
+        return {k: _substitute(v, resolve) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_substitute(v, resolve) for v in value]
+    return value
+
+
+def mask_id_of(data):
+    """The mask ID a mask-creating tool returned."""
+    mask = data.get('mask') if isinstance(data.get('mask'), dict) else {}
+    found = data.get('mask_id') or mask.get('id')
+    if not found:
+        raise RecipeError(f'the engine returned no mask id: {sorted(data)}')
+    return found
+
+
+def revision_tools_of(call, revision_tools=None):
+    """Names of the tools that take `expected_revision`: given, or asked of the engine through `call`."""
+    if revision_tools is None:
+        ask = getattr(call, 'revision_tools', None)
+        if ask is None:
+            raise RecipeError('cannot tell which tools take expected_revision: give call a revision_tools() '
+                              'method or pass revision_tools to run()')
+        revision_tools = ask()
+    return set(revision_tools)
+
+
+def run(recipe, call, session_id, params=None, log=None, stop_after=None, revision_tools=None):
+    """Replay `recipe` into an open session. Returns {'masks': {name: id}, 'revision': n, 'log': [...]}."""
+    params = params or {}
+    missing = [name for name in required_parameters(recipe) if name not in params]
+    if missing:
+        raise RecipeError(f'missing parameters {missing}: pass them with --param NAME=JSON before the run starts')
+    versioned = revision_tools_of(call, revision_tools)
+    state = call('get_session', {'session_id': session_id})
+    revision = state.get('revision', 0)
+    masks, journal = {}, [] if log is None else log
+
+    def resolve(key, inner):
+        if key == '$param':
+            if inner not in params:
+                raise RecipeError(f'missing parameter {inner!r}')
+            return params[inner]
+        if key == '$mask':
+            return masks[inner]
+        live = call('get_session', {'session_id': session_id, 'include_adjustments': True})
+        items = live.get('adjustments', {}).get('masks', [])
+        match = next((m for m in items if m.get('id') == masks[inner['mask']]), None)
+        subs = (match or {}).get('subMasks') or (match or {}).get('sub_masks') or []
+        if inner['index'] >= len(subs):
+            raise RecipeError(f'mask {inner["mask"]!r} has {len(subs)} submasks, not index {inner["index"]}')
+        return subs[inner['index']]['id']
+
+    for index, step in enumerate(recipe['steps']):
+        args = _substitute(step.get('args', {}), resolve)
+        full = {'session_id': session_id, **args}
+        if step['tool'] in versioned:
+            full['expected_revision'] = revision
+        data = call(step['tool'], full)
+        revision = data.get('revision', revision)
+        if step.get('as'):
+            masks[step['as']] = mask_id_of(data)
+        journal.append({'step': index, 'id': step.get('id'), 'tool': step['tool'], 'args': args, 'revision': revision})
+        if stop_after is not None and step.get('id') == stop_after:
+            break
+    return {'masks': masks, 'revision': revision, 'log': journal}
+
+
+def render_without_mask_adjustments(call, session_id, render_args=None, mask_ids=None):
+    """Render the edit beside a copy with its masks switched off, without touching the session.
+
+    Uses the engine's `render_compare`, which applies the mask disabling to temporary
+    variants only: every mask adjustment (curves, colour grading, HSL, LUTs and the
+    rest) is excluded, the session revision and history do not change, and there is
+    nothing to restore. The result is the `render_compare` reply: variant "Edit" and
+    variant "Global only", rendered with the same crop and size, for judging what the
+    masks added. `render_args` may hold `long_edge` and `region`; `mask_ids` limits
+    which masks are switched off (all of them by default, at most 32).
+    """
+    live = call('get_session', {'session_id': session_id, 'include_adjustments': True})
+    masks = [m['id'] for m in live.get('adjustments', {}).get('masks', []) if mask_ids is None or m.get('id') in mask_ids]
+    if not masks:
+        raise RecipeError('the session has no masks to switch off')
+    if len(masks) > MAX_DISABLED_MASKS:
+        raise RecipeError(f'render_compare can switch off at most {MAX_DISABLED_MASKS} masks; pass mask_ids')
+    variants = [{'label': 'Edit'}, {'label': 'Global only', 'disabled_masks': masks}]
+    return call('render_compare', {'session_id': session_id, **(render_args or {}), 'variants': variants})
+
+
+class StdioClient:
+    """Drive the rapidraw-mcp skill's persistent client (`mcp-client.mjs`) over pipes.
+
+    Output is read on a background thread so every wait has a deadline: a hung or
+    crashed client raises a RecipeError that carries the client's last stderr lines
+    instead of blocking forever. Lines that are not JSON replies are skipped.
+    """
+
+    reply_grace = 30  # seconds beyond a request's own timeout before the client is declared hung
+
+    def __init__(self, command, ready_timeout=60):
+        self.process = subprocess.Popen(command, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                        stderr=subprocess.PIPE, text=True, bufsize=1)
+        self._revision_tools = None
+        self._replies = queue.Queue()
+        self._errors = collections.deque(maxlen=20)
+        threading.Thread(target=self._pump_stdout, daemon=True).start()
+        threading.Thread(target=self._pump_stderr, daemon=True).start()
+        self._read(ready_timeout, lambda line: '"ready"' in line, 'ready signal')
+
+    def _pump_stdout(self):
+        try:
+            for line in self.process.stdout:
+                if line.startswith('{'):
+                    self._replies.put(line)
+        except (OSError, ValueError):  # stream closed by kill()
+            pass
+        self._replies.put(None)
+
+    def _pump_stderr(self):
+        try:
+            for line in self.process.stderr:
+                self._errors.append(line.rstrip())
+        except (OSError, ValueError):
+            pass
+
+    def _diagnostics(self):
+        tail = ' | '.join(self._errors)
+        return f' (client stderr: {tail[-600:]})' if tail else ''
+
+    def _read(self, timeout, accept, what):
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            try:
+                line = self._replies.get(timeout=max(remaining, 0.001))
+            except queue.Empty:
+                self.kill()
+                raise RecipeError(f'client gave no {what} within {timeout:g} s{self._diagnostics()}') from None
+            if line is None:
+                raise RecipeError(f'client closed before its {what}{self._diagnostics()}')
+            if accept(line):
+                return line
+
+    def __call__(self, tool, arguments, wait=600):
+        try:
+            self.process.stdin.write(json.dumps({'tool': tool, 'arguments': arguments, 'timeout_ms': wait * 1000}) + '\n')
+            self.process.stdin.flush()
+        except OSError as error:
+            raise RecipeError(f'client is not accepting requests: {error}{self._diagnostics()}') from error
+        reply = json.loads(self._read(wait + self.reply_grace, lambda line: True, f'reply to {tool}'))
+        if reply.get('isError'):
+            raise RecipeError(f'{tool} failed: {json.dumps(reply)[:800]}')
+        return reply.get('data', reply)
+
+    def revision_tools(self):
+        """Tools whose input schema accepts `expected_revision`, read once from the engine."""
+        if self._revision_tools is None:
+            self.process.stdin.write(json.dumps({'list_tools': []}) + '\n')
+            self.process.stdin.flush()
+            reply = json.loads(self._read(60 + self.reply_grace, lambda line: True, 'tool list'))
+            tools = (reply.get('data') or {}).get('tools') if not reply.get('isError') else None
+            if not isinstance(tools, list) or not tools:
+                raise RecipeError(f'client returned no tool list: {json.dumps(reply)[:300]}')
+            self._revision_tools = {tool['name'].removeprefix('rapidraw_') for tool in tools
+                                    if 'expected_revision' in (tool.get('inputSchema') or {}).get('properties', {})}
+        return set(self._revision_tools)
+
+    def kill(self):
+        if self.process.poll() is None:
+            self.process.kill()
+        self.process.wait()
+        for stream in (self.process.stdin, self.process.stdout, self.process.stderr):
+            try:
+                stream.close()
+            except OSError:
+                pass
+
+    def close(self):
+        try:
+            self.process.stdin.write('{"close":true}\n')
+            self.process.stdin.flush()
+        except OSError:
+            pass
+        try:
+            self.process.wait(timeout=30)
+        except subprocess.TimeoutExpired:
+            pass
+        self.kill()
+
+
+def _params(pairs):
+    result = {}
+    for pair in pairs or []:
+        name, _, raw = pair.partition('=')
+        try:
+            result[name] = json.loads(raw)
+        except json.JSONDecodeError:
+            result[name] = raw
+    return result
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest='command', required=True)
+    for name, text in (('validate', 'Check a recipe and its parents'), ('flatten', 'Print the recipe with `extends` resolved')):
+        item = sub.add_parser(name, help=text)
+        item.add_argument('recipe', type=Path)
+    runner = sub.add_parser('run', help='Replay a recipe into an open session')
+    runner.add_argument('recipe', type=Path)
+    runner.add_argument('--session', required=True, help='Session ID of the opened photograph')
+    runner.add_argument('--param', action='append', metavar='NAME=JSON')
+    runner.add_argument('--log', type=Path, help='Write the operation log here')
+    runner.add_argument('--client', nargs=argparse.REMAINDER, required=True,
+                        help='Command that starts the persistent MCP client, e.g. node mcp-client.mjs --server ...')
+    args = parser.parse_args(argv)
+    try:
+        recipe = load(args.recipe)
+        if args.command == 'validate':
+            names = required_parameters(recipe)
+            print(f'ok: {len(recipe["steps"])} steps' + (f'; parameters: {", ".join(names)}' if names else ''))
+        elif args.command == 'flatten':
+            print(json.dumps(recipe, indent=2))
+        else:
+            params = _params(args.param)
+            missing = [name for name in required_parameters(recipe) if name not in params]
+            if missing:
+                raise RecipeError(f'missing parameters {missing}: pass them with --param NAME=JSON')
+            client = StdioClient(args.client)
+            try:
+                result = run(recipe, client, args.session, params)
+            finally:
+                client.close()
+            if args.log:
+                args.log.write_text(json.dumps(result['log'], indent=2) + '\n')
+            print(json.dumps({'masks': result['masks'], 'revision': result['revision'], 'steps': len(result['log'])}, indent=2))
+    except RecipeError as error:
+        print(f'error: {error}', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())