purview-dev · kieronlanning · Sep 29, 2026 · Sep 29, 2026
diff --git a/.agents/prompts/sdk-diagnose-agent-folder-copy.md b/.agents/prompts/sdk-diagnose-agent-folder-copy.md
@@ -11,16 +11,27 @@ destination in a consuming repository.
 3. Check `EnableAgentFolderInPackage` is not set to `false` anywhere in the build (project file,
    `Directory.Build.props`, or command-line `-p:` overrides).
 4. Confirm the destination folder: default is `.agents` at the repo root, overridable per-build with
-   `-p:AgentPackDestinationFolder=<folder>`.
+   `-p:AgentPackDestinationFolder=<folder>`, and the source defaults to the package-level `.agents`
+   folder (override with `PurviewAgentFolderSourcePath`).
 5. Verify repo-root discovery succeeded: explicit `RepoRoot`, then a nearby `AGENTS.md`, then source-control
    root metadata.
-6. Re-run the build and confirm the destination folder now contains the copied files (including the
+6. If the destination looks stale or incomplete, inspect the change-detection manifest
+   (`<repo root>/.purview/agent-sync.cache`). It lists the files the SDK believes it already mirrored; a
+   matching entry with a present destination file means the sync was skipped as up to date. Delete the
+   manifest (or the affected destination file) to force a fresh copy.
+7. Retry notices are demoted to low-importance messages, so a healthy build shows no `MSB3026` warnings.
+   A copy that still fails after every retry is reported as an error naming the source, destination and
+   OS error - search the build log for `The Purview SDK could not copy`. Temporarily set
+   `PurviewAgentFolderCopyRetries` / `PurviewAgentFolderCopyRetryDelayMilliseconds` to retry longer, and
+   `PurviewSuppressCopyRetryWarnings=false` to see every retry attempt.
+8. Re-run the build and confirm the destination folder now contains the copied files (including the
    generated `.gitignore` for skill/prompt/agent subfolders).
 
 ## Suggested output
 
-- A short root-cause explanation (missing import, disabled flag, wrong destination override, or repo-root
-  discovery miss).
+- A short root-cause explanation (missing import, disabled flag, wrong destination override, repo-root
+  discovery miss, or a destination held open by another process).
 - The exact command used to reproduce/verify the fix (for example
   `dotnet build <project> -p:AgentPackDestinationFolder=<folder>`).
-- Confirmation that the expected files exist at the resolved destination path.
+- Confirmation that the expected files exist at the resolved destination path, plus whether the
+  manifest skipped the sync (in which case the content was already up to date).
diff --git a/AGENTS.md b/AGENTS.md
@@ -62,7 +62,7 @@ conventional-commits check.
 | `just update-version` | Runs `.build/update-version.ts` to sync the version into docs/samples. |
 | `just pack` | Updates the version then packs the NuGet package into `artifacts/`. |
 
-The version lives in `package.json`. **Current Version:** 5.0.0-prerelease.13 — applied to `Version` /
+The version lives in `package.json`. **Current Version:** 5.0.0 — applied to `Version` /
 `PackageVersion` via the SDK's package.json version detection.
 
 ### Pipelines (reusable `purview-build` tool)
@@ -100,6 +100,8 @@ src/
 ├── src/
 │   ├── SourceGenerator/                    # Main incremental source generator (netstandard2.0, Roslyn)
 │   │   ├── Analyzers/                      # Diagnostic analyzers for telemetry interfaces
+│   │   ├── AnalyzerReleases.Shipped.md     # Roslyn analyzer release tracking (shipped TSG rules)
+│   │   ├── AnalyzerReleases.Unshipped.md   # Roslyn analyzer release tracking (upcoming TSG rules)
 │   │   ├── Emitters/                       # CodeWriter-based code emission
 │   │   ├── Generators/                     # Incremental generator pipeline
 │   │   └── Sdk/                            # SDK-style package content (props/targets)
@@ -158,6 +160,12 @@ The sample projects enable `EmitCompilerGeneratedFiles`, so generated telemetry
 - **SDK**: projects import `Purview.BuildSdk` via `Directory.Build.props`/`.targets`. The repo
   sets `ExcludePurviewTelemetry=true` (it does not consume the telemetry package it generates) and
   `NamespacePrefix=Purview.Telemetry` under `src/`. See `.agents/skills/sdk-*` for SDK behavior.
+- **Analyzer release tracking**: the `TSG` rules are tracked in
+  `src/src/SourceGenerator/AnalyzerReleases.{Shipped,Unshipped}.md` (wired as `AdditionalFiles`, so
+  the Roslyn RS2000-series checks run under `EnforceExtendedAnalyzerRules=true`). Add new rules to
+  `AnalyzerReleases.Unshipped.md`, then move them into a new `## Release x.y.z` section in
+  `AnalyzerReleases.Shipped.md` at release time. `RS2003` is suppressed — see the comment in
+  `src/src/SourceGenerator/SourceGenerator.csproj`.
 
 ## Source-generator and testing skills
 

diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ Generates [`ActivitySource`](https://learn.microsoft.com/en-us/dotnet/api/system
 Add to your `Directory.Build.props` or `.csproj` file:
 
 ```xml
-<PackageReference Include="Purview.Telemetry.SourceGenerator" Version="5.0.0-prerelease.13">
+<PackageReference Include="Purview.Telemetry.SourceGenerator" Version="5.0.0">
   <PrivateAssets>all</PrivateAssets>
   <IncludeAssets>analyzers</IncludeAssets>
 </PackageReference>
@@ -132,16 +132,15 @@ public class EntityService(IEntityStoreTelemetry telemetry)
 | `[ObservableCounter]`, `[ObservableGauge]`, `[ObservableUpDownCounter]` | Method | Observable instruments |
 
 > [!TIP]
-> For single-target interfaces (only Activities, only Logging, or only Metrics), the generator automatically infers the necessary attributes. See the [wiki](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Multi-Targeting) for details.
+> For single-target interfaces (only Activities, only Logging, or only Metrics), the generator automatically infers the necessary attributes. See the [Multi-Targeting guide](https://purview.dev/docs/telemetry-sourcegenerator/multi-targeting/) for details.
 
 ## Documentation
 
 - [Homepage](https://purview.dev/projects/telemetry-sourcegenerator/)
 - [Documentation](https://purview.dev/docs/telemetry-sourcegenerator/)
-- [Full Wiki](https://github.com/purview-dev/telemetry-sourcegenerator/wiki)
-- [Generated Output Examples](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Generated-Output)
-- [Multi-Targeting Guide](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Multi-Targeting)
-- [Logging Configuration](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Logging)
+- [Generated Output Examples](https://purview.dev/docs/telemetry-sourcegenerator/generated-output/)
+- [Multi-Targeting Guide](https://purview.dev/docs/telemetry-sourcegenerator/multi-targeting/)
+- [Logging Configuration](https://purview.dev/docs/telemetry-sourcegenerator/logging/)
 
 ## Agent Skills
 
@@ -156,7 +155,7 @@ The [.NET Aspire Sample](https://github.com/purview-dev/telemetry-sourcegenerato
 
 ## Performance
 
-Benchmarked on 13th Gen Intel Core i9-13900KF, .NET SDK 10.0.401. See the [Performance](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Performance) wiki page for full cross-runtime results.
+Benchmarked on 13th Gen Intel Core i9-13900KF, .NET SDK 10.0.401. See the [Performance](https://purview.dev/docs/telemetry-sourcegenerator/performance/) page for full cross-runtime results.
 
 ### Activities (.NET 10.0)
 
@@ -290,7 +289,7 @@ public enum NamingConvention
 
 ## Contributing
 
-Contributions are welcome! See the [Contributing guide](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Contributing) for development setup and testing instructions.
+Contributions are welcome! See the [Contributing guide](https://purview.dev/docs/telemetry-sourcegenerator/contributing/) for development setup and testing instructions.
 
 See [docs/release-process.md](docs/release-process.md) for the release flow, and [`AGENTS.md`](AGENTS.md)
 for the build, validation, and convention rules. Bump the version in `package.json` and run

diff --git a/docs/release-process.md b/docs/release-process.md
@@ -70,12 +70,25 @@ Merging to `main` triggers `release.yml`, which runs the reusable `purview-relea
 
 ## Versioning
 
-- The version lives in `package.json`. **Current Version:** 5.0.0-prerelease.13
+- The version lives in `package.json`. **Current Version:** 5.0.0
 - It is applied to `Version` / `PackageVersion` by `Purview.BuildSdk` via package.json
   version detection (`UsePackageJsonVersion`, default `true`).
 - `just version` prints the current version.
 - After bumping `package.json`, run `just update-version` to sync the version into docs/samples.
 
+### Analyzer release tracking
+
+The `TSG` diagnostics are tracked in `src/src/SourceGenerator/AnalyzerReleases.Shipped.md` and
+`src/src/SourceGenerator/AnalyzerReleases.Unshipped.md`. The files are wired up as `AdditionalFiles`,
+so the Roslyn release-tracking analyzers validate them on every build (`EnforceExtendedAnalyzerRules`
+is enabled by `Purview.BuildSdk`).
+
+1. Add new rules to `AnalyzerReleases.Unshipped.md`.
+2. At release time, create a new `## Release <version>` section in `AnalyzerReleases.Shipped.md`,
+   move the unshipped entries into it, and leave the unshipped file empty.
+3. Keep the rule ID, category, and severity in sync with the `DiagnosticDescriptor`s in
+   `src/src/SourceGenerator/Helpers/DiagnosticLibrary.*.cs`.
+
 ## Building the package locally
 
 | Command | Purpose |