[xavierjohn]

Summary

This is a proposal, opened as a draft so the team can decide whether it fits the project before any further work.

It packs three short Markdown guides for coding agents (Copilot, Claude Code and similar) inside the Asp.Versioning.Http package, so an agent working in a project that references the package can read guidance for the installed version instead of guessing or relying on stale web pages.

• agent-guide.md (required, about 1.9 KB): registration, versioning Minimal API endpoints, and the default behavior an agent must know.
• version-sources-and-defaults.md (on demand): query string, header and URL segment readers, how a custom reader replaces the defaults, and AssumeDefaultVersionWhenUnspecified.
• deprecation-and-errors.md (on demand): HasDeprecatedApiVersion, the version headers, the unspecified, unsupported and invalid problem responses, and version-neutral endpoints.

Every behavioral statement in the guides was checked by running the code against current main (status codes, headers and problem types), including some non-obvious ones, for example that setting ApiVersionReader replaces the default readers and that an unsupported version in a URL segment is a 404.

What changes in the package

• Adds guidance/reference-manifest.json and guides/*.md to the nupkg.
• Adds a build-only PackageReference to Trellis.AgentDocs.Packaging (PrivateAssets="all"). It does not appear in the nuspec dependencies and nothing is added to the library or its runtime dependencies. I confirmed the dependency list of the packed nuspec is unchanged.
• No source code, public API or behavior changes.

How consumers see it

Nothing happens by default. Restoring the package never modifies a repository. A developer opts in with the separate Trellis.AgentDocs .NET tool; guidance from a package is read only after they approve that package ID in a committed policy.json.

Scope and open questions

• Only Asp.Versioning.Http is included. Other packages (Mvc, ApiExplorer, OData, Abstractions) are left for later, so the team can judge the approach on one package first.
• The helper is pinned to 0.1.0-preview.22. A newer helper is needed before multi-targeted packages such as Asp.Versioning.Abstractions can carry guidance.
• This adds no tests; the guides were verified by hand against running code. I am happy to add a pack-time check if the team wants this direction.
• I did not touch ReleaseNotes.txt or the version, since those follow your release process.

Verification

• dotnet pack of the project produces the manifest and the three guides alongside the existing README, analyzer and library.
• agentdocs validate --strict on the package: 0 errors, 0 warnings.
• End to end: restored the package in a scratch repository, ran agentdocs init, approved the package and ran sync; the required guide and both on-demand guides installed and the generated index lists them.
• The CLA will be signed through the bot as usual.