doc-detective 4.32.0 → 4.33.0

package/dist/index.cjs

@@ -30470,9 +30470,10 @@ var init_schemas = __esm({
                                                       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"
                                                           ]
@@ -30706,9 +30707,10 @@ var init_schemas = __esm({
                                                                 },
                                                                 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"
                                                                   ]
@@ -30966,9 +30968,10 @@ var init_schemas = __esm({
                                                         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"
                                                             ]
@@ -31202,9 +31205,10 @@ var init_schemas = __esm({
                                                                   },
                                                                   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"
                                                                     ]
@@ -31678,9 +31682,10 @@ var init_schemas = __esm({
                                                               },
                                                               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"
                                                                 ]
@@ -32062,6 +32067,7 @@ var init_schemas = __esm({
                                                         "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",
@@ -34496,10 +34502,11 @@ var init_schemas = __esm({
                                                             },
                                                             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: {
@@ -34557,6 +34564,38 @@ var init_schemas = __esm({
                                                                   }
                                                                 }
                                                               ]
+                                                            },
+                                                            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)"
@@ -34818,10 +34857,11 @@ var init_schemas = __esm({
                                                               },
                                                               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: {
@@ -34879,6 +34919,38 @@ var init_schemas = __esm({
                                                                     }
                                                                   }
                                                                 ]
+                                                              },
+                                                              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)"
@@ -34945,6 +35017,17 @@ var init_schemas = __esm({
                                                           path: "results.mp4",
                                                           engine: "ffmpeg"
                                                         },
+                                                        {
+                                                          path: "results.mp4",
+                                                          checkpoints: true
+                                                        },
+                                                        {
+                                                          path: "results.mp4",
+                                                          checkpoints: {
+                                                            maxVariation: 0.02,
+                                                            directory: "baselines/results"
+                                                          }
+                                                        },
                                                         {
                                                           path: "results.mp4",
                                                           engine: {
@@ -76109,9 +76192,10 @@ var init_schemas = __esm({
                                         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"
                                             ]
@@ -76345,9 +76429,10 @@ var init_schemas = __esm({
                                                   },
                                                   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"
                                                     ]
@@ -76605,9 +76690,10 @@ var init_schemas = __esm({
                                           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"
                                               ]
@@ -76841,9 +76927,10 @@ var init_schemas = __esm({
                                                     },
                                                     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"
                                                       ]
@@ -77317,9 +77404,10 @@ var init_schemas = __esm({
                                                 },
                                                 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"
                                                   ]
@@ -77701,6 +77789,7 @@ var init_schemas = __esm({
                                           "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",
@@ -80135,10 +80224,11 @@ var init_schemas = __esm({
                                               },
                                               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: {
@@ -80196,6 +80286,38 @@ var init_schemas = __esm({
                                                     }
                                                   }
                                                 ]
+                                              },
+                                              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)"
@@ -80457,10 +80579,11 @@ var init_schemas = __esm({
                                                 },
                                                 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: {
@@ -80518,6 +80641,38 @@ var init_schemas = __esm({
                                                       }
                                                     }
                                                   ]
+                                                },
+                                                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)"
@@ -80584,6 +80739,17 @@ var init_schemas = __esm({
                                             path: "results.mp4",
                                             engine: "ffmpeg"
                                           },
+                                          {
+                                            path: "results.mp4",
+                                            checkpoints: true
+                                          },
+                                          {
+                                            path: "results.mp4",
+                                            checkpoints: {
+                                              maxVariation: 0.02,
+                                              directory: "baselines/results"
+                                            }
+                                          },
                                           {
                                             path: "results.mp4",
                                             engine: {
@@ -106420,10 +106586,11 @@ var init_schemas = __esm({
               },
               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: {
@@ -106481,6 +106648,38 @@ var init_schemas = __esm({
                     }
                   }
                 ]
+              },
+              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)"
@@ -106742,10 +106941,11 @@ var init_schemas = __esm({
                 },
                 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: {
@@ -106803,6 +107003,38 @@ var init_schemas = __esm({
                       }
                     }
                   ]
+                },
+                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)"
@@ -106869,6 +107101,17 @@ var init_schemas = __esm({
             path: "results.mp4",
             engine: "ffmpeg"
           },
+          {
+            path: "results.mp4",
+            checkpoints: true
+          },
+          {
+            path: "results.mp4",
+            checkpoints: {
+              maxVariation: 0.02,
+              directory: "baselines/results"
+            }
+          },
           {
             path: "results.mp4",
             engine: {
@@ -135035,9 +135278,10 @@ var init_schemas = __esm({
                                                           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"
                                                               ]
@@ -135271,9 +135515,10 @@ var init_schemas = __esm({
                                                                     },
                                                                     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"
                                                                       ]
@@ -135531,9 +135776,10 @@ var init_schemas = __esm({
                                                             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"
                                                                 ]
@@ -135767,9 +136013,10 @@ var init_schemas = __esm({
                                                                       },
                                                                       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"
                                                                         ]
@@ -136243,9 +136490,10 @@ var init_schemas = __esm({
                                                                   },
                                                                   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"
                                                                     ]
@@ -136627,6 +136875,7 @@ var init_schemas = __esm({
                                                             "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",
@@ -139061,10 +139310,11 @@ var init_schemas = __esm({
                                                                 },
                                                                 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: {
@@ -139122,6 +139372,38 @@ var init_schemas = __esm({
                                                                       }
                                                                     }
                                                                   ]
+                                                                },
+                                                                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)"
@@ -139383,10 +139665,11 @@ var init_schemas = __esm({
                                                                   },
                                                                   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: {
@@ -139444,6 +139727,38 @@ var init_schemas = __esm({
                                                                         }
                                                                       }
                                                                     ]
+                                                                  },
+                                                                  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)"
@@ -139510,6 +139825,17 @@ var init_schemas = __esm({
                                                               path: "results.mp4",
                                                               engine: "ffmpeg"
                                                             },
+                                                            {
+                                                              path: "results.mp4",
+                                                              checkpoints: true
+                                                            },
+                                                            {
+                                                              path: "results.mp4",
+                                                              checkpoints: {
+                                                                maxVariation: 0.02,
+                                                                directory: "baselines/results"
+                                                              }
+                                                            },
                                                             {
                                                               path: "results.mp4",
                                                               engine: {
@@ -180674,9 +181000,10 @@ var init_schemas = __esm({
                                             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"
                                                 ]
@@ -180910,9 +181237,10 @@ var init_schemas = __esm({
                                                       },
                                                       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"
                                                         ]
@@ -181170,9 +181498,10 @@ var init_schemas = __esm({
                                               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"
                                                   ]
@@ -181406,9 +181735,10 @@ var init_schemas = __esm({
                                                         },
                                                         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"
                                                           ]
@@ -181882,9 +182212,10 @@ var init_schemas = __esm({
                                                     },
                                                     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"
                                                       ]
@@ -182266,6 +182597,7 @@ var init_schemas = __esm({
                                               "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",
@@ -184700,10 +185032,11 @@ var init_schemas = __esm({
                                                   },
                                                   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: {
@@ -184761,6 +185094,38 @@ var init_schemas = __esm({
                                                         }
                                                       }
                                                     ]
+                                                  },
+                                                  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)"
@@ -185022,10 +185387,11 @@ var init_schemas = __esm({
                                                     },
                                                     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: {
@@ -185083,6 +185449,38 @@ var init_schemas = __esm({
                                                           }
                                                         }
                                                       ]
+                                                    },
+                                                    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)"
@@ -185149,6 +185547,17 @@ var init_schemas = __esm({
                                                 path: "results.mp4",
                                                 engine: "ffmpeg"
                                               },
+                                              {
+                                                path: "results.mp4",
+                                                checkpoints: true
+                                              },
+                                              {
+                                                path: "results.mp4",
+                                                checkpoints: {
+                                                  maxVariation: 0.02,
+                                                  directory: "baselines/results"
+                                                }
+                                              },
                                               {
                                                 path: "results.mp4",
                                                 engine: {
@@ -228052,9 +228461,10 @@ var init_schemas = __esm({
                                               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"
                                                   ]
@@ -228288,9 +228698,10 @@ var init_schemas = __esm({
                                                         },
                                                         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"
                                                           ]
@@ -228548,9 +228959,10 @@ var init_schemas = __esm({
                                                 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"
                                                     ]
@@ -228784,9 +229196,10 @@ var init_schemas = __esm({
                                                           },
                                                           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"
                                                             ]
@@ -229260,9 +229673,10 @@ var init_schemas = __esm({
                                                       },
                                                       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"
                                                         ]
@@ -229644,6 +230058,7 @@ var init_schemas = __esm({
                                                 "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",
@@ -232078,10 +232493,11 @@ var init_schemas = __esm({
                                                     },
                                                     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: {
@@ -232139,6 +232555,38 @@ var init_schemas = __esm({
                                                           }
                                                         }
                                                       ]
+                                                    },
+                                                    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)"
@@ -232400,10 +232848,11 @@ var init_schemas = __esm({
                                                       },
                                                       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: {
@@ -232461,6 +232910,38 @@ var init_schemas = __esm({
                                                             }
                                                           }
                                                         ]
+                                                      },
+                                                      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)"
@@ -232527,6 +233008,17 @@ var init_schemas = __esm({
                                                   path: "results.mp4",
                                                   engine: "ffmpeg"
                                                 },
+                                                {
+                                                  path: "results.mp4",
+                                                  checkpoints: true
+                                                },
+                                                {
+                                                  path: "results.mp4",
+                                                  checkpoints: {
+                                                    maxVariation: 0.02,
+                                                    directory: "baselines/results"
+                                                  }
+                                                },
                                                 {
                                                   path: "results.mp4",
                                                   engine: {
@@ -272953,9 +273445,10 @@ var init_schemas = __esm({
                                                     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"
                                                         ]
@@ -273189,9 +273682,10 @@ var init_schemas = __esm({
                                                               },
                                                               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"
                                                                 ]
@@ -273449,9 +273943,10 @@ var init_schemas = __esm({
                                                       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"
                                                           ]
@@ -273685,9 +274180,10 @@ var init_schemas = __esm({
                                                                 },
                                                                 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"
                                                                   ]
@@ -274161,9 +274657,10 @@ var init_schemas = __esm({
                                                             },
                                                             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"
                                                               ]
@@ -274545,6 +275042,7 @@ var init_schemas = __esm({
                                                       "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",
@@ -276979,10 +277477,11 @@ var init_schemas = __esm({
                                                           },
                                                           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: {
@@ -277040,6 +277539,38 @@ var init_schemas = __esm({
                                                                 }
                                                               }
                                                             ]
+                                                          },
+                                                          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)"
@@ -277301,10 +277832,11 @@ var init_schemas = __esm({
                                                             },
                                                             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: {
@@ -277362,6 +277894,38 @@ var init_schemas = __esm({
                                                                   }
                                                                 }
                                                               ]
+                                                            },
+                                                            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)"
@@ -277428,6 +277992,17 @@ var init_schemas = __esm({
                                                         path: "results.mp4",
                                                         engine: "ffmpeg"
                                                       },
+                                                      {
+                                                        path: "results.mp4",
+                                                        checkpoints: true
+                                                      },
+                                                      {
+                                                        path: "results.mp4",
+                                                        checkpoints: {
+                                                          maxVariation: 0.02,
+                                                          directory: "baselines/results"
+                                                        }
+                                                      },
                                                       {
                                                         path: "results.mp4",
                                                         engine: {
@@ -320815,9 +321390,10 @@ var init_schemas = __esm({
                                               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"
                                                   ]
@@ -321051,9 +321627,10 @@ var init_schemas = __esm({
                                                         },
                                                         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"
                                                           ]
@@ -321311,9 +321888,10 @@ var init_schemas = __esm({
                                                 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"
                                                     ]
@@ -321547,9 +322125,10 @@ var init_schemas = __esm({
                                                           },
                                                           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"
                                                             ]
@@ -322023,9 +322602,10 @@ var init_schemas = __esm({
                                                       },
                                                       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"
                                                         ]
@@ -322407,6 +322987,7 @@ var init_schemas = __esm({
                                                 "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",
@@ -324841,10 +325422,11 @@ var init_schemas = __esm({
                                                     },
                                                     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: {
@@ -324902,6 +325484,38 @@ var init_schemas = __esm({
                                                           }
                                                         }
                                                       ]
+                                                    },
+                                                    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)"
@@ -325163,10 +325777,11 @@ var init_schemas = __esm({
                                                       },
                                                       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: {
@@ -325224,6 +325839,38 @@ var init_schemas = __esm({
                                                             }
                                                           }
                                                         ]
+                                                      },
+                                                      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)"
@@ -325290,6 +325937,17 @@ var init_schemas = __esm({
                                                   path: "results.mp4",
                                                   engine: "ffmpeg"
                                                 },
+                                                {
+                                                  path: "results.mp4",
+                                                  checkpoints: true
+                                                },
+                                                {
+                                                  path: "results.mp4",
+                                                  checkpoints: {
+                                                    maxVariation: 0.02,
+                                                    directory: "baselines/results"
+                                                  }
+                                                },
                                                 {
                                                   path: "results.mp4",
                                                   engine: {
@@ -365716,9 +366374,10 @@ var init_schemas = __esm({
                                                     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"
                                                         ]
@@ -365952,9 +366611,10 @@ var init_schemas = __esm({
                                                               },
                                                               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"
                                                                 ]
@@ -366212,9 +366872,10 @@ var init_schemas = __esm({
                                                       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"
                                                           ]
@@ -366448,9 +367109,10 @@ var init_schemas = __esm({
                                                                 },
                                                                 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"
                                                                   ]
@@ -366924,9 +367586,10 @@ var init_schemas = __esm({
                                                             },
                                                             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"
                                                               ]
@@ -367308,6 +367971,7 @@ var init_schemas = __esm({
                                                       "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",
@@ -369742,10 +370406,11 @@ var init_schemas = __esm({
                                                           },
                                                           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: {
@@ -369803,6 +370468,38 @@ var init_schemas = __esm({
                                                                 }
                                                               }
                                                             ]
+                                                          },
+                                                          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)"
@@ -370064,10 +370761,11 @@ var init_schemas = __esm({
                                                             },
                                                             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: {
@@ -370125,6 +370823,38 @@ var init_schemas = __esm({
                                                                   }
                                                                 }
                                                               ]
+                                                            },
+                                                            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)"
@@ -370191,6 +370921,17 @@ var init_schemas = __esm({
                                                         path: "results.mp4",
                                                         engine: "ffmpeg"
                                                       },
+                                                      {
+                                                        path: "results.mp4",
+                                                        checkpoints: true
+                                                      },
+                                                      {
+                                                        path: "results.mp4",
+                                                        checkpoints: {
+                                                          maxVariation: 0.02,
+                                                          directory: "baselines/results"
+                                                        }
+                                                      },
                                                       {
                                                         path: "results.mp4",
                                                         engine: {
@@ -385727,9 +386468,10 @@ var init_schemas = __esm({
         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"
             ]
@@ -385963,9 +386705,10 @@ var init_schemas = __esm({
                   },
                   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"
                     ]
@@ -386223,9 +386966,10 @@ var init_schemas = __esm({
           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"
               ]
@@ -386459,9 +387203,10 @@ var init_schemas = __esm({
                     },
                     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"
                       ]
@@ -386935,9 +387680,10 @@ var init_schemas = __esm({
                 },
                 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"
                   ]
@@ -387319,6 +388065,7 @@ var init_schemas = __esm({
           "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",
@@ -416902,9 +417649,10 @@ var init_schemas = __esm({
                                     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"
                                         ]
@@ -417138,9 +417886,10 @@ var init_schemas = __esm({
                                               },
                                               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"
                                                 ]
@@ -417398,9 +418147,10 @@ var init_schemas = __esm({
                                       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"
                                           ]
@@ -417634,9 +418384,10 @@ var init_schemas = __esm({
                                                 },
                                                 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"
                                                   ]
@@ -418110,9 +418861,10 @@ var init_schemas = __esm({
                                             },
                                             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"
                                               ]
@@ -418494,6 +419246,7 @@ var init_schemas = __esm({
                                       "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",
@@ -420928,10 +421681,11 @@ var init_schemas = __esm({
                                           },
                                           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: {
@@ -420989,6 +421743,38 @@ var init_schemas = __esm({
                                                 }
                                               }
                                             ]
+                                          },
+                                          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)"
@@ -421250,10 +422036,11 @@ var init_schemas = __esm({
                                             },
                                             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: {
@@ -421311,6 +422098,38 @@ var init_schemas = __esm({
                                                   }
                                                 }
                                               ]
+                                            },
+                                            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)"
@@ -421377,6 +422196,17 @@ var init_schemas = __esm({
                                         path: "results.mp4",
                                         engine: "ffmpeg"
                                       },
+                                      {
+                                        path: "results.mp4",
+                                        checkpoints: true
+                                      },
+                                      {
+                                        path: "results.mp4",
+                                        checkpoints: {
+                                          maxVariation: 0.02,
+                                          directory: "baselines/results"
+                                        }
+                                      },
                                       {
                                         path: "results.mp4",
                                         engine: {
@@ -461803,9 +462633,10 @@ var init_schemas = __esm({
                                           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"
                                               ]
@@ -462039,9 +462870,10 @@ var init_schemas = __esm({
                                                     },
                                                     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"
                                                       ]
@@ -462299,9 +463131,10 @@ var init_schemas = __esm({
                                             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"
                                                 ]
@@ -462535,9 +463368,10 @@ var init_schemas = __esm({
                                                       },
                                                       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"
                                                         ]
@@ -463011,9 +463845,10 @@ var init_schemas = __esm({
                                                   },
                                                   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"
                                                     ]
@@ -463395,6 +464230,7 @@ var init_schemas = __esm({
                                             "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",
@@ -465829,10 +466665,11 @@ var init_schemas = __esm({
                                                 },
                                                 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: {
@@ -465890,6 +466727,38 @@ var init_schemas = __esm({
                                                       }
                                                     }
                                                   ]
+                                                },
+                                                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)"
@@ -466151,10 +467020,11 @@ var init_schemas = __esm({
                                                   },
                                                   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: {
@@ -466212,6 +467082,38 @@ var init_schemas = __esm({
                                                         }
                                                       }
                                                     ]
+                                                  },
+                                                  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)"
@@ -466278,6 +467180,17 @@ var init_schemas = __esm({
                                               path: "results.mp4",
                                               engine: "ffmpeg"
                                             },
+                                            {
+                                              path: "results.mp4",
+                                              checkpoints: true
+                                            },
+                                            {
+                                              path: "results.mp4",
+                                              checkpoints: {
+                                                maxVariation: 0.02,
+                                                directory: "baselines/results"
+                                              }
+                                            },
                                             {
                                               path: "results.mp4",
                                               engine: {
@@ -508396,9 +509309,10 @@ var init_schemas = __esm({
                     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"
                         ]
@@ -508632,9 +509546,10 @@ var init_schemas = __esm({
                               },
                               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"
                                 ]
@@ -508892,9 +509807,10 @@ var init_schemas = __esm({
                       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"
                           ]
@@ -509128,9 +510044,10 @@ var init_schemas = __esm({
                                 },
                                 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"
                                   ]
@@ -509604,9 +510521,10 @@ var init_schemas = __esm({
                             },
                             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"
                               ]
@@ -509988,6 +510906,7 @@ var init_schemas = __esm({
                       "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",
@@ -512422,10 +513341,11 @@ var init_schemas = __esm({
                           },
                           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: {
@@ -512483,6 +513403,38 @@ var init_schemas = __esm({
                                 }
                               }
                             ]
+                          },
+                          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)"
@@ -512744,10 +513696,11 @@ var init_schemas = __esm({
                             },
                             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: {
@@ -512805,6 +513758,38 @@ var init_schemas = __esm({
                                   }
                                 }
                               ]
+                            },
+                            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)"
@@ -512871,6 +513856,17 @@ var init_schemas = __esm({
                         path: "results.mp4",
                         engine: "ffmpeg"
                       },
+                      {
+                        path: "results.mp4",
+                        checkpoints: true
+                      },
+                      {
+                        path: "results.mp4",
+                        checkpoints: {
+                          maxVariation: 0.02,
+                          directory: "baselines/results"
+                        }
+                      },
                       {
                         path: "results.mp4",
                         engine: {
@@ -556642,9 +557638,10 @@ var init_schemas = __esm({
                           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"
                               ]
@@ -556878,9 +557875,10 @@ var init_schemas = __esm({
                                     },
                                     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"
                                       ]
@@ -557138,9 +558136,10 @@ var init_schemas = __esm({
                             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"
                                 ]
@@ -557374,9 +558373,10 @@ var init_schemas = __esm({
                                       },
                                       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"
                                         ]
@@ -557850,9 +558850,10 @@ var init_schemas = __esm({
                                   },
                                   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"
                                     ]
@@ -558234,6 +559235,7 @@ var init_schemas = __esm({
                             "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",
@@ -560668,10 +561670,11 @@ var init_schemas = __esm({
                                 },
                                 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: {
@@ -560729,6 +561732,38 @@ var init_schemas = __esm({
                                       }
                                     }
                                   ]
+                                },
+                                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)"
@@ -560990,10 +562025,11 @@ var init_schemas = __esm({
                                   },
                                   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: {
@@ -561051,6 +562087,38 @@ var init_schemas = __esm({
                                         }
                                       }
                                     ]
+                                  },
+                                  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)"
@@ -561117,6 +562185,17 @@ var init_schemas = __esm({
                               path: "results.mp4",
                               engine: "ffmpeg"
                             },
+                            {
+                              path: "results.mp4",
+                              checkpoints: true
+                            },
+                            {
+                              path: "results.mp4",
+                              checkpoints: {
+                                maxVariation: 0.02,
+                                directory: "baselines/results"
+                              }
+                            },
                             {
                               path: "results.mp4",
                               engine: {
@@ -601543,9 +602622,10 @@ var init_schemas = __esm({
                                 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"
                                     ]
@@ -601779,9 +602859,10 @@ var init_schemas = __esm({
                                           },
                                           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"
                                             ]
@@ -602039,9 +603120,10 @@ var init_schemas = __esm({
                                   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"
                                       ]
@@ -602275,9 +603357,10 @@ var init_schemas = __esm({
                                             },
                                             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"
                                               ]
@@ -602751,9 +603834,10 @@ var init_schemas = __esm({
                                         },
                                         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"
                                           ]
@@ -603135,6 +604219,7 @@ var init_schemas = __esm({
                                   "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",
@@ -605569,10 +606654,11 @@ var init_schemas = __esm({
                                       },
                                       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: {
@@ -605630,6 +606716,38 @@ var init_schemas = __esm({
                                             }
                                           }
                                         ]
+                                      },
+                                      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)"
@@ -605891,10 +607009,11 @@ var init_schemas = __esm({
                                         },
                                         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: {
@@ -605952,6 +607071,38 @@ var init_schemas = __esm({
                                               }
                                             }
                                           ]
+                                        },
+                                        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)"
@@ -606018,6 +607169,17 @@ var init_schemas = __esm({
                                     path: "results.mp4",
                                     engine: "ffmpeg"
                                   },
+                                  {
+                                    path: "results.mp4",
+                                    checkpoints: true
+                                  },
+                                  {
+                                    path: "results.mp4",
+                                    checkpoints: {
+                                      maxVariation: 0.02,
+                                      directory: "baselines/results"
+                                    }
+                                  },
                                   {
                                     path: "results.mp4",
                                     engine: {
@@ -634667,12 +635829,12 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
   }
   if (!force && existing && isStillFresh(existing.latestCheckedAt, now)) {
     if (existing.latestKnownVersion === existing.installedVersion) {
-      const path29 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
-      return { path: path29, version: existing.installedVersion, outdated: false };
+      const path30 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
+      return { path: path30, version: existing.installedVersion, outdated: false };
     }
-    const path28 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
+    const path29 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
     logger(`${name} ${existing.installedVersion} installed in ${cacheDir}; "${BROWSER_CHANNELS[name]}" channel is now ${existing.latestKnownVersion}. Run \`doc-detective install browsers ${name} --force\` to update.`, "warn");
-    return { path: path28, version: existing.installedVersion, outdated: true };
+    return { path: path29, version: existing.installedVersion, outdated: true };
   }
   let latest;
   try {
@@ -634680,8 +635842,8 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
   } catch (err) {
     logger(`Channel resolution for ${name} skipped: ${String(err)}`, "debug");
     if (existing) {
-      const path28 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
-      return { path: path28, version: existing.installedVersion, outdated: false };
+      const path29 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
+      return { path: path29, version: existing.installedVersion, outdated: false };
     }
     throw err;
   }
@@ -634692,8 +635854,8 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
       latestCheckedAt: now.toISOString()
     };
     writeInstalledRecord(record, ctx);
-    const path28 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
-    return { path: path28, version: latest, outdated: false };
+    const path29 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
+    return { path: path29, version: latest, outdated: false };
   }
   if (!force && existing) {
     record.browsers[name] = {
@@ -634703,8 +635865,8 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
     };
     writeInstalledRecord(record, ctx);
     logger(`${name} ${existing.installedVersion} installed in ${cacheDir}; "${BROWSER_CHANNELS[name]}" channel is now ${latest}. Run \`doc-detective install browsers ${name} --force\` to update.`, "warn");
-    const path28 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
-    return { path: path28, version: existing.installedVersion, outdated: true };
+    const path29 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
+    return { path: path29, version: existing.installedVersion, outdated: true };
   }
   logger(`Installing ${name} ${latest} into ${cacheDir}`, "info");
   await browsersModule.install({
@@ -634712,9 +635874,9 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
     buildId: latest,
     cacheDir
   });
-  let path27 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
-  if (name === "chromedriver" && isAllowedDriverPath(path27)) {
-    let verify = await verifyDriverBinary(name, path27, { exec: deps.verifyExec });
+  let path28 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
+  if (name === "chromedriver" && isAllowedDriverPath(path28)) {
+    let verify = await verifyDriverBinary(name, path28, { exec: deps.verifyExec });
     if (!verify.ok) {
       logger(`Installed ${name} ${latest} failed validation (${verify.error}); reinstalling once.`, "warn");
       try {
@@ -634723,11 +635885,11 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
         logger(`Failed to prune broken ${name} ${latest}: ${String(err)}`, "debug");
       }
       await browsersModule.install({ browser: name, buildId: latest, cacheDir });
-      path27 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
-      verify = await verifyDriverBinary(name, path27, { exec: deps.verifyExec });
+      path28 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
+      verify = await verifyDriverBinary(name, path28, { exec: deps.verifyExec });
     }
     if (!verify.ok) {
-      throw new Error(`${name} ${latest} is present but non-functional after a reinstall (${verify.error}). It may be a partial or corrupt download; delete ${path27} or reinstall.`);
+      throw new Error(`${name} ${latest} is present but non-functional after a reinstall (${verify.error}). It may be a partial or corrupt download; delete ${path28} or reinstall.`);
     }
   }
   if (existing && existing.installedVersion !== latest) {
@@ -634748,7 +635910,7 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
     latestCheckedAt: now.toISOString()
   };
   writeInstalledRecord(record, ctx);
-  return { path: path27, version: latest, outdated: false };
+  return { path: path28, version: latest, outdated: false };
 }
 async function locateExecutable(browsersModule, name, buildId, cacheDir, platform) {
   if (typeof browsersModule.computeExecutablePath === "function") {
@@ -635201,10 +636363,10 @@ async function getOperation(definition = {}, operationId = "", responseCode = ""
   if (!operationId) {
     throw new Error("OperationId is required.");
   }
-  for (const path27 in definition.paths) {
-    for (const method in definition.paths[path27]) {
-      if (definition.paths[path27][method].operationId === operationId) {
-        const operation = definition.paths[path27][method];
+  for (const path28 in definition.paths) {
+    for (const method in definition.paths[path28]) {
+      if (definition.paths[path28][method].operationId === operationId) {
+        const operation = definition.paths[path28][method];
         if (!server) {
           if (definition.servers && definition.servers.length > 0) {
             server = definition.servers[0].url;
@@ -635212,9 +636374,9 @@ async function getOperation(definition = {}, operationId = "", responseCode = ""
             throw new Error("No server URL provided and no servers defined in the OpenAPI definition.");
           }
         }
-        const example = await compileExample(operation, server + path27, responseCode, exampleKey);
+        const example = await compileExample(operation, server + path28, responseCode, exampleKey);
         const schemas2 = getSchemas(operation, responseCode);
-        return { path: path27, method, definition: operation, schemas: schemas2, example };
+        return { path: path28, method, definition: operation, schemas: schemas2, example };
       }
     }
   }
@@ -635235,15 +636397,15 @@ function getSchemas(definition = {}, responseCode = "") {
   schemas2.response = definition.responses[responseCode].content[Object.keys(definition.responses[responseCode].content)[0]].schema;
   return schemas2;
 }
-async function compileExample(operation = {}, path27 = "", responseCode = "", exampleKey = "") {
+async function compileExample(operation = {}, path28 = "", responseCode = "", exampleKey = "") {
   if (!operation) {
     throw new Error("Operation is required.");
   }
-  if (!path27) {
+  if (!path28) {
     throw new Error("Path is required.");
   }
   let example = {
-    url: path27,
+    url: path28,
     request: { parameters: {}, headers: {}, body: {} },
     response: { headers: {}, body: {} }
   };
@@ -639194,11 +640356,11 @@ init_utils();
 
 // dist/core/tests.js
 var import_tree_kill3 = __toESM(require("tree-kill"), 1);
-var import_node_fs29 = __toESM(require("node:fs"), 1);
+var import_node_fs30 = __toESM(require("node:fs"), 1);
 init_loader();
 init_browsers();
 init_browserStepKeys();
-var import_node_os11 = __toESM(require("node:os"), 1);
+var import_node_os12 = __toESM(require("node:os"), 1);
 init_utils();
 var import_axios6 = __toESM(require("axios"), 1);
 
@@ -639940,22 +641102,22 @@ function computeWdaKey(xcode, driverVersion) {
 var RUNNER_APP_RELATIVE = import_node_path12.default.join("DerivedData", "Build", "Products", "Debug-iphonesimulator", "WebDriverAgentRunner-Runner.app");
 var PRODUCTS_MARKER = "products.json";
 var LAST_USED_STAMP = "last-used";
-function readProductsMarker(keyDir, fs28) {
+function readProductsMarker(keyDir, fs29) {
   try {
-    const parsed = JSON.parse(String(fs28.readFileSync(import_node_path12.default.join(keyDir, PRODUCTS_MARKER))));
+    const parsed = JSON.parse(String(fs29.readFileSync(import_node_path12.default.join(keyDir, PRODUCTS_MARKER))));
     if (typeof parsed?.key !== "string" || typeof parsed?.driverVersion !== "string") {
       return null;
     }
-    if (!fs28.existsSync(import_node_path12.default.join(keyDir, RUNNER_APP_RELATIVE)))
+    if (!fs29.existsSync(import_node_path12.default.join(keyDir, RUNNER_APP_RELATIVE)))
       return null;
     return parsed;
   } catch {
     return null;
   }
 }
-function touchLastUsed(keyDir, fs28, now) {
+function touchLastUsed(keyDir, fs29, now) {
   try {
-    fs28.writeFileSync(import_node_path12.default.join(keyDir, LAST_USED_STAMP), String(now()));
+    fs29.writeFileSync(import_node_path12.default.join(keyDir, LAST_USED_STAMP), String(now()));
   } catch {
   }
 }
@@ -639977,7 +641139,7 @@ function probeXcodeVersionCached() {
   return cachedXcodeProbe;
 }
 function locateManagedWda(options = {}) {
-  const { ctx = {}, fs: fs28 = import_node_fs14.default, platform = process.platform, probeXcode = probeXcodeVersionCached, resolveDriverVersion = resolveHeavyDepVersion, now = Date.now } = options;
+  const { ctx = {}, fs: fs29 = import_node_fs14.default, platform = process.platform, probeXcode = probeXcodeVersionCached, resolveDriverVersion = resolveHeavyDepVersion, now = Date.now } = options;
   try {
     if (platform !== "darwin")
       return null;
@@ -639994,10 +641156,10 @@ function locateManagedWda(options = {}) {
     const wdaRoot = import_node_path12.default.normalize(options.wdaRootDir ?? getWdaRoot(ctx));
     const key = computeWdaKey(xcode, driverVersion);
     const keyDir = import_node_path12.default.join(wdaRoot, key);
-    const marker = readProductsMarker(keyDir, fs28);
+    const marker = readProductsMarker(keyDir, fs29);
     if (!marker || marker.key !== key)
       return null;
-    touchLastUsed(keyDir, fs28, now);
+    touchLastUsed(keyDir, fs29, now);
     return { key, derivedDataPath: import_node_path12.default.join(keyDir, "DerivedData") };
   } catch {
     return null;
@@ -640604,9 +641766,9 @@ function hostAbi(arch = process.arch) {
 }
 var JRE_FEATURE_VERSION = "17";
 function jreDownloadUrl(platform = process.platform, arch = process.arch) {
-  const os13 = platform === "win32" ? "windows" : platform === "darwin" ? "mac" : "linux";
+  const os14 = platform === "win32" ? "windows" : platform === "darwin" ? "mac" : "linux";
   const adoptiumArch = arch === "arm64" ? "aarch64" : "x64";
-  return `https://api.adoptium.net/v3/binary/latest/${JRE_FEATURE_VERSION}/ga/${os13}/${adoptiumArch}/jre/hotspot/normal/eclipse`;
+  return `https://api.adoptium.net/v3/binary/latest/${JRE_FEATURE_VERSION}/ga/${os14}/${adoptiumArch}/jre/hotspot/normal/eclipse`;
 }
 function jreArchiveFilename(platform = process.platform) {
   return platform === "win32" ? "jre.zip" : "jre.tar.gz";
@@ -641374,8 +642536,8 @@ async function hostHasKvm() {
   if (process.platform !== "linux")
     return false;
   try {
-    const fs28 = await import("node:fs");
-    fs28.accessSync("/dev/kvm", fs28.constants.R_OK | fs28.constants.W_OK);
+    const fs29 = await import("node:fs");
+    fs29.accessSync("/dev/kvm", fs29.constants.R_OK | fs29.constants.W_OK);
     return true;
   } catch {
     return false;
@@ -643304,11 +644466,14 @@ function safeContextId(contextId) {
   const hash = import_node_crypto6.default.createHash("sha1").update(raw).digest("hex").slice(0, 8);
   return `${base}-${hash}`;
 }
+function recordingProcessToken() {
+  return String(process.pid);
+}
 function browserCaptureTitle(contextId) {
-  return `RECORD_ME_${safeContextId(contextId)}`;
+  return `RECORD_ME_${recordingProcessToken()}_${safeContextId(contextId)}`;
 }
 function browserDownloadDir(contextId) {
-  return import_node_path15.default.join(import_node_os7.default.tmpdir(), "doc-detective", "recordings", safeContextId(contextId));
+  return import_node_path15.default.join(import_node_os7.default.tmpdir(), "doc-detective", "recordings", `${safeContextId(contextId)}-${recordingProcessToken()}`);
 }
 function engineFields(record) {
   const engine = record && typeof record === "object" ? record.engine : void 0;
@@ -644035,11 +645200,11 @@ function hasUnresolvedMetaReference(expression, context) {
   }
   return false;
 }
-function getMetaValue(path27, context) {
+function getMetaValue(path28, context) {
   if (!context) {
     return void 0;
   }
-  const [basePath, jsonPointer] = path27.split("#");
+  const [basePath, jsonPointer] = path28.split("#");
   const resolvedPath = resolvePathTemplateVariables(basePath, context);
   let value = getNestedProperty(context, resolvedPath);
   if (jsonPointer && value) {
@@ -644056,9 +645221,9 @@ function getMetaValue(path27, context) {
   }
   return value;
 }
-function resolvePathTemplateVariables(path27, context) {
+function resolvePathTemplateVariables(path28, context) {
   const templateRegex = /\{\{(\w+)\}\}/g;
-  return path27.replace(templateRegex, (match, varName) => {
+  return path28.replace(templateRegex, (match, varName) => {
     if (context && context.id && varName === "id") {
       return context.id;
     }
@@ -644095,10 +645260,10 @@ async function resolveEmbeddedExpressions(str, context) {
   parts.push(str.slice(lastIdx));
   return parts.join("");
 }
-function getNestedProperty(obj, path27) {
-  if (!obj || !path27)
+function getNestedProperty(obj, path28) {
+  if (!obj || !path28)
     return void 0;
-  const parts = path27.split(".");
+  const parts = path28.split(".");
   let current = obj;
   for (const part of parts) {
     if (current === null || current === void 0)
@@ -646327,7 +647492,7 @@ function aspectRatiosMatch(a, b) {
   const rb = b.width / b.height;
   return Math.abs(ra - rb) / Math.max(ra, rb) <= 0.05;
 }
-async function saveScreenshot({ config, step, driver, appSession }) {
+async function saveScreenshot({ config, step, driver, appSession, internal }) {
   let result = {
     status: "PASS",
     description: "Saved screenshot.",
@@ -646483,7 +647648,7 @@ async function saveScreenshot({ config, step, driver, appSession }) {
     }
   } else {
     dir = import_node_path17.default.dirname(step.screenshot.path);
-    if (!import_node_fs20.default.existsSync(dir)) {
+    if (!internal?.compareOnly && !import_node_fs20.default.existsSync(dir)) {
       import_node_fs20.default.mkdirSync(dir, { recursive: true });
     }
     if (import_node_fs20.default.existsSync(filePath)) {
@@ -646695,6 +647860,10 @@ async function saveScreenshot({ config, step, driver, appSession }) {
     if (!writeFinalPng(filePath))
       return result;
   }
+  if (internal?.compareOnly) {
+    if (!writeFinalPng(internal.capturePath))
+      return result;
+  }
   if (existFilePath) {
     if (step.screenshot.overwrite == "true" && !isUrlPath) {
       if (!writeFinalPng(existFilePath))
@@ -646765,7 +647934,7 @@ async function saveScreenshot({ config, step, driver, appSession }) {
         severity: "warning"
       });
       if (fractionalDiff > step.screenshot.maxVariation) {
-        if (step.screenshot.overwrite == "aboveVariation" && !isUrlPath) {
+        if (step.screenshot.overwrite == "aboveVariation" && !isUrlPath && !internal?.compareOnly) {
           if (!writeFinalPng(existFilePath))
             return result;
         }
@@ -646773,6 +647942,8 @@ async function saveScreenshot({ config, step, driver, appSession }) {
         if (isUrlPath) {
           result.outputs.screenshotPath = filePath;
           result.outputs.referenceUrl = redactedUrl;
+        } else if (internal?.compareOnly) {
+          result.outputs.screenshotPath = internal.capturePath;
         } else {
           result.outputs.changed = true;
           result.outputs.screenshotPath = existFilePath;
@@ -646796,25 +647967,248 @@ async function saveScreenshot({ config, step, driver, appSession }) {
     }
   }
   if (!result.outputs.screenshotPath) {
-    if (!writeFinalPng(filePath))
-      return result;
-    result.outputs.screenshotPath = filePath;
-    result.outputs.changed = true;
-    if (step.screenshot.sourceIntegration) {
-      result.outputs.sourceIntegration = step.screenshot.sourceIntegration;
+    if (internal?.compareOnly) {
+      result.outputs.screenshotPath = internal.capturePath;
+      result.outputs.baselineMissing = true;
+    } else {
+      if (!writeFinalPng(filePath))
+        return result;
+      result.outputs.screenshotPath = filePath;
+      result.outputs.changed = true;
+      if (step.screenshot.sourceIntegration) {
+        result.outputs.sourceIntegration = step.screenshot.sourceIntegration;
+      }
     }
   }
   return await evaluateApplicable();
 }
 
+// dist/core/tests/recordingCheckpoints.js
+var import_node_fs21 = __toESM(require("node:fs"), 1);
+var import_node_os8 = __toESM(require("node:os"), 1);
+var import_node_path18 = __toESM(require("node:path"), 1);
+var import_node_crypto7 = require("node:crypto");
+init_utils();
+init_browserStepKeys();
+function capPathSegment(segment, max = 32) {
+  if (segment.length <= max)
+    return segment;
+  const hash = (0, import_node_crypto7.createHash)("sha1").update(segment).digest("hex").slice(0, 8);
+  const tail = segment.slice(segment.length - (max - hash.length - 1));
+  return `${hash}-${tail}`;
+}
+function stepArtifactFileName({ step, stepIndex, stepCount, testId }) {
+  const action = BROWSER_STEP_KEYS.find((key) => typeof step[key] !== "undefined") || "step";
+  const sanitizedTestId = sanitizeFilesystemName(String(testId ?? ""), "test");
+  const stepIdString = sanitizeFilesystemName(String(step.stepId ?? ""), "step");
+  const stepRef = capPathSegment(stepIdString.startsWith(`${sanitizedTestId}~`) ? stepIdString.slice(sanitizedTestId.length + 1) : stepIdString);
+  const pad = Math.max(2, String(stepCount).length);
+  return `${String(stepIndex + 1).padStart(pad, "0")}-${action}-${stepRef}.png`;
+}
+function recordingCheckpointsEnabled(record) {
+  if (record?.overwrite === "aboveVariation")
+    return true;
+  return record?.checkpoints !== void 0 && record?.checkpoints !== false;
+}
+function resolveCheckpointsConfig({ record, targetPath, handleId }) {
+  let raw = record?.checkpoints;
+  if (record?.overwrite === "aboveVariation" && (raw === void 0 || raw === false)) {
+    raw = true;
+  }
+  if (raw === void 0 || raw === false)
+    return null;
+  const opts = raw === true ? {} : raw;
+  const baselineDir = opts.directory ? import_node_path18.default.resolve(import_node_path18.default.dirname(targetPath), opts.directory) : `${targetPath}.checkpoints`;
+  return {
+    maxVariation: opts.maxVariation ?? 0.05,
+    baselineDir,
+    stagingDir: import_node_path18.default.join(import_node_os8.default.tmpdir(), "doc-detective", "checkpoints", String(handleId)),
+    entries: []
+  };
+}
+function computeSpanVerdict({ entries, baselineDir, maxVariation, targetExists }) {
+  const reasons = [];
+  const drifted = entries.filter((e) => typeof e.variation === "number" && e.variation > maxVariation);
+  if (drifted.length > 0) {
+    reasons.push(`${drifted.length} checkpoint(s) drifted beyond maxVariation (${maxVariation}): pixel variation up to ${Math.max(...drifted.map((e) => e.variation)).toFixed(3)}`);
+  }
+  const missing = entries.filter((e) => e.baselineMissing);
+  if (missing.length > 0) {
+    reasons.push(`${missing.length} checkpoint(s) have no baseline (step added or renamed)`);
+  }
+  const errored = entries.filter((e) => e.error);
+  if (errored.length > 0) {
+    reasons.push(`${errored.length} checkpoint(s) couldn't be compared (capture or comparison error)`);
+  }
+  let orphans = [];
+  try {
+    const expected = new Set(entries.map((e) => e.fileName));
+    orphans = import_node_fs21.default.readdirSync(baselineDir).filter((name) => name.endsWith(".png") && !expected.has(name));
+  } catch {
+  }
+  if (orphans.length > 0) {
+    reasons.push(`${orphans.length} baseline(s) have no matching step (step removed or renamed)`);
+  }
+  if (!targetExists) {
+    reasons.push("the recording file is missing");
+  }
+  return { changed: reasons.length > 0, reasons, orphans };
+}
+function promoteRecordingSpan({ config, stagingTarget, targetPath, entries, orphans, baselineDir }) {
+  const backupPath = `${targetPath}.promote-backup`;
+  const targetExisted = import_node_fs21.default.existsSync(targetPath);
+  try {
+    import_node_fs21.default.rmSync(backupPath, { force: true });
+  } catch {
+  }
+  try {
+    if (targetExisted)
+      import_node_fs21.default.renameSync(targetPath, backupPath);
+    import_node_fs21.default.renameSync(stagingTarget, targetPath);
+  } catch (error) {
+    log(config, "warning", `Couldn't promote the refreshed recording over ${targetPath}; keeping the existing recording. ${error?.message ?? error}`);
+    try {
+      if (targetExisted && !import_node_fs21.default.existsSync(targetPath)) {
+        import_node_fs21.default.renameSync(backupPath, targetPath);
+      }
+      import_node_fs21.default.rmSync(stagingTarget, { force: true });
+    } catch {
+    }
+    return { videoPromoted: false, seededBaselines: 0, baselineFailures: 0 };
+  }
+  try {
+    import_node_fs21.default.rmSync(backupPath, { force: true });
+  } catch {
+  }
+  try {
+    import_node_fs21.default.mkdirSync(baselineDir, { recursive: true });
+  } catch {
+  }
+  let seededBaselines = 0;
+  let baselineFailures = 0;
+  for (const entry of entries) {
+    if (entry.error)
+      continue;
+    try {
+      const tempPath = `${entry.baselinePath}.tmp`;
+      import_node_fs21.default.copyFileSync(entry.stagingPath, tempPath);
+      import_node_fs21.default.renameSync(tempPath, entry.baselinePath);
+      if (entry.baselineMissing)
+        seededBaselines++;
+    } catch (error) {
+      baselineFailures++;
+      log(config, "warning", `Couldn't update checkpoint baseline ${entry.baselinePath}: ${error?.message ?? error}`);
+    }
+  }
+  for (const orphan of orphans) {
+    try {
+      import_node_fs21.default.unlinkSync(import_node_path18.default.join(baselineDir, orphan));
+    } catch (error) {
+      baselineFailures++;
+      log(config, "warning", `Couldn't remove orphaned checkpoint baseline ${orphan}: ${error?.message ?? error}`);
+    }
+  }
+  return { videoPromoted: true, seededBaselines, baselineFailures };
+}
+function buildCheckpointOutputs(entries) {
+  let maxCheckpointVariation = 0;
+  for (const entry of entries) {
+    if (typeof entry.variation === "number") {
+      maxCheckpointVariation = Math.max(maxCheckpointVariation, entry.variation);
+    }
+  }
+  return {
+    checkpoints: entries.map((entry) => ({
+      fileName: entry.fileName,
+      ...typeof entry.variation === "number" ? { variation: entry.variation } : {},
+      ...entry.baselineMissing ? { baselineMissing: true } : {},
+      ...entry.error ? { error: entry.error } : {}
+    })),
+    maxCheckpointVariation,
+    checkpointErrors: entries.filter((entry) => entry.error).length
+  };
+}
+async function captureRecordingCheckpoints({ config, driver, recordingHost, step, stepStatus, stepIndex, stepCount, testId, appSession }) {
+  const recordings = recordingHost?.state?.recordings;
+  if (!Array.isArray(recordings) || recordings.length === 0)
+    return;
+  const qualifying = recordings.filter((h) => h?.checkpoints && !h.synthetic);
+  if (qualifying.length === 0)
+    return;
+  if (!driver) {
+    log(config, "debug", "Recording checkpoints skipped: no browser driver in this context.");
+    return;
+  }
+  if (stepStatus === "FAIL") {
+    for (const handle of qualifying) {
+      handle.checkpoints.spanDirty = true;
+    }
+    log(config, "debug", `Recording checkpoint skipped for failed step ${step.stepId}; span marked dirty.`);
+    return;
+  }
+  for (const handle of qualifying) {
+    const checkpoints = handle.checkpoints;
+    const fileName = stepArtifactFileName({
+      step,
+      stepIndex,
+      stepCount,
+      testId
+    });
+    const entry = {
+      fileName,
+      stagingPath: import_node_path18.default.join(checkpoints.stagingDir, fileName),
+      baselinePath: import_node_path18.default.join(checkpoints.baselineDir, fileName)
+    };
+    try {
+      import_node_fs21.default.mkdirSync(checkpoints.stagingDir, { recursive: true });
+      const screenshotStep = {
+        stepId: `${step.stepId}_checkpoint`,
+        description: "Recording checkpoint screenshot",
+        screenshot: {
+          path: entry.baselinePath,
+          maxVariation: checkpoints.maxVariation,
+          overwrite: "aboveVariation"
+        }
+      };
+      const captureResult = await saveScreenshot({
+        config,
+        step: screenshotStep,
+        driver,
+        appSession,
+        internal: { compareOnly: true, capturePath: entry.stagingPath }
+      });
+      if (captureResult.status !== "PASS" && captureResult.status !== "WARNING") {
+        entry.error = captureResult.description;
+        log(config, "warning", `Recording checkpoint failed after step ${step.stepId}: ${captureResult.description}`);
+      } else {
+        if (typeof captureResult.outputs?.variation === "number") {
+          entry.variation = captureResult.outputs.variation;
+        }
+        if (captureResult.outputs?.baselineMissing) {
+          entry.baselineMissing = true;
+        }
+      }
+    } catch (error) {
+      entry.error = String(error?.message ?? error);
+      log(config, "warning", `Recording checkpoint failed after step ${step.stepId}: ${entry.error}`);
+    }
+    const existingIndex = checkpoints.entries.findIndex((e) => e.fileName === fileName);
+    if (existingIndex >= 0) {
+      checkpoints.entries[existingIndex] = entry;
+    } else {
+      checkpoints.entries.push(entry);
+    }
+  }
+}
+
 // dist/core/tests/startRecording.js
 init_validate();
 init_utils();
 var import_node_child_process12 = require("node:child_process");
-var import_node_crypto7 = require("node:crypto");
-var import_node_path18 = __toESM(require("node:path"), 1);
-var import_node_fs21 = __toESM(require("node:fs"), 1);
-var import_node_os8 = __toESM(require("node:os"), 1);
+var import_node_crypto8 = require("node:crypto");
+var import_node_path19 = __toESM(require("node:path"), 1);
+var import_node_fs22 = __toESM(require("node:fs"), 1);
+var import_node_os9 = __toESM(require("node:os"), 1);
 async function startRecording({ config, context, step, driver, recordingHost, appSession, deps = {} }) {
   let result = {
     status: "PASS",
@@ -646882,7 +648276,7 @@ async function startRecording({ config, context, step, driver, recordingHost, ap
   if (typeof step.record.path === "undefined") {
     step.record.path = `${step.stepId}.mp4`;
     if (step.record.directory) {
-      step.record.path = import_node_path18.default.resolve(step.record.directory, step.record.path);
+      step.record.path = import_node_path19.default.resolve(step.record.directory, step.record.path);
     }
   }
   step.record = {
@@ -646890,18 +648284,26 @@ async function startRecording({ config, context, step, driver, recordingHost, ap
     overwrite: step.record.overwrite || "false"
   };
   let filePath = step.record.path;
-  const baseName = import_node_path18.default.basename(filePath, import_node_path18.default.extname(filePath));
-  const dir = import_node_path18.default.dirname(step.record.path);
-  if (!import_node_fs21.default.existsSync(dir)) {
-    import_node_fs21.default.mkdirSync(dir, { recursive: true });
+  const baseName = import_node_path19.default.basename(filePath, import_node_path19.default.extname(filePath));
+  const dir = import_node_path19.default.dirname(step.record.path);
+  if (!import_node_fs22.default.existsSync(dir)) {
+    import_node_fs22.default.mkdirSync(dir, { recursive: true });
   }
-  if (import_node_fs21.default.existsSync(filePath) && step.record.overwrite == "false") {
+  const phantomRecordingResult = (skipDescription, skipReason = "headless") => {
     result.status = "SKIPPED";
-    result.description = `File already exists: ${filePath}`;
+    if (recordingCheckpointsEnabled(step.record)) {
+      result.description = `${skipDescription} Running checkpoint comparisons only, to detect whether the recording is stale.`;
+      result.recording = { type: "phantom", targetPath: filePath, skipReason };
+    } else {
+      result.description = skipDescription;
+    }
     return result;
+  };
+  if (import_node_fs22.default.existsSync(filePath) && step.record.overwrite == "false") {
+    return phantomRecordingResult(`File already exists: ${filePath}`, "targetExists");
   }
   const normalizeActiveTarget = (p) => {
-    const resolved = import_node_path18.default.resolve(p);
+    const resolved = import_node_path19.default.resolve(p);
     return process.platform === "win32" || process.platform === "darwin" ? resolved.toLowerCase() : resolved;
   };
   const normalizedTarget = normalizeActiveTarget(filePath);
@@ -646978,9 +648380,7 @@ async function startRecording({ config, context, step, driver, recordingHost, ap
   }
   if (plan.name === "browser") {
     if (context.browser?.headless) {
-      result.status = "SKIPPED";
-      result.description = `Recording isn't supported in headless mode with the browser engine. Use the ffmpeg engine to record headless.`;
-      return result;
+      return phantomRecordingResult(`Recording isn't supported in headless mode with the browser engine. Use the ffmpeg engine to record headless.`);
     }
     if (context.browser?.name !== "chrome") {
       result.status = "SKIPPED";
@@ -646989,13 +648389,13 @@ async function startRecording({ config, context, step, driver, recordingHost, ap
     }
     const captureTitle = browserCaptureTitle(context.contextId);
     const downloadDir = browserDownloadDir(context.contextId);
-    if (!import_node_fs21.default.existsSync(downloadDir)) {
-      import_node_fs21.default.mkdirSync(downloadDir, { recursive: true });
+    if (!import_node_fs22.default.existsSync(downloadDir)) {
+      import_node_fs22.default.mkdirSync(downloadDir, { recursive: true });
     }
-    const downloadPath = import_node_path18.default.join(downloadDir, `${baseName}.webm`);
-    if (import_node_fs21.default.existsSync(downloadPath)) {
+    const downloadPath = import_node_path19.default.join(downloadDir, `${baseName}.webm`);
+    if (import_node_fs22.default.existsSync(downloadPath)) {
       try {
-        import_node_fs21.default.unlinkSync(downloadPath);
+        import_node_fs22.default.unlinkSync(downloadPath);
       } catch {
       }
     }
@@ -647107,9 +648507,7 @@ async function startRecording({ config, context, step, driver, recordingHost, ap
     return result;
   }
   if (!appRef && context.browser?.headless && !context.__display) {
-    result.status = "SKIPPED";
-    result.description = `Recording isn't supported in headless mode without a virtual display (Xvfb).`;
-    return result;
+    return phantomRecordingResult(`Recording isn't supported in headless mode without a virtual display (Xvfb).`);
   }
   let crop = null;
   let appCropRect = null;
@@ -647135,10 +648533,10 @@ async function startRecording({ config, context, step, driver, recordingHost, ap
     } catch {
     }
   }
-  const tempDir = import_node_path18.default.join(import_node_os8.default.tmpdir(), "doc-detective", "recordings");
-  if (!import_node_fs21.default.existsSync(tempDir))
-    import_node_fs21.default.mkdirSync(tempDir, { recursive: true });
-  const tempPath = import_node_path18.default.join(tempDir, `${safeContextId(context.contextId)}-${baseName}-${(0, import_node_crypto7.randomUUID)().slice(0, 8)}.mkv`);
+  const tempDir = import_node_path19.default.join(import_node_os9.default.tmpdir(), "doc-detective", "recordings");
+  if (!import_node_fs22.default.existsSync(tempDir))
+    import_node_fs22.default.mkdirSync(tempDir, { recursive: true });
+  const tempPath = import_node_path19.default.join(tempDir, `${safeContextId(context.contextId)}-${baseName}-${(0, import_node_crypto8.randomUUID)().slice(0, 8)}.mkv`);
   let ffmpegPath;
   try {
     ffmpegPath = await (deps.getFfmpegPath ?? getFfmpegPath)({
@@ -647209,10 +648607,10 @@ async function startRecording({ config, context, step, driver, recordingHost, ap
 init_validate();
 init_utils();
 var import_node_child_process13 = require("node:child_process");
-var import_node_crypto8 = require("node:crypto");
-var import_node_path19 = __toESM(require("node:path"), 1);
-var import_node_fs22 = __toESM(require("node:fs"), 1);
-var import_node_os9 = __toESM(require("node:os"), 1);
+var import_node_crypto9 = require("node:crypto");
+var import_node_path20 = __toESM(require("node:path"), 1);
+var import_node_fs23 = __toESM(require("node:fs"), 1);
+var import_node_os10 = __toESM(require("node:os"), 1);
 async function stopRecording({ config, step, driver, deps = {} }) {
   let result = {
     status: "PASS",
@@ -647266,8 +648664,49 @@ async function stopRecording({ config, step, driver, deps = {} }) {
     if (idx !== -1)
       recordings.splice(idx, 1);
   };
+  const discardCheckpointStaging = () => {
+    const dir = recording?.checkpoints?.stagingDir;
+    if (!dir)
+      return;
+    try {
+      import_node_fs23.default.rmSync(dir, { recursive: true, force: true });
+    } catch {
+    }
+  };
+  if (recording.type === "phantom") {
+    dropHandle();
+    const phantomCheckpoints = recording.checkpoints;
+    const entries = phantomCheckpoints?.entries ?? [];
+    discardCheckpointStaging();
+    const skipCause = recording.skipReason === "targetExists" ? `Recording skipped (the target already exists)` : `Recording skipped (headless)`;
+    const refreshRemedy = recording.skipReason === "targetExists" ? `Delete it, or set \`overwrite\` to "true" or "aboveVariation", to refresh it.` : `Recording is skipped in headless mode; re-run headed to refresh it.`;
+    if (phantomCheckpoints?.spanDirty || entries.length === 0) {
+      result.status = "SKIPPED";
+      result.description = `${skipCause}; the span didn't produce a complete checkpoint set, so staleness couldn't be determined.`;
+      return result;
+    }
+    const verdict = computeSpanVerdict({
+      entries,
+      baselineDir: phantomCheckpoints?.baselineDir ?? "",
+      maxVariation: phantomCheckpoints?.maxVariation ?? 0.05,
+      targetExists: import_node_fs23.default.existsSync(recording.targetPath)
+    });
+    result.outputs = {
+      stale: verdict.changed,
+      ...buildCheckpointOutputs(entries)
+    };
+    if (verdict.changed) {
+      result.status = "WARNING";
+      result.description = `The recording at ${recording.targetPath} appears stale \u2014 ${verdict.reasons.join("; ")}. ${refreshRemedy}`;
+    } else {
+      result.status = "SKIPPED";
+      result.description = `${skipCause}; checkpoints match their baselines, so the recording appears current.`;
+    }
+    return result;
+  }
   if (recording.type === "appium-pending") {
     dropHandle();
+    discardCheckpointStaging();
     if (recording.startError) {
       result.status = recording.startSkip ? "SKIPPED" : "FAIL";
       result.description = recording.startError;
@@ -647277,6 +648716,9 @@ async function stopRecording({ config, step, driver, deps = {} }) {
     result.description = "The device recording never started (no app surface opened a device session), so there is nothing to save.";
     return result;
   }
+  const isAboveVariation = recording.overwrite === "aboveVariation";
+  const finalTargetPath = recording.targetPath;
+  const writeTargetPath = isAboveVariation ? import_node_path20.default.join(import_node_path20.default.dirname(finalTargetPath), `.${import_node_path20.default.basename(finalTargetPath, import_node_path20.default.extname(finalTargetPath))}.staging${import_node_path20.default.extname(finalTargetPath)}`) : finalTargetPath;
   try {
     if (recording.type === "MediaRecorder") {
       let returnTab = null;
@@ -647303,6 +648745,7 @@ async function stopRecording({ config, step, driver, deps = {} }) {
         result.description = "Recording was not properly started. The recorder object doesn't exist in the browser context.";
         await closeRecorderTabAndRestoreFocus();
         dropHandle();
+        discardCheckpointStaging();
         return result;
       }
       await driver.execute(() => {
@@ -647314,13 +648757,14 @@ async function stopRecording({ config, step, driver, deps = {} }) {
         result.description = "Recording download timed out.";
         await closeRecorderTabAndRestoreFocus();
         dropHandle();
+        discardCheckpointStaging();
         return result;
       }
       await closeRecorderTabAndRestoreFocus();
       await transcode({
         config,
         sourcePath: recording.downloadPath,
-        targetPath: recording.targetPath,
+        targetPath: writeTargetPath,
         deleteSource: true
       });
       dropHandle();
@@ -647378,7 +648822,7 @@ async function stopRecording({ config, step, driver, deps = {} }) {
       await transcode({
         config,
         sourcePath: recording.tempPath,
-        targetPath: recording.targetPath,
+        targetPath: writeTargetPath,
         deleteSource: true,
         crop
       });
@@ -647389,6 +648833,7 @@ async function stopRecording({ config, step, driver, deps = {} }) {
         result.status = "FAIL";
         result.description = "The device recording returned no data; nothing was saved.";
         dropHandle();
+        discardCheckpointStaging();
         return result;
       }
       let buffer;
@@ -647398,26 +648843,28 @@ async function stopRecording({ config, step, driver, deps = {} }) {
         result.status = "FAIL";
         result.description = `Couldn't buffer the device recording (${Math.round(b64.length / 1024 / 1024)} MB base64) \u2014 device recordings transfer in one payload, so long recordings can exhaust memory. Keep device recordings short (they cap at 30 minutes). ${error?.message ?? error}`;
         dropHandle();
+        discardCheckpointStaging();
         return result;
       }
       if (buffer.length === 0) {
         result.status = "FAIL";
         result.description = "The device recording decoded to an empty payload (no data); nothing was saved.";
         dropHandle();
+        discardCheckpointStaging();
         return result;
       }
-      if (import_node_path19.default.extname(recording.targetPath) === ".mp4") {
-        import_node_fs22.default.writeFileSync(recording.targetPath, buffer);
+      if (import_node_path20.default.extname(writeTargetPath) === ".mp4") {
+        import_node_fs23.default.writeFileSync(writeTargetPath, buffer);
       } else {
-        const tempDir = import_node_path19.default.join(import_node_os9.default.tmpdir(), "doc-detective", "recordings");
-        if (!import_node_fs22.default.existsSync(tempDir))
-          import_node_fs22.default.mkdirSync(tempDir, { recursive: true });
-        const tempPath = import_node_path19.default.join(tempDir, `device-${(0, import_node_crypto8.randomUUID)().slice(0, 8)}.mp4`);
-        import_node_fs22.default.writeFileSync(tempPath, buffer);
+        const tempDir = import_node_path20.default.join(import_node_os10.default.tmpdir(), "doc-detective", "recordings");
+        if (!import_node_fs23.default.existsSync(tempDir))
+          import_node_fs23.default.mkdirSync(tempDir, { recursive: true });
+        const tempPath = import_node_path20.default.join(tempDir, `device-${(0, import_node_crypto9.randomUUID)().slice(0, 8)}.mp4`);
+        import_node_fs23.default.writeFileSync(tempPath, buffer);
         await transcode({
           config,
           sourcePath: tempPath,
-          targetPath: recording.targetPath,
+          targetPath: writeTargetPath,
           deleteSource: true
         });
       }
@@ -647427,15 +648874,100 @@ async function stopRecording({ config, step, driver, deps = {} }) {
     result.status = "FAIL";
     result.description = `Couldn't stop recording. ${error}`;
     dropHandle();
+    discardCheckpointStaging();
+    if (isAboveVariation) {
+      try {
+        import_node_fs23.default.rmSync(writeTargetPath, { force: true });
+      } catch {
+      }
+    }
     return result;
   }
-  result.outputs = {
-    recordingPath: import_node_path19.default.resolve(recording.targetPath),
-    format: import_node_path19.default.extname(recording.targetPath).slice(1)
-  };
+  const checkpoints = recording.checkpoints;
+  let seededBaselines = 0;
+  let promoteFailed = false;
+  let baselineFailures = 0;
+  result.outputs = {};
+  if (isAboveVariation) {
+    const entries = checkpoints?.entries ?? [];
+    const targetExists = import_node_fs23.default.existsSync(finalTargetPath);
+    const discardStagedVideo = () => {
+      try {
+        import_node_fs23.default.rmSync(writeTargetPath, { force: true });
+      } catch {
+      }
+    };
+    const indeterminate = checkpoints?.spanDirty || entries.length === 0;
+    if (indeterminate && targetExists) {
+      discardStagedVideo();
+      result.outputs.changed = false;
+      log(config, "warning", checkpoints?.spanDirty ? `Recording kept unchanged (${finalTargetPath}): a step failed during the span, so drift couldn't be judged.` : `Recording kept unchanged (${finalTargetPath}): no checkpoints were captured this run, so drift couldn't be judged.`);
+    } else if (indeterminate) {
+      const promoted = promoteRecordingSpan({
+        config,
+        stagingTarget: writeTargetPath,
+        targetPath: finalTargetPath,
+        entries,
+        orphans: [],
+        baselineDir: checkpoints?.baselineDir ?? ""
+      });
+      seededBaselines = promoted.seededBaselines;
+      result.outputs.changed = promoted.videoPromoted;
+      promoteFailed = !promoted.videoPromoted;
+      baselineFailures = promoted.baselineFailures;
+      if (promoted.videoPromoted) {
+        result.outputs.changeReasons = ["the recording file is missing"];
+      }
+    } else {
+      const verdict = computeSpanVerdict({
+        entries,
+        baselineDir: checkpoints?.baselineDir ?? "",
+        maxVariation: checkpoints?.maxVariation ?? 0.05,
+        targetExists
+      });
+      if (verdict.changed) {
+        const promoted = promoteRecordingSpan({
+          config,
+          stagingTarget: writeTargetPath,
+          targetPath: finalTargetPath,
+          entries,
+          orphans: verdict.orphans,
+          baselineDir: checkpoints?.baselineDir ?? ""
+        });
+        seededBaselines = promoted.seededBaselines;
+        result.outputs.changed = promoted.videoPromoted;
+        promoteFailed = !promoted.videoPromoted;
+        baselineFailures = promoted.baselineFailures;
+        if (promoted.videoPromoted) {
+          result.outputs.changeReasons = verdict.reasons;
+          log(config, "info", `Recording refreshed (${finalTargetPath}): ${verdict.reasons.join("; ")}`);
+        }
+      } else {
+        discardStagedVideo();
+        result.outputs.changed = false;
+      }
+    }
+  } else if (checkpoints?.entries?.length) {
+    for (const entry of checkpoints.entries) {
+      if (checkpoints.spanDirty)
+        break;
+      if (entry.baselineMissing && !entry.error) {
+        try {
+          import_node_fs23.default.mkdirSync(checkpoints.baselineDir, { recursive: true });
+          import_node_fs23.default.copyFileSync(entry.stagingPath, entry.baselinePath, import_node_fs23.default.constants.COPYFILE_EXCL);
+          seededBaselines++;
+        } catch (error) {
+          entry.error = error?.code === "EEXIST" ? `A baseline appeared at ${entry.baselinePath} after this checkpoint was captured; left it untouched.` : String(error?.message ?? error);
+          log(config, "warning", `Couldn't seed checkpoint baseline ${entry.baselinePath}: ${entry.error}`);
+        }
+      }
+    }
+  }
+  result.outputs.recordingPath = import_node_path20.default.resolve(finalTargetPath);
+  result.outputs.format = import_node_path20.default.extname(finalTargetPath).slice(1);
   const meta = await probeVideoMetadata({
     cacheDir: config?.cacheDir,
-    filePath: recording.targetPath
+    filePath: finalTargetPath
   });
   if (meta?.duration !== void 0)
     result.outputs.duration = meta.duration;
@@ -647446,7 +648978,45 @@ async function stopRecording({ config, step, driver, deps = {} }) {
   if (meta?.fps !== void 0)
     result.outputs.fps = meta.fps;
   if (!meta || Object.keys(meta).length === 0) {
-    log(config, "debug", `Couldn't probe recording metadata for ${recording.targetPath}.`);
+    log(config, "debug", `Couldn't probe recording metadata for ${finalTargetPath}.`);
+  }
+  if (checkpoints?.entries?.length) {
+    Object.assign(result.outputs, buildCheckpointOutputs(checkpoints.entries));
+    result.outputs.seededBaselines = seededBaselines;
+    const ctx = buildConditionContext({ outputs: result.outputs });
+    const { assertions, status } = await evaluateImplicitAssertions([
+      {
+        statement: `$$outputs.maxCheckpointVariation <= ${checkpoints.maxVariation}`,
+        severity: "warning"
+      },
+      {
+        statement: `$$outputs.checkpointErrors == 0`,
+        severity: "warning"
+      }
+    ], ctx);
+    result.assertions = assertions;
+    result.status = status;
+    if (status === "WARNING") {
+      result.description += !isAboveVariation ? ` One or more checkpoints drifted beyond maxVariation (${checkpoints.maxVariation}) or couldn't be compared \u2014 the recorded flow's content may have changed since its baselines were captured.` : result.outputs.changed ? ` One or more checkpoints drifted beyond maxVariation (${checkpoints.maxVariation}) or couldn't be compared \u2014 the recording was refreshed to match the current content.` : ` One or more checkpoints drifted beyond maxVariation (${checkpoints.maxVariation}) or couldn't be compared \u2014 the existing recording was kept.`;
+    }
+    if (baselineFailures > 0) {
+      result.outputs.baselineFailures = baselineFailures;
+    }
+    try {
+      import_node_fs23.default.rmSync(checkpoints.stagingDir, { recursive: true, force: true });
+    } catch {
+    }
+  }
+  if (promoteFailed) {
+    if (!import_node_fs23.default.existsSync(finalTargetPath)) {
+      result.status = "FAIL";
+      result.description = `Couldn't save the recording to ${finalTargetPath}: promoting the captured video failed and no previous recording exists at that path.`;
+      delete result.outputs.recordingPath;
+      delete result.outputs.format;
+    } else {
+      result.status = "WARNING";
+      result.description += ` The captured video couldn't replace ${finalTargetPath}, so the existing (now stale) recording was kept.`;
+    }
   }
   return result;
 }
@@ -647460,7 +649030,7 @@ async function transcode({ config, sourcePath, targetPath, deleteSource, crop })
     const cy = `max(0\\,min(${crop.y}\\,ih-${ch}))`;
     filters.push(`crop=w=${cw}:h=${ch}:x=${cx}:y=${cy}`);
   }
-  if (import_node_path19.default.extname(targetPath) === ".gif") {
+  if (import_node_path20.default.extname(targetPath) === ".gif") {
     filters.push("scale=iw:-1:flags=lanczos");
   }
   if (filters.length > 0) {
@@ -647478,7 +649048,7 @@ async function transcode({ config, sourcePath, targetPath, deleteSource, crop })
       if (code === 0) {
         if (deleteSource && sourcePath !== targetPath) {
           try {
-            import_node_fs22.default.unlinkSync(sourcePath);
+            import_node_fs23.default.unlinkSync(sourcePath);
           } catch {
           }
         }
@@ -647497,7 +649067,7 @@ async function waitForStableFile(filePath, maxSeconds) {
   for (let i = 0; i < deadline; i++) {
     let size = -1;
     try {
-      size = import_node_fs22.default.statSync(filePath).size;
+      size = import_node_fs23.default.statSync(filePath).size;
     } catch {
       size = -1;
     }
@@ -647537,8 +649107,8 @@ async function loadVariables({ step }) {
 // dist/core/tests/saveCookie.js
 init_validate();
 init_utils();
-var import_node_path20 = __toESM(require("node:path"), 1);
-var import_node_fs23 = __toESM(require("node:fs"), 1);
+var import_node_path21 = __toESM(require("node:path"), 1);
+var import_node_fs24 = __toESM(require("node:fs"), 1);
 async function saveCookie({ config, step, driver }) {
   let result = {
     status: "PASS",
@@ -647555,7 +649125,7 @@ async function saveCookie({ config, step, driver }) {
   let cookieName, filePath, directory, overwrite, domain, variable;
   if (typeof step.saveCookie === "string") {
     if (step.saveCookie.endsWith(".txt")) {
-      cookieName = import_node_path20.default.basename(step.saveCookie, ".txt");
+      cookieName = import_node_path21.default.basename(step.saveCookie, ".txt");
       filePath = step.saveCookie;
     } else {
       cookieName = step.saveCookie;
@@ -647604,15 +649174,15 @@ async function saveCookie({ config, step, driver }) {
     }
     if (filePath) {
       const outputDirectory = directory || config.output || process.cwd();
-      const fullPath = import_node_path20.default.resolve(outputDirectory, filePath);
-      if (import_node_fs23.default.existsSync(fullPath) && !(overwrite === true || overwrite === "true")) {
+      const fullPath = import_node_path21.default.resolve(outputDirectory, filePath);
+      if (import_node_fs24.default.existsSync(fullPath) && !(overwrite === true || overwrite === "true")) {
         result.status = "FAIL";
         result.description = `File '${fullPath}' already exists and overwrite is not enabled.`;
         return result;
       }
-      const dir = import_node_path20.default.dirname(fullPath);
-      if (!import_node_fs23.default.existsSync(dir)) {
-        import_node_fs23.default.mkdirSync(dir, { recursive: true });
+      const dir = import_node_path21.default.dirname(fullPath);
+      if (!import_node_fs24.default.existsSync(dir)) {
+        import_node_fs24.default.mkdirSync(dir, { recursive: true });
       }
       if (targetCookie) {
         const netscapeCookie = formatCookieForNetscape(targetCookie);
@@ -647620,11 +649190,11 @@ async function saveCookie({ config, step, driver }) {
 # This is a cookie file saved by Doc Detective
 ${netscapeCookie}
 `;
-        import_node_fs23.default.writeFileSync(fullPath, content, "utf8");
+        import_node_fs24.default.writeFileSync(fullPath, content, "utf8");
         result.description = `Saved cookie '${cookieName}' to '${fullPath}'.`;
         log(config, "debug", `Saved cookie '${cookieName}' to file: ${fullPath}`);
       } else {
-        import_node_fs23.default.writeFileSync(fullPath, "# No cookie data\n", "utf8");
+        import_node_fs24.default.writeFileSync(fullPath, "# No cookie data\n", "utf8");
         result.description = `Created empty cookie file at '${fullPath}'.`;
         log(config, "debug", `Created empty cookie file: ${fullPath}`);
       }
@@ -647651,8 +649221,8 @@ function formatCookieForNetscape(cookie) {
 // dist/core/tests/loadCookie.js
 init_validate();
 init_utils();
-var import_node_path21 = __toESM(require("node:path"), 1);
-var import_node_fs24 = __toESM(require("node:fs"), 1);
+var import_node_path22 = __toESM(require("node:path"), 1);
+var import_node_fs25 = __toESM(require("node:fs"), 1);
 async function loadCookie({ config, step, driver }) {
   let result = {
     status: "PASS",
@@ -647669,7 +649239,7 @@ async function loadCookie({ config, step, driver }) {
   let cookieName, filePath, directory, domain, variable;
   if (typeof step.loadCookie === "string") {
     if (step.loadCookie.endsWith(".txt")) {
-      cookieName = import_node_path21.default.basename(step.loadCookie, ".txt");
+      cookieName = import_node_path22.default.basename(step.loadCookie, ".txt");
       filePath = step.loadCookie;
     } else {
       cookieName = step.loadCookie;
@@ -647682,9 +649252,9 @@ async function loadCookie({ config, step, driver }) {
     domain = step.loadCookie.domain;
     variable = step.loadCookie.variable;
     if (filePath && !cookieName) {
-      const ext = import_node_path21.default.extname(filePath).toLowerCase();
+      const ext = import_node_path22.default.extname(filePath).toLowerCase();
       if (ext === ".txt") {
-        cookieName = import_node_path21.default.basename(filePath, ext);
+        cookieName = import_node_path22.default.basename(filePath, ext);
       }
     }
   }
@@ -647707,14 +649277,14 @@ async function loadCookie({ config, step, driver }) {
       }
     } else if (filePath) {
       const inputDirectory = directory || config.output || process.cwd();
-      const fullPath = import_node_path21.default.resolve(inputDirectory, filePath);
-      if (!import_node_fs24.default.existsSync(fullPath)) {
+      const fullPath = import_node_path22.default.resolve(inputDirectory, filePath);
+      if (!import_node_fs25.default.existsSync(fullPath)) {
         result.status = "FAIL";
         result.description = `Cookie file '${fullPath}' not found`;
         return result;
       }
       try {
-        const fileContent = import_node_fs24.default.readFileSync(fullPath, "utf8");
+        const fileContent = import_node_fs25.default.readFileSync(fullPath, "utf8");
         const cookies = parseNetscapeCookieFile(fileContent);
         if (cookies.length === 0) {
           result.status = "FAIL";
@@ -647880,8 +649450,8 @@ function isDomainCompatible(currentDomain, cookieDomain) {
 // dist/core/tests/httpRequest.js
 init_validate();
 var import_axios5 = __toESM(require("axios"), 1);
-var import_node_fs25 = __toESM(require("node:fs"), 1);
-var import_node_path22 = __toESM(require("node:path"), 1);
+var import_node_fs26 = __toESM(require("node:fs"), 1);
+var import_node_path23 = __toESM(require("node:path"), 1);
 var import_ajv2 = __toESM(require("ajv"), 1);
 init_openapi();
 init_utils();
@@ -647911,9 +649481,9 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
       delete step.httpRequest.openApi.definition;
     } else if (openApiDefinitions.length > 0) {
       findOperation: for (const openApiConfig of openApiDefinitions) {
-        for (const path27 in openApiConfig.definition.paths) {
-          for (const method in openApiConfig.definition.paths[path27]) {
-            if (openApiConfig.definition.paths[path27][method].operationId === step.httpRequest.openApi.operationId) {
+        for (const path28 in openApiConfig.definition.paths) {
+          for (const method in openApiConfig.definition.paths[path28]) {
+            if (openApiConfig.definition.paths[path28][method].operationId === step.httpRequest.openApi.operationId) {
               openApiDefinition = openApiConfig.definition;
               step.httpRequest.openApi = {
                 ...openApiConfig,
@@ -648227,20 +649797,20 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
     }
   }
   if (step.httpRequest.path) {
-    const dir = import_node_path22.default.dirname(step.httpRequest.path);
-    if (!import_node_fs25.default.existsSync(dir)) {
-      import_node_fs25.default.mkdirSync(dir, { recursive: true });
+    const dir = import_node_path23.default.dirname(step.httpRequest.path);
+    if (!import_node_fs26.default.existsSync(dir)) {
+      import_node_fs26.default.mkdirSync(dir, { recursive: true });
     }
     let filePath = step.httpRequest.path;
     log(config, "debug", `Saving output to file: ${filePath}`);
-    if (!import_node_fs25.default.existsSync(filePath)) {
-      await import_node_fs25.default.promises.writeFile(filePath, JSON.stringify(response.data, null, 2));
+    if (!import_node_fs26.default.existsSync(filePath)) {
+      await import_node_fs26.default.promises.writeFile(filePath, JSON.stringify(response.data, null, 2));
       descriptions.push(`Saved output to file.`);
     } else {
       if (step.httpRequest.overwrite == "false") {
         descriptions.push(`Didn't save output. File already exists.`);
       }
-      const existingFile = import_node_fs25.default.readFileSync(filePath, "utf8");
+      const existingFile = import_node_fs26.default.readFileSync(filePath, "utf8");
       const fractionalDiff = calculateFractionalDifference(existingFile, JSON.stringify(response.data, null, 2));
       log(config, "debug", `Fractional difference: ${fractionalDiff}`);
       result.outputs.variation = fractionalDiff;
@@ -648250,13 +649820,13 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
       });
       if (fractionalDiff > step.httpRequest.maxVariation) {
         if (step.httpRequest.overwrite == "aboveVariation") {
-          await import_node_fs25.default.promises.writeFile(filePath, JSON.stringify(response.data, null, 2));
+          await import_node_fs26.default.promises.writeFile(filePath, JSON.stringify(response.data, null, 2));
           descriptions.push(`Saved response to file.`);
         }
         descriptions.push(`The difference between the existing saved response and the new response (${fractionalDiff.toFixed(2)}) is greater than the max accepted variation (${step.httpRequest.maxVariation}).`);
       } else {
         if (step.httpRequest.overwrite == "true") {
-          import_node_fs25.default.writeFileSync(filePath, JSON.stringify(response.data, null, 2));
+          import_node_fs26.default.writeFileSync(filePath, JSON.stringify(response.data, null, 2));
           descriptions.push(`Saved response to file.`);
         }
       }
@@ -648269,8 +649839,8 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
   result.description = descriptions.join(" ").trim();
   return result;
 }
-function fieldExistsAtPath(obj, path27) {
-  const segments = path27.match(/[^.[\]]+/g);
+function fieldExistsAtPath(obj, path28) {
+  const segments = path28.match(/[^.[\]]+/g);
   if (!segments) {
     return false;
   }
@@ -648460,9 +650030,9 @@ async function clickElement({ config, step, driver, appSession }) {
 // dist/core/tests/runCode.js
 init_validate();
 init_utils();
-var import_node_fs26 = __toESM(require("node:fs"), 1);
-var import_node_path23 = __toESM(require("node:path"), 1);
-var import_node_os10 = __toESM(require("node:os"), 1);
+var import_node_fs27 = __toESM(require("node:fs"), 1);
+var import_node_path24 = __toESM(require("node:path"), 1);
+var import_node_os11 = __toESM(require("node:os"), 1);
 function createTempScript(code, language) {
   let extension;
   switch (language) {
@@ -648485,10 +650055,10 @@ function createTempScript(code, language) {
     default:
       extension = "";
   }
-  const tmpDir = import_node_os10.default.tmpdir();
-  const tmpFile = import_node_path23.default.join(tmpDir, `doc-detective-${Date.now()}${extension}`);
+  const tmpDir = import_node_os11.default.tmpdir();
+  const tmpFile = import_node_path24.default.join(tmpDir, `doc-detective-${Date.now()}${extension}`);
   try {
-    import_node_fs26.default.writeFileSync(tmpFile, code);
+    import_node_fs27.default.writeFileSync(tmpFile, code);
   } catch (error) {
     throw new Error(`Failed to create temporary script: ${error.message}`);
   }
@@ -648547,9 +650117,9 @@ async function runCode({ config, step, driver, processRegistry }) {
     }
     let command = step.runCode.command;
     const wantsBash = command === "bash" || step.runCode.language?.toLowerCase() === "bash";
-    const interpreterShell = wantsBash ? "bash" : import_node_os10.default.platform() === "win32" ? "cmd" : "bash";
+    const interpreterShell = wantsBash ? "bash" : import_node_os11.default.platform() === "win32" ? "cmd" : "bash";
     let commandPreverified = false;
-    if (import_node_os10.default.platform() === "win32" && command === "bash") {
+    if (import_node_os11.default.platform() === "win32" && command === "bash") {
       try {
         command = await resolveShellExecutable("bash", {
           cacheDir: config?.cacheDir
@@ -648561,7 +650131,7 @@ async function runCode({ config, step, driver, processRegistry }) {
         return result;
       }
     }
-    if (import_node_os10.default.platform() === "win32" && interpreterShell === "bash") {
+    if (import_node_os11.default.platform() === "win32" && interpreterShell === "bash") {
       command = command.replace(/\\/g, "/");
       if (/\s/.test(command) && !command.startsWith('"')) {
         command = `"${command}"`;
@@ -648576,7 +650146,7 @@ async function runCode({ config, step, driver, processRegistry }) {
       }
     }
     let scriptArg = scriptPath;
-    if (import_node_os10.default.platform() === "win32")
+    if (import_node_os11.default.platform() === "win32")
       scriptArg = scriptArg.replace(/\\/g, "/");
     if (/\s/.test(scriptArg))
       scriptArg = `"${scriptArg}"`;
@@ -648593,7 +650163,7 @@ async function runCode({ config, step, driver, processRegistry }) {
     if (typeof step.runCode.stdio !== "undefined")
       runShellOptions.stdio = step.runCode.stdio;
     if (typeof step.runCode.path !== "undefined") {
-      runShellOptions.path = step.runCode.directory ? import_node_path23.default.join(step.runCode.directory, step.runCode.path) : step.runCode.path;
+      runShellOptions.path = step.runCode.directory ? import_node_path24.default.join(step.runCode.directory, step.runCode.path) : step.runCode.path;
     }
     if (step.runCode.background) {
       runShellOptions.background = step.runCode.background;
@@ -648622,7 +650192,7 @@ async function runCode({ config, step, driver, processRegistry }) {
   } finally {
     if (!deferTempCleanup) {
       try {
-        import_node_fs26.default.unlinkSync(scriptPath);
+        import_node_fs27.default.unlinkSync(scriptPath);
         log(config, "debug", `Removed temporary script: ${scriptPath}`);
       } catch (error) {
         log(config, "warning", `Failed to remove temporary script: ${scriptPath}`);
@@ -648636,7 +650206,7 @@ async function runCode({ config, step, driver, processRegistry }) {
 init_validate();
 init_utils();
 var import_tree_kill2 = __toESM(require("tree-kill"), 1);
-var import_node_fs27 = __toESM(require("node:fs"), 1);
+var import_node_fs28 = __toESM(require("node:fs"), 1);
 async function closeSurface({ config, step, driver, processRegistry, appSession }) {
   const result = {
     status: "PASS",
@@ -648785,7 +650355,7 @@ async function closeSurface({ config, step, driver, processRegistry, appSession
     }
     if (entry.tempPath) {
       try {
-        import_node_fs27.default.unlinkSync(entry.tempPath);
+        import_node_fs28.default.unlinkSync(entry.tempPath);
       } catch {
       }
     }
@@ -649042,7 +650612,7 @@ async function startSurfaceStep({ config, step, platform, driver, processRegistr
 }
 
 // dist/core/tests/mobileBrowser.js
-var import_node_path24 = __toESM(require("node:path"), 1);
+var import_node_path25 = __toESM(require("node:path"), 1);
 var SUPPORTED_MOBILE_BROWSER = {
   android: "chrome",
   ios: "safari"
@@ -649121,7 +650691,7 @@ function buildMobileBrowserCapabilities({ platform, udid, cacheDir, timeout, loc
       // --allow-insecure=uiautomator2:chromedriver_autodownload. The
       // download lands in the Doc Detective cache so later runs reuse it.
       "appium:chromedriverAutodownload": true,
-      "appium:chromedriverExecutableDir": import_node_path24.default.join(cacheDir, MOBILE_CHROMEDRIVER_DIR)
+      "appium:chromedriverExecutableDir": import_node_path25.default.join(cacheDir, MOBILE_CHROMEDRIVER_DIR)
     };
   }
   const capabilities = {
@@ -649691,8 +651261,8 @@ function buildAcquireSimulatorDeps(log3) {
 // dist/core/tests/runBrowserScript.js
 init_validate();
 init_utils();
-var import_node_fs28 = __toESM(require("node:fs"), 1);
-var import_node_path25 = __toESM(require("node:path"), 1);
+var import_node_fs29 = __toESM(require("node:fs"), 1);
+var import_node_path26 = __toESM(require("node:path"), 1);
 async function runBrowserScript({ config, step, driver }) {
   const result = {
     status: "PASS",
@@ -649767,16 +651337,16 @@ async function runBrowserScript({ config, step, driver }) {
   }
   if (step.runBrowserScript.path) {
     try {
-      const dir = import_node_path25.default.dirname(step.runBrowserScript.path);
-      if (!import_node_fs28.default.existsSync(dir)) {
-        import_node_fs28.default.mkdirSync(dir, { recursive: true });
+      const dir = import_node_path26.default.dirname(step.runBrowserScript.path);
+      if (!import_node_fs29.default.existsSync(dir)) {
+        import_node_fs29.default.mkdirSync(dir, { recursive: true });
       }
       const filePath = step.runBrowserScript.path;
       log(config, "debug", `Saving script result to file: ${filePath}`);
-      if (!import_node_fs28.default.existsSync(filePath)) {
-        import_node_fs28.default.writeFileSync(filePath, serialized);
+      if (!import_node_fs29.default.existsSync(filePath)) {
+        import_node_fs29.default.writeFileSync(filePath, serialized);
       } else {
-        const existingFile = import_node_fs28.default.readFileSync(filePath, "utf8");
+        const existingFile = import_node_fs29.default.readFileSync(filePath, "utf8");
         const fractionalDiff = calculateFractionalDifference(existingFile, serialized);
         log(config, "debug", `Fractional difference: ${fractionalDiff}`);
         result.outputs.variation = fractionalDiff;
@@ -649786,7 +651356,7 @@ async function runBrowserScript({ config, step, driver }) {
         });
         if (fractionalDiff > step.runBrowserScript.maxVariation) {
           if (step.runBrowserScript.overwrite == "aboveVariation" || step.runBrowserScript.overwrite == "true") {
-            import_node_fs28.default.writeFileSync(filePath, serialized);
+            import_node_fs29.default.writeFileSync(filePath, serialized);
             descriptions.push(`Saved output to file.`);
           } else {
             descriptions.push(`Didn't overwrite the existing file.`);
@@ -649794,7 +651364,7 @@ async function runBrowserScript({ config, step, driver }) {
           descriptions.push(`The difference between the existing output and the new output (${fractionalDiff.toFixed(2)}) is greater than the max accepted variation (${step.runBrowserScript.maxVariation}).`);
         } else {
           if (step.runBrowserScript.overwrite == "true") {
-            import_node_fs28.default.writeFileSync(filePath, serialized);
+            import_node_fs29.default.writeFileSync(filePath, serialized);
             descriptions.push(`Saved output to file.`);
           }
         }
@@ -649962,9 +651532,9 @@ async function dragAndDropElement({ config, step, driver }) {
 }
 
 // dist/core/tests.js
-var import_node_path26 = __toESM(require("node:path"), 1);
+var import_node_path27 = __toESM(require("node:path"), 1);
 var import_node_child_process15 = require("node:child_process");
-var import_node_crypto9 = require("node:crypto");
+var import_node_crypto10 = require("node:crypto");
 init_appium();
 init_config();
 
@@ -650116,7 +651686,7 @@ function getIntegrationConfig(config, sourceIntegration) {
 var import_node_http2 = __toESM(require("node:http"), 1);
 var import_node_https3 = __toESM(require("node:https"), 1);
 var import_node_url6 = require("node:url");
-var __dirname5 = import_node_path26.default.dirname((0, import_node_url6.fileURLToPath)(importMetaUrl));
+var __dirname5 = import_node_path27.default.dirname((0, import_node_url6.fileURLToPath)(importMetaUrl));
 var KNOWN_BROWSERS = ["firefox", "chrome", "safari", "webkit"];
 function killTree(pid, timeoutMs = 5e3) {
   return new Promise((resolve) => {
@@ -650261,7 +651831,7 @@ function getDriverCapabilities({ runnerDetails, name, options }) {
             prefs: {
               // Per-context download dir keeps concurrent recordings from
               // colliding on the same .webm filename in a shared temp dir.
-              "download.default_directory": options.downloadDir || import_node_os11.default.tmpdir(),
+              "download.default_directory": options.downloadDir || import_node_os12.default.tmpdir(),
               "download.prompt_for_download": false,
               "download.directory_upgrade": true
             },
@@ -650762,7 +652332,7 @@ async function runSpecs({ resolvedTests }) {
   const runDir = getRunOutputDir(config, {
     create: runArchivesArtifacts(config, specs)
   });
-  const runId = import_node_path26.default.basename(runDir);
+  const runId = import_node_path27.default.basename(runDir);
   const report = {
     runId,
     runDir,
@@ -651004,7 +652574,7 @@ async function runSpecs({ resolvedTests }) {
       }
       if (entry?.tempPath) {
         try {
-          import_node_fs29.default.unlinkSync(entry.tempPath);
+          import_node_fs30.default.unlinkSync(entry.tempPath);
         } catch {
         }
       }
@@ -651876,7 +653446,7 @@ function buildAutoRecordStep({ config, spec, test, context }) {
     return null;
   const runDir = getRunOutputDir(config, { create: false });
   const contextSegment = capPathSegment(sanitizeFilesystemName(String(context.contextId ?? ""), "context"));
-  const recordPath = import_node_path26.default.join(runDir, "specs", capPathSegment(sanitizeFilesystemName(String(spec.specId ?? ""), "spec")), "tests", capPathSegment(sanitizeFilesystemName(String(test.testId ?? ""), "test")), "contexts", contextSegment, "recordings", `${contextSegment}.mp4`);
+  const recordPath = import_node_path27.default.join(runDir, "specs", capPathSegment(sanitizeFilesystemName(String(spec.specId ?? ""), "spec")), "tests", capPathSegment(sanitizeFilesystemName(String(test.testId ?? ""), "test")), "contexts", contextSegment, "recordings", `${contextSegment}.mp4`);
   return {
     // Mobile-target contexts record the device screen through the app driver
     // (the internal device plan, resolved from the platform) — pinning ffmpeg
@@ -651893,28 +653463,21 @@ function buildAutoRecordStep({ config, spec, test, context }) {
     __autoRecord: true
   };
 }
-function capPathSegment(segment, max = 32) {
-  if (segment.length <= max)
-    return segment;
-  const hash = (0, import_node_crypto9.createHash)("sha1").update(segment).digest("hex").slice(0, 8);
-  const tail = segment.slice(segment.length - (max - hash.length - 1));
-  return `${hash}-${tail}`;
-}
 async function captureAutoScreenshot({ config, driver, spec, test, context, step, stepIndex, stepCount }) {
   try {
-    const action = BROWSER_STEP_KEYS.find((key) => typeof step[key] !== "undefined") || "step";
-    const sanitizedTestId = sanitizeFilesystemName(String(test.testId ?? ""), "test");
     const runDir = getRunOutputDir(config);
-    const dir = import_node_path26.default.join(runDir, "specs", capPathSegment(sanitizeFilesystemName(String(spec.specId ?? ""), "spec")), "tests", capPathSegment(sanitizedTestId), "contexts", capPathSegment(sanitizeFilesystemName(String(context.contextId ?? ""), "context")), "screenshots");
-    const stepIdString = sanitizeFilesystemName(String(step.stepId ?? ""), "step");
-    const stepRef = capPathSegment(stepIdString.startsWith(`${sanitizedTestId}~`) ? stepIdString.slice(sanitizedTestId.length + 1) : stepIdString);
-    const pad = Math.max(2, String(stepCount).length);
-    const fileName = `${String(stepIndex + 1).padStart(pad, "0")}-${action}-${stepRef}.png`;
+    const dir = import_node_path27.default.join(runDir, "specs", capPathSegment(sanitizeFilesystemName(String(spec.specId ?? ""), "spec")), "tests", capPathSegment(sanitizeFilesystemName(String(test.testId ?? ""), "test")), "contexts", capPathSegment(sanitizeFilesystemName(String(context.contextId ?? ""), "context")), "screenshots");
+    const fileName = stepArtifactFileName({
+      step,
+      stepIndex,
+      stepCount,
+      testId: test.testId
+    });
     const screenshotStep = {
       stepId: `${step.stepId}_auto`,
       description: "Automatic post-step screenshot",
       screenshot: {
-        path: import_node_path26.default.join(dir, fileName),
+        path: import_node_path27.default.join(dir, fileName),
         overwrite: "true"
       }
     };
@@ -651927,7 +653490,7 @@ async function captureAutoScreenshot({ config, driver, spec, test, context, step
       log(config, "warning", `Auto screenshot failed after step ${step.stepId}: ${captureResult.description}`);
       return null;
     }
-    return import_node_path26.default.relative(runDir, screenshotStep.screenshot.path).split(import_node_path26.default.sep).join("/");
+    return import_node_path27.default.relative(runDir, screenshotStep.screenshot.path).split(import_node_path27.default.sep).join("/");
   } catch (error) {
     log(config, "warning", `Auto screenshot failed after step ${step.stepId}: ${error?.message ?? error}`);
     return null;
@@ -652355,7 +653918,7 @@ ${JSON.stringify(context, null, 2)}`);
     const usedStepIds = new Set(context.steps.map((s) => s.stepId).filter(Boolean));
     for (const step of context.steps) {
       if (!step.stepId) {
-        const baseId = sanitizeFilesystemName(`${test.testId}~s${contentHash(step)}`, `step-${(0, import_node_crypto9.randomUUID)()}`);
+        const baseId = sanitizeFilesystemName(`${test.testId}~s${contentHash(step)}`, `step-${(0, import_node_crypto10.randomUUID)()}`);
         let stepId = baseId;
         let suffix = 2;
         while (usedStepIds.has(stepId)) {
@@ -652550,6 +654113,19 @@ ${JSON.stringify(r, null, 2)}`);
         if (capturedPath)
           stepReport.autoScreenshot = capturedPath;
       }
+      for (const checkpointDriver of sessionDrivers(browserSessions, driver)) {
+        await captureRecordingCheckpoints({
+          config,
+          driver: checkpointDriver,
+          recordingHost: checkpointDriver,
+          step,
+          stepStatus: stepReport.result,
+          stepIndex,
+          stepCount: context.steps.length,
+          testId: test.testId,
+          appSession
+        });
+      }
       pushStepReport(stepReport);
       if (routingDecision.action === "stop" && !step._fromAfter) {
         if (routingDecision.scope !== "test") {
@@ -652655,7 +654231,7 @@ async function stopAllRecordings({ config, context, driver, contextReport }) {
       stopRecord: true,
       __stopAny: true,
       description: "Stopping recording",
-      stepId: (0, import_node_crypto9.randomUUID)()
+      stepId: (0, import_node_crypto10.randomUUID)()
     };
     try {
       const stepResult = await runStep({
@@ -652753,8 +654329,16 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
       if (!Array.isArray(recordingHost.state.recordings))
         recordingHost.state.recordings = [];
       const handle = actionResult.recording;
-      handle.id = handle.id ?? (0, import_node_crypto9.randomUUID)();
+      handle.id = handle.id ?? (0, import_node_crypto10.randomUUID)();
       handle.name = handle.name ?? recordStepName(step.record);
+      handle.overwrite = step.record?.overwrite;
+      if (handle.targetPath) {
+        handle.checkpoints = resolveCheckpointsConfig({
+          record: step.record,
+          targetPath: handle.targetPath,
+          handleId: handle.id
+        });
+      }
       if (step.__autoRecord) {
         handle.synthetic = true;
         if (!driver && appSession && !isMobileTargetPlatform(context?.platform)) {
@@ -652897,7 +654481,7 @@ async function spawnAppiumServer(appiumEntry, config, display, extraEnv, extraAr
   } : process.env;
   const proc = (0, import_node_child_process15.spawn)(process.execPath, [appiumEntry, "-a", "127.0.0.1", "-p", String(port), ...extraArgs ?? []], {
     windowsHide: true,
-    cwd: import_node_path26.default.join(__dirname5, "../.."),
+    cwd: import_node_path27.default.join(__dirname5, "../.."),
     env
   });
   proc.on("error", (err) => {
@@ -653055,7 +654639,7 @@ async function getRunner(options = {}) {
   }
   const appium = (0, import_node_child_process15.spawn)(process.execPath, [appiumEntry, "-a", "127.0.0.1", "-p", String(appiumPort)], {
     windowsHide: true,
-    cwd: import_node_path26.default.join(__dirname5, "../..")
+    cwd: import_node_path27.default.join(__dirname5, "../..")
   });
   appium.on("error", (err) => {
     log(config, "warning", `Appium process error: ${err?.stack ?? err?.message ?? String(err)}`);
@@ -653114,7 +654698,7 @@ async function getRunner(options = {}) {
 }
 
 // dist/core/telem.js
-var import_node_os12 = __toESM(require("node:os"), 1);
+var import_node_os13 = __toESM(require("node:os"), 1);
 init_utils();
 var import_posthog_node = require("posthog-node");
 var import_node_module2 = require("node:module");
@@ -653142,11 +654726,11 @@ function sendTelemetry(config, command, results) {
   telemetryData.dist_interface = telemetryData.dist_interface || "package";
   telemetryData.core_version = pkg.version;
   telemetryData.dist_version = telemetryData.dist_version || telemetryData.core_version;
-  telemetryData.core_platform = platformMap2[import_node_os12.default.platform()] || import_node_os12.default.platform();
+  telemetryData.core_platform = platformMap2[import_node_os13.default.platform()] || import_node_os13.default.platform();
   telemetryData.dist_platform = telemetryData.dist_platform || telemetryData.core_platform;
-  telemetryData.core_platform_version = import_node_os12.default.release();
+  telemetryData.core_platform_version = import_node_os13.default.release();
   telemetryData.dist_platform_version = telemetryData.dist_platform_version || telemetryData.core_platform_version;
-  telemetryData.core_platform_arch = import_node_os12.default.arch();
+  telemetryData.core_platform_arch = import_node_os13.default.arch();
   telemetryData.dist_platform_arch = telemetryData.dist_platform_arch || telemetryData.core_platform_arch;
   telemetryData.core_deployment = telemetryData.core_deployment || "node";
   telemetryData.dist_deployment = telemetryData.dist_deployment || telemetryData.core_deployment;