Improve F# / Expecto docs and clarify text snapshot encoding conventions

[IvanTheGeek]

Summary

I’ve been using Verify from F# with Expecto, and I think there’s an opportunity to make that path easier to discover and understand.

The current docs are useful, and I may have missed some existing guidance, but a few things were not obvious until I dug further than I expected.

What was confusing

From the perspective of an F# / Expecto user, it would help to have clearer guidance on:

• the recommended minimal setup for Verify + Expecto
• the expected approval/update flow in that stack
• text snapshot file conventions
• the fact that text snapshots are written as UTF-8 with BOM
• whether BOM in .verified.* files is expected behavior or something to “fix”

This led to extra investigation just to confirm whether generated files were correct.

What would help

A few documentation improvements would go a long way:

• a clearer F# + Expecto setup example
• a small end-to-end example showing:
  • test code
  • generated .received.* / .verified.* files
  • the expected review/approval flow
• a more visible note about text snapshot file conventions
• an explicit statement that text snapshots are written as UTF-8 with BOM
• a brief explanation of why that choice exists / what users should expect in editors and diffs

Why this matters

This would make the F# / Expecto path easier to adopt and reduce the need to inspect generated files at the byte level just to understand expected behavior.

It would also help separate:

• intended Verify behavior
• editor/tooling display differences
• actual snapshot problems

Possible docs additions

Any of these would help:

• expand the existing README Expecto section
• add a dedicated F# + Expecto doc page
• add a short text snapshot file conventions doc page
• add a small BOM / encoding troubleshooting note

Example of the clarification I was looking for

Something as simple as this would have helped:

• Verify text snapshots are written as UTF-8 with BOM.
• This is expected behavior.
• Editors and diff tools may display this differently.
• If you inspect the raw bytes, the BOM appears as EF BB BF.

If this would be welcome, I’d be happy to turn it into a more concrete docs PR proposal.

[SimonCropp]

have u tried the Getting Started Wizard? https://github.com/VerifyTests/Verify/blob/main/docs/wiz/readme.md

[IvanTheGeek]

I just did and got to docs/wiz/Linux_Other_Cli_Expecto_None.md which should be helpful. I have been using OpenAI Codex 5.4 which did not locate this doc when first using the expecto + Verify (which I was not aware of Verify to begin with). We had several rounds of codex having issues with the BOM.

I wonder if there is a way to prime the AIs to hit the wizard docs and bone up before they try to use Verify... Hmmm

[SimonCropp]

the conventions are also document on the readme https://github.com/VerifyTests/Verify?tab=readme-ov-file#conventions

I wonder if there is a way to prime the AIs to hit the wizard docs and bone up before they try to use Verify

not that i know of. happy to be educated

[IvanTheGeek]

I post this as help to others who might be having issues concerning AI assistance:

My prompt in my Verify chat which has previous context and history:

check out https://github.com/orgs/VerifyTests/discussions/1699#discussioncomment-16406706 and follow the links. So was our problem that you used the Verify package and did not then check the repo and websites for understanding how to use it and what it produced?

Codex reply:

Yes, mostly.

The main problem was not that Verify lacked docs. The problem was that I did not follow the better onboarding path early enough:

1. repo README / docs spine
2. Getting Started Wizard
3. conventions/docs
4. only then lower-level inspection if still needed

The relevant official docs were there:

• The wizard entry point is docs/wiz/readme.md, and the maintainer explicitly pointed to it in your discussion.
• The README’s Conventions section already says text verified/received files are UTF-8 with BOM, LF, and no trailing newline, and it includes VerifyChecks.Run() guidance for Expecto.

So the honest answer is:

• yes, I used the package and then reasoned too much from behavior/output
• no, I did not consult the right official docs soon enough
• yes, that was a meaningful part of why we got friction around the BOM and workflow

The deeper lesson is the same one we adopted for NEXUS:

• TOC/docs first
• examples next
• source/API details after that
• byte/binary inspection only as fallback

So if you’re asking whether this was primarily a documentation-missed-by-me problem rather than “Verify has no docs,” I’d say yes.

So the point is that when you are working with AI coders, and they/you want to use a package, instruct them to "Read the #%$# docs" - basically, same as for humans. Guess I should have taken my own advice, which I will now!

[SimonCropp]

@IvanTheGeek can u ask codex if there is anything in the xml docs, or in the nugetm or in the readme that could be done that would mean the next codex interaction discovers the correct setup

[IvanTheGeek]

Sorry for the delay in response. Right after this my VM crapped out and I had to do some gymnastics to recover the AI history. However, Claude Code came to the rescue and helped me. I asked him to review what that session was doing and he gave me the following to pass along:

---

Good context. The maintainer's question is essentially: what can I add to the package/docs that will make AI tools find the right setup path without being told?

---

To answer your question — the first thing Codex did was crack open the DLL. It reflected over the assembly to figure out the API surface before writing any code. It never consulted the README, the wizard, or the NuGet page first. That's the root cause of the BOM/encoding issues we went through: it reasoned from the types and method signatures alone, without the context the docs would have provided.

A few things that would help, ordered roughly by how directly they address that path:

1. AssemblyMetadata attributes on the assembly

These are baked into the binary itself. Any tool that reflects over the DLL — ILSpy, dotnet-reflect, Codex — sees them without needing the companion XML file:

[assembly: System.Reflection.AssemblyMetadata("docs", "https://github.com/VerifyTests/Verify/blob/main/docs/wiz/readme.md")]
[assembly: System.Reflection.AssemblyMetadata("getting-started", "Before writing any code, run the Getting Started Wizard at the docs URL above — it generates exact setup for your test framework, language, and OS")]

This is the most robust option for the DLL-inspection path specifically.

2. XML <remarks> on the primary entry-point type/method

The .xml companion file ships in the NuGet package alongside the DLL. If the AI reads that file (rather than the binary), it hits this immediately:

/// <remarks>
/// Before first use, follow the Getting Started Wizard:
/// https://github.com/VerifyTests/Verify/blob/main/docs/wiz/readme.md
/// It generates the exact setup for your test framework, language, and OS.
/// </remarks>

3. llms.txt at the repo root and docs site

Emerging standard specifically for this problem — https://llmstxt.org. AI agents that follow this convention check it before anything else. Put the wizard link, the conventions link, and a short "start here" summary in it. Won't help for the DLL-inspection path, but catches agents that start from the repo or docs site.

4. README: wizard first, before installation steps

AIs weight the top of a README heavily. Putting the wizard link after installation steps means it gets skipped when an AI synthesizes from the README. Moving it to the first line after the title would help:

> **New here?** Start with the [Getting Started Wizard](docs/wiz/readme.md) — generates exact setup for your framework, language, and OS.

5. NuGet package description

Include the wizard URL in <Description> in the .csproj. Tools that start from the NuGet package page will read it before anything else.

---

The AssemblyMetadata approach directly addresses the DLL-inspection path Codex took and is probably the single highest-leverage change for AI tooling specifically. The llms.txt file covers agents that start from the repo/docs. Together they cover both entry points.

---

I would be happy to do a PR for these changes if you like, or you can take the advice and change for yourself. Let me know. :)