feat(workflow): add editing recipes and persistent review notes

.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
 

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

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
 

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

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.

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.
 

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.