doc-detective 4.32.0 → 4.34.0

package/dist/common/src/schemas/schemas.json

@@ -30428,9 +30428,10 @@
                                                   "anyOf": [
                                                     {
                                                       "title": "Screenshot (simple)",
+                                                      "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                       "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                       "type": "string",
-                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                       "transform": [
                                                         "trim"
                                                       ]
@@ -30664,9 +30665,10 @@
                                                             },
                                                             "path": {
                                                               "title": "Screenshot (simple)",
+                                                              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                               "type": "string",
-                                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                               "transform": [
                                                                 "trim"
                                                               ]
@@ -30924,9 +30926,10 @@
                                                     "schemas": {
                                                       "path": {
                                                         "title": "Screenshot (simple)",
+                                                        "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                         "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                         "type": "string",
-                                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                         "transform": [
                                                           "trim"
                                                         ]
@@ -31160,9 +31163,10 @@
                                                               },
                                                               "path": {
                                                                 "title": "Screenshot (simple)",
+                                                                "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                                 "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                                 "type": "string",
-                                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                                 "transform": [
                                                                   "trim"
                                                                 ]
@@ -31636,9 +31640,10 @@
                                                           },
                                                           "path": {
                                                             "title": "Screenshot (simple)",
+                                                            "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                             "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                             "type": "string",
-                                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                             "transform": [
                                                               "trim"
                                                             ]
@@ -32020,6 +32025,7 @@
                                                     "image.png",
                                                     "static/images/image.png",
                                                     "/User/manny/projects/doc-detective/static/images/image.png",
+                                                    "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                                     "https://example.com/static/images/image.png",
                                                     {
                                                       "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -34454,10 +34460,11 @@
                                                         },
                                                         "overwrite": {
                                                           "type": "string",
-                                                          "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                          "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                           "enum": [
                                                             "true",
-                                                            "false"
+                                                            "false",
+                                                            "aboveVariation"
                                                           ]
                                                         },
                                                         "name": {
@@ -34515,6 +34522,88 @@
                                                               }
                                                             }
                                                           ]
+                                                        },
+                                                        "verify": {
+                                                          "title": "Recording verify guards",
+                                                          "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                          "type": "object",
+                                                          "additionalProperties": false,
+                                                          "properties": {
+                                                            "minDuration": {
+                                                              "type": "number",
+                                                              "description": "Fail if the video is shorter than this many seconds.",
+                                                              "minimum": 0
+                                                            },
+                                                            "maxDuration": {
+                                                              "type": "number",
+                                                              "description": "Fail if the video is longer than this many seconds.",
+                                                              "minimum": 0
+                                                            },
+                                                            "resolution": {
+                                                              "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                              "anyOf": [
+                                                                {
+                                                                  "type": "boolean",
+                                                                  "title": "Verify resolution (boolean)"
+                                                                },
+                                                                {
+                                                                  "type": "object",
+                                                                  "title": "Verify resolution (detailed)",
+                                                                  "additionalProperties": false,
+                                                                  "required": [
+                                                                    "width",
+                                                                    "height"
+                                                                  ],
+                                                                  "properties": {
+                                                                    "width": {
+                                                                      "type": "integer",
+                                                                      "minimum": 1
+                                                                    },
+                                                                    "height": {
+                                                                      "type": "integer",
+                                                                      "minimum": 1
+                                                                    }
+                                                                  }
+                                                                }
+                                                              ]
+                                                            },
+                                                            "notBlack": {
+                                                              "type": "boolean",
+                                                              "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                            }
+                                                          }
+                                                        },
+                                                        "checkpoints": {
+                                                          "title": "Recording checkpoints",
+                                                          "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                          "anyOf": [
+                                                            {
+                                                              "type": "boolean",
+                                                              "title": "Recording checkpoints (boolean)",
+                                                              "description": "If `true`, enables checkpoints with default settings."
+                                                            },
+                                                            {
+                                                              "type": "object",
+                                                              "title": "Recording checkpoints (detailed)",
+                                                              "additionalProperties": false,
+                                                              "properties": {
+                                                                "maxVariation": {
+                                                                  "type": "number",
+                                                                  "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                                  "default": 0.05,
+                                                                  "minimum": 0,
+                                                                  "maximum": 1
+                                                                },
+                                                                "directory": {
+                                                                  "type": "string",
+                                                                  "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                                  "transform": [
+                                                                    "trim"
+                                                                  ]
+                                                                }
+                                                              }
+                                                            }
+                                                          ]
                                                         }
                                                       },
                                                       "title": "Record (detailed)"
@@ -34776,10 +34865,11 @@
                                                           },
                                                           "overwrite": {
                                                             "type": "string",
-                                                            "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                            "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                             "enum": [
                                                               "true",
-                                                              "false"
+                                                              "false",
+                                                              "aboveVariation"
                                                             ]
                                                           },
                                                           "name": {
@@ -34837,6 +34927,88 @@
                                                                 }
                                                               }
                                                             ]
+                                                          },
+                                                          "verify": {
+                                                            "title": "Recording verify guards",
+                                                            "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                            "type": "object",
+                                                            "additionalProperties": false,
+                                                            "properties": {
+                                                              "minDuration": {
+                                                                "type": "number",
+                                                                "description": "Fail if the video is shorter than this many seconds.",
+                                                                "minimum": 0
+                                                              },
+                                                              "maxDuration": {
+                                                                "type": "number",
+                                                                "description": "Fail if the video is longer than this many seconds.",
+                                                                "minimum": 0
+                                                              },
+                                                              "resolution": {
+                                                                "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                                "anyOf": [
+                                                                  {
+                                                                    "type": "boolean",
+                                                                    "title": "Verify resolution (boolean)"
+                                                                  },
+                                                                  {
+                                                                    "type": "object",
+                                                                    "title": "Verify resolution (detailed)",
+                                                                    "additionalProperties": false,
+                                                                    "required": [
+                                                                      "width",
+                                                                      "height"
+                                                                    ],
+                                                                    "properties": {
+                                                                      "width": {
+                                                                        "type": "integer",
+                                                                        "minimum": 1
+                                                                      },
+                                                                      "height": {
+                                                                        "type": "integer",
+                                                                        "minimum": 1
+                                                                      }
+                                                                    }
+                                                                  }
+                                                                ]
+                                                              },
+                                                              "notBlack": {
+                                                                "type": "boolean",
+                                                                "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                              }
+                                                            }
+                                                          },
+                                                          "checkpoints": {
+                                                            "title": "Recording checkpoints",
+                                                            "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                            "anyOf": [
+                                                              {
+                                                                "type": "boolean",
+                                                                "title": "Recording checkpoints (boolean)",
+                                                                "description": "If `true`, enables checkpoints with default settings."
+                                                              },
+                                                              {
+                                                                "type": "object",
+                                                                "title": "Recording checkpoints (detailed)",
+                                                                "additionalProperties": false,
+                                                                "properties": {
+                                                                  "maxVariation": {
+                                                                    "type": "number",
+                                                                    "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                                    "default": 0.05,
+                                                                    "minimum": 0,
+                                                                    "maximum": 1
+                                                                  },
+                                                                  "directory": {
+                                                                    "type": "string",
+                                                                    "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                                    "transform": [
+                                                                      "trim"
+                                                                    ]
+                                                                  }
+                                                                }
+                                                              }
+                                                            ]
                                                           }
                                                         },
                                                         "title": "Record (detailed)"
@@ -34903,6 +35075,17 @@
                                                       "path": "results.mp4",
                                                       "engine": "ffmpeg"
                                                     },
+                                                    {
+                                                      "path": "results.mp4",
+                                                      "checkpoints": true
+                                                    },
+                                                    {
+                                                      "path": "results.mp4",
+                                                      "checkpoints": {
+                                                        "maxVariation": 0.02,
+                                                        "directory": "baselines/results"
+                                                      }
+                                                    },
                                                     {
                                                       "path": "results.mp4",
                                                       "engine": {
@@ -76067,9 +76250,10 @@
                                     "anyOf": [
                                       {
                                         "title": "Screenshot (simple)",
+                                        "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                         "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                         "type": "string",
-                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                         "transform": [
                                           "trim"
                                         ]
@@ -76303,9 +76487,10 @@
                                               },
                                               "path": {
                                                 "title": "Screenshot (simple)",
+                                                "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                 "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                 "type": "string",
-                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                 "transform": [
                                                   "trim"
                                                 ]
@@ -76563,9 +76748,10 @@
                                       "schemas": {
                                         "path": {
                                           "title": "Screenshot (simple)",
+                                          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                           "type": "string",
-                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                           "transform": [
                                             "trim"
                                           ]
@@ -76799,9 +76985,10 @@
                                                 },
                                                 "path": {
                                                   "title": "Screenshot (simple)",
+                                                  "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                   "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                   "type": "string",
-                                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                   "transform": [
                                                     "trim"
                                                   ]
@@ -77275,9 +77462,10 @@
                                             },
                                             "path": {
                                               "title": "Screenshot (simple)",
+                                              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                               "type": "string",
-                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                               "transform": [
                                                 "trim"
                                               ]
@@ -77659,6 +77847,7 @@
                                       "image.png",
                                       "static/images/image.png",
                                       "/User/manny/projects/doc-detective/static/images/image.png",
+                                      "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                       "https://example.com/static/images/image.png",
                                       {
                                         "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -80093,10 +80282,11 @@
                                           },
                                           "overwrite": {
                                             "type": "string",
-                                            "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                            "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                             "enum": [
                                               "true",
-                                              "false"
+                                              "false",
+                                              "aboveVariation"
                                             ]
                                           },
                                           "name": {
@@ -80154,6 +80344,88 @@
                                                 }
                                               }
                                             ]
+                                          },
+                                          "verify": {
+                                            "title": "Recording verify guards",
+                                            "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                            "type": "object",
+                                            "additionalProperties": false,
+                                            "properties": {
+                                              "minDuration": {
+                                                "type": "number",
+                                                "description": "Fail if the video is shorter than this many seconds.",
+                                                "minimum": 0
+                                              },
+                                              "maxDuration": {
+                                                "type": "number",
+                                                "description": "Fail if the video is longer than this many seconds.",
+                                                "minimum": 0
+                                              },
+                                              "resolution": {
+                                                "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                "anyOf": [
+                                                  {
+                                                    "type": "boolean",
+                                                    "title": "Verify resolution (boolean)"
+                                                  },
+                                                  {
+                                                    "type": "object",
+                                                    "title": "Verify resolution (detailed)",
+                                                    "additionalProperties": false,
+                                                    "required": [
+                                                      "width",
+                                                      "height"
+                                                    ],
+                                                    "properties": {
+                                                      "width": {
+                                                        "type": "integer",
+                                                        "minimum": 1
+                                                      },
+                                                      "height": {
+                                                        "type": "integer",
+                                                        "minimum": 1
+                                                      }
+                                                    }
+                                                  }
+                                                ]
+                                              },
+                                              "notBlack": {
+                                                "type": "boolean",
+                                                "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                              }
+                                            }
+                                          },
+                                          "checkpoints": {
+                                            "title": "Recording checkpoints",
+                                            "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                            "anyOf": [
+                                              {
+                                                "type": "boolean",
+                                                "title": "Recording checkpoints (boolean)",
+                                                "description": "If `true`, enables checkpoints with default settings."
+                                              },
+                                              {
+                                                "type": "object",
+                                                "title": "Recording checkpoints (detailed)",
+                                                "additionalProperties": false,
+                                                "properties": {
+                                                  "maxVariation": {
+                                                    "type": "number",
+                                                    "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                    "default": 0.05,
+                                                    "minimum": 0,
+                                                    "maximum": 1
+                                                  },
+                                                  "directory": {
+                                                    "type": "string",
+                                                    "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                    "transform": [
+                                                      "trim"
+                                                    ]
+                                                  }
+                                                }
+                                              }
+                                            ]
                                           }
                                         },
                                         "title": "Record (detailed)"
@@ -80415,10 +80687,11 @@
                                             },
                                             "overwrite": {
                                               "type": "string",
-                                              "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                              "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                               "enum": [
                                                 "true",
-                                                "false"
+                                                "false",
+                                                "aboveVariation"
                                               ]
                                             },
                                             "name": {
@@ -80476,6 +80749,88 @@
                                                   }
                                                 }
                                               ]
+                                            },
+                                            "verify": {
+                                              "title": "Recording verify guards",
+                                              "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                              "type": "object",
+                                              "additionalProperties": false,
+                                              "properties": {
+                                                "minDuration": {
+                                                  "type": "number",
+                                                  "description": "Fail if the video is shorter than this many seconds.",
+                                                  "minimum": 0
+                                                },
+                                                "maxDuration": {
+                                                  "type": "number",
+                                                  "description": "Fail if the video is longer than this many seconds.",
+                                                  "minimum": 0
+                                                },
+                                                "resolution": {
+                                                  "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                  "anyOf": [
+                                                    {
+                                                      "type": "boolean",
+                                                      "title": "Verify resolution (boolean)"
+                                                    },
+                                                    {
+                                                      "type": "object",
+                                                      "title": "Verify resolution (detailed)",
+                                                      "additionalProperties": false,
+                                                      "required": [
+                                                        "width",
+                                                        "height"
+                                                      ],
+                                                      "properties": {
+                                                        "width": {
+                                                          "type": "integer",
+                                                          "minimum": 1
+                                                        },
+                                                        "height": {
+                                                          "type": "integer",
+                                                          "minimum": 1
+                                                        }
+                                                      }
+                                                    }
+                                                  ]
+                                                },
+                                                "notBlack": {
+                                                  "type": "boolean",
+                                                  "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                }
+                                              }
+                                            },
+                                            "checkpoints": {
+                                              "title": "Recording checkpoints",
+                                              "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                              "anyOf": [
+                                                {
+                                                  "type": "boolean",
+                                                  "title": "Recording checkpoints (boolean)",
+                                                  "description": "If `true`, enables checkpoints with default settings."
+                                                },
+                                                {
+                                                  "type": "object",
+                                                  "title": "Recording checkpoints (detailed)",
+                                                  "additionalProperties": false,
+                                                  "properties": {
+                                                    "maxVariation": {
+                                                      "type": "number",
+                                                      "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                      "default": 0.05,
+                                                      "minimum": 0,
+                                                      "maximum": 1
+                                                    },
+                                                    "directory": {
+                                                      "type": "string",
+                                                      "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                      "transform": [
+                                                        "trim"
+                                                      ]
+                                                    }
+                                                  }
+                                                }
+                                              ]
                                             }
                                           },
                                           "title": "Record (detailed)"
@@ -80542,6 +80897,17 @@
                                         "path": "results.mp4",
                                         "engine": "ffmpeg"
                                       },
+                                      {
+                                        "path": "results.mp4",
+                                        "checkpoints": true
+                                      },
+                                      {
+                                        "path": "results.mp4",
+                                        "checkpoints": {
+                                          "maxVariation": 0.02,
+                                          "directory": "baselines/results"
+                                        }
+                                      },
                                       {
                                         "path": "results.mp4",
                                         "engine": {
@@ -106378,10 +106744,11 @@
           },
           "overwrite": {
             "type": "string",
-            "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+            "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
             "enum": [
               "true",
-              "false"
+              "false",
+              "aboveVariation"
             ]
           },
           "name": {
@@ -106439,6 +106806,88 @@
                 }
               }
             ]
+          },
+          "verify": {
+            "title": "Recording verify guards",
+            "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "minDuration": {
+                "type": "number",
+                "description": "Fail if the video is shorter than this many seconds.",
+                "minimum": 0
+              },
+              "maxDuration": {
+                "type": "number",
+                "description": "Fail if the video is longer than this many seconds.",
+                "minimum": 0
+              },
+              "resolution": {
+                "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                "anyOf": [
+                  {
+                    "type": "boolean",
+                    "title": "Verify resolution (boolean)"
+                  },
+                  {
+                    "type": "object",
+                    "title": "Verify resolution (detailed)",
+                    "additionalProperties": false,
+                    "required": [
+                      "width",
+                      "height"
+                    ],
+                    "properties": {
+                      "width": {
+                        "type": "integer",
+                        "minimum": 1
+                      },
+                      "height": {
+                        "type": "integer",
+                        "minimum": 1
+                      }
+                    }
+                  }
+                ]
+              },
+              "notBlack": {
+                "type": "boolean",
+                "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+              }
+            }
+          },
+          "checkpoints": {
+            "title": "Recording checkpoints",
+            "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+            "anyOf": [
+              {
+                "type": "boolean",
+                "title": "Recording checkpoints (boolean)",
+                "description": "If `true`, enables checkpoints with default settings."
+              },
+              {
+                "type": "object",
+                "title": "Recording checkpoints (detailed)",
+                "additionalProperties": false,
+                "properties": {
+                  "maxVariation": {
+                    "type": "number",
+                    "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                    "default": 0.05,
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "directory": {
+                    "type": "string",
+                    "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                    "transform": [
+                      "trim"
+                    ]
+                  }
+                }
+              }
+            ]
           }
         },
         "title": "Record (detailed)"
@@ -106700,10 +107149,11 @@
             },
             "overwrite": {
               "type": "string",
-              "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+              "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
               "enum": [
                 "true",
-                "false"
+                "false",
+                "aboveVariation"
               ]
             },
             "name": {
@@ -106761,6 +107211,88 @@
                   }
                 }
               ]
+            },
+            "verify": {
+              "title": "Recording verify guards",
+              "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "minDuration": {
+                  "type": "number",
+                  "description": "Fail if the video is shorter than this many seconds.",
+                  "minimum": 0
+                },
+                "maxDuration": {
+                  "type": "number",
+                  "description": "Fail if the video is longer than this many seconds.",
+                  "minimum": 0
+                },
+                "resolution": {
+                  "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                  "anyOf": [
+                    {
+                      "type": "boolean",
+                      "title": "Verify resolution (boolean)"
+                    },
+                    {
+                      "type": "object",
+                      "title": "Verify resolution (detailed)",
+                      "additionalProperties": false,
+                      "required": [
+                        "width",
+                        "height"
+                      ],
+                      "properties": {
+                        "width": {
+                          "type": "integer",
+                          "minimum": 1
+                        },
+                        "height": {
+                          "type": "integer",
+                          "minimum": 1
+                        }
+                      }
+                    }
+                  ]
+                },
+                "notBlack": {
+                  "type": "boolean",
+                  "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                }
+              }
+            },
+            "checkpoints": {
+              "title": "Recording checkpoints",
+              "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+              "anyOf": [
+                {
+                  "type": "boolean",
+                  "title": "Recording checkpoints (boolean)",
+                  "description": "If `true`, enables checkpoints with default settings."
+                },
+                {
+                  "type": "object",
+                  "title": "Recording checkpoints (detailed)",
+                  "additionalProperties": false,
+                  "properties": {
+                    "maxVariation": {
+                      "type": "number",
+                      "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                      "default": 0.05,
+                      "minimum": 0,
+                      "maximum": 1
+                    },
+                    "directory": {
+                      "type": "string",
+                      "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                      "transform": [
+                        "trim"
+                      ]
+                    }
+                  }
+                }
+              ]
             }
           },
           "title": "Record (detailed)"
@@ -106827,6 +107359,17 @@
         "path": "results.mp4",
         "engine": "ffmpeg"
       },
+      {
+        "path": "results.mp4",
+        "checkpoints": true
+      },
+      {
+        "path": "results.mp4",
+        "checkpoints": {
+          "maxVariation": 0.02,
+          "directory": "baselines/results"
+        }
+      },
       {
         "path": "results.mp4",
         "engine": {
@@ -134993,9 +135536,10 @@
                                                       "anyOf": [
                                                         {
                                                           "title": "Screenshot (simple)",
+                                                          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                           "type": "string",
-                                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                           "transform": [
                                                             "trim"
                                                           ]
@@ -135229,9 +135773,10 @@
                                                                 },
                                                                 "path": {
                                                                   "title": "Screenshot (simple)",
+                                                                  "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                                   "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                                   "type": "string",
-                                                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                                   "transform": [
                                                                     "trim"
                                                                   ]
@@ -135489,9 +136034,10 @@
                                                         "schemas": {
                                                           "path": {
                                                             "title": "Screenshot (simple)",
+                                                            "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                             "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                             "type": "string",
-                                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                             "transform": [
                                                               "trim"
                                                             ]
@@ -135725,9 +136271,10 @@
                                                                   },
                                                                   "path": {
                                                                     "title": "Screenshot (simple)",
+                                                                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                                     "type": "string",
-                                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                                     "transform": [
                                                                       "trim"
                                                                     ]
@@ -136201,9 +136748,10 @@
                                                               },
                                                               "path": {
                                                                 "title": "Screenshot (simple)",
+                                                                "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                                 "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                                 "type": "string",
-                                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                                 "transform": [
                                                                   "trim"
                                                                 ]
@@ -136585,6 +137133,7 @@
                                                         "image.png",
                                                         "static/images/image.png",
                                                         "/User/manny/projects/doc-detective/static/images/image.png",
+                                                        "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                                         "https://example.com/static/images/image.png",
                                                         {
                                                           "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -139019,10 +139568,11 @@
                                                             },
                                                             "overwrite": {
                                                               "type": "string",
-                                                              "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                              "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                               "enum": [
                                                                 "true",
-                                                                "false"
+                                                                "false",
+                                                                "aboveVariation"
                                                               ]
                                                             },
                                                             "name": {
@@ -139080,6 +139630,88 @@
                                                                   }
                                                                 }
                                                               ]
+                                                            },
+                                                            "verify": {
+                                                              "title": "Recording verify guards",
+                                                              "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                              "type": "object",
+                                                              "additionalProperties": false,
+                                                              "properties": {
+                                                                "minDuration": {
+                                                                  "type": "number",
+                                                                  "description": "Fail if the video is shorter than this many seconds.",
+                                                                  "minimum": 0
+                                                                },
+                                                                "maxDuration": {
+                                                                  "type": "number",
+                                                                  "description": "Fail if the video is longer than this many seconds.",
+                                                                  "minimum": 0
+                                                                },
+                                                                "resolution": {
+                                                                  "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                                  "anyOf": [
+                                                                    {
+                                                                      "type": "boolean",
+                                                                      "title": "Verify resolution (boolean)"
+                                                                    },
+                                                                    {
+                                                                      "type": "object",
+                                                                      "title": "Verify resolution (detailed)",
+                                                                      "additionalProperties": false,
+                                                                      "required": [
+                                                                        "width",
+                                                                        "height"
+                                                                      ],
+                                                                      "properties": {
+                                                                        "width": {
+                                                                          "type": "integer",
+                                                                          "minimum": 1
+                                                                        },
+                                                                        "height": {
+                                                                          "type": "integer",
+                                                                          "minimum": 1
+                                                                        }
+                                                                      }
+                                                                    }
+                                                                  ]
+                                                                },
+                                                                "notBlack": {
+                                                                  "type": "boolean",
+                                                                  "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                                }
+                                                              }
+                                                            },
+                                                            "checkpoints": {
+                                                              "title": "Recording checkpoints",
+                                                              "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                              "anyOf": [
+                                                                {
+                                                                  "type": "boolean",
+                                                                  "title": "Recording checkpoints (boolean)",
+                                                                  "description": "If `true`, enables checkpoints with default settings."
+                                                                },
+                                                                {
+                                                                  "type": "object",
+                                                                  "title": "Recording checkpoints (detailed)",
+                                                                  "additionalProperties": false,
+                                                                  "properties": {
+                                                                    "maxVariation": {
+                                                                      "type": "number",
+                                                                      "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                                      "default": 0.05,
+                                                                      "minimum": 0,
+                                                                      "maximum": 1
+                                                                    },
+                                                                    "directory": {
+                                                                      "type": "string",
+                                                                      "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                                      "transform": [
+                                                                        "trim"
+                                                                      ]
+                                                                    }
+                                                                  }
+                                                                }
+                                                              ]
                                                             }
                                                           },
                                                           "title": "Record (detailed)"
@@ -139341,10 +139973,11 @@
                                                               },
                                                               "overwrite": {
                                                                 "type": "string",
-                                                                "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                                "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                                 "enum": [
                                                                   "true",
-                                                                  "false"
+                                                                  "false",
+                                                                  "aboveVariation"
                                                                 ]
                                                               },
                                                               "name": {
@@ -139402,6 +140035,88 @@
                                                                     }
                                                                   }
                                                                 ]
+                                                              },
+                                                              "verify": {
+                                                                "title": "Recording verify guards",
+                                                                "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                                "type": "object",
+                                                                "additionalProperties": false,
+                                                                "properties": {
+                                                                  "minDuration": {
+                                                                    "type": "number",
+                                                                    "description": "Fail if the video is shorter than this many seconds.",
+                                                                    "minimum": 0
+                                                                  },
+                                                                  "maxDuration": {
+                                                                    "type": "number",
+                                                                    "description": "Fail if the video is longer than this many seconds.",
+                                                                    "minimum": 0
+                                                                  },
+                                                                  "resolution": {
+                                                                    "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                                    "anyOf": [
+                                                                      {
+                                                                        "type": "boolean",
+                                                                        "title": "Verify resolution (boolean)"
+                                                                      },
+                                                                      {
+                                                                        "type": "object",
+                                                                        "title": "Verify resolution (detailed)",
+                                                                        "additionalProperties": false,
+                                                                        "required": [
+                                                                          "width",
+                                                                          "height"
+                                                                        ],
+                                                                        "properties": {
+                                                                          "width": {
+                                                                            "type": "integer",
+                                                                            "minimum": 1
+                                                                          },
+                                                                          "height": {
+                                                                            "type": "integer",
+                                                                            "minimum": 1
+                                                                          }
+                                                                        }
+                                                                      }
+                                                                    ]
+                                                                  },
+                                                                  "notBlack": {
+                                                                    "type": "boolean",
+                                                                    "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                                  }
+                                                                }
+                                                              },
+                                                              "checkpoints": {
+                                                                "title": "Recording checkpoints",
+                                                                "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                                "anyOf": [
+                                                                  {
+                                                                    "type": "boolean",
+                                                                    "title": "Recording checkpoints (boolean)",
+                                                                    "description": "If `true`, enables checkpoints with default settings."
+                                                                  },
+                                                                  {
+                                                                    "type": "object",
+                                                                    "title": "Recording checkpoints (detailed)",
+                                                                    "additionalProperties": false,
+                                                                    "properties": {
+                                                                      "maxVariation": {
+                                                                        "type": "number",
+                                                                        "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                                        "default": 0.05,
+                                                                        "minimum": 0,
+                                                                        "maximum": 1
+                                                                      },
+                                                                      "directory": {
+                                                                        "type": "string",
+                                                                        "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                                        "transform": [
+                                                                          "trim"
+                                                                        ]
+                                                                      }
+                                                                    }
+                                                                  }
+                                                                ]
                                                               }
                                                             },
                                                             "title": "Record (detailed)"
@@ -139468,6 +140183,17 @@
                                                           "path": "results.mp4",
                                                           "engine": "ffmpeg"
                                                         },
+                                                        {
+                                                          "path": "results.mp4",
+                                                          "checkpoints": true
+                                                        },
+                                                        {
+                                                          "path": "results.mp4",
+                                                          "checkpoints": {
+                                                            "maxVariation": 0.02,
+                                                            "directory": "baselines/results"
+                                                          }
+                                                        },
                                                         {
                                                           "path": "results.mp4",
                                                           "engine": {
@@ -180632,9 +181358,10 @@
                                         "anyOf": [
                                           {
                                             "title": "Screenshot (simple)",
+                                            "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                             "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                             "type": "string",
-                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                             "transform": [
                                               "trim"
                                             ]
@@ -180868,9 +181595,10 @@
                                                   },
                                                   "path": {
                                                     "title": "Screenshot (simple)",
+                                                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                     "type": "string",
-                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                     "transform": [
                                                       "trim"
                                                     ]
@@ -181128,9 +181856,10 @@
                                           "schemas": {
                                             "path": {
                                               "title": "Screenshot (simple)",
+                                              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                               "type": "string",
-                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                               "transform": [
                                                 "trim"
                                               ]
@@ -181364,9 +182093,10 @@
                                                     },
                                                     "path": {
                                                       "title": "Screenshot (simple)",
+                                                      "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                       "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                       "type": "string",
-                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                       "transform": [
                                                         "trim"
                                                       ]
@@ -181840,9 +182570,10 @@
                                                 },
                                                 "path": {
                                                   "title": "Screenshot (simple)",
+                                                  "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                   "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                   "type": "string",
-                                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                   "transform": [
                                                     "trim"
                                                   ]
@@ -182224,6 +182955,7 @@
                                           "image.png",
                                           "static/images/image.png",
                                           "/User/manny/projects/doc-detective/static/images/image.png",
+                                          "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                           "https://example.com/static/images/image.png",
                                           {
                                             "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -184658,10 +185390,11 @@
                                               },
                                               "overwrite": {
                                                 "type": "string",
-                                                "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                 "enum": [
                                                   "true",
-                                                  "false"
+                                                  "false",
+                                                  "aboveVariation"
                                                 ]
                                               },
                                               "name": {
@@ -184719,6 +185452,88 @@
                                                     }
                                                   }
                                                 ]
+                                              },
+                                              "verify": {
+                                                "title": "Recording verify guards",
+                                                "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                "type": "object",
+                                                "additionalProperties": false,
+                                                "properties": {
+                                                  "minDuration": {
+                                                    "type": "number",
+                                                    "description": "Fail if the video is shorter than this many seconds.",
+                                                    "minimum": 0
+                                                  },
+                                                  "maxDuration": {
+                                                    "type": "number",
+                                                    "description": "Fail if the video is longer than this many seconds.",
+                                                    "minimum": 0
+                                                  },
+                                                  "resolution": {
+                                                    "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                    "anyOf": [
+                                                      {
+                                                        "type": "boolean",
+                                                        "title": "Verify resolution (boolean)"
+                                                      },
+                                                      {
+                                                        "type": "object",
+                                                        "title": "Verify resolution (detailed)",
+                                                        "additionalProperties": false,
+                                                        "required": [
+                                                          "width",
+                                                          "height"
+                                                        ],
+                                                        "properties": {
+                                                          "width": {
+                                                            "type": "integer",
+                                                            "minimum": 1
+                                                          },
+                                                          "height": {
+                                                            "type": "integer",
+                                                            "minimum": 1
+                                                          }
+                                                        }
+                                                      }
+                                                    ]
+                                                  },
+                                                  "notBlack": {
+                                                    "type": "boolean",
+                                                    "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                  }
+                                                }
+                                              },
+                                              "checkpoints": {
+                                                "title": "Recording checkpoints",
+                                                "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                "anyOf": [
+                                                  {
+                                                    "type": "boolean",
+                                                    "title": "Recording checkpoints (boolean)",
+                                                    "description": "If `true`, enables checkpoints with default settings."
+                                                  },
+                                                  {
+                                                    "type": "object",
+                                                    "title": "Recording checkpoints (detailed)",
+                                                    "additionalProperties": false,
+                                                    "properties": {
+                                                      "maxVariation": {
+                                                        "type": "number",
+                                                        "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                        "default": 0.05,
+                                                        "minimum": 0,
+                                                        "maximum": 1
+                                                      },
+                                                      "directory": {
+                                                        "type": "string",
+                                                        "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                        "transform": [
+                                                          "trim"
+                                                        ]
+                                                      }
+                                                    }
+                                                  }
+                                                ]
                                               }
                                             },
                                             "title": "Record (detailed)"
@@ -184980,10 +185795,11 @@
                                                 },
                                                 "overwrite": {
                                                   "type": "string",
-                                                  "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                  "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                   "enum": [
                                                     "true",
-                                                    "false"
+                                                    "false",
+                                                    "aboveVariation"
                                                   ]
                                                 },
                                                 "name": {
@@ -185041,6 +185857,88 @@
                                                       }
                                                     }
                                                   ]
+                                                },
+                                                "verify": {
+                                                  "title": "Recording verify guards",
+                                                  "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                  "type": "object",
+                                                  "additionalProperties": false,
+                                                  "properties": {
+                                                    "minDuration": {
+                                                      "type": "number",
+                                                      "description": "Fail if the video is shorter than this many seconds.",
+                                                      "minimum": 0
+                                                    },
+                                                    "maxDuration": {
+                                                      "type": "number",
+                                                      "description": "Fail if the video is longer than this many seconds.",
+                                                      "minimum": 0
+                                                    },
+                                                    "resolution": {
+                                                      "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                      "anyOf": [
+                                                        {
+                                                          "type": "boolean",
+                                                          "title": "Verify resolution (boolean)"
+                                                        },
+                                                        {
+                                                          "type": "object",
+                                                          "title": "Verify resolution (detailed)",
+                                                          "additionalProperties": false,
+                                                          "required": [
+                                                            "width",
+                                                            "height"
+                                                          ],
+                                                          "properties": {
+                                                            "width": {
+                                                              "type": "integer",
+                                                              "minimum": 1
+                                                            },
+                                                            "height": {
+                                                              "type": "integer",
+                                                              "minimum": 1
+                                                            }
+                                                          }
+                                                        }
+                                                      ]
+                                                    },
+                                                    "notBlack": {
+                                                      "type": "boolean",
+                                                      "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                    }
+                                                  }
+                                                },
+                                                "checkpoints": {
+                                                  "title": "Recording checkpoints",
+                                                  "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                  "anyOf": [
+                                                    {
+                                                      "type": "boolean",
+                                                      "title": "Recording checkpoints (boolean)",
+                                                      "description": "If `true`, enables checkpoints with default settings."
+                                                    },
+                                                    {
+                                                      "type": "object",
+                                                      "title": "Recording checkpoints (detailed)",
+                                                      "additionalProperties": false,
+                                                      "properties": {
+                                                        "maxVariation": {
+                                                          "type": "number",
+                                                          "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                          "default": 0.05,
+                                                          "minimum": 0,
+                                                          "maximum": 1
+                                                        },
+                                                        "directory": {
+                                                          "type": "string",
+                                                          "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                          "transform": [
+                                                            "trim"
+                                                          ]
+                                                        }
+                                                      }
+                                                    }
+                                                  ]
                                                 }
                                               },
                                               "title": "Record (detailed)"
@@ -185107,6 +186005,17 @@
                                             "path": "results.mp4",
                                             "engine": "ffmpeg"
                                           },
+                                          {
+                                            "path": "results.mp4",
+                                            "checkpoints": true
+                                          },
+                                          {
+                                            "path": "results.mp4",
+                                            "checkpoints": {
+                                              "maxVariation": 0.02,
+                                              "directory": "baselines/results"
+                                            }
+                                          },
                                           {
                                             "path": "results.mp4",
                                             "engine": {
@@ -228010,9 +228919,10 @@
                                           "anyOf": [
                                             {
                                               "title": "Screenshot (simple)",
+                                              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                               "type": "string",
-                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                               "transform": [
                                                 "trim"
                                               ]
@@ -228246,9 +229156,10 @@
                                                     },
                                                     "path": {
                                                       "title": "Screenshot (simple)",
+                                                      "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                       "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                       "type": "string",
-                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                       "transform": [
                                                         "trim"
                                                       ]
@@ -228506,9 +229417,10 @@
                                             "schemas": {
                                               "path": {
                                                 "title": "Screenshot (simple)",
+                                                "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                 "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                 "type": "string",
-                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                 "transform": [
                                                   "trim"
                                                 ]
@@ -228742,9 +229654,10 @@
                                                       },
                                                       "path": {
                                                         "title": "Screenshot (simple)",
+                                                        "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                         "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                         "type": "string",
-                                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                         "transform": [
                                                           "trim"
                                                         ]
@@ -229218,9 +230131,10 @@
                                                   },
                                                   "path": {
                                                     "title": "Screenshot (simple)",
+                                                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                     "type": "string",
-                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                     "transform": [
                                                       "trim"
                                                     ]
@@ -229602,6 +230516,7 @@
                                             "image.png",
                                             "static/images/image.png",
                                             "/User/manny/projects/doc-detective/static/images/image.png",
+                                            "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                             "https://example.com/static/images/image.png",
                                             {
                                               "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -232036,10 +232951,11 @@
                                                 },
                                                 "overwrite": {
                                                   "type": "string",
-                                                  "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                  "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                   "enum": [
                                                     "true",
-                                                    "false"
+                                                    "false",
+                                                    "aboveVariation"
                                                   ]
                                                 },
                                                 "name": {
@@ -232097,6 +233013,88 @@
                                                       }
                                                     }
                                                   ]
+                                                },
+                                                "verify": {
+                                                  "title": "Recording verify guards",
+                                                  "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                  "type": "object",
+                                                  "additionalProperties": false,
+                                                  "properties": {
+                                                    "minDuration": {
+                                                      "type": "number",
+                                                      "description": "Fail if the video is shorter than this many seconds.",
+                                                      "minimum": 0
+                                                    },
+                                                    "maxDuration": {
+                                                      "type": "number",
+                                                      "description": "Fail if the video is longer than this many seconds.",
+                                                      "minimum": 0
+                                                    },
+                                                    "resolution": {
+                                                      "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                      "anyOf": [
+                                                        {
+                                                          "type": "boolean",
+                                                          "title": "Verify resolution (boolean)"
+                                                        },
+                                                        {
+                                                          "type": "object",
+                                                          "title": "Verify resolution (detailed)",
+                                                          "additionalProperties": false,
+                                                          "required": [
+                                                            "width",
+                                                            "height"
+                                                          ],
+                                                          "properties": {
+                                                            "width": {
+                                                              "type": "integer",
+                                                              "minimum": 1
+                                                            },
+                                                            "height": {
+                                                              "type": "integer",
+                                                              "minimum": 1
+                                                            }
+                                                          }
+                                                        }
+                                                      ]
+                                                    },
+                                                    "notBlack": {
+                                                      "type": "boolean",
+                                                      "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                    }
+                                                  }
+                                                },
+                                                "checkpoints": {
+                                                  "title": "Recording checkpoints",
+                                                  "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                  "anyOf": [
+                                                    {
+                                                      "type": "boolean",
+                                                      "title": "Recording checkpoints (boolean)",
+                                                      "description": "If `true`, enables checkpoints with default settings."
+                                                    },
+                                                    {
+                                                      "type": "object",
+                                                      "title": "Recording checkpoints (detailed)",
+                                                      "additionalProperties": false,
+                                                      "properties": {
+                                                        "maxVariation": {
+                                                          "type": "number",
+                                                          "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                          "default": 0.05,
+                                                          "minimum": 0,
+                                                          "maximum": 1
+                                                        },
+                                                        "directory": {
+                                                          "type": "string",
+                                                          "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                          "transform": [
+                                                            "trim"
+                                                          ]
+                                                        }
+                                                      }
+                                                    }
+                                                  ]
                                                 }
                                               },
                                               "title": "Record (detailed)"
@@ -232358,10 +233356,11 @@
                                                   },
                                                   "overwrite": {
                                                     "type": "string",
-                                                    "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                    "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                     "enum": [
                                                       "true",
-                                                      "false"
+                                                      "false",
+                                                      "aboveVariation"
                                                     ]
                                                   },
                                                   "name": {
@@ -232419,6 +233418,88 @@
                                                         }
                                                       }
                                                     ]
+                                                  },
+                                                  "verify": {
+                                                    "title": "Recording verify guards",
+                                                    "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                    "type": "object",
+                                                    "additionalProperties": false,
+                                                    "properties": {
+                                                      "minDuration": {
+                                                        "type": "number",
+                                                        "description": "Fail if the video is shorter than this many seconds.",
+                                                        "minimum": 0
+                                                      },
+                                                      "maxDuration": {
+                                                        "type": "number",
+                                                        "description": "Fail if the video is longer than this many seconds.",
+                                                        "minimum": 0
+                                                      },
+                                                      "resolution": {
+                                                        "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                        "anyOf": [
+                                                          {
+                                                            "type": "boolean",
+                                                            "title": "Verify resolution (boolean)"
+                                                          },
+                                                          {
+                                                            "type": "object",
+                                                            "title": "Verify resolution (detailed)",
+                                                            "additionalProperties": false,
+                                                            "required": [
+                                                              "width",
+                                                              "height"
+                                                            ],
+                                                            "properties": {
+                                                              "width": {
+                                                                "type": "integer",
+                                                                "minimum": 1
+                                                              },
+                                                              "height": {
+                                                                "type": "integer",
+                                                                "minimum": 1
+                                                              }
+                                                            }
+                                                          }
+                                                        ]
+                                                      },
+                                                      "notBlack": {
+                                                        "type": "boolean",
+                                                        "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                      }
+                                                    }
+                                                  },
+                                                  "checkpoints": {
+                                                    "title": "Recording checkpoints",
+                                                    "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                    "anyOf": [
+                                                      {
+                                                        "type": "boolean",
+                                                        "title": "Recording checkpoints (boolean)",
+                                                        "description": "If `true`, enables checkpoints with default settings."
+                                                      },
+                                                      {
+                                                        "type": "object",
+                                                        "title": "Recording checkpoints (detailed)",
+                                                        "additionalProperties": false,
+                                                        "properties": {
+                                                          "maxVariation": {
+                                                            "type": "number",
+                                                            "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                            "default": 0.05,
+                                                            "minimum": 0,
+                                                            "maximum": 1
+                                                          },
+                                                          "directory": {
+                                                            "type": "string",
+                                                            "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                            "transform": [
+                                                              "trim"
+                                                            ]
+                                                          }
+                                                        }
+                                                      }
+                                                    ]
                                                   }
                                                 },
                                                 "title": "Record (detailed)"
@@ -232485,6 +233566,17 @@
                                               "path": "results.mp4",
                                               "engine": "ffmpeg"
                                             },
+                                            {
+                                              "path": "results.mp4",
+                                              "checkpoints": true
+                                            },
+                                            {
+                                              "path": "results.mp4",
+                                              "checkpoints": {
+                                                "maxVariation": 0.02,
+                                                "directory": "baselines/results"
+                                              }
+                                            },
                                             {
                                               "path": "results.mp4",
                                               "engine": {
@@ -272911,9 +274003,10 @@
                                                 "anyOf": [
                                                   {
                                                     "title": "Screenshot (simple)",
+                                                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                     "type": "string",
-                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                     "transform": [
                                                       "trim"
                                                     ]
@@ -273147,9 +274240,10 @@
                                                           },
                                                           "path": {
                                                             "title": "Screenshot (simple)",
+                                                            "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                             "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                             "type": "string",
-                                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                             "transform": [
                                                               "trim"
                                                             ]
@@ -273407,9 +274501,10 @@
                                                   "schemas": {
                                                     "path": {
                                                       "title": "Screenshot (simple)",
+                                                      "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                       "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                       "type": "string",
-                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                       "transform": [
                                                         "trim"
                                                       ]
@@ -273643,9 +274738,10 @@
                                                             },
                                                             "path": {
                                                               "title": "Screenshot (simple)",
+                                                              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                               "type": "string",
-                                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                               "transform": [
                                                                 "trim"
                                                               ]
@@ -274119,9 +275215,10 @@
                                                         },
                                                         "path": {
                                                           "title": "Screenshot (simple)",
+                                                          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                           "type": "string",
-                                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                           "transform": [
                                                             "trim"
                                                           ]
@@ -274503,6 +275600,7 @@
                                                   "image.png",
                                                   "static/images/image.png",
                                                   "/User/manny/projects/doc-detective/static/images/image.png",
+                                                  "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                                   "https://example.com/static/images/image.png",
                                                   {
                                                     "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -276937,10 +278035,11 @@
                                                       },
                                                       "overwrite": {
                                                         "type": "string",
-                                                        "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                        "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                         "enum": [
                                                           "true",
-                                                          "false"
+                                                          "false",
+                                                          "aboveVariation"
                                                         ]
                                                       },
                                                       "name": {
@@ -276998,6 +278097,88 @@
                                                             }
                                                           }
                                                         ]
+                                                      },
+                                                      "verify": {
+                                                        "title": "Recording verify guards",
+                                                        "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                        "type": "object",
+                                                        "additionalProperties": false,
+                                                        "properties": {
+                                                          "minDuration": {
+                                                            "type": "number",
+                                                            "description": "Fail if the video is shorter than this many seconds.",
+                                                            "minimum": 0
+                                                          },
+                                                          "maxDuration": {
+                                                            "type": "number",
+                                                            "description": "Fail if the video is longer than this many seconds.",
+                                                            "minimum": 0
+                                                          },
+                                                          "resolution": {
+                                                            "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                            "anyOf": [
+                                                              {
+                                                                "type": "boolean",
+                                                                "title": "Verify resolution (boolean)"
+                                                              },
+                                                              {
+                                                                "type": "object",
+                                                                "title": "Verify resolution (detailed)",
+                                                                "additionalProperties": false,
+                                                                "required": [
+                                                                  "width",
+                                                                  "height"
+                                                                ],
+                                                                "properties": {
+                                                                  "width": {
+                                                                    "type": "integer",
+                                                                    "minimum": 1
+                                                                  },
+                                                                  "height": {
+                                                                    "type": "integer",
+                                                                    "minimum": 1
+                                                                  }
+                                                                }
+                                                              }
+                                                            ]
+                                                          },
+                                                          "notBlack": {
+                                                            "type": "boolean",
+                                                            "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                          }
+                                                        }
+                                                      },
+                                                      "checkpoints": {
+                                                        "title": "Recording checkpoints",
+                                                        "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                        "anyOf": [
+                                                          {
+                                                            "type": "boolean",
+                                                            "title": "Recording checkpoints (boolean)",
+                                                            "description": "If `true`, enables checkpoints with default settings."
+                                                          },
+                                                          {
+                                                            "type": "object",
+                                                            "title": "Recording checkpoints (detailed)",
+                                                            "additionalProperties": false,
+                                                            "properties": {
+                                                              "maxVariation": {
+                                                                "type": "number",
+                                                                "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                                "default": 0.05,
+                                                                "minimum": 0,
+                                                                "maximum": 1
+                                                              },
+                                                              "directory": {
+                                                                "type": "string",
+                                                                "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                                "transform": [
+                                                                  "trim"
+                                                                ]
+                                                              }
+                                                            }
+                                                          }
+                                                        ]
                                                       }
                                                     },
                                                     "title": "Record (detailed)"
@@ -277259,10 +278440,11 @@
                                                         },
                                                         "overwrite": {
                                                           "type": "string",
-                                                          "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                          "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                           "enum": [
                                                             "true",
-                                                            "false"
+                                                            "false",
+                                                            "aboveVariation"
                                                           ]
                                                         },
                                                         "name": {
@@ -277320,6 +278502,88 @@
                                                               }
                                                             }
                                                           ]
+                                                        },
+                                                        "verify": {
+                                                          "title": "Recording verify guards",
+                                                          "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                          "type": "object",
+                                                          "additionalProperties": false,
+                                                          "properties": {
+                                                            "minDuration": {
+                                                              "type": "number",
+                                                              "description": "Fail if the video is shorter than this many seconds.",
+                                                              "minimum": 0
+                                                            },
+                                                            "maxDuration": {
+                                                              "type": "number",
+                                                              "description": "Fail if the video is longer than this many seconds.",
+                                                              "minimum": 0
+                                                            },
+                                                            "resolution": {
+                                                              "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                              "anyOf": [
+                                                                {
+                                                                  "type": "boolean",
+                                                                  "title": "Verify resolution (boolean)"
+                                                                },
+                                                                {
+                                                                  "type": "object",
+                                                                  "title": "Verify resolution (detailed)",
+                                                                  "additionalProperties": false,
+                                                                  "required": [
+                                                                    "width",
+                                                                    "height"
+                                                                  ],
+                                                                  "properties": {
+                                                                    "width": {
+                                                                      "type": "integer",
+                                                                      "minimum": 1
+                                                                    },
+                                                                    "height": {
+                                                                      "type": "integer",
+                                                                      "minimum": 1
+                                                                    }
+                                                                  }
+                                                                }
+                                                              ]
+                                                            },
+                                                            "notBlack": {
+                                                              "type": "boolean",
+                                                              "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                            }
+                                                          }
+                                                        },
+                                                        "checkpoints": {
+                                                          "title": "Recording checkpoints",
+                                                          "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                          "anyOf": [
+                                                            {
+                                                              "type": "boolean",
+                                                              "title": "Recording checkpoints (boolean)",
+                                                              "description": "If `true`, enables checkpoints with default settings."
+                                                            },
+                                                            {
+                                                              "type": "object",
+                                                              "title": "Recording checkpoints (detailed)",
+                                                              "additionalProperties": false,
+                                                              "properties": {
+                                                                "maxVariation": {
+                                                                  "type": "number",
+                                                                  "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                                  "default": 0.05,
+                                                                  "minimum": 0,
+                                                                  "maximum": 1
+                                                                },
+                                                                "directory": {
+                                                                  "type": "string",
+                                                                  "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                                  "transform": [
+                                                                    "trim"
+                                                                  ]
+                                                                }
+                                                              }
+                                                            }
+                                                          ]
                                                         }
                                                       },
                                                       "title": "Record (detailed)"
@@ -277386,6 +278650,17 @@
                                                     "path": "results.mp4",
                                                     "engine": "ffmpeg"
                                                   },
+                                                  {
+                                                    "path": "results.mp4",
+                                                    "checkpoints": true
+                                                  },
+                                                  {
+                                                    "path": "results.mp4",
+                                                    "checkpoints": {
+                                                      "maxVariation": 0.02,
+                                                      "directory": "baselines/results"
+                                                    }
+                                                  },
                                                   {
                                                     "path": "results.mp4",
                                                     "engine": {
@@ -320773,9 +322048,10 @@
                                           "anyOf": [
                                             {
                                               "title": "Screenshot (simple)",
+                                              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                               "type": "string",
-                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                               "transform": [
                                                 "trim"
                                               ]
@@ -321009,9 +322285,10 @@
                                                     },
                                                     "path": {
                                                       "title": "Screenshot (simple)",
+                                                      "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                       "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                       "type": "string",
-                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                       "transform": [
                                                         "trim"
                                                       ]
@@ -321269,9 +322546,10 @@
                                             "schemas": {
                                               "path": {
                                                 "title": "Screenshot (simple)",
+                                                "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                 "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                 "type": "string",
-                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                 "transform": [
                                                   "trim"
                                                 ]
@@ -321505,9 +322783,10 @@
                                                       },
                                                       "path": {
                                                         "title": "Screenshot (simple)",
+                                                        "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                         "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                         "type": "string",
-                                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                         "transform": [
                                                           "trim"
                                                         ]
@@ -321981,9 +323260,10 @@
                                                   },
                                                   "path": {
                                                     "title": "Screenshot (simple)",
+                                                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                     "type": "string",
-                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                     "transform": [
                                                       "trim"
                                                     ]
@@ -322365,6 +323645,7 @@
                                             "image.png",
                                             "static/images/image.png",
                                             "/User/manny/projects/doc-detective/static/images/image.png",
+                                            "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                             "https://example.com/static/images/image.png",
                                             {
                                               "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -324799,10 +326080,11 @@
                                                 },
                                                 "overwrite": {
                                                   "type": "string",
-                                                  "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                  "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                   "enum": [
                                                     "true",
-                                                    "false"
+                                                    "false",
+                                                    "aboveVariation"
                                                   ]
                                                 },
                                                 "name": {
@@ -324860,6 +326142,88 @@
                                                       }
                                                     }
                                                   ]
+                                                },
+                                                "verify": {
+                                                  "title": "Recording verify guards",
+                                                  "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                  "type": "object",
+                                                  "additionalProperties": false,
+                                                  "properties": {
+                                                    "minDuration": {
+                                                      "type": "number",
+                                                      "description": "Fail if the video is shorter than this many seconds.",
+                                                      "minimum": 0
+                                                    },
+                                                    "maxDuration": {
+                                                      "type": "number",
+                                                      "description": "Fail if the video is longer than this many seconds.",
+                                                      "minimum": 0
+                                                    },
+                                                    "resolution": {
+                                                      "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                      "anyOf": [
+                                                        {
+                                                          "type": "boolean",
+                                                          "title": "Verify resolution (boolean)"
+                                                        },
+                                                        {
+                                                          "type": "object",
+                                                          "title": "Verify resolution (detailed)",
+                                                          "additionalProperties": false,
+                                                          "required": [
+                                                            "width",
+                                                            "height"
+                                                          ],
+                                                          "properties": {
+                                                            "width": {
+                                                              "type": "integer",
+                                                              "minimum": 1
+                                                            },
+                                                            "height": {
+                                                              "type": "integer",
+                                                              "minimum": 1
+                                                            }
+                                                          }
+                                                        }
+                                                      ]
+                                                    },
+                                                    "notBlack": {
+                                                      "type": "boolean",
+                                                      "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                    }
+                                                  }
+                                                },
+                                                "checkpoints": {
+                                                  "title": "Recording checkpoints",
+                                                  "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                  "anyOf": [
+                                                    {
+                                                      "type": "boolean",
+                                                      "title": "Recording checkpoints (boolean)",
+                                                      "description": "If `true`, enables checkpoints with default settings."
+                                                    },
+                                                    {
+                                                      "type": "object",
+                                                      "title": "Recording checkpoints (detailed)",
+                                                      "additionalProperties": false,
+                                                      "properties": {
+                                                        "maxVariation": {
+                                                          "type": "number",
+                                                          "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                          "default": 0.05,
+                                                          "minimum": 0,
+                                                          "maximum": 1
+                                                        },
+                                                        "directory": {
+                                                          "type": "string",
+                                                          "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                          "transform": [
+                                                            "trim"
+                                                          ]
+                                                        }
+                                                      }
+                                                    }
+                                                  ]
                                                 }
                                               },
                                               "title": "Record (detailed)"
@@ -325121,10 +326485,11 @@
                                                   },
                                                   "overwrite": {
                                                     "type": "string",
-                                                    "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                    "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                     "enum": [
                                                       "true",
-                                                      "false"
+                                                      "false",
+                                                      "aboveVariation"
                                                     ]
                                                   },
                                                   "name": {
@@ -325182,6 +326547,88 @@
                                                         }
                                                       }
                                                     ]
+                                                  },
+                                                  "verify": {
+                                                    "title": "Recording verify guards",
+                                                    "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                    "type": "object",
+                                                    "additionalProperties": false,
+                                                    "properties": {
+                                                      "minDuration": {
+                                                        "type": "number",
+                                                        "description": "Fail if the video is shorter than this many seconds.",
+                                                        "minimum": 0
+                                                      },
+                                                      "maxDuration": {
+                                                        "type": "number",
+                                                        "description": "Fail if the video is longer than this many seconds.",
+                                                        "minimum": 0
+                                                      },
+                                                      "resolution": {
+                                                        "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                        "anyOf": [
+                                                          {
+                                                            "type": "boolean",
+                                                            "title": "Verify resolution (boolean)"
+                                                          },
+                                                          {
+                                                            "type": "object",
+                                                            "title": "Verify resolution (detailed)",
+                                                            "additionalProperties": false,
+                                                            "required": [
+                                                              "width",
+                                                              "height"
+                                                            ],
+                                                            "properties": {
+                                                              "width": {
+                                                                "type": "integer",
+                                                                "minimum": 1
+                                                              },
+                                                              "height": {
+                                                                "type": "integer",
+                                                                "minimum": 1
+                                                              }
+                                                            }
+                                                          }
+                                                        ]
+                                                      },
+                                                      "notBlack": {
+                                                        "type": "boolean",
+                                                        "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                      }
+                                                    }
+                                                  },
+                                                  "checkpoints": {
+                                                    "title": "Recording checkpoints",
+                                                    "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                    "anyOf": [
+                                                      {
+                                                        "type": "boolean",
+                                                        "title": "Recording checkpoints (boolean)",
+                                                        "description": "If `true`, enables checkpoints with default settings."
+                                                      },
+                                                      {
+                                                        "type": "object",
+                                                        "title": "Recording checkpoints (detailed)",
+                                                        "additionalProperties": false,
+                                                        "properties": {
+                                                          "maxVariation": {
+                                                            "type": "number",
+                                                            "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                            "default": 0.05,
+                                                            "minimum": 0,
+                                                            "maximum": 1
+                                                          },
+                                                          "directory": {
+                                                            "type": "string",
+                                                            "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                            "transform": [
+                                                              "trim"
+                                                            ]
+                                                          }
+                                                        }
+                                                      }
+                                                    ]
                                                   }
                                                 },
                                                 "title": "Record (detailed)"
@@ -325248,6 +326695,17 @@
                                               "path": "results.mp4",
                                               "engine": "ffmpeg"
                                             },
+                                            {
+                                              "path": "results.mp4",
+                                              "checkpoints": true
+                                            },
+                                            {
+                                              "path": "results.mp4",
+                                              "checkpoints": {
+                                                "maxVariation": 0.02,
+                                                "directory": "baselines/results"
+                                              }
+                                            },
                                             {
                                               "path": "results.mp4",
                                               "engine": {
@@ -365674,9 +367132,10 @@
                                                 "anyOf": [
                                                   {
                                                     "title": "Screenshot (simple)",
+                                                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                     "type": "string",
-                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                     "transform": [
                                                       "trim"
                                                     ]
@@ -365910,9 +367369,10 @@
                                                           },
                                                           "path": {
                                                             "title": "Screenshot (simple)",
+                                                            "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                             "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                             "type": "string",
-                                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                             "transform": [
                                                               "trim"
                                                             ]
@@ -366170,9 +367630,10 @@
                                                   "schemas": {
                                                     "path": {
                                                       "title": "Screenshot (simple)",
+                                                      "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                       "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                       "type": "string",
-                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                       "transform": [
                                                         "trim"
                                                       ]
@@ -366406,9 +367867,10 @@
                                                             },
                                                             "path": {
                                                               "title": "Screenshot (simple)",
+                                                              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                               "type": "string",
-                                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                               "transform": [
                                                                 "trim"
                                                               ]
@@ -366882,9 +368344,10 @@
                                                         },
                                                         "path": {
                                                           "title": "Screenshot (simple)",
+                                                          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                           "type": "string",
-                                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                           "transform": [
                                                             "trim"
                                                           ]
@@ -367266,6 +368729,7 @@
                                                   "image.png",
                                                   "static/images/image.png",
                                                   "/User/manny/projects/doc-detective/static/images/image.png",
+                                                  "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                                   "https://example.com/static/images/image.png",
                                                   {
                                                     "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -369700,10 +371164,11 @@
                                                       },
                                                       "overwrite": {
                                                         "type": "string",
-                                                        "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                        "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                         "enum": [
                                                           "true",
-                                                          "false"
+                                                          "false",
+                                                          "aboveVariation"
                                                         ]
                                                       },
                                                       "name": {
@@ -369761,6 +371226,88 @@
                                                             }
                                                           }
                                                         ]
+                                                      },
+                                                      "verify": {
+                                                        "title": "Recording verify guards",
+                                                        "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                        "type": "object",
+                                                        "additionalProperties": false,
+                                                        "properties": {
+                                                          "minDuration": {
+                                                            "type": "number",
+                                                            "description": "Fail if the video is shorter than this many seconds.",
+                                                            "minimum": 0
+                                                          },
+                                                          "maxDuration": {
+                                                            "type": "number",
+                                                            "description": "Fail if the video is longer than this many seconds.",
+                                                            "minimum": 0
+                                                          },
+                                                          "resolution": {
+                                                            "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                            "anyOf": [
+                                                              {
+                                                                "type": "boolean",
+                                                                "title": "Verify resolution (boolean)"
+                                                              },
+                                                              {
+                                                                "type": "object",
+                                                                "title": "Verify resolution (detailed)",
+                                                                "additionalProperties": false,
+                                                                "required": [
+                                                                  "width",
+                                                                  "height"
+                                                                ],
+                                                                "properties": {
+                                                                  "width": {
+                                                                    "type": "integer",
+                                                                    "minimum": 1
+                                                                  },
+                                                                  "height": {
+                                                                    "type": "integer",
+                                                                    "minimum": 1
+                                                                  }
+                                                                }
+                                                              }
+                                                            ]
+                                                          },
+                                                          "notBlack": {
+                                                            "type": "boolean",
+                                                            "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                          }
+                                                        }
+                                                      },
+                                                      "checkpoints": {
+                                                        "title": "Recording checkpoints",
+                                                        "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                        "anyOf": [
+                                                          {
+                                                            "type": "boolean",
+                                                            "title": "Recording checkpoints (boolean)",
+                                                            "description": "If `true`, enables checkpoints with default settings."
+                                                          },
+                                                          {
+                                                            "type": "object",
+                                                            "title": "Recording checkpoints (detailed)",
+                                                            "additionalProperties": false,
+                                                            "properties": {
+                                                              "maxVariation": {
+                                                                "type": "number",
+                                                                "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                                "default": 0.05,
+                                                                "minimum": 0,
+                                                                "maximum": 1
+                                                              },
+                                                              "directory": {
+                                                                "type": "string",
+                                                                "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                                "transform": [
+                                                                  "trim"
+                                                                ]
+                                                              }
+                                                            }
+                                                          }
+                                                        ]
                                                       }
                                                     },
                                                     "title": "Record (detailed)"
@@ -370022,10 +371569,11 @@
                                                         },
                                                         "overwrite": {
                                                           "type": "string",
-                                                          "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                          "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                           "enum": [
                                                             "true",
-                                                            "false"
+                                                            "false",
+                                                            "aboveVariation"
                                                           ]
                                                         },
                                                         "name": {
@@ -370083,6 +371631,88 @@
                                                               }
                                                             }
                                                           ]
+                                                        },
+                                                        "verify": {
+                                                          "title": "Recording verify guards",
+                                                          "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                          "type": "object",
+                                                          "additionalProperties": false,
+                                                          "properties": {
+                                                            "minDuration": {
+                                                              "type": "number",
+                                                              "description": "Fail if the video is shorter than this many seconds.",
+                                                              "minimum": 0
+                                                            },
+                                                            "maxDuration": {
+                                                              "type": "number",
+                                                              "description": "Fail if the video is longer than this many seconds.",
+                                                              "minimum": 0
+                                                            },
+                                                            "resolution": {
+                                                              "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                              "anyOf": [
+                                                                {
+                                                                  "type": "boolean",
+                                                                  "title": "Verify resolution (boolean)"
+                                                                },
+                                                                {
+                                                                  "type": "object",
+                                                                  "title": "Verify resolution (detailed)",
+                                                                  "additionalProperties": false,
+                                                                  "required": [
+                                                                    "width",
+                                                                    "height"
+                                                                  ],
+                                                                  "properties": {
+                                                                    "width": {
+                                                                      "type": "integer",
+                                                                      "minimum": 1
+                                                                    },
+                                                                    "height": {
+                                                                      "type": "integer",
+                                                                      "minimum": 1
+                                                                    }
+                                                                  }
+                                                                }
+                                                              ]
+                                                            },
+                                                            "notBlack": {
+                                                              "type": "boolean",
+                                                              "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                            }
+                                                          }
+                                                        },
+                                                        "checkpoints": {
+                                                          "title": "Recording checkpoints",
+                                                          "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                          "anyOf": [
+                                                            {
+                                                              "type": "boolean",
+                                                              "title": "Recording checkpoints (boolean)",
+                                                              "description": "If `true`, enables checkpoints with default settings."
+                                                            },
+                                                            {
+                                                              "type": "object",
+                                                              "title": "Recording checkpoints (detailed)",
+                                                              "additionalProperties": false,
+                                                              "properties": {
+                                                                "maxVariation": {
+                                                                  "type": "number",
+                                                                  "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                                  "default": 0.05,
+                                                                  "minimum": 0,
+                                                                  "maximum": 1
+                                                                },
+                                                                "directory": {
+                                                                  "type": "string",
+                                                                  "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                                  "transform": [
+                                                                    "trim"
+                                                                  ]
+                                                                }
+                                                              }
+                                                            }
+                                                          ]
                                                         }
                                                       },
                                                       "title": "Record (detailed)"
@@ -370149,6 +371779,17 @@
                                                     "path": "results.mp4",
                                                     "engine": "ffmpeg"
                                                   },
+                                                  {
+                                                    "path": "results.mp4",
+                                                    "checkpoints": true
+                                                  },
+                                                  {
+                                                    "path": "results.mp4",
+                                                    "checkpoints": {
+                                                      "maxVariation": 0.02,
+                                                      "directory": "baselines/results"
+                                                    }
+                                                  },
                                                   {
                                                     "path": "results.mp4",
                                                     "engine": {
@@ -385685,9 +387326,10 @@
     "anyOf": [
       {
         "title": "Screenshot (simple)",
+        "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
         "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
         "type": "string",
-        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
         "transform": [
           "trim"
         ]
@@ -385921,9 +387563,10 @@
               },
               "path": {
                 "title": "Screenshot (simple)",
+                "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                 "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                 "type": "string",
-                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                 "transform": [
                   "trim"
                 ]
@@ -386181,9 +387824,10 @@
       "schemas": {
         "path": {
           "title": "Screenshot (simple)",
+          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
           "type": "string",
-          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
           "transform": [
             "trim"
           ]
@@ -386417,9 +388061,10 @@
                 },
                 "path": {
                   "title": "Screenshot (simple)",
+                  "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                   "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                   "type": "string",
-                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                   "transform": [
                     "trim"
                   ]
@@ -386893,9 +388538,10 @@
             },
             "path": {
               "title": "Screenshot (simple)",
+              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
               "type": "string",
-              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
               "transform": [
                 "trim"
               ]
@@ -387277,6 +388923,7 @@
       "image.png",
       "static/images/image.png",
       "/User/manny/projects/doc-detective/static/images/image.png",
+      "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
       "https://example.com/static/images/image.png",
       {
         "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -416860,9 +418507,10 @@
                                 "anyOf": [
                                   {
                                     "title": "Screenshot (simple)",
+                                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                     "type": "string",
-                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                     "transform": [
                                       "trim"
                                     ]
@@ -417096,9 +418744,10 @@
                                           },
                                           "path": {
                                             "title": "Screenshot (simple)",
+                                            "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                             "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                             "type": "string",
-                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                             "transform": [
                                               "trim"
                                             ]
@@ -417356,9 +419005,10 @@
                                   "schemas": {
                                     "path": {
                                       "title": "Screenshot (simple)",
+                                      "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                       "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                       "type": "string",
-                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                       "transform": [
                                         "trim"
                                       ]
@@ -417592,9 +419242,10 @@
                                             },
                                             "path": {
                                               "title": "Screenshot (simple)",
+                                              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                               "type": "string",
-                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                               "transform": [
                                                 "trim"
                                               ]
@@ -418068,9 +419719,10 @@
                                         },
                                         "path": {
                                           "title": "Screenshot (simple)",
+                                          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                           "type": "string",
-                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                           "transform": [
                                             "trim"
                                           ]
@@ -418452,6 +420104,7 @@
                                   "image.png",
                                   "static/images/image.png",
                                   "/User/manny/projects/doc-detective/static/images/image.png",
+                                  "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                   "https://example.com/static/images/image.png",
                                   {
                                     "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -420886,10 +422539,11 @@
                                       },
                                       "overwrite": {
                                         "type": "string",
-                                        "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                        "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                         "enum": [
                                           "true",
-                                          "false"
+                                          "false",
+                                          "aboveVariation"
                                         ]
                                       },
                                       "name": {
@@ -420947,6 +422601,88 @@
                                             }
                                           }
                                         ]
+                                      },
+                                      "verify": {
+                                        "title": "Recording verify guards",
+                                        "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                        "type": "object",
+                                        "additionalProperties": false,
+                                        "properties": {
+                                          "minDuration": {
+                                            "type": "number",
+                                            "description": "Fail if the video is shorter than this many seconds.",
+                                            "minimum": 0
+                                          },
+                                          "maxDuration": {
+                                            "type": "number",
+                                            "description": "Fail if the video is longer than this many seconds.",
+                                            "minimum": 0
+                                          },
+                                          "resolution": {
+                                            "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                            "anyOf": [
+                                              {
+                                                "type": "boolean",
+                                                "title": "Verify resolution (boolean)"
+                                              },
+                                              {
+                                                "type": "object",
+                                                "title": "Verify resolution (detailed)",
+                                                "additionalProperties": false,
+                                                "required": [
+                                                  "width",
+                                                  "height"
+                                                ],
+                                                "properties": {
+                                                  "width": {
+                                                    "type": "integer",
+                                                    "minimum": 1
+                                                  },
+                                                  "height": {
+                                                    "type": "integer",
+                                                    "minimum": 1
+                                                  }
+                                                }
+                                              }
+                                            ]
+                                          },
+                                          "notBlack": {
+                                            "type": "boolean",
+                                            "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                          }
+                                        }
+                                      },
+                                      "checkpoints": {
+                                        "title": "Recording checkpoints",
+                                        "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                        "anyOf": [
+                                          {
+                                            "type": "boolean",
+                                            "title": "Recording checkpoints (boolean)",
+                                            "description": "If `true`, enables checkpoints with default settings."
+                                          },
+                                          {
+                                            "type": "object",
+                                            "title": "Recording checkpoints (detailed)",
+                                            "additionalProperties": false,
+                                            "properties": {
+                                              "maxVariation": {
+                                                "type": "number",
+                                                "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                "default": 0.05,
+                                                "minimum": 0,
+                                                "maximum": 1
+                                              },
+                                              "directory": {
+                                                "type": "string",
+                                                "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                "transform": [
+                                                  "trim"
+                                                ]
+                                              }
+                                            }
+                                          }
+                                        ]
                                       }
                                     },
                                     "title": "Record (detailed)"
@@ -421208,10 +422944,11 @@
                                         },
                                         "overwrite": {
                                           "type": "string",
-                                          "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                          "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                           "enum": [
                                             "true",
-                                            "false"
+                                            "false",
+                                            "aboveVariation"
                                           ]
                                         },
                                         "name": {
@@ -421269,6 +423006,88 @@
                                               }
                                             }
                                           ]
+                                        },
+                                        "verify": {
+                                          "title": "Recording verify guards",
+                                          "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                          "type": "object",
+                                          "additionalProperties": false,
+                                          "properties": {
+                                            "minDuration": {
+                                              "type": "number",
+                                              "description": "Fail if the video is shorter than this many seconds.",
+                                              "minimum": 0
+                                            },
+                                            "maxDuration": {
+                                              "type": "number",
+                                              "description": "Fail if the video is longer than this many seconds.",
+                                              "minimum": 0
+                                            },
+                                            "resolution": {
+                                              "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                              "anyOf": [
+                                                {
+                                                  "type": "boolean",
+                                                  "title": "Verify resolution (boolean)"
+                                                },
+                                                {
+                                                  "type": "object",
+                                                  "title": "Verify resolution (detailed)",
+                                                  "additionalProperties": false,
+                                                  "required": [
+                                                    "width",
+                                                    "height"
+                                                  ],
+                                                  "properties": {
+                                                    "width": {
+                                                      "type": "integer",
+                                                      "minimum": 1
+                                                    },
+                                                    "height": {
+                                                      "type": "integer",
+                                                      "minimum": 1
+                                                    }
+                                                  }
+                                                }
+                                              ]
+                                            },
+                                            "notBlack": {
+                                              "type": "boolean",
+                                              "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                            }
+                                          }
+                                        },
+                                        "checkpoints": {
+                                          "title": "Recording checkpoints",
+                                          "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                          "anyOf": [
+                                            {
+                                              "type": "boolean",
+                                              "title": "Recording checkpoints (boolean)",
+                                              "description": "If `true`, enables checkpoints with default settings."
+                                            },
+                                            {
+                                              "type": "object",
+                                              "title": "Recording checkpoints (detailed)",
+                                              "additionalProperties": false,
+                                              "properties": {
+                                                "maxVariation": {
+                                                  "type": "number",
+                                                  "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                  "default": 0.05,
+                                                  "minimum": 0,
+                                                  "maximum": 1
+                                                },
+                                                "directory": {
+                                                  "type": "string",
+                                                  "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                  "transform": [
+                                                    "trim"
+                                                  ]
+                                                }
+                                              }
+                                            }
+                                          ]
                                         }
                                       },
                                       "title": "Record (detailed)"
@@ -421335,6 +423154,17 @@
                                     "path": "results.mp4",
                                     "engine": "ffmpeg"
                                   },
+                                  {
+                                    "path": "results.mp4",
+                                    "checkpoints": true
+                                  },
+                                  {
+                                    "path": "results.mp4",
+                                    "checkpoints": {
+                                      "maxVariation": 0.02,
+                                      "directory": "baselines/results"
+                                    }
+                                  },
                                   {
                                     "path": "results.mp4",
                                     "engine": {
@@ -461761,9 +463591,10 @@
                                       "anyOf": [
                                         {
                                           "title": "Screenshot (simple)",
+                                          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                           "type": "string",
-                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                           "transform": [
                                             "trim"
                                           ]
@@ -461997,9 +463828,10 @@
                                                 },
                                                 "path": {
                                                   "title": "Screenshot (simple)",
+                                                  "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                   "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                   "type": "string",
-                                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                   "transform": [
                                                     "trim"
                                                   ]
@@ -462257,9 +464089,10 @@
                                         "schemas": {
                                           "path": {
                                             "title": "Screenshot (simple)",
+                                            "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                             "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                             "type": "string",
-                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                             "transform": [
                                               "trim"
                                             ]
@@ -462493,9 +464326,10 @@
                                                   },
                                                   "path": {
                                                     "title": "Screenshot (simple)",
+                                                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                     "type": "string",
-                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                     "transform": [
                                                       "trim"
                                                     ]
@@ -462969,9 +464803,10 @@
                                               },
                                               "path": {
                                                 "title": "Screenshot (simple)",
+                                                "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                                 "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                                 "type": "string",
-                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                                 "transform": [
                                                   "trim"
                                                 ]
@@ -463353,6 +465188,7 @@
                                         "image.png",
                                         "static/images/image.png",
                                         "/User/manny/projects/doc-detective/static/images/image.png",
+                                        "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                                         "https://example.com/static/images/image.png",
                                         {
                                           "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -465787,10 +467623,11 @@
                                             },
                                             "overwrite": {
                                               "type": "string",
-                                              "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                              "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                               "enum": [
                                                 "true",
-                                                "false"
+                                                "false",
+                                                "aboveVariation"
                                               ]
                                             },
                                             "name": {
@@ -465848,6 +467685,88 @@
                                                   }
                                                 }
                                               ]
+                                            },
+                                            "verify": {
+                                              "title": "Recording verify guards",
+                                              "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                              "type": "object",
+                                              "additionalProperties": false,
+                                              "properties": {
+                                                "minDuration": {
+                                                  "type": "number",
+                                                  "description": "Fail if the video is shorter than this many seconds.",
+                                                  "minimum": 0
+                                                },
+                                                "maxDuration": {
+                                                  "type": "number",
+                                                  "description": "Fail if the video is longer than this many seconds.",
+                                                  "minimum": 0
+                                                },
+                                                "resolution": {
+                                                  "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                  "anyOf": [
+                                                    {
+                                                      "type": "boolean",
+                                                      "title": "Verify resolution (boolean)"
+                                                    },
+                                                    {
+                                                      "type": "object",
+                                                      "title": "Verify resolution (detailed)",
+                                                      "additionalProperties": false,
+                                                      "required": [
+                                                        "width",
+                                                        "height"
+                                                      ],
+                                                      "properties": {
+                                                        "width": {
+                                                          "type": "integer",
+                                                          "minimum": 1
+                                                        },
+                                                        "height": {
+                                                          "type": "integer",
+                                                          "minimum": 1
+                                                        }
+                                                      }
+                                                    }
+                                                  ]
+                                                },
+                                                "notBlack": {
+                                                  "type": "boolean",
+                                                  "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                }
+                                              }
+                                            },
+                                            "checkpoints": {
+                                              "title": "Recording checkpoints",
+                                              "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                              "anyOf": [
+                                                {
+                                                  "type": "boolean",
+                                                  "title": "Recording checkpoints (boolean)",
+                                                  "description": "If `true`, enables checkpoints with default settings."
+                                                },
+                                                {
+                                                  "type": "object",
+                                                  "title": "Recording checkpoints (detailed)",
+                                                  "additionalProperties": false,
+                                                  "properties": {
+                                                    "maxVariation": {
+                                                      "type": "number",
+                                                      "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                      "default": 0.05,
+                                                      "minimum": 0,
+                                                      "maximum": 1
+                                                    },
+                                                    "directory": {
+                                                      "type": "string",
+                                                      "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                      "transform": [
+                                                        "trim"
+                                                      ]
+                                                    }
+                                                  }
+                                                }
+                                              ]
                                             }
                                           },
                                           "title": "Record (detailed)"
@@ -466109,10 +468028,11 @@
                                               },
                                               "overwrite": {
                                                 "type": "string",
-                                                "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                                "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                                 "enum": [
                                                   "true",
-                                                  "false"
+                                                  "false",
+                                                  "aboveVariation"
                                                 ]
                                               },
                                               "name": {
@@ -466170,6 +468090,88 @@
                                                     }
                                                   }
                                                 ]
+                                              },
+                                              "verify": {
+                                                "title": "Recording verify guards",
+                                                "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                                "type": "object",
+                                                "additionalProperties": false,
+                                                "properties": {
+                                                  "minDuration": {
+                                                    "type": "number",
+                                                    "description": "Fail if the video is shorter than this many seconds.",
+                                                    "minimum": 0
+                                                  },
+                                                  "maxDuration": {
+                                                    "type": "number",
+                                                    "description": "Fail if the video is longer than this many seconds.",
+                                                    "minimum": 0
+                                                  },
+                                                  "resolution": {
+                                                    "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                                    "anyOf": [
+                                                      {
+                                                        "type": "boolean",
+                                                        "title": "Verify resolution (boolean)"
+                                                      },
+                                                      {
+                                                        "type": "object",
+                                                        "title": "Verify resolution (detailed)",
+                                                        "additionalProperties": false,
+                                                        "required": [
+                                                          "width",
+                                                          "height"
+                                                        ],
+                                                        "properties": {
+                                                          "width": {
+                                                            "type": "integer",
+                                                            "minimum": 1
+                                                          },
+                                                          "height": {
+                                                            "type": "integer",
+                                                            "minimum": 1
+                                                          }
+                                                        }
+                                                      }
+                                                    ]
+                                                  },
+                                                  "notBlack": {
+                                                    "type": "boolean",
+                                                    "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                                  }
+                                                }
+                                              },
+                                              "checkpoints": {
+                                                "title": "Recording checkpoints",
+                                                "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                                "anyOf": [
+                                                  {
+                                                    "type": "boolean",
+                                                    "title": "Recording checkpoints (boolean)",
+                                                    "description": "If `true`, enables checkpoints with default settings."
+                                                  },
+                                                  {
+                                                    "type": "object",
+                                                    "title": "Recording checkpoints (detailed)",
+                                                    "additionalProperties": false,
+                                                    "properties": {
+                                                      "maxVariation": {
+                                                        "type": "number",
+                                                        "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                                        "default": 0.05,
+                                                        "minimum": 0,
+                                                        "maximum": 1
+                                                      },
+                                                      "directory": {
+                                                        "type": "string",
+                                                        "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                                        "transform": [
+                                                          "trim"
+                                                        ]
+                                                      }
+                                                    }
+                                                  }
+                                                ]
                                               }
                                             },
                                             "title": "Record (detailed)"
@@ -466236,6 +468238,17 @@
                                           "path": "results.mp4",
                                           "engine": "ffmpeg"
                                         },
+                                        {
+                                          "path": "results.mp4",
+                                          "checkpoints": true
+                                        },
+                                        {
+                                          "path": "results.mp4",
+                                          "checkpoints": {
+                                            "maxVariation": 0.02,
+                                            "directory": "baselines/results"
+                                          }
+                                        },
                                         {
                                           "path": "results.mp4",
                                           "engine": {
@@ -508354,9 +510367,10 @@
                 "anyOf": [
                   {
                     "title": "Screenshot (simple)",
+                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                     "type": "string",
-                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                     "transform": [
                       "trim"
                     ]
@@ -508590,9 +510604,10 @@
                           },
                           "path": {
                             "title": "Screenshot (simple)",
+                            "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                             "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                             "type": "string",
-                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                             "transform": [
                               "trim"
                             ]
@@ -508850,9 +510865,10 @@
                   "schemas": {
                     "path": {
                       "title": "Screenshot (simple)",
+                      "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                       "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                       "type": "string",
-                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                       "transform": [
                         "trim"
                       ]
@@ -509086,9 +511102,10 @@
                             },
                             "path": {
                               "title": "Screenshot (simple)",
+                              "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                               "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                               "type": "string",
-                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                              "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                               "transform": [
                                 "trim"
                               ]
@@ -509562,9 +511579,10 @@
                         },
                         "path": {
                           "title": "Screenshot (simple)",
+                          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                           "type": "string",
-                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                           "transform": [
                             "trim"
                           ]
@@ -509946,6 +511964,7 @@
                   "image.png",
                   "static/images/image.png",
                   "/User/manny/projects/doc-detective/static/images/image.png",
+                  "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                   "https://example.com/static/images/image.png",
                   {
                     "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -512380,10 +514399,11 @@
                       },
                       "overwrite": {
                         "type": "string",
-                        "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                        "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                         "enum": [
                           "true",
-                          "false"
+                          "false",
+                          "aboveVariation"
                         ]
                       },
                       "name": {
@@ -512441,6 +514461,88 @@
                             }
                           }
                         ]
+                      },
+                      "verify": {
+                        "title": "Recording verify guards",
+                        "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                          "minDuration": {
+                            "type": "number",
+                            "description": "Fail if the video is shorter than this many seconds.",
+                            "minimum": 0
+                          },
+                          "maxDuration": {
+                            "type": "number",
+                            "description": "Fail if the video is longer than this many seconds.",
+                            "minimum": 0
+                          },
+                          "resolution": {
+                            "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                            "anyOf": [
+                              {
+                                "type": "boolean",
+                                "title": "Verify resolution (boolean)"
+                              },
+                              {
+                                "type": "object",
+                                "title": "Verify resolution (detailed)",
+                                "additionalProperties": false,
+                                "required": [
+                                  "width",
+                                  "height"
+                                ],
+                                "properties": {
+                                  "width": {
+                                    "type": "integer",
+                                    "minimum": 1
+                                  },
+                                  "height": {
+                                    "type": "integer",
+                                    "minimum": 1
+                                  }
+                                }
+                              }
+                            ]
+                          },
+                          "notBlack": {
+                            "type": "boolean",
+                            "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                          }
+                        }
+                      },
+                      "checkpoints": {
+                        "title": "Recording checkpoints",
+                        "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                        "anyOf": [
+                          {
+                            "type": "boolean",
+                            "title": "Recording checkpoints (boolean)",
+                            "description": "If `true`, enables checkpoints with default settings."
+                          },
+                          {
+                            "type": "object",
+                            "title": "Recording checkpoints (detailed)",
+                            "additionalProperties": false,
+                            "properties": {
+                              "maxVariation": {
+                                "type": "number",
+                                "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                "default": 0.05,
+                                "minimum": 0,
+                                "maximum": 1
+                              },
+                              "directory": {
+                                "type": "string",
+                                "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                "transform": [
+                                  "trim"
+                                ]
+                              }
+                            }
+                          }
+                        ]
                       }
                     },
                     "title": "Record (detailed)"
@@ -512702,10 +514804,11 @@
                         },
                         "overwrite": {
                           "type": "string",
-                          "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                          "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                           "enum": [
                             "true",
-                            "false"
+                            "false",
+                            "aboveVariation"
                           ]
                         },
                         "name": {
@@ -512763,6 +514866,88 @@
                               }
                             }
                           ]
+                        },
+                        "verify": {
+                          "title": "Recording verify guards",
+                          "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                          "type": "object",
+                          "additionalProperties": false,
+                          "properties": {
+                            "minDuration": {
+                              "type": "number",
+                              "description": "Fail if the video is shorter than this many seconds.",
+                              "minimum": 0
+                            },
+                            "maxDuration": {
+                              "type": "number",
+                              "description": "Fail if the video is longer than this many seconds.",
+                              "minimum": 0
+                            },
+                            "resolution": {
+                              "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                              "anyOf": [
+                                {
+                                  "type": "boolean",
+                                  "title": "Verify resolution (boolean)"
+                                },
+                                {
+                                  "type": "object",
+                                  "title": "Verify resolution (detailed)",
+                                  "additionalProperties": false,
+                                  "required": [
+                                    "width",
+                                    "height"
+                                  ],
+                                  "properties": {
+                                    "width": {
+                                      "type": "integer",
+                                      "minimum": 1
+                                    },
+                                    "height": {
+                                      "type": "integer",
+                                      "minimum": 1
+                                    }
+                                  }
+                                }
+                              ]
+                            },
+                            "notBlack": {
+                              "type": "boolean",
+                              "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                            }
+                          }
+                        },
+                        "checkpoints": {
+                          "title": "Recording checkpoints",
+                          "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                          "anyOf": [
+                            {
+                              "type": "boolean",
+                              "title": "Recording checkpoints (boolean)",
+                              "description": "If `true`, enables checkpoints with default settings."
+                            },
+                            {
+                              "type": "object",
+                              "title": "Recording checkpoints (detailed)",
+                              "additionalProperties": false,
+                              "properties": {
+                                "maxVariation": {
+                                  "type": "number",
+                                  "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                  "default": 0.05,
+                                  "minimum": 0,
+                                  "maximum": 1
+                                },
+                                "directory": {
+                                  "type": "string",
+                                  "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                  "transform": [
+                                    "trim"
+                                  ]
+                                }
+                              }
+                            }
+                          ]
                         }
                       },
                       "title": "Record (detailed)"
@@ -512829,6 +515014,17 @@
                     "path": "results.mp4",
                     "engine": "ffmpeg"
                   },
+                  {
+                    "path": "results.mp4",
+                    "checkpoints": true
+                  },
+                  {
+                    "path": "results.mp4",
+                    "checkpoints": {
+                      "maxVariation": 0.02,
+                      "directory": "baselines/results"
+                    }
+                  },
                   {
                     "path": "results.mp4",
                     "engine": {
@@ -556600,9 +558796,10 @@
                       "anyOf": [
                         {
                           "title": "Screenshot (simple)",
+                          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                           "type": "string",
-                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                           "transform": [
                             "trim"
                           ]
@@ -556836,9 +559033,10 @@
                                 },
                                 "path": {
                                   "title": "Screenshot (simple)",
+                                  "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                   "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                   "type": "string",
-                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                   "transform": [
                                     "trim"
                                   ]
@@ -557096,9 +559294,10 @@
                         "schemas": {
                           "path": {
                             "title": "Screenshot (simple)",
+                            "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                             "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                             "type": "string",
-                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                            "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                             "transform": [
                               "trim"
                             ]
@@ -557332,9 +559531,10 @@
                                   },
                                   "path": {
                                     "title": "Screenshot (simple)",
+                                    "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                     "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                     "type": "string",
-                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                    "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                     "transform": [
                                       "trim"
                                     ]
@@ -557808,9 +560008,10 @@
                               },
                               "path": {
                                 "title": "Screenshot (simple)",
+                                "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                 "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                 "type": "string",
-                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                 "transform": [
                                   "trim"
                                 ]
@@ -558192,6 +560393,7 @@
                         "image.png",
                         "static/images/image.png",
                         "/User/manny/projects/doc-detective/static/images/image.png",
+                        "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                         "https://example.com/static/images/image.png",
                         {
                           "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -560626,10 +562828,11 @@
                             },
                             "overwrite": {
                               "type": "string",
-                              "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                              "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                               "enum": [
                                 "true",
-                                "false"
+                                "false",
+                                "aboveVariation"
                               ]
                             },
                             "name": {
@@ -560687,6 +562890,88 @@
                                   }
                                 }
                               ]
+                            },
+                            "verify": {
+                              "title": "Recording verify guards",
+                              "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                              "type": "object",
+                              "additionalProperties": false,
+                              "properties": {
+                                "minDuration": {
+                                  "type": "number",
+                                  "description": "Fail if the video is shorter than this many seconds.",
+                                  "minimum": 0
+                                },
+                                "maxDuration": {
+                                  "type": "number",
+                                  "description": "Fail if the video is longer than this many seconds.",
+                                  "minimum": 0
+                                },
+                                "resolution": {
+                                  "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                  "anyOf": [
+                                    {
+                                      "type": "boolean",
+                                      "title": "Verify resolution (boolean)"
+                                    },
+                                    {
+                                      "type": "object",
+                                      "title": "Verify resolution (detailed)",
+                                      "additionalProperties": false,
+                                      "required": [
+                                        "width",
+                                        "height"
+                                      ],
+                                      "properties": {
+                                        "width": {
+                                          "type": "integer",
+                                          "minimum": 1
+                                        },
+                                        "height": {
+                                          "type": "integer",
+                                          "minimum": 1
+                                        }
+                                      }
+                                    }
+                                  ]
+                                },
+                                "notBlack": {
+                                  "type": "boolean",
+                                  "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                }
+                              }
+                            },
+                            "checkpoints": {
+                              "title": "Recording checkpoints",
+                              "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                              "anyOf": [
+                                {
+                                  "type": "boolean",
+                                  "title": "Recording checkpoints (boolean)",
+                                  "description": "If `true`, enables checkpoints with default settings."
+                                },
+                                {
+                                  "type": "object",
+                                  "title": "Recording checkpoints (detailed)",
+                                  "additionalProperties": false,
+                                  "properties": {
+                                    "maxVariation": {
+                                      "type": "number",
+                                      "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                      "default": 0.05,
+                                      "minimum": 0,
+                                      "maximum": 1
+                                    },
+                                    "directory": {
+                                      "type": "string",
+                                      "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                      "transform": [
+                                        "trim"
+                                      ]
+                                    }
+                                  }
+                                }
+                              ]
                             }
                           },
                           "title": "Record (detailed)"
@@ -560948,10 +563233,11 @@
                               },
                               "overwrite": {
                                 "type": "string",
-                                "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                 "enum": [
                                   "true",
-                                  "false"
+                                  "false",
+                                  "aboveVariation"
                                 ]
                               },
                               "name": {
@@ -561009,6 +563295,88 @@
                                     }
                                   }
                                 ]
+                              },
+                              "verify": {
+                                "title": "Recording verify guards",
+                                "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                "type": "object",
+                                "additionalProperties": false,
+                                "properties": {
+                                  "minDuration": {
+                                    "type": "number",
+                                    "description": "Fail if the video is shorter than this many seconds.",
+                                    "minimum": 0
+                                  },
+                                  "maxDuration": {
+                                    "type": "number",
+                                    "description": "Fail if the video is longer than this many seconds.",
+                                    "minimum": 0
+                                  },
+                                  "resolution": {
+                                    "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                    "anyOf": [
+                                      {
+                                        "type": "boolean",
+                                        "title": "Verify resolution (boolean)"
+                                      },
+                                      {
+                                        "type": "object",
+                                        "title": "Verify resolution (detailed)",
+                                        "additionalProperties": false,
+                                        "required": [
+                                          "width",
+                                          "height"
+                                        ],
+                                        "properties": {
+                                          "width": {
+                                            "type": "integer",
+                                            "minimum": 1
+                                          },
+                                          "height": {
+                                            "type": "integer",
+                                            "minimum": 1
+                                          }
+                                        }
+                                      }
+                                    ]
+                                  },
+                                  "notBlack": {
+                                    "type": "boolean",
+                                    "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                  }
+                                }
+                              },
+                              "checkpoints": {
+                                "title": "Recording checkpoints",
+                                "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                "anyOf": [
+                                  {
+                                    "type": "boolean",
+                                    "title": "Recording checkpoints (boolean)",
+                                    "description": "If `true`, enables checkpoints with default settings."
+                                  },
+                                  {
+                                    "type": "object",
+                                    "title": "Recording checkpoints (detailed)",
+                                    "additionalProperties": false,
+                                    "properties": {
+                                      "maxVariation": {
+                                        "type": "number",
+                                        "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                        "default": 0.05,
+                                        "minimum": 0,
+                                        "maximum": 1
+                                      },
+                                      "directory": {
+                                        "type": "string",
+                                        "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                        "transform": [
+                                          "trim"
+                                        ]
+                                      }
+                                    }
+                                  }
+                                ]
                               }
                             },
                             "title": "Record (detailed)"
@@ -561075,6 +563443,17 @@
                           "path": "results.mp4",
                           "engine": "ffmpeg"
                         },
+                        {
+                          "path": "results.mp4",
+                          "checkpoints": true
+                        },
+                        {
+                          "path": "results.mp4",
+                          "checkpoints": {
+                            "maxVariation": 0.02,
+                            "directory": "baselines/results"
+                          }
+                        },
                         {
                           "path": "results.mp4",
                           "engine": {
@@ -601501,9 +603880,10 @@
                             "anyOf": [
                               {
                                 "title": "Screenshot (simple)",
+                                "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                 "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                 "type": "string",
-                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                 "transform": [
                                   "trim"
                                 ]
@@ -601737,9 +604117,10 @@
                                       },
                                       "path": {
                                         "title": "Screenshot (simple)",
+                                        "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                         "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                         "type": "string",
-                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                        "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                         "transform": [
                                           "trim"
                                         ]
@@ -601997,9 +604378,10 @@
                               "schemas": {
                                 "path": {
                                   "title": "Screenshot (simple)",
+                                  "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                   "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                   "type": "string",
-                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                  "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                   "transform": [
                                     "trim"
                                   ]
@@ -602233,9 +604615,10 @@
                                         },
                                         "path": {
                                           "title": "Screenshot (simple)",
+                                          "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                           "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                           "type": "string",
-                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                          "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                           "transform": [
                                             "trim"
                                           ]
@@ -602709,9 +605092,10 @@
                                     },
                                     "path": {
                                       "title": "Screenshot (simple)",
+                                      "$comment": "The pattern gates the target's EXTENSION, not its characters or location: any path ending in .png/.PNG is accepted, plus an http(s) URL to a PNG (optionally with a query string, for signed URLs) and a `$VAR` reference. It deliberately does not restrict the character set — an earlier pattern allowed any Windows absolute path but limited non-Windows paths to [A-Za-z0-9_./\\-], so ordinary macOS/Linux projects (a space, parentheses, '~', or non-ASCII anywhere in the path) failed validation, including for the absolute paths doc-detective synthesizes internally for autoScreenshot and recording checkpoints. That charset never bounded WHERE a screenshot could be written (traversal like ../../x.png always passed), so it only made non-Windows projects second-class. See ADR 01077.",
                                       "description": "File path of the PNG file. Accepts absolute paths. If not specified, the file name is the ID of the step. If an `http(s)` URL is supplied, the remote image is downloaded and used as a read-only reference for comparison; the new capture is written to a local run-specific folder instead of being uploaded back to the URL.",
                                       "type": "string",
-                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|[A-Za-z]:[\\/\\\\].*\\.(?:png|PNG)|[\\/\\\\]?[A-Za-z0-9_.\\/\\\\-]*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
+                                      "pattern": "^(?:https?:\\/\\/.+\\.(?:png|PNG)(?:\\?.*)?|.*\\.(?:png|PNG)|\\$[A-Za-z0-9_]+)$",
                                       "transform": [
                                         "trim"
                                       ]
@@ -603093,6 +605477,7 @@
                               "image.png",
                               "static/images/image.png",
                               "/User/manny/projects/doc-detective/static/images/image.png",
+                              "/Users/jane doe/projects/my docs (v2)/static/images/image.png",
                               "https://example.com/static/images/image.png",
                               {
                                 "path": "https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/request-changes-button-0c851bb3.png",
@@ -605527,10 +607912,11 @@
                                   },
                                   "overwrite": {
                                     "type": "string",
-                                    "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                    "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                     "enum": [
                                       "true",
-                                      "false"
+                                      "false",
+                                      "aboveVariation"
                                     ]
                                   },
                                   "name": {
@@ -605588,6 +607974,88 @@
                                         }
                                       }
                                     ]
+                                  },
+                                  "verify": {
+                                    "title": "Recording verify guards",
+                                    "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                    "type": "object",
+                                    "additionalProperties": false,
+                                    "properties": {
+                                      "minDuration": {
+                                        "type": "number",
+                                        "description": "Fail if the video is shorter than this many seconds.",
+                                        "minimum": 0
+                                      },
+                                      "maxDuration": {
+                                        "type": "number",
+                                        "description": "Fail if the video is longer than this many seconds.",
+                                        "minimum": 0
+                                      },
+                                      "resolution": {
+                                        "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                        "anyOf": [
+                                          {
+                                            "type": "boolean",
+                                            "title": "Verify resolution (boolean)"
+                                          },
+                                          {
+                                            "type": "object",
+                                            "title": "Verify resolution (detailed)",
+                                            "additionalProperties": false,
+                                            "required": [
+                                              "width",
+                                              "height"
+                                            ],
+                                            "properties": {
+                                              "width": {
+                                                "type": "integer",
+                                                "minimum": 1
+                                              },
+                                              "height": {
+                                                "type": "integer",
+                                                "minimum": 1
+                                              }
+                                            }
+                                          }
+                                        ]
+                                      },
+                                      "notBlack": {
+                                        "type": "boolean",
+                                        "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                      }
+                                    }
+                                  },
+                                  "checkpoints": {
+                                    "title": "Recording checkpoints",
+                                    "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                    "anyOf": [
+                                      {
+                                        "type": "boolean",
+                                        "title": "Recording checkpoints (boolean)",
+                                        "description": "If `true`, enables checkpoints with default settings."
+                                      },
+                                      {
+                                        "type": "object",
+                                        "title": "Recording checkpoints (detailed)",
+                                        "additionalProperties": false,
+                                        "properties": {
+                                          "maxVariation": {
+                                            "type": "number",
+                                            "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                            "default": 0.05,
+                                            "minimum": 0,
+                                            "maximum": 1
+                                          },
+                                          "directory": {
+                                            "type": "string",
+                                            "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                            "transform": [
+                                              "trim"
+                                            ]
+                                          }
+                                        }
+                                      }
+                                    ]
                                   }
                                 },
                                 "title": "Record (detailed)"
@@ -605849,10 +608317,11 @@
                                     },
                                     "overwrite": {
                                       "type": "string",
-                                      "description": "If `true`, overwrites the existing recording at `path` if it exists.",
+                                      "description": "If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`.",
                                       "enum": [
                                         "true",
-                                        "false"
+                                        "false",
+                                        "aboveVariation"
                                       ]
                                     },
                                     "name": {
@@ -605910,6 +608379,88 @@
                                           }
                                         }
                                       ]
+                                    },
+                                    "verify": {
+                                      "title": "Recording verify guards",
+                                      "description": "Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.",
+                                      "type": "object",
+                                      "additionalProperties": false,
+                                      "properties": {
+                                        "minDuration": {
+                                          "type": "number",
+                                          "description": "Fail if the video is shorter than this many seconds.",
+                                          "minimum": 0
+                                        },
+                                        "maxDuration": {
+                                          "type": "number",
+                                          "description": "Fail if the video is longer than this many seconds.",
+                                          "minimum": 0
+                                        },
+                                        "resolution": {
+                                          "description": "Verify the video's dimensions (±2 pixels — encoders round to even dimensions). `true` compares against the capture plan's resolved expectation (the crop rectangle when a window/viewport crop applied, else the capture frame size; skipped when no expectation exists for the engine). An object compares literal dimensions.",
+                                          "anyOf": [
+                                            {
+                                              "type": "boolean",
+                                              "title": "Verify resolution (boolean)"
+                                            },
+                                            {
+                                              "type": "object",
+                                              "title": "Verify resolution (detailed)",
+                                              "additionalProperties": false,
+                                              "required": [
+                                                "width",
+                                                "height"
+                                              ],
+                                              "properties": {
+                                                "width": {
+                                                  "type": "integer",
+                                                  "minimum": 1
+                                                },
+                                                "height": {
+                                                  "type": "integer",
+                                                  "minimum": 1
+                                                }
+                                              }
+                                            }
+                                          ]
+                                        },
+                                        "notBlack": {
+                                          "type": "boolean",
+                                          "description": "Fail if the video is essentially all black (black frames cover 95% or more of its duration) — the classic symptom of a broken screen capture."
+                                        }
+                                      }
+                                    },
+                                    "checkpoints": {
+                                      "title": "Recording checkpoints",
+                                      "description": "Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.",
+                                      "anyOf": [
+                                        {
+                                          "type": "boolean",
+                                          "title": "Recording checkpoints (boolean)",
+                                          "description": "If `true`, enables checkpoints with default settings."
+                                        },
+                                        {
+                                          "type": "object",
+                                          "title": "Recording checkpoints (detailed)",
+                                          "additionalProperties": false,
+                                          "properties": {
+                                            "maxVariation": {
+                                              "type": "number",
+                                              "description": "Maximum fractional pixel difference tolerated between a checkpoint and its baseline before the drift surfaces as a WARNING.",
+                                              "default": 0.05,
+                                              "minimum": 0,
+                                              "maximum": 1
+                                            },
+                                            "directory": {
+                                              "type": "string",
+                                              "description": "Directory for the checkpoint baselines. If unset, defaults to a `.checkpoints` directory beside the recording (for example, `demo.mp4.checkpoints/`).",
+                                              "transform": [
+                                                "trim"
+                                              ]
+                                            }
+                                          }
+                                        }
+                                      ]
                                     }
                                   },
                                   "title": "Record (detailed)"
@@ -605976,6 +608527,17 @@
                                 "path": "results.mp4",
                                 "engine": "ffmpeg"
                               },
+                              {
+                                "path": "results.mp4",
+                                "checkpoints": true
+                              },
+                              {
+                                "path": "results.mp4",
+                                "checkpoints": {
+                                  "maxVariation": 0.02,
+                                  "directory": "baselines/results"
+                                }
+                              },
                               {
                                 "path": "results.mp4",
                                 "engine": {