From 2302fc9d83c921d4014d90064a8796af38045f99 Mon Sep 17 00:00:00 2001
From: Xavier <1859710+xavierjohn@users.noreply.github.com>
Date: Fri, 16 Oct 2026 17:03:22 -0700
Subject: [PATCH] Upgrade AgentDocs packaging to preview 22

---
 Directory.Packages.props                                      | 2 +-
 .../src/README.md                                             | 4 ++--
 Trellis.ServiceLevelIndicators.Asp/src/README.md              | 4 ++--
 Trellis.ServiceLevelIndicators/src/README.md                  | 4 ++--
 docs/usage-reference.md                                       | 4 ++--
 5 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Directory.Packages.props b/Directory.Packages.props
index c4b6ebe..79998a6 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -11,7 +11,7 @@
     <PackageVersion Include="Asp.Versioning.Mvc.ApiExplorer" Version="10.2.1" />
     <PackageVersion Include="Asp.Versioning.OpenApi" Version="10.2.3" />
     <PackageVersion Include="DotNet.ReproducibleBuilds" Version="2.0.5" />
-    <PackageVersion Include="Trellis.AgentDocs.Packaging" Version="0.1.0-preview.20" />
+    <PackageVersion Include="Trellis.AgentDocs.Packaging" Version="0.1.0-preview.22" />
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.13" />
     <PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="10.0.13" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.13" />
diff --git a/Trellis.ServiceLevelIndicators.Asp.ApiVersioning/src/README.md b/Trellis.ServiceLevelIndicators.Asp.ApiVersioning/src/README.md
index b84f148..f7c15a9 100644
--- a/Trellis.ServiceLevelIndicators.Asp.ApiVersioning/src/README.md
+++ b/Trellis.ServiceLevelIndicators.Asp.ApiVersioning/src/README.md
@@ -61,7 +61,7 @@ run from its Git root:
 
 ```powershell
 dotnet new tool-manifest --output .config
-dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.20 --tool-manifest .config/dotnet-tools.json
+dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.22 --tool-manifest .config/dotnet-tools.json
 dotnet tool run agentdocs init <solution-or-project>
 ```
 
@@ -72,7 +72,7 @@ lists `Trellis.ServiceLevelIndicators.Asp.ApiVersioning` as pending and prints t
 `dotnet tool run agentdocs sync` to install the guides under Git-root
 `.agentdocs/`. The guide is on-demand: the generated index describes it, and an
 agent opens it when its task concerns SLI metrics. After a package upgrade, run
-`dotnet restore` and then `dotnet tool run agentdocs sync`.
+`dotnet restore --force` and then `dotnet tool run agentdocs sync`.
 
 ## Further Reading
 
diff --git a/Trellis.ServiceLevelIndicators.Asp/src/README.md b/Trellis.ServiceLevelIndicators.Asp/src/README.md
index 9a70962..91800ac 100644
--- a/Trellis.ServiceLevelIndicators.Asp/src/README.md
+++ b/Trellis.ServiceLevelIndicators.Asp/src/README.md
@@ -297,7 +297,7 @@ run from its Git root:
 
 ```powershell
 dotnet new tool-manifest --output .config
-dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.20 --tool-manifest .config/dotnet-tools.json
+dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.22 --tool-manifest .config/dotnet-tools.json
 dotnet tool run agentdocs init <solution-or-project>
 ```
 
@@ -308,7 +308,7 @@ lists `Trellis.ServiceLevelIndicators.Asp` as pending and prints the package IDs
 `dotnet tool run agentdocs sync` to install the guides under Git-root
 `.agentdocs/`. The guide is on-demand: the generated index describes it, and an
 agent opens it when its task concerns SLI metrics. After a package upgrade, run
-`dotnet restore` and then `dotnet tool run agentdocs sync`.
+`dotnet restore --force` and then `dotnet tool run agentdocs sync`.
 
 ## Further Reading
 
diff --git a/Trellis.ServiceLevelIndicators/src/README.md b/Trellis.ServiceLevelIndicators/src/README.md
index 1c74a01..019bbd7 100644
--- a/Trellis.ServiceLevelIndicators/src/README.md
+++ b/Trellis.ServiceLevelIndicators/src/README.md
@@ -202,7 +202,7 @@ run from its Git root:
 
 ```powershell
 dotnet new tool-manifest --output .config
-dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.20 --tool-manifest .config/dotnet-tools.json
+dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.22 --tool-manifest .config/dotnet-tools.json
 dotnet tool run agentdocs init <solution-or-project>
 ```
 
@@ -213,7 +213,7 @@ lists `Trellis.ServiceLevelIndicators` as pending and prints the package IDs to
 `dotnet tool run agentdocs sync` to install the guides under Git-root
 `.agentdocs/`. The guide is on-demand: the generated index describes it, and an
 agent opens it when its task concerns SLI metrics. After a package upgrade, run
-`dotnet restore` and then `dotnet tool run agentdocs sync`.
+`dotnet restore --force` and then `dotnet tool run agentdocs sync`.
 
 ## Further Reading
 
diff --git a/docs/usage-reference.md b/docs/usage-reference.md
index 73ad095..e993e79 100644
--- a/docs/usage-reference.md
+++ b/docs/usage-reference.md
@@ -542,13 +542,13 @@ Ordinary restore/build does not write `.github/`, `AGENTS.md`, or `.agentdocs/`
 
 ```powershell
 dotnet new tool-manifest --output .config
-dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.20 --tool-manifest .config\dotnet-tools.json
+dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.22 --tool-manifest .config\dotnet-tools.json
 dotnet tool run agentdocs init <solution-or-project>
 ```
 
 Reuse an existing root `.config\dotnet-tools.json` instead of creating another. Restoring a package never activates its guide. `init` lists packages that publish guidance as pending and prints the package IDs to add to `approvedPackages` in `.agentdocs/policy.json`. Add the SLI packages you trust, then run `dotnet tool run agentdocs sync` to install their guides into Git-root `.agentdocs/`; `init` also adds managed instruction pointers.
 
-Guides are on-demand: the generated index lists each with a description, and an agent opens one when its task concerns SLI metrics. After a package upgrade, run `dotnet restore` and `dotnet tool run agentdocs sync`. The helper and tool are preview packages published on NuGet.org.
+Guides are on-demand: the generated index lists each with a description, and an agent opens one when its task concerns SLI metrics. After a package upgrade, run `dotnet restore --force` and `dotnet tool run agentdocs sync`. The forced restore refreshes NuGet's successful-restore checkpoint even when the resolved graph stays unchanged; the tool rejects stale restore output rather than installing outdated guidance. The helper and tool are preview packages published on NuGet.org.
 
 For maintainers, the three publishing projects use a pinned, private `Trellis.AgentDocs.Packaging` build dependency to generate manifests at pack time. Each project sets `TrellisApiRefDescription`, the one-line "Open when..." topic consumers see. Guides refer to sibling packages by ID rather than by link because every package installs into its own directory. The packaging build target is not included in published SLI packages. Run `pwsh -NoProfile -File build\test-guidance-packages.ps1` after packing to verify payloads and the absence of legacy consumer targets.