fix wizard gen

Author: SimonCropp

docs/ai-usage.md

@@ -9,10 +9,102 @@ To change this file edit the source file and then run MarkdownSnippets.
 
 AI coding assistants (Claude Code, GitHub Copilot, Cursor, etc.) work well with Verify snapshot tests, but benefit from some project-level guidance. This page covers how to configure a project so AI assistants understand Verify's workflow.
 
+There are two approaches: a **skill** (action-oriented, invocable on-demand) and a **context file** (passive, always-on knowledge). Both can be used together.
 
-## AI context file
 
-Add the following to the AI context file for the relevant tool. Adapt the test command and framework references to match the project.
+## Skill
+
+A skill provides action-oriented instructions that an AI assistant can invoke when handling Verify snapshot test failures.
+
+Create a `SKILL.md` file in the appropriate directory for the tool:
+
+ * **Claude Code**: `.claude/skills/verify-snapshot-testing/SKILL.md`
+ * **GitHub Copilot**: `.github/skills/verify-snapshot-testing/SKILL.md`
+
+The content is the same for both tools:
+
+~~~markdown
+---
+name: verify-snapshot-testing
+description: Handle Verify snapshot test failures. Use this when a Verify snapshot test fails, when asked to accept or update snapshots, or when asked to add a new Verify test.
+---
+
+Handle [Verify](https://github.com/VerifyTests/Verify) snapshot test failures.
+
+## Key concepts
+
+- **`.verified.*` files** are the approved snapshots. They are committed to source control.
+- **`.received.*` files** are the actual output from the latest test run. They are generated when a test fails (actual != expected) and are git-ignored.
+
+## Handling a test failure
+
+When a Verify snapshot test fails, follow this process:
+
+### Step 1: Read the exception message
+
+The exception message is machine-parsable:
+
+```
+Directory: /path/to/test/project
+New:
+  - Received: TestClass.Method.received.txt
+    Verified: TestClass.Method.verified.txt
+NotEqual:
+  - Received: TestClass.Method.received.txt
+    Verified: TestClass.Method.verified.txt
+
+FileContent:
+
+Received: TestClass.Method.received.txt
+<received content>
+Verified: TestClass.Method.verified.txt
+<verified content>
+```
+
+- `Directory:` gives the base path for all file references.
+- `New` means no `.verified.` file exists yet (first run or new test).
+- `NotEqual` means the `.received.` and `.verified.` files differ.
+- `Delete` means a `.verified.` file is no longer produced by any test.
+- `FileContent:` contains the actual content for comparison.
+
+### Step 2: Read the files
+
+1. Read the `.received.*` file to see the actual output.
+2. Read the `.verified.*` file (if it exists) to see the expected output.
+3. Compare the two to understand the difference.
+
+### Step 3: Determine the action
+
+- **If the change is expected** (due to an intentional code change): copy the `.received.*` file over the `.verified.*` file to accept the new snapshot.
+- **If it is a new test** (no `.verified.*` file): accept the `.received.*` file as the new snapshot by renaming it to `.verified.*`.
+- **If the change is a bug**: fix the code, not the snapshot. Re-run the test to confirm the fix.
+
+## Rules
+
+- **Never hand-edit `.verified.*` files** to make tests pass. Always let Verify generate the correct output by running the test.
+- Snapshot files live next to the test source file. For a test in `Tests/MyTests.cs`, look for `Tests/MyTests.MethodName.verified.txt`.
+
+## Scrubbed values
+
+Verify replaces non-deterministic values with stable placeholders. These are intentional:
+
+- GUIDs become `Guid_1`, `Guid_2`, etc.
+- DateTimes become `DateTime_1`, `DateTime_2`, etc.
+- File paths become `{SolutionDirectory}`, `{ProjectDirectory}`, `{TempPath}`.
+
+Do not treat these placeholders as errors.
+
+## Verified file conventions
+
+- Encoding: UTF-8 with BOM
+- Line endings: LF (not CRLF)
+- No trailing newline
+~~~
+
+
+## Context file
+
+A context file provides passive, always-on knowledge about Verify. Add the following to the AI context file for the relevant tool. Adapt the test command and framework references to match the project.
 
  * **Claude Code**: `CLAUDE.md`
  * **GitHub Copilot**: `.github/copilot-instructions.md`

docs/explicit-targets.md

@@ -144,5 +144,5 @@ public Task WithTargets() =>
 ```txt
 Raw target value
 ```
-<sup><a href='/src/Verify.MSTest.Tests/Tests.WithTargets#targetName.verified.txt#L1-L1' title='Snippet source file'>snippet source</a> | <a href='#snippet-Verify.MSTest.Tests/Tests.WithTargets#targetName.verified.txt' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Verify.MSTest.Tests/Tests.WithTargets%23targetName.verified.txt#L1-L1' title='Snippet source file'>snippet source</a> | <a href='#snippet-Verify.MSTest.Tests/Tests.WithTargets#targetName.verified.txt' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->

docs/jsonappender.md

@@ -106,7 +106,7 @@ Then the appended content will be added to the `.verified.txt` file:
   theData: theValue
 }
 ```
-<sup><a href='/src/Verify.Tests/Converters/JsonAppenderTests.Stream#00.verified.txt#L1-L3' title='Snippet source file'>snippet source</a> | <a href='#snippet-JsonAppenderTests.Stream#00.verified.txt' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/Verify.Tests/Converters/JsonAppenderTests.Stream%2300.verified.txt#L1-L3' title='Snippet source file'>snippet source</a> | <a href='#snippet-JsonAppenderTests.Stream#00.verified.txt' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 See [Converters](/docs/converter.md) for more information on `*.00.verified.txt` files.

docs/mdsource/ai-usage.source.md

@@ -22,7 +22,7 @@ name: verify-snapshot-testing
 description: Handle Verify snapshot test failures. Use this when a Verify snapshot test fails, when asked to accept or update snapshots, or when asked to add a new Verify test.
 ---
 
-You are a specialized agent for handling [Verify](https://github.com/VerifyTests/Verify) snapshot test failures.
+Handle [Verify](https://github.com/VerifyTests/Verify) snapshot test failures.
 
 ## Key concepts
 

docs/mdsource/text-file-settings.include.md

@@ -14,7 +14,7 @@ All text extensions of `*.verified.*` should have:
  * `eol` set to `lf`
  * `working-tree-encoding` set to `UTF-8`
 
-Note: `working-tree-encoding=UTF-8` is correct even though Verify writes files with a BOM. Git doesn't strip or add the BOM — it just passes through transparently. The `UTF-8-BOM` encoding would explicitly add a BOM on checkout and strip it on commit (so the internal blob differs from the working tree), but that's not the desired behavior since Verify writes the BOM itself and it should be preserved in the blob too.
+Note: `working-tree-encoding=UTF-8` is correct even though Verify writes files with a BOM. Git does not strip or add the BOM — it passes through transparently. The `UTF-8-BOM` encoding would explicitly add a BOM on checkout and strip it on commit (so the internal blob differs from the working tree), but that is not the desired behavior since Verify writes the BOM itself and it should be preserved in the blob.
 
 All Binary files should also be marked to avoid merging and line ending issues with binary files.
 

docs/wiz/Linux_Other_Cli_Expecto_AppVeyor.md

@@ -69,6 +69,8 @@ All text extensions of `*.verified.*` should have:
  * `eol` set to `lf`
  * `working-tree-encoding` set to `UTF-8`
 
+Note: `working-tree-encoding=UTF-8` is correct even though Verify writes files with a BOM. Git does not strip or add the BOM — it passes through transparently. The `UTF-8-BOM` encoding would explicitly add a BOM on checkout and strip it on commit (so the internal blob differs from the working tree), but that is not the desired behavior since Verify writes the BOM itself and it should be preserved in the blob.
+
 All Binary files should also be marked to avoid merging and line ending issues with binary files.
 
 eg add the following to `.gitattributes`

docs/wiz/Linux_Other_Cli_Expecto_AzureDevOps.md

@@ -69,6 +69,8 @@ All text extensions of `*.verified.*` should have:
  * `eol` set to `lf`
  * `working-tree-encoding` set to `UTF-8`
 
+Note: `working-tree-encoding=UTF-8` is correct even though Verify writes files with a BOM. Git does not strip or add the BOM — it passes through transparently. The `UTF-8-BOM` encoding would explicitly add a BOM on checkout and strip it on commit (so the internal blob differs from the working tree), but that is not the desired behavior since Verify writes the BOM itself and it should be preserved in the blob.
+
 All Binary files should also be marked to avoid merging and line ending issues with binary files.
 
 eg add the following to `.gitattributes`

docs/wiz/Linux_Other_Cli_Expecto_GitHubActions.md

@@ -69,6 +69,8 @@ All text extensions of `*.verified.*` should have:
  * `eol` set to `lf`
  * `working-tree-encoding` set to `UTF-8`
 
+Note: `working-tree-encoding=UTF-8` is correct even though Verify writes files with a BOM. Git does not strip or add the BOM — it passes through transparently. The `UTF-8-BOM` encoding would explicitly add a BOM on checkout and strip it on commit (so the internal blob differs from the working tree), but that is not the desired behavior since Verify writes the BOM itself and it should be preserved in the blob.
+
 All Binary files should also be marked to avoid merging and line ending issues with binary files.
 
 eg add the following to `.gitattributes`

docs/wiz/Linux_Other_Cli_Expecto_None.md

@@ -69,6 +69,8 @@ All text extensions of `*.verified.*` should have:
  * `eol` set to `lf`
  * `working-tree-encoding` set to `UTF-8`
 
+Note: `working-tree-encoding=UTF-8` is correct even though Verify writes files with a BOM. Git does not strip or add the BOM — it passes through transparently. The `UTF-8-BOM` encoding would explicitly add a BOM on checkout and strip it on commit (so the internal blob differs from the working tree), but that is not the desired behavior since Verify writes the BOM itself and it should be preserved in the blob.
+
 All Binary files should also be marked to avoid merging and line ending issues with binary files.
 
 eg add the following to `.gitattributes`

docs/wiz/Linux_Other_Cli_Fixie_AppVeyor.md

@@ -68,6 +68,8 @@ All text extensions of `*.verified.*` should have:
  * `eol` set to `lf`
  * `working-tree-encoding` set to `UTF-8`
 
+Note: `working-tree-encoding=UTF-8` is correct even though Verify writes files with a BOM. Git does not strip or add the BOM — it passes through transparently. The `UTF-8-BOM` encoding would explicitly add a BOM on checkout and strip it on commit (so the internal blob differs from the working tree), but that is not the desired behavior since Verify writes the BOM itself and it should be preserved in the blob.
+
 All Binary files should also be marked to avoid merging and line ending issues with binary files.
 
 eg add the following to `.gitattributes`