Update package READMEs as part of the release process

.github/release-process.md

@@ -12,11 +12,13 @@ The following process is used when publishing new releases to NuGet.org.
 
 From a local clone of the repository, use Copilot CLI to invoke the `prepare-release` skill. The skill assesses the semantic version, bumps the version in [`src/Directory.Build.props`](../src/Directory.Build.props), runs API compatibility checks, reviews documentation, drafts release notes, and creates a pull request with all release artifacts.
 
+As part of Step 9 (documentation review), the skill also updates the shared embedded NuGet README (`src/PACKAGE.md`) -- adding any newly introduced packages to the package-list closure, applying the correct badge style (`nuget/vpre` for a prerelease series or `nuget/v` for a stable release), adding a release-notes link pointing to the tag being created, and syncing the same closure changes to the root `README.md`.
+
 Review the PR, request changes if needed, and merge when ready.
 
 ## 3. Publish the release
 
-After the prepare-release PR is merged, invoke the `publish-release` skill. The skill checks for any late-arriving PRs that could affect the release, refreshes the release notes, and creates a **draft** GitHub release.
+After the prepare-release PR is merged, invoke the `publish-release` skill. The skill checks for any late-arriving PRs that could affect the release, refreshes the release notes, re-runs the README content checklist (confirming package closure, badge style, and release-notes link), and creates a **draft** GitHub release.
 
 Review the draft release on GitHub, check 'Set as a pre-release' if appropriate, and click 'Publish release'.
 

.github/skills/prepare-release/SKILL.md

@@ -130,13 +130,25 @@ Generate a human-readable diff of the public API surface between the previous re
 
 Review repository documentation for changes needed to compensate for or adapt to this release:
 
-1. **NuGet package READMEs** — Validate that code samples in `README.md` and `src/PACKAGE.md` compile against the current SDK. Follow [references/readme-snippets.md](references/readme-snippets.md) for the validation procedure. Propose fixes for any API mismatches.
-2. **Conceptual documentation** — Review `docs/` for content affected by the changes in this release. Update references to changed APIs, new features, or removed functionality.
-3. **Versioning documentation** — If the release introduces new versioning-relevant policies (new experimental APIs, obsoletion changes), verify `docs/versioning.md` reflects them.
-4. **Changelogs** — If the repository contains changelog files (e.g., `CHANGELOG.md`), update them with the release information. If no changelogs exist, skip this sub-step and note it in the summary.
+1. **NuGet package READMEs** -- Run the README content checklist from [references/readme-content.md](references/readme-content.md) and validate code samples:
+   a. **Content checklist** -- Open `src/PACKAGE.md` and verify each item in the checklist:
+      - **Package-list closure**: every shipping SDK package is listed. If a new package was introduced in this release, add it now. Use non-counting phrasing -- do not say "N main packages".
+      - **Badge strategy**: all package badges use `nuget/vpre` for a prerelease series or `nuget/v` for a stable release. Switch all badges together if the release type has changed.
+      - **Release-notes link**: add or update the link to `https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v{version}` for the confirmed release version. The tag does not yet exist at prepare time; the link is forward-referencing and resolves when the GitHub release is published.
+      - **Root README.md sync**: mirror any package-list closure changes in the root `README.md`.
+      - **Other salient content**: descriptions, getting-started links, version-specific notes.
+   b. **Snippet validation** -- Validate that `csharp`-fenced code blocks in `src/PACKAGE.md` and `README.md` compile against the current SDK. Follow [references/readme-snippets.md](references/readme-snippets.md) for the full procedure. Propose fixes for any API mismatches.
+2. **Conceptual documentation** -- Review `docs/` for content affected by the changes in this release. Update references to changed APIs, new features, or removed functionality.
+3. **Versioning documentation** -- If the release introduces new versioning-relevant policies (new experimental APIs, obsoletion changes), verify `docs/versioning.md` reflects them.
+4. **Changelogs** -- If the repository contains changelog files (e.g., `CHANGELOG.md`), update them with the release information. If no changelogs exist, skip this sub-step and note it in the summary.
 
 Stage all documentation changes for inclusion in the release commit.
 
+**Edge Cases for README updates:**
+- **New package introduced** -- Add it to the package-list closure in `src/PACKAGE.md` and `README.md`. Use the package's `<Description>` from its `.csproj` as the short description.
+- **Release type changes (prerelease to stable or vice versa)** -- Switch all package badges between `nuget/vpre` and `nuget/v` together.
+- **Release tag does not yet exist at prepare time** -- The release-notes link is forward-referencing; it is verified to resolve during the publish-release step.
+
 ### Step 10: Draft Release Notes
 
 Compose the release notes that will appear in the PR description and serve as the foundation for the **publish-release** skill. This is a draft — the final release notes will be refreshed when the GitHub release is created.

.github/skills/prepare-release/references/readme-content.md

@@ -0,0 +1,94 @@
+# README Content Checklist
+
+This reference describes what to review and update in the shared embedded NuGet README
+(`src/PACKAGE.md`) and the root repository README (`README.md`) as part of every release.
+
+## The Shared Embedded README
+
+All four SDK packages embed the **same** README file: `src/PACKAGE.md`.
+
+Each project packs it identically:
+
+```xml
+<None Include="..\PACKAGE.md" Pack="true" PackagePath="\README.md" />
+<PackageReadmeFile>README.md</PackageReadmeFile>
+```
+
+Updating `src/PACKAGE.md` updates every package's nuget.org README at once.
+There are no per-package README files; `src/ModelContextProtocol.Core/README.md` and
+similar paths do not exist.
+
+## Checklist
+
+### 1. Package-list closure
+
+Every shipping SDK package must be listed in the packages section of `src/PACKAGE.md`,
+including packages introduced after the initial SDK launch and including the package
+being viewed in its own embedded README on nuget.org.
+
+Current packages to list:
+- `ModelContextProtocol.Core`
+- `ModelContextProtocol`
+- `ModelContextProtocol.AspNetCore`
+- `ModelContextProtocol.Extensions.Apps`
+
+Avoid counting phrases such as "three main packages" -- they become stale when packages
+are added. Use a non-counting closure such as "The SDK packages are:" instead.
+
+When a new package is introduced, add it to the list in both `src/PACKAGE.md` and the
+root `README.md` (see section below).
+
+### 2. Badge strategy
+
+Each package entry carries a nuget.org version badge. The correct badge endpoint depends
+on the release type:
+
+| Release type | Badge endpoint | Example |
+|---|---|---|
+| Prerelease series (e.g., `2.0.0-preview.*`) | `nuget/vpre/{package}` | `https://img.shields.io/nuget/vpre/ModelContextProtocol.svg` |
+| Stable release | `nuget/v/{package}` | `https://img.shields.io/nuget/v/ModelContextProtocol.svg` |
+
+`nuget/v` renders only the latest stable version and shows nothing (or a placeholder)
+during a prerelease-only series. `nuget/vpre` renders the latest version including
+prereleases. Switch all package badges together when the release type changes.
+
+Verify every badge in `src/PACKAGE.md` uses the correct endpoint for this release.
+
+### 3. Release-notes link
+
+`src/PACKAGE.md` must contain one statement linking to the release notes for the
+current version:
+
+```markdown
+See the [release notes](https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v{version})
+for what's new in this version.
+```
+
+Replace `{version}` with the exact version being released, including any prerelease
+suffix (e.g., `2.0.0-preview.2`).
+
+At prepare time the tag does not yet exist; the link is forward-referencing. The link
+resolves once the GitHub release is published during the publish-release step.
+
+Update this link for every release -- it must point to the tag being created, not a
+prior release.
+
+### 4. Root README.md sync
+
+The root `README.md` (the GitHub repo readme, NOT packed into packages) has its own
+package-list section. Keep it aligned with `src/PACKAGE.md`:
+- Same set of packages listed
+- Same non-counting closure phrasing
+- Badge strategy in `README.md` may also be updated for consistency, but the root
+  README is visible on GitHub (not nuget.org) so the badge choice is less critical
+
+## Salient content to review
+
+Beyond the structural checks above, read the current `src/PACKAGE.md` for any content
+that has become stale due to changes in this release:
+
+- Package descriptions (are they still accurate?)
+- Getting-started links (do they resolve and describe the current API?)
+- Code samples, if any (do they compile against the current SDK? see
+  [readme-snippets.md](readme-snippets.md))
+- Any version-specific notes from a prior release that should be removed or updated

.github/skills/prepare-release/references/readme-snippets.md

@@ -4,19 +4,23 @@ This reference describes how to validate that C# code samples in README files co
 
 ## Which READMEs to Validate
 
-Validate code samples from the **package README** files — these are shipped with NuGet packages and are the primary documentation users see:
+Validate code samples from the **package README** and the root repository README:
 
-| README | Package |
-|--------|---------|
-| `README.md` (root) | ModelContextProtocol |
-| `src/ModelContextProtocol.Core/README.md` | ModelContextProtocol.Core |
-| `src/ModelContextProtocol.AspNetCore/README.md` | ModelContextProtocol.AspNetCore |
+| README | Notes |
+|--------|-------|
+| `src/PACKAGE.md` | The single shared embedded README packed into every SDK package. This is the primary documentation users see on nuget.org. |
+| `README.md` (root) | The GitHub repository readme. Not packed into packages, but visible to developers browsing the repo. |
 
-Sample README files (`samples/*/README.md`) are excluded — the samples themselves are buildable projects and are validated by CI.
+All four SDK packages (`ModelContextProtocol.Core`, `ModelContextProtocol`,
+`ModelContextProtocol.AspNetCore`, `ModelContextProtocol.Extensions.Apps`) embed
+`src/PACKAGE.md` via their `.csproj` files. There are no per-package README files;
+paths such as `src/ModelContextProtocol.Core/README.md` do not exist.
+
+Sample README files (`samples/*/README.md`) are excluded -- the samples themselves are buildable projects and are validated by CI.
 
 ## What to Extract
 
-Extract only fenced code blocks tagged as `csharp` (` ```csharp `). Skip blocks tagged as plain ` ``` ` (shell commands, install instructions) or any other language.
+Extract only fenced code blocks tagged as `csharp` (` ```csharp `) from `src/PACKAGE.md` and `README.md`. Skip blocks tagged as plain ` ``` ` (shell commands, install instructions) or any other language.
 
 ### Handling Incomplete Snippets
 

.github/skills/publish-release/SKILL.md

@@ -69,14 +69,24 @@ Re-categorize all PRs in the commit range (including any new ones from Step 3).
 3. **Re-attribute** co-authors for any new PRs by harvesting `Co-authored-by` trailers from all commits in each PR.
 4. **Update acknowledgements** to include contributors from new PRs.
 
-### Step 5: Validate README Code Samples
+### Step 5: Review README and Validate Code Samples
 
-Verify that all C# code samples in the package README files compile against the current SDK at the merge commit. Follow the [README validation guide](../prepare-release/references/readme-snippets.md) for the full procedure.
+Re-run the README content checklist from [../prepare-release/references/readme-content.md](../prepare-release/references/readme-content.md) and validate code samples against the current SDK at the merge commit. Produce final suggestions before the release is created.
 
-1. Extract `csharp`-fenced code blocks from `README.md` and `src/PACKAGE.md`
-2. Create a temporary test project at `tests/ReadmeSnippetValidation/`
-3. Build and report results
-4. Delete the temporary project
+1. **Content checklist** -- Open `src/PACKAGE.md` and verify:
+   - **Package-list closure**: every shipping SDK package is listed. If a new package was introduced after prepare-release ran, it may be missing.
+   - **Badge strategy**: all badges use `nuget/vpre` for a prerelease or `nuget/v` for a stable release. Verify the badge style is correct for this release type.
+   - **Release-notes link**: the link points to `https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v{version}` for the tag being created. The tag is about to exist -- verify the URL is correct.
+   - **Root README.md sync**: confirm the root `README.md` package list is aligned.
+2. **Snippet validation** -- Extract `csharp`-fenced code blocks from `src/PACKAGE.md` and `README.md`, build the temporary test project, and report results. Follow [../prepare-release/references/readme-snippets.md](../prepare-release/references/readme-snippets.md) for the full procedure.
+3. **Delete** the temporary project after validation.
+
+If issues are found, present them to the user with proposed fixes. Any fixes must be applied as a separate commit before the draft release is created.
+
+**Edge Cases:**
+- **Stale package closure** -- A package introduced between prepare-release and now may not be listed. Add it to `src/PACKAGE.md` and `README.md`.
+- **Wrong badge style for the release type** -- Switch all badges together from `nuget/vpre` to `nuget/v` (or vice versa) if the prepare-release step used the wrong style.
+- **Missing or incorrect release-notes link** -- Correct the link to target the exact tag being created, including any prerelease suffix.
 
 ### Step 6: Review Sections
 

README.md

@@ -6,14 +6,16 @@ The official C# SDK for the [Model Context Protocol](https://modelcontextprotoco
 
 ## Packages
 
-This SDK consists of three main packages:
+The SDK packages are:
 
 - **[ModelContextProtocol.Core](https://www.nuget.org/packages/ModelContextProtocol.Core)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.Core.svg)](https://www.nuget.org/packages/ModelContextProtocol.Core) - For projects that only need to use the client or low-level server APIs and want the minimum number of dependencies.
 
 - **[ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol) - The main package with hosting and dependency injection extensions. References `ModelContextProtocol.Core`. This is the right fit for most projects that don't need HTTP server capabilities.
 
 - **[ModelContextProtocol.AspNetCore](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.AspNetCore.svg)](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore) - The library for HTTP-based MCP servers. References `ModelContextProtocol`.
 
+- **[ModelContextProtocol.Extensions.Apps](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.Extensions.Apps.svg)](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps) - MCP Apps extension for the .NET Model Context Protocol (MCP) SDK.
+
 ## Getting Started
 
 To get started, see the [Getting Started](https://csharp.sdk.modelcontextprotocol.io/concepts/getting-started.html) guide in the conceptual documentation for installation instructions, package-selection guidance, and complete examples for both clients and servers.

src/PACKAGE.md

@@ -1,18 +1,22 @@
 # MCP C# SDK
 
-[![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol)
+[![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol)
 
 The official C# SDK for the [Model Context Protocol](https://modelcontextprotocol.io/), enabling .NET applications, services, and libraries to implement and interact with MCP clients and servers. Please visit the [API documentation](https://csharp.sdk.modelcontextprotocol.io/api/ModelContextProtocol.html) for more details on available functionality.
 
+See the [release notes](https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v2.0.0-preview.1) for what's new in this version.
+
 ## Packages
 
-This SDK consists of three main packages:
+The SDK packages are:
+
+- **[ModelContextProtocol.Core](https://www.nuget.org/packages/ModelContextProtocol.Core)** [![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.Core.svg)](https://www.nuget.org/packages/ModelContextProtocol.Core) - For projects that only need to use the client or low-level server APIs and want the minimum number of dependencies.
 
-- **[ModelContextProtocol.Core](https://www.nuget.org/packages/ModelContextProtocol.Core)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.Core.svg)](https://www.nuget.org/packages/ModelContextProtocol.Core) - For projects that only need to use the client or low-level server APIs and want the minimum number of dependencies.
+- **[ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol)** [![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol) - The main package with hosting and dependency injection extensions. References `ModelContextProtocol.Core`. This is the right fit for most projects that don't need HTTP server capabilities.
 
-- **[ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol) - The main package with hosting and dependency injection extensions. References `ModelContextProtocol.Core`. This is the right fit for most projects that don't need HTTP server capabilities.
+- **[ModelContextProtocol.AspNetCore](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore)** [![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.AspNetCore.svg)](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore) - The library for HTTP-based MCP servers. References `ModelContextProtocol`.
 
-- **[ModelContextProtocol.AspNetCore](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.AspNetCore.svg)](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore) - The library for HTTP-based MCP servers. References `ModelContextProtocol`.
+- **[ModelContextProtocol.Extensions.Apps](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps)** [![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.Extensions.Apps.svg)](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps) - MCP Apps extension for the .NET Model Context Protocol (MCP) SDK.
 
 ## Getting Started