doc-detective-common 4.32.0 → 4.34.0

package/dist/index.cjs

@@ -30469,9 +30469,10 @@ var schemas_default = {
                                                   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 \u2014 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"
                                                       ]
@@ -30705,9 +30706,10 @@ var schemas_default = {
                                                             },
                                                             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 \u2014 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"
                                                               ]
@@ -30965,9 +30967,10 @@ var schemas_default = {
                                                     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 \u2014 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"
                                                         ]
@@ -31201,9 +31204,10 @@ var schemas_default = {
                                                               },
                                                               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 \u2014 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"
                                                                 ]
@@ -31677,9 +31681,10 @@ var schemas_default = {
                                                           },
                                                           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 \u2014 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"
                                                             ]
@@ -32061,6 +32066,7 @@ var schemas_default = {
                                                     "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",
@@ -34495,10 +34501,11 @@ var schemas_default = {
                                                         },
                                                         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 \u2014 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: {
@@ -34556,6 +34563,88 @@ var schemas_default = {
                                                               }
                                                             }
                                                           ]
+                                                        },
+                                                        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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -34817,10 +34906,11 @@ var schemas_default = {
                                                           },
                                                           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 \u2014 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: {
@@ -34878,6 +34968,88 @@ var schemas_default = {
                                                                 }
                                                               }
                                                             ]
+                                                          },
+                                                          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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -34944,6 +35116,17 @@ var schemas_default = {
                                                       path: "results.mp4",
                                                       engine: "ffmpeg"
                                                     },
+                                                    {
+                                                      path: "results.mp4",
+                                                      checkpoints: true
+                                                    },
+                                                    {
+                                                      path: "results.mp4",
+                                                      checkpoints: {
+                                                        maxVariation: 0.02,
+                                                        directory: "baselines/results"
+                                                      }
+                                                    },
                                                     {
                                                       path: "results.mp4",
                                                       engine: {
@@ -76108,9 +76291,10 @@ var schemas_default = {
                                     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 \u2014 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"
                                         ]
@@ -76344,9 +76528,10 @@ var schemas_default = {
                                               },
                                               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 \u2014 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"
                                                 ]
@@ -76604,9 +76789,10 @@ var schemas_default = {
                                       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 \u2014 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"
                                           ]
@@ -76840,9 +77026,10 @@ var schemas_default = {
                                                 },
                                                 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 \u2014 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"
                                                   ]
@@ -77316,9 +77503,10 @@ var schemas_default = {
                                             },
                                             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 \u2014 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"
                                               ]
@@ -77700,6 +77888,7 @@ var schemas_default = {
                                       "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",
@@ -80134,10 +80323,11 @@ var schemas_default = {
                                           },
                                           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 \u2014 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: {
@@ -80195,6 +80385,88 @@ var schemas_default = {
                                                 }
                                               }
                                             ]
+                                          },
+                                          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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -80456,10 +80728,11 @@ var schemas_default = {
                                             },
                                             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 \u2014 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: {
@@ -80517,6 +80790,88 @@ var schemas_default = {
                                                   }
                                                 }
                                               ]
+                                            },
+                                            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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -80583,6 +80938,17 @@ var schemas_default = {
                                         path: "results.mp4",
                                         engine: "ffmpeg"
                                       },
+                                      {
+                                        path: "results.mp4",
+                                        checkpoints: true
+                                      },
+                                      {
+                                        path: "results.mp4",
+                                        checkpoints: {
+                                          maxVariation: 0.02,
+                                          directory: "baselines/results"
+                                        }
+                                      },
                                       {
                                         path: "results.mp4",
                                         engine: {
@@ -106419,10 +106785,11 @@ var schemas_default = {
           },
           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 \u2014 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: {
@@ -106480,6 +106847,88 @@ var schemas_default = {
                 }
               }
             ]
+          },
+          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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -106741,10 +107190,11 @@ var schemas_default = {
             },
             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 \u2014 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: {
@@ -106802,6 +107252,88 @@ var schemas_default = {
                   }
                 }
               ]
+            },
+            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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -106868,6 +107400,17 @@ var schemas_default = {
         path: "results.mp4",
         engine: "ffmpeg"
       },
+      {
+        path: "results.mp4",
+        checkpoints: true
+      },
+      {
+        path: "results.mp4",
+        checkpoints: {
+          maxVariation: 0.02,
+          directory: "baselines/results"
+        }
+      },
       {
         path: "results.mp4",
         engine: {
@@ -135034,9 +135577,10 @@ var schemas_default = {
                                                       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 \u2014 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"
                                                           ]
@@ -135270,9 +135814,10 @@ var schemas_default = {
                                                                 },
                                                                 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 \u2014 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"
                                                                   ]
@@ -135530,9 +136075,10 @@ var schemas_default = {
                                                         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 \u2014 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"
                                                             ]
@@ -135766,9 +136312,10 @@ var schemas_default = {
                                                                   },
                                                                   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 \u2014 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"
                                                                     ]
@@ -136242,9 +136789,10 @@ var schemas_default = {
                                                               },
                                                               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 \u2014 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"
                                                                 ]
@@ -136626,6 +137174,7 @@ var schemas_default = {
                                                         "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",
@@ -139060,10 +139609,11 @@ var schemas_default = {
                                                             },
                                                             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 \u2014 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: {
@@ -139121,6 +139671,88 @@ var schemas_default = {
                                                                   }
                                                                 }
                                                               ]
+                                                            },
+                                                            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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -139382,10 +140014,11 @@ var schemas_default = {
                                                               },
                                                               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 \u2014 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: {
@@ -139443,6 +140076,88 @@ var schemas_default = {
                                                                     }
                                                                   }
                                                                 ]
+                                                              },
+                                                              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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -139509,6 +140224,17 @@ var schemas_default = {
                                                           path: "results.mp4",
                                                           engine: "ffmpeg"
                                                         },
+                                                        {
+                                                          path: "results.mp4",
+                                                          checkpoints: true
+                                                        },
+                                                        {
+                                                          path: "results.mp4",
+                                                          checkpoints: {
+                                                            maxVariation: 0.02,
+                                                            directory: "baselines/results"
+                                                          }
+                                                        },
                                                         {
                                                           path: "results.mp4",
                                                           engine: {
@@ -180673,9 +181399,10 @@ var schemas_default = {
                                         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 \u2014 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"
                                             ]
@@ -180909,9 +181636,10 @@ var schemas_default = {
                                                   },
                                                   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 \u2014 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"
                                                     ]
@@ -181169,9 +181897,10 @@ var schemas_default = {
                                           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 \u2014 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"
                                               ]
@@ -181405,9 +182134,10 @@ var schemas_default = {
                                                     },
                                                     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 \u2014 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"
                                                       ]
@@ -181881,9 +182611,10 @@ var schemas_default = {
                                                 },
                                                 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 \u2014 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"
                                                   ]
@@ -182265,6 +182996,7 @@ var schemas_default = {
                                           "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",
@@ -184699,10 +185431,11 @@ var schemas_default = {
                                               },
                                               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 \u2014 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: {
@@ -184760,6 +185493,88 @@ var schemas_default = {
                                                     }
                                                   }
                                                 ]
+                                              },
+                                              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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -185021,10 +185836,11 @@ var schemas_default = {
                                                 },
                                                 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 \u2014 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: {
@@ -185082,6 +185898,88 @@ var schemas_default = {
                                                       }
                                                     }
                                                   ]
+                                                },
+                                                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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -185148,6 +186046,17 @@ var schemas_default = {
                                             path: "results.mp4",
                                             engine: "ffmpeg"
                                           },
+                                          {
+                                            path: "results.mp4",
+                                            checkpoints: true
+                                          },
+                                          {
+                                            path: "results.mp4",
+                                            checkpoints: {
+                                              maxVariation: 0.02,
+                                              directory: "baselines/results"
+                                            }
+                                          },
                                           {
                                             path: "results.mp4",
                                             engine: {
@@ -228051,9 +228960,10 @@ var schemas_default = {
                                           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 \u2014 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"
                                               ]
@@ -228287,9 +229197,10 @@ var schemas_default = {
                                                     },
                                                     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 \u2014 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"
                                                       ]
@@ -228547,9 +229458,10 @@ var schemas_default = {
                                             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 \u2014 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"
                                                 ]
@@ -228783,9 +229695,10 @@ var schemas_default = {
                                                       },
                                                       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 \u2014 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"
                                                         ]
@@ -229259,9 +230172,10 @@ var schemas_default = {
                                                   },
                                                   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 \u2014 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"
                                                     ]
@@ -229643,6 +230557,7 @@ var schemas_default = {
                                             "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",
@@ -232077,10 +232992,11 @@ var schemas_default = {
                                                 },
                                                 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 \u2014 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: {
@@ -232138,6 +233054,88 @@ var schemas_default = {
                                                       }
                                                     }
                                                   ]
+                                                },
+                                                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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -232399,10 +233397,11 @@ var schemas_default = {
                                                   },
                                                   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 \u2014 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: {
@@ -232460,6 +233459,88 @@ var schemas_default = {
                                                         }
                                                       }
                                                     ]
+                                                  },
+                                                  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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -232526,6 +233607,17 @@ var schemas_default = {
                                               path: "results.mp4",
                                               engine: "ffmpeg"
                                             },
+                                            {
+                                              path: "results.mp4",
+                                              checkpoints: true
+                                            },
+                                            {
+                                              path: "results.mp4",
+                                              checkpoints: {
+                                                maxVariation: 0.02,
+                                                directory: "baselines/results"
+                                              }
+                                            },
                                             {
                                               path: "results.mp4",
                                               engine: {
@@ -272952,9 +274044,10 @@ var schemas_default = {
                                                 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 \u2014 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"
                                                     ]
@@ -273188,9 +274281,10 @@ var schemas_default = {
                                                           },
                                                           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 \u2014 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"
                                                             ]
@@ -273448,9 +274542,10 @@ var schemas_default = {
                                                   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 \u2014 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"
                                                       ]
@@ -273684,9 +274779,10 @@ var schemas_default = {
                                                             },
                                                             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 \u2014 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"
                                                               ]
@@ -274160,9 +275256,10 @@ var schemas_default = {
                                                         },
                                                         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 \u2014 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"
                                                           ]
@@ -274544,6 +275641,7 @@ var schemas_default = {
                                                   "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",
@@ -276978,10 +278076,11 @@ var schemas_default = {
                                                       },
                                                       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 \u2014 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: {
@@ -277039,6 +278138,88 @@ var schemas_default = {
                                                             }
                                                           }
                                                         ]
+                                                      },
+                                                      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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -277300,10 +278481,11 @@ var schemas_default = {
                                                         },
                                                         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 \u2014 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: {
@@ -277361,6 +278543,88 @@ var schemas_default = {
                                                               }
                                                             }
                                                           ]
+                                                        },
+                                                        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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -277427,6 +278691,17 @@ var schemas_default = {
                                                     path: "results.mp4",
                                                     engine: "ffmpeg"
                                                   },
+                                                  {
+                                                    path: "results.mp4",
+                                                    checkpoints: true
+                                                  },
+                                                  {
+                                                    path: "results.mp4",
+                                                    checkpoints: {
+                                                      maxVariation: 0.02,
+                                                      directory: "baselines/results"
+                                                    }
+                                                  },
                                                   {
                                                     path: "results.mp4",
                                                     engine: {
@@ -320814,9 +322089,10 @@ var schemas_default = {
                                           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 \u2014 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"
                                               ]
@@ -321050,9 +322326,10 @@ var schemas_default = {
                                                     },
                                                     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 \u2014 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"
                                                       ]
@@ -321310,9 +322587,10 @@ var schemas_default = {
                                             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 \u2014 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"
                                                 ]
@@ -321546,9 +322824,10 @@ var schemas_default = {
                                                       },
                                                       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 \u2014 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"
                                                         ]
@@ -322022,9 +323301,10 @@ var schemas_default = {
                                                   },
                                                   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 \u2014 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"
                                                     ]
@@ -322406,6 +323686,7 @@ var schemas_default = {
                                             "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",
@@ -324840,10 +326121,11 @@ var schemas_default = {
                                                 },
                                                 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 \u2014 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: {
@@ -324901,6 +326183,88 @@ var schemas_default = {
                                                       }
                                                     }
                                                   ]
+                                                },
+                                                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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -325162,10 +326526,11 @@ var schemas_default = {
                                                   },
                                                   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 \u2014 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: {
@@ -325223,6 +326588,88 @@ var schemas_default = {
                                                         }
                                                       }
                                                     ]
+                                                  },
+                                                  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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -325289,6 +326736,17 @@ var schemas_default = {
                                               path: "results.mp4",
                                               engine: "ffmpeg"
                                             },
+                                            {
+                                              path: "results.mp4",
+                                              checkpoints: true
+                                            },
+                                            {
+                                              path: "results.mp4",
+                                              checkpoints: {
+                                                maxVariation: 0.02,
+                                                directory: "baselines/results"
+                                              }
+                                            },
                                             {
                                               path: "results.mp4",
                                               engine: {
@@ -365715,9 +367173,10 @@ var schemas_default = {
                                                 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 \u2014 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"
                                                     ]
@@ -365951,9 +367410,10 @@ var schemas_default = {
                                                           },
                                                           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 \u2014 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"
                                                             ]
@@ -366211,9 +367671,10 @@ var schemas_default = {
                                                   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 \u2014 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"
                                                       ]
@@ -366447,9 +367908,10 @@ var schemas_default = {
                                                             },
                                                             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 \u2014 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"
                                                               ]
@@ -366923,9 +368385,10 @@ var schemas_default = {
                                                         },
                                                         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 \u2014 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"
                                                           ]
@@ -367307,6 +368770,7 @@ var schemas_default = {
                                                   "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",
@@ -369741,10 +371205,11 @@ var schemas_default = {
                                                       },
                                                       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 \u2014 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: {
@@ -369802,6 +371267,88 @@ var schemas_default = {
                                                             }
                                                           }
                                                         ]
+                                                      },
+                                                      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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -370063,10 +371610,11 @@ var schemas_default = {
                                                         },
                                                         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 \u2014 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: {
@@ -370124,6 +371672,88 @@ var schemas_default = {
                                                               }
                                                             }
                                                           ]
+                                                        },
+                                                        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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -370190,6 +371820,17 @@ var schemas_default = {
                                                     path: "results.mp4",
                                                     engine: "ffmpeg"
                                                   },
+                                                  {
+                                                    path: "results.mp4",
+                                                    checkpoints: true
+                                                  },
+                                                  {
+                                                    path: "results.mp4",
+                                                    checkpoints: {
+                                                      maxVariation: 0.02,
+                                                      directory: "baselines/results"
+                                                    }
+                                                  },
                                                   {
                                                     path: "results.mp4",
                                                     engine: {
@@ -385726,9 +387367,10 @@ var schemas_default = {
     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 \u2014 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"
         ]
@@ -385962,9 +387604,10 @@ var schemas_default = {
               },
               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 \u2014 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"
                 ]
@@ -386222,9 +387865,10 @@ var schemas_default = {
       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 \u2014 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"
           ]
@@ -386458,9 +388102,10 @@ var schemas_default = {
                 },
                 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 \u2014 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"
                   ]
@@ -386934,9 +388579,10 @@ var schemas_default = {
             },
             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 \u2014 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"
               ]
@@ -387318,6 +388964,7 @@ var schemas_default = {
       "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",
@@ -416901,9 +418548,10 @@ var schemas_default = {
                                 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 \u2014 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"
                                     ]
@@ -417137,9 +418785,10 @@ var schemas_default = {
                                           },
                                           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 \u2014 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"
                                             ]
@@ -417397,9 +419046,10 @@ var schemas_default = {
                                   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 \u2014 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"
                                       ]
@@ -417633,9 +419283,10 @@ var schemas_default = {
                                             },
                                             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 \u2014 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"
                                               ]
@@ -418109,9 +419760,10 @@ var schemas_default = {
                                         },
                                         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 \u2014 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"
                                           ]
@@ -418493,6 +420145,7 @@ var schemas_default = {
                                   "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",
@@ -420927,10 +422580,11 @@ var schemas_default = {
                                       },
                                       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 \u2014 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: {
@@ -420988,6 +422642,88 @@ var schemas_default = {
                                             }
                                           }
                                         ]
+                                      },
+                                      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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -421249,10 +422985,11 @@ var schemas_default = {
                                         },
                                         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 \u2014 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: {
@@ -421310,6 +423047,88 @@ var schemas_default = {
                                               }
                                             }
                                           ]
+                                        },
+                                        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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -421376,6 +423195,17 @@ var schemas_default = {
                                     path: "results.mp4",
                                     engine: "ffmpeg"
                                   },
+                                  {
+                                    path: "results.mp4",
+                                    checkpoints: true
+                                  },
+                                  {
+                                    path: "results.mp4",
+                                    checkpoints: {
+                                      maxVariation: 0.02,
+                                      directory: "baselines/results"
+                                    }
+                                  },
                                   {
                                     path: "results.mp4",
                                     engine: {
@@ -461802,9 +463632,10 @@ var schemas_default = {
                                       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 \u2014 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"
                                           ]
@@ -462038,9 +463869,10 @@ var schemas_default = {
                                                 },
                                                 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 \u2014 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"
                                                   ]
@@ -462298,9 +464130,10 @@ var schemas_default = {
                                         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 \u2014 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"
                                             ]
@@ -462534,9 +464367,10 @@ var schemas_default = {
                                                   },
                                                   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 \u2014 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"
                                                     ]
@@ -463010,9 +464844,10 @@ var schemas_default = {
                                               },
                                               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 \u2014 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"
                                                 ]
@@ -463394,6 +465229,7 @@ var schemas_default = {
                                         "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",
@@ -465828,10 +467664,11 @@ var schemas_default = {
                                             },
                                             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 \u2014 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: {
@@ -465889,6 +467726,88 @@ var schemas_default = {
                                                   }
                                                 }
                                               ]
+                                            },
+                                            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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -466150,10 +468069,11 @@ var schemas_default = {
                                               },
                                               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 \u2014 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: {
@@ -466211,6 +468131,88 @@ var schemas_default = {
                                                     }
                                                   }
                                                 ]
+                                              },
+                                              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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -466277,6 +468279,17 @@ var schemas_default = {
                                           path: "results.mp4",
                                           engine: "ffmpeg"
                                         },
+                                        {
+                                          path: "results.mp4",
+                                          checkpoints: true
+                                        },
+                                        {
+                                          path: "results.mp4",
+                                          checkpoints: {
+                                            maxVariation: 0.02,
+                                            directory: "baselines/results"
+                                          }
+                                        },
                                         {
                                           path: "results.mp4",
                                           engine: {
@@ -508395,9 +510408,10 @@ var schemas_default = {
                 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 \u2014 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"
                     ]
@@ -508631,9 +510645,10 @@ var schemas_default = {
                           },
                           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 \u2014 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"
                             ]
@@ -508891,9 +510906,10 @@ var schemas_default = {
                   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 \u2014 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"
                       ]
@@ -509127,9 +511143,10 @@ var schemas_default = {
                             },
                             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 \u2014 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"
                               ]
@@ -509603,9 +511620,10 @@ var schemas_default = {
                         },
                         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 \u2014 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"
                           ]
@@ -509987,6 +512005,7 @@ var schemas_default = {
                   "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",
@@ -512421,10 +514440,11 @@ var schemas_default = {
                       },
                       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 \u2014 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: {
@@ -512482,6 +514502,88 @@ var schemas_default = {
                             }
                           }
                         ]
+                      },
+                      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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -512743,10 +514845,11 @@ var schemas_default = {
                         },
                         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 \u2014 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: {
@@ -512804,6 +514907,88 @@ var schemas_default = {
                               }
                             }
                           ]
+                        },
+                        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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -512870,6 +515055,17 @@ var schemas_default = {
                     path: "results.mp4",
                     engine: "ffmpeg"
                   },
+                  {
+                    path: "results.mp4",
+                    checkpoints: true
+                  },
+                  {
+                    path: "results.mp4",
+                    checkpoints: {
+                      maxVariation: 0.02,
+                      directory: "baselines/results"
+                    }
+                  },
                   {
                     path: "results.mp4",
                     engine: {
@@ -556641,9 +558837,10 @@ var schemas_default = {
                       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 \u2014 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"
                           ]
@@ -556877,9 +559074,10 @@ var schemas_default = {
                                 },
                                 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 \u2014 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"
                                   ]
@@ -557137,9 +559335,10 @@ var schemas_default = {
                         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 \u2014 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"
                             ]
@@ -557373,9 +559572,10 @@ var schemas_default = {
                                   },
                                   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 \u2014 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"
                                     ]
@@ -557849,9 +560049,10 @@ var schemas_default = {
                               },
                               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 \u2014 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"
                                 ]
@@ -558233,6 +560434,7 @@ var schemas_default = {
                         "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",
@@ -560667,10 +562869,11 @@ var schemas_default = {
                             },
                             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 \u2014 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: {
@@ -560728,6 +562931,88 @@ var schemas_default = {
                                   }
                                 }
                               ]
+                            },
+                            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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -560989,10 +563274,11 @@ var schemas_default = {
                               },
                               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 \u2014 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: {
@@ -561050,6 +563336,88 @@ var schemas_default = {
                                     }
                                   }
                                 ]
+                              },
+                              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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -561116,6 +563484,17 @@ var schemas_default = {
                           path: "results.mp4",
                           engine: "ffmpeg"
                         },
+                        {
+                          path: "results.mp4",
+                          checkpoints: true
+                        },
+                        {
+                          path: "results.mp4",
+                          checkpoints: {
+                            maxVariation: 0.02,
+                            directory: "baselines/results"
+                          }
+                        },
                         {
                           path: "results.mp4",
                           engine: {
@@ -601542,9 +603921,10 @@ var schemas_default = {
                             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 \u2014 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"
                                 ]
@@ -601778,9 +604158,10 @@ var schemas_default = {
                                       },
                                       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 \u2014 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"
                                         ]
@@ -602038,9 +604419,10 @@ var schemas_default = {
                               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 \u2014 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"
                                   ]
@@ -602274,9 +604656,10 @@ var schemas_default = {
                                         },
                                         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 \u2014 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"
                                           ]
@@ -602750,9 +605133,10 @@ var schemas_default = {
                                     },
                                     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 \u2014 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"
                                       ]
@@ -603134,6 +605518,7 @@ var schemas_default = {
                               "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",
@@ -605568,10 +607953,11 @@ var schemas_default = {
                                   },
                                   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 \u2014 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: {
@@ -605629,6 +608015,88 @@ var schemas_default = {
                                         }
                                       }
                                     ]
+                                  },
+                                  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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -605890,10 +608358,11 @@ var schemas_default = {
                                     },
                                     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 \u2014 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: {
@@ -605951,6 +608420,88 @@ var schemas_default = {
                                           }
                                         }
                                       ]
+                                    },
+                                    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 \u2014 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 (\xB12 pixels \u2014 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) \u2014 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)"
@@ -606017,6 +608568,17 @@ var schemas_default = {
                                 path: "results.mp4",
                                 engine: "ffmpeg"
                               },
+                              {
+                                path: "results.mp4",
+                                checkpoints: true
+                              },
+                              {
+                                path: "results.mp4",
+                                checkpoints: {
+                                  maxVariation: 0.02,
+                                  directory: "baselines/results"
+                                }
+                              },
                               {
                                 path: "results.mp4",
                                 engine: {