From 6e2f49984f9f6a0b153f0e69ae0648b0a59ffeb7 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 15:16:56 +0200
Subject: [PATCH 01/88] =?UTF-8?q?=E2=9C=A8=20add=20dotnet-docfx-digest=20s?=
 =?UTF-8?q?kill?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce new docfx documentation skill for validating and maintaining .NET public API documentation. Includes SKILL.md definition, bundled scripts for DocFX maintenance and compilation validation, evals for testing, and references for overwrite file guidance.
---
 skills/dotnet-docfx-digest/SKILL.md           |  603 ++++++++
 skills/dotnet-docfx-digest/evals/evals.json   |   78 +
 .../references/docfx-overwrite-files.md       |   45 +
 skills/dotnet-docfx-digest/scripts/README.md  |  110 ++
 skills/dotnet-docfx-digest/scripts/agents.cs  |  432 ++++++
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 1338 +++++++++++++++++
 6 files changed, 2606 insertions(+)
 create mode 100644 skills/dotnet-docfx-digest/SKILL.md
 create mode 100644 skills/dotnet-docfx-digest/evals/evals.json
 create mode 100644 skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
 create mode 100644 skills/dotnet-docfx-digest/scripts/README.md
 create mode 100644 skills/dotnet-docfx-digest/scripts/agents.cs
 create mode 100644 skills/dotnet-docfx-digest/scripts/docfx.cs

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
new file mode 100644
index 0000000..02f5a8e
--- /dev/null
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -0,0 +1,603 @@
+---
+name: dotnet-docfx-digest
+description: >
+  Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including repo-wide no-input audits, namespace overview pages, extension-member documentation, overwrite files, examples, availability notes, AGENTS.md maintenance, and verification. Use when the user asks to document a .NET API, create or update DocFX documentation, write namespace overview pages, add extension-method tables, update XML documentation comments, add API examples, maintain DocFX overwrite files, or verify documentation builds. Treat requests like "use dotnet-docfx-digest", "update the DocFX docs", "complete missing documentation", "create namespace pages", "add examples for this type", "update the extension members table", or "verify the documentation builds" as automatic triggers. Also use whenever public .NET API surface changes and documentation needs to stay aligned with source code.
+---
+
+# .NET DocFX Digest Steward
+
+## Description
+
+Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including namespace overview pages, extension-member documentation, overwrite files, examples, availability notes, and verification. Preserve manual edits, document public API only, require buildable copy/paste-ready examples for concrete APIs, and keep documentation aligned with actual source code and tests.
+
+## Activation Requirements
+
+This skill is autonomous by default. If the user invokes the skill without naming a namespace, type, member, or changed API, do not ask what to document first. Treat the request as a repo-wide DocFX documentation audit and repair task:
+
+1. Run the repository-instruction script.
+2. Inspect repository guidance, `docfx.json`, source projects, generated metadata, tests, samples, existing overwrite files, namespace pages, and availability includes.
+3. Run the validator to discover missing or stale complementary documentation.
+4. Fill the missing DocFX pieces that can be derived from source evidence.
+5. Ask a concise clarifying question only when inspection exposes a correctness-affecting choice that cannot be resolved from repository evidence.
+
+When this skill is invoked against a repository, the agent must run the deterministic repository-instruction script before completing the task:
+
+```bash
+dotnet run --file skills/dotnet-docfx-digest/scripts/agents.cs -- --repo-root .
+```
+
+Before reporting completion, the agent must run the deterministic validator:
+
+```bash
+dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root .
+```
+
+If either script cannot run, the agent must report the exact command, exit code, and failure output. Do not claim repository instructions or documentation were verified unless the scripts ran successfully.
+
+## Core Principles
+
+Documentation is part of the public contract. When changing public .NET APIs, the agent must update the corresponding documentation in the same change set. This includes XML documentation comments, DocFX overwrite files, namespace overview pages, examples, extension-method listings, and availability information.
+
+The documentation must reflect the actual code, not intended code. Do not invent APIs, overloads, target frameworks, behaviors, exceptions, or examples. Verify every documented claim against source code, tests, project files, generated metadata, or existing documentation.
+
+Manual documentation is authoritative context. Preserve existing manual edits unless they are factually incorrect. Prefer additive changes. When information is stale, update the stale portion while retaining nearby human-written explanations, tone, and structure.
+
+## Scope
+
+Apply this skill to:
+
+- Public .NET types,
+- Public constructors,
+- Public properties,
+- Public methods,
+- Public fields,
+- Public events,
+- Public delegates,
+- Public enums and enum members,
+- Public extension methods,
+- Public namespaces containing public API,
+- DocFX overwrite Markdown files,
+- DocFX namespace overview Markdown files,
+- XML documentation comments,
+- API examples,
+- availability includes or availability statements.
+
+Do not document:
+
+- Private types,
+- Internal types,
+- Private members,
+- Internal members,
+- Implementation-only helpers,
+- Test-only fixtures unless they are part of a documented public test-support API,
+- Namespaces that contain no public API.
+
+If a namespace contains only private or internal types, do not create a namespace overview page for it.
+
+## Repository Discovery
+
+Before editing documentation, locate the DocFX workspace.
+
+For Codebelt repositories, the DocFX workspace is always:
+
+```text
+.docfx
+```
+
+The DocFX configuration file is always:
+
+```text
+.docfx/docfx.json
+```
+
+For other repositories, locate `docfx.json` before making DocFX-specific changes.
+
+Inspect `docfx.json` to understand:
+
+- Content roots,
+- API metadata inputs,
+- Overwrite file locations,
+- Include file locations,
+- Resource paths,
+- Output conventions.
+
+Do not assume paths beyond the repository's actual DocFX configuration, except for Codebelt repositories where `.docfx/docfx.json` is the convention.
+
+When creating or repairing overwrite files, read `references/docfx-overwrite-files.md` for the DocFX overwrite and `docfx.json` rules that matter most to agents.
+
+## AGENTS.md Maintenance
+
+Persistent repository guidance is enforced by script, not by AI memory. When this skill is invoked, run:
+
+```bash
+dotnet run --file skills/dotnet-docfx-digest/scripts/agents.cs -- --repo-root .
+```
+
+The script must create or update a marker-bounded DocFX documentation maintenance section in the repository root `AGENTS.md`. Do not manually duplicate this section. If the script fails, report the failure and do not claim `AGENTS.md` was updated.
+
+## Public API Rule
+
+Only public API is documented. Before adding or updating documentation, determine whether the item is public from source code or generated metadata.
+
+A type is documentable only when it is externally visible. A member is documentable only when it is public and belongs to a documentable public type.
+
+Do not add documentation pages for namespaces that contain no public types. Do not add extension-method documentation for non-public extension methods.
+
+## Required Documentation Updates
+
+When a public API is added or materially changed, update all relevant documentation surfaces:
+
+1. XML documentation comments in source code.
+2. DocFX overwrite files when manual API documentation exists or is needed.
+3. Namespace overview page.
+4. Extension members table when extension methods are involved.
+5. Availability information.
+6. At least one usage example unless the documented item is an abstraction.
+7. Verification artifacts or commands proving the documentation remains buildable and accurate.
+
+A "material change" includes:
+
+- New public API,
+- Removed public API,
+- Changed public signature,
+- Changed behavior,
+- Changed exception behavior,
+- Changed generic constraints,
+- Changed nullability contract,
+- Changed target framework availability,
+- Changed platform availability,
+- Changed extension-method availability,
+- Changed obsolete/deprecation status,
+- Changed default values,
+- Changed thread-safety or lifecycle expectations.
+
+## Examples Are Mandatory
+
+Every automatically documented concrete public type or concrete public member must include at least one example showing how to use it.
+
+An example may be omitted only when the item is an abstraction, such as:
+
+- Interface,
+- Abstract class,
+- Abstract member,
+- Attribute intended only for framework discovery,
+- Marker type with no direct usage,
+- Pure contract type where concrete usage belongs on implementations.
+
+When omitting an example for an abstraction, the documentation must make that reason clear.
+
+Preferred source for examples:
+
+1. Existing unit tests,
+2. Existing functional tests,
+3. Existing integration tests,
+4. Existing samples,
+5. Minimal new sample derived from actual public API behavior.
+
+Examples derived from tests must be converted into real-life usage. Do not paste raw assertion-heavy test code as documentation unless the documentation is specifically explaining testing. Convert Arrange/Act/Assert test structure into developer-oriented sample code.
+
+The example must be:
+
+- Realistic,
+- Minimal,
+- Deterministic,
+- Copy/paste-ready,
+- Buildable in a normal consuming project,
+- Free of hidden repository-specific helpers unless those helpers are also public and documented,
+- Free of pseudo-code,
+- Free of ellipses inside code blocks,
+- Free of unexplained magic values,
+- Valid for the documented target framework availability.
+
+Bad example pattern:
+
+```csharp
+// Arrange
+var sut = new Foo();
+
+// Act
+var actual = sut.Bar();
+
+// Assert
+Assert.Equal("baz", actual);
+```
+
+Preferred documentation pattern:
+
+```csharp
+using My.Library;
+
+var formatter = new Foo();
+string value = formatter.Bar();
+Console.WriteLine(value);
+```
+
+If assertions are useful, use them only when the sample is explicitly framed as a test sample and can compile in that test context.
+
+## Example Verification
+
+Every code sample added or changed must be verified. A C# code sample must compile.
+
+The deterministic validator compiles C# documentation samples as .NET 10 file-based apps. Run:
+
+```bash
+dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root .
+```
+
+A sample may opt out only when the code fence includes:
+
+```csharp
+// dotnet-docfx-digest:skip-compile - <reason>
+```
+
+The reason is mandatory. Do not use silent opt-outs.
+
+Do not claim a sample compiles unless the validator or an equivalent repository verification command has compiled it successfully.
+
+## Namespace Overview Pages
+
+Every namespace containing public API must have a namespace overview Markdown page.
+
+The namespace overview page must be named after the namespace:
+
+```text
+X.Y.Z.md
+```
+
+The page must live in the appropriate DocFX documentation folder for namespace overwrite/custom content. For Codebelt repositories, place namespace overview pages under the `.docfx` documentation structure according to the existing repository layout.
+
+The namespace page must use DocFX overwrite front matter with the namespace UID:
+
+```markdown
+---
+uid: X.Y.Z
+summary: *content
+---
+```
+
+The page must provide a developer-friendly fly-in explaining what the namespace is for. The fly-in should be similar in usefulness and tone to Microsoft .NET API documentation:
+
+- Start with what the namespace contains.
+- Explain the developer problem it solves.
+- Explain when to use it.
+- Mention important concepts or type families.
+- Avoid marketing language.
+- Avoid restating type names without explaining purpose.
+- Keep the explanation accurate to the public API.
+
+Minimum namespace overview structure:
+
+```markdown
+---
+uid: X.Y.Z
+summary: *content
+---
+The `X.Y.Z` namespace contains types that ...
+
+[!INCLUDE [availability-default](../../includes/availability-default.md)]
+```
+
+If the namespace contains extension methods, include an `Extension Members` section.
+
+## Extension Method Documentation
+
+Extension methods must be documented at namespace level.
+
+If any public type exposes public extension members in namespace `X.Y.Z`, then the DocFX documentation must include:
+
+```text
+X.Y.Z.md
+```
+
+This file must contain an `Extension Members` section. The section must list public extension methods exposed by that namespace.
+
+Required table format:
+
+```markdown
+### Extension Members
+
+|Type|Ext|Methods|
+|--:|:-:|---|
+|ITestOutputHelper|⬇️|`WriteLines`|
+|String|⬇️|`ReplaceLineEndings` (TFM netstandard2.0)|
+```
+
+Rules for the table:
+
+- `Type` is the extended type, not the static extension class.
+- `Ext` must use `⬇️`.
+- `Methods` lists public extension methods.
+- Use backticks around method names.
+- Include TFM-specific availability when a method is conditional.
+- Group overloads under the same method name unless overload distinction is essential.
+- Do not include internal/private extension methods.
+- Do not include extension classes as the primary documentation target unless the class itself has relevant public API beyond extension methods.
+
+Example:
+
+```markdown
+### Extension Members
+
+|Type|Ext|Methods|
+|--:|:-:|---|
+|String|⬇️|`ToSlug`, `NormalizeLineEndings`|
+|IEnumerable<T>|⬇️|`ForEach`, `Batch`|
+```
+
+## Availability Documentation
+
+Availability information must be present for public API documentation.
+
+Availability can be documented in either of two ways:
+
+1. By referencing an existing include file.
+2. By writing explicit availability text when no suitable include exists.
+
+Prefer include files when the repository has an `includes` folder with Markdown files that define availability.
+
+Example include:
+
+```markdown
+[!INCLUDE [availability-default](../../includes/availability-default.md)]
+```
+
+Example explicit availability:
+
+```markdown
+Availability: .NET 10, .NET 9 and .NET Standard 2.0.
+```
+
+If a suitable include exists, reference it instead of duplicating availability text. If no suitable include exists, explicit availability is acceptable.
+
+Do not add redundant availability text if the page already references an availability include that covers the same API surface.
+
+When availability differs by type, member, target framework, or platform, document the difference close to the affected item.
+
+Availability must reflect actual project files, conditional compilation, target frameworks, package metadata, and source code.
+
+## DocFX Overwrite Files
+
+Use DocFX overwrite files to modify or add content for generated API items without editing generated metadata directly.
+
+Overwrite files must include YAML front matter with the target `uid`. Example:
+
+```markdown
+---
+uid: X.Y.Z.MyType
+summary: *content
+---
+```
+
+The `uid` must match the generated DocFX UID. Do not guess UIDs. Verify them from generated metadata, existing API pages, source conventions, or DocFX output.
+
+Use overwrite files for:
+
+- Namespace overview pages,
+- Additional conceptual remarks,
+- Examples,
+- Corrected summaries,
+- Extension-method namespace documentation,
+- Availability notes,
+- Developer-oriented usage guidance.
+
+Do not use overwrite files to conceal inaccurate XML documentation. Correct the source XML documentation when it is wrong.
+
+## XML Documentation Comments
+
+Public API should have useful XML documentation comments. Prefer concise source-level XML comments and richer examples/remarks in DocFX overwrite files when documentation becomes long.
+
+XML documentation should describe:
+
+- Purpose,
+- Parameters,
+- Return value,
+- Exceptions,
+- Type parameters,
+- Important behavior,
+- Nullability expectations,
+- Thread-safety or lifecycle behavior when relevant.
+
+Do not use empty boilerplate summaries.
+
+Bad:
+
+```csharp
+/// <summary>
+/// Gets or sets the value.
+/// </summary>
+```
+
+Better:
+
+```csharp
+/// <summary>
+/// Gets or sets the normalized name used when matching configuration keys.
+/// </summary>
+```
+
+## Preservation Rules
+
+Manual edits must be preserved.
+
+Before editing an existing Markdown file:
+
+1. Read the entire file.
+2. Identify manually written sections.
+3. Preserve structure and tone where possible.
+4. Add new information in the most appropriate existing section.
+5. Avoid replacing the whole file unless the file is clearly generated or corrupt.
+6. Keep existing includes, admonitions, links, and examples unless they are stale.
+7. Update stale statements instead of appending contradictory new statements.
+
+Documentation must stay current. If additive-only editing would leave conflicting or stale information, update the stale information. Accuracy is more important than blindly appending content. Never leave two conflicting descriptions of the same API behavior.
+
+## Style Rules
+
+Use developer-friendly documentation style.
+
+Prefer:
+
+- Direct explanations,
+- Practical examples,
+- Concrete behavior,
+- Accurate terminology,
+- Small complete samples,
+- Links to related APIs when useful,
+- Namespace-level fly-ins that explain purpose.
+
+Avoid:
+
+- Marketing language,
+- Placeholder text,
+- "Simply",
+- "Just",
+- "Obviously",
+- Pseudo-code,
+- Incomplete snippets,
+- Unverified claims,
+- Duplicating generated API signatures manually,
+- Restating the namespace name without explaining its purpose.
+
+## Documentation Workflow
+
+When the user names a changed API or namespace:
+
+1. Run `agents.cs`.
+2. Inspect the changed public API.
+3. Determine affected namespaces.
+4. Determine whether public extension methods are involved.
+5. Locate `.docfx/docfx.json` or repository-specific DocFX config.
+6. Locate existing overwrite files and namespace pages.
+7. Locate availability include files.
+8. Locate relevant tests that demonstrate the API.
+9. Convert test usage into real-life documentation examples.
+10. Update XML documentation where needed.
+11. Update or create namespace overview pages.
+12. Update extension-member tables.
+13. Update or create overwrite files.
+14. Preserve manual edits.
+15. Run `dotnet build`.
+16. Run `dotnet test`.
+17. Run `docfx .docfx/docfx.json`.
+18. Run `docfx.cs`.
+19. Report verification results.
+
+When no specific API or namespace is named:
+
+1. Run `agents.cs`.
+2. Read repository guidance, especially root `AGENTS.md`.
+3. Locate `.docfx/docfx.json` or repository-specific DocFX config.
+4. Read `references/docfx-overwrite-files.md`.
+5. Run `dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --json` to collect deterministic missing-doc findings when the repository is buildable.
+6. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
+7. Determine every namespace containing public API and whether each namespace exposes public extension methods.
+8. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
+9. Add or repair `Extension Members` tables for namespaces with public extension methods.
+10. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
+11. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+12. Run `dotnet build`.
+13. Run `dotnet test`.
+14. Run `docfx .docfx/docfx.json`.
+15. Run `docfx.cs`.
+16. Report verification results and any remaining findings.
+
+## Namespace Page Template
+
+Use this template when creating a new namespace overview page:
+
+```markdown
+---
+uid: X.Y.Z
+summary: *content
+---
+The `X.Y.Z` namespace contains types that ...
+
+[!INCLUDE [availability-default](../../includes/availability-default.md)]
+
+### Extension Members
+
+|Type|Ext|Methods|
+|--:|:-:|---|
+|String|⬇️|`ExampleMethod`|
+```
+
+Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path based on the actual file location.
+
+## Type Example Template
+
+Use this shape for concrete public type examples:
+
+````markdown
+### Examples
+
+The following example shows how to use `MyType` in a consuming application.
+
+```csharp
+using X.Y.Z;
+
+var value = new MyType();
+Console.WriteLine(value);
+```
+````
+
+The sample must compile. Do not include `using` directives for namespaces that do not exist. Do not use APIs that are internal to the repository unless the sample is explicitly for contributors and not public API consumers.
+
+## Extension Method Example Template
+
+Use this shape for extension-method examples:
+
+````markdown
+### Examples
+
+The following example shows how to call `NormalizeLineEndings` on a string.
+
+```csharp
+using X.Y.Z;
+
+string text = "first\r\nsecond";
+string normalized = text.NormalizeLineEndings();
+Console.WriteLine(normalized);
+```
+````
+
+The namespace containing the extension method must be imported. The sample must compile in a consuming project.
+
+## Verification Checklist
+
+Before completing documentation work, verify:
+
+- [ ] `agents.cs` has run successfully.
+- [ ] `AGENTS.md` contains the managed DocFX documentation maintenance block.
+- [ ] Only public API is documented.
+- [ ] Every namespace with public API has a namespace overview page.
+- [ ] Namespaces with public extension methods have an `Extension Members` section.
+- [ ] Extension methods are documented by extended type, not extension class.
+- [ ] Concrete public APIs have at least one example.
+- [ ] Abstractions without examples have a clear reason.
+- [ ] Examples are realistic and copy/paste-ready.
+- [ ] Examples compile.
+- [ ] Examples are preferably derived from passing tests.
+- [ ] Availability is included or explicitly stated.
+- [ ] Availability matches actual target frameworks and conditions.
+- [ ] Existing manual edits are preserved.
+- [ ] Stale documentation is corrected.
+- [ ] No contradictory documentation remains.
+- [ ] `dotnet build` has been run or the failure is reported.
+- [ ] `dotnet test` has been run or the failure is reported.
+- [ ] `docfx .docfx/docfx.json` has been run or the failure is reported.
+- [ ] `docfx.cs` has run successfully or the failure is reported.
+
+## Completion Response
+
+When reporting completion, include:
+
+- Public APIs documented,
+- Namespace pages added or updated,
+- Extension-member tables added or updated,
+- Examples added and their source test/sample when applicable,
+- Availability handling,
+- `AGENTS.md` created, updated, already compliant, or failed,
+- Verification commands run,
+- Any verification failures or skipped checks.
+
+Do not claim documentation was verified unless the relevant command actually ran successfully.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
new file mode 100644
index 0000000..cf10fa9
--- /dev/null
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -0,0 +1,78 @@
+{
+  "skill_name": "dotnet-docfx-digest",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just added a new public class `RetryPolicy` and a public extension method `WithRetry(this HttpClient client, int attempts)` to my .NET library in the `Acme.Net.Http` namespace. Please update the DocFX documentation for this change.",
+      "expected_output": "Agent runs scripts/agents.cs to seed AGENTS.md, creates/updates the Acme.Net.Http namespace overview page with uid front matter, a fly-in, availability, and an Extension Members table listing the extended type with the WithRetry method, adds a buildable example for RetryPolicy, and runs scripts/docfx.cs to verify.",
+      "expectations": [
+        "Runs the deterministic scripts/agents.cs against the repository before completing",
+        "Creates or updates a namespace overview page named Acme.Net.Http.md with DocFX overwrite front matter whose uid matches the namespace",
+        "Adds an Extension Members table documenting the extended type (HttpClient), the ⬇️ marker, and the WithRetry method in backticks",
+        "Adds at least one copy/paste-ready, buildable example for the concrete RetryPolicy type",
+        "Includes availability information via an include or explicit Availability text",
+        "Runs scripts/docfx.cs to verify before claiming the documentation was verified"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Document the new `internal` helper class `BufferPool` and the `private` method `Rent` I added under `Acme.Buffers`. There is no other public type in that namespace yet.",
+      "expected_output": "Agent declines to create documentation for internal/private members and does not create a namespace overview page for a namespace that contains no public API, explaining the public-API-only rule.",
+      "expectations": [
+        "Does not create documentation pages or overwrite files for internal or private members",
+        "Does not create a namespace overview page for Acme.Buffers because it contains no public API",
+        "Explains that only public API is documented and points to the public-API rule",
+        "Does not fabricate public API that does not exist"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Add a usage example to the `Acme.Text` namespace page for the `Greeter` class. Base it on the existing unit test `GreeterTest.Greet_WithName_ReturnsGreeting`.",
+      "expected_output": "Agent converts the Arrange/Act/Assert test into a real-life consumer-oriented, buildable example without raw assertions, and verifies it compiles with scripts/docfx.cs.",
+      "expectations": [
+        "Derives the example from the referenced test rather than inventing behavior",
+        "Converts the Arrange/Act/Assert structure into developer-oriented usage instead of pasting raw assertions",
+        "Produces a minimal, deterministic, copy/paste-ready C# example with a real using directive for Acme.Text",
+        "Avoids pseudo-code, ellipses, and hidden helpers in the sample",
+        "Verifies the sample compiles via scripts/docfx.cs or an equivalent build command"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Run the DocFX documentation validator on this repository and tell me whether the docs are in good shape.",
+      "expected_output": "Agent runs scripts/docfx.cs (and scripts/agents.cs if needed), reports the exact command, exit code, and the deterministic JSON/console findings, and does not claim verification without running the script.",
+      "expectations": [
+        "Runs scripts/docfx.cs against the repository root",
+        "Reports the exact command run and its exit code",
+        "Surfaces the deterministic findings (errors/warnings with their codes) rather than guessing",
+        "Does not claim the documentation was verified unless the script actually ran successfully"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "The `Acme.Text` namespace page already has a hand-written introduction and a couple of links I care about. I changed the `Shout` extension method to also trim whitespace. Update the docs but keep my wording.",
+      "expected_output": "Agent preserves the manual introduction and links, updates only the stale parts relevant to the behavior change, keeps the Extension Members table accurate, and avoids wholesale file replacement.",
+      "expectations": [
+        "Preserves the existing hand-written introduction and links instead of replacing the whole file",
+        "Updates only the stale portions affected by the behavior change",
+        "Keeps the Extension Members table accurate for the Shout method",
+        "Does not leave contradictory descriptions of the Shout behavior",
+        "Re-verifies any changed sample compiles"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Use dotnet-docfx-digest on this repository.",
+      "expected_output": "Agent treats the request as a repo-wide DocFX documentation audit instead of asking what to document first. It runs scripts/agents.cs, inspects AGENTS.md, docfx.json, source projects, public API, tests, samples, overwrite files, namespace pages, and availability includes, runs scripts/docfx.cs to collect deterministic findings, repairs missing complementary DocFX documentation that can be derived from source evidence, reads the DocFX overwrite reference when creating or repairing overwrite files, and asks for clarification only if discovery exposes a correctness-affecting choice.",
+      "expectations": [
+        "Does not start by asking the user which API or namespace to document",
+        "Runs scripts/agents.cs to ensure the repository AGENTS.md contains the managed DocFX maintenance block",
+        "Inspects docfx.json and existing DocFX overwrite, namespace, include, source, test, and sample evidence before editing",
+        "Runs scripts/docfx.cs, preferably with --json when collecting repo-wide findings",
+        "Creates or updates missing namespace overview pages, Extension Members tables, examples, and availability notes that can be derived from evidence",
+        "Reads references/docfx-overwrite-files.md before creating or repairing DocFX overwrite files",
+        "Asks a concise clarifying question only after inspection finds a correctness-affecting unresolved choice"
+      ]
+    }
+  ]
+}
diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
new file mode 100644
index 0000000..13538ae
--- /dev/null
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -0,0 +1,45 @@
+# DocFX Overwrite Files Reference
+
+Use this reference when creating, auditing, or repairing DocFX overwrite files for .NET API documentation.
+
+Sources:
+
+- https://dotnet.github.io/docfx/tutorial/intro_overwrite_files.html
+- https://dotnet.github.io/docfx/reference/docfx-json-reference.html#overwrite
+
+## Agent Summary
+
+DocFX treats generated API metadata and Markdown content as models. An overwrite file is a Markdown file that updates a model by matching its `uid`; this lets documentation add or replace properties such as `summary`, `remarks`, examples, conceptual content, and namespace-level guidance without editing generated metadata.
+
+Every overwrite section starts with YAML front matter delimited by `---`. The front matter must include `uid`, and the value must match the generated model UID. Do not guess UIDs. Verify them from generated metadata, existing API pages, source conventions, DocFX output, or `docfx build --exportRawModel`.
+
+The `*content` anchor maps the Markdown body following the YAML header into a chosen model property. For this skill, namespace overview pages normally use:
+
+```markdown
+---
+uid: X.Y.Z
+summary: *content
+---
+The `X.Y.Z` namespace contains types that ...
+```
+
+If `*content` is not used, DocFX assigns the Markdown body to the default conceptual content property. Prefer `summary: *content` for namespace fly-ins and other summary replacements that should flow into generated API pages.
+
+DocFX applies overwrite models by `uid`. If the same `uid` appears more than once in one overwrite file, later sections in that same file override earlier sections. Across different overwrite files, ordering is not deterministic, so keep competing sections for the same `uid` together or consolidate them.
+
+Overwrite models should follow the target model shape. Existing properties can be replaced or merged depending on the DocFX model rules; properties not already present can be added. For managed reference docs, common useful overwrite targets include `summary`, `remarks`, `example`, `exceptions`, `see`, `seealso`, and parameter descriptions under `syntax`.
+
+The `build.overwrite` entry in `docfx.json` tells DocFX which conceptual Markdown files contain overwrite sections. All relative paths in `docfx.json` are resolved relative to the directory containing `docfx.json`, not necessarily the repository root.
+
+When a repository has no obvious overwrite location, inspect `docfx.json` first. Look at `build.content`, `build.overwrite`, `metadata.dest`, include paths, and existing Markdown layout before deciding where a new namespace page belongs.
+
+## Practical Rules
+
+- Run `agents.cs` before finishing so root `AGENTS.md` receives persistent DocFX maintenance guidance.
+- Use overwrite files to complement generated API metadata, not to hide incorrect XML documentation.
+- Correct bad XML comments at source when the generated summary is wrong.
+- Use namespace overview pages for namespace fly-ins and extension-member tables.
+- Keep examples and remarks close to the API item or namespace they explain.
+- Preserve existing hand-written overwrite sections unless they are stale or contradictory.
+- Prefer additive edits, but remove or revise contradictions.
+- Re-run `docfx.cs` after edits so missing namespace pages, extension tables, availability, and sample compilation are checked deterministically.
diff --git a/skills/dotnet-docfx-digest/scripts/README.md b/skills/dotnet-docfx-digest/scripts/README.md
new file mode 100644
index 0000000..a65f2c7
--- /dev/null
+++ b/skills/dotnet-docfx-digest/scripts/README.md
@@ -0,0 +1,110 @@
+# dotnet-docfx-digest scripts
+
+Two deterministic .NET 10 file-based apps back the skill so that repository
+guidance and documentation rules are enforced by code, not by AI memory. Each
+script is a single `.cs` file with no `.csproj` and runs directly:
+
+```bash
+dotnet run --file <script>.cs -- <arguments>
+dotnet build <script>.cs
+```
+
+Both declare `#:property TargetFramework=net10.0` and `#:property PublishAot=false`,
+return deterministic exit codes, and emit machine-readable JSON with `--json`.
+
+## agents.cs
+
+Ensures the repository root `AGENTS.md` contains a marker-bounded DocFX
+documentation-maintenance block. Idempotent: running it repeatedly never
+duplicates the block. Content outside the markers is preserved, the host file's
+line endings are respected, and new files are written as UTF-8 without a BOM.
+
+```bash
+dotnet run --file agents.cs -- --repo-root .            # write (default)
+dotnet run --file agents.cs -- --repo-root . --check    # CI enforcement
+dotnet run --file agents.cs -- --repo-root . --dry-run  # preview
+dotnet run --file agents.cs -- --repo-root . --json     # machine-readable
+```
+
+Markers:
+
+```markdown
+<!-- dotnet-docfx-digest:start -->
+<!-- dotnet-docfx-digest:end -->
+```
+
+If both markers exist, only the content between them (inclusive) is replaced.
+If neither exists, the block is appended. If exactly one marker exists, the file
+is treated as corrupt and the script exits non-zero.
+
+Exit codes:
+
+| Code | Meaning |
+|-----:|---------|
+| 0 | Success; file already compliant or successfully updated |
+| 1 | Validation failed in `--check` mode |
+| 2 | Invalid arguments |
+| 3 | Repository root does not exist |
+| 4 | `AGENTS.md` contains a corrupt managed block |
+| 5 | Write failed |
+
+## docfx.cs
+
+Validates the deterministic documentation requirements against the *compiled*
+repository, not against text in `SKILL.md`. It builds the solution, discovers
+public API from compiled assemblies (preferring reference assemblies) via
+`System.Reflection.MetadataLoadContext`, then checks namespace overview pages,
+extension-member tables, availability, and compiles every C# documentation
+sample as a file-based app.
+
+```bash
+dotnet run --file docfx.cs -- --repo-root .
+dotnet run --file docfx.cs -- --repo-root . --json
+dotnet run --file docfx.cs -- --repo-root . --no-validate-samples
+dotnet run --file docfx.cs -- --repo-root . --changed-only
+dotnet run --file docfx.cs -- --repo-root . --configuration Debug --framework net10.0
+```
+
+Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`),
+`--framework`, `--validate-samples` / `--no-validate-samples` (default on),
+`--changed-only`, `--json`, `--help`.
+
+Exit codes:
+
+| Code | Meaning |
+|-----:|---------|
+| 0 | Validation passed |
+| 1 | Validation failed |
+| 2 | Invalid arguments |
+| 3 | Repository root does not exist |
+| 4 | DocFX configuration file not found |
+| 5 | Build failed |
+| 6 | Public API discovery failed |
+| 7 | Sample compilation failed |
+| 8 | Unexpected internal error |
+
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`,
+`DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`,
+`NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`,
+`NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`,
+`EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`,
+`SAMPLE_COMPILE_FAILED`, and `SAMPLE_SKIP_REASON_MISSING`.
+
+### Sample opt-out
+
+A C# fence may opt out of compilation only with a mandatory reason:
+
+```csharp
+// dotnet-docfx-digest:skip-compile - requires a configured database connection
+```
+
+A skip marker without a reason is reported as `SAMPLE_SKIP_REASON_MISSING`.
+
+### Extension-method detection note
+
+Extension methods are detected from compiled metadata: a public static method,
+carrying `System.Runtime.CompilerServices.ExtensionAttribute`, declared on a
+public static non-generic class, with at least one parameter. The first
+parameter's type is recorded as the extended type. (The C# compiler marks the
+method — not the first parameter — with `ExtensionAttribute`, so detection keys
+off the method attribute to match real metadata.)
diff --git a/skills/dotnet-docfx-digest/scripts/agents.cs b/skills/dotnet-docfx-digest/scripts/agents.cs
new file mode 100644
index 0000000..20ccc97
--- /dev/null
+++ b/skills/dotnet-docfx-digest/scripts/agents.cs
@@ -0,0 +1,432 @@
+#:property TargetFramework=net10.0
+#:property Nullable=enable
+#:property LangVersion=latest
+#:property PublishAot=false
+
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+return AgentsScript.Run(args);
+
+internal static class AgentsScript
+{
+    private const string ScriptId = "ensure-agents-docfx-digest";
+    private const string AgentsFileName = "AGENTS.md";
+    private const string StartMarker = "<!-- dotnet-docfx-digest:start -->";
+    private const string EndMarker = "<!-- dotnet-docfx-digest:end -->";
+
+    private static readonly Encoding Utf8NoBom = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);
+
+    // Canonical managed block content. Stored with LF line endings; rendered with the
+    // host file's detected line ending at write time. Begins with StartMarker and ends
+    // with EndMarker so the prefix/suffix of the host file is preserved exactly.
+    private const string ManagedBlock =
+        """
+        <!-- dotnet-docfx-digest:start -->
+        ## DocFX Documentation Maintenance
+
+        When changing public .NET APIs, keep the DocFX documentation current in the same change set.
+
+        Documentation updates must cover public API only. Do not document private or internal types or members. Do not create namespace overview pages for namespaces that contain no public API.
+
+        For concrete public APIs, include at least one realistic, copy/paste-ready usage example unless the item is an abstraction. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage.
+
+        All added or changed code samples must be deterministic and verified to compile. Do not add pseudo-code, ellipses, hidden test helpers, or examples that rely on unverified behavior.
+
+        Every namespace containing public API must have a DocFX namespace overview page named after the namespace, such as `X.Y.Z.md`, using DocFX overwrite front matter with the namespace `uid`.
+
+        Namespaces exposing public extension methods must document those extension members at namespace level. The namespace page must include an `Extension Members` table listing the extended type, the extension marker, and the public extension methods.
+
+        Availability must be documented by referencing the appropriate include file when one exists, or by adding explicit availability text when no suitable include exists. Availability must reflect the actual target frameworks, conditional compilation, and project configuration.
+
+        Preserve manual documentation edits. Prefer additive changes, but correct stale or contradictory information so documentation remains accurate.
+
+        Before completing documentation work, run the relevant verification commands, normally:
+
+        ```bash
+        dotnet build
+        dotnet test
+        docfx .docfx/docfx.json
+        dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root .
+        ```
+
+        If a command cannot be run, report the exact limitation or failure instead of claiming the documentation was verified.
+        <!-- dotnet-docfx-digest:end -->
+        """;
+
+    public static int Run(string[] args)
+    {
+        var options = new Options();
+        try
+        {
+            if (!TryParse(args, options, out var parseError, out var wantHelp))
+            {
+                if (wantHelp)
+                {
+                    PrintUsage(Console.Out);
+                    return 0;
+                }
+
+                return Fail(options.Json, ExitCode.InvalidArguments, "failed", parseError, options);
+            }
+
+            if (options.Help)
+            {
+                PrintUsage(Console.Out);
+                return 0;
+            }
+        }
+        catch (Exception ex)
+        {
+            Console.Error.WriteLine($"{ScriptId}: argument parsing failed: {ex.Message}");
+            return (int)ExitCode.InvalidArguments;
+        }
+
+        string repoRoot;
+        try
+        {
+            repoRoot = Path.GetFullPath(string.IsNullOrWhiteSpace(options.RepoRoot) ? "." : options.RepoRoot);
+        }
+        catch (Exception ex)
+        {
+            return Fail(options.Json, ExitCode.RepoRootMissing, "failed", $"Invalid repository root: {ex.Message}", options);
+        }
+
+        options.ResolvedRepoRoot = repoRoot;
+
+        if (!Directory.Exists(repoRoot))
+        {
+            return Fail(options.Json, ExitCode.RepoRootMissing, "failed", $"Repository root does not exist: {repoRoot}", options);
+        }
+
+        var agentsPath = Path.Combine(repoRoot, AgentsFileName);
+        options.AgentsPath = agentsPath;
+
+        string? existing = null;
+        if (File.Exists(agentsPath))
+        {
+            try
+            {
+                existing = File.ReadAllText(agentsPath);
+            }
+            catch (Exception ex)
+            {
+                return Fail(options.Json, ExitCode.WriteFailed, "failed", $"Unable to read {AgentsFileName}: {ex.Message}", options);
+            }
+        }
+
+        var eol = DetectLineEnding(existing);
+        var renderedBlock = RenderBlock(eol);
+
+        // Locate markers and reject a corrupt (single-marker or out-of-order) block.
+        int startIdx = existing?.IndexOf(StartMarker, StringComparison.Ordinal) ?? -1;
+        int endIdx = existing?.IndexOf(EndMarker, StringComparison.Ordinal) ?? -1;
+
+        bool hasStart = startIdx >= 0;
+        bool hasEnd = endIdx >= 0;
+
+        if (hasStart ^ hasEnd)
+        {
+            return Fail(options.Json, ExitCode.CorruptBlock, "failed",
+                $"{AgentsFileName} contains a corrupt managed block: only one of the start/end markers was found.", options);
+        }
+
+        if (hasStart && hasEnd && startIdx > endIdx)
+        {
+            return Fail(options.Json, ExitCode.CorruptBlock, "failed",
+                $"{AgentsFileName} contains a corrupt managed block: the end marker appears before the start marker.", options);
+        }
+
+        string newContent;
+        bool fileMissing = existing is null;
+        if (hasStart && hasEnd)
+        {
+            var prefix = existing!.Substring(0, startIdx);
+            var suffix = existing.Substring(endIdx + EndMarker.Length);
+            newContent = prefix + renderedBlock + suffix;
+        }
+        else if (fileMissing)
+        {
+            newContent = renderedBlock + eol;
+        }
+        else
+        {
+            var baseText = existing!;
+            if (baseText.Length == 0)
+            {
+                newContent = renderedBlock + eol;
+            }
+            else
+            {
+                if (!baseText.EndsWith("\n", StringComparison.Ordinal))
+                {
+                    baseText += eol;
+                }
+
+                baseText += eol;
+                newContent = baseText + renderedBlock + eol;
+            }
+        }
+
+        bool changed = fileMissing || !string.Equals(existing, newContent, StringComparison.Ordinal);
+
+        // CHECK: read-only CI enforcement.
+        if (options.Mode == RunMode.Check)
+        {
+            if (!changed)
+            {
+                return Done(options, ExitCode.Success, "unchanged", false,
+                    $"{AgentsFileName} already contains an up-to-date managed block.");
+            }
+
+            var status = fileMissing ? "would-create" : "would-update";
+            var msg = fileMissing
+                ? $"{AgentsFileName} is missing and would be created."
+                : $"{AgentsFileName} managed block is stale and would be updated.";
+            return Done(options, ExitCode.ValidationFailed, status, true, msg);
+        }
+
+        // DRY-RUN: report intended action without writing.
+        if (options.Mode == RunMode.DryRun)
+        {
+            if (!changed)
+            {
+                return Done(options, ExitCode.Success, "unchanged", false,
+                    $"{AgentsFileName} already contains an up-to-date managed block.");
+            }
+
+            var status = fileMissing ? "would-create" : "would-update";
+            var msg = fileMissing
+                ? $"{AgentsFileName} would be created with the managed block."
+                : $"{AgentsFileName} managed block would be updated.";
+            return Done(options, ExitCode.Success, status, true, msg);
+        }
+
+        // WRITE: persist changes.
+        if (!changed)
+        {
+            return Done(options, ExitCode.Success, "unchanged", false,
+                $"{AgentsFileName} already contains an up-to-date managed block.");
+        }
+
+        try
+        {
+            File.WriteAllText(agentsPath, newContent, Utf8NoBom);
+        }
+        catch (Exception ex)
+        {
+            return Fail(options.Json, ExitCode.WriteFailed, "failed", $"Failed to write {AgentsFileName}: {ex.Message}", options);
+        }
+
+        var writeStatus = fileMissing ? "created" : "updated";
+        var writeMsg = fileMissing
+            ? $"Created {AgentsFileName} with the managed DocFX documentation maintenance block."
+            : $"Updated the managed DocFX documentation maintenance block in {AgentsFileName}.";
+        return Done(options, ExitCode.Success, writeStatus, true, writeMsg);
+    }
+
+    private static string RenderBlock(string eol)
+    {
+        // ManagedBlock is normalized to LF; render with the host file's line ending.
+        var normalized = ManagedBlock.Replace("\r\n", "\n").Replace("\r", "\n");
+        return eol == "\n" ? normalized : normalized.Replace("\n", eol);
+    }
+
+    private static string DetectLineEnding(string? content)
+    {
+        if (!string.IsNullOrEmpty(content) && content.Contains("\r\n", StringComparison.Ordinal))
+        {
+            return "\r\n";
+        }
+
+        return "\n";
+    }
+
+    private static bool TryParse(string[] args, Options options, out string error, out bool wantHelp)
+    {
+        error = string.Empty;
+        wantHelp = false;
+        bool sawCheck = false, sawWrite = false, sawDryRun = false;
+
+        for (int i = 0; i < args.Length; i++)
+        {
+            var arg = args[i];
+            switch (arg)
+            {
+                case "--help":
+                case "-h":
+                    options.Help = true;
+                    wantHelp = true;
+                    return true;
+                case "--repo-root":
+                    if (i + 1 >= args.Length)
+                    {
+                        error = "--repo-root requires a path argument.";
+                        return false;
+                    }
+
+                    options.RepoRoot = args[++i];
+                    break;
+                case "--check":
+                    sawCheck = true;
+                    break;
+                case "--write":
+                    sawWrite = true;
+                    break;
+                case "--dry-run":
+                    sawDryRun = true;
+                    break;
+                case "--json":
+                    options.Json = true;
+                    break;
+                default:
+                    if (arg.StartsWith("--repo-root=", StringComparison.Ordinal))
+                    {
+                        options.RepoRoot = arg["--repo-root=".Length..];
+                        break;
+                    }
+
+                    error = $"Unknown argument: {arg}";
+                    return false;
+            }
+        }
+
+        // Precedence: --check wins over --dry-run wins over --write; default is write.
+        if (sawCheck)
+        {
+            options.Mode = RunMode.Check;
+        }
+        else if (sawDryRun)
+        {
+            options.Mode = RunMode.DryRun;
+        }
+        else
+        {
+            options.Mode = RunMode.Write;
+        }
+
+        _ = sawWrite;
+        return true;
+    }
+
+    private static int Fail(bool json, ExitCode code, string status, string message, Options options)
+    {
+        if (json)
+        {
+            EmitJson(options, status, message, changed: false);
+        }
+        else
+        {
+            Console.Error.WriteLine($"{ScriptId}: {message}");
+        }
+
+        return (int)code;
+    }
+
+    private static int Done(Options options, ExitCode code, string status, bool changed, string message)
+    {
+        if (options.Json)
+        {
+            EmitJson(options, status, message, changed);
+        }
+        else
+        {
+            Console.WriteLine($"{ScriptId}: {status}: {message}");
+        }
+
+        return (int)code;
+    }
+
+    private static void EmitJson(Options options, string status, string message, bool changed)
+    {
+        var payload = new JsonSummary
+        {
+            Script = ScriptId,
+            RepoRoot = options.ResolvedRepoRoot ?? options.RepoRoot ?? string.Empty,
+            AgentsPath = options.AgentsPath ?? string.Empty,
+            Mode = options.Mode switch
+            {
+                RunMode.Check => "check",
+                RunMode.DryRun => "dry-run",
+                _ => "write"
+            },
+            Status = status,
+            Changed = changed,
+            Message = message
+        };
+
+        Console.WriteLine(JsonSerializer.Serialize(payload, JsonContext.Default.JsonSummary));
+    }
+
+    private static void PrintUsage(TextWriter writer)
+    {
+        writer.WriteLine(
+            $"""
+            {ScriptId} - ensure the repository AGENTS.md contains the dotnet-docfx-digest managed block.
+
+            Usage:
+              dotnet run --file agents.cs -- [options]
+
+            Options:
+              --repo-root <path>   Repository root. Default: current directory.
+              --check              Do not write. Exit non-zero if AGENTS.md is missing or stale.
+              --write              Write changes. Default mode when neither --check nor --dry-run is supplied.
+              --dry-run            Show what would change without writing.
+              --json               Emit a machine-readable JSON summary.
+              --help               Print this usage.
+
+            Exit codes:
+              0  Success; file already compliant or successfully updated.
+              1  Validation failed in --check mode.
+              2  Invalid arguments.
+              3  Repository root does not exist.
+              4  AGENTS.md contains a corrupt managed block.
+              5  Write failed.
+            """);
+    }
+
+    private enum RunMode
+    {
+        Write,
+        Check,
+        DryRun
+    }
+
+    private enum ExitCode
+    {
+        Success = 0,
+        ValidationFailed = 1,
+        InvalidArguments = 2,
+        RepoRootMissing = 3,
+        CorruptBlock = 4,
+        WriteFailed = 5
+    }
+
+    private sealed class Options
+    {
+        public string? RepoRoot { get; set; }
+        public string? ResolvedRepoRoot { get; set; }
+        public string? AgentsPath { get; set; }
+        public bool Json { get; set; }
+        public bool Help { get; set; }
+        public RunMode Mode { get; set; } = RunMode.Write;
+    }
+}
+
+internal sealed class JsonSummary
+{
+    [JsonPropertyName("script")] public string Script { get; set; } = string.Empty;
+    [JsonPropertyName("repoRoot")] public string RepoRoot { get; set; } = string.Empty;
+    [JsonPropertyName("agentsPath")] public string AgentsPath { get; set; } = string.Empty;
+    [JsonPropertyName("mode")] public string Mode { get; set; } = string.Empty;
+    [JsonPropertyName("status")] public string Status { get; set; } = string.Empty;
+    [JsonPropertyName("changed")] public bool Changed { get; set; }
+    [JsonPropertyName("message")] public string Message { get; set; } = string.Empty;
+}
+
+[JsonSerializable(typeof(JsonSummary))]
+[JsonSourceGenerationOptions(WriteIndented = true)]
+internal partial class JsonContext : JsonSerializerContext
+{
+}
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
new file mode 100644
index 0000000..80a0574
--- /dev/null
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -0,0 +1,1338 @@
+#:property TargetFramework=net10.0
+#:property Nullable=enable
+#:property LangVersion=latest
+#:property PublishAot=false
+#:package System.Reflection.MetadataLoadContext@9.0.0
+
+using System.Diagnostics;
+using System.Reflection;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using System.Text.RegularExpressions;
+using System.Xml.Linq;
+
+return DocfxValidator.Run(args);
+
+internal static class DocfxValidator
+{
+    private const string ScriptId = "validate-docfx-digest";
+    private const string StartMarker = "<!-- dotnet-docfx-digest:start -->";
+    private const string EndMarker = "<!-- dotnet-docfx-digest:end -->";
+    private const string ExtensionAttributeFullName = "System.Runtime.CompilerServices.ExtensionAttribute";
+    private const string SkipMarker = "dotnet-docfx-digest:skip-compile";
+
+    private static readonly string[] IgnoredDirectorySegments = ["bin", "obj", "_site", ".git", "node_modules"];
+    private static readonly TimeSpan ProcessTimeout = TimeSpan.FromMinutes(10);
+
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        WriteIndented = true,
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
+    };
+
+    public static int Run(string[] args)
+    {
+        Options options;
+        try
+        {
+            if (!TryParse(args, out options, out var parseError, out var wantHelp))
+            {
+                if (wantHelp)
+                {
+                    PrintUsage();
+                    return 0;
+                }
+
+                Console.Error.WriteLine($"{ScriptId}: {parseError}");
+                return (int)ExitCode.InvalidArguments;
+            }
+
+            if (options.Help)
+            {
+                PrintUsage();
+                return 0;
+            }
+        }
+        catch (Exception ex)
+        {
+            Console.Error.WriteLine($"{ScriptId}: argument parsing failed: {ex.Message}");
+            return (int)ExitCode.InvalidArguments;
+        }
+
+        try
+        {
+            return Validate(options);
+        }
+        catch (Exception ex)
+        {
+            if (options.Json)
+            {
+                var report = new Report { Script = ScriptId, Status = "failed" };
+                report.Errors.Add(new Diagnostic("INTERNAL_ERROR", null, null, $"Unexpected internal error: {ex.Message}"));
+                Console.WriteLine(JsonSerializer.Serialize(report, JsonOptions));
+            }
+            else
+            {
+                Console.Error.WriteLine($"{ScriptId}: unexpected internal error: {ex}");
+            }
+
+            return (int)ExitCode.InternalError;
+        }
+    }
+
+    private static int Validate(Options options)
+    {
+        var report = new Report { Script = ScriptId };
+
+        // 1. Resolve repository root.
+        string repoRoot;
+        try
+        {
+            repoRoot = Path.GetFullPath(string.IsNullOrWhiteSpace(options.RepoRoot) ? "." : options.RepoRoot);
+        }
+        catch (Exception ex)
+        {
+            return Emit(options, report, ExitCode.RepoRootMissing, $"Invalid repository root: {ex.Message}");
+        }
+
+        report.RepoRoot = repoRoot;
+        if (!Directory.Exists(repoRoot))
+        {
+            return Emit(options, report, ExitCode.RepoRootMissing, $"Repository root does not exist: {repoRoot}");
+        }
+
+        // 2. Locate the DocFX configuration file.
+        var docfxPath = ResolveDocfxPath(repoRoot, options.DocfxPath);
+        if (docfxPath is null)
+        {
+            report.Errors.Add(new Diagnostic("DOCFX_CONFIG_MISSING", null, null,
+                "No DocFX configuration file (docfx.json) was found. Looked under .docfx/docfx.json and the repository root."));
+            return Emit(options, report, ExitCode.DocfxConfigMissing, "DocFX configuration file not found.");
+        }
+
+        report.DocfxPath = docfxPath;
+        var docfxWorkspace = Path.GetDirectoryName(docfxPath)!;
+
+        // 3. Verify AGENTS.md contains the managed block.
+        var agentsPath = Path.Combine(repoRoot, "AGENTS.md");
+        if (!AgentsBlockPresent(agentsPath))
+        {
+            report.Errors.Add(new Diagnostic("AGENTS_BLOCK_MISSING", agentsPath, null,
+                "AGENTS.md does not contain the dotnet-docfx-digest managed block. Run scripts/agents.cs first."));
+        }
+
+        // Optional changed-only scoping.
+        HashSet<string>? changedFiles = null;
+        if (options.ChangedOnly)
+        {
+            changedFiles = GetChangedFiles(repoRoot, report);
+            if (changedFiles is null)
+            {
+                report.Warnings.Add(new Diagnostic("CHANGED_ONLY_FALLBACK", null, null,
+                    "git was unavailable or the repository has no HEAD; falling back to full validation."));
+            }
+        }
+
+        // 4. Build the repository before metadata inspection.
+        var (buildOk, buildOutput) = BuildRepository(repoRoot, options.Configuration);
+        if (!buildOk)
+        {
+            report.Errors.Add(new Diagnostic("BUILD_FAILED", null, null,
+                $"dotnet build failed (configuration {options.Configuration}).\n{Trim(buildOutput)}"));
+            return Emit(options, report, ExitCode.BuildFailed, "Build failed.");
+        }
+
+        // 5-7. Discover public API, namespaces and extension methods from compiled metadata.
+        var projects = DiscoverProjects(repoRoot);
+        var libraryProjects = projects.Where(p => !p.IsTest).ToList();
+        ApiModel api;
+        try
+        {
+            api = DiscoverApi(libraryProjects, options.Configuration, options.Framework, report);
+        }
+        catch (Exception ex)
+        {
+            report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
+                $"Public API discovery failed: {ex.Message}"));
+            return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
+        }
+
+        if (api.Namespaces.Count == 0)
+        {
+            report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
+                "No public API could be discovered from the compiled library assemblies. Ensure the repository builds and exposes public types."));
+            return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
+        }
+
+        report.Summary.PublicNamespaces = api.Namespaces.Count;
+        report.Summary.ExtensionMethods = api.Namespaces.Sum(n => n.ExtensionMethods.Count);
+
+        // 8. Discover DocFX Markdown files under the workspace.
+        var markdownFiles = DiscoverMarkdown(docfxWorkspace);
+
+        // 9-11. Validate namespace overview pages, extension tables and availability.
+        foreach (var ns in api.Namespaces.OrderBy(n => n.Name, StringComparer.Ordinal))
+        {
+            var page = markdownFiles.FirstOrDefault(f =>
+                string.Equals(Path.GetFileNameWithoutExtension(f), ns.Name, StringComparison.Ordinal));
+
+            if (page is null)
+            {
+                report.Errors.Add(new Diagnostic("NAMESPACE_PAGE_MISSING", null, ns.Name,
+                    $"Missing namespace overview page for namespace {ns.Name}. Expected a file named {ns.Name}.md under {Rel(repoRoot, docfxWorkspace)}."));
+                continue;
+            }
+
+            if (options.ChangedOnly && changedFiles is not null && !changedFiles.Contains(Path.GetFullPath(page)))
+            {
+                continue;
+            }
+
+            ValidateNamespacePage(repoRoot, page, ns, report);
+            report.Summary.NamespacePagesValidated++;
+        }
+
+        // 12-13. Extract and compile C# documentation samples.
+        if (options.ValidateSamples)
+        {
+            ValidateSamples(repoRoot, markdownFiles, libraryProjects, options, changedFiles, report);
+        }
+
+        // 14-15. Produce report and return a deterministic exit code.
+        bool hasSampleError = report.Errors.Any(e => e.Code is "SAMPLE_COMPILE_FAILED");
+        bool hasOtherError = report.Errors.Any(e => e.Code is not "SAMPLE_COMPILE_FAILED");
+
+        report.Status = report.Errors.Count == 0 ? "passed" : "failed";
+        report.Summary.Errors = report.Errors.Count;
+        report.Summary.Warnings = report.Warnings.Count;
+
+        if (hasOtherError)
+        {
+            return Emit(options, report, ExitCode.ValidationFailed, "Validation failed.");
+        }
+
+        if (hasSampleError)
+        {
+            return Emit(options, report, ExitCode.SampleCompilationFailed, "Sample compilation failed.");
+        }
+
+        return Emit(options, report, ExitCode.Success, "Validation passed.");
+    }
+
+    // ----------------------------------------------------------------------
+    // DocFX discovery
+    // ----------------------------------------------------------------------
+
+    private static string? ResolveDocfxPath(string repoRoot, string? explicitPath)
+    {
+        if (!string.IsNullOrWhiteSpace(explicitPath))
+        {
+            var full = Path.GetFullPath(explicitPath, repoRoot);
+            return File.Exists(full) ? full : null;
+        }
+
+        var conventional = Path.Combine(repoRoot, ".docfx", "docfx.json");
+        if (File.Exists(conventional))
+        {
+            return conventional;
+        }
+
+        var atRoot = Path.Combine(repoRoot, "docfx.json");
+        if (File.Exists(atRoot))
+        {
+            return atRoot;
+        }
+
+        // Fall back to the first docfx.json found anywhere under the repo (excluding build output).
+        foreach (var file in EnumerateFiles(repoRoot, "docfx.json"))
+        {
+            return file;
+        }
+
+        return null;
+    }
+
+    private static List<string> DiscoverMarkdown(string docfxWorkspace)
+    {
+        var list = new List<string>();
+        foreach (var file in EnumerateFiles(docfxWorkspace, "*.md"))
+        {
+            list.Add(Path.GetFullPath(file));
+        }
+
+        return list;
+    }
+
+    private static IEnumerable<string> EnumerateFiles(string root, string pattern)
+    {
+        var stack = new Stack<string>();
+        stack.Push(root);
+        while (stack.Count > 0)
+        {
+            var dir = stack.Pop();
+            string[] entries;
+            try
+            {
+                entries = Directory.GetDirectories(dir);
+            }
+            catch
+            {
+                continue;
+            }
+
+            foreach (var sub in entries)
+            {
+                var name = Path.GetFileName(sub);
+                if (IgnoredDirectorySegments.Contains(name, StringComparer.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
+                stack.Push(sub);
+            }
+
+            string[] files;
+            try
+            {
+                files = Directory.GetFiles(dir, pattern);
+            }
+            catch
+            {
+                continue;
+            }
+
+            foreach (var f in files)
+            {
+                yield return f;
+            }
+        }
+    }
+
+    private static bool AgentsBlockPresent(string agentsPath)
+    {
+        if (!File.Exists(agentsPath))
+        {
+            return false;
+        }
+
+        var text = File.ReadAllText(agentsPath);
+        return text.Contains(StartMarker, StringComparison.Ordinal) && text.Contains(EndMarker, StringComparison.Ordinal);
+    }
+
+    // ----------------------------------------------------------------------
+    // Build
+    // ----------------------------------------------------------------------
+
+    private static (bool Ok, string Output) BuildRepository(string repoRoot, string configuration)
+    {
+        // Build a solution if one is present, otherwise let dotnet resolve the project in the repo root.
+        var target = Directory.GetFiles(repoRoot, "*.slnx").Concat(Directory.GetFiles(repoRoot, "*.sln")).FirstOrDefault();
+        var args = target is null
+            ? $"build -c {configuration} --nologo"
+            : $"build \"{target}\" -c {configuration} --nologo";
+        var result = RunProcess("dotnet", args, repoRoot);
+        return (result.ExitCode == 0, result.StdOut + result.StdErr);
+    }
+
+    // ----------------------------------------------------------------------
+    // Project + API discovery
+    // ----------------------------------------------------------------------
+
+    private static List<ProjectInfo> DiscoverProjects(string repoRoot)
+    {
+        var projects = new List<ProjectInfo>();
+        foreach (var proj in EnumerateFiles(repoRoot, "*.csproj"))
+        {
+            var info = ReadProject(proj);
+            projects.Add(info);
+        }
+
+        return projects;
+    }
+
+    private static ProjectInfo ReadProject(string projectPath)
+    {
+        string? assemblyName = null;
+        var tfms = new List<string>();
+        bool isTest = false;
+
+        try
+        {
+            var doc = XDocument.Load(projectPath);
+            foreach (var el in doc.Descendants())
+            {
+                switch (el.Name.LocalName)
+                {
+                    case "AssemblyName":
+                        assemblyName = el.Value.Trim();
+                        break;
+                    case "TargetFramework":
+                        if (!string.IsNullOrWhiteSpace(el.Value))
+                        {
+                            tfms.Add(el.Value.Trim());
+                        }
+
+                        break;
+                    case "TargetFrameworks":
+                        tfms.AddRange(el.Value.Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries));
+                        break;
+                    case "IsTestProject":
+                        if (bool.TryParse(el.Value.Trim(), out var b) && b)
+                        {
+                            isTest = true;
+                        }
+
+                        break;
+                    case "PackageReference":
+                        var include = el.Attribute("Include")?.Value ?? string.Empty;
+                        if (include.Contains("Microsoft.NET.Test.Sdk", StringComparison.OrdinalIgnoreCase) ||
+                            include.Contains("xunit", StringComparison.OrdinalIgnoreCase) ||
+                            include.StartsWith("NUnit", StringComparison.OrdinalIgnoreCase) ||
+                            include.Contains("MSTest", StringComparison.OrdinalIgnoreCase))
+                        {
+                            isTest = true;
+                        }
+
+                        break;
+                }
+            }
+        }
+        catch
+        {
+            // Ignore malformed project files; they simply contribute no metadata.
+        }
+
+        assemblyName ??= Path.GetFileNameWithoutExtension(projectPath);
+
+        // Path-based heuristic: anything under a test/tests folder or named *Test(s).
+        var segments = projectPath.Split(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+        if (segments.Any(s => string.Equals(s, "test", StringComparison.OrdinalIgnoreCase) ||
+                              string.Equals(s, "tests", StringComparison.OrdinalIgnoreCase)))
+        {
+            isTest = true;
+        }
+
+        var fileName = Path.GetFileNameWithoutExtension(projectPath);
+        if (fileName.EndsWith("Test", StringComparison.OrdinalIgnoreCase) ||
+            fileName.EndsWith("Tests", StringComparison.OrdinalIgnoreCase))
+        {
+            isTest = true;
+        }
+
+        return new ProjectInfo(projectPath, assemblyName, tfms, isTest);
+    }
+
+    private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string configuration, string? framework, Report report)
+    {
+        var assemblyPaths = new List<string>();
+        foreach (var proj in libraryProjects)
+        {
+            var dll = FindAssembly(proj, configuration, framework);
+            if (dll is not null)
+            {
+                assemblyPaths.Add(dll);
+            }
+        }
+
+        if (assemblyPaths.Count == 0)
+        {
+            return new ApiModel(new List<NamespaceInfo>());
+        }
+
+        // Resolve dependencies from the runtime directory and the assemblies' own output folders.
+        var resolverPaths = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        var runtimeDir = System.Runtime.InteropServices.RuntimeEnvironment.GetRuntimeDirectory();
+        foreach (var dll in Directory.GetFiles(runtimeDir, "*.dll"))
+        {
+            resolverPaths.Add(dll);
+        }
+
+        foreach (var dll in assemblyPaths)
+        {
+            var dir = Path.GetDirectoryName(dll)!;
+            foreach (var sibling in Directory.GetFiles(dir, "*.dll"))
+            {
+                resolverPaths.Add(sibling);
+            }
+        }
+
+        var resolver = new PathAssemblyResolver(resolverPaths);
+        using var mlc = new MetadataLoadContext(resolver, "System.Private.CoreLib");
+
+        var namespaces = new Dictionary<string, NamespaceInfo>(StringComparer.Ordinal);
+        foreach (var dll in assemblyPaths)
+        {
+            Assembly asm;
+            try
+            {
+                asm = mlc.LoadFromAssemblyPath(dll);
+            }
+            catch
+            {
+                continue;
+            }
+
+            Type[] types;
+            try
+            {
+                types = asm.GetTypes();
+            }
+            catch (ReflectionTypeLoadException rtle)
+            {
+                types = rtle.Types.Where(t => t is not null).Cast<Type>().ToArray();
+            }
+            catch
+            {
+                continue;
+            }
+
+            foreach (var type in types)
+            {
+                if (type is null || !IsExternallyVisible(type))
+                {
+                    continue;
+                }
+
+                var nsName = type.Namespace;
+                if (string.IsNullOrEmpty(nsName))
+                {
+                    continue;
+                }
+
+                if (!namespaces.TryGetValue(nsName, out var info))
+                {
+                    info = new NamespaceInfo(nsName);
+                    namespaces[nsName] = info;
+                }
+
+                CollectExtensionMethods(type, info);
+            }
+        }
+
+        return new ApiModel(namespaces.Values.ToList());
+    }
+
+    private static void CollectExtensionMethods(Type type, NamespaceInfo ns)
+    {
+        // A public extension method lives on a public static (abstract+sealed) non-generic class.
+        if (!type.IsClass || !type.IsAbstract || !type.IsSealed || type.IsGenericType || !type.IsPublic)
+        {
+            return;
+        }
+
+        MethodInfo[] methods;
+        try
+        {
+            methods = type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly);
+        }
+        catch
+        {
+            return;
+        }
+
+        foreach (var method in methods)
+        {
+            if (!method.IsStatic || !method.IsPublic)
+            {
+                continue;
+            }
+
+            if (!HasExtensionAttribute(method))
+            {
+                continue;
+            }
+
+            var parameters = method.GetParameters();
+            if (parameters.Length == 0)
+            {
+                continue;
+            }
+
+            var extendedType = SimpleTypeName(parameters[0].ParameterType);
+            ns.ExtensionMethods.Add(new ExtensionMethodInfo(method.Name, extendedType, type.Name));
+        }
+    }
+
+    private static bool HasExtensionAttribute(MemberInfo member)
+    {
+        try
+        {
+            foreach (var attr in member.GetCustomAttributesData())
+            {
+                if (string.Equals(attr.AttributeType.FullName, ExtensionAttributeFullName, StringComparison.Ordinal))
+                {
+                    return true;
+                }
+            }
+        }
+        catch
+        {
+            // ignore
+        }
+
+        return false;
+    }
+
+    private static bool IsExternallyVisible(Type type)
+    {
+        try
+        {
+            if (type.IsNested)
+            {
+                return type.IsNestedPublic && type.DeclaringType is not null && IsExternallyVisible(type.DeclaringType);
+            }
+
+            return type.IsPublic;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    private static string SimpleTypeName(Type type)
+    {
+        var name = type.Name;
+        var tick = name.IndexOf('`');
+        return tick >= 0 ? name[..tick] : name;
+    }
+
+    private static string? FindAssembly(ProjectInfo project, string configuration, string? framework)
+    {
+        var projDir = Path.GetDirectoryName(project.Path)!;
+        var dllName = project.AssemblyName + ".dll";
+
+        // Prefer reference assemblies (ref/) when present, then regular output. Honor --framework.
+        var roots = new[] { Path.Combine(projDir, "bin", configuration), Path.Combine(projDir, "obj", configuration) };
+        string? fallback = null;
+
+        foreach (var root in roots)
+        {
+            if (!Directory.Exists(root))
+            {
+                continue;
+            }
+
+            IEnumerable<string> candidates;
+            try
+            {
+                candidates = Directory.GetFiles(root, dllName, SearchOption.AllDirectories);
+            }
+            catch
+            {
+                continue;
+            }
+
+            foreach (var candidate in candidates)
+            {
+                if (framework is not null && !candidate.Replace('\\', '/').Contains($"/{framework}/", StringComparison.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
+                var isRef = candidate.Replace('\\', '/').Contains("/ref/", StringComparison.OrdinalIgnoreCase);
+                if (isRef)
+                {
+                    return candidate;
+                }
+
+                fallback ??= candidate;
+            }
+        }
+
+        return fallback;
+    }
+
+    // ----------------------------------------------------------------------
+    // Namespace page validation
+    // ----------------------------------------------------------------------
+
+    private static void ValidateNamespacePage(string repoRoot, string page, NamespaceInfo ns, Report report)
+    {
+        var rel = Rel(repoRoot, page);
+        string text;
+        try
+        {
+            text = File.ReadAllText(page);
+        }
+        catch (Exception ex)
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_PAGE_MISSING", rel, ns.Name, $"Unable to read namespace page: {ex.Message}"));
+            return;
+        }
+
+        var (frontMatter, body) = SplitFrontMatter(text);
+
+        // uid
+        var uid = ReadYamlScalar(frontMatter, "uid");
+        if (uid is null)
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_UID_MISSING", rel, ns.Name,
+                $"Namespace page is missing a 'uid' in its DocFX overwrite front matter."));
+        }
+        else if (!string.Equals(uid, ns.Name, StringComparison.Ordinal))
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_UID_MISMATCH", rel, ns.Name,
+                $"Namespace page uid '{uid}' does not match the namespace '{ns.Name}'."));
+        }
+
+        // summary
+        if (ReadYamlScalar(frontMatter, "summary") is null)
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_SUMMARY_MISSING", rel, ns.Name,
+                "Namespace page front matter is missing a 'summary' key (expected 'summary: *content')."));
+        }
+
+        // fly-in paragraph
+        if (!HasFlyIn(body))
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_FLYIN_MISSING", rel, ns.Name,
+                "Namespace page has no human-written fly-in paragraph, or contains only placeholder text."));
+        }
+
+        // availability
+        if (!HasAvailability(body))
+        {
+            report.Errors.Add(new Diagnostic("AVAILABILITY_MISSING", rel, ns.Name,
+                "Namespace page has no availability information (expected an availability include or explicit 'Availability:' text)."));
+        }
+
+        // extension members
+        if (ns.ExtensionMethods.Count > 0)
+        {
+            ValidateExtensionSection(rel, body, ns, report);
+        }
+    }
+
+    private static void ValidateExtensionSection(string rel, string body, NamespaceInfo ns, Report report)
+    {
+        var sectionMatch = Regex.Match(body, @"(?im)^#{2,4}\s+Extension\s+Members\s*$");
+        if (!sectionMatch.Success)
+        {
+            report.Errors.Add(new Diagnostic("EXTENSION_SECTION_MISSING", rel, ns.Name,
+                $"Namespace {ns.Name} exposes public extension methods but the page has no 'Extension Members' section."));
+            return;
+        }
+
+        var section = body[sectionMatch.Index..];
+        // Stop at the next heading of equal-or-higher level.
+        var nextHeading = Regex.Match(section[sectionMatch.Length..], @"(?im)^#{1,4}\s+\S");
+        if (nextHeading.Success)
+        {
+            section = section[..(sectionMatch.Length + nextHeading.Index)];
+        }
+
+        if (!Regex.IsMatch(section, @"\|\s*Type\s*\|\s*Ext\s*\|\s*Methods\s*\|", RegexOptions.IgnoreCase))
+        {
+            report.Errors.Add(new Diagnostic("EXTENSION_TABLE_MISSING", rel, ns.Name,
+                $"The 'Extension Members' section for namespace {ns.Name} is missing the '|Type|Ext|Methods|' table header."));
+            return;
+        }
+
+        // Every discovered extension method name must appear (backticked) in the section.
+        foreach (var group in ns.ExtensionMethods.GroupBy(m => m.MethodName, StringComparer.Ordinal))
+        {
+            var methodName = group.Key;
+            var pattern = "`" + Regex.Escape(methodName);
+            if (!Regex.IsMatch(section, pattern + @"[`(]"))
+            {
+                report.Errors.Add(new Diagnostic("EXTENSION_METHOD_MISSING", rel, ns.Name,
+                    $"Extension method `{methodName}` (extending {group.First().ExtendedType}) is not listed in the 'Extension Members' table for namespace {ns.Name}."));
+            }
+        }
+    }
+
+    private static bool HasFlyIn(string body)
+    {
+        foreach (var raw in body.Split('\n'))
+        {
+            var line = raw.Trim();
+            if (line.Length == 0)
+            {
+                continue;
+            }
+
+            if (line.StartsWith('#') || line.StartsWith('|') || line.StartsWith("[!INCLUDE", StringComparison.OrdinalIgnoreCase) ||
+                line.StartsWith("```", StringComparison.Ordinal) || line.StartsWith("---", StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            // Reject template placeholders like "contains types that ..." or bare ellipses / TODO.
+            if (line.Contains("...", StringComparison.Ordinal) || line.Contains("TODO", StringComparison.OrdinalIgnoreCase) ||
+                line.EndsWith("contains types that", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            if (line.Length >= 20)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private static bool HasAvailability(string body)
+    {
+        if (body.Contains("[!INCLUDE", StringComparison.OrdinalIgnoreCase))
+        {
+            return true;
+        }
+
+        return Regex.IsMatch(body, @"(?im)^\s*Availability\s*:");
+    }
+
+    // ----------------------------------------------------------------------
+    // Sample validation
+    // ----------------------------------------------------------------------
+
+    private static void ValidateSamples(string repoRoot, List<string> markdownFiles, List<ProjectInfo> libraryProjects,
+        Options options, HashSet<string>? changedFiles, Report report)
+    {
+        var samples = new List<SampleFence>();
+        foreach (var md in markdownFiles)
+        {
+            if (options.ChangedOnly && changedFiles is not null && !changedFiles.Contains(Path.GetFullPath(md)))
+            {
+                continue;
+            }
+
+            samples.AddRange(ExtractFences(md));
+        }
+
+        if (samples.Count == 0)
+        {
+            return;
+        }
+
+        var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-samples-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(tempRoot);
+        try
+        {
+            int index = 0;
+            foreach (var sample in samples)
+            {
+                index++;
+                var skip = FindSkip(sample.Code);
+                if (skip.Found)
+                {
+                    if (string.IsNullOrWhiteSpace(skip.Reason))
+                    {
+                        report.Errors.Add(new Diagnostic("SAMPLE_SKIP_REASON_MISSING", Rel(repoRoot, sample.File), null,
+                            $"A C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) uses the skip-compile marker without a mandatory reason."));
+                    }
+                    else
+                    {
+                        report.Summary.SamplesSkipped++;
+                    }
+
+                    continue;
+                }
+
+                var (ok, diagnostics, exitCode) = CompileSample(tempRoot, index, sample, libraryProjects, options.Configuration);
+                if (ok)
+                {
+                    report.Summary.SamplesCompiled++;
+                }
+                else
+                {
+                    report.Errors.Add(new Diagnostic("SAMPLE_COMPILE_FAILED", Rel(repoRoot, sample.File), null,
+                        $"C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) failed to compile (exit {exitCode}).\n{Trim(diagnostics)}"));
+                }
+            }
+        }
+        finally
+        {
+            TryDeleteDirectory(tempRoot);
+        }
+    }
+
+    private static (bool Ok, string Diagnostics, int ExitCode) CompileSample(string tempRoot, int index, SampleFence sample,
+        List<ProjectInfo> libraryProjects, string configuration)
+    {
+        var dir = Path.Combine(tempRoot, "sample_" + index);
+        Directory.CreateDirectory(dir);
+        var file = Path.Combine(dir, "sample.cs");
+
+        var sb = new StringBuilder();
+        sb.Append("#:property TargetFramework=net10.0\n");
+        sb.Append("#:property PublishAot=false\n");
+        sb.Append("#:property Nullable=enable\n");
+        foreach (var proj in libraryProjects)
+        {
+            sb.Append("#:project ").Append(proj.Path).Append('\n');
+        }
+
+        sb.Append('\n');
+        sb.Append(sample.Code);
+        if (!sample.Code.EndsWith('\n'))
+        {
+            sb.Append('\n');
+        }
+
+        File.WriteAllText(file, sb.ToString(), new UTF8Encoding(false));
+
+        var result = RunProcess("dotnet", $"build \"{file}\" -c {configuration} --nologo", dir);
+        return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
+    }
+
+    private static List<SampleFence> ExtractFences(string mdFile)
+    {
+        var fences = new List<SampleFence>();
+        string[] lines;
+        try
+        {
+            lines = File.ReadAllLines(mdFile);
+        }
+        catch
+        {
+            return fences;
+        }
+
+        int fenceIndex = 0;
+        for (int i = 0; i < lines.Length; i++)
+        {
+            var trimmed = lines[i].TrimStart();
+            if (!trimmed.StartsWith("```", StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            var info = trimmed.TrimStart('`').Trim().ToLowerInvariant();
+            int start = i;
+            int j = i + 1;
+            var content = new StringBuilder();
+            while (j < lines.Length && !lines[j].TrimStart().StartsWith("```", StringComparison.Ordinal))
+            {
+                content.Append(lines[j]).Append('\n');
+                j++;
+            }
+
+            if (info is "csharp" or "cs")
+            {
+                fenceIndex++;
+                fences.Add(new SampleFence(mdFile, fenceIndex, start + 1, content.ToString()));
+            }
+
+            i = j; // continue after the closing fence
+        }
+
+        return fences;
+    }
+
+    private static (bool Found, string Reason) FindSkip(string code)
+    {
+        foreach (var line in code.Split('\n'))
+        {
+            var idx = line.IndexOf(SkipMarker, StringComparison.Ordinal);
+            if (idx < 0)
+            {
+                continue;
+            }
+
+            var after = line[(idx + SkipMarker.Length)..].Trim();
+            if (after.StartsWith('-'))
+            {
+                after = after[1..].Trim();
+            }
+
+            return (true, after);
+        }
+
+        return (false, string.Empty);
+    }
+
+    // ----------------------------------------------------------------------
+    // git changed-only
+    // ----------------------------------------------------------------------
+
+    private static HashSet<string>? GetChangedFiles(string repoRoot, Report report)
+    {
+        var result = RunProcess("git", "rev-parse --verify HEAD", repoRoot);
+        if (result.ExitCode != 0)
+        {
+            return null;
+        }
+
+        var diff = RunProcess("git", "diff --name-only --diff-filter=ACMRTUXB HEAD", repoRoot);
+        if (diff.ExitCode != 0)
+        {
+            return null;
+        }
+
+        var set = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var line in diff.StdOut.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+        {
+            set.Add(Path.GetFullPath(Path.Combine(repoRoot, line)));
+        }
+
+        return set;
+    }
+
+    // ----------------------------------------------------------------------
+    // YAML / markdown helpers
+    // ----------------------------------------------------------------------
+
+    private static (string FrontMatter, string Body) SplitFrontMatter(string text)
+    {
+        var normalized = text.Replace("\r\n", "\n").Replace("\r", "\n");
+        if (!normalized.StartsWith("---\n", StringComparison.Ordinal))
+        {
+            return (string.Empty, normalized);
+        }
+
+        var end = normalized.IndexOf("\n---", 3, StringComparison.Ordinal);
+        if (end < 0)
+        {
+            return (string.Empty, normalized);
+        }
+
+        var frontMatter = normalized[4..end];
+        var afterIdx = normalized.IndexOf('\n', end + 1);
+        var body = afterIdx >= 0 ? normalized[(afterIdx + 1)..] : string.Empty;
+        return (frontMatter, body);
+    }
+
+    private static string? ReadYamlScalar(string frontMatter, string key)
+    {
+        foreach (var raw in frontMatter.Split('\n'))
+        {
+            var line = raw.Trim();
+            if (line.StartsWith(key + ":", StringComparison.Ordinal))
+            {
+                var value = line[(key.Length + 1)..].Trim();
+                return value.Length == 0 ? null : value;
+            }
+        }
+
+        return null;
+    }
+
+    // ----------------------------------------------------------------------
+    // Process + output helpers
+    // ----------------------------------------------------------------------
+
+    private static ProcessResult RunProcess(string fileName, string arguments, string workingDirectory)
+    {
+        var psi = new ProcessStartInfo
+        {
+            FileName = fileName,
+            Arguments = arguments,
+            WorkingDirectory = workingDirectory,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            UseShellExecute = false,
+            CreateNoWindow = true
+        };
+
+        try
+        {
+            using var process = Process.Start(psi);
+            if (process is null)
+            {
+                return new ProcessResult(-1, string.Empty, $"Failed to start process '{fileName}'.");
+            }
+
+            var stdout = process.StandardOutput.ReadToEnd();
+            var stderr = process.StandardError.ReadToEnd();
+            if (!process.WaitForExit(ProcessTimeout))
+            {
+                try
+                {
+                    process.Kill(entireProcessTree: true);
+                }
+                catch
+                {
+                    // ignore
+                }
+
+                return new ProcessResult(-1, stdout, stderr + $"\nProcess '{fileName}' timed out after {ProcessTimeout.TotalMinutes} minutes.");
+            }
+
+            return new ProcessResult(process.ExitCode, stdout, stderr);
+        }
+        catch (Exception ex)
+        {
+            return new ProcessResult(-1, string.Empty, $"Failed to run '{fileName} {arguments}': {ex.Message}");
+        }
+    }
+
+    private static void TryDeleteDirectory(string path)
+    {
+        try
+        {
+            if (Directory.Exists(path))
+            {
+                Directory.Delete(path, recursive: true);
+            }
+        }
+        catch
+        {
+            // best effort
+        }
+    }
+
+    private static string Rel(string root, string path)
+    {
+        try
+        {
+            return Path.GetRelativePath(root, path).Replace('\\', '/');
+        }
+        catch
+        {
+            return path;
+        }
+    }
+
+    private static string Trim(string text)
+    {
+        const int max = 4000;
+        text = text.Trim();
+        return text.Length <= max ? text : text[..max] + "\n... (truncated)";
+    }
+
+    private static int Emit(Options options, Report report, ExitCode code, string consoleMessage)
+    {
+        if (report.Status is null)
+        {
+            report.Status = code == ExitCode.Success ? "passed" : "failed";
+        }
+
+        report.Summary.Errors = report.Errors.Count;
+        report.Summary.Warnings = report.Warnings.Count;
+
+        if (options.Json)
+        {
+            Console.WriteLine(JsonSerializer.Serialize(report, JsonOptions));
+        }
+        else
+        {
+            Console.WriteLine($"{ScriptId}: {report.Status}: {consoleMessage}");
+            foreach (var error in report.Errors)
+            {
+                Console.WriteLine($"  ERROR  [{error.Code}] {Describe(error)}");
+            }
+
+            foreach (var warning in report.Warnings)
+            {
+                Console.WriteLine($"  WARN   [{warning.Code}] {Describe(warning)}");
+            }
+
+            Console.WriteLine(
+                $"  Summary: namespaces={report.Summary.PublicNamespaces}, pages={report.Summary.NamespacePagesValidated}, " +
+                $"extMethods={report.Summary.ExtensionMethods}, samplesCompiled={report.Summary.SamplesCompiled}, " +
+                $"samplesSkipped={report.Summary.SamplesSkipped}, errors={report.Summary.Errors}, warnings={report.Summary.Warnings}");
+        }
+
+        return (int)code;
+    }
+
+    private static string Describe(Diagnostic d)
+    {
+        var location = d.Namespace is not null ? $"({d.Namespace}) " : string.Empty;
+        var path = d.Path is not null ? $"{d.Path}: " : string.Empty;
+        return $"{path}{location}{d.Message}";
+    }
+
+    // ----------------------------------------------------------------------
+    // Argument parsing
+    // ----------------------------------------------------------------------
+
+    private static bool TryParse(string[] args, out Options options, out string error, out bool wantHelp)
+    {
+        options = new Options();
+        error = string.Empty;
+        wantHelp = false;
+
+        for (int i = 0; i < args.Length; i++)
+        {
+            var arg = args[i];
+            switch (arg)
+            {
+                case "--help":
+                case "-h":
+                    options.Help = true;
+                    wantHelp = true;
+                    return true;
+                case "--repo-root":
+                    if (!Next(args, ref i, out var rr)) { error = "--repo-root requires a path."; return false; }
+                    options.RepoRoot = rr;
+                    break;
+                case "--docfx":
+                    if (!Next(args, ref i, out var dx)) { error = "--docfx requires a path."; return false; }
+                    options.DocfxPath = dx;
+                    break;
+                case "--configuration":
+                    if (!Next(args, ref i, out var cfg)) { error = "--configuration requires a name."; return false; }
+                    options.Configuration = cfg;
+                    break;
+                case "--framework":
+                    if (!Next(args, ref i, out var fw)) { error = "--framework requires a TFM."; return false; }
+                    options.Framework = fw;
+                    break;
+                case "--validate-samples":
+                    options.ValidateSamples = true;
+                    break;
+                case "--no-validate-samples":
+                    options.ValidateSamples = false;
+                    break;
+                case "--changed-only":
+                    options.ChangedOnly = true;
+                    break;
+                case "--json":
+                    options.Json = true;
+                    break;
+                default:
+                    if (TrySplit(arg, "--repo-root", out var v1)) { options.RepoRoot = v1; break; }
+                    if (TrySplit(arg, "--docfx", out var v2)) { options.DocfxPath = v2; break; }
+                    if (TrySplit(arg, "--configuration", out var v3)) { options.Configuration = v3; break; }
+                    if (TrySplit(arg, "--framework", out var v4)) { options.Framework = v4; break; }
+                    error = $"Unknown argument: {arg}";
+                    return false;
+            }
+        }
+
+        return true;
+    }
+
+    private static bool Next(string[] args, ref int i, out string value)
+    {
+        if (i + 1 >= args.Length)
+        {
+            value = string.Empty;
+            return false;
+        }
+
+        value = args[++i];
+        return true;
+    }
+
+    private static bool TrySplit(string arg, string name, out string value)
+    {
+        var prefix = name + "=";
+        if (arg.StartsWith(prefix, StringComparison.Ordinal))
+        {
+            value = arg[prefix.Length..];
+            return true;
+        }
+
+        value = string.Empty;
+        return false;
+    }
+
+    private static void PrintUsage()
+    {
+        Console.WriteLine(
+            $"""
+            {ScriptId} - validate DocFX documentation for .NET public APIs.
+
+            Usage:
+              dotnet run --file docfx.cs -- [options]
+
+            Options:
+              --repo-root <path>       Repository root. Default: current directory.
+              --docfx <path>           Path to docfx.json. Default: .docfx/docfx.json under repo root.
+              --configuration <name>   Build configuration. Default: Release.
+              --framework <tfm>        Optional target framework to validate against.
+              --validate-samples       Compile C# samples. Default: enabled.
+              --no-validate-samples    Skip C# sample compilation.
+              --changed-only           Validate only files changed according to git.
+              --json                   Emit a machine-readable JSON summary.
+              --help                   Print this usage.
+
+            Exit codes:
+              0  Validation passed.
+              1  Validation failed.
+              2  Invalid arguments.
+              3  Repository root does not exist.
+              4  DocFX configuration file not found.
+              5  Build failed.
+              6  Public API discovery failed.
+              7  Sample compilation failed.
+              8  Unexpected internal error.
+            """);
+    }
+
+    private enum ExitCode
+    {
+        Success = 0,
+        ValidationFailed = 1,
+        InvalidArguments = 2,
+        RepoRootMissing = 3,
+        DocfxConfigMissing = 4,
+        BuildFailed = 5,
+        PublicApiDiscoveryFailed = 6,
+        SampleCompilationFailed = 7,
+        InternalError = 8
+    }
+
+    private sealed class Options
+    {
+        public string? RepoRoot { get; set; }
+        public string? DocfxPath { get; set; }
+        public string Configuration { get; set; } = "Release";
+        public string? Framework { get; set; }
+        public bool ValidateSamples { get; set; } = true;
+        public bool ChangedOnly { get; set; }
+        public bool Json { get; set; }
+        public bool Help { get; set; }
+    }
+
+    private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest);
+
+    private sealed record ExtensionMethodInfo(string MethodName, string ExtendedType, string DeclaringClass);
+
+    private sealed class NamespaceInfo(string name)
+    {
+        public string Name { get; } = name;
+        public List<ExtensionMethodInfo> ExtensionMethods { get; } = new();
+    }
+
+    private sealed record ApiModel(List<NamespaceInfo> Namespaces);
+
+    private sealed record SampleFence(string File, int FenceIndex, int StartLine, string Code);
+
+    private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
+}
+
+internal sealed class Diagnostic
+{
+    public Diagnostic(string code, string? path, string? @namespace, string message)
+    {
+        Code = code;
+        Path = path;
+        Namespace = @namespace;
+        Message = message;
+    }
+
+    [JsonPropertyName("code")] public string Code { get; }
+    [JsonPropertyName("path")] public string? Path { get; }
+    [JsonPropertyName("namespace")] public string? Namespace { get; }
+    [JsonPropertyName("message")] public string Message { get; }
+}
+
+internal sealed class Summary
+{
+    public int PublicNamespaces { get; set; }
+    public int NamespacePagesValidated { get; set; }
+    public int ExtensionMethods { get; set; }
+    public int SamplesCompiled { get; set; }
+    public int SamplesSkipped { get; set; }
+    public int Errors { get; set; }
+    public int Warnings { get; set; }
+}
+
+internal sealed class Report
+{
+    public string Script { get; set; } = string.Empty;
+    public string RepoRoot { get; set; } = string.Empty;
+    public string? DocfxPath { get; set; }
+    public string? Status { get; set; }
+    public Summary Summary { get; set; } = new();
+    public List<Diagnostic> Errors { get; set; } = new();
+    public List<Diagnostic> Warnings { get; set; } = new();
+}

From 4d7505588998c9b5bd982f094847d05df0b009b3 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 15:17:05 +0200
Subject: [PATCH 02/88] =?UTF-8?q?=F0=9F=93=9D=20document=20dotnet-docfx-di?=
 =?UTF-8?q?gest=20in=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add install command, skill table entry, and 'Why docfx-digest' motivation section to README explaining the skill's approach to preventing API documentation rot through deterministic tooling.
---
 README.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/README.md b/README.md
index 6c96113..0d49a66 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-new-app-sln
 npx skills add https://github.com/codebeltnet/agentic --skill dotnet-new-lib-slnx
 npx skills add https://github.com/codebeltnet/agentic --skill git-remote-release
 npx skills add https://github.com/codebeltnet/agentic --skill dotnet-change-impact
+npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-digest
 # npx skills add https://github.com/codebeltnet/agentic --skill another-skill
 ```
 
@@ -96,6 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-change-impa
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext`, then validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, and compiles every C# documentation sample as a file-based app. Documents public API only, uses a bundled DocFX overwrite reference, requires buildable copy/paste-ready examples for concrete types, preserves manual edits, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -185,6 +187,12 @@ npx skills add https://github.com/codebeltnet/agentic --skill git-remote-release
 npx skills add https://github.com/codebeltnet/agentic --skill dotnet-change-impact
 ```
 
+`dotnet-docfx-digest`
+
+```bash
+npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-digest
+```
+
 ### Why git-visual-commits?
 
 Commit messages are the most-read documentation in any codebase — yet they're usually an afterthought. "fix stuff", "wip", "address PR feedback" tells you nothing six months later. Writing good commits takes discipline, and when you're in flow, it's the first thing that slips.
@@ -519,6 +527,23 @@ Picking the wrong version number is one of the easiest ways to break downstream
 - **Precedence-aware** — mixed releases take the highest required bump,
 - **Special-case savvy** — dependency updates, bug fixes, new overloads, interface and enum changes, analyzers/source generators, TFM/platform support, and performance changes each get the right default and the right escalation triggers.
 
+### Why dotnet-docfx-digest?
+
+API documentation rots the moment code changes. A new public type ships without a namespace page, an extension method never makes it into the `Extension Members` table, a copy/paste example silently stops compiling, and "availability" drifts away from the real target frameworks. The usual fix — telling an agent to "remember to update the docs" — relies on AI memory, which is exactly the thing that fails on the next change.
+
+**dotnet-docfx-digest** moves the rules from prose into deterministic .NET 10 tooling, so guidance persists and verification is real.
+
+- **No-input audits by default** — `Use dotnet-docfx-digest` means inspect the repository, DocFX config, public API, tests, samples, overwrite files, namespace pages, and availability includes, then repair missing complementary documentation that can be derived from evidence before asking any clarifying questions,
+- **Persistent guidance by script, not memory** — `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; running it twice never duplicates the block, and `--check` gates it in CI,
+- **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
+- **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, instead of guessing from text,
+- **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
+- **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
+- **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
+- **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
+- **Preserves manual edits** — additive by default, correcting stale or contradictory statements rather than overwriting hand-written documentation,
+- **CI-friendly** — deterministic exit codes plus `--json` reports let pipelines fail on actual documentation drift instead of trusting an agent's claim that it checked.
+
 ## Repository structure
 
 ```

From 303459b6cea23808941d3aa287b34e14aee8d73e Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 15:38:20 +0200
Subject: [PATCH 03/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20to=20enforce=20mandatory=20overwrite=20examples?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enhance the skill to require explicit examples in DocFX overwrite content for concrete public types and public extension methods, not just namespace pages or extension tables. Updates SKILL.md guidance and checklists, adds a new eval test case for the examples requirement, strengthens script documentation (agents.cs and docfx.cs to validate and report EXAMPLE_MISSING diagnostics), and clarifies overwrite-file usage patterns. Concrete types and extension methods now must have copy/paste-ready examples derived from tests or actual behavior.
---
 README.md                                     |   1 +
 skills/dotnet-docfx-digest/SKILL.md           |  68 +++--
 skills/dotnet-docfx-digest/evals/evals.json   |  13 +
 .../references/docfx-overwrite-files.md       |   7 +-
 skills/dotnet-docfx-digest/scripts/README.md  |  17 +-
 skills/dotnet-docfx-digest/scripts/agents.cs  |  10 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 251 +++++++++++++++++-
 7 files changed, 321 insertions(+), 46 deletions(-)

diff --git a/README.md b/README.md
index 0d49a66..e74591b 100644
--- a/README.md
+++ b/README.md
@@ -538,6 +538,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
 - **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, instead of guessing from text,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
+- **Mandatory overwrite examples** — concrete public types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 02f5a8e..1e011ef 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -17,7 +17,7 @@ This skill is autonomous by default. If the user invokes the skill without namin
 1. Run the repository-instruction script.
 2. Inspect repository guidance, `docfx.json`, source projects, generated metadata, tests, samples, existing overwrite files, namespace pages, and availability includes.
 3. Run the validator to discover missing or stale complementary documentation.
-4. Fill the missing DocFX pieces that can be derived from source evidence.
+4. Fill the missing DocFX pieces that can be derived from source evidence, including overwrite examples for concrete public types and public extension methods.
 5. Ask a concise clarifying question only when inspection exposes a correctness-affecting choice that cannot be resolved from repository evidence.
 
 When this skill is invoked against a repository, the agent must run the deterministic repository-instruction script before completing the task:
@@ -132,8 +132,8 @@ When a public API is added or materially changed, update all relevant documentat
 3. Namespace overview page.
 4. Extension members table when extension methods are involved.
 5. Availability information.
-6. At least one usage example unless the documented item is an abstraction.
-7. Verification artifacts or commands proving the documentation remains buildable and accurate.
+6. At least one usage example in DocFX overwrite content unless the documented item is an abstraction.
+7. Verification artifacts or commands proving the documentation remains buildable and accurate.
 
 A "material change" includes:
 
@@ -153,7 +153,11 @@ A "material change" includes:
 
 ## Examples Are Mandatory
 
-Every automatically documented concrete public type or concrete public member must include at least one example showing how to use it.
+Every automatically documented concrete public type and every public extension method must include at least one example showing how to use it. A namespace overview fly-in or `Extension Members` table is not enough.
+
+Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create one in a Markdown file included by `build.overwrite` in `docfx.json`. Do not stop after editing namespace pages when concrete public types or public extension methods still lack examples.
+
+For concrete public types, prefer an overwrite section whose `uid` is the generated type UID. For public extension methods, add the example to the generated method UID when known; otherwise add it to the extension class UID or the namespace page, but the example must name and demonstrate the extension method.
 
 An example may be omitted only when the item is an abstraction, such as:
 
@@ -357,7 +361,7 @@ Availability must reflect actual project files, conditional compilation, target
 
 ## DocFX Overwrite Files
 
-Use DocFX overwrite files to modify or add content for generated API items without editing generated metadata directly.
+Use DocFX overwrite files to modify or add content for generated API items without editing generated metadata directly.
 
 Overwrite files must include YAML front matter with the target `uid`. Example:
 
@@ -370,17 +374,19 @@ summary: *content
 
 The `uid` must match the generated DocFX UID. Do not guess UIDs. Verify them from generated metadata, existing API pages, source conventions, or DocFX output.
 
-Use overwrite files for:
-
-- Namespace overview pages,
-- Additional conceptual remarks,
-- Examples,
+Use overwrite files for:
+
+- Namespace overview pages,
+- Additional conceptual remarks,
+- Examples,
 - Corrected summaries,
 - Extension-method namespace documentation,
 - Availability notes,
 - Developer-oriented usage guidance.
 
-Do not use overwrite files to conceal inaccurate XML documentation. Correct the source XML documentation when it is wrong.
+Do not use overwrite files to conceal inaccurate XML documentation. Correct the source XML documentation when it is wrong.
+
+When the validator reports `EXAMPLE_MISSING`, create or update DocFX overwrite content for the reported UID instead of treating the missing example as a prose-only issue.
 
 ## XML Documentation Comments
 
@@ -469,12 +475,12 @@ When the user names a changed API or namespace:
 5. Locate `.docfx/docfx.json` or repository-specific DocFX config.
 6. Locate existing overwrite files and namespace pages.
 7. Locate availability include files.
-8. Locate relevant tests that demonstrate the API.
-9. Convert test usage into real-life documentation examples.
-10. Update XML documentation where needed.
-11. Update or create namespace overview pages.
-12. Update extension-member tables.
-13. Update or create overwrite files.
+8. Locate relevant tests that demonstrate the API.
+9. Convert test usage into real-life documentation examples.
+10. Update XML documentation where needed.
+11. Update or create namespace overview pages.
+12. Update extension-member tables.
+13. Update or create overwrite files, including example sections for concrete public types and public extension methods.
 14. Preserve manual edits.
 15. Run `dotnet build`.
 16. Run `dotnet test`.
@@ -491,15 +497,17 @@ When no specific API or namespace is named:
 5. Run `dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --json` to collect deterministic missing-doc findings when the repository is buildable.
 6. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
 7. Determine every namespace containing public API and whether each namespace exposes public extension methods.
-8. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
-9. Add or repair `Extension Members` tables for namespaces with public extension methods.
-10. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
-11. Preserve manual edits and correct stale contradictions instead of replacing whole files.
-12. Run `dotnet build`.
-13. Run `dotnet test`.
-14. Run `docfx .docfx/docfx.json`.
-15. Run `docfx.cs`.
-16. Report verification results and any remaining findings.
+8. Determine every concrete public type and every public extension method that requires an example.
+9. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
+10. Add or repair `Extension Members` tables for namespaces with public extension methods.
+11. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
+12. Create overwrite example sections for concrete public types and public extension methods that have no example yet.
+13. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+14. Run `dotnet build`.
+15. Run `dotnet test`.
+16. Run `docfx .docfx/docfx.json`.
+17. Run `docfx.cs`.
+18. Report verification results and any remaining findings.
 
 ## Namespace Page Template
 
@@ -571,9 +579,11 @@ Before completing documentation work, verify:
 - [ ] Only public API is documented.
 - [ ] Every namespace with public API has a namespace overview page.
 - [ ] Namespaces with public extension methods have an `Extension Members` section.
-- [ ] Extension methods are documented by extended type, not extension class.
-- [ ] Concrete public APIs have at least one example.
-- [ ] Abstractions without examples have a clear reason.
+- [ ] Extension methods are documented by extended type, not extension class.
+- [ ] Concrete public APIs have at least one example.
+- [ ] Public extension methods have at least one example, not only a table entry.
+- [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`.
+- [ ] Abstractions without examples have a clear reason.
 - [ ] Examples are realistic and copy/paste-ready.
 - [ ] Examples compile.
 - [ ] Examples are preferably derived from passing tests.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index cf10fa9..2427390 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -73,6 +73,19 @@
         "Reads references/docfx-overwrite-files.md before creating or repairing DocFX overwrite files",
         "Asks a concise clarifying question only after inspection finds a correctness-affecting unresolved choice"
       ]
+    },
+    {
+      "id": 7,
+      "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but concrete public types and extension methods have no examples. The DocFX config has build.overwrite pointing at .docfx/api/**/*.md.",
+      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits concrete public types and public extension methods for examples, creates or updates DocFX overwrite sections/files included by build.overwrite for missing examples, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, and reruns scripts/docfx.cs until EXAMPLE_MISSING findings are gone.",
+      "expectations": [
+        "Treats namespace overview pages and Extension Members tables as insufficient when examples are missing",
+        "Creates or updates DocFX overwrite content included by build.overwrite for concrete public type examples",
+        "Creates or updates overwrite content for public extension method examples, or places the example on the extension class or namespace page while explicitly demonstrating the method",
+        "Uses generated DocFX UIDs or verified metadata instead of inventing overwrite UIDs",
+        "Runs scripts/docfx.cs and responds to EXAMPLE_MISSING diagnostics before claiming completion",
+        "Compiles changed C# examples or reports the exact verification failure"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
index 13538ae..b72190c 100644
--- a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -9,7 +9,7 @@ Sources:
 
 ## Agent Summary
 
-DocFX treats generated API metadata and Markdown content as models. An overwrite file is a Markdown file that updates a model by matching its `uid`; this lets documentation add or replace properties such as `summary`, `remarks`, examples, conceptual content, and namespace-level guidance without editing generated metadata.
+DocFX treats generated API metadata and Markdown content as models. An overwrite file is a Markdown file that updates a model by matching its `uid`; this lets documentation add or replace properties such as `summary`, `remarks`, `example`, conceptual content, and namespace-level guidance without editing generated metadata.
 
 Every overwrite section starts with YAML front matter delimited by `---`. The front matter must include `uid`, and the value must match the generated model UID. Do not guess UIDs. Verify them from generated metadata, existing API pages, source conventions, DocFX output, or `docfx build --exportRawModel`.
 
@@ -27,12 +27,14 @@ If `*content` is not used, DocFX assigns the Markdown body to the default concep
 
 DocFX applies overwrite models by `uid`. If the same `uid` appears more than once in one overwrite file, later sections in that same file override earlier sections. Across different overwrite files, ordering is not deterministic, so keep competing sections for the same `uid` together or consolidate them.
 
-Overwrite models should follow the target model shape. Existing properties can be replaced or merged depending on the DocFX model rules; properties not already present can be added. For managed reference docs, common useful overwrite targets include `summary`, `remarks`, `example`, `exceptions`, `see`, `seealso`, and parameter descriptions under `syntax`.
+Overwrite models should follow the target model shape. Existing properties can be replaced or merged depending on the DocFX model rules; properties not already present can be added. For managed reference docs, common useful overwrite targets include `summary`, `remarks`, `example`, `exceptions`, `see`, `seealso`, and parameter descriptions under `syntax`. The official managed reference model lists `example` as an overwriteable property, so usage examples can be added through overwrite sections when generated metadata lacks them.
 
 The `build.overwrite` entry in `docfx.json` tells DocFX which conceptual Markdown files contain overwrite sections. All relative paths in `docfx.json` are resolved relative to the directory containing `docfx.json`, not necessarily the repository root.
 
 When a repository has no obvious overwrite location, inspect `docfx.json` first. Look at `build.content`, `build.overwrite`, `metadata.dest`, include paths, and existing Markdown layout before deciding where a new namespace page belongs.
 
+If a concrete public type or public extension method lacks an example, create a matching overwrite section in a Markdown file that is included by `build.overwrite`. Namespace overview pages and `Extension Members` tables complement examples; they do not replace examples.
+
 ## Practical Rules
 
 - Run `agents.cs` before finishing so root `AGENTS.md` receives persistent DocFX maintenance guidance.
@@ -40,6 +42,7 @@ When a repository has no obvious overwrite location, inspect `docfx.json` first.
 - Correct bad XML comments at source when the generated summary is wrong.
 - Use namespace overview pages for namespace fly-ins and extension-member tables.
 - Keep examples and remarks close to the API item or namespace they explain.
+- Add examples through overwrite sections when XML comments or generated metadata do not already provide developer-friendly examples.
 - Preserve existing hand-written overwrite sections unless they are stale or contradictory.
 - Prefer additive edits, but remove or revise contradictions.
 - Re-run `docfx.cs` after edits so missing namespace pages, extension tables, availability, and sample compilation are checked deterministically.
diff --git a/skills/dotnet-docfx-digest/scripts/README.md b/skills/dotnet-docfx-digest/scripts/README.md
index a65f2c7..d68f53e 100644
--- a/skills/dotnet-docfx-digest/scripts/README.md
+++ b/skills/dotnet-docfx-digest/scripts/README.md
@@ -52,10 +52,11 @@ Exit codes:
 
 Validates the deterministic documentation requirements against the *compiled*
 repository, not against text in `SKILL.md`. It builds the solution, discovers
-public API from compiled assemblies (preferring reference assemblies) via
-`System.Reflection.MetadataLoadContext`, then checks namespace overview pages,
-extension-member tables, availability, and compiles every C# documentation
-sample as a file-based app.
+public API from compiled assemblies (preferring reference assemblies) via
+`System.Reflection.MetadataLoadContext`, then checks namespace overview pages,
+extension-member tables, availability, required overwrite examples for concrete
+public types and public extension methods, and compiles every C# documentation
+sample as a file-based app.
 
 ```bash
 dotnet run --file docfx.cs -- --repo-root .
@@ -85,10 +86,10 @@ Exit codes:
 
 Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`,
 `DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`,
-`NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`,
-`NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`,
-`EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`,
-`SAMPLE_COMPILE_FAILED`, and `SAMPLE_SKIP_REASON_MISSING`.
+`NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`,
+`NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`,
+`EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`,
+`EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, and `SAMPLE_SKIP_REASON_MISSING`.
 
 ### Sample opt-out
 
diff --git a/skills/dotnet-docfx-digest/scripts/agents.cs b/skills/dotnet-docfx-digest/scripts/agents.cs
index 20ccc97..3db2670 100644
--- a/skills/dotnet-docfx-digest/scripts/agents.cs
+++ b/skills/dotnet-docfx-digest/scripts/agents.cs
@@ -30,9 +30,13 @@ internal static class AgentsScript
 
         Documentation updates must cover public API only. Do not document private or internal types or members. Do not create namespace overview pages for namespaces that contain no public API.
 
-        For concrete public APIs, include at least one realistic, copy/paste-ready usage example unless the item is an abstraction. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage.
-
-        All added or changed code samples must be deterministic and verified to compile. Do not add pseudo-code, ellipses, hidden test helpers, or examples that rely on unverified behavior.
+        For concrete public APIs, include at least one realistic, copy/paste-ready usage example unless the item is an abstraction. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage.
+
+        Missing examples must be added through DocFX overwrite content included by `build.overwrite` in `docfx.json`. Namespace overview text and `Extension Members` tables are not substitutes for examples.
+
+        Public extension methods must have examples too. Listing an extension method in an `Extension Members` table is required, but it is not enough.
+
+        All added or changed code samples must be deterministic and verified to compile. Do not add pseudo-code, ellipses, hidden test helpers, or examples that rely on unverified behavior.
 
         Every namespace containing public API must have a DocFX namespace overview page named after the namespace, such as `X.Y.Z.md`, using DocFX overwrite front matter with the namespace `uid`.
 
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 80a0574..387456f 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -167,6 +167,7 @@ private static int Validate(Options options)
         }
 
         report.Summary.PublicNamespaces = api.Namespaces.Count;
+        report.Summary.ConcreteApiTargets = api.ConcreteTargets.Count;
         report.Summary.ExtensionMethods = api.Namespaces.Sum(n => n.ExtensionMethods.Count);
 
         // 8. Discover DocFX Markdown files under the workspace.
@@ -194,7 +195,10 @@ private static int Validate(Options options)
             report.Summary.NamespacePagesValidated++;
         }
 
-        // 12-13. Extract and compile C# documentation samples.
+        // 12. Verify mandatory examples exist before compiling the examples that were found.
+        ValidateRequiredExamples(repoRoot, markdownFiles, api, options, changedFiles, report);
+
+        // 13. Extract and compile C# documentation samples.
         if (options.ValidateSamples)
         {
             ValidateSamples(repoRoot, markdownFiles, libraryProjects, options, changedFiles, report);
@@ -438,7 +442,7 @@ private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string co
 
         if (assemblyPaths.Count == 0)
         {
-            return new ApiModel(new List<NamespaceInfo>());
+            return new ApiModel(new List<NamespaceInfo>(), new List<ApiTargetInfo>());
         }
 
         // Resolve dependencies from the runtime directory and the assemblies' own output folders.
@@ -507,11 +511,51 @@ private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string co
                     namespaces[nsName] = info;
                 }
 
+                CollectApiTargets(type, info);
                 CollectExtensionMethods(type, info);
             }
         }
 
-        return new ApiModel(namespaces.Values.ToList());
+        var concreteTargets = namespaces.Values
+            .SelectMany(ns => ns.ConcreteTargets)
+            .OrderBy(t => t.Uid, StringComparer.Ordinal)
+            .ToList();
+
+        return new ApiModel(namespaces.Values.ToList(), concreteTargets);
+    }
+
+    private static void CollectApiTargets(Type type, NamespaceInfo ns)
+    {
+        var typeUid = TypeUid(type);
+        if (typeUid is null)
+        {
+            return;
+        }
+
+        if (IsConcreteDocumentableType(type))
+        {
+            ns.ConcreteTargets.Add(new ApiTargetInfo(typeUid, ns.Name, ApiTargetKind.Type, SimpleTypeName(type)));
+        }
+
+        MethodInfo[] methods;
+        try
+        {
+            methods = type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly);
+        }
+        catch
+        {
+            return;
+        }
+
+        foreach (var method in methods)
+        {
+            if (!method.IsPublic || method.IsSpecialName || method.IsAbstract || !HasExtensionAttribute(method))
+            {
+                continue;
+            }
+
+            ns.ConcreteTargets.Add(new ApiTargetInfo(MethodUid(typeUid, method), ns.Name, ApiTargetKind.ExtensionMethod, method.Name, typeUid));
+        }
     }
 
     private static void CollectExtensionMethods(Type type, NamespaceInfo ns)
@@ -592,6 +636,63 @@ private static bool IsExternallyVisible(Type type)
         }
     }
 
+    private static bool IsConcreteDocumentableType(Type type)
+    {
+        if (type.IsInterface || type.IsAbstract || type.IsEnum || type.IsValueType)
+        {
+            return false;
+        }
+
+        if (InheritsFrom(type, "System.Attribute") || InheritsFrom(type, "System.MulticastDelegate"))
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static bool InheritsFrom(Type type, string baseTypeFullName)
+    {
+        try
+        {
+            var current = type.BaseType;
+            while (current is not null)
+            {
+                if (string.Equals(current.FullName, baseTypeFullName, StringComparison.Ordinal))
+                {
+                    return true;
+                }
+
+                current = current.BaseType;
+            }
+        }
+        catch
+        {
+            // ignore
+        }
+
+        return false;
+    }
+
+    private static string? TypeUid(Type type)
+    {
+        var fullName = type.FullName;
+        if (string.IsNullOrWhiteSpace(fullName))
+        {
+            return null;
+        }
+
+        return fullName.Replace('+', '.');
+    }
+
+    private static string MethodUid(string typeUid, MethodInfo method)
+    {
+        var parameters = method.GetParameters()
+            .Select(p => TypeUid(p.ParameterType) ?? SimpleTypeName(p.ParameterType));
+
+        return typeUid + "." + method.Name + "(" + string.Join(",", parameters) + ")";
+    }
+
     private static string SimpleTypeName(Type type)
     {
         var name = type.Name;
@@ -786,6 +887,95 @@ private static bool HasAvailability(string body)
         return Regex.IsMatch(body, @"(?im)^\s*Availability\s*:");
     }
 
+    // ----------------------------------------------------------------------
+    // Required example validation
+    // ----------------------------------------------------------------------
+
+    private static void ValidateRequiredExamples(string repoRoot, List<string> markdownFiles, ApiModel api,
+        Options options, HashSet<string>? changedFiles, Report report)
+    {
+        if (options.ChangedOnly && changedFiles is not null)
+        {
+            return;
+        }
+
+        var sections = new List<OverwriteSection>();
+        foreach (var md in markdownFiles)
+        {
+            sections.AddRange(ExtractOverwriteSections(md));
+        }
+
+        foreach (var target in api.ConcreteTargets)
+        {
+            var candidates = sections.Where(s => IsExampleCandidate(s, target)).ToList();
+            if (candidates.Any(s => HasExampleForTarget(s, target)))
+            {
+                report.Summary.RequiredExamples++;
+                continue;
+            }
+
+            var expectedUid = target.Kind == ApiTargetKind.Type
+                ? target.Uid
+                : target.DeclaringTypeUid ?? target.Uid;
+
+            var message = target.Kind == ApiTargetKind.Type
+                ? $"Concrete public type `{target.DisplayName}` requires a DocFX overwrite section with uid `{target.Uid}` and an Examples section containing a C# code fence."
+                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}`, its declaring type uid `{expectedUid}`, or the namespace page `{target.Namespace}`.";
+
+            report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", null, target.Namespace, message));
+        }
+    }
+
+    private static bool IsExampleCandidate(OverwriteSection section, ApiTargetInfo target)
+    {
+        if (string.Equals(section.Uid, target.Uid, StringComparison.Ordinal))
+        {
+            return true;
+        }
+
+        if (target.Kind == ApiTargetKind.ExtensionMethod)
+        {
+            return string.Equals(section.Uid, target.DeclaringTypeUid, StringComparison.Ordinal) ||
+                   string.Equals(section.Uid, target.Namespace, StringComparison.Ordinal);
+        }
+
+        return false;
+    }
+
+    private static bool HasExampleForTarget(OverwriteSection section, ApiTargetInfo target)
+    {
+        if (!HasExampleSectionWithCSharpFence(section.Body))
+        {
+            return false;
+        }
+
+        if (target.Kind == ApiTargetKind.ExtensionMethod &&
+            !section.Body.Contains(target.DisplayName, StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static bool HasExampleSectionWithCSharpFence(string body)
+    {
+        var match = Regex.Match(body, @"(?im)^#{2,5}\s+Examples?\s*$");
+        if (!match.Success)
+        {
+            return false;
+        }
+
+        var section = body[match.Index..];
+        var nextHeading = Regex.Match(section[match.Length..], @"(?im)^#{1,5}\s+\S");
+        if (nextHeading.Success)
+        {
+            section = section[..(match.Length + nextHeading.Index)];
+        }
+
+        return Regex.IsMatch(section, @"(?im)^```\s*(csharp|cs)\s*$");
+    }
+
     // ----------------------------------------------------------------------
     // Sample validation
     // ----------------------------------------------------------------------
@@ -924,6 +1114,45 @@ private static List<SampleFence> ExtractFences(string mdFile)
         return fences;
     }
 
+    private static List<OverwriteSection> ExtractOverwriteSections(string mdFile)
+    {
+        var sections = new List<OverwriteSection>();
+        string text;
+        try
+        {
+            text = File.ReadAllText(mdFile);
+        }
+        catch
+        {
+            return sections;
+        }
+
+        var normalized = text.Replace("\r\n", "\n").Replace("\r", "\n");
+        var matches = Regex.Matches(normalized, @"(?ms)^---\s*\n(?<yaml>.*?)^---\s*$");
+        for (var i = 0; i < matches.Count; i++)
+        {
+            var match = matches[i];
+            var yaml = match.Groups["yaml"].Value;
+            var uid = ReadYamlScalar(yaml, "uid");
+            if (string.IsNullOrWhiteSpace(uid))
+            {
+                continue;
+            }
+
+            var bodyStart = match.Index + match.Length;
+            if (bodyStart < normalized.Length && normalized[bodyStart] == '\n')
+            {
+                bodyStart++;
+            }
+
+            var bodyEnd = i + 1 < matches.Count ? matches[i + 1].Index : normalized.Length;
+            var body = bodyEnd > bodyStart ? normalized[bodyStart..bodyEnd] : string.Empty;
+            sections.Add(new OverwriteSection(mdFile, uid, body));
+        }
+
+        return sections;
+    }
+
     private static (bool Found, string Reason) FindSkip(string code)
     {
         foreach (var line in code.Split('\n'))
@@ -1124,6 +1353,7 @@ private static int Emit(Options options, Report report, ExitCode code, string co
 
             Console.WriteLine(
                 $"  Summary: namespaces={report.Summary.PublicNamespaces}, pages={report.Summary.NamespacePagesValidated}, " +
+                $"concreteTargets={report.Summary.ConcreteApiTargets}, requiredExamples={report.Summary.RequiredExamples}, " +
                 $"extMethods={report.Summary.ExtensionMethods}, samplesCompiled={report.Summary.SamplesCompiled}, " +
                 $"samplesSkipped={report.Summary.SamplesSkipped}, errors={report.Summary.Errors}, warnings={report.Summary.Warnings}");
         }
@@ -1286,16 +1516,27 @@ private sealed record ProjectInfo(string Path, string AssemblyName, List<string>
 
     private sealed record ExtensionMethodInfo(string MethodName, string ExtendedType, string DeclaringClass);
 
+    private sealed record ApiTargetInfo(string Uid, string Namespace, ApiTargetKind Kind, string DisplayName, string? DeclaringTypeUid = null);
+
+    private enum ApiTargetKind
+    {
+        Type,
+        ExtensionMethod
+    }
+
     private sealed class NamespaceInfo(string name)
     {
         public string Name { get; } = name;
+        public List<ApiTargetInfo> ConcreteTargets { get; } = new();
         public List<ExtensionMethodInfo> ExtensionMethods { get; } = new();
     }
 
-    private sealed record ApiModel(List<NamespaceInfo> Namespaces);
+    private sealed record ApiModel(List<NamespaceInfo> Namespaces, List<ApiTargetInfo> ConcreteTargets);
 
     private sealed record SampleFence(string File, int FenceIndex, int StartLine, string Code);
 
+    private sealed record OverwriteSection(string File, string Uid, string Body);
+
     private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
 }
 
@@ -1319,6 +1560,8 @@ internal sealed class Summary
 {
     public int PublicNamespaces { get; set; }
     public int NamespacePagesValidated { get; set; }
+    public int ConcreteApiTargets { get; set; }
+    public int RequiredExamples { get; set; }
     public int ExtensionMethods { get; set; }
     public int SamplesCompiled { get; set; }
     public int SamplesSkipped { get; set; }

From 8923de1ebd558187a0db29b0aa64e5f6be4d6198 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 15:50:03 +0200
Subject: [PATCH 04/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20clarify=20that=20typ?=
 =?UTF-8?q?e=20examples=20must=20appear=20on=20type=20pages?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refine dotnet-docfx-digest skill documentation to emphasize that public non-abstraction type examples must be placed on the generated type-page/overwrite section, not only on namespace overview pages. Updates SKILL.md guidance, evals expectations, reference documentation, and helper script docs to consistently clarify this requirement.
---
 skills/dotnet-docfx-digest/SKILL.md           | 20 ++++++++++---------
 skills/dotnet-docfx-digest/evals/evals.json   |  7 ++++---
 .../references/docfx-overwrite-files.md       |  2 +-
 skills/dotnet-docfx-digest/scripts/README.md  |  4 ++--
 4 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 1e011ef..96c531c 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -17,7 +17,7 @@ This skill is autonomous by default. If the user invokes the skill without namin
 1. Run the repository-instruction script.
 2. Inspect repository guidance, `docfx.json`, source projects, generated metadata, tests, samples, existing overwrite files, namespace pages, and availability includes.
 3. Run the validator to discover missing or stale complementary documentation.
-4. Fill the missing DocFX pieces that can be derived from source evidence, including overwrite examples for concrete public types and public extension methods.
+4. Fill the missing DocFX pieces that can be derived from source evidence, including type-page overwrite examples for public non-abstraction types and public extension methods.
 5. Ask a concise clarifying question only when inspection exposes a correctness-affecting choice that cannot be resolved from repository evidence.
 
 When this skill is invoked against a repository, the agent must run the deterministic repository-instruction script before completing the task:
@@ -153,11 +153,13 @@ A "material change" includes:
 
 ## Examples Are Mandatory
 
-Every automatically documented concrete public type and every public extension method must include at least one example showing how to use it. A namespace overview fly-in or `Extension Members` table is not enough.
+Every automatically documented public non-abstraction type and every public extension method must include at least one example showing how to use it. A namespace overview fly-in or `Extension Members` table is not enough.
 
-Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create one in a Markdown file included by `build.overwrite` in `docfx.json`. Do not stop after editing namespace pages when concrete public types or public extension methods still lack examples.
+Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create one in a Markdown file included by `build.overwrite` in `docfx.json`. Do not stop after editing namespace pages when public non-abstraction types or public extension methods still lack examples.
 
-For concrete public types, prefer an overwrite section whose `uid` is the generated type UID. For public extension methods, add the example to the generated method UID when known; otherwise add it to the extension class UID or the namespace page, but the example must name and demonstrate the extension method.
+For public non-abstraction types, the example must belong to the generated type page/overwrite section for that type `uid`. For example, if `Class1` is public and not an abstraction, add an `Examples` section to the DocFX overwrite content for `Class1` so the example appears on `Class1.md` at the bottom of the generated API page. A namespace page example does not satisfy the type-page example requirement for `Class1`.
+
+For public extension methods, add the example to the generated method UID when known; otherwise add it to the extension class UID or the namespace page, but the example must name and demonstrate the extension method.
 
 An example may be omitted only when the item is an abstraction, such as:
 
@@ -480,7 +482,7 @@ When the user names a changed API or namespace:
 10. Update XML documentation where needed.
 11. Update or create namespace overview pages.
 12. Update extension-member tables.
-13. Update or create overwrite files, including example sections for concrete public types and public extension methods.
+13. Update or create overwrite files, including type-page example sections for public non-abstraction types and example sections for public extension methods.
 14. Preserve manual edits.
 15. Run `dotnet build`.
 16. Run `dotnet test`.
@@ -497,11 +499,11 @@ When no specific API or namespace is named:
 5. Run `dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --json` to collect deterministic missing-doc findings when the repository is buildable.
 6. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
 7. Determine every namespace containing public API and whether each namespace exposes public extension methods.
-8. Determine every concrete public type and every public extension method that requires an example.
+8. Determine every public non-abstraction type and every public extension method that requires an example.
 9. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
 10. Add or repair `Extension Members` tables for namespaces with public extension methods.
 11. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
-12. Create overwrite example sections for concrete public types and public extension methods that have no example yet.
+12. Create type-page overwrite example sections for public non-abstraction types and example sections for public extension methods that have no example yet.
 13. Preserve manual edits and correct stale contradictions instead of replacing whole files.
 14. Run `dotnet build`.
 15. Run `dotnet test`.
@@ -533,7 +535,7 @@ Remove the `Extension Members` section when the namespace has no public extensio
 
 ## Type Example Template
 
-Use this shape for concrete public type examples:
+Use this shape for public non-abstraction type examples. Put this on the generated type page/overwrite section for the type `uid`; for a public `Class1`, the example belongs on the `Class1` API page, not only on the namespace page.
 
 ````markdown
 ### Examples
@@ -580,7 +582,7 @@ Before completing documentation work, verify:
 - [ ] Every namespace with public API has a namespace overview page.
 - [ ] Namespaces with public extension methods have an `Extension Members` section.
 - [ ] Extension methods are documented by extended type, not extension class.
-- [ ] Concrete public APIs have at least one example.
+- [ ] Public non-abstraction types have at least one type-page example.
 - [ ] Public extension methods have at least one example, not only a table entry.
 - [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`.
 - [ ] Abstractions without examples have a clear reason.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 2427390..461d89d 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -76,11 +76,12 @@
     },
     {
       "id": 7,
-      "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but concrete public types and extension methods have no examples. The DocFX config has build.overwrite pointing at .docfx/api/**/*.md.",
-      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits concrete public types and public extension methods for examples, creates or updates DocFX overwrite sections/files included by build.overwrite for missing examples, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, and reruns scripts/docfx.cs until EXAMPLE_MISSING findings are gone.",
+      "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but public non-abstraction types such as `Class1` and public extension methods have no examples. The DocFX config has build.overwrite pointing at .docfx/api/**/*.md.",
+      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates or updates DocFX overwrite sections/files included by build.overwrite for missing examples, puts type examples on the generated type page/overwrite section such as Class1.md for Class1, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, and reruns scripts/docfx.cs until EXAMPLE_MISSING findings are gone.",
       "expectations": [
         "Treats namespace overview pages and Extension Members tables as insufficient when examples are missing",
-        "Creates or updates DocFX overwrite content included by build.overwrite for concrete public type examples",
+        "Creates or updates DocFX overwrite content included by build.overwrite for public non-abstraction type examples",
+        "Places a public Class1 example on the Class1 type page/overwrite section rather than only on the namespace page",
         "Creates or updates overwrite content for public extension method examples, or places the example on the extension class or namespace page while explicitly demonstrating the method",
         "Uses generated DocFX UIDs or verified metadata instead of inventing overwrite UIDs",
         "Runs scripts/docfx.cs and responds to EXAMPLE_MISSING diagnostics before claiming completion",
diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
index b72190c..61236ef 100644
--- a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -33,7 +33,7 @@ The `build.overwrite` entry in `docfx.json` tells DocFX which conceptual Markdow
 
 When a repository has no obvious overwrite location, inspect `docfx.json` first. Look at `build.content`, `build.overwrite`, `metadata.dest`, include paths, and existing Markdown layout before deciding where a new namespace page belongs.
 
-If a concrete public type or public extension method lacks an example, create a matching overwrite section in a Markdown file that is included by `build.overwrite`. Namespace overview pages and `Extension Members` tables complement examples; they do not replace examples.
+If a public non-abstraction type lacks an example, create a matching type-UID overwrite section in a Markdown file that is included by `build.overwrite` so the example appears on the generated type API page. For example, a public `Class1` needs an example on the `Class1` API page. Namespace overview pages and `Extension Members` tables complement examples; they do not replace type-page examples.
 
 ## Practical Rules
 
diff --git a/skills/dotnet-docfx-digest/scripts/README.md b/skills/dotnet-docfx-digest/scripts/README.md
index d68f53e..9e92d90 100644
--- a/skills/dotnet-docfx-digest/scripts/README.md
+++ b/skills/dotnet-docfx-digest/scripts/README.md
@@ -54,8 +54,8 @@ Validates the deterministic documentation requirements against the *compiled*
 repository, not against text in `SKILL.md`. It builds the solution, discovers
 public API from compiled assemblies (preferring reference assemblies) via
 `System.Reflection.MetadataLoadContext`, then checks namespace overview pages,
-extension-member tables, availability, required overwrite examples for concrete
-public types and public extension methods, and compiles every C# documentation
+extension-member tables, availability, required type-page overwrite examples for
+public non-abstraction types and public extension methods, and compiles every C# documentation
 sample as a file-based app.
 
 ```bash

From ee010444373c839d1cb606169586409ed1c5b55b Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 15:50:18 +0200
Subject: [PATCH 05/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20simplify=20validator?=
 =?UTF-8?q?=20internal=20concepts=20and=20naming?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rename IsConcreteDocumentableType to IsExampleRequiredType and ConcreteTargets to RequiredExampleTargets throughout the validator. Simplify the type classification logic by removing specialized checks for enums, value types, attributes, and delegates, keeping only the core distinction: interfaces and abstractions do not require examples. Updates summary reporting and error messages to use clearer terminology.
---
 skills/dotnet-docfx-digest/scripts/agents.cs |  4 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs  | 84 +++++++-------------
 2 files changed, 30 insertions(+), 58 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/agents.cs b/skills/dotnet-docfx-digest/scripts/agents.cs
index 3db2670..fdad331 100644
--- a/skills/dotnet-docfx-digest/scripts/agents.cs
+++ b/skills/dotnet-docfx-digest/scripts/agents.cs
@@ -30,9 +30,9 @@ internal static class AgentsScript
 
         Documentation updates must cover public API only. Do not document private or internal types or members. Do not create namespace overview pages for namespaces that contain no public API.
 
-        For concrete public APIs, include at least one realistic, copy/paste-ready usage example unless the item is an abstraction. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage.
+        For public non-abstraction types, include at least one realistic, copy/paste-ready usage example on the generated type page/overwrite section for that type UID. For example, a public `Class1` requires an example on the `Class1` API page, not only on the namespace page. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage.
 
-        Missing examples must be added through DocFX overwrite content included by `build.overwrite` in `docfx.json`. Namespace overview text and `Extension Members` tables are not substitutes for examples.
+        Missing examples must be added through DocFX overwrite content included by `build.overwrite` in `docfx.json`. Namespace overview text and `Extension Members` tables are not substitutes for type-page examples.
 
         Public extension methods must have examples too. Listing an extension method in an `Extension Members` table is required, but it is not enough.
 
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 387456f..1444414 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -167,7 +167,7 @@ private static int Validate(Options options)
         }
 
         report.Summary.PublicNamespaces = api.Namespaces.Count;
-        report.Summary.ConcreteApiTargets = api.ConcreteTargets.Count;
+        report.Summary.RequiredExampleTargets = api.RequiredExampleTargets.Count;
         report.Summary.ExtensionMethods = api.Namespaces.Sum(n => n.ExtensionMethods.Count);
 
         // 8. Discover DocFX Markdown files under the workspace.
@@ -516,12 +516,12 @@ private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string co
             }
         }
 
-        var concreteTargets = namespaces.Values
-            .SelectMany(ns => ns.ConcreteTargets)
-            .OrderBy(t => t.Uid, StringComparer.Ordinal)
-            .ToList();
-
-        return new ApiModel(namespaces.Values.ToList(), concreteTargets);
+        var requiredExampleTargets = namespaces.Values
+            .SelectMany(ns => ns.RequiredExampleTargets)
+            .OrderBy(t => t.Uid, StringComparer.Ordinal)
+            .ToList();
+
+        return new ApiModel(namespaces.Values.ToList(), requiredExampleTargets);
     }
 
     private static void CollectApiTargets(Type type, NamespaceInfo ns)
@@ -532,9 +532,9 @@ private static void CollectApiTargets(Type type, NamespaceInfo ns)
             return;
         }
 
-        if (IsConcreteDocumentableType(type))
-        {
-            ns.ConcreteTargets.Add(new ApiTargetInfo(typeUid, ns.Name, ApiTargetKind.Type, SimpleTypeName(type)));
+        if (IsExampleRequiredType(type))
+        {
+            ns.RequiredExampleTargets.Add(new ApiTargetInfo(typeUid, ns.Name, ApiTargetKind.Type, SimpleTypeName(type)));
         }
 
         MethodInfo[] methods;
@@ -554,7 +554,7 @@ private static void CollectApiTargets(Type type, NamespaceInfo ns)
                 continue;
             }
 
-            ns.ConcreteTargets.Add(new ApiTargetInfo(MethodUid(typeUid, method), ns.Name, ApiTargetKind.ExtensionMethod, method.Name, typeUid));
+            ns.RequiredExampleTargets.Add(new ApiTargetInfo(MethodUid(typeUid, method), ns.Name, ApiTargetKind.ExtensionMethod, method.Name, typeUid));
         }
     }
 
@@ -636,43 +636,15 @@ private static bool IsExternallyVisible(Type type)
         }
     }
 
-    private static bool IsConcreteDocumentableType(Type type)
-    {
-        if (type.IsInterface || type.IsAbstract || type.IsEnum || type.IsValueType)
-        {
-            return false;
-        }
-
-        if (InheritsFrom(type, "System.Attribute") || InheritsFrom(type, "System.MulticastDelegate"))
-        {
-            return false;
-        }
-
-        return true;
-    }
-
-    private static bool InheritsFrom(Type type, string baseTypeFullName)
-    {
-        try
-        {
-            var current = type.BaseType;
-            while (current is not null)
-            {
-                if (string.Equals(current.FullName, baseTypeFullName, StringComparison.Ordinal))
-                {
-                    return true;
-                }
-
-                current = current.BaseType;
-            }
-        }
-        catch
-        {
-            // ignore
-        }
-
-        return false;
-    }
+    private static bool IsExampleRequiredType(Type type)
+    {
+        if (type.IsInterface || type.IsAbstract)
+        {
+            return false;
+        }
+
+        return true;
+    }
 
     private static string? TypeUid(Type type)
     {
@@ -905,7 +877,7 @@ private static void ValidateRequiredExamples(string repoRoot, List<string> markd
             sections.AddRange(ExtractOverwriteSections(md));
         }
 
-        foreach (var target in api.ConcreteTargets)
+        foreach (var target in api.RequiredExampleTargets)
         {
             var candidates = sections.Where(s => IsExampleCandidate(s, target)).ToList();
             if (candidates.Any(s => HasExampleForTarget(s, target)))
@@ -918,9 +890,9 @@ private static void ValidateRequiredExamples(string repoRoot, List<string> markd
                 ? target.Uid
                 : target.DeclaringTypeUid ?? target.Uid;
 
-            var message = target.Kind == ApiTargetKind.Type
-                ? $"Concrete public type `{target.DisplayName}` requires a DocFX overwrite section with uid `{target.Uid}` and an Examples section containing a C# code fence."
-                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}`, its declaring type uid `{expectedUid}`, or the namespace page `{target.Namespace}`.";
+            var message = target.Kind == ApiTargetKind.Type
+                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to the generated type page/overwrite section for uid `{target.Uid}` (for example `{target.DisplayName}.md` when that is the repository's API-page convention)."
+                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}`, its declaring type uid `{expectedUid}`, or the namespace page `{target.Namespace}`.";
 
             report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", null, target.Namespace, message));
         }
@@ -1353,7 +1325,7 @@ private static int Emit(Options options, Report report, ExitCode code, string co
 
             Console.WriteLine(
                 $"  Summary: namespaces={report.Summary.PublicNamespaces}, pages={report.Summary.NamespacePagesValidated}, " +
-                $"concreteTargets={report.Summary.ConcreteApiTargets}, requiredExamples={report.Summary.RequiredExamples}, " +
+                $"requiredExampleTargets={report.Summary.RequiredExampleTargets}, requiredExamples={report.Summary.RequiredExamples}, " +
                 $"extMethods={report.Summary.ExtensionMethods}, samplesCompiled={report.Summary.SamplesCompiled}, " +
                 $"samplesSkipped={report.Summary.SamplesSkipped}, errors={report.Summary.Errors}, warnings={report.Summary.Warnings}");
         }
@@ -1527,11 +1499,11 @@ private enum ApiTargetKind
     private sealed class NamespaceInfo(string name)
     {
         public string Name { get; } = name;
-        public List<ApiTargetInfo> ConcreteTargets { get; } = new();
+        public List<ApiTargetInfo> RequiredExampleTargets { get; } = new();
         public List<ExtensionMethodInfo> ExtensionMethods { get; } = new();
     }
 
-    private sealed record ApiModel(List<NamespaceInfo> Namespaces, List<ApiTargetInfo> ConcreteTargets);
+    private sealed record ApiModel(List<NamespaceInfo> Namespaces, List<ApiTargetInfo> RequiredExampleTargets);
 
     private sealed record SampleFence(string File, int FenceIndex, int StartLine, string Code);
 
@@ -1560,7 +1532,7 @@ internal sealed class Summary
 {
     public int PublicNamespaces { get; set; }
     public int NamespacePagesValidated { get; set; }
-    public int ConcreteApiTargets { get; set; }
+    public int RequiredExampleTargets { get; set; }
     public int RequiredExamples { get; set; }
     public int ExtensionMethods { get; set; }
     public int SamplesCompiled { get; set; }

From 7680636890c5c5e65df0e0451bf37cb1ecce72e0 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 15:50:28 +0200
Subject: [PATCH 06/88] =?UTF-8?q?=F0=9F=92=AC=20add=20markdown=20formattin?=
 =?UTF-8?q?g=20guidelines?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add section to AGENTS.md clarifying that all markdown files in the repository must use natural paragraph flow without artificial column-width breaks or hard-wrapped mid-sentence content. This improves readability across devices, eases maintenance, and produces cleaner git diffs.
---
 AGENTS.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 3bb301d..3ff421a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -141,6 +141,12 @@ When committing changes to this repo, group by technology and logical purpose 
 - Template files (`.csproj`, `.yml`, `.cs`) get their own commit(s)
 - Documentation updates (`README.md`, `CONTRIBUTING.md`) get their own commit
 
+## Markdown Formatting
+
+All markdown files in this repository must use natural paragraph flow. Do not artificially break paragraphs at fixed column widths or insert hard line breaks within sentences. Paragraphs should flow as complete thoughts, allowing line wrapping to be determined by the reader's viewport or rendering engine, not by arbitrary character limits.
+
+**Why:** Natural paragraphs are more readable, easier to edit, and render correctly across all devices and markdown renderers. Artificially clipped paragraphs create maintenance friction and look awkward in source control diffs.
+
 ## README Sync
 
 After modifying any skill (`SKILL.md`, `FORMS.md`) or repo-level config (`AGENTS.md`), **always update `README.md` before considering the task done**. This is a mandatory gate — not a nice-to-have. The README's "Available Skills" table, install examples, and "Why" sections must reflect the current state of all skills. A new skill without a README entry is incomplete work.

From 0d5f9741d999c0b8b34feba2cbb681a815fdb440 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 15:50:37 +0200
Subject: [PATCH 07/88] =?UTF-8?q?=F0=9F=93=9D=20sync=20README=20with=20ref?=
 =?UTF-8?q?ined=20type-example=20requirements?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update README.md dotnet-docfx-digest section to reflect refined guidance: public non-abstraction types now require examples on the generated type page/overwrite section, not just on namespace pages. Clarifies that type-page examples are mandatory and distinct from namespace overview documentation.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e74591b..9c90e1c 100644
--- a/README.md
+++ b/README.md
@@ -538,7 +538,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
 - **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, instead of guessing from text,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
-- **Mandatory overwrite examples** — concrete public types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`,
+- **Mandatory overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; type examples belong on the generated type page such as `Class1.md`, and namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,

From a271798dce03cbcb593007da9eaae6eb89e589b0 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 16:40:08 +0200
Subject: [PATCH 08/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20to=20verify=20docfx=20builds=20in=20temp=20workspa?=
 =?UTF-8?q?ce?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add --verify-docfx-build flag to docfx.cs script so generated API YAML, manifests, and configured site output stay outside the working tree. Updates SKILL.md instructions and verification checklist to run DocFX CLI in a temporary copy of the repository. Updates evals and supporting documentation to reflect the new verification workflow.
---
 skills/dotnet-docfx-digest/SKILL.md          |  40 +-
 skills/dotnet-docfx-digest/evals/evals.json  |  16 +-
 skills/dotnet-docfx-digest/scripts/README.md |  27 +-
 skills/dotnet-docfx-digest/scripts/agents.cs |  25 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs  | 373 ++++++++++++++++---
 5 files changed, 380 insertions(+), 101 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 96c531c..0da0eb6 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -26,13 +26,13 @@ When this skill is invoked against a repository, the agent must run the determin
 dotnet run --file skills/dotnet-docfx-digest/scripts/agents.cs -- --repo-root .
 ```
 
-Before reporting completion, the agent must run the deterministic validator:
-
-```bash
-dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root .
-```
-
-If either script cannot run, the agent must report the exact command, exit code, and failure output. Do not claim repository instructions or documentation were verified unless the scripts ran successfully.
+Before reporting completion, the agent must run the deterministic validator:
+
+```bash
+dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --verify-docfx-build
+```
+
+If either script cannot run, the agent must report the exact command, exit code, and failure output. Do not claim repository instructions or documentation were verified unless the scripts ran successfully.
 
 ## Core Principles
 
@@ -224,13 +224,13 @@ If assertions are useful, use them only when the sample is explicitly framed as
 
 Every code sample added or changed must be verified. A C# code sample must compile.
 
-The deterministic validator compiles C# documentation samples as .NET 10 file-based apps. Run:
-
-```bash
-dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root .
-```
-
-A sample may opt out only when the code fence includes:
+The deterministic validator compiles C# documentation samples as .NET 10 file-based apps. When completing DocFX documentation work, also ask it to verify the DocFX build in a temporary copy of the repository so generated metadata and site output stay outside the working tree. Run:
+
+```bash
+dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --verify-docfx-build
+```
+
+A sample may opt out only when the code fence includes:
 
 ```csharp
 // dotnet-docfx-digest:skip-compile - <reason>
@@ -486,8 +486,8 @@ When the user names a changed API or namespace:
 14. Preserve manual edits.
 15. Run `dotnet build`.
 16. Run `dotnet test`.
-17. Run `docfx .docfx/docfx.json`.
-18. Run `docfx.cs`.
+17. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
+18. Confirm generated DocFX metadata and build output did not remain in the working tree.
 19. Report verification results.
 
 When no specific API or namespace is named:
@@ -507,8 +507,8 @@ When no specific API or namespace is named:
 13. Preserve manual edits and correct stale contradictions instead of replacing whole files.
 14. Run `dotnet build`.
 15. Run `dotnet test`.
-16. Run `docfx .docfx/docfx.json`.
-17. Run `docfx.cs`.
+16. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
+17. Confirm generated DocFX metadata and build output did not remain in the working tree.
 18. Report verification results and any remaining findings.
 
 ## Namespace Page Template
@@ -596,8 +596,8 @@ Before completing documentation work, verify:
 - [ ] No contradictory documentation remains.
 - [ ] `dotnet build` has been run or the failure is reported.
 - [ ] `dotnet test` has been run or the failure is reported.
-- [ ] `docfx .docfx/docfx.json` has been run or the failure is reported.
-- [ ] `docfx.cs` has run successfully or the failure is reported.
+- [ ] `docfx.cs --verify-docfx-build` has run successfully, including the temp-workspace DocFX build, or the failure is reported.
+- [ ] Generated DocFX metadata files and build output directories did not remain in the working tree after verification.
 
 ## Completion Response
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 461d89d..0746fad 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -4,14 +4,14 @@
     {
       "id": 1,
       "prompt": "I just added a new public class `RetryPolicy` and a public extension method `WithRetry(this HttpClient client, int attempts)` to my .NET library in the `Acme.Net.Http` namespace. Please update the DocFX documentation for this change.",
-      "expected_output": "Agent runs scripts/agents.cs to seed AGENTS.md, creates/updates the Acme.Net.Http namespace overview page with uid front matter, a fly-in, availability, and an Extension Members table listing the extended type with the WithRetry method, adds a buildable example for RetryPolicy, and runs scripts/docfx.cs to verify.",
+      "expected_output": "Agent runs scripts/agents.cs to seed AGENTS.md, creates/updates the Acme.Net.Http namespace overview page with uid front matter, a fly-in, availability, and an Extension Members table listing the extended type with the WithRetry method, adds a buildable example for RetryPolicy, and runs scripts/docfx.cs with --verify-docfx-build to verify without leaving generated DocFX output in the working tree.",
       "expectations": [
         "Runs the deterministic scripts/agents.cs against the repository before completing",
         "Creates or updates a namespace overview page named Acme.Net.Http.md with DocFX overwrite front matter whose uid matches the namespace",
         "Adds an Extension Members table documenting the extended type (HttpClient), the ⬇️ marker, and the WithRetry method in backticks",
         "Adds at least one copy/paste-ready, buildable example for the concrete RetryPolicy type",
         "Includes availability information via an include or explicit Availability text",
-        "Runs scripts/docfx.cs to verify before claiming the documentation was verified"
+        "Runs scripts/docfx.cs with --verify-docfx-build to verify before claiming the documentation was verified"
       ]
     },
     {
@@ -40,9 +40,9 @@
     {
       "id": 4,
       "prompt": "Run the DocFX documentation validator on this repository and tell me whether the docs are in good shape.",
-      "expected_output": "Agent runs scripts/docfx.cs (and scripts/agents.cs if needed), reports the exact command, exit code, and the deterministic JSON/console findings, and does not claim verification without running the script.",
+      "expected_output": "Agent runs scripts/docfx.cs with --verify-docfx-build (and scripts/agents.cs if needed), reports the exact command, exit code, and the deterministic JSON/console findings, and does not claim verification without running the script.",
       "expectations": [
-        "Runs scripts/docfx.cs against the repository root",
+        "Runs scripts/docfx.cs against the repository root with --verify-docfx-build so DocFX runs in a temp workspace",
         "Reports the exact command run and its exit code",
         "Surfaces the deterministic findings (errors/warnings with their codes) rather than guessing",
         "Does not claim the documentation was verified unless the script actually ran successfully"
@@ -63,12 +63,12 @@
     {
       "id": 6,
       "prompt": "Use dotnet-docfx-digest on this repository.",
-      "expected_output": "Agent treats the request as a repo-wide DocFX documentation audit instead of asking what to document first. It runs scripts/agents.cs, inspects AGENTS.md, docfx.json, source projects, public API, tests, samples, overwrite files, namespace pages, and availability includes, runs scripts/docfx.cs to collect deterministic findings, repairs missing complementary DocFX documentation that can be derived from source evidence, reads the DocFX overwrite reference when creating or repairing overwrite files, and asks for clarification only if discovery exposes a correctness-affecting choice.",
+      "expected_output": "Agent treats the request as a repo-wide DocFX documentation audit instead of asking what to document first. It runs scripts/agents.cs, inspects AGENTS.md, docfx.json, source projects, public API, tests, samples, overwrite files, namespace pages, and availability includes, runs scripts/docfx.cs to collect deterministic findings and with --verify-docfx-build before completion, repairs missing complementary DocFX documentation that can be derived from source evidence, reads the DocFX overwrite reference when creating or repairing overwrite files, and asks for clarification only if discovery exposes a correctness-affecting choice.",
       "expectations": [
         "Does not start by asking the user which API or namespace to document",
         "Runs scripts/agents.cs to ensure the repository AGENTS.md contains the managed DocFX maintenance block",
         "Inspects docfx.json and existing DocFX overwrite, namespace, include, source, test, and sample evidence before editing",
-        "Runs scripts/docfx.cs, preferably with --json when collecting repo-wide findings",
+        "Runs scripts/docfx.cs, preferably with --json when collecting repo-wide findings, and uses --verify-docfx-build before completion so generated output stays outside the working tree",
         "Creates or updates missing namespace overview pages, Extension Members tables, examples, and availability notes that can be derived from evidence",
         "Reads references/docfx-overwrite-files.md before creating or repairing DocFX overwrite files",
         "Asks a concise clarifying question only after inspection finds a correctness-affecting unresolved choice"
@@ -77,14 +77,14 @@
     {
       "id": 7,
       "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but public non-abstraction types such as `Class1` and public extension methods have no examples. The DocFX config has build.overwrite pointing at .docfx/api/**/*.md.",
-      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates or updates DocFX overwrite sections/files included by build.overwrite for missing examples, puts type examples on the generated type page/overwrite section such as Class1.md for Class1, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, and reruns scripts/docfx.cs until EXAMPLE_MISSING findings are gone.",
+      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates or updates DocFX overwrite sections/files included by build.overwrite for missing examples, puts type examples on the generated type page/overwrite section such as Class1.md for Class1, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, and reruns scripts/docfx.cs until EXAMPLE_MISSING findings are gone, using --verify-docfx-build before completion so DocFX output is generated in temp space.",
       "expectations": [
         "Treats namespace overview pages and Extension Members tables as insufficient when examples are missing",
         "Creates or updates DocFX overwrite content included by build.overwrite for public non-abstraction type examples",
         "Places a public Class1 example on the Class1 type page/overwrite section rather than only on the namespace page",
         "Creates or updates overwrite content for public extension method examples, or places the example on the extension class or namespace page while explicitly demonstrating the method",
         "Uses generated DocFX UIDs or verified metadata instead of inventing overwrite UIDs",
-        "Runs scripts/docfx.cs and responds to EXAMPLE_MISSING diagnostics before claiming completion",
+        "Runs scripts/docfx.cs and responds to EXAMPLE_MISSING diagnostics before claiming completion, then uses --verify-docfx-build for final DocFX build verification",
         "Compiles changed C# examples or reports the exact verification failure"
       ]
     }
diff --git a/skills/dotnet-docfx-digest/scripts/README.md b/skills/dotnet-docfx-digest/scripts/README.md
index 9e92d90..eaf4246 100644
--- a/skills/dotnet-docfx-digest/scripts/README.md
+++ b/skills/dotnet-docfx-digest/scripts/README.md
@@ -60,15 +60,18 @@ sample as a file-based app.
 
 ```bash
 dotnet run --file docfx.cs -- --repo-root .
-dotnet run --file docfx.cs -- --repo-root . --json
-dotnet run --file docfx.cs -- --repo-root . --no-validate-samples
-dotnet run --file docfx.cs -- --repo-root . --changed-only
-dotnet run --file docfx.cs -- --repo-root . --configuration Debug --framework net10.0
-```
-
-Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`),
-`--framework`, `--validate-samples` / `--no-validate-samples` (default on),
-`--changed-only`, `--json`, `--help`.
+dotnet run --file docfx.cs -- --repo-root . --json
+dotnet run --file docfx.cs -- --repo-root . --no-validate-samples
+dotnet run --file docfx.cs -- --repo-root . --changed-only
+dotnet run --file docfx.cs -- --repo-root . --verify-docfx-build
+dotnet run --file docfx.cs -- --repo-root . --configuration Debug --framework net10.0
+```
+
+Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`),
+`--framework`, `--validate-samples` / `--no-validate-samples` (default on),
+`--changed-only`, `--verify-docfx-build`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`.
+
+`--verify-docfx-build` copies the repository to a temp workspace, runs the DocFX CLI against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree, so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory when it is safely inside the repository.
 
 Exit codes:
 
@@ -84,12 +87,12 @@ Exit codes:
 | 7 | Sample compilation failed |
 | 8 | Unexpected internal error |
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`,
-`DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`,
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`,
+`DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`,
 `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`,
 `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`,
 `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`,
-`EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, and `SAMPLE_SKIP_REASON_MISSING`.
+`EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`.
 
 ### Sample opt-out
 
diff --git a/skills/dotnet-docfx-digest/scripts/agents.cs b/skills/dotnet-docfx-digest/scripts/agents.cs
index fdad331..29c6cdf 100644
--- a/skills/dotnet-docfx-digest/scripts/agents.cs
+++ b/skills/dotnet-docfx-digest/scripts/agents.cs
@@ -46,18 +46,19 @@ internal static class AgentsScript
 
         Preserve manual documentation edits. Prefer additive changes, but correct stale or contradictory information so documentation remains accurate.
 
-        Before completing documentation work, run the relevant verification commands, normally:
-
-        ```bash
-        dotnet build
-        dotnet test
-        docfx .docfx/docfx.json
-        dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root .
-        ```
-
-        If a command cannot be run, report the exact limitation or failure instead of claiming the documentation was verified.
-        <!-- dotnet-docfx-digest:end -->
-        """;
+        Before completing documentation work, run the relevant verification commands, normally:
+
+        ```bash
+        dotnet build
+        dotnet test
+        dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --verify-docfx-build
+        ```
+
+        The DocFX build verification must run outside the working tree when possible. The `--verify-docfx-build` option copies the repository to a temp workspace, runs DocFX against the resolved `docfx.json` there, and removes the temp workspace afterward so generated API YAML, manifest files, and site output do not flood git status.
+
+        If a command cannot be run, report the exact limitation or failure instead of claiming the documentation was verified.
+        <!-- dotnet-docfx-digest:end -->
+        """;
 
     public static int Run(string[] args)
     {
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 1444414..dea2e73 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -22,7 +22,7 @@ internal static class DocfxValidator
     private const string ExtensionAttributeFullName = "System.Runtime.CompilerServices.ExtensionAttribute";
     private const string SkipMarker = "dotnet-docfx-digest:skip-compile";
 
-    private static readonly string[] IgnoredDirectorySegments = ["bin", "obj", "_site", ".git", "node_modules"];
+    private static readonly string[] IgnoredDirectorySegments = ["bin", "obj", "_site", ".git", ".vs", ".vscode", ".idea", "node_modules"];
     private static readonly TimeSpan ProcessTimeout = TimeSpan.FromMinutes(10);
 
     private static readonly JsonSerializerOptions JsonOptions = new()
@@ -112,11 +112,12 @@ private static int Validate(Options options)
             return Emit(options, report, ExitCode.DocfxConfigMissing, "DocFX configuration file not found.");
         }
 
-        report.DocfxPath = docfxPath;
-        var docfxWorkspace = Path.GetDirectoryName(docfxPath)!;
-
-        // 3. Verify AGENTS.md contains the managed block.
-        var agentsPath = Path.Combine(repoRoot, "AGENTS.md");
+        report.DocfxPath = docfxPath;
+        var docfxWorkspace = Path.GetDirectoryName(docfxPath)!;
+        CleanupGeneratedMetadata(repoRoot, docfxPath, docfxWorkspace, options, report);
+
+        // 3. Verify AGENTS.md contains the managed block.
+        var agentsPath = Path.Combine(repoRoot, "AGENTS.md");
         if (!AgentsBlockPresent(agentsPath))
         {
             report.Errors.Add(new Diagnostic("AGENTS_BLOCK_MISSING", agentsPath, null,
@@ -199,10 +200,16 @@ private static int Validate(Options options)
         ValidateRequiredExamples(repoRoot, markdownFiles, api, options, changedFiles, report);
 
         // 13. Extract and compile C# documentation samples.
-        if (options.ValidateSamples)
-        {
-            ValidateSamples(repoRoot, markdownFiles, libraryProjects, options, changedFiles, report);
-        }
+        if (options.ValidateSamples)
+        {
+            ValidateSamples(repoRoot, markdownFiles, libraryProjects, options, changedFiles, report);
+        }
+
+        // Optional DocFX build verification happens in a temp copy so generated output never lands in the working tree.
+        if (options.VerifyDocfxBuild)
+        {
+            VerifyDocfxBuild(repoRoot, docfxPath, report);
+        }
 
         // 14-15. Produce report and return a deterministic exit code.
         bool hasSampleError = report.Errors.Any(e => e.Code is "SAMPLE_COMPILE_FAILED");
@@ -229,8 +236,8 @@ private static int Validate(Options options)
     // DocFX discovery
     // ----------------------------------------------------------------------
 
-    private static string? ResolveDocfxPath(string repoRoot, string? explicitPath)
-    {
+    private static string? ResolveDocfxPath(string repoRoot, string? explicitPath)
+    {
         if (!string.IsNullOrWhiteSpace(explicitPath))
         {
             var full = Path.GetFullPath(explicitPath, repoRoot);
@@ -254,13 +261,210 @@ private static int Validate(Options options)
         {
             return file;
         }
-
-        return null;
-    }
-
-    private static List<string> DiscoverMarkdown(string docfxWorkspace)
-    {
-        var list = new List<string>();
+
+        return null;
+    }
+
+    private static void CleanupGeneratedMetadata(string repoRoot, string docfxPath, string docfxWorkspace, Options options, Report report)
+    {
+        if (!options.CleanGeneratedMetadata)
+        {
+            return;
+        }
+
+        foreach (var metadataPath in ResolveMetadataDestinations(docfxPath, docfxWorkspace, report)
+                     .Distinct(StringComparer.OrdinalIgnoreCase))
+        {
+            if (!Directory.Exists(metadataPath))
+            {
+                continue;
+            }
+
+            if (!IsInsideDirectory(metadataPath, repoRoot) ||
+                string.Equals(Path.GetFullPath(metadataPath).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar),
+                    Path.GetFullPath(repoRoot).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar),
+                    StringComparison.OrdinalIgnoreCase))
+            {
+                report.Warnings.Add(new Diagnostic("GENERATED_METADATA_CLEANUP_SKIPPED", metadataPath, null,
+                    "Generated metadata cleanup was skipped because the resolved metadata destination is outside the repository root or is the repository root."));
+                continue;
+            }
+
+            foreach (var file in EnumerateGeneratedMetadataFiles(metadataPath))
+            {
+                try
+                {
+                    File.Delete(file);
+                    report.Summary.GeneratedMetadataFilesRemoved++;
+                }
+                catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+                {
+                    report.Warnings.Add(new Diagnostic("GENERATED_METADATA_CLEANUP_FAILED", file, null,
+                        $"Unable to remove generated DocFX metadata file: {ex.Message}"));
+                }
+            }
+        }
+
+        foreach (var buildOutputPath in ResolveBuildOutputDestinations(docfxPath, docfxWorkspace, report)
+                     .Distinct(StringComparer.OrdinalIgnoreCase))
+        {
+            if (!Directory.Exists(buildOutputPath))
+            {
+                continue;
+            }
+
+            if (!IsSafeGeneratedOutputDirectory(buildOutputPath, repoRoot))
+            {
+                report.Warnings.Add(new Diagnostic("GENERATED_OUTPUT_CLEANUP_SKIPPED", buildOutputPath, null,
+                    "Generated output cleanup was skipped because the resolved DocFX build destination is outside the repository root or is the repository root."));
+                continue;
+            }
+
+            try
+            {
+                Directory.Delete(buildOutputPath, recursive: true);
+                report.Summary.GeneratedOutputDirectoriesRemoved++;
+            }
+            catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+            {
+                report.Warnings.Add(new Diagnostic("GENERATED_OUTPUT_CLEANUP_FAILED", buildOutputPath, null,
+                    $"Unable to remove generated DocFX build output directory: {ex.Message}"));
+            }
+        }
+    }
+
+    private static IEnumerable<string> ResolveMetadataDestinations(string docfxPath, string docfxWorkspace, Report report)
+    {
+        JsonDocument doc;
+        try
+        {
+            doc = JsonDocument.Parse(File.ReadAllText(docfxPath), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+        }
+        catch (Exception ex) when (ex is IOException or JsonException)
+        {
+            report.Warnings.Add(new Diagnostic("GENERATED_METADATA_CLEANUP_FAILED", docfxPath, null,
+                $"Unable to read DocFX metadata destinations for cleanup: {ex.Message}"));
+            yield break;
+        }
+
+        using (doc)
+        {
+            if (!doc.RootElement.TryGetProperty("metadata", out var metadata))
+            {
+                yield break;
+            }
+
+            var foundDest = false;
+            foreach (var entry in EnumerateMetadataEntries(metadata))
+            {
+                if (entry.ValueKind != JsonValueKind.Object ||
+                    !entry.TryGetProperty("dest", out var destElement) ||
+                    destElement.ValueKind != JsonValueKind.String)
+                {
+                    continue;
+                }
+
+                var dest = destElement.GetString();
+                if (string.IsNullOrWhiteSpace(dest))
+                {
+                    continue;
+                }
+
+                foundDest = true;
+                yield return Path.GetFullPath(dest, docfxWorkspace);
+            }
+
+            if (!foundDest)
+            {
+                yield return Path.GetFullPath("api", docfxWorkspace);
+            }
+        }
+    }
+
+    private static IEnumerable<string> ResolveBuildOutputDestinations(string docfxPath, string docfxWorkspace, Report report)
+    {
+        JsonDocument doc;
+        try
+        {
+            doc = JsonDocument.Parse(File.ReadAllText(docfxPath), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+        }
+        catch (Exception ex) when (ex is IOException or JsonException)
+        {
+            report.Warnings.Add(new Diagnostic("GENERATED_OUTPUT_CLEANUP_FAILED", docfxPath, null,
+                $"Unable to read DocFX build destination for cleanup: {ex.Message}"));
+            yield break;
+        }
+
+        using (doc)
+        {
+            if (!doc.RootElement.TryGetProperty("build", out var build) ||
+                build.ValueKind != JsonValueKind.Object ||
+                !build.TryGetProperty("dest", out var destElement) ||
+                destElement.ValueKind != JsonValueKind.String)
+            {
+                yield break;
+            }
+
+            var dest = destElement.GetString();
+            if (!string.IsNullOrWhiteSpace(dest))
+            {
+                yield return Path.GetFullPath(dest, docfxWorkspace);
+            }
+        }
+    }
+
+    private static IEnumerable<JsonElement> EnumerateMetadataEntries(JsonElement metadata)
+    {
+        if (metadata.ValueKind == JsonValueKind.Array)
+        {
+            foreach (var entry in metadata.EnumerateArray())
+            {
+                yield return entry;
+            }
+        }
+        else
+        {
+            yield return metadata;
+        }
+    }
+
+    private static IEnumerable<string> EnumerateGeneratedMetadataFiles(string metadataPath)
+    {
+        return EnumerateFiles(metadataPath, "*.yml")
+            .Concat(EnumerateFiles(metadataPath, ".manifest"))
+            .Concat(EnumerateFiles(metadataPath, "*.manifest"))
+            .Select(Path.GetFullPath)
+            .Distinct(StringComparer.OrdinalIgnoreCase);
+    }
+
+    private static bool IsInsideDirectory(string path, string directory)
+    {
+        var fullPath = Path.GetFullPath(path).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar) +
+                       Path.DirectorySeparatorChar;
+        var fullDirectory = Path.GetFullPath(directory).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar) +
+                            Path.DirectorySeparatorChar;
+        return fullPath.StartsWith(fullDirectory, StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static bool IsSafeGeneratedOutputDirectory(string path, string repoRoot)
+    {
+        return IsInsideDirectory(path, repoRoot) &&
+               !string.Equals(Path.GetFullPath(path).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar),
+                   Path.GetFullPath(repoRoot).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar),
+                   StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static List<string> DiscoverMarkdown(string docfxWorkspace)
+    {
+        var list = new List<string>();
         foreach (var file in EnumerateFiles(docfxWorkspace, "*.md"))
         {
             list.Add(Path.GetFullPath(file));
@@ -269,7 +473,7 @@ private static List<string> DiscoverMarkdown(string docfxWorkspace)
         return list;
     }
 
-    private static IEnumerable<string> EnumerateFiles(string root, string pattern)
+    private static IEnumerable<string> EnumerateFiles(string root, string pattern)
     {
         var stack = new Stack<string>();
         stack.Push(root);
@@ -311,11 +515,61 @@ private static IEnumerable<string> EnumerateFiles(string root, string pattern)
             {
                 yield return f;
             }
-        }
-    }
-
-    private static bool AgentsBlockPresent(string agentsPath)
-    {
+        }
+    }
+
+    private static void VerifyDocfxBuild(string repoRoot, string docfxPath, Report report)
+    {
+        var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-build-" + Guid.NewGuid().ToString("N"));
+        try
+        {
+            CopyDirectory(repoRoot, tempRoot);
+            var relativeDocfxPath = Path.GetRelativePath(repoRoot, docfxPath);
+            var tempDocfxPath = Path.Combine(tempRoot, relativeDocfxPath);
+            var result = RunProcess("docfx", $"\"{tempDocfxPath}\"", tempRoot);
+            if (result.ExitCode != 0)
+            {
+                report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
+                    $"DocFX build failed in a temp workspace (exit {result.ExitCode}).\n{Trim(result.StdOut + result.StdErr)}"));
+                return;
+            }
+
+            report.Summary.DocfxBuildsVerified++;
+        }
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+        {
+            report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
+                $"Unable to verify DocFX build in a temp workspace: {ex.Message}"));
+        }
+        finally
+        {
+            TryDeleteDirectory(tempRoot);
+        }
+    }
+
+    private static void CopyDirectory(string sourceDirectory, string destinationDirectory)
+    {
+        Directory.CreateDirectory(destinationDirectory);
+
+        foreach (var file in Directory.GetFiles(sourceDirectory))
+        {
+            File.Copy(file, Path.Combine(destinationDirectory, Path.GetFileName(file)), overwrite: true);
+        }
+
+        foreach (var directory in Directory.GetDirectories(sourceDirectory))
+        {
+            var name = Path.GetFileName(directory);
+            if (IgnoredDirectorySegments.Contains(name, StringComparer.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            CopyDirectory(directory, Path.Combine(destinationDirectory, name));
+        }
+    }
+
+    private static bool AgentsBlockPresent(string agentsPath)
+    {
         if (!File.Exists(agentsPath))
         {
             return false;
@@ -1326,9 +1580,11 @@ private static int Emit(Options options, Report report, ExitCode code, string co
             Console.WriteLine(
                 $"  Summary: namespaces={report.Summary.PublicNamespaces}, pages={report.Summary.NamespacePagesValidated}, " +
                 $"requiredExampleTargets={report.Summary.RequiredExampleTargets}, requiredExamples={report.Summary.RequiredExamples}, " +
-                $"extMethods={report.Summary.ExtensionMethods}, samplesCompiled={report.Summary.SamplesCompiled}, " +
-                $"samplesSkipped={report.Summary.SamplesSkipped}, errors={report.Summary.Errors}, warnings={report.Summary.Warnings}");
-        }
+                $"extMethods={report.Summary.ExtensionMethods}, samplesCompiled={report.Summary.SamplesCompiled}, " +
+                $"samplesSkipped={report.Summary.SamplesSkipped}, generatedMetadataRemoved={report.Summary.GeneratedMetadataFilesRemoved}, " +
+                $"generatedOutputDirectoriesRemoved={report.Summary.GeneratedOutputDirectoriesRemoved}, " +
+                $"docfxBuildsVerified={report.Summary.DocfxBuildsVerified}, errors={report.Summary.Errors}, warnings={report.Summary.Warnings}");
+        }
 
         return (int)code;
     }
@@ -1382,12 +1638,21 @@ private static bool TryParse(string[] args, out Options options, out string erro
                 case "--no-validate-samples":
                     options.ValidateSamples = false;
                     break;
-                case "--changed-only":
-                    options.ChangedOnly = true;
-                    break;
-                case "--json":
-                    options.Json = true;
-                    break;
+                case "--changed-only":
+                    options.ChangedOnly = true;
+                    break;
+                case "--verify-docfx-build":
+                    options.VerifyDocfxBuild = true;
+                    break;
+                case "--clean-generated-metadata":
+                    options.CleanGeneratedMetadata = true;
+                    break;
+                case "--no-clean-generated-metadata":
+                    options.CleanGeneratedMetadata = false;
+                    break;
+                case "--json":
+                    options.Json = true;
+                    break;
                 default:
                     if (TrySplit(arg, "--repo-root", out var v1)) { options.RepoRoot = v1; break; }
                     if (TrySplit(arg, "--docfx", out var v2)) { options.DocfxPath = v2; break; }
@@ -1440,11 +1705,16 @@ dotnet run --file docfx.cs -- [options]
               --docfx <path>           Path to docfx.json. Default: .docfx/docfx.json under repo root.
               --configuration <name>   Build configuration. Default: Release.
               --framework <tfm>        Optional target framework to validate against.
-              --validate-samples       Compile C# samples. Default: enabled.
-              --no-validate-samples    Skip C# sample compilation.
-              --changed-only           Validate only files changed according to git.
-              --json                   Emit a machine-readable JSON summary.
-              --help                   Print this usage.
+              --validate-samples       Compile C# samples. Default: enabled.
+              --no-validate-samples    Skip C# sample compilation.
+              --changed-only           Validate only files changed according to git.
+              --verify-docfx-build     Run DocFX against a temp copy of the repository so generated output stays outside the working tree.
+              --clean-generated-metadata
+                                      Remove DocFX-generated *.yml and manifest files under metadata.dest. Default: enabled.
+              --no-clean-generated-metadata
+                                      Leave DocFX-generated metadata files untouched.
+              --json                   Emit a machine-readable JSON summary.
+              --help                   Print this usage.
 
             Exit codes:
               0  Validation passed.
@@ -1478,10 +1748,12 @@ private sealed class Options
         public string? DocfxPath { get; set; }
         public string Configuration { get; set; } = "Release";
         public string? Framework { get; set; }
-        public bool ValidateSamples { get; set; } = true;
-        public bool ChangedOnly { get; set; }
-        public bool Json { get; set; }
-        public bool Help { get; set; }
+        public bool ValidateSamples { get; set; } = true;
+        public bool ChangedOnly { get; set; }
+        public bool VerifyDocfxBuild { get; set; }
+        public bool CleanGeneratedMetadata { get; set; } = true;
+        public bool Json { get; set; }
+        public bool Help { get; set; }
     }
 
     private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest);
@@ -1534,12 +1806,15 @@ internal sealed class Summary
     public int NamespacePagesValidated { get; set; }
     public int RequiredExampleTargets { get; set; }
     public int RequiredExamples { get; set; }
-    public int ExtensionMethods { get; set; }
-    public int SamplesCompiled { get; set; }
-    public int SamplesSkipped { get; set; }
-    public int Errors { get; set; }
-    public int Warnings { get; set; }
-}
+    public int ExtensionMethods { get; set; }
+    public int SamplesCompiled { get; set; }
+    public int SamplesSkipped { get; set; }
+    public int GeneratedMetadataFilesRemoved { get; set; }
+    public int GeneratedOutputDirectoriesRemoved { get; set; }
+    public int DocfxBuildsVerified { get; set; }
+    public int Errors { get; set; }
+    public int Warnings { get; set; }
+}
 
 internal sealed class Report
 {

From 509c57fed2b71b0696df507f3798934ee976c96f Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 16:40:21 +0200
Subject: [PATCH 09/88] =?UTF-8?q?=F0=9F=92=AC=20update=20dotnet-docfx-dige?=
 =?UTF-8?q?st=20description=20in=20available=20skills?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reflect the new --verify-docfx-build capability that runs the DocFX CLI in a temporary repository copy, keeping generated metadata and site output outside the working tree.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9c90e1c..d06d9d7 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext`, then validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, and compiles every C# documentation sample as a file-based app. Documents public API only, uses a bundled DocFX overwrite reference, requires buildable copy/paste-ready examples for concrete types, preserves manual edits, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext`, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, and C# documentation samples, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses a bundled DocFX overwrite reference, requires buildable copy/paste-ready examples for concrete types, preserves manual edits, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 

From ee29d95cc39c85fc3783db0095a12c1a4f202bb8 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 19:18:52 +0200
Subject: [PATCH 10/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20add=20per-type=20doc?=
 =?UTF-8?q?fx=20overwrite=20file=20support?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update dotnet-docfx-digest to create separate per-type DocFX overwrite files (e.g. .docfx/api/TypeUid.md) instead of namespace-only files. Modifies SKILL.md workflow steps, adds framework-aware MetadataLoadContext dependency resolution to scripts/docfx.cs, and validates that build.overwrite includes per-type files. Updates evals and reference documentation to reflect the new per-type overwrite strategy.
---
 skills/dotnet-docfx-digest/SKILL.md           |  28 +-
 skills/dotnet-docfx-digest/evals/evals.json   |   7 +-
 .../references/docfx-overwrite-files.md       |   3 +-
 skills/dotnet-docfx-digest/scripts/README.md  |  44 +-
 skills/dotnet-docfx-digest/scripts/agents.cs  |   2 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 482 +++++++++++++++++-
 6 files changed, 495 insertions(+), 71 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 0da0eb6..c1d9ee0 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -155,7 +155,13 @@ A "material change" includes:
 
 Every automatically documented public non-abstraction type and every public extension method must include at least one example showing how to use it. A namespace overview fly-in or `Extension Members` table is not enough.
 
-Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create one in a Markdown file included by `build.overwrite` in `docfx.json`. Do not stop after editing namespace pages when public non-abstraction types or public extension methods still lack examples.
+Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create a separate per-type Markdown overwrite file by default. For Codebelt repositories, the default type example file is:
+
+```text
+.docfx/api/{TypeUid}.md
+```
+
+For example, create `.docfx/api/Codebelt.Bootstrapper.ProgramRoot.md` for uid `Codebelt.Bootstrapper.ProgramRoot`. If `build.overwrite` does not include the chosen per-type file path, update `docfx.json` so the overwrite glob includes both namespace pages and per-type API overwrite files, such as `api/**/*.md`. Do not hide type examples in namespace pages because the current overwrite glob only includes namespace files.
 
 For public non-abstraction types, the example must belong to the generated type page/overwrite section for that type `uid`. For example, if `Class1` is public and not an abstraction, add an `Examples` section to the DocFX overwrite content for `Class1` so the example appears on `Class1.md` at the bottom of the generated API page. A namespace page example does not satisfy the type-page example requirement for `Class1`.
 
@@ -389,6 +395,8 @@ Use overwrite files for:
 Do not use overwrite files to conceal inaccurate XML documentation. Correct the source XML documentation when it is wrong.
 
 When the validator reports `EXAMPLE_MISSING`, create or update DocFX overwrite content for the reported UID instead of treating the missing example as a prose-only issue.
+
+When a repository has namespace overview files but no per-type overwrite files, create the per-type files. Do not treat the absence of existing type files as a signal to skip examples. For Codebelt repositories, place new type files beside generated API metadata under `.docfx/api/` and update `build.overwrite` if it currently points only at `.docfx/api/namespaces/**/*.md`.
 
 ## XML Documentation Comments
 
@@ -503,13 +511,15 @@ When no specific API or namespace is named:
 9. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
 10. Add or repair `Extension Members` tables for namespaces with public extension methods.
 11. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
-12. Create type-page overwrite example sections for public non-abstraction types and example sections for public extension methods that have no example yet.
-13. Preserve manual edits and correct stale contradictions instead of replacing whole files.
-14. Run `dotnet build`.
-15. Run `dotnet test`.
-16. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
-17. Confirm generated DocFX metadata and build output did not remain in the working tree.
-18. Report verification results and any remaining findings.
+12. Create separate type-page overwrite files for public non-abstraction types that have no example yet, using `.docfx/api/{TypeUid}.md` in Codebelt repositories unless the repo has a stronger existing convention.
+13. Ensure `build.overwrite` includes the per-type overwrite files you create; update a namespace-only overwrite glob to include API overwrite files when needed.
+14. Create example sections for public extension methods that have no example yet.
+15. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+16. Run `dotnet build`.
+17. Run `dotnet test`.
+18. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
+19. Confirm generated DocFX metadata and build output did not remain in the working tree.
+20. Report verification results and any remaining findings.
 
 ## Namespace Page Template
 
@@ -535,7 +545,7 @@ Remove the `Extension Members` section when the namespace has no public extensio
 
 ## Type Example Template
 
-Use this shape for public non-abstraction type examples. Put this on the generated type page/overwrite section for the type `uid`; for a public `Class1`, the example belongs on the `Class1` API page, not only on the namespace page.
+Use this shape for public non-abstraction type examples. Put this on the generated type page/overwrite section for the type `uid`; for a public `Class1`, the example belongs on the `Class1` API page, not only on the namespace page. When no type overwrite file exists yet, create a separate per-type file such as `.docfx/api/X.Y.Z.Class1.md` and ensure `build.overwrite` includes that file.
 
 ````markdown
 ### Examples
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 0746fad..fbd93e6 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -76,11 +76,12 @@
     },
     {
       "id": 7,
-      "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but public non-abstraction types such as `Class1` and public extension methods have no examples. The DocFX config has build.overwrite pointing at .docfx/api/**/*.md.",
-      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates or updates DocFX overwrite sections/files included by build.overwrite for missing examples, puts type examples on the generated type page/overwrite section such as Class1.md for Class1, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, and reruns scripts/docfx.cs until EXAMPLE_MISSING findings are gone, using --verify-docfx-build before completion so DocFX output is generated in temp space.",
+      "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but public non-abstraction types such as `Class1` and public extension methods have no examples. The DocFX config currently has build.overwrite pointing only at .docfx/api/namespaces/**/*.md, and there are no existing per-type overwrite files.",
+      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates separate per-type DocFX overwrite files such as .docfx/api/Acme.Class1.md for missing concrete-type examples, updates build.overwrite so those per-type files are included, puts type examples on the generated type page/overwrite section rather than namespace pages, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, and reruns scripts/docfx.cs until EXAMPLE_MISSING findings are gone, using --verify-docfx-build before completion so DocFX output is generated in temp space.",
       "expectations": [
         "Treats namespace overview pages and Extension Members tables as insufficient when examples are missing",
-        "Creates or updates DocFX overwrite content included by build.overwrite for public non-abstraction type examples",
+        "Creates separate per-type DocFX overwrite files for public non-abstraction type examples when no type files exist yet",
+        "Updates a namespace-only build.overwrite glob so the new per-type overwrite files are included",
         "Places a public Class1 example on the Class1 type page/overwrite section rather than only on the namespace page",
         "Creates or updates overwrite content for public extension method examples, or places the example on the extension class or namespace page while explicitly demonstrating the method",
         "Uses generated DocFX UIDs or verified metadata instead of inventing overwrite UIDs",
diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
index 61236ef..603d1d4 100644
--- a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -33,7 +33,7 @@ The `build.overwrite` entry in `docfx.json` tells DocFX which conceptual Markdow
 
 When a repository has no obvious overwrite location, inspect `docfx.json` first. Look at `build.content`, `build.overwrite`, `metadata.dest`, include paths, and existing Markdown layout before deciding where a new namespace page belongs.
 
-If a public non-abstraction type lacks an example, create a matching type-UID overwrite section in a Markdown file that is included by `build.overwrite` so the example appears on the generated type API page. For example, a public `Class1` needs an example on the `Class1` API page. Namespace overview pages and `Extension Members` tables complement examples; they do not replace type-page examples.
+If a public non-abstraction type lacks an example, create a matching type-UID overwrite section in a separate per-type Markdown file by default, and make sure that file is included by `build.overwrite` so the example appears on the generated type API page. In Codebelt repositories, create new type example files under `.docfx/api/{TypeUid}.md`, such as `.docfx/api/X.Y.Z.Class1.md`. If `build.overwrite` only includes namespace files such as `api/namespaces/**/*.md`, update it to include per-type API overwrite files too, such as `api/**/*.md`. Namespace overview pages and `Extension Members` tables complement examples; they do not replace type-page examples.
 
 ## Practical Rules
 
@@ -42,6 +42,7 @@ If a public non-abstraction type lacks an example, create a matching type-UID ov
 - Correct bad XML comments at source when the generated summary is wrong.
 - Use namespace overview pages for namespace fly-ins and extension-member tables.
 - Keep examples and remarks close to the API item or namespace they explain.
+- Create per-type overwrite files for missing concrete-type examples even when the repository currently has only namespace overview files.
 - Add examples through overwrite sections when XML comments or generated metadata do not already provide developer-friendly examples.
 - Preserve existing hand-written overwrite sections unless they are stale or contradictory.
 - Prefer additive edits, but remove or revise contradictions.
diff --git a/skills/dotnet-docfx-digest/scripts/README.md b/skills/dotnet-docfx-digest/scripts/README.md
index eaf4246..a9b3f14 100644
--- a/skills/dotnet-docfx-digest/scripts/README.md
+++ b/skills/dotnet-docfx-digest/scripts/README.md
@@ -1,23 +1,17 @@
 # dotnet-docfx-digest scripts
 
-Two deterministic .NET 10 file-based apps back the skill so that repository
-guidance and documentation rules are enforced by code, not by AI memory. Each
-script is a single `.cs` file with no `.csproj` and runs directly:
+Two deterministic .NET 10 file-based apps back the skill so that repository guidance and documentation rules are enforced by code, not by AI memory. Each script is a single `.cs` file with no `.csproj` and runs directly:
 
 ```bash
 dotnet run --file <script>.cs -- <arguments>
 dotnet build <script>.cs
 ```
 
-Both declare `#:property TargetFramework=net10.0` and `#:property PublishAot=false`,
-return deterministic exit codes, and emit machine-readable JSON with `--json`.
+Both declare `#:property TargetFramework=net10.0` and `#:property PublishAot=false`, return deterministic exit codes, and emit machine-readable JSON with `--json`.
 
 ## agents.cs
 
-Ensures the repository root `AGENTS.md` contains a marker-bounded DocFX
-documentation-maintenance block. Idempotent: running it repeatedly never
-duplicates the block. Content outside the markers is preserved, the host file's
-line endings are respected, and new files are written as UTF-8 without a BOM.
+Ensures the repository root `AGENTS.md` contains a marker-bounded DocFX documentation-maintenance block. Idempotent: running it repeatedly never duplicates the block. Content outside the markers is preserved, the host file's line endings are respected, and new files are written as UTF-8 without a BOM.
 
 ```bash
 dotnet run --file agents.cs -- --repo-root .            # write (default)
@@ -33,9 +27,7 @@ Markers:
 <!-- dotnet-docfx-digest:end -->
 ```
 
-If both markers exist, only the content between them (inclusive) is replaced.
-If neither exists, the block is appended. If exactly one marker exists, the file
-is treated as corrupt and the script exits non-zero.
+If both markers exist, only the content between them (inclusive) is replaced. If neither exists, the block is appended. If exactly one marker exists, the file is treated as corrupt and the script exits non-zero.
 
 Exit codes:
 
@@ -50,13 +42,7 @@ Exit codes:
 
 ## docfx.cs
 
-Validates the deterministic documentation requirements against the *compiled*
-repository, not against text in `SKILL.md`. It builds the solution, discovers
-public API from compiled assemblies (preferring reference assemblies) via
-`System.Reflection.MetadataLoadContext`, then checks namespace overview pages,
-extension-member tables, availability, required type-page overwrite examples for
-public non-abstraction types and public extension methods, and compiles every C# documentation
-sample as a file-based app.
+Validates the deterministic documentation requirements against the *compiled* repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies (preferring reference assemblies) via `System.Reflection.MetadataLoadContext`, resolves dependency metadata from project assets, deps files, and installed .NET framework reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, and compiles every C# documentation sample as a file-based app.
 
 ```bash
 dotnet run --file docfx.cs -- --repo-root .
@@ -67,11 +53,9 @@ dotnet run --file docfx.cs -- --repo-root . --verify-docfx-build
 dotnet run --file docfx.cs -- --repo-root . --configuration Debug --framework net10.0
 ```
 
-Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`),
-`--framework`, `--validate-samples` / `--no-validate-samples` (default on),
-`--changed-only`, `--verify-docfx-build`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`.
+Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--framework`, `--validate-samples` / `--no-validate-samples` (default on), `--changed-only`, `--verify-docfx-build`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
-`--verify-docfx-build` copies the repository to a temp workspace, runs the DocFX CLI against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree, so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory when it is safely inside the repository.
+`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree, so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory when it is safely inside the repository.
 
 Exit codes:
 
@@ -87,12 +71,7 @@ Exit codes:
 | 7 | Sample compilation failed |
 | 8 | Unexpected internal error |
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`,
-`DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`,
-`NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`,
-`NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`,
-`EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`,
-`EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`.
 
 ### Sample opt-out
 
@@ -106,9 +85,4 @@ A skip marker without a reason is reported as `SAMPLE_SKIP_REASON_MISSING`.
 
 ### Extension-method detection note
 
-Extension methods are detected from compiled metadata: a public static method,
-carrying `System.Runtime.CompilerServices.ExtensionAttribute`, declared on a
-public static non-generic class, with at least one parameter. The first
-parameter's type is recorded as the extended type. (The C# compiler marks the
-method — not the first parameter — with `ExtensionAttribute`, so detection keys
-off the method attribute to match real metadata.)
+Extension methods are detected from compiled metadata: a public static method, carrying `System.Runtime.CompilerServices.ExtensionAttribute`, declared on a public static non-generic class, with at least one parameter. The first parameter's type is recorded as the extended type. (The C# compiler marks the method — not the first parameter — with `ExtensionAttribute`, so detection keys off the method attribute to match real metadata.)
diff --git a/skills/dotnet-docfx-digest/scripts/agents.cs b/skills/dotnet-docfx-digest/scripts/agents.cs
index 29c6cdf..efab6e4 100644
--- a/skills/dotnet-docfx-digest/scripts/agents.cs
+++ b/skills/dotnet-docfx-digest/scripts/agents.cs
@@ -32,7 +32,7 @@ internal static class AgentsScript
 
         For public non-abstraction types, include at least one realistic, copy/paste-ready usage example on the generated type page/overwrite section for that type UID. For example, a public `Class1` requires an example on the `Class1` API page, not only on the namespace page. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage.
 
-        Missing examples must be added through DocFX overwrite content included by `build.overwrite` in `docfx.json`. Namespace overview text and `Extension Members` tables are not substitutes for type-page examples.
+        Missing type examples must be added through separate per-type DocFX overwrite files by default, such as `.docfx/api/{TypeUid}.md` in Codebelt repositories. If `build.overwrite` only includes namespace files, update `docfx.json` so it includes the per-type overwrite files too, for example with `api/**/*.md`. Namespace overview text and `Extension Members` tables are not substitutes for type-page examples.
 
         Public extension methods must have examples too. Listing an extension method in an `Extension Members` table is required, but it is not enough.
 
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index dea2e73..d76296c 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -114,6 +114,7 @@ private static int Validate(Options options)
 
         report.DocfxPath = docfxPath;
         var docfxWorkspace = Path.GetDirectoryName(docfxPath)!;
+        options.Framework ??= ResolveDefaultFramework(docfxPath, report);
         CleanupGeneratedMetadata(repoRoot, docfxPath, docfxWorkspace, options, report);
 
         // 3. Verify AGENTS.md contains the managed block.
@@ -265,6 +266,60 @@ private static int Validate(Options options)
         return null;
     }
 
+    private static string? ResolveDefaultFramework(string docfxPath, Report report)
+    {
+        try
+        {
+            using var doc = JsonDocument.Parse(File.ReadAllText(docfxPath), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+
+            if (!doc.RootElement.TryGetProperty("metadata", out var metadata))
+            {
+                return null;
+            }
+
+            var frameworks = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var entry in EnumerateMetadataEntries(metadata))
+            {
+                if (entry.ValueKind != JsonValueKind.Object ||
+                    !entry.TryGetProperty("properties", out var properties) ||
+                    properties.ValueKind != JsonValueKind.Object ||
+                    !properties.TryGetProperty("TargetFramework", out var tfm) ||
+                    tfm.ValueKind != JsonValueKind.String)
+                {
+                    continue;
+                }
+
+                var value = tfm.GetString();
+                if (!string.IsNullOrWhiteSpace(value))
+                {
+                    frameworks.Add(value.Trim());
+                }
+            }
+
+            if (frameworks.Count == 1)
+            {
+                return frameworks.First();
+            }
+
+            if (frameworks.Count > 1)
+            {
+                report.Warnings.Add(new Diagnostic("FRAMEWORK_DEFAULT_SKIPPED", docfxPath, null,
+                    "DocFX metadata declares multiple TargetFramework values; pass --framework explicitly to validate one target framework."));
+            }
+        }
+        catch (Exception ex) when (ex is IOException or JsonException)
+        {
+            report.Warnings.Add(new Diagnostic("FRAMEWORK_DEFAULT_SKIPPED", docfxPath, null,
+                $"Unable to read DocFX metadata TargetFramework default: {ex.Message}"));
+        }
+
+        return null;
+    }
+
     private static void CleanupGeneratedMetadata(string repoRoot, string docfxPath, string docfxWorkspace, Options options, Report report)
     {
         if (!options.CleanGeneratedMetadata)
@@ -520,13 +575,21 @@ private static IEnumerable<string> EnumerateFiles(string root, string pattern)
 
     private static void VerifyDocfxBuild(string repoRoot, string docfxPath, Report report)
     {
+        var docfxExecutable = ResolveDocfxExecutable();
+        if (docfxExecutable is null)
+        {
+            report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
+                "Unable to find the DocFX CLI on PATH. Install the docfx .NET tool or make docfx.exe available on PATH."));
+            return;
+        }
+
         var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-build-" + Guid.NewGuid().ToString("N"));
         try
         {
             CopyDirectory(repoRoot, tempRoot);
             var relativeDocfxPath = Path.GetRelativePath(repoRoot, docfxPath);
             var tempDocfxPath = Path.Combine(tempRoot, relativeDocfxPath);
-            var result = RunProcess("docfx", $"\"{tempDocfxPath}\"", tempRoot);
+            var result = RunProcess(docfxExecutable, $"\"{tempDocfxPath}\"", tempRoot);
             if (result.ExitCode != 0)
             {
                 report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
@@ -547,6 +610,43 @@ private static void VerifyDocfxBuild(string repoRoot, string docfxPath, Report r
         }
     }
 
+    private static string? ResolveDocfxExecutable()
+    {
+        var currentProcess = Environment.ProcessPath;
+        var path = Environment.GetEnvironmentVariable("PATH");
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            return null;
+        }
+
+        var extensions = OperatingSystem.IsWindows()
+            ? (Environment.GetEnvironmentVariable("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD")
+                .Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
+            : [string.Empty];
+
+        foreach (var directory in path.Split(Path.PathSeparator, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+        {
+            foreach (var extension in extensions)
+            {
+                var candidate = Path.Combine(directory, OperatingSystem.IsWindows() ? "docfx" + extension.ToLowerInvariant() : "docfx");
+                if (!File.Exists(candidate))
+                {
+                    continue;
+                }
+
+                var full = Path.GetFullPath(candidate);
+                if (currentProcess is not null && string.Equals(full, currentProcess, StringComparison.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
+                return full;
+            }
+        }
+
+        return null;
+    }
+
     private static void CopyDirectory(string sourceDirectory, string destinationDirectory)
     {
         Directory.CreateDirectory(destinationDirectory);
@@ -702,22 +802,34 @@ private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string co
         // Resolve dependencies from the runtime directory and the assemblies' own output folders.
         var resolverPaths = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
         var runtimeDir = System.Runtime.InteropServices.RuntimeEnvironment.GetRuntimeDirectory();
-        foreach (var dll in Directory.GetFiles(runtimeDir, "*.dll"))
-        {
-            resolverPaths.Add(dll);
-        }
-
-        foreach (var dll in assemblyPaths)
-        {
-            var dir = Path.GetDirectoryName(dll)!;
-            foreach (var sibling in Directory.GetFiles(dir, "*.dll"))
-            {
-                resolverPaths.Add(sibling);
-            }
-        }
-
-        var resolver = new PathAssemblyResolver(resolverPaths);
-        using var mlc = new MetadataLoadContext(resolver, "System.Private.CoreLib");
+        foreach (var dll in Directory.GetFiles(runtimeDir, "*.dll"))
+        {
+            resolverPaths.Add(dll);
+        }
+
+        AddDotNetPackResolverPaths(runtimeDir, framework, resolverPaths);
+
+        foreach (var dll in assemblyPaths)
+        {
+            var dir = Path.GetDirectoryName(dll)!;
+            foreach (var sibling in Directory.GetFiles(dir, "*.dll"))
+            {
+                resolverPaths.Add(sibling);
+            }
+        }
+
+        foreach (var proj in libraryProjects)
+        {
+            var dll = assemblyPaths.FirstOrDefault(p =>
+                string.Equals(Path.GetFileNameWithoutExtension(p), proj.AssemblyName, StringComparison.OrdinalIgnoreCase));
+            if (dll is not null)
+            {
+                AddProjectDependencyResolverPaths(proj, dll, configuration, framework, resolverPaths);
+            }
+        }
+
+        var resolver = new PathAssemblyResolver(DistinctResolverPaths(resolverPaths));
+        using var mlc = new MetadataLoadContext(resolver, "System.Private.CoreLib");
 
         var namespaces = new Dictionary<string, NamespaceInfo>(StringComparer.Ordinal);
         foreach (var dll in assemblyPaths)
@@ -776,10 +888,336 @@ private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string co
             .ToList();
 
         return new ApiModel(namespaces.Values.ToList(), requiredExampleTargets);
-    }
-
-    private static void CollectApiTargets(Type type, NamespaceInfo ns)
-    {
+    }
+
+    private static List<string> DistinctResolverPaths(IEnumerable<string> paths)
+    {
+        var byIdentity = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        var fallback = new List<string>();
+        foreach (var path in paths)
+        {
+            try
+            {
+                var identity = AssemblyName.GetAssemblyName(path).FullName;
+                byIdentity.TryAdd(identity, path);
+            }
+            catch
+            {
+                fallback.Add(path);
+            }
+        }
+
+        return byIdentity.Values.Concat(fallback).ToList();
+    }
+
+    private static void AddDotNetPackResolverPaths(string runtimeDir, string? framework, HashSet<string> resolverPaths)
+    {
+        if (string.IsNullOrWhiteSpace(framework))
+        {
+            return;
+        }
+
+        var dotnetRoot = Directory.GetParent(runtimeDir.TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar))?
+            .Parent?
+            .Parent?
+            .FullName;
+        if (dotnetRoot is null)
+        {
+            return;
+        }
+
+        var packsRoot = Path.Combine(dotnetRoot, "packs");
+        if (!Directory.Exists(packsRoot))
+        {
+            return;
+        }
+
+        foreach (var pack in Directory.GetDirectories(packsRoot))
+        {
+            if (string.Equals(Path.GetFileName(pack), "Microsoft.NETCore.App.Ref", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            var refDir = Directory.GetDirectories(pack)
+                .Select(version => Path.Combine(version, "ref", framework))
+                .Where(Directory.Exists)
+                .OrderByDescending(path => path, StringComparer.OrdinalIgnoreCase)
+                .FirstOrDefault();
+
+            if (refDir is null)
+            {
+                continue;
+            }
+
+            foreach (var dll in Directory.GetFiles(refDir, "*.dll"))
+            {
+                resolverPaths.Add(dll);
+            }
+        }
+    }
+
+    private static void AddProjectDependencyResolverPaths(ProjectInfo project, string assemblyPath, string configuration,
+        string? framework, HashSet<string> resolverPaths)
+    {
+        var projectFramework = framework ?? DetectFrameworkFromAssemblyPath(project, assemblyPath);
+        AddProjectAssetsResolverPaths(project, projectFramework, resolverPaths);
+        AddDepsJsonResolverPaths(project, assemblyPath, configuration, projectFramework, resolverPaths);
+    }
+
+    private static string? DetectFrameworkFromAssemblyPath(ProjectInfo project, string assemblyPath)
+    {
+        if (project.TargetFrameworks.Count == 0)
+        {
+            return null;
+        }
+
+        var segments = Path.GetFullPath(assemblyPath)
+            .Split(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+
+        return project.TargetFrameworks.FirstOrDefault(tfm =>
+            segments.Any(s => string.Equals(s, tfm, StringComparison.OrdinalIgnoreCase)));
+    }
+
+    private static void AddProjectAssetsResolverPaths(ProjectInfo project, string? framework, HashSet<string> resolverPaths)
+    {
+        var projectDir = Path.GetDirectoryName(project.Path)!;
+        var assetsPath = Path.Combine(projectDir, "obj", "project.assets.json");
+        if (!File.Exists(assetsPath))
+        {
+            return;
+        }
+
+        try
+        {
+            using var doc = JsonDocument.Parse(File.ReadAllText(assetsPath), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+
+            if (!doc.RootElement.TryGetProperty("targets", out var targets) ||
+                targets.ValueKind != JsonValueKind.Object)
+            {
+                return;
+            }
+
+            var packageFolders = ReadPackageFolders(doc.RootElement);
+            foreach (var target in targets.EnumerateObject())
+            {
+                if (!IsMatchingAssetsTarget(target.Name, framework))
+                {
+                    continue;
+                }
+
+                foreach (var dependency in target.Value.EnumerateObject())
+                {
+                    AddAssetGroupResolverPaths(dependency, "compile", packageFolders, resolverPaths);
+                    AddAssetGroupResolverPaths(dependency, "runtime", packageFolders, resolverPaths);
+                }
+            }
+        }
+        catch (Exception ex) when (ex is IOException or JsonException)
+        {
+            // Missing asset details should not block metadata discovery when output-folder resolution is enough.
+        }
+    }
+
+    private static List<string> ReadPackageFolders(JsonElement root)
+    {
+        var packageFolders = new List<string>();
+        if (!root.TryGetProperty("packageFolders", out var folders) ||
+            folders.ValueKind != JsonValueKind.Object)
+        {
+            return packageFolders;
+        }
+
+        foreach (var folder in folders.EnumerateObject())
+        {
+            if (!string.IsNullOrWhiteSpace(folder.Name))
+            {
+                packageFolders.Add(folder.Name);
+            }
+        }
+
+        return packageFolders;
+    }
+
+    private static bool IsMatchingAssetsTarget(string targetName, string? framework)
+    {
+        if (string.IsNullOrWhiteSpace(framework))
+        {
+            return true;
+        }
+
+        return string.Equals(targetName, framework, StringComparison.OrdinalIgnoreCase) ||
+               targetName.StartsWith(framework + "/", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static void AddAssetGroupResolverPaths(JsonProperty dependency, string groupName, List<string> packageFolders,
+        HashSet<string> resolverPaths)
+    {
+        if (dependency.Value.ValueKind != JsonValueKind.Object ||
+            !dependency.Value.TryGetProperty("type", out var typeElement) ||
+            typeElement.ValueKind != JsonValueKind.String ||
+            !string.Equals(typeElement.GetString(), "package", StringComparison.OrdinalIgnoreCase) ||
+            !dependency.Value.TryGetProperty(groupName, out var group) ||
+            group.ValueKind != JsonValueKind.Object)
+        {
+            return;
+        }
+
+        var slash = dependency.Name.IndexOf('/');
+        if (slash <= 0 || slash == dependency.Name.Length - 1)
+        {
+            return;
+        }
+
+        var packageId = dependency.Name[..slash];
+        var version = dependency.Name[(slash + 1)..];
+        foreach (var asset in group.EnumerateObject())
+        {
+            if (!asset.Name.EndsWith(".dll", StringComparison.OrdinalIgnoreCase) ||
+                asset.Name.EndsWith("/_._", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            foreach (var packageFolder in packageFolders)
+            {
+                var packageRoot = Path.Combine(packageFolder, packageId.ToLowerInvariant(), version.ToLowerInvariant());
+                var fullPath = Path.GetFullPath(asset.Name.Replace('/', Path.DirectorySeparatorChar), packageRoot);
+                if (File.Exists(fullPath))
+                {
+                    resolverPaths.Add(fullPath);
+                    break;
+                }
+
+                packageRoot = Path.Combine(packageFolder, packageId, version);
+                fullPath = Path.GetFullPath(asset.Name.Replace('/', Path.DirectorySeparatorChar), packageRoot);
+                if (File.Exists(fullPath))
+                {
+                    resolverPaths.Add(fullPath);
+                    break;
+                }
+            }
+        }
+    }
+
+    private static void AddDepsJsonResolverPaths(ProjectInfo project, string assemblyPath, string configuration,
+        string? framework, HashSet<string> resolverPaths)
+    {
+        var projectDir = Path.GetDirectoryName(project.Path)!;
+        var outputDir = Path.GetDirectoryName(assemblyPath)!;
+        var depsName = Path.GetFileNameWithoutExtension(assemblyPath) + ".deps.json";
+        var candidates = new List<string> { Path.Combine(outputDir, depsName) };
+
+        if (!string.IsNullOrWhiteSpace(framework))
+        {
+            candidates.Add(Path.Combine(projectDir, "bin", configuration, framework, depsName));
+        }
+
+        foreach (var depsPath in candidates.Distinct(StringComparer.OrdinalIgnoreCase))
+        {
+            if (!File.Exists(depsPath))
+            {
+                continue;
+            }
+
+            AddDepsJsonPackagePaths(depsPath, resolverPaths);
+        }
+    }
+
+    private static void AddDepsJsonPackagePaths(string depsPath, HashSet<string> resolverPaths)
+    {
+        try
+        {
+            using var doc = JsonDocument.Parse(File.ReadAllText(depsPath), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+
+            if (!doc.RootElement.TryGetProperty("targets", out var targets) ||
+                targets.ValueKind != JsonValueKind.Object)
+            {
+                return;
+            }
+
+            var packageFolders = ResolveNuGetPackageFolders();
+            foreach (var target in targets.EnumerateObject())
+            {
+                foreach (var dependency in target.Value.EnumerateObject())
+                {
+                    AddDepsRuntimeResolverPaths(dependency, packageFolders, resolverPaths);
+                }
+            }
+        }
+        catch (Exception ex) when (ex is IOException or JsonException)
+        {
+            // project.assets.json is the primary package resolver; deps.json only supplements it.
+        }
+    }
+
+    private static List<string> ResolveNuGetPackageFolders()
+    {
+        var folders = new List<string>();
+        var userProfile = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+        if (!string.IsNullOrWhiteSpace(userProfile))
+        {
+            folders.Add(Path.Combine(userProfile, ".nuget", "packages"));
+        }
+
+        var packages = Environment.GetEnvironmentVariable("NUGET_PACKAGES");
+        if (!string.IsNullOrWhiteSpace(packages))
+        {
+            folders.Insert(0, packages);
+        }
+
+        return folders.Where(Directory.Exists).Distinct(StringComparer.OrdinalIgnoreCase).ToList();
+    }
+
+    private static void AddDepsRuntimeResolverPaths(JsonProperty dependency, List<string> packageFolders,
+        HashSet<string> resolverPaths)
+    {
+        if (dependency.Value.ValueKind != JsonValueKind.Object ||
+            !dependency.Value.TryGetProperty("runtime", out var runtime) ||
+            runtime.ValueKind != JsonValueKind.Object)
+        {
+            return;
+        }
+
+        var slash = dependency.Name.IndexOf('/');
+        if (slash <= 0 || slash == dependency.Name.Length - 1)
+        {
+            return;
+        }
+
+        var packageId = dependency.Name[..slash];
+        var version = dependency.Name[(slash + 1)..];
+        foreach (var asset in runtime.EnumerateObject())
+        {
+            if (!asset.Name.EndsWith(".dll", StringComparison.OrdinalIgnoreCase) ||
+                asset.Name.EndsWith("/_._", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            foreach (var packageFolder in packageFolders)
+            {
+                var packageRoot = Path.Combine(packageFolder, packageId.ToLowerInvariant(), version.ToLowerInvariant());
+                var fullPath = Path.GetFullPath(asset.Name.Replace('/', Path.DirectorySeparatorChar), packageRoot);
+                if (File.Exists(fullPath))
+                {
+                    resolverPaths.Add(fullPath);
+                    break;
+                }
+            }
+        }
+    }
+
+    private static void CollectApiTargets(Type type, NamespaceInfo ns)
+    {
         var typeUid = TypeUid(type);
         if (typeUid is null)
         {
@@ -1145,7 +1583,7 @@ private static void ValidateRequiredExamples(string repoRoot, List<string> markd
                 : target.DeclaringTypeUid ?? target.Uid;
 
             var message = target.Kind == ApiTargetKind.Type
-                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to the generated type page/overwrite section for uid `{target.Uid}` (for example `{target.DisplayName}.md` when that is the repository's API-page convention)."
+                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to a per-type overwrite file for uid `{target.Uid}` (for Codebelt repositories, create `.docfx/api/{target.Uid}.md` and ensure build.overwrite includes it, for example with `api/**/*.md`)."
                 : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}`, its declaring type uid `{expectedUid}`, or the namespace page `{target.Namespace}`.";
 
             report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", null, target.Namespace, message));

From 83a1ed678dea59af8fa3c6dcc1e62dc7dfa59aba Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 19:18:55 +0200
Subject: [PATCH 11/88] =?UTF-8?q?=F0=9F=92=AC=20update=20available=20skill?=
 =?UTF-8?q?s=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reflect the per-type DocFX overwrite file support in dotnet-docfx-digest. Updates the skill description to mention framework-aware metadata resolution, per-type overwrite files, and the requirement that build.overwrite includes those files.
---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index d06d9d7..daa177c 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext`, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, and C# documentation samples, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses a bundled DocFX overwrite reference, requires buildable copy/paste-ready examples for concrete types, preserves manual edits, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses a bundled DocFX overwrite reference, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -536,9 +536,9 @@ API documentation rots the moment code changes. A new public type ships without
 - **No-input audits by default** — `Use dotnet-docfx-digest` means inspect the repository, DocFX config, public API, tests, samples, overwrite files, namespace pages, and availability includes, then repair missing complementary documentation that can be derived from evidence before asking any clarifying questions,
 - **Persistent guidance by script, not memory** — `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; running it twice never duplicates the block, and `--check` gates it in CI,
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
-- **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, instead of guessing from text,
+- **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, resolving NuGet package dependencies, deps files, and installed .NET framework reference packs instead of guessing from text,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
-- **Mandatory overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; type examples belong on the generated type page such as `Class1.md`, and namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`,
+- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, namespace-only overwrite globs must be widened to include those files, and namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,

From 0ddb4e71ca13582fd228695988756dcb8af4207c Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 20:04:47 +0200
Subject: [PATCH 12/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20restructure=20dotnet?=
 =?UTF-8?q?-docfx-digest=20skill=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move detailed script CLI documentation from scripts/README.md to references/scripts.md following progressive disclosure and Anthropic skill authoring conventions. Updates SKILL.md to reference the new location. Reorganizes skill sections, clarifies scope and principles, and updates evals to match the new structure. Includes enhanced docfx.cs with improved diagnostics and JSON output.
---
 skills/dotnet-docfx-digest/SKILL.md           | 1048 +++---
 skills/dotnet-docfx-digest/evals/evals.json   |  104 +-
 .../README.md => references/scripts.md}       |  160 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 3017 +++++++++--------
 4 files changed, 2211 insertions(+), 2118 deletions(-)
 rename skills/dotnet-docfx-digest/{scripts/README.md => references/scripts.md} (62%)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index c1d9ee0..7254f82 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -1,15 +1,15 @@
----
-name: dotnet-docfx-digest
+---
+name: dotnet-docfx-digest
 description: >
   Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including repo-wide no-input audits, namespace overview pages, extension-member documentation, overwrite files, examples, availability notes, AGENTS.md maintenance, and verification. Use when the user asks to document a .NET API, create or update DocFX documentation, write namespace overview pages, add extension-method tables, update XML documentation comments, add API examples, maintain DocFX overwrite files, or verify documentation builds. Treat requests like "use dotnet-docfx-digest", "update the DocFX docs", "complete missing documentation", "create namespace pages", "add examples for this type", "update the extension members table", or "verify the documentation builds" as automatic triggers. Also use whenever public .NET API surface changes and documentation needs to stay aligned with source code.
----
-
-# .NET DocFX Digest Steward
-
-## Description
-
-Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including namespace overview pages, extension-member documentation, overwrite files, examples, availability notes, and verification. Preserve manual edits, document public API only, require buildable copy/paste-ready examples for concrete APIs, and keep documentation aligned with actual source code and tests.
-
+---
+
+# .NET DocFX Digest Steward
+
+## Description
+
+Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including namespace overview pages, extension-member documentation, overwrite files, examples, availability notes, and verification. Preserve manual edits, document public API only, require buildable copy/paste-ready examples for concrete APIs, and keep documentation aligned with actual source code and tests.
+
 ## Activation Requirements
 
 This skill is autonomous by default. If the user invokes the skill without naming a namespace, type, member, or changed API, do not ask what to document first. Treat the request as a repo-wide DocFX documentation audit and repair task:
@@ -21,11 +21,11 @@ This skill is autonomous by default. If the user invokes the skill without namin
 5. Ask a concise clarifying question only when inspection exposes a correctness-affecting choice that cannot be resolved from repository evidence.
 
 When this skill is invoked against a repository, the agent must run the deterministic repository-instruction script before completing the task:
-
-```bash
-dotnet run --file skills/dotnet-docfx-digest/scripts/agents.cs -- --repo-root .
-```
-
+
+```bash
+dotnet run --file skills/dotnet-docfx-digest/scripts/agents.cs -- --repo-root .
+```
+
 Before reporting completion, the agent must run the deterministic validator:
 
 ```bash
@@ -33,126 +33,128 @@ dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . -
 ```
 
 If either script cannot run, the agent must report the exact command, exit code, and failure output. Do not claim repository instructions or documentation were verified unless the scripts ran successfully.
-
-## Core Principles
-
-Documentation is part of the public contract. When changing public .NET APIs, the agent must update the corresponding documentation in the same change set. This includes XML documentation comments, DocFX overwrite files, namespace overview pages, examples, extension-method listings, and availability information.
-
-The documentation must reflect the actual code, not intended code. Do not invent APIs, overloads, target frameworks, behaviors, exceptions, or examples. Verify every documented claim against source code, tests, project files, generated metadata, or existing documentation.
-
-Manual documentation is authoritative context. Preserve existing manual edits unless they are factually incorrect. Prefer additive changes. When information is stale, update the stale portion while retaining nearby human-written explanations, tone, and structure.
-
-## Scope
-
-Apply this skill to:
-
-- Public .NET types,
-- Public constructors,
-- Public properties,
-- Public methods,
-- Public fields,
-- Public events,
-- Public delegates,
-- Public enums and enum members,
-- Public extension methods,
-- Public namespaces containing public API,
-- DocFX overwrite Markdown files,
-- DocFX namespace overview Markdown files,
-- XML documentation comments,
-- API examples,
-- availability includes or availability statements.
-
-Do not document:
-
-- Private types,
-- Internal types,
-- Private members,
-- Internal members,
-- Implementation-only helpers,
-- Test-only fixtures unless they are part of a documented public test-support API,
-- Namespaces that contain no public API.
-
-If a namespace contains only private or internal types, do not create a namespace overview page for it.
-
+
+Read `references/scripts.md` when you need the exact CLI surface, exit codes, JSON diagnostics, or validator behavior for `agents.cs` and `docfx.cs`.
+
+## Core Principles
+
+Documentation is part of the public contract. When changing public .NET APIs, the agent must update the corresponding documentation in the same change set. This includes XML documentation comments, DocFX overwrite files, namespace overview pages, examples, extension-method listings, and availability information.
+
+The documentation must reflect the actual code, not intended code. Do not invent APIs, overloads, target frameworks, behaviors, exceptions, or examples. Verify every documented claim against source code, tests, project files, generated metadata, or existing documentation.
+
+Manual documentation is authoritative context. Preserve existing manual edits unless they are factually incorrect. Prefer additive changes. When information is stale, update the stale portion while retaining nearby human-written explanations, tone, and structure.
+
+## Scope
+
+Apply this skill to:
+
+- Public .NET types,
+- Public constructors,
+- Public properties,
+- Public methods,
+- Public fields,
+- Public events,
+- Public delegates,
+- Public enums and enum members,
+- Public extension methods,
+- Public namespaces containing public API,
+- DocFX overwrite Markdown files,
+- DocFX namespace overview Markdown files,
+- XML documentation comments,
+- API examples,
+- availability includes or availability statements.
+
+Do not document:
+
+- Private types,
+- Internal types,
+- Private members,
+- Internal members,
+- Implementation-only helpers,
+- Test-only fixtures unless they are part of a documented public test-support API,
+- Namespaces that contain no public API.
+
+If a namespace contains only private or internal types, do not create a namespace overview page for it.
+
 ## Repository Discovery
 
 Before editing documentation, locate the DocFX workspace.
-
-For Codebelt repositories, the DocFX workspace is always:
-
-```text
-.docfx
-```
-
-The DocFX configuration file is always:
-
-```text
-.docfx/docfx.json
-```
-
-For other repositories, locate `docfx.json` before making DocFX-specific changes.
-
-Inspect `docfx.json` to understand:
-
-- Content roots,
-- API metadata inputs,
-- Overwrite file locations,
-- Include file locations,
-- Resource paths,
-- Output conventions.
-
+
+For Codebelt repositories, the DocFX workspace is always:
+
+```text
+.docfx
+```
+
+The DocFX configuration file is always:
+
+```text
+.docfx/docfx.json
+```
+
+For other repositories, locate `docfx.json` before making DocFX-specific changes.
+
+Inspect `docfx.json` to understand:
+
+- Content roots,
+- API metadata inputs,
+- Overwrite file locations,
+- Include file locations,
+- Resource paths,
+- Output conventions.
+
 Do not assume paths beyond the repository's actual DocFX configuration, except for Codebelt repositories where `.docfx/docfx.json` is the convention.
 
 When creating or repairing overwrite files, read `references/docfx-overwrite-files.md` for the DocFX overwrite and `docfx.json` rules that matter most to agents.
-
-## AGENTS.md Maintenance
-
-Persistent repository guidance is enforced by script, not by AI memory. When this skill is invoked, run:
-
-```bash
-dotnet run --file skills/dotnet-docfx-digest/scripts/agents.cs -- --repo-root .
-```
-
-The script must create or update a marker-bounded DocFX documentation maintenance section in the repository root `AGENTS.md`. Do not manually duplicate this section. If the script fails, report the failure and do not claim `AGENTS.md` was updated.
-
-## Public API Rule
-
-Only public API is documented. Before adding or updating documentation, determine whether the item is public from source code or generated metadata.
-
-A type is documentable only when it is externally visible. A member is documentable only when it is public and belongs to a documentable public type.
-
-Do not add documentation pages for namespaces that contain no public types. Do not add extension-method documentation for non-public extension methods.
-
-## Required Documentation Updates
-
-When a public API is added or materially changed, update all relevant documentation surfaces:
-
-1. XML documentation comments in source code.
-2. DocFX overwrite files when manual API documentation exists or is needed.
-3. Namespace overview page.
-4. Extension members table when extension methods are involved.
-5. Availability information.
+
+## AGENTS.md Maintenance
+
+Persistent repository guidance is enforced by script, not by AI memory. When this skill is invoked, run:
+
+```bash
+dotnet run --file skills/dotnet-docfx-digest/scripts/agents.cs -- --repo-root .
+```
+
+The script must create or update a marker-bounded DocFX documentation maintenance section in the repository root `AGENTS.md`. Do not manually duplicate this section. If the script fails, report the failure and do not claim `AGENTS.md` was updated.
+
+## Public API Rule
+
+Only public API is documented. Before adding or updating documentation, determine whether the item is public from source code or generated metadata.
+
+A type is documentable only when it is externally visible. A member is documentable only when it is public and belongs to a documentable public type.
+
+Do not add documentation pages for namespaces that contain no public types. Do not add extension-method documentation for non-public extension methods.
+
+## Required Documentation Updates
+
+When a public API is added or materially changed, update all relevant documentation surfaces:
+
+1. XML documentation comments in source code.
+2. DocFX overwrite files when manual API documentation exists or is needed.
+3. Namespace overview page.
+4. Extension members table when extension methods are involved.
+5. Availability information.
 6. At least one usage example in DocFX overwrite content unless the documented item is an abstraction.
 7. Verification artifacts or commands proving the documentation remains buildable and accurate.
-
-A "material change" includes:
-
-- New public API,
-- Removed public API,
-- Changed public signature,
-- Changed behavior,
-- Changed exception behavior,
-- Changed generic constraints,
-- Changed nullability contract,
-- Changed target framework availability,
-- Changed platform availability,
-- Changed extension-method availability,
-- Changed obsolete/deprecation status,
-- Changed default values,
-- Changed thread-safety or lifecycle expectations.
-
-## Examples Are Mandatory
-
+
+A "material change" includes:
+
+- New public API,
+- Removed public API,
+- Changed public signature,
+- Changed behavior,
+- Changed exception behavior,
+- Changed generic constraints,
+- Changed nullability contract,
+- Changed target framework availability,
+- Changed platform availability,
+- Changed extension-method availability,
+- Changed obsolete/deprecation status,
+- Changed default values,
+- Changed thread-safety or lifecycle expectations.
+
+## Examples Are Mandatory
+
 Every automatically documented public non-abstraction type and every public extension method must include at least one example showing how to use it. A namespace overview fly-in or `Extension Members` table is not enough.
 
 Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create a separate per-type Markdown overwrite file by default. For Codebelt repositories, the default type example file is:
@@ -166,70 +168,70 @@ For example, create `.docfx/api/Codebelt.Bootstrapper.ProgramRoot.md` for uid `C
 For public non-abstraction types, the example must belong to the generated type page/overwrite section for that type `uid`. For example, if `Class1` is public and not an abstraction, add an `Examples` section to the DocFX overwrite content for `Class1` so the example appears on `Class1.md` at the bottom of the generated API page. A namespace page example does not satisfy the type-page example requirement for `Class1`.
 
 For public extension methods, add the example to the generated method UID when known; otherwise add it to the extension class UID or the namespace page, but the example must name and demonstrate the extension method.
-
-An example may be omitted only when the item is an abstraction, such as:
-
-- Interface,
-- Abstract class,
-- Abstract member,
-- Attribute intended only for framework discovery,
-- Marker type with no direct usage,
-- Pure contract type where concrete usage belongs on implementations.
-
-When omitting an example for an abstraction, the documentation must make that reason clear.
-
-Preferred source for examples:
-
-1. Existing unit tests,
-2. Existing functional tests,
-3. Existing integration tests,
-4. Existing samples,
-5. Minimal new sample derived from actual public API behavior.
-
-Examples derived from tests must be converted into real-life usage. Do not paste raw assertion-heavy test code as documentation unless the documentation is specifically explaining testing. Convert Arrange/Act/Assert test structure into developer-oriented sample code.
-
-The example must be:
-
-- Realistic,
-- Minimal,
-- Deterministic,
-- Copy/paste-ready,
-- Buildable in a normal consuming project,
-- Free of hidden repository-specific helpers unless those helpers are also public and documented,
-- Free of pseudo-code,
-- Free of ellipses inside code blocks,
-- Free of unexplained magic values,
-- Valid for the documented target framework availability.
-
-Bad example pattern:
-
-```csharp
-// Arrange
-var sut = new Foo();
-
-// Act
-var actual = sut.Bar();
-
-// Assert
-Assert.Equal("baz", actual);
-```
-
-Preferred documentation pattern:
-
-```csharp
-using My.Library;
-
-var formatter = new Foo();
-string value = formatter.Bar();
-Console.WriteLine(value);
-```
-
-If assertions are useful, use them only when the sample is explicitly framed as a test sample and can compile in that test context.
-
-## Example Verification
-
-Every code sample added or changed must be verified. A C# code sample must compile.
-
+
+An example may be omitted only when the item is an abstraction, such as:
+
+- Interface,
+- Abstract class,
+- Abstract member,
+- Attribute intended only for framework discovery,
+- Marker type with no direct usage,
+- Pure contract type where concrete usage belongs on implementations.
+
+When omitting an example for an abstraction, the documentation must make that reason clear.
+
+Preferred source for examples:
+
+1. Existing unit tests,
+2. Existing functional tests,
+3. Existing integration tests,
+4. Existing samples,
+5. Minimal new sample derived from actual public API behavior.
+
+Examples derived from tests must be converted into real-life usage. Do not paste raw assertion-heavy test code as documentation unless the documentation is specifically explaining testing. Convert Arrange/Act/Assert test structure into developer-oriented sample code.
+
+The example must be:
+
+- Realistic,
+- Minimal,
+- Deterministic,
+- Copy/paste-ready,
+- Buildable in a normal consuming project,
+- Free of hidden repository-specific helpers unless those helpers are also public and documented,
+- Free of pseudo-code,
+- Free of ellipses inside code blocks,
+- Free of unexplained magic values,
+- Valid for the documented target framework availability.
+
+Bad example pattern:
+
+```csharp
+// Arrange
+var sut = new Foo();
+
+// Act
+var actual = sut.Bar();
+
+// Assert
+Assert.Equal("baz", actual);
+```
+
+Preferred documentation pattern:
+
+```csharp
+using My.Library;
+
+var formatter = new Foo();
+string value = formatter.Bar();
+Console.WriteLine(value);
+```
+
+If assertions are useful, use them only when the sample is explicitly framed as a test sample and can compile in that test context.
+
+## Example Verification
+
+Every code sample added or changed must be verified. A C# code sample must compile.
+
 The deterministic validator compiles C# documentation samples as .NET 10 file-based apps. When completing DocFX documentation work, also ask it to verify the DocFX build in a temporary copy of the repository so generated metadata and site output stay outside the working tree. Run:
 
 ```bash
@@ -237,263 +239,263 @@ dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . -
 ```
 
 A sample may opt out only when the code fence includes:
-
-```csharp
-// dotnet-docfx-digest:skip-compile - <reason>
-```
-
-The reason is mandatory. Do not use silent opt-outs.
-
-Do not claim a sample compiles unless the validator or an equivalent repository verification command has compiled it successfully.
-
-## Namespace Overview Pages
-
-Every namespace containing public API must have a namespace overview Markdown page.
-
-The namespace overview page must be named after the namespace:
-
-```text
-X.Y.Z.md
-```
-
-The page must live in the appropriate DocFX documentation folder for namespace overwrite/custom content. For Codebelt repositories, place namespace overview pages under the `.docfx` documentation structure according to the existing repository layout.
-
-The namespace page must use DocFX overwrite front matter with the namespace UID:
-
-```markdown
----
-uid: X.Y.Z
-summary: *content
----
-```
-
-The page must provide a developer-friendly fly-in explaining what the namespace is for. The fly-in should be similar in usefulness and tone to Microsoft .NET API documentation:
-
-- Start with what the namespace contains.
-- Explain the developer problem it solves.
-- Explain when to use it.
-- Mention important concepts or type families.
-- Avoid marketing language.
-- Avoid restating type names without explaining purpose.
-- Keep the explanation accurate to the public API.
-
-Minimum namespace overview structure:
-
-```markdown
----
-uid: X.Y.Z
-summary: *content
----
-The `X.Y.Z` namespace contains types that ...
-
-[!INCLUDE [availability-default](../../includes/availability-default.md)]
-```
-
-If the namespace contains extension methods, include an `Extension Members` section.
-
-## Extension Method Documentation
-
-Extension methods must be documented at namespace level.
-
-If any public type exposes public extension members in namespace `X.Y.Z`, then the DocFX documentation must include:
-
-```text
-X.Y.Z.md
-```
-
-This file must contain an `Extension Members` section. The section must list public extension methods exposed by that namespace.
-
-Required table format:
-
-```markdown
-### Extension Members
-
-|Type|Ext|Methods|
-|--:|:-:|---|
-|ITestOutputHelper|⬇️|`WriteLines`|
-|String|⬇️|`ReplaceLineEndings` (TFM netstandard2.0)|
-```
-
-Rules for the table:
-
-- `Type` is the extended type, not the static extension class.
-- `Ext` must use `⬇️`.
-- `Methods` lists public extension methods.
-- Use backticks around method names.
-- Include TFM-specific availability when a method is conditional.
-- Group overloads under the same method name unless overload distinction is essential.
-- Do not include internal/private extension methods.
-- Do not include extension classes as the primary documentation target unless the class itself has relevant public API beyond extension methods.
-
-Example:
-
-```markdown
-### Extension Members
-
-|Type|Ext|Methods|
-|--:|:-:|---|
-|String|⬇️|`ToSlug`, `NormalizeLineEndings`|
-|IEnumerable<T>|⬇️|`ForEach`, `Batch`|
-```
-
-## Availability Documentation
-
-Availability information must be present for public API documentation.
-
-Availability can be documented in either of two ways:
-
-1. By referencing an existing include file.
-2. By writing explicit availability text when no suitable include exists.
-
-Prefer include files when the repository has an `includes` folder with Markdown files that define availability.
-
-Example include:
-
-```markdown
-[!INCLUDE [availability-default](../../includes/availability-default.md)]
-```
-
-Example explicit availability:
-
-```markdown
-Availability: .NET 10, .NET 9 and .NET Standard 2.0.
-```
-
-If a suitable include exists, reference it instead of duplicating availability text. If no suitable include exists, explicit availability is acceptable.
-
-Do not add redundant availability text if the page already references an availability include that covers the same API surface.
-
-When availability differs by type, member, target framework, or platform, document the difference close to the affected item.
-
-Availability must reflect actual project files, conditional compilation, target frameworks, package metadata, and source code.
-
-## DocFX Overwrite Files
-
+
+```csharp
+// dotnet-docfx-digest:skip-compile - <reason>
+```
+
+The reason is mandatory. Do not use silent opt-outs.
+
+Do not claim a sample compiles unless the validator or an equivalent repository verification command has compiled it successfully.
+
+## Namespace Overview Pages
+
+Every namespace containing public API must have a namespace overview Markdown page.
+
+The namespace overview page must be named after the namespace:
+
+```text
+X.Y.Z.md
+```
+
+The page must live in the appropriate DocFX documentation folder for namespace overwrite/custom content. For Codebelt repositories, place namespace overview pages under the `.docfx` documentation structure according to the existing repository layout.
+
+The namespace page must use DocFX overwrite front matter with the namespace UID:
+
+```markdown
+---
+uid: X.Y.Z
+summary: *content
+---
+```
+
+The page must provide a developer-friendly fly-in explaining what the namespace is for. The fly-in should be similar in usefulness and tone to Microsoft .NET API documentation:
+
+- Start with what the namespace contains.
+- Explain the developer problem it solves.
+- Explain when to use it.
+- Mention important concepts or type families.
+- Avoid marketing language.
+- Avoid restating type names without explaining purpose.
+- Keep the explanation accurate to the public API.
+
+Minimum namespace overview structure:
+
+```markdown
+---
+uid: X.Y.Z
+summary: *content
+---
+The `X.Y.Z` namespace contains types that ...
+
+[!INCLUDE [availability-default](../../includes/availability-default.md)]
+```
+
+If the namespace contains extension methods, include an `Extension Members` section.
+
+## Extension Method Documentation
+
+Extension methods must be documented at namespace level.
+
+If any public type exposes public extension members in namespace `X.Y.Z`, then the DocFX documentation must include:
+
+```text
+X.Y.Z.md
+```
+
+This file must contain an `Extension Members` section. The section must list public extension methods exposed by that namespace.
+
+Required table format:
+
+```markdown
+### Extension Members
+
+|Type|Ext|Methods|
+|--:|:-:|---|
+|ITestOutputHelper|⬇️|`WriteLines`|
+|String|⬇️|`ReplaceLineEndings` (TFM netstandard2.0)|
+```
+
+Rules for the table:
+
+- `Type` is the extended type, not the static extension class.
+- `Ext` must use `⬇️`.
+- `Methods` lists public extension methods.
+- Use backticks around method names.
+- Include TFM-specific availability when a method is conditional.
+- Group overloads under the same method name unless overload distinction is essential.
+- Do not include internal/private extension methods.
+- Do not include extension classes as the primary documentation target unless the class itself has relevant public API beyond extension methods.
+
+Example:
+
+```markdown
+### Extension Members
+
+|Type|Ext|Methods|
+|--:|:-:|---|
+|String|⬇️|`ToSlug`, `NormalizeLineEndings`|
+|IEnumerable<T>|⬇️|`ForEach`, `Batch`|
+```
+
+## Availability Documentation
+
+Availability information must be present for public API documentation.
+
+Availability can be documented in either of two ways:
+
+1. By referencing an existing include file.
+2. By writing explicit availability text when no suitable include exists.
+
+Prefer include files when the repository has an `includes` folder with Markdown files that define availability.
+
+Example include:
+
+```markdown
+[!INCLUDE [availability-default](../../includes/availability-default.md)]
+```
+
+Example explicit availability:
+
+```markdown
+Availability: .NET 10, .NET 9 and .NET Standard 2.0.
+```
+
+If a suitable include exists, reference it instead of duplicating availability text. If no suitable include exists, explicit availability is acceptable.
+
+Do not add redundant availability text if the page already references an availability include that covers the same API surface.
+
+When availability differs by type, member, target framework, or platform, document the difference close to the affected item.
+
+Availability must reflect actual project files, conditional compilation, target frameworks, package metadata, and source code.
+
+## DocFX Overwrite Files
+
 Use DocFX overwrite files to modify or add content for generated API items without editing generated metadata directly.
-
-Overwrite files must include YAML front matter with the target `uid`. Example:
-
-```markdown
----
-uid: X.Y.Z.MyType
-summary: *content
----
-```
-
-The `uid` must match the generated DocFX UID. Do not guess UIDs. Verify them from generated metadata, existing API pages, source conventions, or DocFX output.
-
+
+Overwrite files must include YAML front matter with the target `uid`. Example:
+
+```markdown
+---
+uid: X.Y.Z.MyType
+summary: *content
+---
+```
+
+The `uid` must match the generated DocFX UID. Do not guess UIDs. Verify them from generated metadata, existing API pages, source conventions, or DocFX output.
+
 Use overwrite files for:
 
 - Namespace overview pages,
 - Additional conceptual remarks,
 - Examples,
-- Corrected summaries,
-- Extension-method namespace documentation,
-- Availability notes,
-- Developer-oriented usage guidance.
-
+- Corrected summaries,
+- Extension-method namespace documentation,
+- Availability notes,
+- Developer-oriented usage guidance.
+
 Do not use overwrite files to conceal inaccurate XML documentation. Correct the source XML documentation when it is wrong.
 
 When the validator reports `EXAMPLE_MISSING`, create or update DocFX overwrite content for the reported UID instead of treating the missing example as a prose-only issue.
 
 When a repository has namespace overview files but no per-type overwrite files, create the per-type files. Do not treat the absence of existing type files as a signal to skip examples. For Codebelt repositories, place new type files beside generated API metadata under `.docfx/api/` and update `build.overwrite` if it currently points only at `.docfx/api/namespaces/**/*.md`.
-
-## XML Documentation Comments
-
-Public API should have useful XML documentation comments. Prefer concise source-level XML comments and richer examples/remarks in DocFX overwrite files when documentation becomes long.
-
-XML documentation should describe:
-
-- Purpose,
-- Parameters,
-- Return value,
-- Exceptions,
-- Type parameters,
-- Important behavior,
-- Nullability expectations,
-- Thread-safety or lifecycle behavior when relevant.
-
-Do not use empty boilerplate summaries.
-
-Bad:
-
-```csharp
-/// <summary>
-/// Gets or sets the value.
-/// </summary>
-```
-
-Better:
-
-```csharp
-/// <summary>
-/// Gets or sets the normalized name used when matching configuration keys.
-/// </summary>
-```
-
-## Preservation Rules
-
-Manual edits must be preserved.
-
-Before editing an existing Markdown file:
-
-1. Read the entire file.
-2. Identify manually written sections.
-3. Preserve structure and tone where possible.
-4. Add new information in the most appropriate existing section.
-5. Avoid replacing the whole file unless the file is clearly generated or corrupt.
-6. Keep existing includes, admonitions, links, and examples unless they are stale.
-7. Update stale statements instead of appending contradictory new statements.
-
-Documentation must stay current. If additive-only editing would leave conflicting or stale information, update the stale information. Accuracy is more important than blindly appending content. Never leave two conflicting descriptions of the same API behavior.
-
-## Style Rules
-
-Use developer-friendly documentation style.
-
-Prefer:
-
-- Direct explanations,
-- Practical examples,
-- Concrete behavior,
-- Accurate terminology,
-- Small complete samples,
-- Links to related APIs when useful,
-- Namespace-level fly-ins that explain purpose.
-
-Avoid:
-
-- Marketing language,
-- Placeholder text,
-- "Simply",
-- "Just",
-- "Obviously",
-- Pseudo-code,
-- Incomplete snippets,
-- Unverified claims,
-- Duplicating generated API signatures manually,
-- Restating the namespace name without explaining its purpose.
-
+
+## XML Documentation Comments
+
+Public API should have useful XML documentation comments. Prefer concise source-level XML comments and richer examples/remarks in DocFX overwrite files when documentation becomes long.
+
+XML documentation should describe:
+
+- Purpose,
+- Parameters,
+- Return value,
+- Exceptions,
+- Type parameters,
+- Important behavior,
+- Nullability expectations,
+- Thread-safety or lifecycle behavior when relevant.
+
+Do not use empty boilerplate summaries.
+
+Bad:
+
+```csharp
+/// <summary>
+/// Gets or sets the value.
+/// </summary>
+```
+
+Better:
+
+```csharp
+/// <summary>
+/// Gets or sets the normalized name used when matching configuration keys.
+/// </summary>
+```
+
+## Preservation Rules
+
+Manual edits must be preserved.
+
+Before editing an existing Markdown file:
+
+1. Read the entire file.
+2. Identify manually written sections.
+3. Preserve structure and tone where possible.
+4. Add new information in the most appropriate existing section.
+5. Avoid replacing the whole file unless the file is clearly generated or corrupt.
+6. Keep existing includes, admonitions, links, and examples unless they are stale.
+7. Update stale statements instead of appending contradictory new statements.
+
+Documentation must stay current. If additive-only editing would leave conflicting or stale information, update the stale information. Accuracy is more important than blindly appending content. Never leave two conflicting descriptions of the same API behavior.
+
+## Style Rules
+
+Use developer-friendly documentation style.
+
+Prefer:
+
+- Direct explanations,
+- Practical examples,
+- Concrete behavior,
+- Accurate terminology,
+- Small complete samples,
+- Links to related APIs when useful,
+- Namespace-level fly-ins that explain purpose.
+
+Avoid:
+
+- Marketing language,
+- Placeholder text,
+- "Simply",
+- "Just",
+- "Obviously",
+- Pseudo-code,
+- Incomplete snippets,
+- Unverified claims,
+- Duplicating generated API signatures manually,
+- Restating the namespace name without explaining its purpose.
+
 ## Documentation Workflow
 
 When the user names a changed API or namespace:
-
-1. Run `agents.cs`.
-2. Inspect the changed public API.
-3. Determine affected namespaces.
-4. Determine whether public extension methods are involved.
-5. Locate `.docfx/docfx.json` or repository-specific DocFX config.
-6. Locate existing overwrite files and namespace pages.
-7. Locate availability include files.
+
+1. Run `agents.cs`.
+2. Inspect the changed public API.
+3. Determine affected namespaces.
+4. Determine whether public extension methods are involved.
+5. Locate `.docfx/docfx.json` or repository-specific DocFX config.
+6. Locate existing overwrite files and namespace pages.
+7. Locate availability include files.
 8. Locate relevant tests that demonstrate the API.
 9. Convert test usage into real-life documentation examples.
 10. Update XML documentation where needed.
 11. Update or create namespace overview pages.
 12. Update extension-member tables.
 13. Update or create overwrite files, including type-page example sections for public non-abstraction types and example sections for public extension methods.
-14. Preserve manual edits.
-15. Run `dotnet build`.
-16. Run `dotnet test`.
+14. Preserve manual edits.
+15. Run `dotnet build`.
+16. Run `dotnet test`.
 17. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
 18. Confirm generated DocFX metadata and build output did not remain in the working tree.
 19. Report verification results.
@@ -520,106 +522,106 @@ When no specific API or namespace is named:
 18. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
 19. Confirm generated DocFX metadata and build output did not remain in the working tree.
 20. Report verification results and any remaining findings.
-
-## Namespace Page Template
-
-Use this template when creating a new namespace overview page:
-
-```markdown
----
-uid: X.Y.Z
-summary: *content
----
-The `X.Y.Z` namespace contains types that ...
-
-[!INCLUDE [availability-default](../../includes/availability-default.md)]
-
-### Extension Members
-
-|Type|Ext|Methods|
-|--:|:-:|---|
-|String|⬇️|`ExampleMethod`|
-```
-
-Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path based on the actual file location.
-
-## Type Example Template
-
+
+## Namespace Page Template
+
+Use this template when creating a new namespace overview page:
+
+```markdown
+---
+uid: X.Y.Z
+summary: *content
+---
+The `X.Y.Z` namespace contains types that ...
+
+[!INCLUDE [availability-default](../../includes/availability-default.md)]
+
+### Extension Members
+
+|Type|Ext|Methods|
+|--:|:-:|---|
+|String|⬇️|`ExampleMethod`|
+```
+
+Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path based on the actual file location.
+
+## Type Example Template
+
 Use this shape for public non-abstraction type examples. Put this on the generated type page/overwrite section for the type `uid`; for a public `Class1`, the example belongs on the `Class1` API page, not only on the namespace page. When no type overwrite file exists yet, create a separate per-type file such as `.docfx/api/X.Y.Z.Class1.md` and ensure `build.overwrite` includes that file.
-
-````markdown
-### Examples
-
-The following example shows how to use `MyType` in a consuming application.
-
-```csharp
-using X.Y.Z;
-
-var value = new MyType();
-Console.WriteLine(value);
-```
-````
-
-The sample must compile. Do not include `using` directives for namespaces that do not exist. Do not use APIs that are internal to the repository unless the sample is explicitly for contributors and not public API consumers.
-
-## Extension Method Example Template
-
-Use this shape for extension-method examples:
-
-````markdown
-### Examples
-
-The following example shows how to call `NormalizeLineEndings` on a string.
-
-```csharp
-using X.Y.Z;
-
-string text = "first\r\nsecond";
-string normalized = text.NormalizeLineEndings();
-Console.WriteLine(normalized);
-```
-````
-
-The namespace containing the extension method must be imported. The sample must compile in a consuming project.
-
-## Verification Checklist
-
-Before completing documentation work, verify:
-
-- [ ] `agents.cs` has run successfully.
-- [ ] `AGENTS.md` contains the managed DocFX documentation maintenance block.
-- [ ] Only public API is documented.
-- [ ] Every namespace with public API has a namespace overview page.
-- [ ] Namespaces with public extension methods have an `Extension Members` section.
+
+````markdown
+### Examples
+
+The following example shows how to use `MyType` in a consuming application.
+
+```csharp
+using X.Y.Z;
+
+var value = new MyType();
+Console.WriteLine(value);
+```
+````
+
+The sample must compile. Do not include `using` directives for namespaces that do not exist. Do not use APIs that are internal to the repository unless the sample is explicitly for contributors and not public API consumers.
+
+## Extension Method Example Template
+
+Use this shape for extension-method examples:
+
+````markdown
+### Examples
+
+The following example shows how to call `NormalizeLineEndings` on a string.
+
+```csharp
+using X.Y.Z;
+
+string text = "first\r\nsecond";
+string normalized = text.NormalizeLineEndings();
+Console.WriteLine(normalized);
+```
+````
+
+The namespace containing the extension method must be imported. The sample must compile in a consuming project.
+
+## Verification Checklist
+
+Before completing documentation work, verify:
+
+- [ ] `agents.cs` has run successfully.
+- [ ] `AGENTS.md` contains the managed DocFX documentation maintenance block.
+- [ ] Only public API is documented.
+- [ ] Every namespace with public API has a namespace overview page.
+- [ ] Namespaces with public extension methods have an `Extension Members` section.
 - [ ] Extension methods are documented by extended type, not extension class.
 - [ ] Public non-abstraction types have at least one type-page example.
 - [ ] Public extension methods have at least one example, not only a table entry.
 - [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`.
 - [ ] Abstractions without examples have a clear reason.
-- [ ] Examples are realistic and copy/paste-ready.
-- [ ] Examples compile.
-- [ ] Examples are preferably derived from passing tests.
-- [ ] Availability is included or explicitly stated.
-- [ ] Availability matches actual target frameworks and conditions.
-- [ ] Existing manual edits are preserved.
-- [ ] Stale documentation is corrected.
-- [ ] No contradictory documentation remains.
-- [ ] `dotnet build` has been run or the failure is reported.
-- [ ] `dotnet test` has been run or the failure is reported.
+- [ ] Examples are realistic and copy/paste-ready.
+- [ ] Examples compile.
+- [ ] Examples are preferably derived from passing tests.
+- [ ] Availability is included or explicitly stated.
+- [ ] Availability matches actual target frameworks and conditions.
+- [ ] Existing manual edits are preserved.
+- [ ] Stale documentation is corrected.
+- [ ] No contradictory documentation remains.
+- [ ] `dotnet build` has been run or the failure is reported.
+- [ ] `dotnet test` has been run or the failure is reported.
 - [ ] `docfx.cs --verify-docfx-build` has run successfully, including the temp-workspace DocFX build, or the failure is reported.
 - [ ] Generated DocFX metadata files and build output directories did not remain in the working tree after verification.
-
-## Completion Response
-
-When reporting completion, include:
-
-- Public APIs documented,
-- Namespace pages added or updated,
-- Extension-member tables added or updated,
-- Examples added and their source test/sample when applicable,
-- Availability handling,
-- `AGENTS.md` created, updated, already compliant, or failed,
-- Verification commands run,
-- Any verification failures or skipped checks.
-
-Do not claim documentation was verified unless the relevant command actually ran successfully.
+
+## Completion Response
+
+When reporting completion, include:
+
+- Public APIs documented,
+- Namespace pages added or updated,
+- Extension-member tables added or updated,
+- Examples added and their source test/sample when applicable,
+- Availability handling,
+- `AGENTS.md` created, updated, already compliant, or failed,
+- Verification commands run,
+- Any verification failures or skipped checks.
+
+Do not claim documentation was verified unless the relevant command actually ran successfully.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index fbd93e6..2438d42 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -1,53 +1,53 @@
-{
-  "skill_name": "dotnet-docfx-digest",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "I just added a new public class `RetryPolicy` and a public extension method `WithRetry(this HttpClient client, int attempts)` to my .NET library in the `Acme.Net.Http` namespace. Please update the DocFX documentation for this change.",
+{
+  "skill_name": "dotnet-docfx-digest",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just added a new public class `RetryPolicy` and a public extension method `WithRetry(this HttpClient client, int attempts)` to my .NET library in the `Acme.Net.Http` namespace. Please update the DocFX documentation for this change.",
       "expected_output": "Agent runs scripts/agents.cs to seed AGENTS.md, creates/updates the Acme.Net.Http namespace overview page with uid front matter, a fly-in, availability, and an Extension Members table listing the extended type with the WithRetry method, adds a buildable example for RetryPolicy, and runs scripts/docfx.cs with --verify-docfx-build to verify without leaving generated DocFX output in the working tree.",
-      "expectations": [
-        "Runs the deterministic scripts/agents.cs against the repository before completing",
-        "Creates or updates a namespace overview page named Acme.Net.Http.md with DocFX overwrite front matter whose uid matches the namespace",
-        "Adds an Extension Members table documenting the extended type (HttpClient), the ⬇️ marker, and the WithRetry method in backticks",
-        "Adds at least one copy/paste-ready, buildable example for the concrete RetryPolicy type",
-        "Includes availability information via an include or explicit Availability text",
+      "expectations": [
+        "Runs the deterministic scripts/agents.cs against the repository before completing",
+        "Creates or updates a namespace overview page named Acme.Net.Http.md with DocFX overwrite front matter whose uid matches the namespace",
+        "Adds an Extension Members table documenting the extended type (HttpClient), the ⬇️ marker, and the WithRetry method in backticks",
+        "Adds at least one copy/paste-ready, buildable example for the concrete RetryPolicy type",
+        "Includes availability information via an include or explicit Availability text",
         "Runs scripts/docfx.cs with --verify-docfx-build to verify before claiming the documentation was verified"
-      ]
-    },
-    {
-      "id": 2,
-      "prompt": "Document the new `internal` helper class `BufferPool` and the `private` method `Rent` I added under `Acme.Buffers`. There is no other public type in that namespace yet.",
-      "expected_output": "Agent declines to create documentation for internal/private members and does not create a namespace overview page for a namespace that contains no public API, explaining the public-API-only rule.",
-      "expectations": [
-        "Does not create documentation pages or overwrite files for internal or private members",
-        "Does not create a namespace overview page for Acme.Buffers because it contains no public API",
-        "Explains that only public API is documented and points to the public-API rule",
-        "Does not fabricate public API that does not exist"
-      ]
-    },
-    {
-      "id": 3,
-      "prompt": "Add a usage example to the `Acme.Text` namespace page for the `Greeter` class. Base it on the existing unit test `GreeterTest.Greet_WithName_ReturnsGreeting`.",
-      "expected_output": "Agent converts the Arrange/Act/Assert test into a real-life consumer-oriented, buildable example without raw assertions, and verifies it compiles with scripts/docfx.cs.",
-      "expectations": [
-        "Derives the example from the referenced test rather than inventing behavior",
-        "Converts the Arrange/Act/Assert structure into developer-oriented usage instead of pasting raw assertions",
-        "Produces a minimal, deterministic, copy/paste-ready C# example with a real using directive for Acme.Text",
-        "Avoids pseudo-code, ellipses, and hidden helpers in the sample",
-        "Verifies the sample compiles via scripts/docfx.cs or an equivalent build command"
-      ]
-    },
-    {
-      "id": 4,
-      "prompt": "Run the DocFX documentation validator on this repository and tell me whether the docs are in good shape.",
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Document the new `internal` helper class `BufferPool` and the `private` method `Rent` I added under `Acme.Buffers`. There is no other public type in that namespace yet.",
+      "expected_output": "Agent declines to create documentation for internal/private members and does not create a namespace overview page for a namespace that contains no public API, explaining the public-API-only rule.",
+      "expectations": [
+        "Does not create documentation pages or overwrite files for internal or private members",
+        "Does not create a namespace overview page for Acme.Buffers because it contains no public API",
+        "Explains that only public API is documented and points to the public-API rule",
+        "Does not fabricate public API that does not exist"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Add a usage example to the `Acme.Text` namespace page for the `Greeter` class. Base it on the existing unit test `GreeterTest.Greet_WithName_ReturnsGreeting`.",
+      "expected_output": "Agent converts the Arrange/Act/Assert test into a real-life consumer-oriented, buildable example without raw assertions, and verifies it compiles with scripts/docfx.cs.",
+      "expectations": [
+        "Derives the example from the referenced test rather than inventing behavior",
+        "Converts the Arrange/Act/Assert structure into developer-oriented usage instead of pasting raw assertions",
+        "Produces a minimal, deterministic, copy/paste-ready C# example with a real using directive for Acme.Text",
+        "Avoids pseudo-code, ellipses, and hidden helpers in the sample",
+        "Verifies the sample compiles via scripts/docfx.cs or an equivalent build command"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Run the DocFX documentation validator on this repository and tell me whether the docs are in good shape.",
       "expected_output": "Agent runs scripts/docfx.cs with --verify-docfx-build (and scripts/agents.cs if needed), reports the exact command, exit code, and the deterministic JSON/console findings, and does not claim verification without running the script.",
-      "expectations": [
+      "expectations": [
         "Runs scripts/docfx.cs against the repository root with --verify-docfx-build so DocFX runs in a temp workspace",
-        "Reports the exact command run and its exit code",
-        "Surfaces the deterministic findings (errors/warnings with their codes) rather than guessing",
-        "Does not claim the documentation was verified unless the script actually ran successfully"
-      ]
-    },
+        "Reports the exact command run and its exit code",
+        "Surfaces the deterministic findings (errors/warnings with their codes) rather than guessing",
+        "Does not claim the documentation was verified unless the script actually ran successfully"
+      ]
+    },
     {
       "id": 5,
       "prompt": "The `Acme.Text` namespace page already has a hand-written introduction and a couple of links I care about. I changed the `Shout` extension method to also trim whitespace. Update the docs but keep my wording.",
@@ -88,6 +88,18 @@
         "Runs scripts/docfx.cs and responds to EXAMPLE_MISSING diagnostics before claiming completion, then uses --verify-docfx-build for final DocFX build verification",
         "Compiles changed C# examples or reports the exact verification failure"
       ]
+    },
+    {
+      "id": 8,
+      "prompt": "Run dotnet-docfx-digest validation with `--changed-only` after I added a new public concrete type `Acme.Http.RetryPolicy` and a public extension method `WithRetry(this HttpClient client, int attempts)`, but I still have not added the required overwrite examples. Git is available and only the changed source files, the namespace page, and docfx.json should be considered.",
+      "expected_output": "Agent runs scripts/docfx.cs with --changed-only and still surfaces EXAMPLE_MISSING for the affected changed public APIs instead of skipping required-example validation wholesale. It scopes the check to the changed APIs and related DocFX inputs, explains which examples are still missing, and uses --verify-docfx-build before claiming the docs are verified.",
+      "expectations": [
+        "Runs scripts/docfx.cs with --changed-only when collecting incremental findings",
+        "Still surfaces EXAMPLE_MISSING for the changed concrete type and extension method when their overwrite examples are absent",
+        "Does not silently skip all required-example validation just because git returned a changed file set",
+        "Scopes the example validation to changed APIs or related DocFX inputs rather than re-reporting the whole repository by default",
+        "Uses --verify-docfx-build before claiming final verification"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/scripts/README.md b/skills/dotnet-docfx-digest/references/scripts.md
similarity index 62%
rename from skills/dotnet-docfx-digest/scripts/README.md
rename to skills/dotnet-docfx-digest/references/scripts.md
index a9b3f14..0971158 100644
--- a/skills/dotnet-docfx-digest/scripts/README.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -1,51 +1,51 @@
-# dotnet-docfx-digest scripts
-
-Two deterministic .NET 10 file-based apps back the skill so that repository guidance and documentation rules are enforced by code, not by AI memory. Each script is a single `.cs` file with no `.csproj` and runs directly:
-
-```bash
-dotnet run --file <script>.cs -- <arguments>
-dotnet build <script>.cs
-```
-
-Both declare `#:property TargetFramework=net10.0` and `#:property PublishAot=false`, return deterministic exit codes, and emit machine-readable JSON with `--json`.
-
-## agents.cs
-
-Ensures the repository root `AGENTS.md` contains a marker-bounded DocFX documentation-maintenance block. Idempotent: running it repeatedly never duplicates the block. Content outside the markers is preserved, the host file's line endings are respected, and new files are written as UTF-8 without a BOM.
-
-```bash
-dotnet run --file agents.cs -- --repo-root .            # write (default)
-dotnet run --file agents.cs -- --repo-root . --check    # CI enforcement
-dotnet run --file agents.cs -- --repo-root . --dry-run  # preview
-dotnet run --file agents.cs -- --repo-root . --json     # machine-readable
-```
-
-Markers:
-
-```markdown
-<!-- dotnet-docfx-digest:start -->
-<!-- dotnet-docfx-digest:end -->
-```
-
-If both markers exist, only the content between them (inclusive) is replaced. If neither exists, the block is appended. If exactly one marker exists, the file is treated as corrupt and the script exits non-zero.
-
-Exit codes:
-
-| Code | Meaning |
-|-----:|---------|
-| 0 | Success; file already compliant or successfully updated |
-| 1 | Validation failed in `--check` mode |
-| 2 | Invalid arguments |
-| 3 | Repository root does not exist |
-| 4 | `AGENTS.md` contains a corrupt managed block |
-| 5 | Write failed |
-
-## docfx.cs
-
-Validates the deterministic documentation requirements against the *compiled* repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies (preferring reference assemblies) via `System.Reflection.MetadataLoadContext`, resolves dependency metadata from project assets, deps files, and installed .NET framework reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, and compiles every C# documentation sample as a file-based app.
-
-```bash
-dotnet run --file docfx.cs -- --repo-root .
+# dotnet-docfx-digest script reference
+
+Two deterministic .NET 10 file-based apps back the skill so repository guidance and documentation rules are enforced by code instead of AI memory. Each script is a single `.cs` file with no `.csproj` and runs directly:
+
+```bash
+dotnet run --file <script>.cs -- <arguments>
+dotnet build <script>.cs
+```
+
+Both scripts declare `#:property TargetFramework=net10.0` and `#:property PublishAot=false`, return deterministic exit codes, and emit machine-readable JSON with `--json`.
+
+## agents.cs
+
+Ensures the repository root `AGENTS.md` contains a marker-bounded DocFX documentation-maintenance block. It is idempotent, so repeated runs never duplicate the block. Content outside the markers is preserved, the host file's line endings are respected, and new files are written as UTF-8 without a BOM.
+
+```bash
+dotnet run --file agents.cs -- --repo-root .            # write (default)
+dotnet run --file agents.cs -- --repo-root . --check    # CI enforcement
+dotnet run --file agents.cs -- --repo-root . --dry-run  # preview
+dotnet run --file agents.cs -- --repo-root . --json     # machine-readable
+```
+
+Markers:
+
+```markdown
+<!-- dotnet-docfx-digest:start -->
+<!-- dotnet-docfx-digest:end -->
+```
+
+If both markers exist, only the content between them, inclusive, is replaced. If neither exists, the block is appended. If exactly one marker exists, the file is treated as corrupt and the script exits non-zero.
+
+Exit codes:
+
+| Code | Meaning |
+|-----:|---------|
+| 0 | Success; file already compliant or successfully updated |
+| 1 | Validation failed in `--check` mode |
+| 2 | Invalid arguments |
+| 3 | Repository root does not exist |
+| 4 | `AGENTS.md` contains a corrupt managed block |
+| 5 | Write failed |
+
+## docfx.cs
+
+Validates the deterministic documentation requirements against the compiled repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies, prefers reference assemblies, loads metadata through `System.Reflection.MetadataLoadContext`, resolves dependencies from project assets, deps files, and installed .NET reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, and compiles every C# documentation sample as a file-based app.
+
+```bash
+dotnet run --file docfx.cs -- --repo-root .
 dotnet run --file docfx.cs -- --repo-root . --json
 dotnet run --file docfx.cs -- --repo-root . --no-validate-samples
 dotnet run --file docfx.cs -- --repo-root . --changed-only
@@ -55,34 +55,38 @@ dotnet run --file docfx.cs -- --repo-root . --configuration Debug --framework ne
 
 Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--framework`, `--validate-samples` / `--no-validate-samples` (default on), `--changed-only`, `--verify-docfx-build`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
-`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree, so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory when it is safely inside the repository.
-
-Exit codes:
-
-| Code | Meaning |
-|-----:|---------|
-| 0 | Validation passed |
-| 1 | Validation failed |
-| 2 | Invalid arguments |
-| 3 | Repository root does not exist |
-| 4 | DocFX configuration file not found |
-| 5 | Build failed |
-| 6 | Public API discovery failed |
-| 7 | Sample compilation failed |
-| 8 | Unexpected internal error |
-
+`--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
+
+`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory when it is safely inside the repository.
+
+Process execution drains stdout and stderr concurrently so verbose `dotnet build` or DocFX runs cannot deadlock on a full pipe while the validator waits for exit.
+
+Exit codes:
+
+| Code | Meaning |
+|-----:|---------|
+| 0 | Validation passed |
+| 1 | Validation failed |
+| 2 | Invalid arguments |
+| 3 | Repository root does not exist |
+| 4 | DocFX configuration file not found |
+| 5 | Build failed |
+| 6 | Public API discovery failed |
+| 7 | Sample compilation failed |
+| 8 | Unexpected internal error |
+
 Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`.
-
-### Sample opt-out
-
-A C# fence may opt out of compilation only with a mandatory reason:
-
-```csharp
-// dotnet-docfx-digest:skip-compile - requires a configured database connection
-```
-
-A skip marker without a reason is reported as `SAMPLE_SKIP_REASON_MISSING`.
-
-### Extension-method detection note
-
-Extension methods are detected from compiled metadata: a public static method, carrying `System.Runtime.CompilerServices.ExtensionAttribute`, declared on a public static non-generic class, with at least one parameter. The first parameter's type is recorded as the extended type. (The C# compiler marks the method — not the first parameter — with `ExtensionAttribute`, so detection keys off the method attribute to match real metadata.)
+
+### Sample opt-out
+
+A C# fence may opt out of compilation only with a mandatory reason:
+
+```csharp
+// dotnet-docfx-digest:skip-compile - requires a configured database connection
+```
+
+A skip marker without a reason is reported as `SAMPLE_SKIP_REASON_MISSING`.
+
+### Extension-method detection note
+
+Extension methods are detected from compiled metadata: a public static method, carrying `System.Runtime.CompilerServices.ExtensionAttribute`, declared on a public static non-generic class, with at least one parameter. The first parameter's type is recorded as the extended type. The C# compiler marks the method, not the first parameter, with `ExtensionAttribute`, so detection keys off the method attribute to match real metadata.
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index d76296c..7e55292 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -1,117 +1,119 @@
-#:property TargetFramework=net10.0
-#:property Nullable=enable
-#:property LangVersion=latest
-#:property PublishAot=false
-#:package System.Reflection.MetadataLoadContext@9.0.0
-
-using System.Diagnostics;
-using System.Reflection;
-using System.Text;
-using System.Text.Json;
-using System.Text.Json.Serialization;
-using System.Text.RegularExpressions;
-using System.Xml.Linq;
-
-return DocfxValidator.Run(args);
-
-internal static class DocfxValidator
-{
-    private const string ScriptId = "validate-docfx-digest";
-    private const string StartMarker = "<!-- dotnet-docfx-digest:start -->";
-    private const string EndMarker = "<!-- dotnet-docfx-digest:end -->";
-    private const string ExtensionAttributeFullName = "System.Runtime.CompilerServices.ExtensionAttribute";
-    private const string SkipMarker = "dotnet-docfx-digest:skip-compile";
-
+#:property TargetFramework=net10.0
+#:property Nullable=enable
+#:property LangVersion=latest
+#:property PublishAot=false
+#:package System.Reflection.MetadataLoadContext@9.0.0
+
+using System.Diagnostics;
+using System.Reflection;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using System.Text.RegularExpressions;
+using System.Threading.Tasks;
+using System.Xml.Linq;
+
+return DocfxValidator.Run(args);
+
+internal static class DocfxValidator
+{
+    private const string ScriptId = "validate-docfx-digest";
+    private const string StartMarker = "<!-- dotnet-docfx-digest:start -->";
+    private const string EndMarker = "<!-- dotnet-docfx-digest:end -->";
+    private const string ExtensionAttributeFullName = "System.Runtime.CompilerServices.ExtensionAttribute";
+    private const string SkipMarker = "dotnet-docfx-digest:skip-compile";
+
     private static readonly string[] IgnoredDirectorySegments = ["bin", "obj", "_site", ".git", ".vs", ".vscode", ".idea", "node_modules"];
-    private static readonly TimeSpan ProcessTimeout = TimeSpan.FromMinutes(10);
-
-    private static readonly JsonSerializerOptions JsonOptions = new()
-    {
-        WriteIndented = true,
-        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
-        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
-    };
-
-    public static int Run(string[] args)
-    {
-        Options options;
-        try
-        {
-            if (!TryParse(args, out options, out var parseError, out var wantHelp))
-            {
-                if (wantHelp)
-                {
-                    PrintUsage();
-                    return 0;
-                }
-
-                Console.Error.WriteLine($"{ScriptId}: {parseError}");
-                return (int)ExitCode.InvalidArguments;
-            }
-
-            if (options.Help)
-            {
-                PrintUsage();
-                return 0;
-            }
-        }
-        catch (Exception ex)
-        {
-            Console.Error.WriteLine($"{ScriptId}: argument parsing failed: {ex.Message}");
-            return (int)ExitCode.InvalidArguments;
-        }
-
-        try
-        {
-            return Validate(options);
-        }
-        catch (Exception ex)
-        {
-            if (options.Json)
-            {
-                var report = new Report { Script = ScriptId, Status = "failed" };
-                report.Errors.Add(new Diagnostic("INTERNAL_ERROR", null, null, $"Unexpected internal error: {ex.Message}"));
-                Console.WriteLine(JsonSerializer.Serialize(report, JsonOptions));
-            }
-            else
-            {
-                Console.Error.WriteLine($"{ScriptId}: unexpected internal error: {ex}");
-            }
-
-            return (int)ExitCode.InternalError;
-        }
-    }
-
-    private static int Validate(Options options)
-    {
-        var report = new Report { Script = ScriptId };
-
-        // 1. Resolve repository root.
-        string repoRoot;
-        try
-        {
-            repoRoot = Path.GetFullPath(string.IsNullOrWhiteSpace(options.RepoRoot) ? "." : options.RepoRoot);
-        }
-        catch (Exception ex)
-        {
-            return Emit(options, report, ExitCode.RepoRootMissing, $"Invalid repository root: {ex.Message}");
-        }
-
-        report.RepoRoot = repoRoot;
-        if (!Directory.Exists(repoRoot))
-        {
-            return Emit(options, report, ExitCode.RepoRootMissing, $"Repository root does not exist: {repoRoot}");
-        }
-
-        // 2. Locate the DocFX configuration file.
-        var docfxPath = ResolveDocfxPath(repoRoot, options.DocfxPath);
-        if (docfxPath is null)
-        {
-            report.Errors.Add(new Diagnostic("DOCFX_CONFIG_MISSING", null, null,
-                "No DocFX configuration file (docfx.json) was found. Looked under .docfx/docfx.json and the repository root."));
-            return Emit(options, report, ExitCode.DocfxConfigMissing, "DocFX configuration file not found.");
-        }
-
+    private static readonly TimeSpan ProcessTimeout = TimeSpan.FromMinutes(10);
+    private static readonly TimeSpan ProcessStreamDrainTimeout = TimeSpan.FromSeconds(5);
+
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        WriteIndented = true,
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
+    };
+
+    public static int Run(string[] args)
+    {
+        Options options;
+        try
+        {
+            if (!TryParse(args, out options, out var parseError, out var wantHelp))
+            {
+                if (wantHelp)
+                {
+                    PrintUsage();
+                    return 0;
+                }
+
+                Console.Error.WriteLine($"{ScriptId}: {parseError}");
+                return (int)ExitCode.InvalidArguments;
+            }
+
+            if (options.Help)
+            {
+                PrintUsage();
+                return 0;
+            }
+        }
+        catch (Exception ex)
+        {
+            Console.Error.WriteLine($"{ScriptId}: argument parsing failed: {ex.Message}");
+            return (int)ExitCode.InvalidArguments;
+        }
+
+        try
+        {
+            return Validate(options);
+        }
+        catch (Exception ex)
+        {
+            if (options.Json)
+            {
+                var report = new Report { Script = ScriptId, Status = "failed" };
+                report.Errors.Add(new Diagnostic("INTERNAL_ERROR", null, null, $"Unexpected internal error: {ex.Message}"));
+                Console.WriteLine(JsonSerializer.Serialize(report, JsonOptions));
+            }
+            else
+            {
+                Console.Error.WriteLine($"{ScriptId}: unexpected internal error: {ex}");
+            }
+
+            return (int)ExitCode.InternalError;
+        }
+    }
+
+    private static int Validate(Options options)
+    {
+        var report = new Report { Script = ScriptId };
+
+        // 1. Resolve repository root.
+        string repoRoot;
+        try
+        {
+            repoRoot = Path.GetFullPath(string.IsNullOrWhiteSpace(options.RepoRoot) ? "." : options.RepoRoot);
+        }
+        catch (Exception ex)
+        {
+            return Emit(options, report, ExitCode.RepoRootMissing, $"Invalid repository root: {ex.Message}");
+        }
+
+        report.RepoRoot = repoRoot;
+        if (!Directory.Exists(repoRoot))
+        {
+            return Emit(options, report, ExitCode.RepoRootMissing, $"Repository root does not exist: {repoRoot}");
+        }
+
+        // 2. Locate the DocFX configuration file.
+        var docfxPath = ResolveDocfxPath(repoRoot, options.DocfxPath);
+        if (docfxPath is null)
+        {
+            report.Errors.Add(new Diagnostic("DOCFX_CONFIG_MISSING", null, null,
+                "No DocFX configuration file (docfx.json) was found. Looked under .docfx/docfx.json and the repository root."));
+            return Emit(options, report, ExitCode.DocfxConfigMissing, "DocFX configuration file not found.");
+        }
+
         report.DocfxPath = docfxPath;
         var docfxWorkspace = Path.GetDirectoryName(docfxPath)!;
         options.Framework ??= ResolveDefaultFramework(docfxPath, report);
@@ -119,88 +121,88 @@ private static int Validate(Options options)
 
         // 3. Verify AGENTS.md contains the managed block.
         var agentsPath = Path.Combine(repoRoot, "AGENTS.md");
-        if (!AgentsBlockPresent(agentsPath))
-        {
-            report.Errors.Add(new Diagnostic("AGENTS_BLOCK_MISSING", agentsPath, null,
-                "AGENTS.md does not contain the dotnet-docfx-digest managed block. Run scripts/agents.cs first."));
-        }
-
-        // Optional changed-only scoping.
-        HashSet<string>? changedFiles = null;
-        if (options.ChangedOnly)
-        {
-            changedFiles = GetChangedFiles(repoRoot, report);
-            if (changedFiles is null)
-            {
-                report.Warnings.Add(new Diagnostic("CHANGED_ONLY_FALLBACK", null, null,
-                    "git was unavailable or the repository has no HEAD; falling back to full validation."));
-            }
-        }
-
-        // 4. Build the repository before metadata inspection.
-        var (buildOk, buildOutput) = BuildRepository(repoRoot, options.Configuration);
-        if (!buildOk)
-        {
-            report.Errors.Add(new Diagnostic("BUILD_FAILED", null, null,
-                $"dotnet build failed (configuration {options.Configuration}).\n{Trim(buildOutput)}"));
-            return Emit(options, report, ExitCode.BuildFailed, "Build failed.");
-        }
-
-        // 5-7. Discover public API, namespaces and extension methods from compiled metadata.
-        var projects = DiscoverProjects(repoRoot);
-        var libraryProjects = projects.Where(p => !p.IsTest).ToList();
-        ApiModel api;
-        try
-        {
-            api = DiscoverApi(libraryProjects, options.Configuration, options.Framework, report);
-        }
-        catch (Exception ex)
-        {
-            report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
-                $"Public API discovery failed: {ex.Message}"));
-            return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
-        }
-
-        if (api.Namespaces.Count == 0)
-        {
-            report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
-                "No public API could be discovered from the compiled library assemblies. Ensure the repository builds and exposes public types."));
-            return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
-        }
-
-        report.Summary.PublicNamespaces = api.Namespaces.Count;
+        if (!AgentsBlockPresent(agentsPath))
+        {
+            report.Errors.Add(new Diagnostic("AGENTS_BLOCK_MISSING", agentsPath, null,
+                "AGENTS.md does not contain the dotnet-docfx-digest managed block. Run scripts/agents.cs first."));
+        }
+
+        // Optional changed-only scoping.
+        HashSet<string>? changedFiles = null;
+        if (options.ChangedOnly)
+        {
+            changedFiles = GetChangedFiles(repoRoot, report);
+            if (changedFiles is null)
+            {
+                report.Warnings.Add(new Diagnostic("CHANGED_ONLY_FALLBACK", null, null,
+                    "git was unavailable or the repository has no HEAD; falling back to full validation."));
+            }
+        }
+
+        // 4. Build the repository before metadata inspection.
+        var (buildOk, buildOutput) = BuildRepository(repoRoot, options.Configuration);
+        if (!buildOk)
+        {
+            report.Errors.Add(new Diagnostic("BUILD_FAILED", null, null,
+                $"dotnet build failed (configuration {options.Configuration}).\n{Trim(buildOutput)}"));
+            return Emit(options, report, ExitCode.BuildFailed, "Build failed.");
+        }
+
+        // 5-7. Discover public API, namespaces and extension methods from compiled metadata.
+        var projects = DiscoverProjects(repoRoot);
+        var libraryProjects = projects.Where(p => !p.IsTest).ToList();
+        ApiModel api;
+        try
+        {
+            api = DiscoverApi(libraryProjects, options.Configuration, options.Framework, report);
+        }
+        catch (Exception ex)
+        {
+            report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
+                $"Public API discovery failed: {ex.Message}"));
+            return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
+        }
+
+        if (api.Namespaces.Count == 0)
+        {
+            report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
+                "No public API could be discovered from the compiled library assemblies. Ensure the repository builds and exposes public types."));
+            return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
+        }
+
+        report.Summary.PublicNamespaces = api.Namespaces.Count;
         report.Summary.RequiredExampleTargets = api.RequiredExampleTargets.Count;
-        report.Summary.ExtensionMethods = api.Namespaces.Sum(n => n.ExtensionMethods.Count);
-
-        // 8. Discover DocFX Markdown files under the workspace.
-        var markdownFiles = DiscoverMarkdown(docfxWorkspace);
-
-        // 9-11. Validate namespace overview pages, extension tables and availability.
-        foreach (var ns in api.Namespaces.OrderBy(n => n.Name, StringComparer.Ordinal))
-        {
-            var page = markdownFiles.FirstOrDefault(f =>
-                string.Equals(Path.GetFileNameWithoutExtension(f), ns.Name, StringComparison.Ordinal));
-
-            if (page is null)
-            {
-                report.Errors.Add(new Diagnostic("NAMESPACE_PAGE_MISSING", null, ns.Name,
-                    $"Missing namespace overview page for namespace {ns.Name}. Expected a file named {ns.Name}.md under {Rel(repoRoot, docfxWorkspace)}."));
-                continue;
-            }
-
-            if (options.ChangedOnly && changedFiles is not null && !changedFiles.Contains(Path.GetFullPath(page)))
-            {
-                continue;
-            }
-
-            ValidateNamespacePage(repoRoot, page, ns, report);
-            report.Summary.NamespacePagesValidated++;
-        }
-
-        // 12. Verify mandatory examples exist before compiling the examples that were found.
-        ValidateRequiredExamples(repoRoot, markdownFiles, api, options, changedFiles, report);
-
-        // 13. Extract and compile C# documentation samples.
+        report.Summary.ExtensionMethods = api.Namespaces.Sum(n => n.ExtensionMethods.Count);
+
+        // 8. Discover DocFX Markdown files under the workspace.
+        var markdownFiles = DiscoverMarkdown(docfxWorkspace);
+
+        // 9-11. Validate namespace overview pages, extension tables and availability.
+        foreach (var ns in api.Namespaces.OrderBy(n => n.Name, StringComparer.Ordinal))
+        {
+            var page = markdownFiles.FirstOrDefault(f =>
+                string.Equals(Path.GetFileNameWithoutExtension(f), ns.Name, StringComparison.Ordinal));
+
+            if (page is null)
+            {
+                report.Errors.Add(new Diagnostic("NAMESPACE_PAGE_MISSING", null, ns.Name,
+                    $"Missing namespace overview page for namespace {ns.Name}. Expected a file named {ns.Name}.md under {Rel(repoRoot, docfxWorkspace)}."));
+                continue;
+            }
+
+            if (options.ChangedOnly && changedFiles is not null && !changedFiles.Contains(Path.GetFullPath(page)))
+            {
+                continue;
+            }
+
+            ValidateNamespacePage(repoRoot, page, ns, report);
+            report.Summary.NamespacePagesValidated++;
+        }
+
+        // 12. Verify mandatory examples exist before compiling the examples that were found.
+        ValidateRequiredExamples(repoRoot, markdownFiles, api, options, changedFiles, report);
+
+        // 13. Extract and compile C# documentation samples.
         if (options.ValidateSamples)
         {
             ValidateSamples(repoRoot, markdownFiles, libraryProjects, options, changedFiles, report);
@@ -211,57 +213,57 @@ private static int Validate(Options options)
         {
             VerifyDocfxBuild(repoRoot, docfxPath, report);
         }
-
-        // 14-15. Produce report and return a deterministic exit code.
-        bool hasSampleError = report.Errors.Any(e => e.Code is "SAMPLE_COMPILE_FAILED");
-        bool hasOtherError = report.Errors.Any(e => e.Code is not "SAMPLE_COMPILE_FAILED");
-
-        report.Status = report.Errors.Count == 0 ? "passed" : "failed";
-        report.Summary.Errors = report.Errors.Count;
-        report.Summary.Warnings = report.Warnings.Count;
-
-        if (hasOtherError)
-        {
-            return Emit(options, report, ExitCode.ValidationFailed, "Validation failed.");
-        }
-
-        if (hasSampleError)
-        {
-            return Emit(options, report, ExitCode.SampleCompilationFailed, "Sample compilation failed.");
-        }
-
-        return Emit(options, report, ExitCode.Success, "Validation passed.");
-    }
-
-    // ----------------------------------------------------------------------
-    // DocFX discovery
-    // ----------------------------------------------------------------------
-
+
+        // 14-15. Produce report and return a deterministic exit code.
+        bool hasSampleError = report.Errors.Any(e => e.Code is "SAMPLE_COMPILE_FAILED");
+        bool hasOtherError = report.Errors.Any(e => e.Code is not "SAMPLE_COMPILE_FAILED");
+
+        report.Status = report.Errors.Count == 0 ? "passed" : "failed";
+        report.Summary.Errors = report.Errors.Count;
+        report.Summary.Warnings = report.Warnings.Count;
+
+        if (hasOtherError)
+        {
+            return Emit(options, report, ExitCode.ValidationFailed, "Validation failed.");
+        }
+
+        if (hasSampleError)
+        {
+            return Emit(options, report, ExitCode.SampleCompilationFailed, "Sample compilation failed.");
+        }
+
+        return Emit(options, report, ExitCode.Success, "Validation passed.");
+    }
+
+    // ----------------------------------------------------------------------
+    // DocFX discovery
+    // ----------------------------------------------------------------------
+
     private static string? ResolveDocfxPath(string repoRoot, string? explicitPath)
     {
-        if (!string.IsNullOrWhiteSpace(explicitPath))
-        {
-            var full = Path.GetFullPath(explicitPath, repoRoot);
-            return File.Exists(full) ? full : null;
-        }
-
-        var conventional = Path.Combine(repoRoot, ".docfx", "docfx.json");
-        if (File.Exists(conventional))
-        {
-            return conventional;
-        }
-
-        var atRoot = Path.Combine(repoRoot, "docfx.json");
-        if (File.Exists(atRoot))
-        {
-            return atRoot;
-        }
-
-        // Fall back to the first docfx.json found anywhere under the repo (excluding build output).
-        foreach (var file in EnumerateFiles(repoRoot, "docfx.json"))
-        {
-            return file;
-        }
+        if (!string.IsNullOrWhiteSpace(explicitPath))
+        {
+            var full = Path.GetFullPath(explicitPath, repoRoot);
+            return File.Exists(full) ? full : null;
+        }
+
+        var conventional = Path.Combine(repoRoot, ".docfx", "docfx.json");
+        if (File.Exists(conventional))
+        {
+            return conventional;
+        }
+
+        var atRoot = Path.Combine(repoRoot, "docfx.json");
+        if (File.Exists(atRoot))
+        {
+            return atRoot;
+        }
+
+        // Fall back to the first docfx.json found anywhere under the repo (excluding build output).
+        foreach (var file in EnumerateFiles(repoRoot, "docfx.json"))
+        {
+            return file;
+        }
 
         return null;
     }
@@ -520,56 +522,56 @@ private static bool IsSafeGeneratedOutputDirectory(string path, string repoRoot)
     private static List<string> DiscoverMarkdown(string docfxWorkspace)
     {
         var list = new List<string>();
-        foreach (var file in EnumerateFiles(docfxWorkspace, "*.md"))
-        {
-            list.Add(Path.GetFullPath(file));
-        }
-
-        return list;
-    }
-
+        foreach (var file in EnumerateFiles(docfxWorkspace, "*.md"))
+        {
+            list.Add(Path.GetFullPath(file));
+        }
+
+        return list;
+    }
+
     private static IEnumerable<string> EnumerateFiles(string root, string pattern)
-    {
-        var stack = new Stack<string>();
-        stack.Push(root);
-        while (stack.Count > 0)
-        {
-            var dir = stack.Pop();
-            string[] entries;
-            try
-            {
-                entries = Directory.GetDirectories(dir);
-            }
-            catch
-            {
-                continue;
-            }
-
-            foreach (var sub in entries)
-            {
-                var name = Path.GetFileName(sub);
-                if (IgnoredDirectorySegments.Contains(name, StringComparer.OrdinalIgnoreCase))
-                {
-                    continue;
-                }
-
-                stack.Push(sub);
-            }
-
-            string[] files;
-            try
-            {
-                files = Directory.GetFiles(dir, pattern);
-            }
-            catch
-            {
-                continue;
-            }
-
-            foreach (var f in files)
-            {
-                yield return f;
-            }
+    {
+        var stack = new Stack<string>();
+        stack.Push(root);
+        while (stack.Count > 0)
+        {
+            var dir = stack.Pop();
+            string[] entries;
+            try
+            {
+                entries = Directory.GetDirectories(dir);
+            }
+            catch
+            {
+                continue;
+            }
+
+            foreach (var sub in entries)
+            {
+                var name = Path.GetFileName(sub);
+                if (IgnoredDirectorySegments.Contains(name, StringComparer.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
+                stack.Push(sub);
+            }
+
+            string[] files;
+            try
+            {
+                files = Directory.GetFiles(dir, pattern);
+            }
+            catch
+            {
+                continue;
+            }
+
+            foreach (var f in files)
+            {
+                yield return f;
+            }
         }
     }
 
@@ -670,138 +672,138 @@ private static void CopyDirectory(string sourceDirectory, string destinationDire
 
     private static bool AgentsBlockPresent(string agentsPath)
     {
-        if (!File.Exists(agentsPath))
-        {
-            return false;
-        }
-
-        var text = File.ReadAllText(agentsPath);
-        return text.Contains(StartMarker, StringComparison.Ordinal) && text.Contains(EndMarker, StringComparison.Ordinal);
-    }
-
-    // ----------------------------------------------------------------------
-    // Build
-    // ----------------------------------------------------------------------
-
-    private static (bool Ok, string Output) BuildRepository(string repoRoot, string configuration)
-    {
-        // Build a solution if one is present, otherwise let dotnet resolve the project in the repo root.
-        var target = Directory.GetFiles(repoRoot, "*.slnx").Concat(Directory.GetFiles(repoRoot, "*.sln")).FirstOrDefault();
-        var args = target is null
-            ? $"build -c {configuration} --nologo"
-            : $"build \"{target}\" -c {configuration} --nologo";
-        var result = RunProcess("dotnet", args, repoRoot);
-        return (result.ExitCode == 0, result.StdOut + result.StdErr);
-    }
-
-    // ----------------------------------------------------------------------
-    // Project + API discovery
-    // ----------------------------------------------------------------------
-
-    private static List<ProjectInfo> DiscoverProjects(string repoRoot)
-    {
-        var projects = new List<ProjectInfo>();
-        foreach (var proj in EnumerateFiles(repoRoot, "*.csproj"))
-        {
-            var info = ReadProject(proj);
-            projects.Add(info);
-        }
-
-        return projects;
-    }
-
-    private static ProjectInfo ReadProject(string projectPath)
-    {
-        string? assemblyName = null;
-        var tfms = new List<string>();
-        bool isTest = false;
-
-        try
-        {
-            var doc = XDocument.Load(projectPath);
-            foreach (var el in doc.Descendants())
-            {
-                switch (el.Name.LocalName)
-                {
-                    case "AssemblyName":
-                        assemblyName = el.Value.Trim();
-                        break;
-                    case "TargetFramework":
-                        if (!string.IsNullOrWhiteSpace(el.Value))
-                        {
-                            tfms.Add(el.Value.Trim());
-                        }
-
-                        break;
-                    case "TargetFrameworks":
-                        tfms.AddRange(el.Value.Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries));
-                        break;
-                    case "IsTestProject":
-                        if (bool.TryParse(el.Value.Trim(), out var b) && b)
-                        {
-                            isTest = true;
-                        }
-
-                        break;
-                    case "PackageReference":
-                        var include = el.Attribute("Include")?.Value ?? string.Empty;
-                        if (include.Contains("Microsoft.NET.Test.Sdk", StringComparison.OrdinalIgnoreCase) ||
-                            include.Contains("xunit", StringComparison.OrdinalIgnoreCase) ||
-                            include.StartsWith("NUnit", StringComparison.OrdinalIgnoreCase) ||
-                            include.Contains("MSTest", StringComparison.OrdinalIgnoreCase))
-                        {
-                            isTest = true;
-                        }
-
-                        break;
-                }
-            }
-        }
-        catch
-        {
-            // Ignore malformed project files; they simply contribute no metadata.
-        }
-
-        assemblyName ??= Path.GetFileNameWithoutExtension(projectPath);
-
-        // Path-based heuristic: anything under a test/tests folder or named *Test(s).
-        var segments = projectPath.Split(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
-        if (segments.Any(s => string.Equals(s, "test", StringComparison.OrdinalIgnoreCase) ||
-                              string.Equals(s, "tests", StringComparison.OrdinalIgnoreCase)))
-        {
-            isTest = true;
-        }
-
-        var fileName = Path.GetFileNameWithoutExtension(projectPath);
-        if (fileName.EndsWith("Test", StringComparison.OrdinalIgnoreCase) ||
-            fileName.EndsWith("Tests", StringComparison.OrdinalIgnoreCase))
-        {
-            isTest = true;
-        }
-
-        return new ProjectInfo(projectPath, assemblyName, tfms, isTest);
-    }
-
-    private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string configuration, string? framework, Report report)
-    {
-        var assemblyPaths = new List<string>();
-        foreach (var proj in libraryProjects)
-        {
-            var dll = FindAssembly(proj, configuration, framework);
-            if (dll is not null)
-            {
-                assemblyPaths.Add(dll);
-            }
-        }
-
-        if (assemblyPaths.Count == 0)
-        {
-            return new ApiModel(new List<NamespaceInfo>(), new List<ApiTargetInfo>());
-        }
-
-        // Resolve dependencies from the runtime directory and the assemblies' own output folders.
-        var resolverPaths = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
-        var runtimeDir = System.Runtime.InteropServices.RuntimeEnvironment.GetRuntimeDirectory();
+        if (!File.Exists(agentsPath))
+        {
+            return false;
+        }
+
+        var text = File.ReadAllText(agentsPath);
+        return text.Contains(StartMarker, StringComparison.Ordinal) && text.Contains(EndMarker, StringComparison.Ordinal);
+    }
+
+    // ----------------------------------------------------------------------
+    // Build
+    // ----------------------------------------------------------------------
+
+    private static (bool Ok, string Output) BuildRepository(string repoRoot, string configuration)
+    {
+        // Build a solution if one is present, otherwise let dotnet resolve the project in the repo root.
+        var target = Directory.GetFiles(repoRoot, "*.slnx").Concat(Directory.GetFiles(repoRoot, "*.sln")).FirstOrDefault();
+        var args = target is null
+            ? $"build -c {configuration} --nologo"
+            : $"build \"{target}\" -c {configuration} --nologo";
+        var result = RunProcess("dotnet", args, repoRoot);
+        return (result.ExitCode == 0, result.StdOut + result.StdErr);
+    }
+
+    // ----------------------------------------------------------------------
+    // Project + API discovery
+    // ----------------------------------------------------------------------
+
+    private static List<ProjectInfo> DiscoverProjects(string repoRoot)
+    {
+        var projects = new List<ProjectInfo>();
+        foreach (var proj in EnumerateFiles(repoRoot, "*.csproj"))
+        {
+            var info = ReadProject(proj);
+            projects.Add(info);
+        }
+
+        return projects;
+    }
+
+    private static ProjectInfo ReadProject(string projectPath)
+    {
+        string? assemblyName = null;
+        var tfms = new List<string>();
+        bool isTest = false;
+
+        try
+        {
+            var doc = XDocument.Load(projectPath);
+            foreach (var el in doc.Descendants())
+            {
+                switch (el.Name.LocalName)
+                {
+                    case "AssemblyName":
+                        assemblyName = el.Value.Trim();
+                        break;
+                    case "TargetFramework":
+                        if (!string.IsNullOrWhiteSpace(el.Value))
+                        {
+                            tfms.Add(el.Value.Trim());
+                        }
+
+                        break;
+                    case "TargetFrameworks":
+                        tfms.AddRange(el.Value.Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries));
+                        break;
+                    case "IsTestProject":
+                        if (bool.TryParse(el.Value.Trim(), out var b) && b)
+                        {
+                            isTest = true;
+                        }
+
+                        break;
+                    case "PackageReference":
+                        var include = el.Attribute("Include")?.Value ?? string.Empty;
+                        if (include.Contains("Microsoft.NET.Test.Sdk", StringComparison.OrdinalIgnoreCase) ||
+                            include.Contains("xunit", StringComparison.OrdinalIgnoreCase) ||
+                            include.StartsWith("NUnit", StringComparison.OrdinalIgnoreCase) ||
+                            include.Contains("MSTest", StringComparison.OrdinalIgnoreCase))
+                        {
+                            isTest = true;
+                        }
+
+                        break;
+                }
+            }
+        }
+        catch
+        {
+            // Ignore malformed project files; they simply contribute no metadata.
+        }
+
+        assemblyName ??= Path.GetFileNameWithoutExtension(projectPath);
+
+        // Path-based heuristic: anything under a test/tests folder or named *Test(s).
+        var segments = projectPath.Split(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+        if (segments.Any(s => string.Equals(s, "test", StringComparison.OrdinalIgnoreCase) ||
+                              string.Equals(s, "tests", StringComparison.OrdinalIgnoreCase)))
+        {
+            isTest = true;
+        }
+
+        var fileName = Path.GetFileNameWithoutExtension(projectPath);
+        if (fileName.EndsWith("Test", StringComparison.OrdinalIgnoreCase) ||
+            fileName.EndsWith("Tests", StringComparison.OrdinalIgnoreCase))
+        {
+            isTest = true;
+        }
+
+        return new ProjectInfo(projectPath, assemblyName, tfms, isTest);
+    }
+
+    private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string configuration, string? framework, Report report)
+    {
+        var assemblyPaths = new List<string>();
+        foreach (var proj in libraryProjects)
+        {
+            var dll = FindAssembly(proj, configuration, framework);
+            if (dll is not null)
+            {
+                assemblyPaths.Add(dll);
+            }
+        }
+
+        if (assemblyPaths.Count == 0)
+        {
+            return new ApiModel(new List<NamespaceInfo>(), new List<ApiTargetInfo>());
+        }
+
+        // Resolve dependencies from the runtime directory and the assemblies' own output folders.
+        var resolverPaths = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        var runtimeDir = System.Runtime.InteropServices.RuntimeEnvironment.GetRuntimeDirectory();
         foreach (var dll in Directory.GetFiles(runtimeDir, "*.dll"))
         {
             resolverPaths.Add(dll);
@@ -830,58 +832,58 @@ private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string co
 
         var resolver = new PathAssemblyResolver(DistinctResolverPaths(resolverPaths));
         using var mlc = new MetadataLoadContext(resolver, "System.Private.CoreLib");
-
-        var namespaces = new Dictionary<string, NamespaceInfo>(StringComparer.Ordinal);
-        foreach (var dll in assemblyPaths)
-        {
-            Assembly asm;
-            try
-            {
-                asm = mlc.LoadFromAssemblyPath(dll);
-            }
-            catch
-            {
-                continue;
-            }
-
-            Type[] types;
-            try
-            {
-                types = asm.GetTypes();
-            }
-            catch (ReflectionTypeLoadException rtle)
-            {
-                types = rtle.Types.Where(t => t is not null).Cast<Type>().ToArray();
-            }
-            catch
-            {
-                continue;
-            }
-
-            foreach (var type in types)
-            {
-                if (type is null || !IsExternallyVisible(type))
-                {
-                    continue;
-                }
-
-                var nsName = type.Namespace;
-                if (string.IsNullOrEmpty(nsName))
-                {
-                    continue;
-                }
-
-                if (!namespaces.TryGetValue(nsName, out var info))
-                {
-                    info = new NamespaceInfo(nsName);
-                    namespaces[nsName] = info;
-                }
-
-                CollectApiTargets(type, info);
-                CollectExtensionMethods(type, info);
-            }
-        }
-
+
+        var namespaces = new Dictionary<string, NamespaceInfo>(StringComparer.Ordinal);
+        foreach (var dll in assemblyPaths)
+        {
+            Assembly asm;
+            try
+            {
+                asm = mlc.LoadFromAssemblyPath(dll);
+            }
+            catch
+            {
+                continue;
+            }
+
+            Type[] types;
+            try
+            {
+                types = asm.GetTypes();
+            }
+            catch (ReflectionTypeLoadException rtle)
+            {
+                types = rtle.Types.Where(t => t is not null).Cast<Type>().ToArray();
+            }
+            catch
+            {
+                continue;
+            }
+
+            foreach (var type in types)
+            {
+                if (type is null || !IsExternallyVisible(type))
+                {
+                    continue;
+                }
+
+                var nsName = type.Namespace;
+                if (string.IsNullOrEmpty(nsName))
+                {
+                    continue;
+                }
+
+                if (!namespaces.TryGetValue(nsName, out var info))
+                {
+                    info = new NamespaceInfo(nsName);
+                    namespaces[nsName] = info;
+                }
+
+                CollectApiTargets(type, info);
+                CollectExtensionMethods(type, info);
+            }
+        }
+
         var requiredExampleTargets = namespaces.Values
             .SelectMany(ns => ns.RequiredExampleTargets)
             .OrderBy(t => t.Uid, StringComparer.Ordinal)
@@ -1218,864 +1220,937 @@ private static void AddDepsRuntimeResolverPaths(JsonProperty dependency, List<st
 
     private static void CollectApiTargets(Type type, NamespaceInfo ns)
     {
-        var typeUid = TypeUid(type);
-        if (typeUid is null)
-        {
-            return;
-        }
-
+        var typeUid = TypeUid(type);
+        if (typeUid is null)
+        {
+            return;
+        }
+
         if (IsExampleRequiredType(type))
         {
             ns.RequiredExampleTargets.Add(new ApiTargetInfo(typeUid, ns.Name, ApiTargetKind.Type, SimpleTypeName(type)));
-        }
-
-        MethodInfo[] methods;
-        try
-        {
-            methods = type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly);
-        }
-        catch
-        {
-            return;
-        }
-
-        foreach (var method in methods)
-        {
-            if (!method.IsPublic || method.IsSpecialName || method.IsAbstract || !HasExtensionAttribute(method))
-            {
-                continue;
-            }
-
-            ns.RequiredExampleTargets.Add(new ApiTargetInfo(MethodUid(typeUid, method), ns.Name, ApiTargetKind.ExtensionMethod, method.Name, typeUid));
-        }
-    }
-
-    private static void CollectExtensionMethods(Type type, NamespaceInfo ns)
-    {
-        // A public extension method lives on a public static (abstract+sealed) non-generic class.
-        if (!type.IsClass || !type.IsAbstract || !type.IsSealed || type.IsGenericType || !type.IsPublic)
-        {
-            return;
-        }
-
-        MethodInfo[] methods;
-        try
-        {
-            methods = type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly);
-        }
-        catch
-        {
-            return;
-        }
-
-        foreach (var method in methods)
-        {
-            if (!method.IsStatic || !method.IsPublic)
-            {
-                continue;
-            }
-
-            if (!HasExtensionAttribute(method))
-            {
-                continue;
-            }
-
-            var parameters = method.GetParameters();
-            if (parameters.Length == 0)
-            {
-                continue;
-            }
-
-            var extendedType = SimpleTypeName(parameters[0].ParameterType);
-            ns.ExtensionMethods.Add(new ExtensionMethodInfo(method.Name, extendedType, type.Name));
-        }
-    }
-
-    private static bool HasExtensionAttribute(MemberInfo member)
-    {
-        try
-        {
-            foreach (var attr in member.GetCustomAttributesData())
-            {
-                if (string.Equals(attr.AttributeType.FullName, ExtensionAttributeFullName, StringComparison.Ordinal))
-                {
-                    return true;
-                }
-            }
-        }
-        catch
-        {
-            // ignore
-        }
-
-        return false;
-    }
-
-    private static bool IsExternallyVisible(Type type)
-    {
-        try
-        {
-            if (type.IsNested)
-            {
-                return type.IsNestedPublic && type.DeclaringType is not null && IsExternallyVisible(type.DeclaringType);
-            }
-
-            return type.IsPublic;
-        }
-        catch
-        {
-            return false;
-        }
-    }
-
-    private static bool IsExampleRequiredType(Type type)
-    {
-        if (type.IsInterface || type.IsAbstract)
+        }
+
+        MethodInfo[] methods;
+        try
         {
-            return false;
+            methods = type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly);
+        }
+        catch
+        {
+            return;
         }
 
-        return true;
+        foreach (var method in methods)
+        {
+            if (!method.IsPublic || method.IsSpecialName || method.IsAbstract || !HasExtensionAttribute(method))
+            {
+                continue;
+            }
+
+            ns.RequiredExampleTargets.Add(new ApiTargetInfo(MethodUid(typeUid, method), ns.Name, ApiTargetKind.ExtensionMethod, method.Name, typeUid));
+        }
     }
-
-    private static string? TypeUid(Type type)
-    {
-        var fullName = type.FullName;
-        if (string.IsNullOrWhiteSpace(fullName))
-        {
-            return null;
-        }
-
-        return fullName.Replace('+', '.');
-    }
-
-    private static string MethodUid(string typeUid, MethodInfo method)
-    {
-        var parameters = method.GetParameters()
-            .Select(p => TypeUid(p.ParameterType) ?? SimpleTypeName(p.ParameterType));
-
-        return typeUid + "." + method.Name + "(" + string.Join(",", parameters) + ")";
-    }
-
-    private static string SimpleTypeName(Type type)
-    {
-        var name = type.Name;
-        var tick = name.IndexOf('`');
-        return tick >= 0 ? name[..tick] : name;
-    }
-
-    private static string? FindAssembly(ProjectInfo project, string configuration, string? framework)
-    {
-        var projDir = Path.GetDirectoryName(project.Path)!;
-        var dllName = project.AssemblyName + ".dll";
-
-        // Prefer reference assemblies (ref/) when present, then regular output. Honor --framework.
-        var roots = new[] { Path.Combine(projDir, "bin", configuration), Path.Combine(projDir, "obj", configuration) };
-        string? fallback = null;
-
-        foreach (var root in roots)
-        {
-            if (!Directory.Exists(root))
-            {
-                continue;
-            }
-
-            IEnumerable<string> candidates;
-            try
-            {
-                candidates = Directory.GetFiles(root, dllName, SearchOption.AllDirectories);
-            }
-            catch
-            {
-                continue;
-            }
-
-            foreach (var candidate in candidates)
-            {
-                if (framework is not null && !candidate.Replace('\\', '/').Contains($"/{framework}/", StringComparison.OrdinalIgnoreCase))
-                {
-                    continue;
-                }
-
-                var isRef = candidate.Replace('\\', '/').Contains("/ref/", StringComparison.OrdinalIgnoreCase);
-                if (isRef)
-                {
-                    return candidate;
-                }
-
-                fallback ??= candidate;
-            }
-        }
-
-        return fallback;
-    }
-
-    // ----------------------------------------------------------------------
-    // Namespace page validation
-    // ----------------------------------------------------------------------
-
-    private static void ValidateNamespacePage(string repoRoot, string page, NamespaceInfo ns, Report report)
-    {
-        var rel = Rel(repoRoot, page);
-        string text;
-        try
-        {
-            text = File.ReadAllText(page);
-        }
-        catch (Exception ex)
-        {
-            report.Errors.Add(new Diagnostic("NAMESPACE_PAGE_MISSING", rel, ns.Name, $"Unable to read namespace page: {ex.Message}"));
-            return;
-        }
-
-        var (frontMatter, body) = SplitFrontMatter(text);
-
-        // uid
-        var uid = ReadYamlScalar(frontMatter, "uid");
-        if (uid is null)
-        {
-            report.Errors.Add(new Diagnostic("NAMESPACE_UID_MISSING", rel, ns.Name,
-                $"Namespace page is missing a 'uid' in its DocFX overwrite front matter."));
-        }
-        else if (!string.Equals(uid, ns.Name, StringComparison.Ordinal))
-        {
-            report.Errors.Add(new Diagnostic("NAMESPACE_UID_MISMATCH", rel, ns.Name,
-                $"Namespace page uid '{uid}' does not match the namespace '{ns.Name}'."));
-        }
-
-        // summary
-        if (ReadYamlScalar(frontMatter, "summary") is null)
-        {
-            report.Errors.Add(new Diagnostic("NAMESPACE_SUMMARY_MISSING", rel, ns.Name,
-                "Namespace page front matter is missing a 'summary' key (expected 'summary: *content')."));
-        }
-
-        // fly-in paragraph
-        if (!HasFlyIn(body))
-        {
-            report.Errors.Add(new Diagnostic("NAMESPACE_FLYIN_MISSING", rel, ns.Name,
-                "Namespace page has no human-written fly-in paragraph, or contains only placeholder text."));
-        }
-
-        // availability
-        if (!HasAvailability(body))
-        {
-            report.Errors.Add(new Diagnostic("AVAILABILITY_MISSING", rel, ns.Name,
-                "Namespace page has no availability information (expected an availability include or explicit 'Availability:' text)."));
-        }
-
-        // extension members
-        if (ns.ExtensionMethods.Count > 0)
-        {
-            ValidateExtensionSection(rel, body, ns, report);
-        }
-    }
-
-    private static void ValidateExtensionSection(string rel, string body, NamespaceInfo ns, Report report)
-    {
-        var sectionMatch = Regex.Match(body, @"(?im)^#{2,4}\s+Extension\s+Members\s*$");
-        if (!sectionMatch.Success)
-        {
-            report.Errors.Add(new Diagnostic("EXTENSION_SECTION_MISSING", rel, ns.Name,
-                $"Namespace {ns.Name} exposes public extension methods but the page has no 'Extension Members' section."));
-            return;
-        }
-
-        var section = body[sectionMatch.Index..];
-        // Stop at the next heading of equal-or-higher level.
-        var nextHeading = Regex.Match(section[sectionMatch.Length..], @"(?im)^#{1,4}\s+\S");
-        if (nextHeading.Success)
-        {
-            section = section[..(sectionMatch.Length + nextHeading.Index)];
-        }
-
-        if (!Regex.IsMatch(section, @"\|\s*Type\s*\|\s*Ext\s*\|\s*Methods\s*\|", RegexOptions.IgnoreCase))
-        {
-            report.Errors.Add(new Diagnostic("EXTENSION_TABLE_MISSING", rel, ns.Name,
-                $"The 'Extension Members' section for namespace {ns.Name} is missing the '|Type|Ext|Methods|' table header."));
-            return;
-        }
-
-        // Every discovered extension method name must appear (backticked) in the section.
-        foreach (var group in ns.ExtensionMethods.GroupBy(m => m.MethodName, StringComparer.Ordinal))
-        {
-            var methodName = group.Key;
-            var pattern = "`" + Regex.Escape(methodName);
-            if (!Regex.IsMatch(section, pattern + @"[`(]"))
-            {
-                report.Errors.Add(new Diagnostic("EXTENSION_METHOD_MISSING", rel, ns.Name,
-                    $"Extension method `{methodName}` (extending {group.First().ExtendedType}) is not listed in the 'Extension Members' table for namespace {ns.Name}."));
-            }
-        }
-    }
-
-    private static bool HasFlyIn(string body)
-    {
-        foreach (var raw in body.Split('\n'))
-        {
-            var line = raw.Trim();
-            if (line.Length == 0)
-            {
-                continue;
-            }
-
-            if (line.StartsWith('#') || line.StartsWith('|') || line.StartsWith("[!INCLUDE", StringComparison.OrdinalIgnoreCase) ||
-                line.StartsWith("```", StringComparison.Ordinal) || line.StartsWith("---", StringComparison.Ordinal))
-            {
-                continue;
-            }
-
-            // Reject template placeholders like "contains types that ..." or bare ellipses / TODO.
-            if (line.Contains("...", StringComparison.Ordinal) || line.Contains("TODO", StringComparison.OrdinalIgnoreCase) ||
-                line.EndsWith("contains types that", StringComparison.OrdinalIgnoreCase))
-            {
-                continue;
-            }
-
-            if (line.Length >= 20)
-            {
-                return true;
-            }
-        }
-
-        return false;
-    }
-
-    private static bool HasAvailability(string body)
-    {
-        if (body.Contains("[!INCLUDE", StringComparison.OrdinalIgnoreCase))
-        {
-            return true;
-        }
-
-        return Regex.IsMatch(body, @"(?im)^\s*Availability\s*:");
-    }
-
-    // ----------------------------------------------------------------------
-    // Required example validation
-    // ----------------------------------------------------------------------
-
-    private static void ValidateRequiredExamples(string repoRoot, List<string> markdownFiles, ApiModel api,
-        Options options, HashSet<string>? changedFiles, Report report)
-    {
-        if (options.ChangedOnly && changedFiles is not null)
-        {
-            return;
-        }
-
-        var sections = new List<OverwriteSection>();
-        foreach (var md in markdownFiles)
-        {
-            sections.AddRange(ExtractOverwriteSections(md));
-        }
-
-        foreach (var target in api.RequiredExampleTargets)
-        {
-            var candidates = sections.Where(s => IsExampleCandidate(s, target)).ToList();
-            if (candidates.Any(s => HasExampleForTarget(s, target)))
-            {
-                report.Summary.RequiredExamples++;
-                continue;
-            }
-
-            var expectedUid = target.Kind == ApiTargetKind.Type
-                ? target.Uid
-                : target.DeclaringTypeUid ?? target.Uid;
-
-            var message = target.Kind == ApiTargetKind.Type
-                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to a per-type overwrite file for uid `{target.Uid}` (for Codebelt repositories, create `.docfx/api/{target.Uid}.md` and ensure build.overwrite includes it, for example with `api/**/*.md`)."
-                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}`, its declaring type uid `{expectedUid}`, or the namespace page `{target.Namespace}`.";
-
-            report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", null, target.Namespace, message));
-        }
-    }
-
-    private static bool IsExampleCandidate(OverwriteSection section, ApiTargetInfo target)
-    {
-        if (string.Equals(section.Uid, target.Uid, StringComparison.Ordinal))
-        {
-            return true;
-        }
-
-        if (target.Kind == ApiTargetKind.ExtensionMethod)
-        {
-            return string.Equals(section.Uid, target.DeclaringTypeUid, StringComparison.Ordinal) ||
-                   string.Equals(section.Uid, target.Namespace, StringComparison.Ordinal);
-        }
-
-        return false;
-    }
-
-    private static bool HasExampleForTarget(OverwriteSection section, ApiTargetInfo target)
-    {
-        if (!HasExampleSectionWithCSharpFence(section.Body))
-        {
-            return false;
-        }
-
-        if (target.Kind == ApiTargetKind.ExtensionMethod &&
-            !section.Body.Contains(target.DisplayName, StringComparison.Ordinal))
-        {
-            return false;
-        }
-
-        return true;
-    }
-
-    private static bool HasExampleSectionWithCSharpFence(string body)
-    {
-        var match = Regex.Match(body, @"(?im)^#{2,5}\s+Examples?\s*$");
-        if (!match.Success)
-        {
-            return false;
-        }
-
-        var section = body[match.Index..];
-        var nextHeading = Regex.Match(section[match.Length..], @"(?im)^#{1,5}\s+\S");
-        if (nextHeading.Success)
-        {
-            section = section[..(match.Length + nextHeading.Index)];
-        }
-
-        return Regex.IsMatch(section, @"(?im)^```\s*(csharp|cs)\s*$");
-    }
-
-    // ----------------------------------------------------------------------
-    // Sample validation
-    // ----------------------------------------------------------------------
-
-    private static void ValidateSamples(string repoRoot, List<string> markdownFiles, List<ProjectInfo> libraryProjects,
-        Options options, HashSet<string>? changedFiles, Report report)
-    {
-        var samples = new List<SampleFence>();
-        foreach (var md in markdownFiles)
-        {
-            if (options.ChangedOnly && changedFiles is not null && !changedFiles.Contains(Path.GetFullPath(md)))
-            {
-                continue;
-            }
-
-            samples.AddRange(ExtractFences(md));
-        }
-
-        if (samples.Count == 0)
-        {
-            return;
-        }
-
-        var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-samples-" + Guid.NewGuid().ToString("N"));
-        Directory.CreateDirectory(tempRoot);
-        try
-        {
-            int index = 0;
-            foreach (var sample in samples)
-            {
-                index++;
-                var skip = FindSkip(sample.Code);
-                if (skip.Found)
-                {
-                    if (string.IsNullOrWhiteSpace(skip.Reason))
-                    {
-                        report.Errors.Add(new Diagnostic("SAMPLE_SKIP_REASON_MISSING", Rel(repoRoot, sample.File), null,
-                            $"A C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) uses the skip-compile marker without a mandatory reason."));
-                    }
-                    else
-                    {
-                        report.Summary.SamplesSkipped++;
-                    }
-
-                    continue;
-                }
-
-                var (ok, diagnostics, exitCode) = CompileSample(tempRoot, index, sample, libraryProjects, options.Configuration);
-                if (ok)
-                {
-                    report.Summary.SamplesCompiled++;
-                }
-                else
-                {
-                    report.Errors.Add(new Diagnostic("SAMPLE_COMPILE_FAILED", Rel(repoRoot, sample.File), null,
-                        $"C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) failed to compile (exit {exitCode}).\n{Trim(diagnostics)}"));
-                }
-            }
-        }
-        finally
-        {
-            TryDeleteDirectory(tempRoot);
-        }
-    }
-
-    private static (bool Ok, string Diagnostics, int ExitCode) CompileSample(string tempRoot, int index, SampleFence sample,
-        List<ProjectInfo> libraryProjects, string configuration)
-    {
-        var dir = Path.Combine(tempRoot, "sample_" + index);
-        Directory.CreateDirectory(dir);
-        var file = Path.Combine(dir, "sample.cs");
-
-        var sb = new StringBuilder();
-        sb.Append("#:property TargetFramework=net10.0\n");
-        sb.Append("#:property PublishAot=false\n");
-        sb.Append("#:property Nullable=enable\n");
-        foreach (var proj in libraryProjects)
-        {
-            sb.Append("#:project ").Append(proj.Path).Append('\n');
-        }
-
-        sb.Append('\n');
-        sb.Append(sample.Code);
-        if (!sample.Code.EndsWith('\n'))
-        {
-            sb.Append('\n');
-        }
-
-        File.WriteAllText(file, sb.ToString(), new UTF8Encoding(false));
-
-        var result = RunProcess("dotnet", $"build \"{file}\" -c {configuration} --nologo", dir);
-        return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
-    }
-
-    private static List<SampleFence> ExtractFences(string mdFile)
-    {
-        var fences = new List<SampleFence>();
-        string[] lines;
-        try
-        {
-            lines = File.ReadAllLines(mdFile);
-        }
-        catch
-        {
-            return fences;
-        }
-
-        int fenceIndex = 0;
-        for (int i = 0; i < lines.Length; i++)
-        {
-            var trimmed = lines[i].TrimStart();
-            if (!trimmed.StartsWith("```", StringComparison.Ordinal))
-            {
-                continue;
-            }
-
-            var info = trimmed.TrimStart('`').Trim().ToLowerInvariant();
-            int start = i;
-            int j = i + 1;
-            var content = new StringBuilder();
-            while (j < lines.Length && !lines[j].TrimStart().StartsWith("```", StringComparison.Ordinal))
-            {
-                content.Append(lines[j]).Append('\n');
-                j++;
-            }
-
-            if (info is "csharp" or "cs")
-            {
-                fenceIndex++;
-                fences.Add(new SampleFence(mdFile, fenceIndex, start + 1, content.ToString()));
-            }
-
-            i = j; // continue after the closing fence
-        }
-
-        return fences;
-    }
-
-    private static List<OverwriteSection> ExtractOverwriteSections(string mdFile)
-    {
-        var sections = new List<OverwriteSection>();
-        string text;
-        try
-        {
-            text = File.ReadAllText(mdFile);
-        }
-        catch
-        {
-            return sections;
-        }
-
-        var normalized = text.Replace("\r\n", "\n").Replace("\r", "\n");
-        var matches = Regex.Matches(normalized, @"(?ms)^---\s*\n(?<yaml>.*?)^---\s*$");
-        for (var i = 0; i < matches.Count; i++)
-        {
-            var match = matches[i];
-            var yaml = match.Groups["yaml"].Value;
-            var uid = ReadYamlScalar(yaml, "uid");
-            if (string.IsNullOrWhiteSpace(uid))
-            {
-                continue;
-            }
-
-            var bodyStart = match.Index + match.Length;
-            if (bodyStart < normalized.Length && normalized[bodyStart] == '\n')
-            {
-                bodyStart++;
-            }
-
-            var bodyEnd = i + 1 < matches.Count ? matches[i + 1].Index : normalized.Length;
-            var body = bodyEnd > bodyStart ? normalized[bodyStart..bodyEnd] : string.Empty;
-            sections.Add(new OverwriteSection(mdFile, uid, body));
-        }
-
-        return sections;
-    }
-
-    private static (bool Found, string Reason) FindSkip(string code)
-    {
-        foreach (var line in code.Split('\n'))
-        {
-            var idx = line.IndexOf(SkipMarker, StringComparison.Ordinal);
-            if (idx < 0)
-            {
-                continue;
-            }
-
-            var after = line[(idx + SkipMarker.Length)..].Trim();
-            if (after.StartsWith('-'))
-            {
-                after = after[1..].Trim();
-            }
-
-            return (true, after);
-        }
-
-        return (false, string.Empty);
-    }
-
-    // ----------------------------------------------------------------------
-    // git changed-only
-    // ----------------------------------------------------------------------
-
-    private static HashSet<string>? GetChangedFiles(string repoRoot, Report report)
-    {
-        var result = RunProcess("git", "rev-parse --verify HEAD", repoRoot);
-        if (result.ExitCode != 0)
-        {
-            return null;
-        }
-
-        var diff = RunProcess("git", "diff --name-only --diff-filter=ACMRTUXB HEAD", repoRoot);
-        if (diff.ExitCode != 0)
-        {
-            return null;
-        }
-
-        var set = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
-        foreach (var line in diff.StdOut.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
-        {
-            set.Add(Path.GetFullPath(Path.Combine(repoRoot, line)));
-        }
-
-        return set;
-    }
-
-    // ----------------------------------------------------------------------
-    // YAML / markdown helpers
-    // ----------------------------------------------------------------------
-
-    private static (string FrontMatter, string Body) SplitFrontMatter(string text)
-    {
-        var normalized = text.Replace("\r\n", "\n").Replace("\r", "\n");
-        if (!normalized.StartsWith("---\n", StringComparison.Ordinal))
-        {
-            return (string.Empty, normalized);
-        }
-
-        var end = normalized.IndexOf("\n---", 3, StringComparison.Ordinal);
-        if (end < 0)
-        {
-            return (string.Empty, normalized);
-        }
-
-        var frontMatter = normalized[4..end];
-        var afterIdx = normalized.IndexOf('\n', end + 1);
-        var body = afterIdx >= 0 ? normalized[(afterIdx + 1)..] : string.Empty;
-        return (frontMatter, body);
-    }
-
-    private static string? ReadYamlScalar(string frontMatter, string key)
-    {
-        foreach (var raw in frontMatter.Split('\n'))
-        {
-            var line = raw.Trim();
-            if (line.StartsWith(key + ":", StringComparison.Ordinal))
-            {
-                var value = line[(key.Length + 1)..].Trim();
-                return value.Length == 0 ? null : value;
-            }
-        }
-
-        return null;
-    }
-
-    // ----------------------------------------------------------------------
-    // Process + output helpers
-    // ----------------------------------------------------------------------
-
-    private static ProcessResult RunProcess(string fileName, string arguments, string workingDirectory)
-    {
-        var psi = new ProcessStartInfo
-        {
-            FileName = fileName,
-            Arguments = arguments,
-            WorkingDirectory = workingDirectory,
-            RedirectStandardOutput = true,
-            RedirectStandardError = true,
-            UseShellExecute = false,
-            CreateNoWindow = true
-        };
-
-        try
-        {
-            using var process = Process.Start(psi);
-            if (process is null)
-            {
-                return new ProcessResult(-1, string.Empty, $"Failed to start process '{fileName}'.");
-            }
-
-            var stdout = process.StandardOutput.ReadToEnd();
-            var stderr = process.StandardError.ReadToEnd();
-            if (!process.WaitForExit(ProcessTimeout))
-            {
-                try
-                {
-                    process.Kill(entireProcessTree: true);
-                }
-                catch
-                {
-                    // ignore
-                }
-
-                return new ProcessResult(-1, stdout, stderr + $"\nProcess '{fileName}' timed out after {ProcessTimeout.TotalMinutes} minutes.");
-            }
-
-            return new ProcessResult(process.ExitCode, stdout, stderr);
-        }
-        catch (Exception ex)
-        {
-            return new ProcessResult(-1, string.Empty, $"Failed to run '{fileName} {arguments}': {ex.Message}");
-        }
-    }
-
-    private static void TryDeleteDirectory(string path)
-    {
-        try
-        {
-            if (Directory.Exists(path))
-            {
-                Directory.Delete(path, recursive: true);
-            }
-        }
-        catch
-        {
-            // best effort
-        }
-    }
-
-    private static string Rel(string root, string path)
-    {
-        try
-        {
-            return Path.GetRelativePath(root, path).Replace('\\', '/');
-        }
-        catch
-        {
-            return path;
-        }
-    }
-
-    private static string Trim(string text)
-    {
-        const int max = 4000;
-        text = text.Trim();
-        return text.Length <= max ? text : text[..max] + "\n... (truncated)";
-    }
-
-    private static int Emit(Options options, Report report, ExitCode code, string consoleMessage)
-    {
-        if (report.Status is null)
-        {
-            report.Status = code == ExitCode.Success ? "passed" : "failed";
-        }
-
-        report.Summary.Errors = report.Errors.Count;
-        report.Summary.Warnings = report.Warnings.Count;
-
-        if (options.Json)
-        {
-            Console.WriteLine(JsonSerializer.Serialize(report, JsonOptions));
-        }
-        else
-        {
-            Console.WriteLine($"{ScriptId}: {report.Status}: {consoleMessage}");
-            foreach (var error in report.Errors)
-            {
-                Console.WriteLine($"  ERROR  [{error.Code}] {Describe(error)}");
-            }
-
-            foreach (var warning in report.Warnings)
-            {
-                Console.WriteLine($"  WARN   [{warning.Code}] {Describe(warning)}");
-            }
-
-            Console.WriteLine(
-                $"  Summary: namespaces={report.Summary.PublicNamespaces}, pages={report.Summary.NamespacePagesValidated}, " +
-                $"requiredExampleTargets={report.Summary.RequiredExampleTargets}, requiredExamples={report.Summary.RequiredExamples}, " +
-                $"extMethods={report.Summary.ExtensionMethods}, samplesCompiled={report.Summary.SamplesCompiled}, " +
-                $"samplesSkipped={report.Summary.SamplesSkipped}, generatedMetadataRemoved={report.Summary.GeneratedMetadataFilesRemoved}, " +
-                $"generatedOutputDirectoriesRemoved={report.Summary.GeneratedOutputDirectoriesRemoved}, " +
-                $"docfxBuildsVerified={report.Summary.DocfxBuildsVerified}, errors={report.Summary.Errors}, warnings={report.Summary.Warnings}");
+
+    private static void CollectExtensionMethods(Type type, NamespaceInfo ns)
+    {
+        // A public extension method lives on a public static (abstract+sealed) non-generic class.
+        if (!type.IsClass || !type.IsAbstract || !type.IsSealed || type.IsGenericType || !type.IsPublic)
+        {
+            return;
         }
-
-        return (int)code;
-    }
-
-    private static string Describe(Diagnostic d)
-    {
-        var location = d.Namespace is not null ? $"({d.Namespace}) " : string.Empty;
-        var path = d.Path is not null ? $"{d.Path}: " : string.Empty;
-        return $"{path}{location}{d.Message}";
-    }
-
-    // ----------------------------------------------------------------------
-    // Argument parsing
-    // ----------------------------------------------------------------------
-
-    private static bool TryParse(string[] args, out Options options, out string error, out bool wantHelp)
-    {
-        options = new Options();
-        error = string.Empty;
-        wantHelp = false;
-
-        for (int i = 0; i < args.Length; i++)
-        {
-            var arg = args[i];
-            switch (arg)
-            {
-                case "--help":
-                case "-h":
-                    options.Help = true;
-                    wantHelp = true;
-                    return true;
-                case "--repo-root":
-                    if (!Next(args, ref i, out var rr)) { error = "--repo-root requires a path."; return false; }
-                    options.RepoRoot = rr;
-                    break;
-                case "--docfx":
-                    if (!Next(args, ref i, out var dx)) { error = "--docfx requires a path."; return false; }
-                    options.DocfxPath = dx;
-                    break;
-                case "--configuration":
-                    if (!Next(args, ref i, out var cfg)) { error = "--configuration requires a name."; return false; }
-                    options.Configuration = cfg;
-                    break;
-                case "--framework":
-                    if (!Next(args, ref i, out var fw)) { error = "--framework requires a TFM."; return false; }
-                    options.Framework = fw;
-                    break;
-                case "--validate-samples":
-                    options.ValidateSamples = true;
-                    break;
-                case "--no-validate-samples":
-                    options.ValidateSamples = false;
-                    break;
+
+        MethodInfo[] methods;
+        try
+        {
+            methods = type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly);
+        }
+        catch
+        {
+            return;
+        }
+
+        foreach (var method in methods)
+        {
+            if (!method.IsStatic || !method.IsPublic)
+            {
+                continue;
+            }
+
+            if (!HasExtensionAttribute(method))
+            {
+                continue;
+            }
+
+            var parameters = method.GetParameters();
+            if (parameters.Length == 0)
+            {
+                continue;
+            }
+
+            var extendedType = SimpleTypeName(parameters[0].ParameterType);
+            ns.ExtensionMethods.Add(new ExtensionMethodInfo(method.Name, extendedType, type.Name));
+        }
+    }
+
+    private static bool HasExtensionAttribute(MemberInfo member)
+    {
+        try
+        {
+            foreach (var attr in member.GetCustomAttributesData())
+            {
+                if (string.Equals(attr.AttributeType.FullName, ExtensionAttributeFullName, StringComparison.Ordinal))
+                {
+                    return true;
+                }
+            }
+        }
+        catch
+        {
+            // ignore
+        }
+
+        return false;
+    }
+
+    private static bool IsExternallyVisible(Type type)
+    {
+        try
+        {
+            if (type.IsNested)
+            {
+                return type.IsNestedPublic && type.DeclaringType is not null && IsExternallyVisible(type.DeclaringType);
+            }
+
+            return type.IsPublic;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    private static bool IsExampleRequiredType(Type type)
+    {
+        if (type.IsInterface || type.IsAbstract)
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static string? TypeUid(Type type)
+    {
+        var fullName = type.FullName;
+        if (string.IsNullOrWhiteSpace(fullName))
+        {
+            return null;
+        }
+
+        return fullName.Replace('+', '.');
+    }
+
+    private static string MethodUid(string typeUid, MethodInfo method)
+    {
+        var parameters = method.GetParameters()
+            .Select(p => TypeUid(p.ParameterType) ?? SimpleTypeName(p.ParameterType));
+
+        return typeUid + "." + method.Name + "(" + string.Join(",", parameters) + ")";
+    }
+
+    private static string SimpleTypeName(Type type)
+    {
+        var name = type.Name;
+        var tick = name.IndexOf('`');
+        return tick >= 0 ? name[..tick] : name;
+    }
+
+    private static string? FindAssembly(ProjectInfo project, string configuration, string? framework)
+    {
+        var projDir = Path.GetDirectoryName(project.Path)!;
+        var dllName = project.AssemblyName + ".dll";
+
+        // Prefer reference assemblies (ref/) when present, then regular output. Honor --framework.
+        var roots = new[] { Path.Combine(projDir, "bin", configuration), Path.Combine(projDir, "obj", configuration) };
+        string? fallback = null;
+
+        foreach (var root in roots)
+        {
+            if (!Directory.Exists(root))
+            {
+                continue;
+            }
+
+            IEnumerable<string> candidates;
+            try
+            {
+                candidates = Directory.GetFiles(root, dllName, SearchOption.AllDirectories);
+            }
+            catch
+            {
+                continue;
+            }
+
+            foreach (var candidate in candidates)
+            {
+                if (framework is not null && !candidate.Replace('\\', '/').Contains($"/{framework}/", StringComparison.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
+                var isRef = candidate.Replace('\\', '/').Contains("/ref/", StringComparison.OrdinalIgnoreCase);
+                if (isRef)
+                {
+                    return candidate;
+                }
+
+                fallback ??= candidate;
+            }
+        }
+
+        return fallback;
+    }
+
+    // ----------------------------------------------------------------------
+    // Namespace page validation
+    // ----------------------------------------------------------------------
+
+    private static void ValidateNamespacePage(string repoRoot, string page, NamespaceInfo ns, Report report)
+    {
+        var rel = Rel(repoRoot, page);
+        string text;
+        try
+        {
+            text = File.ReadAllText(page);
+        }
+        catch (Exception ex)
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_PAGE_MISSING", rel, ns.Name, $"Unable to read namespace page: {ex.Message}"));
+            return;
+        }
+
+        var (frontMatter, body) = SplitFrontMatter(text);
+
+        // uid
+        var uid = ReadYamlScalar(frontMatter, "uid");
+        if (uid is null)
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_UID_MISSING", rel, ns.Name,
+                $"Namespace page is missing a 'uid' in its DocFX overwrite front matter."));
+        }
+        else if (!string.Equals(uid, ns.Name, StringComparison.Ordinal))
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_UID_MISMATCH", rel, ns.Name,
+                $"Namespace page uid '{uid}' does not match the namespace '{ns.Name}'."));
+        }
+
+        // summary
+        if (ReadYamlScalar(frontMatter, "summary") is null)
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_SUMMARY_MISSING", rel, ns.Name,
+                "Namespace page front matter is missing a 'summary' key (expected 'summary: *content')."));
+        }
+
+        // fly-in paragraph
+        if (!HasFlyIn(body))
+        {
+            report.Errors.Add(new Diagnostic("NAMESPACE_FLYIN_MISSING", rel, ns.Name,
+                "Namespace page has no human-written fly-in paragraph, or contains only placeholder text."));
+        }
+
+        // availability
+        if (!HasAvailability(body))
+        {
+            report.Errors.Add(new Diagnostic("AVAILABILITY_MISSING", rel, ns.Name,
+                "Namespace page has no availability information (expected an availability include or explicit 'Availability:' text)."));
+        }
+
+        // extension members
+        if (ns.ExtensionMethods.Count > 0)
+        {
+            ValidateExtensionSection(rel, body, ns, report);
+        }
+    }
+
+    private static void ValidateExtensionSection(string rel, string body, NamespaceInfo ns, Report report)
+    {
+        var sectionMatch = Regex.Match(body, @"(?im)^#{2,4}\s+Extension\s+Members\s*$");
+        if (!sectionMatch.Success)
+        {
+            report.Errors.Add(new Diagnostic("EXTENSION_SECTION_MISSING", rel, ns.Name,
+                $"Namespace {ns.Name} exposes public extension methods but the page has no 'Extension Members' section."));
+            return;
+        }
+
+        var section = body[sectionMatch.Index..];
+        // Stop at the next heading of equal-or-higher level.
+        var nextHeading = Regex.Match(section[sectionMatch.Length..], @"(?im)^#{1,4}\s+\S");
+        if (nextHeading.Success)
+        {
+            section = section[..(sectionMatch.Length + nextHeading.Index)];
+        }
+
+        if (!Regex.IsMatch(section, @"\|\s*Type\s*\|\s*Ext\s*\|\s*Methods\s*\|", RegexOptions.IgnoreCase))
+        {
+            report.Errors.Add(new Diagnostic("EXTENSION_TABLE_MISSING", rel, ns.Name,
+                $"The 'Extension Members' section for namespace {ns.Name} is missing the '|Type|Ext|Methods|' table header."));
+            return;
+        }
+
+        // Every discovered extension method name must appear (backticked) in the section.
+        foreach (var group in ns.ExtensionMethods.GroupBy(m => m.MethodName, StringComparer.Ordinal))
+        {
+            var methodName = group.Key;
+            var pattern = "`" + Regex.Escape(methodName);
+            if (!Regex.IsMatch(section, pattern + @"[`(]"))
+            {
+                report.Errors.Add(new Diagnostic("EXTENSION_METHOD_MISSING", rel, ns.Name,
+                    $"Extension method `{methodName}` (extending {group.First().ExtendedType}) is not listed in the 'Extension Members' table for namespace {ns.Name}."));
+            }
+        }
+    }
+
+    private static bool HasFlyIn(string body)
+    {
+        foreach (var raw in body.Split('\n'))
+        {
+            var line = raw.Trim();
+            if (line.Length == 0)
+            {
+                continue;
+            }
+
+            if (line.StartsWith('#') || line.StartsWith('|') || line.StartsWith("[!INCLUDE", StringComparison.OrdinalIgnoreCase) ||
+                line.StartsWith("```", StringComparison.Ordinal) || line.StartsWith("---", StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            // Reject template placeholders like "contains types that ..." or bare ellipses / TODO.
+            if (line.Contains("...", StringComparison.Ordinal) || line.Contains("TODO", StringComparison.OrdinalIgnoreCase) ||
+                line.EndsWith("contains types that", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            if (line.Length >= 20)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private static bool HasAvailability(string body)
+    {
+        if (body.Contains("[!INCLUDE", StringComparison.OrdinalIgnoreCase))
+        {
+            return true;
+        }
+
+        return Regex.IsMatch(body, @"(?im)^\s*Availability\s*:");
+    }
+
+    // ----------------------------------------------------------------------
+    // Required example validation
+    // ----------------------------------------------------------------------
+
+    private static void ValidateRequiredExamples(string repoRoot, List<string> markdownFiles, ApiModel api,
+        Options options, HashSet<string>? changedFiles, Report report)
+    {
+        var sections = new List<OverwriteSection>();
+        foreach (var md in markdownFiles)
+        {
+            sections.AddRange(ExtractOverwriteSections(md));
+        }
+
+        foreach (var target in api.RequiredExampleTargets)
+        {
+            if (options.ChangedOnly && changedFiles is not null &&
+                !ShouldValidateRequiredExampleTarget(target, changedFiles))
+            {
+                continue;
+            }
+
+            var candidates = sections.Where(s => IsExampleCandidate(s, target)).ToList();
+            if (candidates.Any(s => HasExampleForTarget(s, target)))
+            {
+                report.Summary.RequiredExamples++;
+                continue;
+            }
+
+            var expectedUid = target.Kind == ApiTargetKind.Type
+                ? target.Uid
+                : target.DeclaringTypeUid ?? target.Uid;
+
+            var message = target.Kind == ApiTargetKind.Type
+                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to a per-type overwrite file for uid `{target.Uid}` (for Codebelt repositories, create `.docfx/api/{target.Uid}.md` and ensure build.overwrite includes it, for example with `api/**/*.md`)."
+                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}`, its declaring type uid `{expectedUid}`, or the namespace page `{target.Namespace}`.";
+
+            report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", null, target.Namespace, message));
+        }
+    }
+
+    private static bool ShouldValidateRequiredExampleTarget(ApiTargetInfo target, HashSet<string> changedFiles)
+    {
+        foreach (var changedFile in changedFiles)
+        {
+            if (IsChangedExampleCandidateFile(changedFile, target) || ChangedSourceTouchesTarget(changedFile, target))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private static bool IsChangedExampleCandidateFile(string path, ApiTargetInfo target)
+    {
+        if (string.Equals(Path.GetFileName(path), "docfx.json", StringComparison.OrdinalIgnoreCase))
+        {
+            return true;
+        }
+
+        if (!string.Equals(Path.GetExtension(path), ".md", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        var stem = Path.GetFileNameWithoutExtension(path);
+        if (string.Equals(stem, target.Namespace, StringComparison.Ordinal) ||
+            string.Equals(stem, target.Uid, StringComparison.Ordinal))
+        {
+            return true;
+        }
+
+        return target.Kind == ApiTargetKind.ExtensionMethod &&
+               string.Equals(stem, target.DeclaringTypeUid, StringComparison.Ordinal);
+    }
+
+    private static bool ChangedSourceTouchesTarget(string path, ApiTargetInfo target)
+    {
+        if (!string.Equals(Path.GetExtension(path), ".cs", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        string sourceText;
+        try
+        {
+            sourceText = File.ReadAllText(path);
+        }
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+        {
+            return false;
+        }
+
+        if (!Regex.IsMatch(sourceText, $@"(?m)^\s*namespace\s+{Regex.Escape(target.Namespace)}(?:\s*;|\s*\{{)"))
+        {
+            return false;
+        }
+
+        if (target.Kind == ApiTargetKind.Type)
+        {
+            return Regex.IsMatch(sourceText,
+                $@"(?m)\b(?:class|struct|interface|enum|delegate|record(?:\s+class|\s+struct)?)\s+{Regex.Escape(target.DisplayName)}\b");
+        }
+
+        return Regex.IsMatch(sourceText, $@"(?s)\b{Regex.Escape(target.DisplayName)}\s*\([^)]*\bthis\b");
+    }
+
+    private static bool IsExampleCandidate(OverwriteSection section, ApiTargetInfo target)
+    {
+        if (string.Equals(section.Uid, target.Uid, StringComparison.Ordinal))
+        {
+            return true;
+        }
+
+        if (target.Kind == ApiTargetKind.ExtensionMethod)
+        {
+            return string.Equals(section.Uid, target.DeclaringTypeUid, StringComparison.Ordinal) ||
+                   string.Equals(section.Uid, target.Namespace, StringComparison.Ordinal);
+        }
+
+        return false;
+    }
+
+    private static bool HasExampleForTarget(OverwriteSection section, ApiTargetInfo target)
+    {
+        if (!HasExampleSectionWithCSharpFence(section.Body))
+        {
+            return false;
+        }
+
+        if (target.Kind == ApiTargetKind.ExtensionMethod &&
+            !section.Body.Contains(target.DisplayName, StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static bool HasExampleSectionWithCSharpFence(string body)
+    {
+        var match = Regex.Match(body, @"(?im)^#{2,5}\s+Examples?\s*$");
+        if (!match.Success)
+        {
+            return false;
+        }
+
+        var section = body[match.Index..];
+        var nextHeading = Regex.Match(section[match.Length..], @"(?im)^#{1,5}\s+\S");
+        if (nextHeading.Success)
+        {
+            section = section[..(match.Length + nextHeading.Index)];
+        }
+
+        return Regex.IsMatch(section, @"(?im)^```\s*(csharp|cs)\s*$");
+    }
+
+    // ----------------------------------------------------------------------
+    // Sample validation
+    // ----------------------------------------------------------------------
+
+    private static void ValidateSamples(string repoRoot, List<string> markdownFiles, List<ProjectInfo> libraryProjects,
+        Options options, HashSet<string>? changedFiles, Report report)
+    {
+        var samples = new List<SampleFence>();
+        foreach (var md in markdownFiles)
+        {
+            if (options.ChangedOnly && changedFiles is not null && !changedFiles.Contains(Path.GetFullPath(md)))
+            {
+                continue;
+            }
+
+            samples.AddRange(ExtractFences(md));
+        }
+
+        if (samples.Count == 0)
+        {
+            return;
+        }
+
+        var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-samples-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(tempRoot);
+        try
+        {
+            int index = 0;
+            foreach (var sample in samples)
+            {
+                index++;
+                var skip = FindSkip(sample.Code);
+                if (skip.Found)
+                {
+                    if (string.IsNullOrWhiteSpace(skip.Reason))
+                    {
+                        report.Errors.Add(new Diagnostic("SAMPLE_SKIP_REASON_MISSING", Rel(repoRoot, sample.File), null,
+                            $"A C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) uses the skip-compile marker without a mandatory reason."));
+                    }
+                    else
+                    {
+                        report.Summary.SamplesSkipped++;
+                    }
+
+                    continue;
+                }
+
+                var (ok, diagnostics, exitCode) = CompileSample(tempRoot, index, sample, libraryProjects, options.Configuration);
+                if (ok)
+                {
+                    report.Summary.SamplesCompiled++;
+                }
+                else
+                {
+                    report.Errors.Add(new Diagnostic("SAMPLE_COMPILE_FAILED", Rel(repoRoot, sample.File), null,
+                        $"C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) failed to compile (exit {exitCode}).\n{Trim(diagnostics)}"));
+                }
+            }
+        }
+        finally
+        {
+            TryDeleteDirectory(tempRoot);
+        }
+    }
+
+    private static (bool Ok, string Diagnostics, int ExitCode) CompileSample(string tempRoot, int index, SampleFence sample,
+        List<ProjectInfo> libraryProjects, string configuration)
+    {
+        var dir = Path.Combine(tempRoot, "sample_" + index);
+        Directory.CreateDirectory(dir);
+        var file = Path.Combine(dir, "sample.cs");
+
+        var sb = new StringBuilder();
+        sb.Append("#:property TargetFramework=net10.0\n");
+        sb.Append("#:property PublishAot=false\n");
+        sb.Append("#:property Nullable=enable\n");
+        foreach (var proj in libraryProjects)
+        {
+            sb.Append("#:project ").Append(proj.Path).Append('\n');
+        }
+
+        sb.Append('\n');
+        sb.Append(sample.Code);
+        if (!sample.Code.EndsWith('\n'))
+        {
+            sb.Append('\n');
+        }
+
+        File.WriteAllText(file, sb.ToString(), new UTF8Encoding(false));
+
+        var result = RunProcess("dotnet", $"build \"{file}\" -c {configuration} --nologo", dir);
+        return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
+    }
+
+    private static List<SampleFence> ExtractFences(string mdFile)
+    {
+        var fences = new List<SampleFence>();
+        string[] lines;
+        try
+        {
+            lines = File.ReadAllLines(mdFile);
+        }
+        catch
+        {
+            return fences;
+        }
+
+        int fenceIndex = 0;
+        for (int i = 0; i < lines.Length; i++)
+        {
+            var trimmed = lines[i].TrimStart();
+            if (!trimmed.StartsWith("```", StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            var info = trimmed.TrimStart('`').Trim().ToLowerInvariant();
+            int start = i;
+            int j = i + 1;
+            var content = new StringBuilder();
+            while (j < lines.Length && !lines[j].TrimStart().StartsWith("```", StringComparison.Ordinal))
+            {
+                content.Append(lines[j]).Append('\n');
+                j++;
+            }
+
+            if (info is "csharp" or "cs")
+            {
+                fenceIndex++;
+                fences.Add(new SampleFence(mdFile, fenceIndex, start + 1, content.ToString()));
+            }
+
+            i = j; // continue after the closing fence
+        }
+
+        return fences;
+    }
+
+    private static List<OverwriteSection> ExtractOverwriteSections(string mdFile)
+    {
+        var sections = new List<OverwriteSection>();
+        string text;
+        try
+        {
+            text = File.ReadAllText(mdFile);
+        }
+        catch
+        {
+            return sections;
+        }
+
+        var normalized = text.Replace("\r\n", "\n").Replace("\r", "\n");
+        var matches = Regex.Matches(normalized, @"(?ms)^---\s*\n(?<yaml>.*?)^---\s*$");
+        for (var i = 0; i < matches.Count; i++)
+        {
+            var match = matches[i];
+            var yaml = match.Groups["yaml"].Value;
+            var uid = ReadYamlScalar(yaml, "uid");
+            if (string.IsNullOrWhiteSpace(uid))
+            {
+                continue;
+            }
+
+            var bodyStart = match.Index + match.Length;
+            if (bodyStart < normalized.Length && normalized[bodyStart] == '\n')
+            {
+                bodyStart++;
+            }
+
+            var bodyEnd = i + 1 < matches.Count ? matches[i + 1].Index : normalized.Length;
+            var body = bodyEnd > bodyStart ? normalized[bodyStart..bodyEnd] : string.Empty;
+            sections.Add(new OverwriteSection(mdFile, uid, body));
+        }
+
+        return sections;
+    }
+
+    private static (bool Found, string Reason) FindSkip(string code)
+    {
+        foreach (var line in code.Split('\n'))
+        {
+            var idx = line.IndexOf(SkipMarker, StringComparison.Ordinal);
+            if (idx < 0)
+            {
+                continue;
+            }
+
+            var after = line[(idx + SkipMarker.Length)..].Trim();
+            if (after.StartsWith('-'))
+            {
+                after = after[1..].Trim();
+            }
+
+            return (true, after);
+        }
+
+        return (false, string.Empty);
+    }
+
+    // ----------------------------------------------------------------------
+    // git changed-only
+    // ----------------------------------------------------------------------
+
+    private static HashSet<string>? GetChangedFiles(string repoRoot, Report report)
+    {
+        var result = RunProcess("git", "rev-parse --verify HEAD", repoRoot);
+        if (result.ExitCode != 0)
+        {
+            return null;
+        }
+
+        var diff = RunProcess("git", "diff --name-only --diff-filter=ACMRTUXB HEAD", repoRoot);
+        if (diff.ExitCode != 0)
+        {
+            return null;
+        }
+
+        var set = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var line in diff.StdOut.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+        {
+            set.Add(Path.GetFullPath(Path.Combine(repoRoot, line)));
+        }
+
+        return set;
+    }
+
+    // ----------------------------------------------------------------------
+    // YAML / markdown helpers
+    // ----------------------------------------------------------------------
+
+    private static (string FrontMatter, string Body) SplitFrontMatter(string text)
+    {
+        var normalized = text.Replace("\r\n", "\n").Replace("\r", "\n");
+        if (!normalized.StartsWith("---\n", StringComparison.Ordinal))
+        {
+            return (string.Empty, normalized);
+        }
+
+        var end = normalized.IndexOf("\n---", 3, StringComparison.Ordinal);
+        if (end < 0)
+        {
+            return (string.Empty, normalized);
+        }
+
+        var frontMatter = normalized[4..end];
+        var afterIdx = normalized.IndexOf('\n', end + 1);
+        var body = afterIdx >= 0 ? normalized[(afterIdx + 1)..] : string.Empty;
+        return (frontMatter, body);
+    }
+
+    private static string? ReadYamlScalar(string frontMatter, string key)
+    {
+        foreach (var raw in frontMatter.Split('\n'))
+        {
+            var line = raw.Trim();
+            if (line.StartsWith(key + ":", StringComparison.Ordinal))
+            {
+                var value = line[(key.Length + 1)..].Trim();
+                return value.Length == 0 ? null : value;
+            }
+        }
+
+        return null;
+    }
+
+    // ----------------------------------------------------------------------
+    // Process + output helpers
+    // ----------------------------------------------------------------------
+
+    private static ProcessResult RunProcess(string fileName, string arguments, string workingDirectory)
+    {
+        var psi = new ProcessStartInfo
+        {
+            FileName = fileName,
+            Arguments = arguments,
+            WorkingDirectory = workingDirectory,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            UseShellExecute = false,
+            CreateNoWindow = true
+        };
+
+        try
+        {
+            using var process = Process.Start(psi);
+            if (process is null)
+            {
+                return new ProcessResult(-1, string.Empty, $"Failed to start process '{fileName}'.");
+            }
+
+            var stdoutTask = Task.Run(() => process.StandardOutput.ReadToEnd());
+            var stderrTask = Task.Run(() => process.StandardError.ReadToEnd());
+            if (!process.WaitForExit(ProcessTimeout))
+            {
+                try
+                {
+                    process.Kill(entireProcessTree: true);
+                }
+                catch
+                {
+                    // ignore
+                }
+
+                process.WaitForExit(ProcessStreamDrainTimeout);
+                Task.WaitAll([stdoutTask, stderrTask], ProcessStreamDrainTimeout);
+                var stdout = stdoutTask.IsCompletedSuccessfully ? stdoutTask.Result : string.Empty;
+                var stderr = stderrTask.IsCompletedSuccessfully ? stderrTask.Result : string.Empty;
+                return new ProcessResult(-1, stdout, stderr + $"\nProcess '{fileName}' timed out after {ProcessTimeout.TotalMinutes} minutes.");
+            }
+
+            Task.WaitAll([stdoutTask, stderrTask]);
+            return new ProcessResult(process.ExitCode, stdoutTask.Result, stderrTask.Result);
+        }
+        catch (Exception ex)
+        {
+            return new ProcessResult(-1, string.Empty, $"Failed to run '{fileName} {arguments}': {ex.Message}");
+        }
+    }
+
+    private static void TryDeleteDirectory(string path)
+    {
+        try
+        {
+            if (Directory.Exists(path))
+            {
+                Directory.Delete(path, recursive: true);
+            }
+        }
+        catch
+        {
+            // best effort
+        }
+    }
+
+    private static string Rel(string root, string path)
+    {
+        try
+        {
+            return Path.GetRelativePath(root, path).Replace('\\', '/');
+        }
+        catch
+        {
+            return path;
+        }
+    }
+
+    private static string Trim(string text)
+    {
+        const int max = 4000;
+        text = text.Trim();
+        return text.Length <= max ? text : text[..max] + "\n... (truncated)";
+    }
+
+    private static int Emit(Options options, Report report, ExitCode code, string consoleMessage)
+    {
+        if (report.Status is null)
+        {
+            report.Status = code == ExitCode.Success ? "passed" : "failed";
+        }
+
+        report.Summary.Errors = report.Errors.Count;
+        report.Summary.Warnings = report.Warnings.Count;
+
+        if (options.Json)
+        {
+            Console.WriteLine(JsonSerializer.Serialize(report, JsonOptions));
+        }
+        else
+        {
+            Console.WriteLine($"{ScriptId}: {report.Status}: {consoleMessage}");
+            foreach (var error in report.Errors)
+            {
+                Console.WriteLine($"  ERROR  [{error.Code}] {Describe(error)}");
+            }
+
+            foreach (var warning in report.Warnings)
+            {
+                Console.WriteLine($"  WARN   [{warning.Code}] {Describe(warning)}");
+            }
+
+            Console.WriteLine(
+                $"  Summary: namespaces={report.Summary.PublicNamespaces}, pages={report.Summary.NamespacePagesValidated}, " +
+                $"requiredExampleTargets={report.Summary.RequiredExampleTargets}, requiredExamples={report.Summary.RequiredExamples}, " +
+                $"extMethods={report.Summary.ExtensionMethods}, samplesCompiled={report.Summary.SamplesCompiled}, " +
+                $"samplesSkipped={report.Summary.SamplesSkipped}, generatedMetadataRemoved={report.Summary.GeneratedMetadataFilesRemoved}, " +
+                $"generatedOutputDirectoriesRemoved={report.Summary.GeneratedOutputDirectoriesRemoved}, " +
+                $"docfxBuildsVerified={report.Summary.DocfxBuildsVerified}, errors={report.Summary.Errors}, warnings={report.Summary.Warnings}");
+        }
+
+        return (int)code;
+    }
+
+    private static string Describe(Diagnostic d)
+    {
+        var location = d.Namespace is not null ? $"({d.Namespace}) " : string.Empty;
+        var path = d.Path is not null ? $"{d.Path}: " : string.Empty;
+        return $"{path}{location}{d.Message}";
+    }
+
+    // ----------------------------------------------------------------------
+    // Argument parsing
+    // ----------------------------------------------------------------------
+
+    private static bool TryParse(string[] args, out Options options, out string error, out bool wantHelp)
+    {
+        options = new Options();
+        error = string.Empty;
+        wantHelp = false;
+
+        for (int i = 0; i < args.Length; i++)
+        {
+            var arg = args[i];
+            switch (arg)
+            {
+                case "--help":
+                case "-h":
+                    options.Help = true;
+                    wantHelp = true;
+                    return true;
+                case "--repo-root":
+                    if (!Next(args, ref i, out var rr)) { error = "--repo-root requires a path."; return false; }
+                    options.RepoRoot = rr;
+                    break;
+                case "--docfx":
+                    if (!Next(args, ref i, out var dx)) { error = "--docfx requires a path."; return false; }
+                    options.DocfxPath = dx;
+                    break;
+                case "--configuration":
+                    if (!Next(args, ref i, out var cfg)) { error = "--configuration requires a name."; return false; }
+                    options.Configuration = cfg;
+                    break;
+                case "--framework":
+                    if (!Next(args, ref i, out var fw)) { error = "--framework requires a TFM."; return false; }
+                    options.Framework = fw;
+                    break;
+                case "--validate-samples":
+                    options.ValidateSamples = true;
+                    break;
+                case "--no-validate-samples":
+                    options.ValidateSamples = false;
+                    break;
                 case "--changed-only":
                     options.ChangedOnly = true;
                     break;
@@ -2091,58 +2166,58 @@ private static bool TryParse(string[] args, out Options options, out string erro
                 case "--json":
                     options.Json = true;
                     break;
-                default:
-                    if (TrySplit(arg, "--repo-root", out var v1)) { options.RepoRoot = v1; break; }
-                    if (TrySplit(arg, "--docfx", out var v2)) { options.DocfxPath = v2; break; }
-                    if (TrySplit(arg, "--configuration", out var v3)) { options.Configuration = v3; break; }
-                    if (TrySplit(arg, "--framework", out var v4)) { options.Framework = v4; break; }
-                    error = $"Unknown argument: {arg}";
-                    return false;
-            }
-        }
-
-        return true;
-    }
-
-    private static bool Next(string[] args, ref int i, out string value)
-    {
-        if (i + 1 >= args.Length)
-        {
-            value = string.Empty;
-            return false;
-        }
-
-        value = args[++i];
-        return true;
-    }
-
-    private static bool TrySplit(string arg, string name, out string value)
-    {
-        var prefix = name + "=";
-        if (arg.StartsWith(prefix, StringComparison.Ordinal))
-        {
-            value = arg[prefix.Length..];
-            return true;
-        }
-
-        value = string.Empty;
-        return false;
-    }
-
-    private static void PrintUsage()
-    {
-        Console.WriteLine(
-            $"""
-            {ScriptId} - validate DocFX documentation for .NET public APIs.
-
-            Usage:
-              dotnet run --file docfx.cs -- [options]
-
-            Options:
-              --repo-root <path>       Repository root. Default: current directory.
-              --docfx <path>           Path to docfx.json. Default: .docfx/docfx.json under repo root.
-              --configuration <name>   Build configuration. Default: Release.
-              --framework <tfm>        Optional target framework to validate against.
+                default:
+                    if (TrySplit(arg, "--repo-root", out var v1)) { options.RepoRoot = v1; break; }
+                    if (TrySplit(arg, "--docfx", out var v2)) { options.DocfxPath = v2; break; }
+                    if (TrySplit(arg, "--configuration", out var v3)) { options.Configuration = v3; break; }
+                    if (TrySplit(arg, "--framework", out var v4)) { options.Framework = v4; break; }
+                    error = $"Unknown argument: {arg}";
+                    return false;
+            }
+        }
+
+        return true;
+    }
+
+    private static bool Next(string[] args, ref int i, out string value)
+    {
+        if (i + 1 >= args.Length)
+        {
+            value = string.Empty;
+            return false;
+        }
+
+        value = args[++i];
+        return true;
+    }
+
+    private static bool TrySplit(string arg, string name, out string value)
+    {
+        var prefix = name + "=";
+        if (arg.StartsWith(prefix, StringComparison.Ordinal))
+        {
+            value = arg[prefix.Length..];
+            return true;
+        }
+
+        value = string.Empty;
+        return false;
+    }
+
+    private static void PrintUsage()
+    {
+        Console.WriteLine(
+            $"""
+            {ScriptId} - validate DocFX documentation for .NET public APIs.
+
+            Usage:
+              dotnet run --file docfx.cs -- [options]
+
+            Options:
+              --repo-root <path>       Repository root. Default: current directory.
+              --docfx <path>           Path to docfx.json. Default: .docfx/docfx.json under repo root.
+              --configuration <name>   Build configuration. Default: Release.
+              --framework <tfm>        Optional target framework to validate against.
               --validate-samples       Compile C# samples. Default: enabled.
               --no-validate-samples    Skip C# sample compilation.
               --changed-only           Validate only files changed according to git.
@@ -2153,97 +2228,97 @@ dotnet run --file docfx.cs -- [options]
                                       Leave DocFX-generated metadata files untouched.
               --json                   Emit a machine-readable JSON summary.
               --help                   Print this usage.
-
-            Exit codes:
-              0  Validation passed.
-              1  Validation failed.
-              2  Invalid arguments.
-              3  Repository root does not exist.
-              4  DocFX configuration file not found.
-              5  Build failed.
-              6  Public API discovery failed.
-              7  Sample compilation failed.
-              8  Unexpected internal error.
-            """);
-    }
-
-    private enum ExitCode
-    {
-        Success = 0,
-        ValidationFailed = 1,
-        InvalidArguments = 2,
-        RepoRootMissing = 3,
-        DocfxConfigMissing = 4,
-        BuildFailed = 5,
-        PublicApiDiscoveryFailed = 6,
-        SampleCompilationFailed = 7,
-        InternalError = 8
-    }
-
-    private sealed class Options
-    {
-        public string? RepoRoot { get; set; }
-        public string? DocfxPath { get; set; }
-        public string Configuration { get; set; } = "Release";
-        public string? Framework { get; set; }
+
+            Exit codes:
+              0  Validation passed.
+              1  Validation failed.
+              2  Invalid arguments.
+              3  Repository root does not exist.
+              4  DocFX configuration file not found.
+              5  Build failed.
+              6  Public API discovery failed.
+              7  Sample compilation failed.
+              8  Unexpected internal error.
+            """);
+    }
+
+    private enum ExitCode
+    {
+        Success = 0,
+        ValidationFailed = 1,
+        InvalidArguments = 2,
+        RepoRootMissing = 3,
+        DocfxConfigMissing = 4,
+        BuildFailed = 5,
+        PublicApiDiscoveryFailed = 6,
+        SampleCompilationFailed = 7,
+        InternalError = 8
+    }
+
+    private sealed class Options
+    {
+        public string? RepoRoot { get; set; }
+        public string? DocfxPath { get; set; }
+        public string Configuration { get; set; } = "Release";
+        public string? Framework { get; set; }
         public bool ValidateSamples { get; set; } = true;
         public bool ChangedOnly { get; set; }
         public bool VerifyDocfxBuild { get; set; }
         public bool CleanGeneratedMetadata { get; set; } = true;
         public bool Json { get; set; }
         public bool Help { get; set; }
-    }
-
-    private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest);
-
-    private sealed record ExtensionMethodInfo(string MethodName, string ExtendedType, string DeclaringClass);
-
-    private sealed record ApiTargetInfo(string Uid, string Namespace, ApiTargetKind Kind, string DisplayName, string? DeclaringTypeUid = null);
-
-    private enum ApiTargetKind
-    {
-        Type,
-        ExtensionMethod
-    }
-
-    private sealed class NamespaceInfo(string name)
-    {
-        public string Name { get; } = name;
+    }
+
+    private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest);
+
+    private sealed record ExtensionMethodInfo(string MethodName, string ExtendedType, string DeclaringClass);
+
+    private sealed record ApiTargetInfo(string Uid, string Namespace, ApiTargetKind Kind, string DisplayName, string? DeclaringTypeUid = null);
+
+    private enum ApiTargetKind
+    {
+        Type,
+        ExtensionMethod
+    }
+
+    private sealed class NamespaceInfo(string name)
+    {
+        public string Name { get; } = name;
         public List<ApiTargetInfo> RequiredExampleTargets { get; } = new();
-        public List<ExtensionMethodInfo> ExtensionMethods { get; } = new();
-    }
-
+        public List<ExtensionMethodInfo> ExtensionMethods { get; } = new();
+    }
+
     private sealed record ApiModel(List<NamespaceInfo> Namespaces, List<ApiTargetInfo> RequiredExampleTargets);
-
-    private sealed record SampleFence(string File, int FenceIndex, int StartLine, string Code);
-
-    private sealed record OverwriteSection(string File, string Uid, string Body);
-
-    private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
-}
-
-internal sealed class Diagnostic
-{
-    public Diagnostic(string code, string? path, string? @namespace, string message)
-    {
-        Code = code;
-        Path = path;
-        Namespace = @namespace;
-        Message = message;
-    }
-
-    [JsonPropertyName("code")] public string Code { get; }
-    [JsonPropertyName("path")] public string? Path { get; }
-    [JsonPropertyName("namespace")] public string? Namespace { get; }
-    [JsonPropertyName("message")] public string Message { get; }
-}
-
-internal sealed class Summary
-{
-    public int PublicNamespaces { get; set; }
-    public int NamespacePagesValidated { get; set; }
+
+    private sealed record SampleFence(string File, int FenceIndex, int StartLine, string Code);
+
+    private sealed record OverwriteSection(string File, string Uid, string Body);
+
+    private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
+}
+
+internal sealed class Diagnostic
+{
+    public Diagnostic(string code, string? path, string? @namespace, string message)
+    {
+        Code = code;
+        Path = path;
+        Namespace = @namespace;
+        Message = message;
+    }
+
+    [JsonPropertyName("code")] public string Code { get; }
+    [JsonPropertyName("path")] public string? Path { get; }
+    [JsonPropertyName("namespace")] public string? Namespace { get; }
+    [JsonPropertyName("message")] public string Message { get; }
+}
+
+internal sealed class Summary
+{
+    public int PublicNamespaces { get; set; }
+    public int NamespacePagesValidated { get; set; }
     public int RequiredExampleTargets { get; set; }
-    public int RequiredExamples { get; set; }
+    public int RequiredExamples { get; set; }
     public int ExtensionMethods { get; set; }
     public int SamplesCompiled { get; set; }
     public int SamplesSkipped { get; set; }
@@ -2253,14 +2328,14 @@ internal sealed class Summary
     public int Errors { get; set; }
     public int Warnings { get; set; }
 }
-
-internal sealed class Report
-{
-    public string Script { get; set; } = string.Empty;
-    public string RepoRoot { get; set; } = string.Empty;
-    public string? DocfxPath { get; set; }
-    public string? Status { get; set; }
-    public Summary Summary { get; set; } = new();
-    public List<Diagnostic> Errors { get; set; } = new();
-    public List<Diagnostic> Warnings { get; set; } = new();
-}
+
+internal sealed class Report
+{
+    public string Script { get; set; } = string.Empty;
+    public string RepoRoot { get; set; } = string.Empty;
+    public string? DocfxPath { get; set; }
+    public string? Status { get; set; }
+    public Summary Summary { get; set; } = new();
+    public List<Diagnostic> Errors { get; set; } = new();
+    public List<Diagnostic> Warnings { get; set; } = new();
+}

From b3657898187433010a95fd7079aef5132ca26f1a Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 20:04:51 +0200
Subject: [PATCH 13/88] =?UTF-8?q?=F0=9F=92=AC=20update=20available=20skill?=
 =?UTF-8?q?s=20table=20for=20dotnet-docfx-digest?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reflect the restructured skill documentation and enhanced script capabilities in the README available skills table.
---
 README.md | 64 +++++++++++++++++++++++++++----------------------------
 1 file changed, 32 insertions(+), 32 deletions(-)

diff --git a/README.md b/README.md
index daa177c..94d15db 100644
--- a/README.md
+++ b/README.md
@@ -60,7 +60,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill git-repo-digest
 npx skills add https://github.com/codebeltnet/agentic --skill trunk-first-repo
 npx skills add https://github.com/codebeltnet/agentic --skill dotnet-strong-name-signing
 npx skills add https://github.com/codebeltnet/agentic --skill dotnet-new-app-slnx
-npx skills add https://github.com/codebeltnet/agentic --skill dotnet-new-lib-slnx
+npx skills add https://github.com/codebeltnet/agentic --skill dotnet-new-lib-slnx
 npx skills add https://github.com/codebeltnet/agentic --skill git-remote-release
 npx skills add https://github.com/codebeltnet/agentic --skill dotnet-change-impact
 npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-digest
@@ -89,15 +89,15 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [git-nuget-readme](skills/git-nuget-readme/SKILL.md) | Git-aware NuGet README companion for .NET repos that advertise a package from `src/`. Resolves the real packable project the README should sell, combines git history with actual package metadata, source capabilities, and relevant tests when feasible, preserves honest badge/docs/contributing sections, and writes a forthcoming, adoption-friendly `README.md` with repo-derived branding, clear value, install, framework-support, and quick-start guidance. |
 | [git-visual-squash-summary](skills/git-visual-squash-summary/SKILL.md) | Non-mutating grouped-summary companion to `git-visual-commits`. Turns the full current feature branch into a curated set of compact lowercase-start summary lines for PR or squash-and-merge contexts by default, comparing against the repository base branch rather than a same-named tracking remote, including commits from all authors unless explicitly narrowed, preserving technical identifiers, merging overlap, dropping low-signal noise, highlighting distinct meaningful efforts, and avoiding changelog-style wording, unsupported claims, yolo prompts, needless commit-range questions, or commit-selection UI for ordinary branch-level squash requests. |
 | [skill-creator-agnostic](skills/skill-creator-agnostic/SKILL.md) | Runner-agnostic overlay for Anthropic `skill-creator`. Adds repo and environment guardrails for skill authoring and benchmarking: temp-workspace isolation, `iteration-N/eval-name/{config}/run-N/` benchmark layout, valid `grading.json` summaries, generated `benchmark.json`, honest `MEASURED` vs `SIMULATED` labeling, and sync/README discipline for repo-managed skills. |
-| [markdown-illustrator](skills/markdown-illustrator/SKILL.md) | Reads a markdown file and answers directly in chat with one document-wide Visual Brief plus one compiled prompt. Infers a compact visual strategy by default, keeps follow-up questions near zero, and only branches when the user explicitly asks for added specificity. |
+| [markdown-illustrator](skills/markdown-illustrator/SKILL.md) | Reads a markdown file and answers directly in chat with one document-wide Visual Brief plus one compiled prompt. Infers a compact visual strategy by default, keeps follow-up questions near zero, and only branches when the user explicitly asks for added specificity. |
 | [git-repo-digest](skills/git-repo-digest/SKILL.md) | Turns any full repository URL into a deterministic digest workspace using the bundled .NET file-based runner `scripts/digest.cs`. Requires explicit `--repo-url`, resolves omitted output paths to `<active-workspace>/.bot/digests` and passes that as `--output-root`, maps multiple positional URLs the same way for slash commands, bare pasted URLs, and natural-language requests by treating the first URL as the digest repo and every later URL as repeated `--external-repo-url`, always writes into `{output-root}/{repo-id}/{yyyyMMdd-HHmmssZ}`, accepts repeated curated public consumer repos, derives `{repo-id}`, fixes `result/`, performs shallow git clones, packs local tracked files with the bundled C# packer using `git ls-files`, separates XML evidence into `source.xml`, `tests.xml`, `projects.xml`, editorial `readmes.xml`, and scenario-only `external-usage.xml`, writes package and conceptual overview prompts under `prompts/`, emits public API summaries, engineering signals, evidence indexes, ordered XML chunks, referenced-package evidence maps for aggregate examples, and manifest-backed frontmatter hints, treats previous digest prose as contamination during fresh generation, then guides the agent to fully read the current phase's required evidence before writing package digests and a concept-led `result/Index.md` with YAML frontmatter containing Product-derived overview title metadata, validated documentation URLs resolved from PackageProjectUrl, documentation-host-filtered exact `.nuget/<PackageName>/README.md` documentation links including emoji-prefixed Documentation headings and "More documentation..." blocks, DocFX `metadata[].dest` API paths, and source namespace page candidates from `src/<PackageName>/**/*.cs`, target frameworks, package/library counts, external links, package-family links, and context glyphs, and validates authored result examples with `--validate-results` as a deterministic API-shape, Codebelt.Extensions.Xunit shape, PascalCase `MethodName_Scenario_ExpectedBehavior` test-method naming, Basic usage quality, and optimized NuGet-backed executable test gate with bounded parallelism. |
 | [dotnet-new-lib-slnx](skills/dotnet-new-lib-slnx/SKILL.md) | Scaffold a new .NET NuGet library solution following codebeltnet engineering conventions. Dynamic defaults for TFM/repository metadata, latest-stable NuGet package resolution, tuning projects plus a tooling-based benchmark runner, TFM-aware test environments, strong-name signing, NuGet packaging, DocFX documentation, CI/CD pipeline, and code quality tooling. |
 | [dotnet-new-app-slnx](skills/dotnet-new-app-slnx/SKILL.md) | Scaffold a new .NET standalone application solution following codebeltnet engineering conventions. Supports Console, Web, and Worker host families with Startup or Minimal hosting patterns; Web expands into Empty Web, Web API, MVC, or Web App / Razor, plus functional tests and a simplified CI pipeline. |
 | [trunk-first-repo](skills/trunk-first-repo/SKILL.md) | Initialize a git repository following [scaled trunk-based development](https://trunkbaseddevelopment.com/#scaled-trunk-based-development). Seeds an empty `main` branch and creates a versioned feature branch (`v0.1.0/init`), enforcing a PR-first workflow where content only reaches main through peer-reviewed pull requests. |
-| [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
+| [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses a bundled DocFX overwrite reference, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -139,16 +139,16 @@ npx skills add https://github.com/codebeltnet/agentic --skill git-visual-squash-
 npx skills add https://github.com/codebeltnet/agentic --skill skill-creator-agnostic
 ```
 
-`markdown-illustrator`
-
-```bash
-npx skills add https://github.com/codebeltnet/agentic --skill markdown-illustrator
-```
-
-`git-repo-digest`
-
-```bash
-npx skills add https://github.com/codebeltnet/agentic --skill git-repo-digest
+`markdown-illustrator`
+
+```bash
+npx skills add https://github.com/codebeltnet/agentic --skill markdown-illustrator
+```
+
+`git-repo-digest`
+
+```bash
+npx skills add https://github.com/codebeltnet/agentic --skill git-repo-digest
 ```
 
 `dotnet-new-lib-slnx`
@@ -171,10 +171,10 @@ npx skills add https://github.com/codebeltnet/agentic --skill trunk-first-repo
 
 `dotnet-strong-name-signing`
 
-```bash
-npx skills add https://github.com/codebeltnet/agentic --skill dotnet-strong-name-signing
-```
-
+```bash
+npx skills add https://github.com/codebeltnet/agentic --skill dotnet-strong-name-signing
+```
+
 `git-remote-release`
 
 ```bash
@@ -492,24 +492,24 @@ Most repositories start with `git init` followed by committing everything direct
 - **Review from day one** — no "we'll add branch protection later" that never happens
 - **Clean, meaningful history** — main tells the story of reviewed, approved changes
 - **Version-aware branches** — `v0.0.1/spike-auth` vs `v1.0.0/release-prep` signals project maturity at a glance
-- **Zero-friction setup** — one skill invocation, not a 10-step checklist
-
-### Why git-remote-release?
-
-Writing release notes is tedious. Raw commit logs are too noisy, PR titles often lack context, and the best release notes explain what changed and why it matters — not just what was merged. That gap between "here are the commits" and "here is what this release means for you" is where **git-remote-release** fits.
-
+- **Zero-friction setup** — one skill invocation, not a 10-step checklist
+
+### Why git-remote-release?
+
+Writing release notes is tedious. Raw commit logs are too noisy, PR titles often lack context, and the best release notes explain what changed and why it matters — not just what was merged. That gap between "here are the commits" and "here is what this release means for you" is where **git-remote-release** fits.
+
 **git-remote-release** reads all commits and pull requests between two tags or branches in a remote GitHub repository and produces a polished, paste-ready release note.
-
-- **Remote-first workflow** that works entirely through GitHub's API, with no local clone required,
-- **Compare URL awareness** where a pasted GitHub compare URL is used to extract the owner, repository, and both tags,
+
+- **Remote-first workflow** that works entirely through GitHub's API, with no local clone required,
+- **Compare URL awareness** where a pasted GitHub compare URL is used to extract the owner, repository, and both tags,
 - **Pull request-preferred analysis** that uses rich PR metadata when available and gracefully falls back to raw commits,
 - **Default-branch-aware comparisons** that resolve the upstream base and collect only commits on the current branch,
 - **Effect-oriented summaries** that explain what users and maintainers can expect from the release, not just what code was merged,
-- **Thematic grouping** where related changes are discussed together instead of listed chronologically,
-- **GitHub alert blocks** that use `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION` alerts sparingly and only when the release data supports the attention level,
-- **Source preservation** where every release note includes a `Sources:` section with the original PR and commit references,
-- **Strict format** that always starts with `## What's Changed` and always ends with the full changelog compare link,
-- **No invented claims** so every statement in the summary is backed by the commits and pull requests collected,
+- **Thematic grouping** where related changes are discussed together instead of listed chronologically,
+- **GitHub alert blocks** that use `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION` alerts sparingly and only when the release data supports the attention level,
+- **Source preservation** where every release note includes a `Sources:` section with the original PR and commit references,
+- **Strict format** that always starts with `## What's Changed` and always ends with the full changelog compare link,
+- **No invented claims** so every statement in the summary is backed by the commits and pull requests collected,
 - **Read-only operation** that never mutates repository state.
 
 ### Why dotnet-change-impact?

From 82db32c2824484442876c73c1f050c2fc2dc58f0 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 22:40:59 +0200
Subject: [PATCH 14/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20enhance=20dotnet-doc?=
 =?UTF-8?q?fx-digest=20with=20repair-plans=20and=20namespace=20coverage=20?=
 =?UTF-8?q?checks?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add deterministic repair-plan generation for noisy audits, namespace coverage validation to audit related sibling namespace pages consistently, cleanup boundary rules to preserve authored Markdown, and example inventory tracking. Update workflow steps to integrate repair-plan reading and namespace auditing before editing. Add three new test cases for repair-plan usage, cleanup preservation, and namespace family consistency.
---
 skills/dotnet-docfx-digest/SKILL.md           | 88 +++++++++++++------
 skills/dotnet-docfx-digest/evals/evals.json   | 31 ++++++-
 .../dotnet-docfx-digest/references/scripts.md |  7 +-
 3 files changed, 98 insertions(+), 28 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 7254f82..1a49730 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -32,6 +32,12 @@ Before reporting completion, the agent must run the deterministic validator:
 dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --verify-docfx-build
 ```
 
+For repo-wide audits or any validation run that produces more than a small number of diagnostics, the agent must also ask the validator to write a deterministic repair plan and use that plan as the authoritative work queue:
+
+```bash
+dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --json --repair-plan <temp-path>/docfx-repair-plan.md
+```
+
 If either script cannot run, the agent must report the exact command, exit code, and failure output. Do not claim repository instructions or documentation were verified unless the scripts ran successfully.
 
 Read `references/scripts.md` when you need the exact CLI surface, exit codes, JSON diagnostics, or validator behavior for `agents.cs` and `docfx.cs`.
@@ -157,6 +163,8 @@ A "material change" includes:
 
 Every automatically documented public non-abstraction type and every public extension method must include at least one example showing how to use it. A namespace overview fly-in or `Extension Members` table is not enough.
 
+Do not treat an `Extension Members` table as documentation completion. A table answers "what exists"; an example answers "how a consumer uses it." For each public extension method discovered or listed in a namespace page, create or verify an example before moving to final verification. If several related namespace pages are updated together, build an example inventory that maps every public extension method and every public non-abstraction type to the exact overwrite file and UID where its example lives.
+
 Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create a separate per-type Markdown overwrite file by default. For Codebelt repositories, the default type example file is:
 
 ```text
@@ -400,6 +408,12 @@ When the validator reports `EXAMPLE_MISSING`, create or update DocFX overwrite c
 
 When a repository has namespace overview files but no per-type overwrite files, create the per-type files. Do not treat the absence of existing type files as a signal to skip examples. For Codebelt repositories, place new type files beside generated API metadata under `.docfx/api/` and update `build.overwrite` if it currently points only at `.docfx/api/namespaces/**/*.md`.
 
+## Namespace Coverage
+
+When one namespace page in a public API family needs repair, audit the sibling namespace pages before finishing. For example, if `Codebelt.Bootstrapper.md` is touched, also inspect related namespace pages such as `Codebelt.Bootstrapper.Console.md`, `Codebelt.Bootstrapper.Web.md`, and `Codebelt.Bootstrapper.Worker.md` when they exist. Apply the same correctness rules to every affected namespace page: accurate fly-in, availability, extension-member table, and required examples.
+
+Do not update only the first namespace file that exposes the problem. If only one namespace is intentionally changed, state why the other related namespace pages were inspected and left unchanged.
+
 ## XML Documentation Comments
 
 Public API should have useful XML documentation comments. Prefer concise source-level XML comments and richer examples/remarks in DocFX overwrite files when documentation becomes long.
@@ -449,6 +463,20 @@ Before editing an existing Markdown file:
 
 Documentation must stay current. If additive-only editing would leave conflicting or stale information, update the stale information. Accuracy is more important than blindly appending content. Never leave two conflicting descriptions of the same API behavior.
 
+## Cleanup Boundary
+
+Authored DocFX Markdown is documentation output, not disposable build output. This includes namespace overview pages, per-type overwrite files, conceptual pages, includes, and Markdown files created earlier in the same run. Do not delete `.md` or `.mdoc` files, `docfx.json`, `toc.yml`, includes, images, examples, or directories that contain authored documentation while cleaning generated artifacts unless the user explicitly asks for that deletion.
+
+Prefer `docfx.cs --verify-docfx-build` because it runs DocFX in a temp copy and removes that temp workspace itself. After verification, do not run broad manual cleanup commands such as deleting DocFX directories by name. If `git status` shows remaining files, classify each path first:
+
+- Generated metadata cleanup is limited to DocFX-generated `*.yml`, `.manifest`, and `*.manifest` files under configured metadata destinations.
+- Generated site cleanup is limited to the configured `build.dest` directory when it is clearly generated output and contains no authored Markdown, source, project, solution, or DocFX configuration files.
+- Authored documentation changes, especially `.docfx/**/*.md`, must be kept and reported as created or updated documentation.
+
+If a cleanup candidate is ambiguous, leave it in place and report the ambiguity instead of deleting it.
+
+If a cleanup command accidentally deletes authored documentation, stop and inspect `git status` and `git diff` before attempting recovery. Do not run broad `git restore`, `git checkout --`, or equivalent whole-directory restores to hide the mistake. Those commands can discard already checked-out documentation work and make the final files worse than before. Recover only the exact files that were incorrectly removed, preserve any edits made earlier in the run, and report the recovery steps honestly.
+
 ## Style Rules
 
 Use developer-friendly documentation style.
@@ -491,14 +519,16 @@ When the user names a changed API or namespace:
 9. Convert test usage into real-life documentation examples.
 10. Update XML documentation where needed.
 11. Update or create namespace overview pages.
-12. Update extension-member tables.
-13. Update or create overwrite files, including type-page example sections for public non-abstraction types and example sections for public extension methods.
-14. Preserve manual edits.
-15. Run `dotnet build`.
-16. Run `dotnet test`.
-17. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
-18. Confirm generated DocFX metadata and build output did not remain in the working tree.
-19. Report verification results.
+12. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
+13. Update extension-member tables.
+14. Update or create overwrite files, including type-page example sections for public non-abstraction types and example sections for public extension methods.
+15. Build an example inventory that maps each required public type and extension method to its example location.
+16. Preserve manual edits.
+17. Run `dotnet build`.
+18. Run `dotnet test`.
+19. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
+20. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
+21. Report verification results.
 
 When no specific API or namespace is named:
 
@@ -507,21 +537,24 @@ When no specific API or namespace is named:
 3. Locate `.docfx/docfx.json` or repository-specific DocFX config.
 4. Read `references/docfx-overwrite-files.md`.
 5. Run `dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --json` to collect deterministic missing-doc findings when the repository is buildable.
-6. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
-7. Determine every namespace containing public API and whether each namespace exposes public extension methods.
-8. Determine every public non-abstraction type and every public extension method that requires an example.
-9. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
-10. Add or repair `Extension Members` tables for namespaces with public extension methods.
-11. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
-12. Create separate type-page overwrite files for public non-abstraction types that have no example yet, using `.docfx/api/{TypeUid}.md` in Codebelt repositories unless the repo has a stronger existing convention.
-13. Ensure `build.overwrite` includes the per-type overwrite files you create; update a namespace-only overwrite glob to include API overwrite files when needed.
-14. Create example sections for public extension methods that have no example yet.
-15. Preserve manual edits and correct stale contradictions instead of replacing whole files.
-16. Run `dotnet build`.
-17. Run `dotnet test`.
-18. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
-19. Confirm generated DocFX metadata and build output did not remain in the working tree.
-20. Report verification results and any remaining findings.
+6. If the validator reports multiple diagnostics, rerun it with `--repair-plan <temp-path>/docfx-repair-plan.md`, read that plan, and treat it as the work queue.
+7. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
+8. Determine every namespace containing public API and whether each namespace exposes public extension methods.
+9. Determine every public non-abstraction type and every public extension method that requires an example.
+10. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
+11. Audit related namespace pages together so fixes are consistent across the public API family.
+12. Add or repair `Extension Members` tables for namespaces with public extension methods.
+13. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
+14. Create separate type-page overwrite files for public non-abstraction types that have no example yet, using `.docfx/api/{TypeUid}.md` in Codebelt repositories unless the repo has a stronger existing convention.
+15. Ensure `build.overwrite` includes the per-type overwrite files you create; update a namespace-only overwrite glob to include API overwrite files when needed.
+16. Create example sections for public extension methods that have no example yet.
+17. Build an example inventory that maps each required public type and extension method to its example location.
+18. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+19. Run `dotnet build`.
+20. Run `dotnet test`.
+21. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
+22. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
+23. Report verification results and any remaining findings.
 
 ## Namespace Page Template
 
@@ -590,12 +623,15 @@ Before completing documentation work, verify:
 
 - [ ] `agents.cs` has run successfully.
 - [ ] `AGENTS.md` contains the managed DocFX documentation maintenance block.
+- [ ] For multi-diagnostic audits, `docfx.cs --repair-plan` was written, read, and used as the authoritative work queue.
 - [ ] Only public API is documented.
 - [ ] Every namespace with public API has a namespace overview page.
+- [ ] Related namespace pages in the same public API family were inspected and updated consistently, or intentionally left unchanged with a reason.
 - [ ] Namespaces with public extension methods have an `Extension Members` section.
 - [ ] Extension methods are documented by extended type, not extension class.
 - [ ] Public non-abstraction types have at least one type-page example.
 - [ ] Public extension methods have at least one example, not only a table entry.
+- [ ] An example inventory maps every required public type and extension method to its example file and UID.
 - [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`.
 - [ ] Abstractions without examples have a clear reason.
 - [ ] Examples are realistic and copy/paste-ready.
@@ -609,7 +645,8 @@ Before completing documentation work, verify:
 - [ ] `dotnet build` has been run or the failure is reported.
 - [ ] `dotnet test` has been run or the failure is reported.
 - [ ] `docfx.cs --verify-docfx-build` has run successfully, including the temp-workspace DocFX build, or the failure is reported.
-- [ ] Generated DocFX metadata files and build output directories did not remain in the working tree after verification.
+- [ ] Generated DocFX metadata files and build output directories did not remain in the working tree after verification, and authored Markdown or documentation assets were not deleted as cleanup.
+- [ ] No broad restore or checkout command discarded authored documentation changes.
 
 ## Completion Response
 
@@ -618,8 +655,9 @@ When reporting completion, include:
 - Public APIs documented,
 - Namespace pages added or updated,
 - Extension-member tables added or updated,
-- Examples added and their source test/sample when applicable,
+- Examples added, their source test/sample when applicable, and the example inventory by public type or extension method,
 - Availability handling,
+- Related namespace pages inspected and whether each was updated or left unchanged,
 - `AGENTS.md` created, updated, already compliant, or failed,
 - Verification commands run,
 - Any verification failures or skipped checks.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 2438d42..ff4cdef 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -63,12 +63,13 @@
     {
       "id": 6,
       "prompt": "Use dotnet-docfx-digest on this repository.",
-      "expected_output": "Agent treats the request as a repo-wide DocFX documentation audit instead of asking what to document first. It runs scripts/agents.cs, inspects AGENTS.md, docfx.json, source projects, public API, tests, samples, overwrite files, namespace pages, and availability includes, runs scripts/docfx.cs to collect deterministic findings and with --verify-docfx-build before completion, repairs missing complementary DocFX documentation that can be derived from source evidence, reads the DocFX overwrite reference when creating or repairing overwrite files, and asks for clarification only if discovery exposes a correctness-affecting choice.",
+      "expected_output": "Agent treats the request as a repo-wide DocFX documentation audit instead of asking what to document first. It runs scripts/agents.cs, inspects AGENTS.md, docfx.json, source projects, public API, tests, samples, overwrite files, namespace pages, and availability includes, runs scripts/docfx.cs to collect deterministic findings and writes a deterministic --repair-plan for noisy diagnostics, uses that repair plan as the work queue, runs with --verify-docfx-build before completion, repairs missing complementary DocFX documentation that can be derived from source evidence, reads the DocFX overwrite reference when creating or repairing overwrite files, and asks for clarification only if discovery exposes a correctness-affecting choice.",
       "expectations": [
         "Does not start by asking the user which API or namespace to document",
         "Runs scripts/agents.cs to ensure the repository AGENTS.md contains the managed DocFX maintenance block",
         "Inspects docfx.json and existing DocFX overwrite, namespace, include, source, test, and sample evidence before editing",
         "Runs scripts/docfx.cs, preferably with --json when collecting repo-wide findings, and uses --verify-docfx-build before completion so generated output stays outside the working tree",
+        "For multi-diagnostic output, writes and reads a deterministic --repair-plan and uses it as the work queue before editing",
         "Creates or updates missing namespace overview pages, Extension Members tables, examples, and availability notes that can be derived from evidence",
         "Reads references/docfx-overwrite-files.md before creating or repairing DocFX overwrite files",
         "Asks a concise clarifying question only after inspection finds a correctness-affecting unresolved choice"
@@ -100,6 +101,34 @@
         "Scopes the example validation to changed APIs or related DocFX inputs rather than re-reporting the whole repository by default",
         "Uses --verify-docfx-build before claiming final verification"
       ]
+    },
+    {
+      "id": 9,
+      "prompt": "Use dotnet-docfx-digest on a Codebelt.Bootstrapper-style repository. During the run you create `.docfx/api/Codebelt.Bootstrapper.ProgramRoot.md` and `.docfx/api/namespaces/Codebelt.Bootstrapper.md`, then validation leaves generated DocFX metadata files beside those authored markdown files. Clean up generated artifacts before completion.",
+      "expected_output": "Agent preserves all authored Markdown overwrite and namespace files, including files created earlier in the same run, and cleans only known generated DocFX metadata or safe generated site output. It does not delete `.docfx/api/**/*.md`, does not recursively delete DocFX directories that contain Markdown or source/configuration files, uses `docfx.cs --verify-docfx-build` for temp-workspace verification, classifies any remaining `git status` paths before deletion, and leaves ambiguous cleanup candidates in place with a note instead of deleting them.",
+      "expectations": [
+        "Treats newly created `.docfx/**/*.md` files as documentation deliverables rather than cleanup targets",
+        "Does not run broad manual cleanup commands that delete DocFX directories by name",
+        "Limits generated metadata cleanup to DocFX-generated `*.yml`, `.manifest`, and `*.manifest` files under configured metadata destinations",
+        "Does not recursively delete a configured build output directory when it contains Markdown, source, project, solution, or DocFX configuration files",
+        "Uses `docfx.cs --verify-docfx-build` so the DocFX build runs in a temp copy and generated site output stays out of the working tree",
+        "Reports any ambiguous leftover paths instead of deleting authored documentation"
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "Use dotnet-docfx-digest on the Codebelt.Bootstrapper docs after a bad previous run left `Codebelt.Bootstrapper.Console.md`, `Codebelt.Bootstrapper.md`, `Codebelt.Bootstrapper.Web.md`, and `Codebelt.Bootstrapper.Worker.md` checked out. The last agent restored or undid some of those files, only edited `Codebelt.Bootstrapper.md`, and added no required examples.",
+      "expected_output": "Agent does not run broad restore or checkout commands. It captures git status and diffs first, runs scripts/docfx.cs with --json and --repair-plan, reads the repair plan, audits all four Bootstrapper namespace pages as a related family, fixes Extension Members sections consistently, creates or repairs required examples for public non-abstraction types and public extension methods instead of stopping at tables, builds an example inventory mapping each required API to an example file and UID, preserves already checked-out Markdown edits, runs build/test/DocFX verification, and reports any remaining deterministic diagnostics.",
+      "expectations": [
+        "Captures git status and diffs before modifying or recovering checked-out Markdown files",
+        "Does not use broad git restore, checkout, reset, or whole-directory recovery commands",
+        "Runs scripts/docfx.cs with --json and --repair-plan, then reads the generated repair plan before editing",
+        "Audits `Codebelt.Bootstrapper.Console.md`, `Codebelt.Bootstrapper.md`, `Codebelt.Bootstrapper.Web.md`, and `Codebelt.Bootstrapper.Worker.md` together instead of updating only one file",
+        "Uses `Extension Members` headings where extension methods are present",
+        "Adds required examples for public non-abstraction types and public extension methods, not only namespace fly-ins or extension tables",
+        "Builds and reports an example inventory mapping each required API to its example file and UID",
+        "Preserves authored Markdown and reports any remaining validation diagnostics instead of claiming completion"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 0971158..9541cb7 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -50,14 +50,17 @@ dotnet run --file docfx.cs -- --repo-root . --json
 dotnet run --file docfx.cs -- --repo-root . --no-validate-samples
 dotnet run --file docfx.cs -- --repo-root . --changed-only
 dotnet run --file docfx.cs -- --repo-root . --verify-docfx-build
+dotnet run --file docfx.cs -- --repo-root . --json --repair-plan /tmp/docfx-repair-plan.md
 dotnet run --file docfx.cs -- --repo-root . --configuration Debug --framework net10.0
 ```
 
-Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--framework`, `--validate-samples` / `--no-validate-samples` (default on), `--changed-only`, `--verify-docfx-build`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
+Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--framework`, `--validate-samples` / `--no-validate-samples` (default on), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory when it is safely inside the repository.
+`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown and forbid broad restore/checkout recovery. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
+
+`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files and namespace pages are documentation output, not cleanup targets.
 
 Process execution drains stdout and stderr concurrently so verbose `dotnet build` or DocFX runs cannot deadlock on a full pipe while the validator waits for exit.
 

From 179930b07b22baf5637e62f16ab22301c7ca7935 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 22:41:09 +0200
Subject: [PATCH 15/88] =?UTF-8?q?=E2=9C=A8=20add=20repair-plan=20feature?=
 =?UTF-8?q?=20to=20docfx=20script?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implement --repair-plan argument to generate deterministic Markdown work queues from validation diagnostics. Groups repository guidance failures, namespace repairs, extension-table fixes, required-example inventory, sample failures, and other errors with completion gates that prevent broad restore/checkout commands and preserve authored Markdown. Limits cleanup to known generated metadata files and safe output directories. Uses temp workspace for DocFX verification to avoid git status pollution.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 143 ++++++++++++++++++++
 1 file changed, 143 insertions(+)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 7e55292..d267f5c 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -377,6 +377,13 @@ private static void CleanupGeneratedMetadata(string repoRoot, string docfxPath,
                 continue;
             }
 
+            if (ContainsAuthoredOrSourceFiles(buildOutputPath))
+            {
+                report.Warnings.Add(new Diagnostic("GENERATED_OUTPUT_CLEANUP_SKIPPED", buildOutputPath, null,
+                    "Generated output cleanup was skipped because the resolved DocFX build destination contains Markdown, source, project, solution, or DocFX configuration files. These may be authored documentation or repository source files."));
+                continue;
+            }
+
             try
             {
                 Directory.Delete(buildOutputPath, recursive: true);
@@ -519,6 +526,12 @@ private static bool IsSafeGeneratedOutputDirectory(string path, string repoRoot)
                    StringComparison.OrdinalIgnoreCase);
     }
 
+    private static bool ContainsAuthoredOrSourceFiles(string path)
+    {
+        string[] patterns = ["*.md", "*.mdoc", "docfx.json", "toc.yml", "toc.md", "*.cs", "*.csproj", "*.sln", "*.slnx"];
+        return patterns.Any(pattern => EnumerateFiles(path, pattern).Any());
+    }
+
     private static List<string> DiscoverMarkdown(string docfxWorkspace)
     {
         var list = new List<string>();
@@ -2070,6 +2083,8 @@ private static int Emit(Options options, Report report, ExitCode code, string co
             report.Status = code == ExitCode.Success ? "passed" : "failed";
         }
 
+        WriteRepairPlanIfRequested(options, report);
+
         report.Summary.Errors = report.Errors.Count;
         report.Summary.Warnings = report.Warnings.Count;
 
@@ -2109,6 +2124,126 @@ private static string Describe(Diagnostic d)
         return $"{path}{location}{d.Message}";
     }
 
+    private static void WriteRepairPlanIfRequested(Options options, Report report)
+    {
+        if (string.IsNullOrWhiteSpace(options.RepairPlanPath))
+        {
+            return;
+        }
+
+        try
+        {
+            var basePath = Directory.Exists(report.RepoRoot) ? report.RepoRoot : Directory.GetCurrentDirectory();
+            var planPath = Path.GetFullPath(options.RepairPlanPath, basePath);
+            var directory = Path.GetDirectoryName(planPath);
+            if (!string.IsNullOrWhiteSpace(directory))
+            {
+                Directory.CreateDirectory(directory);
+            }
+
+            File.WriteAllText(planPath, BuildRepairPlan(report), new UTF8Encoding(false));
+            report.RepairPlanPath = planPath;
+        }
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException or NotSupportedException)
+        {
+            report.Warnings.Add(new Diagnostic("REPAIR_PLAN_WRITE_FAILED", options.RepairPlanPath, null,
+                $"Unable to write repair plan: {ex.Message}"));
+        }
+    }
+
+    private static string BuildRepairPlan(Report report)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine("# DocFX Repair Plan");
+        sb.AppendLine();
+        sb.AppendLine($"Repository: `{report.RepoRoot}`");
+        if (!string.IsNullOrWhiteSpace(report.DocfxPath))
+        {
+            sb.AppendLine($"DocFX config: `{report.DocfxPath}`");
+        }
+
+        sb.AppendLine($"Status: `{report.Status ?? "unknown"}`");
+        sb.AppendLine();
+        sb.AppendLine("## Summary");
+        sb.AppendLine();
+        sb.AppendLine($"- Public namespaces: {report.Summary.PublicNamespaces}");
+        sb.AppendLine($"- Namespace pages validated: {report.Summary.NamespacePagesValidated}");
+        sb.AppendLine($"- Required example targets: {report.Summary.RequiredExampleTargets}");
+        sb.AppendLine($"- Required examples found: {report.Summary.RequiredExamples}");
+        sb.AppendLine($"- Extension methods: {report.Summary.ExtensionMethods}");
+        sb.AppendLine($"- Samples compiled: {report.Summary.SamplesCompiled}");
+        sb.AppendLine($"- DocFX builds verified: {report.Summary.DocfxBuildsVerified}");
+        sb.AppendLine($"- Errors: {report.Errors.Count}");
+        sb.AppendLine($"- Warnings: {report.Warnings.Count}");
+        sb.AppendLine();
+        sb.AppendLine("## Execution Gates");
+        sb.AppendLine();
+        sb.AppendLine("- Do not use broad restore or checkout commands to recover documentation files.");
+        sb.AppendLine("- Preserve authored `.md` and `.mdoc` files, including files created earlier in the run.");
+        sb.AppendLine("- Treat `Extension Members` tables as incomplete until required examples exist.");
+        sb.AppendLine("- Repair related namespace pages together; do not update only the first page that exposes a shared issue.");
+        sb.AppendLine("- Rerun validation with `--verify-docfx-build` before claiming completion.");
+        sb.AppendLine();
+
+        AppendDiagnostics(sb, "Repository Guidance", report.Errors.Where(e => e.Code is "AGENTS_BLOCK_MISSING"));
+        AppendDiagnostics(sb, "Namespace And Extension Table Repairs", report.Errors.Where(e =>
+            e.Code.StartsWith("NAMESPACE_", StringComparison.Ordinal) ||
+            e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal)));
+        AppendDiagnostics(sb, "Required Example Inventory", report.Errors.Where(e => e.Code is "EXAMPLE_MISSING"));
+        AppendDiagnostics(sb, "Sample Compilation Repairs", report.Errors.Where(e =>
+            e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_SKIP_REASON_MISSING"));
+        AppendDiagnostics(sb, "Other Errors", report.Errors.Where(e =>
+            e.Code is not "AGENTS_BLOCK_MISSING" &&
+            !e.Code.StartsWith("NAMESPACE_", StringComparison.Ordinal) &&
+            !e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal) &&
+            e.Code is not "EXAMPLE_MISSING" &&
+            e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_SKIP_REASON_MISSING"));
+        AppendDiagnostics(sb, "Warnings", report.Warnings);
+
+        sb.AppendLine("## Completion Checklist");
+        sb.AppendLine();
+        sb.AppendLine("- [ ] `agents.cs` has run successfully when `AGENTS_BLOCK_MISSING` appears.");
+        sb.AppendLine("- [ ] Every namespace diagnostic above has been resolved or intentionally excluded with evidence.");
+        sb.AppendLine("- [ ] Every `EXAMPLE_MISSING` diagnostic above maps to a concrete example location.");
+        sb.AppendLine("- [ ] Changed C# examples compile.");
+        sb.AppendLine("- [ ] Authored Markdown files still exist after generated-artifact cleanup.");
+        sb.AppendLine("- [ ] Final validation command and exit code are reported.");
+
+        return sb.ToString();
+    }
+
+    private static void AppendDiagnostics(StringBuilder sb, string title, IEnumerable<Diagnostic> diagnostics)
+    {
+        var items = diagnostics
+            .OrderBy(d => d.Namespace ?? string.Empty, StringComparer.Ordinal)
+            .ThenBy(d => d.Path ?? string.Empty, StringComparer.Ordinal)
+            .ThenBy(d => d.Code, StringComparer.Ordinal)
+            .ThenBy(d => d.Message, StringComparer.Ordinal)
+            .ToList();
+
+        sb.AppendLine($"## {title}");
+        sb.AppendLine();
+        if (items.Count == 0)
+        {
+            sb.AppendLine("None.");
+            sb.AppendLine();
+            return;
+        }
+
+        foreach (var group in items.GroupBy(d => d.Namespace ?? "(repository)", StringComparer.Ordinal))
+        {
+            sb.AppendLine($"### {group.Key}");
+            sb.AppendLine();
+            foreach (var diagnostic in group)
+            {
+                var path = string.IsNullOrWhiteSpace(diagnostic.Path) ? string.Empty : $" `{diagnostic.Path}`";
+                sb.AppendLine($"- `{diagnostic.Code}`{path}: {diagnostic.Message}");
+            }
+
+            sb.AppendLine();
+        }
+    }
+
     // ----------------------------------------------------------------------
     // Argument parsing
     // ----------------------------------------------------------------------
@@ -2157,6 +2292,10 @@ private static bool TryParse(string[] args, out Options options, out string erro
                 case "--verify-docfx-build":
                     options.VerifyDocfxBuild = true;
                     break;
+                case "--repair-plan":
+                    if (!Next(args, ref i, out var rp)) { error = "--repair-plan requires a path."; return false; }
+                    options.RepairPlanPath = rp;
+                    break;
                 case "--clean-generated-metadata":
                     options.CleanGeneratedMetadata = true;
                     break;
@@ -2171,6 +2310,7 @@ private static bool TryParse(string[] args, out Options options, out string erro
                     if (TrySplit(arg, "--docfx", out var v2)) { options.DocfxPath = v2; break; }
                     if (TrySplit(arg, "--configuration", out var v3)) { options.Configuration = v3; break; }
                     if (TrySplit(arg, "--framework", out var v4)) { options.Framework = v4; break; }
+                    if (TrySplit(arg, "--repair-plan", out var v5)) { options.RepairPlanPath = v5; break; }
                     error = $"Unknown argument: {arg}";
                     return false;
             }
@@ -2222,6 +2362,7 @@ dotnet run --file docfx.cs -- [options]
               --no-validate-samples    Skip C# sample compilation.
               --changed-only           Validate only files changed according to git.
               --verify-docfx-build     Run DocFX against a temp copy of the repository so generated output stays outside the working tree.
+              --repair-plan <path>     Write a deterministic Markdown repair plan from validation diagnostics.
               --clean-generated-metadata
                                       Remove DocFX-generated *.yml and manifest files under metadata.dest. Default: enabled.
               --no-clean-generated-metadata
@@ -2261,6 +2402,7 @@ private sealed class Options
         public string? DocfxPath { get; set; }
         public string Configuration { get; set; } = "Release";
         public string? Framework { get; set; }
+        public string? RepairPlanPath { get; set; }
         public bool ValidateSamples { get; set; } = true;
         public bool ChangedOnly { get; set; }
         public bool VerifyDocfxBuild { get; set; }
@@ -2334,6 +2476,7 @@ internal sealed class Report
     public string Script { get; set; } = string.Empty;
     public string RepoRoot { get; set; } = string.Empty;
     public string? DocfxPath { get; set; }
+    public string? RepairPlanPath { get; set; }
     public string? Status { get; set; }
     public Summary Summary { get; set; } = new();
     public List<Diagnostic> Errors { get; set; } = new();

From fbeff246ee0892de0b01f8ebfe681c9f8a737a02 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 22:41:19 +0200
Subject: [PATCH 16/88] =?UTF-8?q?=F0=9F=92=AC=20update=20dotnet-docfx-dige?=
 =?UTF-8?q?st=20skill=20description?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update README.md skill table description to document new repair-plan capability for converting noisy validation output into grouped work queues, deterministic cleanup boundary rules that preserve authored Markdown, and cleanup gates that prevent accidental documentation loss. Highlight temp-workspace verification with --verify-docfx-build to keep git status clean.
---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 94d15db..c8672be 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -538,11 +538,13 @@ API documentation rots the moment code changes. A new public type ships without
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
 - **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, resolving NuGet package dependencies, deps files, and installed .NET framework reference packs instead of guessing from text,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
+- **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, required-example inventory, sample failures, cleanup gates, and completion checks so agents do not update one namespace and forget the rest,
 - **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, namespace-only overwrite globs must be widened to include those files, and namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
 - **Preserves manual edits** — additive by default, correcting stale or contradictory statements rather than overwriting hand-written documentation,
+- **Cleanup keeps authored docs** — `.docfx/**/*.md` overwrite files, namespace pages, includes, and config are documentation outputs, not disposable build artifacts; generated cleanup is limited to known metadata files and safe site-output directories that contain no authored documentation or source files,
 - **CI-friendly** — deterministic exit codes plus `--json` reports let pipelines fail on actual documentation drift instead of trusting an agent's claim that it checked.
 
 ## Repository structure

From 9ed172054d7bb74e8a7ac0d7369e94381892a064 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 23:04:29 +0200
Subject: [PATCH 17/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20strengthen=20safety?=
 =?UTF-8?q?=20gates=20and=20completion=20checks=20for=20documentation=20ed?=
 =?UTF-8?q?its?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add explicit 'Safety Gates' section that captures git status before editing, protects uncommitted documentation changes, and forbids broad restore/recovery commands. Integrate safety gates into both named-API and repo-wide audit workflows as first step. Add git diff verification before final completion. Expand execution gates in repair plan to require cleanup candidates be listed before deletion, preserve existing documentation changes, audit related namespace pages together, and verify diffs are intentional. Update test expectations to validate all safety checks.
---
 skills/dotnet-docfx-digest/SKILL.md           | 106 +++++++++++-------
 skills/dotnet-docfx-digest/evals/evals.json   |   3 +
 .../dotnet-docfx-digest/references/scripts.md |   2 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs   |   4 +
 4 files changed, 71 insertions(+), 44 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 1a49730..fe4083d 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -50,6 +50,19 @@ The documentation must reflect the actual code, not intended code. Do not invent
 
 Manual documentation is authoritative context. Preserve existing manual edits unless they are factually incorrect. Prefer additive changes. When information is stale, update the stale portion while retaining nearby human-written explanations, tone, and structure.
 
+## Safety Gates
+
+Before making documentation changes, capture the current repository state:
+
+1. Run `git status --short` and identify modified, staged, and untracked documentation files.
+2. If source documentation files already have uncommitted changes, treat them as user work. Do not overwrite, restore, reformat, or regenerate them wholesale.
+3. Read each affected Markdown file before editing it.
+4. For cleanup candidates, list the exact files or directories first and classify them as generated metadata, generated site output, build artifacts, or authored documentation.
+
+Before any git operation that can discard or overwrite content, stop and report the exact files that would be affected. Do not run broad `git restore`, `git checkout --`, `git reset`, or whole-directory recovery commands on documentation source directories. If recovery is needed, recover only the specific generated or accidentally removed file after inspecting `git status` and `git diff`.
+
+After modifications, run `git diff` for the touched documentation paths and verify the diff contains only intended documentation changes. If the work cannot be completed without partial, inconsistent, or unverifiable documentation, stop and report the limitation instead of proceeding partially.
+
 ## Scope
 
 Apply this skill to:
@@ -471,7 +484,8 @@ Prefer `docfx.cs --verify-docfx-build` because it runs DocFX in a temp copy and
 
 - Generated metadata cleanup is limited to DocFX-generated `*.yml`, `.manifest`, and `*.manifest` files under configured metadata destinations.
 - Generated site cleanup is limited to the configured `build.dest` directory when it is clearly generated output and contains no authored Markdown, source, project, solution, or DocFX configuration files.
-- Authored documentation changes, especially `.docfx/**/*.md`, must be kept and reported as created or updated documentation.
+- Build artifacts such as `bin/` and `obj/` directories may be cleanup candidates only after confirming they are build output and not documentation source.
+- Authored documentation changes, especially Markdown files included by `build.content` or `build.overwrite`, must be kept and reported as created or updated documentation.
 
 If a cleanup candidate is ambiguous, leave it in place and report the ambiguity instead of deleting it.
 
@@ -509,52 +523,56 @@ Avoid:
 When the user names a changed API or namespace:
 
 1. Run `agents.cs`.
-2. Inspect the changed public API.
-3. Determine affected namespaces.
-4. Determine whether public extension methods are involved.
-5. Locate `.docfx/docfx.json` or repository-specific DocFX config.
-6. Locate existing overwrite files and namespace pages.
-7. Locate availability include files.
-8. Locate relevant tests that demonstrate the API.
-9. Convert test usage into real-life documentation examples.
-10. Update XML documentation where needed.
-11. Update or create namespace overview pages.
-12. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
-13. Update extension-member tables.
-14. Update or create overwrite files, including type-page example sections for public non-abstraction types and example sections for public extension methods.
-15. Build an example inventory that maps each required public type and extension method to its example location.
-16. Preserve manual edits.
-17. Run `dotnet build`.
-18. Run `dotnet test`.
-19. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
-20. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
-21. Report verification results.
-
-When no specific API or namespace is named:
-
-1. Run `agents.cs`.
-2. Read repository guidance, especially root `AGENTS.md`.
-3. Locate `.docfx/docfx.json` or repository-specific DocFX config.
-4. Read `references/docfx-overwrite-files.md`.
-5. Run `dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --json` to collect deterministic missing-doc findings when the repository is buildable.
-6. If the validator reports multiple diagnostics, rerun it with `--repair-plan <temp-path>/docfx-repair-plan.md`, read that plan, and treat it as the work queue.
-7. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
-8. Determine every namespace containing public API and whether each namespace exposes public extension methods.
-9. Determine every public non-abstraction type and every public extension method that requires an example.
-10. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
-11. Audit related namespace pages together so fixes are consistent across the public API family.
-12. Add or repair `Extension Members` tables for namespaces with public extension methods.
-13. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
-14. Create separate type-page overwrite files for public non-abstraction types that have no example yet, using `.docfx/api/{TypeUid}.md` in Codebelt repositories unless the repo has a stronger existing convention.
-15. Ensure `build.overwrite` includes the per-type overwrite files you create; update a namespace-only overwrite glob to include API overwrite files when needed.
-16. Create example sections for public extension methods that have no example yet.
-17. Build an example inventory that maps each required public type and extension method to its example location.
-18. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+2. Run the safety gates: capture `git status`, identify existing documentation changes, and avoid broad restore/recovery commands.
+3. Inspect the changed public API.
+4. Determine affected namespaces.
+5. Determine whether public extension methods are involved.
+6. Locate `.docfx/docfx.json` or repository-specific DocFX config.
+7. Locate existing overwrite files and namespace pages.
+8. Locate availability include files.
+9. Locate relevant tests that demonstrate the API.
+10. Convert test usage into real-life documentation examples.
+11. Update XML documentation where needed.
+12. Update or create namespace overview pages.
+13. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
+14. Update extension-member tables.
+15. Update or create overwrite files, including type-page example sections for public non-abstraction types and example sections for public extension methods.
+16. Build an example inventory that maps each required public type and extension method to its example location.
+17. Preserve manual edits.
+18. Run `git diff` for touched documentation paths and confirm the diff is intentional.
 19. Run `dotnet build`.
 20. Run `dotnet test`.
 21. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
 22. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
-23. Report verification results and any remaining findings.
+23. Report verification results.
+
+When no specific API or namespace is named:
+
+1. Run `agents.cs`.
+2. Run the safety gates: capture `git status`, identify existing documentation changes, and avoid broad restore/recovery commands.
+3. Read repository guidance, especially root `AGENTS.md`.
+4. Locate `.docfx/docfx.json` or repository-specific DocFX config.
+5. Read `references/docfx-overwrite-files.md`.
+6. Run `dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --json` to collect deterministic missing-doc findings when the repository is buildable.
+7. If the validator reports multiple diagnostics, rerun it with `--repair-plan <temp-path>/docfx-repair-plan.md`, read that plan, and treat it as the work queue.
+8. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
+9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
+10. Determine every public non-abstraction type and every public extension method that requires an example.
+11. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
+12. Audit related namespace pages together so fixes are consistent across the public API family.
+13. Add or repair `Extension Members` tables for namespaces with public extension methods.
+14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
+15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, using `.docfx/api/{TypeUid}.md` in Codebelt repositories unless the repo has a stronger existing convention.
+16. Ensure `build.overwrite` includes the per-type overwrite files you create; update a namespace-only overwrite glob to include API overwrite files when needed.
+17. Create example sections for public extension methods that have no example yet.
+18. Build an example inventory that maps each required public type and extension method to its example location.
+19. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+20. Run `git diff` for touched documentation paths and confirm the diff is intentional.
+21. Run `dotnet build`.
+22. Run `dotnet test`.
+23. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
+24. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
+25. Report verification results and any remaining findings.
 
 ## Namespace Page Template
 
@@ -623,6 +641,7 @@ Before completing documentation work, verify:
 
 - [ ] `agents.cs` has run successfully.
 - [ ] `AGENTS.md` contains the managed DocFX documentation maintenance block.
+- [ ] Initial `git status --short` was inspected and existing documentation changes were treated as user work.
 - [ ] For multi-diagnostic audits, `docfx.cs --repair-plan` was written, read, and used as the authoritative work queue.
 - [ ] Only public API is documented.
 - [ ] Every namespace with public API has a namespace overview page.
@@ -642,6 +661,7 @@ Before completing documentation work, verify:
 - [ ] Existing manual edits are preserved.
 - [ ] Stale documentation is corrected.
 - [ ] No contradictory documentation remains.
+- [ ] `git diff` for touched documentation paths was inspected before final verification.
 - [ ] `dotnet build` has been run or the failure is reported.
 - [ ] `dotnet test` has been run or the failure is reported.
 - [ ] `docfx.cs --verify-docfx-build` has run successfully, including the temp-workspace DocFX build, or the failure is reported.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index ff4cdef..0b9308f 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -109,6 +109,7 @@
       "expectations": [
         "Treats newly created `.docfx/**/*.md` files as documentation deliverables rather than cleanup targets",
         "Does not run broad manual cleanup commands that delete DocFX directories by name",
+        "Lists cleanup candidates before deletion and classifies them as generated metadata, generated site output, or build artifacts",
         "Limits generated metadata cleanup to DocFX-generated `*.yml`, `.manifest`, and `*.manifest` files under configured metadata destinations",
         "Does not recursively delete a configured build output directory when it contains Markdown, source, project, solution, or DocFX configuration files",
         "Uses `docfx.cs --verify-docfx-build` so the DocFX build runs in a temp copy and generated site output stays out of the working tree",
@@ -122,11 +123,13 @@
       "expectations": [
         "Captures git status and diffs before modifying or recovering checked-out Markdown files",
         "Does not use broad git restore, checkout, reset, or whole-directory recovery commands",
+        "Stops and reports existing uncommitted documentation changes if they cannot be preserved safely",
         "Runs scripts/docfx.cs with --json and --repair-plan, then reads the generated repair plan before editing",
         "Audits `Codebelt.Bootstrapper.Console.md`, `Codebelt.Bootstrapper.md`, `Codebelt.Bootstrapper.Web.md`, and `Codebelt.Bootstrapper.Worker.md` together instead of updating only one file",
         "Uses `Extension Members` headings where extension methods are present",
         "Adds required examples for public non-abstraction types and public extension methods, not only namespace fly-ins or extension tables",
         "Builds and reports an example inventory mapping each required API to its example file and UID",
+        "Runs git diff for touched documentation paths after edits and before final verification",
         "Preserves authored Markdown and reports any remaining validation diagnostics instead of claiming completion"
       ]
     }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 9541cb7..18fcf96 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -58,7 +58,7 @@ Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--f
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown and forbid broad restore/checkout recovery. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
+`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
 
 `--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files and namespace pages are documentation output, not cleanup targets.
 
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index d267f5c..23e2db9 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -2179,9 +2179,13 @@ private static string BuildRepairPlan(Report report)
         sb.AppendLine("## Execution Gates");
         sb.AppendLine();
         sb.AppendLine("- Do not use broad restore or checkout commands to recover documentation files.");
+        sb.AppendLine("- Before deleting generated artifacts, list the exact paths and verify they are generated metadata, generated site output, or build artifacts.");
         sb.AppendLine("- Preserve authored `.md` and `.mdoc` files, including files created earlier in the run.");
+        sb.AppendLine("- Treat uncommitted documentation changes as user work; stop and report them if they cannot be preserved.");
         sb.AppendLine("- Treat `Extension Members` tables as incomplete until required examples exist.");
         sb.AppendLine("- Repair related namespace pages together; do not update only the first page that exposes a shared issue.");
+        sb.AppendLine("- After edits, inspect `git diff` for the touched documentation paths before final verification.");
+        sb.AppendLine("- If examples cannot be sourced or compiled, report the limitation instead of claiming completion.");
         sb.AppendLine("- Rerun validation with `--verify-docfx-build` before claiming completion.");
         sb.AppendLine();
 

From 250e46feb667f454e3a2d6e1b491501712b01bf4 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 23:04:59 +0200
Subject: [PATCH 18/88] =?UTF-8?q?=F0=9F=92=AC=20update=20dotnet-docfx-dige?=
 =?UTF-8?q?st=20description=20with=20safety=20gate=20features?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Expand skill description to include no-broad-restore rules, cleanup-path listing requirements, related-namespace coverage validation, and git diff review completion checks in the repair-plan feature summary.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c8672be..a7dd03e 100644
--- a/README.md
+++ b/README.md
@@ -538,7 +538,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
 - **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, resolving NuGet package dependencies, deps files, and installed .NET framework reference packs instead of guessing from text,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
-- **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, required-example inventory, sample failures, cleanup gates, and completion checks so agents do not update one namespace and forget the rest,
+- **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
 - **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, namespace-only overwrite globs must be widened to include those files, and namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,

From 4ab4b0daef9ca5b2b8f27bd264c28bbc66f325bc Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 23:25:02 +0200
Subject: [PATCH 19/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20clarify=20script=20r?=
 =?UTF-8?q?esolution=20strategy=20in=20dotnet-docfx-digest=20skill?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Explicitly document that agents.cs and docfx.cs are resolved from the loaded skill directory, with a fallback to repo-managed source when the skill directory is unavailable. Update all script invocation examples to use placeholder paths (<resolved-skill-dir> and <repo-root>) and clarify that repo-root must point to the actual target repository being documented. Add test case for script resolution when skill is installed globally and target repo doesn't vendor the scripts. Update reference documentation with script path resolution guidance.
---
 skills/dotnet-docfx-digest/SKILL.md            | 18 ++++++++++--------
 skills/dotnet-docfx-digest/evals/evals.json    | 12 ++++++++++++
 .../dotnet-docfx-digest/references/scripts.md  |  2 ++
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index fe4083d..0c1d1d2 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -20,22 +20,24 @@ This skill is autonomous by default. If the user invokes the skill without namin
 4. Fill the missing DocFX pieces that can be derived from source evidence, including type-page overwrite examples for public non-abstraction types and public extension methods.
 5. Ask a concise clarifying question only when inspection exposes a correctness-affecting choice that cannot be resolved from repository evidence.
 
-When this skill is invoked against a repository, the agent must run the deterministic repository-instruction script before completing the task:
+When this skill is invoked against a repository, resolve the target repository root and bundled script paths before running any validation. Prefer the loaded `dotnet-docfx-digest` skill directory as the script source, for example `<skill-dir>/scripts/agents.cs` and `<skill-dir>/scripts/docfx.cs`. If the loaded skill directory is unavailable and the target repository contains the repo-managed source copy, use `skills/dotnet-docfx-digest/scripts/*.cs`. Do not conclude a script is unavailable until both locations have been checked.
+
+Run the deterministic repository-instruction script before completing the task:
 
 ```bash
-dotnet run --file skills/dotnet-docfx-digest/scripts/agents.cs -- --repo-root .
+dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-root>
 ```
 
 Before reporting completion, the agent must run the deterministic validator:
 
 ```bash
-dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --verify-docfx-build
+dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --verify-docfx-build
 ```
 
 For repo-wide audits or any validation run that produces more than a small number of diagnostics, the agent must also ask the validator to write a deterministic repair plan and use that plan as the authoritative work queue:
 
 ```bash
-dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --json --repair-plan <temp-path>/docfx-repair-plan.md
+dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --json --repair-plan <temp-path>/docfx-repair-plan.md
 ```
 
 If either script cannot run, the agent must report the exact command, exit code, and failure output. Do not claim repository instructions or documentation were verified unless the scripts ran successfully.
@@ -131,10 +133,10 @@ When creating or repairing overwrite files, read `references/docfx-overwrite-fil
 Persistent repository guidance is enforced by script, not by AI memory. When this skill is invoked, run:
 
 ```bash
-dotnet run --file skills/dotnet-docfx-digest/scripts/agents.cs -- --repo-root .
+dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-root>
 ```
 
-The script must create or update a marker-bounded DocFX documentation maintenance section in the repository root `AGENTS.md`. Do not manually duplicate this section. If the script fails, report the failure and do not claim `AGENTS.md` was updated.
+The script must create or update a marker-bounded DocFX documentation maintenance section in the repository root `AGENTS.md`. Resolve `<repo-root>` from the actual repository being documented, not from a temp workspace or the skill install folder. If the current working directory is already the target repository root, `<repo-root>` may be `.` after confirming it with repository evidence such as `git rev-parse --show-toplevel` or equivalent path inspection. Do not manually duplicate this section. If the script fails, report the exact command, exit code, and output, and do not claim `AGENTS.md` was updated.
 
 ## Public API Rule
 
@@ -256,7 +258,7 @@ Every code sample added or changed must be verified. A C# code sample must compi
 The deterministic validator compiles C# documentation samples as .NET 10 file-based apps. When completing DocFX documentation work, also ask it to verify the DocFX build in a temporary copy of the repository so generated metadata and site output stay outside the working tree. Run:
 
 ```bash
-dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --verify-docfx-build
+dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --verify-docfx-build
 ```
 
 A sample may opt out only when the code fence includes:
@@ -553,7 +555,7 @@ When no specific API or namespace is named:
 3. Read repository guidance, especially root `AGENTS.md`.
 4. Locate `.docfx/docfx.json` or repository-specific DocFX config.
 5. Read `references/docfx-overwrite-files.md`.
-6. Run `dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --json` to collect deterministic missing-doc findings when the repository is buildable.
+6. Run `dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --json` to collect deterministic missing-doc findings when the repository is buildable.
 7. If the validator reports multiple diagnostics, rerun it with `--repair-plan <temp-path>/docfx-repair-plan.md`, read that plan, and treat it as the work queue.
 8. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
 9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 0b9308f..e3a223c 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -132,6 +132,18 @@
         "Runs git diff for touched documentation paths after edits and before final verification",
         "Preserves authored Markdown and reports any remaining validation diagnostics instead of claiming completion"
       ]
+    },
+    {
+      "id": 11,
+      "prompt": "Use dotnet-docfx-digest on a .NET repository that does not contain a `skills/dotnet-docfx-digest/` folder. The skill is installed globally, and the target repository root is the current working directory.",
+      "expected_output": "Agent resolves agents.cs and docfx.cs from the loaded installed dotnet-docfx-digest skill directory instead of assuming the target repository vendors the skill source. It runs agents.cs first with an explicit --repo-root pointing at the target repository, verifies AGENTS.md was created or updated by the script, then runs docfx.cs against the same repository root. If either script path cannot be resolved, it reports every checked location plus the exact command failure instead of claiming the scripts are unavailable.",
+      "expectations": [
+        "Checks the loaded installed skill directory for scripts/agents.cs and scripts/docfx.cs before concluding the scripts are missing",
+        "Does not require the target repository to contain skills/dotnet-docfx-digest/scripts/*.cs",
+        "Passes the target repository path explicitly with --repo-root instead of relying on the skill install directory or a temp workspace as the repository root",
+        "Runs agents.cs before documentation validation so AGENTS.md receives the managed DocFX maintenance block",
+        "Reports the exact command, exit code, output, and checked script locations if script resolution or execution fails"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 18fcf96..30cf035 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -9,6 +9,8 @@ dotnet build <script>.cs
 
 Both scripts declare `#:property TargetFramework=net10.0` and `#:property PublishAot=false`, return deterministic exit codes, and emit machine-readable JSON with `--json`.
 
+When invoking the scripts from an installed skill, resolve the script path from the loaded `dotnet-docfx-digest` skill directory and pass the target repository separately with `--repo-root <repo-root>`. Do not assume the target repository contains `skills/dotnet-docfx-digest/scripts/*.cs`. If the loaded skill directory cannot be resolved, a repo-managed source checkout may use the repo-relative `skills/dotnet-docfx-digest/scripts/*.cs` path after confirming it exists.
+
 ## agents.cs
 
 Ensures the repository root `AGENTS.md` contains a marker-bounded DocFX documentation-maintenance block. It is idempotent, so repeated runs never duplicate the block. Content outside the markers is preserved, the host file's line endings are respected, and new files are written as UTF-8 without a BOM.

From 010f4ea67b6b2524bf17ef0707a2f4223cc7bee5 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 23:29:42 +0200
Subject: [PATCH 20/88] =?UTF-8?q?=F0=9F=94=A7=20update=20dotnet-docfx-dige?=
 =?UTF-8?q?st=20to=20resolve=20scripts=20from=20loaded=20skill=20dir?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index a7dd03e..e29b9ac 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -534,7 +534,7 @@ API documentation rots the moment code changes. A new public type ships without
 **dotnet-docfx-digest** moves the rules from prose into deterministic .NET 10 tooling, so guidance persists and verification is real.
 
 - **No-input audits by default** — `Use dotnet-docfx-digest` means inspect the repository, DocFX config, public API, tests, samples, overwrite files, namespace pages, and availability includes, then repair missing complementary documentation that can be derived from evidence before asking any clarifying questions,
-- **Persistent guidance by script, not memory** — `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; running it twice never duplicates the block, and `--check` gates it in CI,
+- **Persistent guidance by script, not memory** — `scripts/agents.cs` is resolved from the loaded skill directory, with a repo-managed source fallback when present, then writes an idempotent, marker-bounded DocFX maintenance block into the target repository `AGENTS.md`; running it twice never duplicates the block, and `--check` gates it in CI,
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
 - **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, resolving NuGet package dependencies, deps files, and installed .NET framework reference packs instead of guessing from text,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,

From ec43e9cfc5a500153b65520feeb9764010800d05 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 23:46:46 +0200
Subject: [PATCH 21/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20add=20strong-name=20?=
 =?UTF-8?q?signing-key=20fallback=20handling?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extend docfx verification to handle Codebelt repositories where the root .snk file is not present locally by automatically using -p:SkipSignAssembly=true during build, test, and DocFX verification. Updates skill instructions, evals, reference docs, and scripts to implement and document this behavior.
---
 skills/dotnet-docfx-digest/SKILL.md           | 24 ++++++++---
 skills/dotnet-docfx-digest/evals/evals.json   | 13 ++++++
 .../dotnet-docfx-digest/references/scripts.md |  4 +-
 skills/dotnet-docfx-digest/scripts/agents.cs  |  2 +
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 40 +++++++++++++++----
 5 files changed, 68 insertions(+), 15 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 0c1d1d2..124df8e 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -271,6 +271,17 @@ The reason is mandatory. Do not use silent opt-outs.
 
 Do not claim a sample compiles unless the validator or an equivalent repository verification command has compiled it successfully.
 
+## Codebelt Signing Keys
+
+Codebelt solutions are normally strong-name signed with a `.snk` file in the repository root on the main author's codespace. When building a Codebelt repository or a temporary copy of one, preserve and copy the root `.snk` file when it is present. If the target repository or temp copy does not have a root `.snk`, run build and test verification with signing disabled:
+
+```bash
+dotnet build -p:SkipSignAssembly=true
+dotnet test -p:SkipSignAssembly=true
+```
+
+Use the same MSBuild property for any equivalent repository build that documentation validation performs. This avoids reporting signing-key failures as documentation failures while preserving normal signed builds when the key is available.
+
 ## Namespace Overview Pages
 
 Every namespace containing public API must have a namespace overview Markdown page.
@@ -542,8 +553,8 @@ When the user names a changed API or namespace:
 16. Build an example inventory that maps each required public type and extension method to its example location.
 17. Preserve manual edits.
 18. Run `git diff` for touched documentation paths and confirm the diff is intentional.
-19. Run `dotnet build`.
-20. Run `dotnet test`.
+19. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+20. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 21. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
 22. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
 23. Report verification results.
@@ -570,8 +581,8 @@ When no specific API or namespace is named:
 18. Build an example inventory that maps each required public type and extension method to its example location.
 19. Preserve manual edits and correct stale contradictions instead of replacing whole files.
 20. Run `git diff` for touched documentation paths and confirm the diff is intentional.
-21. Run `dotnet build`.
-22. Run `dotnet test`.
+21. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+22. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 23. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
 24. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
 25. Report verification results and any remaining findings.
@@ -664,8 +675,8 @@ Before completing documentation work, verify:
 - [ ] Stale documentation is corrected.
 - [ ] No contradictory documentation remains.
 - [ ] `git diff` for touched documentation paths was inspected before final verification.
-- [ ] `dotnet build` has been run or the failure is reported.
-- [ ] `dotnet test` has been run or the failure is reported.
+- [ ] `dotnet build` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
+- [ ] `dotnet test` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
 - [ ] `docfx.cs --verify-docfx-build` has run successfully, including the temp-workspace DocFX build, or the failure is reported.
 - [ ] Generated DocFX metadata files and build output directories did not remain in the working tree after verification, and authored Markdown or documentation assets were not deleted as cleanup.
 - [ ] No broad restore or checkout command discarded authored documentation changes.
@@ -681,6 +692,7 @@ When reporting completion, include:
 - Availability handling,
 - Related namespace pages inspected and whether each was updated or left unchanged,
 - `AGENTS.md` created, updated, already compliant, or failed,
+- Signing-key handling: whether a root `.snk` was used/copied or `-p:SkipSignAssembly=true` was used because no root `.snk` was present,
 - Verification commands run,
 - Any verification failures or skipped checks.
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index e3a223c..49724d6 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -144,6 +144,19 @@
         "Runs agents.cs before documentation validation so AGENTS.md receives the managed DocFX maintenance block",
         "Reports the exact command, exit code, output, and checked script locations if script resolution or execution fails"
       ]
+    },
+    {
+      "id": 12,
+      "prompt": "Use dotnet-docfx-digest on a Codebelt library repository that is strong-name signed but this checkout does not have the author's root `.snk` file. Update the docs and run verification.",
+      "expected_output": "Agent preserves or copies the root `.snk` file when it exists, but because this checkout has no root `.snk`, it runs build and test verification with `-p:SkipSignAssembly=true`. The deterministic docfx.cs validator also uses the skip-sign fallback for its repository build, sample compilation builds, and temp-workspace DocFX verification instead of reporting signing-key failures as documentation failures.",
+      "expectations": [
+        "Checks whether the Codebelt repository root contains a `.snk` file before choosing verification commands",
+        "Uses `dotnet build -p:SkipSignAssembly=true` when no root `.snk` is present",
+        "Uses `dotnet test -p:SkipSignAssembly=true` when no root `.snk` is present",
+        "Preserves and copies a root `.snk` file into temp workspaces when one exists instead of disabling signing unnecessarily",
+        "Does not treat a missing local signing key as a documentation validation failure",
+        "Reports the skip-sign fallback in the verification summary when it was used"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 30cf035..ae3bfeb 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -44,7 +44,7 @@ Exit codes:
 
 ## docfx.cs
 
-Validates the deterministic documentation requirements against the compiled repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies, prefers reference assemblies, loads metadata through `System.Reflection.MetadataLoadContext`, resolves dependencies from project assets, deps files, and installed .NET reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, and compiles every C# documentation sample as a file-based app.
+Validates the deterministic documentation requirements against the compiled repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies, prefers reference assemblies, loads metadata through `System.Reflection.MetadataLoadContext`, resolves dependencies from project assets, deps files, and installed .NET reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, and compiles every C# documentation sample as a file-based app. For Codebelt strong-name signed repositories, repository and sample builds use the root `.snk` when present and automatically pass `-p:SkipSignAssembly=true` when no root `.snk` exists, so missing local signing keys do not masquerade as documentation failures.
 
 ```bash
 dotnet run --file docfx.cs -- --repo-root .
@@ -62,7 +62,7 @@ Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--f
 
 `--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
 
-`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files and namespace pages are documentation output, not cleanup targets.
+`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files and namespace pages are documentation output, not cleanup targets.
 
 Process execution drains stdout and stderr concurrently so verbose `dotnet build` or DocFX runs cannot deadlock on a full pipe while the validator waits for exit.
 
diff --git a/skills/dotnet-docfx-digest/scripts/agents.cs b/skills/dotnet-docfx-digest/scripts/agents.cs
index efab6e4..066573e 100644
--- a/skills/dotnet-docfx-digest/scripts/agents.cs
+++ b/skills/dotnet-docfx-digest/scripts/agents.cs
@@ -54,6 +54,8 @@ dotnet test
         dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --verify-docfx-build
         ```
 
+        Codebelt repositories are normally strong-name signed with a `.snk` file in the repository root on the main author's codespace. Preserve and copy that root `.snk` file when building a temporary copy. If the repository or temp copy has no root `.snk`, run build and test verification with `-p:SkipSignAssembly=true`, for example `dotnet build -p:SkipSignAssembly=true` and `dotnet test -p:SkipSignAssembly=true`.
+
         The DocFX build verification must run outside the working tree when possible. The `--verify-docfx-build` option copies the repository to a temp workspace, runs DocFX against the resolved `docfx.json` there, and removes the temp workspace afterward so generated API YAML, manifest files, and site output do not flood git status.
 
         If a command cannot be run, report the exact limitation or failure instead of claiming the documentation was verified.
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 23e2db9..ae10bba 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -604,7 +604,10 @@ private static void VerifyDocfxBuild(string repoRoot, string docfxPath, Report r
             CopyDirectory(repoRoot, tempRoot);
             var relativeDocfxPath = Path.GetRelativePath(repoRoot, docfxPath);
             var tempDocfxPath = Path.Combine(tempRoot, relativeDocfxPath);
-            var result = RunProcess(docfxExecutable, $"\"{tempDocfxPath}\"", tempRoot);
+            var environment = HasRootStrongNameKey(tempRoot)
+                ? null
+                : new Dictionary<string, string> { ["SkipSignAssembly"] = "true" };
+            var result = RunProcess(docfxExecutable, $"\"{tempDocfxPath}\"", tempRoot, environment);
             if (result.ExitCode != 0)
             {
                 report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
@@ -702,13 +705,26 @@ private static (bool Ok, string Output) BuildRepository(string repoRoot, string
     {
         // Build a solution if one is present, otherwise let dotnet resolve the project in the repo root.
         var target = Directory.GetFiles(repoRoot, "*.slnx").Concat(Directory.GetFiles(repoRoot, "*.sln")).FirstOrDefault();
+        var signingProperty = HasRootStrongNameKey(repoRoot) ? string.Empty : " -p:SkipSignAssembly=true";
         var args = target is null
-            ? $"build -c {configuration} --nologo"
-            : $"build \"{target}\" -c {configuration} --nologo";
+            ? $"build -c {configuration} --nologo{signingProperty}"
+            : $"build \"{target}\" -c {configuration} --nologo{signingProperty}";
         var result = RunProcess("dotnet", args, repoRoot);
         return (result.ExitCode == 0, result.StdOut + result.StdErr);
     }
 
+    private static bool HasRootStrongNameKey(string repoRoot)
+    {
+        try
+        {
+            return Directory.EnumerateFiles(repoRoot, "*.snk", SearchOption.TopDirectoryOnly).Any();
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
     // ----------------------------------------------------------------------
     // Project + API discovery
     // ----------------------------------------------------------------------
@@ -1770,7 +1786,7 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
                     continue;
                 }
 
-                var (ok, diagnostics, exitCode) = CompileSample(tempRoot, index, sample, libraryProjects, options.Configuration);
+                var (ok, diagnostics, exitCode) = CompileSample(tempRoot, index, sample, libraryProjects, options.Configuration, repoRoot);
                 if (ok)
                 {
                     report.Summary.SamplesCompiled++;
@@ -1789,7 +1805,7 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
     }
 
     private static (bool Ok, string Diagnostics, int ExitCode) CompileSample(string tempRoot, int index, SampleFence sample,
-        List<ProjectInfo> libraryProjects, string configuration)
+        List<ProjectInfo> libraryProjects, string configuration, string repoRoot)
     {
         var dir = Path.Combine(tempRoot, "sample_" + index);
         Directory.CreateDirectory(dir);
@@ -1813,7 +1829,8 @@ private static (bool Ok, string Diagnostics, int ExitCode) CompileSample(string
 
         File.WriteAllText(file, sb.ToString(), new UTF8Encoding(false));
 
-        var result = RunProcess("dotnet", $"build \"{file}\" -c {configuration} --nologo", dir);
+        var signingProperty = HasRootStrongNameKey(repoRoot) ? string.Empty : " -p:SkipSignAssembly=true";
+        var result = RunProcess("dotnet", $"build \"{file}\" -c {configuration} --nologo{signingProperty}", dir);
         return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
     }
 
@@ -1992,7 +2009,8 @@ private static (string FrontMatter, string Body) SplitFrontMatter(string text)
     // Process + output helpers
     // ----------------------------------------------------------------------
 
-    private static ProcessResult RunProcess(string fileName, string arguments, string workingDirectory)
+    private static ProcessResult RunProcess(string fileName, string arguments, string workingDirectory,
+        IReadOnlyDictionary<string, string>? environment = null)
     {
         var psi = new ProcessStartInfo
         {
@@ -2005,6 +2023,14 @@ private static ProcessResult RunProcess(string fileName, string arguments, strin
             CreateNoWindow = true
         };
 
+        if (environment is not null)
+        {
+            foreach (var (key, value) in environment)
+            {
+                psi.Environment[key] = value;
+            }
+        }
+
         try
         {
             using var process = Process.Start(psi);

From 396d18b029e016f2dd06c588b0ffc75c85b738f9 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 8 Jun 2026 23:46:55 +0200
Subject: [PATCH 22/88] =?UTF-8?q?=F0=9F=92=AC=20document=20keyless=20stron?=
 =?UTF-8?q?g-name=20verification=20for=20signed=20repos?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Explain to repository users that the dotnet-docfx-digest skill now supports strong-name signed repositories without requiring a local .snk file by automatically using -p:SkipSignAssembly=true when verification runs.
---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e29b9ac..8ade41e 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -537,6 +537,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Persistent guidance by script, not memory** — `scripts/agents.cs` is resolved from the loaded skill directory, with a repo-managed source fallback when present, then writes an idempotent, marker-bounded DocFX maintenance block into the target repository `AGENTS.md`; running it twice never duplicates the block, and `--check` gates it in CI,
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
 - **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, resolving NuGet package dependencies, deps files, and installed .NET framework reference packs instead of guessing from text,
+- **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
 - **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, namespace-only overwrite globs must be widened to include those files, and namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`,

From 81d3e6994b56670c0f3c07aaa016fa5f16df4224 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Tue, 9 Jun 2026 01:15:23 +0200
Subject: [PATCH 23/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20add=20Completion=20R?=
 =?UTF-8?q?epair=20Loop=20to=20docfx=20workflow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce iterative repair pattern after per-type example and overwrite edits. Agents must rerun docfx.cs --json after modifications and fix remaining EXAMPLE_MISSING and overwrite inclusion diagnostics before completion, instead of listing them as final findings. Updates skill instructions, evals, and README to document and test this mandatory loop.
---
 README.md                                   |  4 +--
 skills/dotnet-docfx-digest/SKILL.md         | 28 ++++++++++++++++-----
 skills/dotnet-docfx-digest/evals/evals.json |  9 ++++---
 3 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 8ade41e..a7b8f0c 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -540,7 +540,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
-- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, namespace-only overwrite globs must be widened to include those files, and namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`,
+- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, namespace-only overwrite globs must be widened to include those files, namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics are fixed or exact blockers are reported,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 124df8e..afaff54 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -34,6 +34,19 @@ Before reporting completion, the agent must run the deterministic validator:
 dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --verify-docfx-build
 ```
 
+## Completion Repair Loop
+
+Do not stop at namespace pages, extension-member tables, or a first-pass documentation edit. Those surfaces are useful discovery aids, but they do not prove that generated type pages have the required examples. Before deeming a DocFX documentation request complete, run a closure loop:
+
+1. Run `docfx.cs --json` after edits and read the remaining diagnostics.
+2. If diagnostics include `EXAMPLE_MISSING`, missing namespace pages, stale extension-member tables, sample compile failures, missing availability, or overwrite inclusion problems, treat them as the next work queue rather than final notes.
+3. For every `EXAMPLE_MISSING` public non-abstraction type, create or update the type-page overwrite file for that type UID, such as `.docfx/api/ApplicationHostFactory.md`, and put the example in that file or another overwrite section that targets the type UID directly.
+4. For every required example file, verify `build.overwrite` includes the file path or a glob that reaches it. Widen namespace-only overwrite globs when needed.
+5. Update the example inventory so each required public non-abstraction type and public extension method maps to the exact example file and UID.
+6. Rerun the validator and repeat the loop until required diagnostics are gone, or stop and report the exact blocker, command, exit code, and remaining diagnostic codes.
+
+The completion loop is the guard against the common failure where an agent finishes namespace overview pages but forgets per-type API overwrite pages. Namespace-level examples do not satisfy `EXAMPLE_MISSING` for public non-abstraction types.
+
 For repo-wide audits or any validation run that produces more than a small number of diagnostics, the agent must also ask the validator to write a deterministic repair plan and use that plan as the authoritative work queue:
 
 ```bash
@@ -555,9 +568,10 @@ When the user names a changed API or namespace:
 18. Run `git diff` for touched documentation paths and confirm the diff is intentional.
 19. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 20. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-21. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
-22. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
-23. Report verification results.
+21. Run the Completion Repair Loop: rerun `docfx.cs --json`, read remaining diagnostics, repair missing per-type examples and overwrite inclusion issues, update the example inventory, and repeat until required diagnostics are gone or a precise blocker is reported.
+22. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
+23. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
+24. Report verification results.
 
 When no specific API or namespace is named:
 
@@ -583,9 +597,10 @@ When no specific API or namespace is named:
 20. Run `git diff` for touched documentation paths and confirm the diff is intentional.
 21. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 22. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-23. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
-24. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
-25. Report verification results and any remaining findings.
+23. Run the Completion Repair Loop: rerun `docfx.cs --json`, read remaining diagnostics, repair missing per-type examples and overwrite inclusion issues, update the example inventory, and repeat until required diagnostics are gone or a precise blocker is reported.
+24. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
+25. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
+26. Report verification results and any remaining findings.
 
 ## Namespace Page Template
 
@@ -665,6 +680,7 @@ Before completing documentation work, verify:
 - [ ] Public extension methods have at least one example, not only a table entry.
 - [ ] An example inventory maps every required public type and extension method to its example file and UID.
 - [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`.
+- [ ] The Completion Repair Loop was run after edits, and remaining `EXAMPLE_MISSING` or overwrite inclusion diagnostics were fixed or reported as exact blockers.
 - [ ] Abstractions without examples have a clear reason.
 - [ ] Examples are realistic and copy/paste-ready.
 - [ ] Examples compile.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 49724d6..7cb5ebd 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -77,16 +77,17 @@
     },
     {
       "id": 7,
-      "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but public non-abstraction types such as `Class1` and public extension methods have no examples. The DocFX config currently has build.overwrite pointing only at .docfx/api/namespaces/**/*.md, and there are no existing per-type overwrite files.",
-      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates separate per-type DocFX overwrite files such as .docfx/api/Acme.Class1.md for missing concrete-type examples, updates build.overwrite so those per-type files are included, puts type examples on the generated type page/overwrite section rather than namespace pages, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, and reruns scripts/docfx.cs until EXAMPLE_MISSING findings are gone, using --verify-docfx-build before completion so DocFX output is generated in temp space.",
+      "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but public non-abstraction types such as `ApplicationHostFactory` and public extension methods have no examples. The DocFX config currently has build.overwrite pointing only at .docfx/api/namespaces/**/*.md, and there are no existing per-type overwrite files.",
+      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates separate per-type DocFX overwrite files such as .docfx/api/Acme.ApplicationHostFactory.md for missing concrete-type examples, updates build.overwrite so those per-type files are included, puts type examples on the generated type page/overwrite section rather than namespace pages, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, runs the Completion Repair Loop by rerunning scripts/docfx.cs --json after edits, fixes remaining EXAMPLE_MISSING or overwrite inclusion diagnostics instead of listing them as final notes, and uses --verify-docfx-build before completion so DocFX output is generated in temp space.",
       "expectations": [
         "Treats namespace overview pages and Extension Members tables as insufficient when examples are missing",
         "Creates separate per-type DocFX overwrite files for public non-abstraction type examples when no type files exist yet",
         "Updates a namespace-only build.overwrite glob so the new per-type overwrite files are included",
-        "Places a public Class1 example on the Class1 type page/overwrite section rather than only on the namespace page",
+        "Places a public ApplicationHostFactory example on the ApplicationHostFactory type page/overwrite section rather than only on the namespace page",
         "Creates or updates overwrite content for public extension method examples, or places the example on the extension class or namespace page while explicitly demonstrating the method",
         "Uses generated DocFX UIDs or verified metadata instead of inventing overwrite UIDs",
-        "Runs scripts/docfx.cs and responds to EXAMPLE_MISSING diagnostics before claiming completion, then uses --verify-docfx-build for final DocFX build verification",
+        "Runs the Completion Repair Loop after edits by rerunning scripts/docfx.cs --json, fixing remaining EXAMPLE_MISSING and overwrite inclusion diagnostics, and updating the example inventory before claiming completion",
+        "Uses --verify-docfx-build for final DocFX build verification",
         "Compiles changed C# examples or reports the exact verification failure"
       ]
     },

From e65731774bef91972525a5dbfb75f176b78a7d05 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Tue, 9 Jun 2026 02:03:54 +0200
Subject: [PATCH 24/88] =?UTF-8?q?=F0=9F=90=9B=20improve=20example=20valida?=
 =?UTF-8?q?tion=20diagnostics=20and=20reporting?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enhance EXAMPLE_MISSING diagnostics with expected overwrite file paths and clearer guidance. Introduce AppendRequiredExampleDiagnostics() to render a formatted table showing namespace, expected location, and required action. Update docfx.cs to pass docfxWorkspace context for accurate path resolution. Revise skill instructions and evals to match improved diagnostic output and reporting format.
---
 README.md                                     |  6 +-
 skills/dotnet-docfx-digest/SKILL.md           | 21 +++++++
 skills/dotnet-docfx-digest/evals/evals.json   | 14 +++++
 .../dotnet-docfx-digest/references/scripts.md |  2 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 58 +++++++++++++++++--
 5 files changed, 91 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index a7b8f0c..ada421d 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -539,8 +539,8 @@ API documentation rots the moment code changes. A new public type ships without
 - **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, resolving NuGet package dependencies, deps files, and installed .NET framework reference packs instead of guessing from text,
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
-- **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
-- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, namespace-only overwrite globs must be widened to include those files, namespace tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics are fixed or exact blockers are reported,
+- **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
+- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are tracked through an explicit inventory and created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, namespace-only overwrite globs must be widened to include those files, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics are fixed or exact blockers are reported,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index afaff54..40cf361 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -47,6 +47,27 @@ Do not stop at namespace pages, extension-member tables, or a first-pass documen
 
 The completion loop is the guard against the common failure where an agent finishes namespace overview pages but forgets per-type API overwrite pages. Namespace-level examples do not satisfy `EXAMPLE_MISSING` for public non-abstraction types.
 
+## Type-Page Example Gate
+
+Before editing examples, build a small example inventory from validator output and source evidence. This inventory is the task queue, not a summary for the final response. Each required item should have this shape:
+
+```markdown
+| UID | Kind | Required example location | Source evidence | Status |
+|---|---|---|---|---|
+| Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | ApplicationHostFactoryTest | Missing |
+```
+
+For every public non-abstraction type, the required example location is a type UID overwrite section. In Codebelt repositories, default to a separate file named `.docfx/api/{TypeUid}.md`. For example, when the missing type is `ApplicationHostFactory`, create `.docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or the exact UID path reported by the validator. Do not put the only example in `.docfx/api/namespaces/*.md`, because that improves the namespace page while leaving the generated type page incomplete.
+
+For public extension methods, the inventory must name the method and the section that demonstrates it. Prefer the generated method UID when known; otherwise use the declaring extension class UID or namespace page only when the example explicitly calls the extension method.
+
+Do not mark the inventory item complete until all of these are true:
+
+- The overwrite section targets the required UID or an allowed extension-method fallback UID.
+- `build.overwrite` includes the file by exact path or a glob such as `api/**/*.md`.
+- The example code fence compiles or carries an explicit, justified skip marker.
+- A rerun of `docfx.cs --json` no longer reports `EXAMPLE_MISSING` for that UID.
+
 For repo-wide audits or any validation run that produces more than a small number of diagnostics, the agent must also ask the validator to write a deterministic repair plan and use that plan as the authoritative work queue:
 
 ```bash
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 7cb5ebd..ffc210a 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -158,6 +158,20 @@
         "Does not treat a missing local signing key as a documentation validation failure",
         "Reports the skip-sign fallback in the verification summary when it was used"
       ]
+    },
+    {
+      "id": 13,
+      "prompt": "A previous run of dotnet-docfx-digest enhanced only `.docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.md` and added examples there, but the validator still reports `EXAMPLE_MISSING` for the public concrete type `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory`. Fix the documentation gap and explain why namespace examples were insufficient.",
+      "expected_output": "Agent treats the remaining EXAMPLE_MISSING diagnostic as an unfinished work item, creates or updates `.docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` with DocFX front matter for uid `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory`, adds a buildable ApplicationHostFactory example derived from source or tests, updates build.overwrite when needed so `.docfx/api/**/*.md` files are included, reruns scripts/docfx.cs --json until the diagnostic is gone, and explains that namespace examples and Extension Members tables complement but do not replace examples on generated type pages.",
+      "expectations": [
+        "Does not treat the namespace page examples as sufficient for the ApplicationHostFactory concrete type",
+        "Creates or updates the per-type overwrite file `.docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or an equivalent file that targets the exact ApplicationHostFactory UID",
+        "Uses DocFX front matter with uid `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory` for the type example section",
+        "Adds a realistic, copy/paste-ready C# example for ApplicationHostFactory based on actual source, tests, or public behavior",
+        "Updates build.overwrite when the existing glob only includes `.docfx/api/namespaces/**/*.md`",
+        "Reruns scripts/docfx.cs --json after the edit and treats any remaining EXAMPLE_MISSING diagnostic as blocking completion",
+        "Explains that namespace overview examples and Extension Members tables are complementary surfaces, not substitutes for type-page examples"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index ae3bfeb..7cf1368 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -60,7 +60,7 @@ Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--f
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
+`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, a required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected per-type overwrite path such as `.docfx/api/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
 
 `--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files and namespace pages are documentation output, not cleanup targets.
 
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index ae10bba..2e74290 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -200,7 +200,7 @@ private static int Validate(Options options)
         }
 
         // 12. Verify mandatory examples exist before compiling the examples that were found.
-        ValidateRequiredExamples(repoRoot, markdownFiles, api, options, changedFiles, report);
+        ValidateRequiredExamples(repoRoot, docfxWorkspace, markdownFiles, api, options, changedFiles, report);
 
         // 13. Extract and compile C# documentation samples.
         if (options.ValidateSamples)
@@ -1586,7 +1586,7 @@ private static bool HasAvailability(string body)
     // Required example validation
     // ----------------------------------------------------------------------
 
-    private static void ValidateRequiredExamples(string repoRoot, List<string> markdownFiles, ApiModel api,
+    private static void ValidateRequiredExamples(string repoRoot, string docfxWorkspace, List<string> markdownFiles, ApiModel api,
         Options options, HashSet<string>? changedFiles, Report report)
     {
         var sections = new List<OverwriteSection>();
@@ -1613,12 +1613,17 @@ private static void ValidateRequiredExamples(string repoRoot, List<string> markd
             var expectedUid = target.Kind == ApiTargetKind.Type
                 ? target.Uid
                 : target.DeclaringTypeUid ?? target.Uid;
+            var expectedPath = target.Kind == ApiTargetKind.Type
+                ? Rel(repoRoot, Path.Combine(docfxWorkspace, "api", $"{target.Uid}.md"))
+                : target.DeclaringTypeUid is null
+                    ? null
+                    : Rel(repoRoot, Path.Combine(docfxWorkspace, "api", $"{target.DeclaringTypeUid}.md"));
 
             var message = target.Kind == ApiTargetKind.Type
-                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to a per-type overwrite file for uid `{target.Uid}` (for Codebelt repositories, create `.docfx/api/{target.Uid}.md` and ensure build.overwrite includes it, for example with `api/**/*.md`)."
-                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}`, its declaring type uid `{expectedUid}`, or the namespace page `{target.Namespace}`.";
+                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}` in `{expectedPath}` or another overwrite file that targets this exact type UID. Namespace overview examples do not satisfy this diagnostic. Ensure build.overwrite includes the file, for example with `api/**/*.md`."
+                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}`, its declaring type uid `{expectedUid}`, or the namespace page `{target.Namespace}`. The example must explicitly call `{target.DisplayName}`.";
 
-            report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", null, target.Namespace, message));
+            report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", expectedPath, target.Namespace, message));
         }
     }
 
@@ -2219,7 +2224,7 @@ private static string BuildRepairPlan(Report report)
         AppendDiagnostics(sb, "Namespace And Extension Table Repairs", report.Errors.Where(e =>
             e.Code.StartsWith("NAMESPACE_", StringComparison.Ordinal) ||
             e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal)));
-        AppendDiagnostics(sb, "Required Example Inventory", report.Errors.Where(e => e.Code is "EXAMPLE_MISSING"));
+        AppendRequiredExampleDiagnostics(sb, report.Errors.Where(e => e.Code is "EXAMPLE_MISSING"));
         AppendDiagnostics(sb, "Sample Compilation Repairs", report.Errors.Where(e =>
             e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_SKIP_REASON_MISSING"));
         AppendDiagnostics(sb, "Other Errors", report.Errors.Where(e =>
@@ -2274,6 +2279,47 @@ private static void AppendDiagnostics(StringBuilder sb, string title, IEnumerabl
         }
     }
 
+    private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerable<Diagnostic> diagnostics)
+    {
+        var items = diagnostics
+            .OrderBy(d => d.Namespace ?? string.Empty, StringComparer.Ordinal)
+            .ThenBy(d => d.Path ?? string.Empty, StringComparer.Ordinal)
+            .ThenBy(d => d.Message, StringComparer.Ordinal)
+            .ToList();
+
+        sb.AppendLine("## Required Example Inventory");
+        sb.AppendLine();
+        if (items.Count == 0)
+        {
+            sb.AppendLine("None.");
+            sb.AppendLine();
+            return;
+        }
+
+        sb.AppendLine("Treat this section as the authoritative example work queue. Namespace overview pages and `Extension Members` tables are not complete until each item below maps to a concrete overwrite example and rerunning `docfx.cs --json` removes the diagnostic.");
+        sb.AppendLine();
+        sb.AppendLine("| Namespace | Expected overwrite location | Diagnostic | Required action |");
+        sb.AppendLine("|---|---|---|---|");
+
+        foreach (var diagnostic in items)
+        {
+            var ns = EscapeTable(diagnostic.Namespace ?? "(repository)");
+            var path = EscapeTable(string.IsNullOrWhiteSpace(diagnostic.Path) ? "(method UID, declaring type UID, or namespace page)" : diagnostic.Path);
+            var message = EscapeTable(diagnostic.Message);
+            var action = diagnostic.Message.Contains("Public non-abstraction type", StringComparison.Ordinal)
+                ? "Create or update the per-type UID overwrite file, include it in build.overwrite, add a compiling Examples section, then rerun validation."
+                : "Add a compiling Examples section that explicitly calls the extension method, then rerun validation.";
+            sb.AppendLine($"| {ns} | `{path}` | `EXAMPLE_MISSING` | {EscapeTable(action)} {message} |");
+        }
+
+        sb.AppendLine();
+    }
+
+    private static string EscapeTable(string value)
+    {
+        return value.Replace("|", "\\|", StringComparison.Ordinal).ReplaceLineEndings(" ");
+    }
+
     // ----------------------------------------------------------------------
     // Argument parsing
     // ----------------------------------------------------------------------

From 7c7f8137e2f87f3875889e35df2a967f36c8346d Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Tue, 9 Jun 2026 02:25:04 +0200
Subject: [PATCH 25/88] =?UTF-8?q?=F0=9F=A6=BA=20validate=20sample=20skip-c?=
 =?UTF-8?q?ompile=20reasons=20strength?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add SAMPLE_SKIP_REASON_INSUFFICIENT diagnostic to catch weak skip reasons that are documentation work rather than true compilation blockers. Implement IsInsufficientSkipReason() to detect patterns like 'requires package', 'shows framework pattern', or 'full example demonstrates X'. Clarify in skill docs that extension-method examples belong on declaring class or namespace pages, not method-UID filenames. Update error inventory and evaluation tests.
---
 README.md                                     |  5 +--
 skills/dotnet-docfx-digest/SKILL.md           | 22 +++++++++++--
 skills/dotnet-docfx-digest/evals/evals.json   | 14 ++++++++
 .../dotnet-docfx-digest/references/scripts.md |  6 ++--
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 33 ++++++++++++++++---
 5 files changed, 69 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index ada421d..e504b46 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, curated fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -540,7 +540,8 @@ API documentation rots the moment code changes. A new public type ships without
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
-- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are tracked through an explicit inventory and created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, namespace-only overwrite globs must be widened to include those files, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics are fixed or exact blockers are reported,
+- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are tracked through an explicit inventory and created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace-only overwrite globs must be widened to include required API files, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics are fixed or exact blockers are reported,
+- **Complementary namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need curated fly-ins, type-family context, extension-method group explanations, availability, and pointers to representative type pages,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 40cf361..5f686c3 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -47,6 +47,16 @@ Do not stop at namespace pages, extension-member tables, or a first-pass documen
 
 The completion loop is the guard against the common failure where an agent finishes namespace overview pages but forgets per-type API overwrite pages. Namespace-level examples do not satisfy `EXAMPLE_MISSING` for public non-abstraction types.
 
+## Complementary Documentation Surfaces
+
+Do not trade one documentation surface for the other. Namespace pages and per-type pages have different jobs, and both must remain useful:
+
+- Namespace pages explain the package or namespace shape: what problem the namespace solves, when to use it, important type families, extension-method groups, availability, and links or references to representative type pages.
+- Per-type pages explain how to use a specific public concrete type with copy/paste-ready examples.
+- Extension-method examples normally live on the declaring extension class page or the namespace page, but the namespace page must still read like curated API documentation, not a dumping ground for examples.
+
+When per-type examples are added, revisit the related namespace page and keep its fly-in well-versed and developer-friendly. Moving examples out of the namespace page must not leave the namespace page as a generic sentence plus table. Preserve or improve the curated namespace overview that helps readers choose the right type before they drill into generated type pages.
+
 ## Type-Page Example Gate
 
 Before editing examples, build a small example inventory from validator output and source evidence. This inventory is the task queue, not a summary for the final response. Each required item should have this shape:
@@ -59,11 +69,11 @@ Before editing examples, build a small example inventory from validator output a
 
 For every public non-abstraction type, the required example location is a type UID overwrite section. In Codebelt repositories, default to a separate file named `.docfx/api/{TypeUid}.md`. For example, when the missing type is `ApplicationHostFactory`, create `.docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or the exact UID path reported by the validator. Do not put the only example in `.docfx/api/namespaces/*.md`, because that improves the namespace page while leaving the generated type page incomplete.
 
-For public extension methods, the inventory must name the method and the section that demonstrates it. Prefer the generated method UID when known; otherwise use the declaring extension class UID or namespace page only when the example explicitly calls the extension method.
+For public extension methods, the inventory must name the method and the section that demonstrates it. Prefer a readable overwrite file for the declaring extension class UID, or the namespace page when that is the existing extension-method documentation surface. Method UIDs can contain signatures, generic parameters, hashes, or URL-encoded characters, so do not create separate encoded method-UID filenames such as `MyExtensions.%3CT%3E...md` by default. Use a method UID section only when generated metadata confirms the UID and the section can live in a readable existing or declaring-class overwrite file. The example must explicitly call the extension method.
 
 Do not mark the inventory item complete until all of these are true:
 
-- The overwrite section targets the required UID or an allowed extension-method fallback UID.
+- The overwrite section targets the required type UID or an allowed extension-method location such as the declaring extension class UID or namespace UID.
 - `build.overwrite` includes the file by exact path or a glob such as `api/**/*.md`.
 - The example code fence compiles or carries an explicit, justified skip marker.
 - A rerun of `docfx.cs --json` no longer reports `EXAMPLE_MISSING` for that UID.
@@ -224,7 +234,7 @@ For example, create `.docfx/api/Codebelt.Bootstrapper.ProgramRoot.md` for uid `C
 
 For public non-abstraction types, the example must belong to the generated type page/overwrite section for that type `uid`. For example, if `Class1` is public and not an abstraction, add an `Examples` section to the DocFX overwrite content for `Class1` so the example appears on `Class1.md` at the bottom of the generated API page. A namespace page example does not satisfy the type-page example requirement for `Class1`.
 
-For public extension methods, add the example to the generated method UID when known; otherwise add it to the extension class UID or the namespace page, but the example must name and demonstrate the extension method.
+For public extension methods, add the example to the declaring extension class UID or the namespace page by default, but the example must name and demonstrate the extension method. Add a generated method UID section only when the exact UID is verified and it can be kept in a readable overwrite file. Do not create URL-encoded or hash-like filenames just to mirror a method UID; DocFX cares about the `uid` in front matter, not that the filename repeats the UID.
 
 An example may be omitted only when the item is an abstraction, such as:
 
@@ -303,6 +313,8 @@ A sample may opt out only when the code fence includes:
 
 The reason is mandatory. Do not use silent opt-outs.
 
+Use skip markers sparingly. A reason such as "shows the framework pattern", "full example requires X package", or "example only" is not enough; it explains intent or setup, not why compilation is impossible. Prefer making the sample compile by adding normal public setup code, public package imports already available to the repository, or a smaller example. Reserve skip markers for samples that cannot be compiled deterministically by the validator, such as snippets that require a live external service, generated credentials, an OS-specific runtime service, or a host environment the file-based sample compiler cannot provide.
+
 Do not claim a sample compiles unless the validator or an equivalent repository verification command has compiled it successfully.
 
 ## Codebelt Signing Keys
@@ -343,6 +355,8 @@ The page must provide a developer-friendly fly-in explaining what the namespace
 - Explain the developer problem it solves.
 - Explain when to use it.
 - Mention important concepts or type families.
+- Mention representative concrete types or extension-method groups when that helps readers choose where to go next.
+- Link or refer to type pages that carry detailed examples when examples are intentionally kept out of the namespace page.
 - Avoid marketing language.
 - Avoid restating type names without explaining purpose.
 - Keep the explanation accurate to the public API.
@@ -684,6 +698,8 @@ Console.WriteLine(normalized);
 
 The namespace containing the extension method must be imported. The sample must compile in a consuming project.
 
+For generic extension methods or methods whose generated DocFX UID contains synthetic fragments such as `<G>$...`, `%3C...%3E`, hashes, or signature encodings, keep the example in a readable file such as `.docfx/api/X.Y.Z.EndpointConventionBuilderExtensions.md` or the namespace page. Do not mirror the synthetic method UID in the filename.
+
 ## Verification Checklist
 
 Before completing documentation work, verify:
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index ffc210a..38066f4 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -172,6 +172,20 @@
         "Reruns scripts/docfx.cs --json after the edit and treats any remaining EXAMPLE_MISSING diagnostic as blocking completion",
         "Explains that namespace overview examples and Extension Members tables are complementary surfaces, not substitutes for type-page examples"
       ]
+    },
+    {
+      "id": 14,
+      "prompt": "Use dotnet-docfx-digest on a Carter-style repository where `EndpointConventionBuilderExtensions` has generic extension methods whose generated DocFX method UIDs look like `Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.<G>$6D0D8037DBBD61D10816ECA5F93B896F`. The previous run created `.docfx/api/Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.%3CG%3E%246D0D8037DBBD61D10816ECA5F93B896F.md`, added `// dotnet-docfx-digest:skip-compile - Full example requires Cuemon.Extensions.AspNetCore.Text.Yaml package`, and left the namespace page as a thin table. Repair the docs.",
+      "expected_output": "Agent removes or avoids the encoded/hash-like method UID filename, places extension-method examples in a readable declaring-class overwrite file such as `.docfx/api/Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.md` or the namespace page, does not use a package-requirement skip marker as a compile escape hatch, either makes the sample compile or reports a precise deterministic blocker, and restores the namespace page as a curated overview with developer-friendly purpose, type-family context, extension-method groups, availability, and pointers to detailed examples.",
+      "expectations": [
+        "Does not create or keep URL-encoded/hash-like method UID filenames for generic extension methods such as `%3CG%3E%24...`",
+        "Uses a readable declaring extension class overwrite file or namespace page for extension-method examples",
+        "Ensures the example explicitly calls the documented extension method",
+        "Does not use `// dotnet-docfx-digest:skip-compile - Full example requires ... package` as the final state",
+        "Documents any required package or setup outside the code fence when relevant",
+        "Keeps or improves the namespace page as a curated overview rather than reducing it to a generic sentence and table",
+        "Reruns scripts/docfx.cs --json and treats `SAMPLE_SKIP_REASON_INSUFFICIENT`, `SAMPLE_COMPILE_FAILED`, and `EXAMPLE_MISSING` as blocking diagnostics"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 7cf1368..cecdde5 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -60,7 +60,7 @@ Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--f
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, a required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected per-type overwrite path such as `.docfx/api/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
+`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, a required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected per-type overwrite path such as `.docfx/api/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
 
 `--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files and namespace pages are documentation output, not cleanup targets.
 
@@ -80,7 +80,7 @@ Exit codes:
 | 7 | Sample compilation failed |
 | 8 | Unexpected internal error |
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`.
 
 ### Sample opt-out
 
@@ -92,6 +92,8 @@ A C# fence may opt out of compilation only with a mandatory reason:
 
 A skip marker without a reason is reported as `SAMPLE_SKIP_REASON_MISSING`.
 
+A skip marker with a weak reason such as "full example requires X package" or "example shows the framework pattern" is reported as `SAMPLE_SKIP_REASON_INSUFFICIENT`. Package requirements and framework setup belong in the documentation around a compiling sample; they are not enough to skip compilation by themselves.
+
 ### Extension-method detection note
 
 Extension methods are detected from compiled metadata: a public static method, carrying `System.Runtime.CompilerServices.ExtensionAttribute`, declared on a public static non-generic class, with at least one parameter. The first parameter's type is recorded as the extended type. The C# compiler marks the method, not the first parameter, with `ExtensionAttribute`, so detection keys off the method attribute to match real metadata.
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 2e74290..1f45adb 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -1621,7 +1621,7 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
 
             var message = target.Kind == ApiTargetKind.Type
                 ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}` in `{expectedPath}` or another overwrite file that targets this exact type UID. Namespace overview examples do not satisfy this diagnostic. Ensure build.overwrite includes the file, for example with `api/**/*.md`."
-                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}`, its declaring type uid `{expectedUid}`, or the namespace page `{target.Namespace}`. The example must explicitly call `{target.DisplayName}`.";
+                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to the declaring extension class uid `{expectedUid}` or the namespace page `{target.Namespace}` by default. The example must explicitly call `{target.DisplayName}`. Do not create URL-encoded or hash-like method UID filenames; use a method UID section only when the exact generated UID is verified and can live in a readable overwrite file.";
 
             report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", expectedPath, target.Namespace, message));
         }
@@ -1783,6 +1783,11 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
                         report.Errors.Add(new Diagnostic("SAMPLE_SKIP_REASON_MISSING", Rel(repoRoot, sample.File), null,
                             $"A C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) uses the skip-compile marker without a mandatory reason."));
                     }
+                    else if (IsInsufficientSkipReason(skip.Reason))
+                    {
+                        report.Errors.Add(new Diagnostic("SAMPLE_SKIP_REASON_INSUFFICIENT", Rel(repoRoot, sample.File), null,
+                            $"A C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) uses a weak skip-compile reason: '{skip.Reason}'. Package requirements, framework-pattern explanations, or full-example notes are documentation work, not a compile opt-out. Make the sample compile, document the package requirement outside the code fence, or use a deterministic blocker such as an external service or host environment that the sample compiler cannot provide."));
+                    }
                     else
                     {
                         report.Summary.SamplesSkipped++;
@@ -1944,6 +1949,26 @@ private static (bool Found, string Reason) FindSkip(string code)
         return (false, string.Empty);
     }
 
+    private static bool IsInsufficientSkipReason(string reason)
+    {
+        if (Regex.IsMatch(reason, @"(?i)\b(full\s+)?example\s+(shows|demonstrates|requires)\b"))
+        {
+            return true;
+        }
+
+        if (Regex.IsMatch(reason, @"(?i)\brequires\b.*\b(package|nuget|reference|dependency)\b"))
+        {
+            return true;
+        }
+
+        if (Regex.IsMatch(reason, @"(?i)\b(package|nuget)\b.*\b(required|dependency|reference)\b"))
+        {
+            return true;
+        }
+
+        return false;
+    }
+
     // ----------------------------------------------------------------------
     // git changed-only
     // ----------------------------------------------------------------------
@@ -2226,13 +2251,13 @@ private static string BuildRepairPlan(Report report)
             e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal)));
         AppendRequiredExampleDiagnostics(sb, report.Errors.Where(e => e.Code is "EXAMPLE_MISSING"));
         AppendDiagnostics(sb, "Sample Compilation Repairs", report.Errors.Where(e =>
-            e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_SKIP_REASON_MISSING"));
+            e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_SKIP_REASON_MISSING" or "SAMPLE_SKIP_REASON_INSUFFICIENT"));
         AppendDiagnostics(sb, "Other Errors", report.Errors.Where(e =>
             e.Code is not "AGENTS_BLOCK_MISSING" &&
             !e.Code.StartsWith("NAMESPACE_", StringComparison.Ordinal) &&
             !e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal) &&
             e.Code is not "EXAMPLE_MISSING" &&
-            e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_SKIP_REASON_MISSING"));
+            e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_SKIP_REASON_MISSING" and not "SAMPLE_SKIP_REASON_INSUFFICIENT"));
         AppendDiagnostics(sb, "Warnings", report.Warnings);
 
         sb.AppendLine("## Completion Checklist");
@@ -2308,7 +2333,7 @@ private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerab
             var message = EscapeTable(diagnostic.Message);
             var action = diagnostic.Message.Contains("Public non-abstraction type", StringComparison.Ordinal)
                 ? "Create or update the per-type UID overwrite file, include it in build.overwrite, add a compiling Examples section, then rerun validation."
-                : "Add a compiling Examples section that explicitly calls the extension method, then rerun validation.";
+                : "Add a compiling Examples section on the declaring extension class or namespace page that explicitly calls the extension method, then rerun validation.";
             sb.AppendLine($"| {ns} | `{path}` | `EXAMPLE_MISSING` | {EscapeTable(action)} {message} |");
         }
 

From f8cac99b8d08710b14090162efd1e0028bcbdf1c Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Tue, 9 Jun 2026 02:35:08 +0200
Subject: [PATCH 26/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20discover=20markdown?=
 =?UTF-8?q?=20from=20docfx=20config=20instead=20of=20scanning=20repo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refactor DiscoverMarkdown() to parse docfx.json and enumerate Markdown files from configured build.content and build.overwrite inputs instead of blindly scanning the workspace. Prevents unrelated repository Markdown (README.md, CHANGELOG.md) from being treated as DocFX overwrite content. Add PathsEqual() helper for consistent path comparison. Update namespace-page validation to trigger revalidation when docfx.json changes. Add DOCFX_MARKDOWN_DISCOVERY_SKIPPED warning when config has no inputs and docfx.json is at repo root. Include two new evaluation test cases for configuration-aware discovery behavior.
---
 README.md                                   |   4 +-
 skills/dotnet-docfx-digest/evals/evals.json |  22 ++
 skills/dotnet-docfx-digest/scripts/docfx.cs | 276 +++++++++++++++++++-
 3 files changed, 290 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index e504b46..98ee554 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, existing overwrite files, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, curated fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` example validation scoped to affected APIs instead of skipping it wholesale, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, curated fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` namespace-page and example validation scoped to affected docs/APIs while revalidating when `docfx.json` changes, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -540,7 +540,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
-- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; concrete-type examples are tracked through an explicit inventory and created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace-only overwrite globs must be widened to include required API files, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics are fixed or exact blockers are reported,
+- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace-only overwrite globs must be widened to include required API files, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics are fixed or exact blockers are reported,
 - **Complementary namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need curated fly-ins, type-family context, extension-method group explanations, availability, and pointers to representative type pages,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 38066f4..99ee560 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -186,6 +186,28 @@
         "Keeps or improves the namespace page as a curated overview rather than reducing it to a generic sentence and table",
         "Reruns scripts/docfx.cs --json and treats `SAMPLE_SKIP_REASON_INSUFFICIENT`, `SAMPLE_COMPILE_FAILED`, and `EXAMPLE_MISSING` as blocking diagnostics"
       ]
+    },
+    {
+      "id": 15,
+      "prompt": "Run dotnet-docfx-digest validation on a .NET repository where `docfx.json` lives at the repository root. The DocFX config includes only `.docfx/api/**/*.md` in `build.overwrite`, but the repository also has `README.md` and `CHANGELOG.md` files with YAML front matter UIDs that happen to match public API targets.",
+      "expected_output": "Agent relies on scripts/docfx.cs resolving Markdown from configured DocFX `build.content` and `build.overwrite` inputs instead of treating every repository Markdown file as overwrite content. Unrelated root Markdown files do not satisfy required example checks, so missing per-type or extension examples still surface as `EXAMPLE_MISSING` diagnostics.",
+      "expectations": [
+        "Does not treat the repository root as the Markdown scan scope merely because `docfx.json` is at the root",
+        "Uses configured DocFX Markdown inputs such as `.docfx/api/**/*.md` as the overwrite discovery scope",
+        "Does not allow README.md or CHANGELOG.md front matter to satisfy required examples unless those files are included by DocFX config",
+        "Still reports `EXAMPLE_MISSING` for public API targets whose configured overwrite files lack examples"
+      ]
+    },
+    {
+      "id": 16,
+      "prompt": "Run dotnet-docfx-digest validation with `--changed-only` after I changed only `docfx.json` to widen `build.overwrite` from namespace pages to per-type files. Existing namespace pages still contain stale Extension Members content, but the namespace page files themselves are not changed.",
+      "expected_output": "Agent runs scripts/docfx.cs with `--changed-only` and still revalidates namespace pages when `docfx.json` changes, because DocFX config changes can change which overwrite files and namespace pages participate in the documentation build. Stale namespace-page diagnostics are surfaced instead of being silently skipped.",
+      "expectations": [
+        "Treats a changed `docfx.json` as a reason to rerun namespace-page validation under `--changed-only`",
+        "Does not require the namespace Markdown file itself to be in the changed file set when DocFX config changed",
+        "Still surfaces stale namespace-page and Extension Members diagnostics after a build.overwrite glob change",
+        "Keeps required-example validation aligned with the same changed `docfx.json` trigger"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 1f45adb..5cf88ae 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -174,8 +174,8 @@ private static int Validate(Options options)
         report.Summary.RequiredExampleTargets = api.RequiredExampleTargets.Count;
         report.Summary.ExtensionMethods = api.Namespaces.Sum(n => n.ExtensionMethods.Count);
 
-        // 8. Discover DocFX Markdown files under the workspace.
-        var markdownFiles = DiscoverMarkdown(docfxWorkspace);
+        // 8. Discover DocFX Markdown files from the DocFX build inputs.
+        var markdownFiles = DiscoverMarkdown(repoRoot, docfxPath, docfxWorkspace, report);
 
         // 9-11. Validate namespace overview pages, extension tables and availability.
         foreach (var ns in api.Namespaces.OrderBy(n => n.Name, StringComparer.Ordinal))
@@ -190,7 +190,7 @@ private static int Validate(Options options)
                 continue;
             }
 
-            if (options.ChangedOnly && changedFiles is not null && !changedFiles.Contains(Path.GetFullPath(page)))
+            if (options.ChangedOnly && changedFiles is not null && !ShouldValidateNamespacePage(page, changedFiles))
             {
                 continue;
             }
@@ -514,10 +514,18 @@ private static bool IsInsideDirectory(string path, string directory)
         var fullPath = Path.GetFullPath(path).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar) +
                        Path.DirectorySeparatorChar;
         var fullDirectory = Path.GetFullPath(directory).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar) +
-                            Path.DirectorySeparatorChar;
+                             Path.DirectorySeparatorChar;
         return fullPath.StartsWith(fullDirectory, StringComparison.OrdinalIgnoreCase);
     }
 
+    private static bool PathsEqual(string left, string right)
+    {
+        return string.Equals(
+            Path.GetFullPath(left).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar),
+            Path.GetFullPath(right).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar),
+            StringComparison.OrdinalIgnoreCase);
+    }
+
     private static bool IsSafeGeneratedOutputDirectory(string path, string repoRoot)
     {
         return IsInsideDirectory(path, repoRoot) &&
@@ -532,15 +540,253 @@ private static bool ContainsAuthoredOrSourceFiles(string path)
         return patterns.Any(pattern => EnumerateFiles(path, pattern).Any());
     }
 
-    private static List<string> DiscoverMarkdown(string docfxWorkspace)
+    private static List<string> DiscoverMarkdown(string repoRoot, string docfxPath, string docfxWorkspace, Report report)
+    {
+        var configuredFiles = DiscoverMarkdownFromDocfxConfig(docfxPath, docfxWorkspace, report)
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .OrderBy(p => p, StringComparer.OrdinalIgnoreCase)
+            .ToList();
+
+        if (configuredFiles.Count > 0)
+        {
+            return configuredFiles;
+        }
+
+        if (!PathsEqual(repoRoot, docfxWorkspace))
+        {
+            return EnumerateFiles(docfxWorkspace, "*.md")
+                .Select(Path.GetFullPath)
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .OrderBy(p => p, StringComparer.OrdinalIgnoreCase)
+                .ToList();
+        }
+
+        report.Warnings.Add(new Diagnostic("DOCFX_MARKDOWN_DISCOVERY_SKIPPED", docfxPath, null,
+            "No Markdown inputs were resolved from build.content or build.overwrite, and docfx.json is at the repository root. Skipped the legacy full-repository Markdown scan to avoid treating unrelated repository Markdown as DocFX overwrite content."));
+        return new List<string>();
+    }
+
+    private static IEnumerable<string> DiscoverMarkdownFromDocfxConfig(string docfxPath, string docfxWorkspace, Report report)
+    {
+        JsonDocument doc;
+        try
+        {
+            doc = JsonDocument.Parse(File.ReadAllText(docfxPath), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+        }
+        catch (Exception ex) when (ex is IOException or JsonException)
+        {
+            report.Warnings.Add(new Diagnostic("DOCFX_MARKDOWN_DISCOVERY_FAILED", docfxPath, null,
+                $"Unable to read DocFX Markdown inputs: {ex.Message}"));
+            yield break;
+        }
+
+        using (doc)
+        {
+            if (!doc.RootElement.TryGetProperty("build", out var build) || build.ValueKind != JsonValueKind.Object)
+            {
+                yield break;
+            }
+
+            foreach (var propertyName in new[] { "content", "overwrite" })
+            {
+                if (!build.TryGetProperty(propertyName, out var entries))
+                {
+                    continue;
+                }
+
+                foreach (var file in ResolveDocfxMarkdownInputFiles(entries, docfxWorkspace))
+                {
+                    yield return file;
+                }
+            }
+        }
+    }
+
+    private static IEnumerable<string> ResolveDocfxMarkdownInputFiles(JsonElement entries, string docfxWorkspace)
     {
-        var list = new List<string>();
-        foreach (var file in EnumerateFiles(docfxWorkspace, "*.md"))
+        foreach (var entry in EnumerateDocfxFileMappingEntries(entries))
         {
-            list.Add(Path.GetFullPath(file));
+            var src = docfxWorkspace;
+            var includePatterns = new List<string>();
+            var excludePatterns = new List<string>();
+
+            if (entry.ValueKind == JsonValueKind.String)
+            {
+                includePatterns.Add(entry.GetString() ?? string.Empty);
+            }
+            else if (entry.ValueKind == JsonValueKind.Object)
+            {
+                if (entry.TryGetProperty("src", out var srcElement) &&
+                    srcElement.ValueKind == JsonValueKind.String &&
+                    !string.IsNullOrWhiteSpace(srcElement.GetString()))
+                {
+                    src = Path.GetFullPath(srcElement.GetString()!, docfxWorkspace);
+                }
+
+                if (entry.TryGetProperty("files", out var files))
+                {
+                    includePatterns.AddRange(ReadDocfxGlobPatterns(files));
+                }
+
+                if (entry.TryGetProperty("exclude", out var exclude))
+                {
+                    excludePatterns.AddRange(ReadDocfxGlobPatterns(exclude));
+                }
+            }
+
+            foreach (var file in ResolveMarkdownGlobPatterns(src, includePatterns, excludePatterns))
+            {
+                yield return file;
+            }
         }
+    }
 
-        return list;
+    private static IEnumerable<JsonElement> EnumerateDocfxFileMappingEntries(JsonElement entries)
+    {
+        if (entries.ValueKind == JsonValueKind.Array)
+        {
+            foreach (var entry in entries.EnumerateArray())
+            {
+                yield return entry;
+            }
+        }
+        else
+        {
+            yield return entries;
+        }
+    }
+
+    private static IEnumerable<string> ReadDocfxGlobPatterns(JsonElement element)
+    {
+        if (element.ValueKind == JsonValueKind.String)
+        {
+            yield return element.GetString() ?? string.Empty;
+            yield break;
+        }
+
+        if (element.ValueKind != JsonValueKind.Array)
+        {
+            yield break;
+        }
+
+        foreach (var item in element.EnumerateArray())
+        {
+            if (item.ValueKind == JsonValueKind.String)
+            {
+                yield return item.GetString() ?? string.Empty;
+            }
+        }
+    }
+
+    private static IEnumerable<string> ResolveMarkdownGlobPatterns(string srcRoot, IEnumerable<string> includePatterns, IEnumerable<string> excludePatterns)
+    {
+        var excludes = excludePatterns
+            .Where(IsMarkdownGlob)
+            .Select(GlobToRegex)
+            .ToList();
+
+        foreach (var pattern in includePatterns.Where(IsMarkdownGlob))
+        {
+            var searchRoot = ResolveGlobSearchRoot(srcRoot, pattern);
+            if (!Directory.Exists(searchRoot))
+            {
+                var exactFile = Path.GetFullPath(pattern, srcRoot);
+                if (File.Exists(exactFile))
+                {
+                    yield return exactFile;
+                }
+
+                continue;
+            }
+
+            var includeRegex = GlobToRegex(pattern);
+            foreach (var file in EnumerateFiles(searchRoot, "*.md"))
+            {
+                var relative = NormalizeDocfxPath(Path.GetRelativePath(srcRoot, file));
+                if (includeRegex.IsMatch(relative) && !excludes.Any(exclude => exclude.IsMatch(relative)))
+                {
+                    yield return Path.GetFullPath(file);
+                }
+            }
+        }
+    }
+
+    private static bool IsMarkdownGlob(string pattern)
+    {
+        if (string.IsNullOrWhiteSpace(pattern))
+        {
+            return false;
+        }
+
+        var extension = Path.GetExtension(pattern);
+        return string.Equals(extension, ".md", StringComparison.OrdinalIgnoreCase) ||
+               (string.IsNullOrEmpty(extension) && pattern.IndexOfAny(['*', '?', '[']) >= 0);
+    }
+
+    private static string ResolveGlobSearchRoot(string srcRoot, string pattern)
+    {
+        var normalized = NormalizeDocfxPath(pattern);
+        var wildcardIndex = normalized.IndexOfAny(['*', '?', '[']);
+        if (wildcardIndex < 0)
+        {
+            var exactDirectory = Path.GetDirectoryName(Path.GetFullPath(normalized, srcRoot));
+            return string.IsNullOrWhiteSpace(exactDirectory) ? srcRoot : exactDirectory;
+        }
+
+        var prefix = normalized[..wildcardIndex];
+        var slashIndex = prefix.LastIndexOf('/');
+        if (slashIndex < 0)
+        {
+            return srcRoot;
+        }
+
+        return Path.GetFullPath(prefix[..slashIndex], srcRoot);
+    }
+
+    private static Regex GlobToRegex(string pattern)
+    {
+        var normalized = NormalizeDocfxPath(pattern);
+        var sb = new StringBuilder("^");
+        for (var i = 0; i < normalized.Length; i++)
+        {
+            var c = normalized[i];
+            if (c == '*')
+            {
+                if (i + 1 < normalized.Length && normalized[i + 1] == '*')
+                {
+                    i++;
+                    if (i + 1 < normalized.Length && normalized[i + 1] == '/')
+                    {
+                        i++;
+                        sb.Append("(?:.*/)?");
+                    }
+                    else
+                    {
+                        sb.Append(".*");
+                    }
+                }
+                else
+                {
+                    sb.Append("[^/]*");
+                }
+
+                continue;
+            }
+
+            sb.Append(c == '?' ? "[^/]" : Regex.Escape(c.ToString()));
+        }
+
+        sb.Append('$');
+        return new Regex(sb.ToString(), RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
+    }
+
+    private static string NormalizeDocfxPath(string path)
+    {
+        return path.Replace(Path.DirectorySeparatorChar, '/').Replace(Path.AltDirectorySeparatorChar, '/');
     }
 
     private static IEnumerable<string> EnumerateFiles(string root, string pattern)
@@ -1627,6 +1873,11 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
         }
     }
 
+    private static bool ShouldValidateNamespacePage(string page, HashSet<string> changedFiles)
+    {
+        return changedFiles.Contains(Path.GetFullPath(page)) || changedFiles.Any(IsChangedDocfxConfig);
+    }
+
     private static bool ShouldValidateRequiredExampleTarget(ApiTargetInfo target, HashSet<string> changedFiles)
     {
         foreach (var changedFile in changedFiles)
@@ -1642,7 +1893,7 @@ private static bool ShouldValidateRequiredExampleTarget(ApiTargetInfo target, Ha
 
     private static bool IsChangedExampleCandidateFile(string path, ApiTargetInfo target)
     {
-        if (string.Equals(Path.GetFileName(path), "docfx.json", StringComparison.OrdinalIgnoreCase))
+        if (IsChangedDocfxConfig(path))
         {
             return true;
         }
@@ -1663,6 +1914,11 @@ private static bool IsChangedExampleCandidateFile(string path, ApiTargetInfo tar
                string.Equals(stem, target.DeclaringTypeUid, StringComparison.Ordinal);
     }
 
+    private static bool IsChangedDocfxConfig(string path)
+    {
+        return string.Equals(Path.GetFileName(path), "docfx.json", StringComparison.OrdinalIgnoreCase);
+    }
+
     private static bool ChangedSourceTouchesTarget(string path, ApiTargetInfo target)
     {
         if (!string.Equals(Path.GetExtension(path), ".cs", StringComparison.OrdinalIgnoreCase))

From f7f486f7bb52230e7e2984cd6ed4929d485444c3 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Tue, 9 Jun 2026 17:20:01 +0200
Subject: [PATCH 27/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20guidance=20for=20clarity?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clarified DocFX YAML front matter requirements and property mappings for type examples and extension-method examples. Added explicit guidance on using the \xample\ property array and prohibited hash-suffix filenames in overwrite file paths. Improved inline documentation to prevent template and API member suppression when using managed reference pages.
---
 skills/dotnet-docfx-digest/SKILL.md           | 42 +++++++++++++++----
 .../references/docfx-overwrite-files.md       | 26 +++++++++++-
 2 files changed, 59 insertions(+), 9 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 5f686c3..fe0f347 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -69,7 +69,7 @@ Before editing examples, build a small example inventory from validator output a
 
 For every public non-abstraction type, the required example location is a type UID overwrite section. In Codebelt repositories, default to a separate file named `.docfx/api/{TypeUid}.md`. For example, when the missing type is `ApplicationHostFactory`, create `.docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or the exact UID path reported by the validator. Do not put the only example in `.docfx/api/namespaces/*.md`, because that improves the namespace page while leaving the generated type page incomplete.
 
-For public extension methods, the inventory must name the method and the section that demonstrates it. Prefer a readable overwrite file for the declaring extension class UID, or the namespace page when that is the existing extension-method documentation surface. Method UIDs can contain signatures, generic parameters, hashes, or URL-encoded characters, so do not create separate encoded method-UID filenames such as `MyExtensions.%3CT%3E...md` by default. Use a method UID section only when generated metadata confirms the UID and the section can live in a readable existing or declaring-class overwrite file. The example must explicitly call the extension method.
+For public extension methods, the inventory must name the method and the section that demonstrates it. Prefer a readable overwrite file for the declaring extension class UID, or the namespace page when that is the existing extension-method documentation surface. Method UIDs can contain signatures, generic parameters, hashes, or URL-encoded characters — **never create filenames that mirror these synthetic UIDs** (e.g., `MyExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md` or `MyExtensions.%3CT%3E...md`). Always use the declaring extension class UID in front matter and keep the file at the readable class path. See the "Hash-Suffix Filenames Are Prohibited" section. The example must explicitly call the extension method.
 
 Do not mark the inventory item complete until all of these are true:
 
@@ -661,11 +661,20 @@ Remove the `Extension Members` section when the namespace has no public extensio
 
 ## Type Example Template
 
-Use this shape for public non-abstraction type examples. Put this on the generated type page/overwrite section for the type `uid`; for a public `Class1`, the example belongs on the `Class1` API page, not only on the namespace page. When no type overwrite file exists yet, create a separate per-type file such as `.docfx/api/X.Y.Z.Class1.md` and ensure `build.overwrite` includes that file.
+Use this shape for public non-abstraction type examples. The overwrite file **must** begin with YAML front matter that maps the body to the `example` property using `example:\n- *content`. This maps the Markdown body to the first slot in the `example` array, which DocFX renders as the "Examples" section **alongside** the auto-generated content (constructors, methods, etc.).
 
-````markdown
-### Examples
+**Critical**: Do NOT use `summary: *content` and do NOT omit the property mapping. Without `example:\n- *content`, the Markdown body maps to the `conceptual` property. In managed reference pages this suppresses the auto-generated API members, leaving only the custom content on the rendered page.
+
+**Do not include a `### Examples` heading inside the body.** DocFX renders the "Examples" section header automatically from the `example` property; adding one manually creates a redundant nested heading.
+
+Put this on the generated type page/overwrite section for the type `uid`; for a public `Class1`, the example belongs on the `Class1` API page, not only on the namespace page. When no type overwrite file exists yet, create a separate per-type file such as `.docfx/api/X.Y.Z.Class1.md` and ensure `build.overwrite` includes that file.
 
+````markdown
+---
+uid: X.Y.Z.MyType
+example:
+- *content
+---
 The following example shows how to use `MyType` in a consuming application.
 
 ```csharp
@@ -680,11 +689,14 @@ The sample must compile. Do not include `using` directives for namespaces that d
 
 ## Extension Method Example Template
 
-Use this shape for extension-method examples:
+Use this shape for extension-method examples. Apply the same YAML front matter rule as type examples: use `example:\n- *content` so the body maps to the `example` property and not to `conceptual`. Do not include a `### Examples` heading in the body.
 
 ````markdown
-### Examples
-
+---
+uid: X.Y.Z.MyExtensions
+example:
+- *content
+---
 The following example shows how to call `NormalizeLineEndings` on a string.
 
 ```csharp
@@ -698,7 +710,21 @@ Console.WriteLine(normalized);
 
 The namespace containing the extension method must be imported. The sample must compile in a consuming project.
 
-For generic extension methods or methods whose generated DocFX UID contains synthetic fragments such as `<G>$...`, `%3C...%3E`, hashes, or signature encodings, keep the example in a readable file such as `.docfx/api/X.Y.Z.EndpointConventionBuilderExtensions.md` or the namespace page. Do not mirror the synthetic method UID in the filename.
+## Hash-Suffix Filenames Are Prohibited
+
+DocFX generates synthetic UIDs for generic or overloaded extension methods that contain hash fragments, encoding characters, or computed suffixes. These UIDs look like:
+
+```
+Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F
+Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.%3CT%3EWithResponseNegotiator...
+```
+
+**Never create an overwrite file whose name mirrors such a synthetic UID.** That means never creating filenames such as:
+
+- `EndpointConventionBuilderExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md`
+- `EndpointConventionBuilderExtensions.%3CT%3E....md`
+
+DocFX resolves overwrites by the `uid` value in front matter, not by filename. Place the extension method example in the **declaring extension class** overwrite file (e.g., `.docfx/api/X.Y.Z.EndpointConventionBuilderExtensions.md`) or the namespace page, and use the class or namespace UID in front matter. If a validator reports a hash-suffix method UID, document that method's example in the declaring class file using the class UID — never create a per-method file with the encoded or hashed UID as the filename.
 
 ## Verification Checklist
 
diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
index 603d1d4..bc675b0 100644
--- a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -23,7 +23,31 @@ summary: *content
 The `X.Y.Z` namespace contains types that ...
 ```
 
-If `*content` is not used, DocFX assigns the Markdown body to the default conceptual content property. Prefer `summary: *content` for namespace fly-ins and other summary replacements that should flow into generated API pages.
+If `*content` is not used, DocFX assigns the Markdown body to the `conceptual` property. **Do not rely on this default for managed reference (API) pages.** When `conceptual` is set on a managed reference page, some DocFX templates suppress the auto-generated member tables (constructors, methods, properties), leaving only the custom content visible. Always use an explicit property mapping.
+
+For **type-page and extension-method examples**, use the `example` array property instead of `summary`:
+
+```markdown
+---
+uid: X.Y.Z.MyType
+example:
+- *content
+---
+The following example shows how to use `MyType`.
+
+```csharp
+using X.Y.Z;
+
+var value = new MyType();
+Console.WriteLine(value);
+```
+```
+
+`example: - *content` maps the Markdown body to the first slot of the `example` string array. DocFX renders this as the "Examples" section on the type page **alongside** the auto-generated constructors, methods, and other members — it does not replace them. The `example` property has **Replace** overwrite behavior, so setting it via an overwrite replaces any example already present in generated metadata.
+
+Do **not** include a `### Examples` heading in the body. DocFX adds the section header automatically from the template.
+
+Do **not** use `summary: *content` for type example files. That replaces only the summary text and does nothing to add a visible Examples section to the page.
 
 DocFX applies overwrite models by `uid`. If the same `uid` appears more than once in one overwrite file, later sections in that same file override earlier sections. Across different overwrite files, ordering is not deterministic, so keep competing sections for the same `uid` together or consolidate them.
 

From 11f255a1da7a2cf82b3ad2ba7cc59ab625d5fcea Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Tue, 9 Jun 2026 17:24:50 +0200
Subject: [PATCH 28/88] =?UTF-8?q?=F0=9F=94=A7=20fix=20git=20diff=20command?=
 =?UTF-8?q?=20to=20include=20deleted=20files=20in=20docfx=20validator?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 5cf88ae..83ab1b3 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -2237,7 +2237,7 @@ private static bool IsInsufficientSkipReason(string reason)
             return null;
         }
 
-        var diff = RunProcess("git", "diff --name-only --diff-filter=ACMRTUXB HEAD", repoRoot);
+        var diff = RunProcess("git", "diff --name-only --diff-filter=ACMRTUXBD HEAD", repoRoot);
         if (diff.ExitCode != 0)
         {
             return null;

From f319be010ce27dd70a06d55b97b46b795c7e01cc Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Tue, 9 Jun 2026 23:10:04 +0200
Subject: [PATCH 29/88] =?UTF-8?q?=F0=9F=93=9A=20Improve=20namespace=20docu?=
 =?UTF-8?q?mentation=20guidance=20in=20dotnet-docfx-digest?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                   |   4 +-
 skills/dotnet-docfx-digest/SKILL.md         | 111 +++++++++++++++++---
 skills/dotnet-docfx-digest/evals/evals.json |  12 +++
 3 files changed, 111 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 98ee554..57adab2 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, curated fly-in, availability), `Extension Members` tables, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` namespace-page and example validation scoped to affected docs/APIs while revalidating when `docfx.json` changes, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` namespace-page and example validation scoped to affected docs/APIs while revalidating when `docfx.json` changes, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -541,7 +541,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
 - **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace-only overwrite globs must be widened to include required API files, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics are fixed or exact blockers are reported,
-- **Complementary namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need curated fly-ins, type-family context, extension-method group explanations, availability, and pointers to representative type pages,
+- **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index fe0f347..47ba4bb 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -1,14 +1,14 @@
 ---
 name: dotnet-docfx-digest
 description: >
-  Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including repo-wide no-input audits, namespace overview pages, extension-member documentation, overwrite files, examples, availability notes, AGENTS.md maintenance, and verification. Use when the user asks to document a .NET API, create or update DocFX documentation, write namespace overview pages, add extension-method tables, update XML documentation comments, add API examples, maintain DocFX overwrite files, or verify documentation builds. Treat requests like "use dotnet-docfx-digest", "update the DocFX docs", "complete missing documentation", "create namespace pages", "add examples for this type", "update the extension members table", or "verify the documentation builds" as automatic triggers. Also use whenever public .NET API surface changes and documentation needs to stay aligned with source code.
+  Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including repo-wide no-input audits, concept-led namespace overview pages, purpose-first type/member summaries, extension-member documentation, overwrite files, examples, availability notes, AGENTS.md maintenance, and verification. Use when the user asks to document a .NET API, create or update DocFX documentation, write namespace overview pages, improve API summaries, add extension-method tables, update XML documentation comments, add API examples, maintain DocFX overwrite files, or verify documentation builds. Treat requests like "use dotnet-docfx-digest", "update the DocFX docs", "complete missing documentation", "create namespace pages", "improve these API summaries", "add examples for this type", "update the extension members table", or "verify the documentation builds" as automatic triggers. Also use whenever public .NET API surface changes and documentation needs to stay aligned with source code.
 ---
 
 # .NET DocFX Digest Steward
 
 ## Description
 
-Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including namespace overview pages, extension-member documentation, overwrite files, examples, availability notes, and verification. Preserve manual edits, document public API only, require buildable copy/paste-ready examples for concrete APIs, and keep documentation aligned with actual source code and tests.
+Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including concept-led namespace overview pages, purpose-first type/member summaries, extension-member documentation, overwrite files, examples, availability notes, and verification. Preserve manual edits, document public API only, require buildable copy/paste-ready examples for concrete APIs, and keep documentation aligned with actual source code and tests.
 
 ## Activation Requirements
 
@@ -52,11 +52,60 @@ The completion loop is the guard against the common failure where an agent finis
 Do not trade one documentation surface for the other. Namespace pages and per-type pages have different jobs, and both must remain useful:
 
 - Namespace pages explain the package or namespace shape: what problem the namespace solves, when to use it, important type families, extension-method groups, availability, and links or references to representative type pages.
-- Per-type pages explain how to use a specific public concrete type with copy/paste-ready examples.
+- Per-type pages explain what a specific public concrete type is for, when a developer would reach for it, and how to use it with copy/paste-ready examples.
 - Extension-method examples normally live on the declaring extension class page or the namespace page, but the namespace page must still read like curated API documentation, not a dumping ground for examples.
 
 When per-type examples are added, revisit the related namespace page and keep its fly-in well-versed and developer-friendly. Moving examples out of the namespace page must not leave the namespace page as a generic sentence plus table. Preserve or improve the curated namespace overview that helps readers choose the right type before they drill into generated type pages.
 
+## Conceptual Orientation
+
+Namespace pages, type summaries, and member summaries should orient a developer to purpose, not just inventory API shape. Use an inverted-pyramid writing order:
+
+1. Lead with the biggest idea: what problem this namespace, type, or member solves, or what outcome it enables.
+2. Follow with when a developer would use it in normal work.
+3. Give quick orientation such as "If you're trying to do X, start with Y" when an entry-point type, option type, or extension method helps readers choose where to go next.
+4. Then add structural detail such as important type families, representative members, or constraints.
+
+Write for a developer who is new to the domain, not for someone who already knows why the API exists. A strong summary should answer "why would I care?" before it answers "what names live here?"
+
+Avoid filing-cabinet labels such as "contains types and extension methods for..." or generic blurbs such as "represents options..." and "adds services..." when they are not followed by concrete purpose. Those phrases are acceptable only when the rest of the sentence explains the real job of the API.
+
+Bad namespace summary:
+
+```markdown
+The `Acme.OpenApi.ModelContextProtocol` namespace contains types and extension methods for MCP integration.
+```
+
+Better namespace summary:
+
+```markdown
+The `Acme.OpenApi.ModelContextProtocol` namespace bridges Model Context Protocol servers with OpenAPI documentation. Use it when you want MCP-enabled services to stay discoverable through standard Swagger/OpenAPI tooling. If you're wiring the integration into an ASP.NET Core app, start with `AddMcpServer`.
+```
+
+Bad type/member summaries:
+
+```csharp
+/// <summary>
+/// Represents options for the server.
+/// </summary>
+
+/// <summary>
+/// Adds MCP server services.
+/// </summary>
+```
+
+Better type/member summaries:
+
+```csharp
+/// <summary>
+/// Configures how the MCP server is exposed through the application's OpenAPI pipeline.
+/// </summary>
+
+/// <summary>
+/// Registers the MCP/OpenAPI integration during service configuration so MCP endpoints appear in generated API documentation.
+/// </summary>
+```
+
 ## Type-Page Example Gate
 
 Before editing examples, build a small example inventory from validator output and source evidence. This inventory is the task queue, not a summary for the final response. Each required item should have this shape:
@@ -351,15 +400,16 @@ summary: *content
 
 The page must provide a developer-friendly fly-in explaining what the namespace is for. The fly-in should be similar in usefulness and tone to Microsoft .NET API documentation:
 
-- Start with what the namespace contains.
-- Explain the developer problem it solves.
+- Lead with the developer problem or outcome the namespace exists for.
 - Explain when to use it.
+- Give quick orientation for a newcomer, such as "If you're trying to do X, start with Y."
 - Mention important concepts or type families.
 - Mention representative concrete types or extension-method groups when that helps readers choose where to go next.
 - Link or refer to type pages that carry detailed examples when examples are intentionally kept out of the namespace page.
 - Avoid marketing language.
-- Avoid restating type names without explaining purpose.
+- Avoid inventory-only wording that merely restates type names without explaining purpose.
 - Keep the explanation accurate to the public API.
+- Use the inverted-pyramid structure from the Conceptual Orientation section before falling back to structural detail.
 
 Minimum namespace overview structure:
 
@@ -368,7 +418,9 @@ Minimum namespace overview structure:
 uid: X.Y.Z
 summary: *content
 ---
-The `X.Y.Z` namespace contains types that ...
+The `X.Y.Z` namespace helps you ...
+Use it when ...
+If you're trying to ..., start with `PrimaryType` or `PrimaryExtensions`.
 
 [!INCLUDE [availability-default](../../includes/availability-default.md)]
 ```
@@ -503,6 +555,8 @@ XML documentation should describe:
 - Nullability expectations,
 - Thread-safety or lifecycle behavior when relevant.
 
+The opening summary sentence should explain the API's job in consumer terms. Lead with purpose and likely use, especially for entry-point extension methods, option types, factories, builders, and orchestration types. Prefer "what this enables and when to call it" over empty structural labels.
+
 Do not use empty boilerplate summaries.
 
 Bad:
@@ -521,6 +575,30 @@ Better:
 /// </summary>
 ```
 
+Bad:
+
+```csharp
+/// <summary>
+/// Represents options for the server.
+/// </summary>
+
+/// <summary>
+/// Adds MCP server services.
+/// </summary>
+```
+
+Better:
+
+```csharp
+/// <summary>
+/// Configures how the MCP server is exposed through the application's OpenAPI pipeline.
+/// </summary>
+
+/// <summary>
+/// Registers the MCP/OpenAPI integration during service configuration so MCP endpoints appear in generated API documentation.
+/// </summary>
+```
+
 ## Preservation Rules
 
 Manual edits must be preserved.
@@ -564,7 +642,8 @@ Prefer:
 - Accurate terminology,
 - Small complete samples,
 - Links to related APIs when useful,
-- Namespace-level fly-ins that explain purpose.
+- Namespace-level fly-ins that explain purpose,
+- Purpose-first type/member summaries that explain why a developer would use the API.
 
 Avoid:
 
@@ -577,7 +656,9 @@ Avoid:
 - Incomplete snippets,
 - Unverified claims,
 - Duplicating generated API signatures manually,
-- Restating the namespace name without explaining its purpose.
+- Restating the namespace name without explaining its purpose,
+- Filing-cabinet summaries that only say what a namespace or type contains,
+- Generic verbs like "represents", "provides", or "adds" when they do not explain the API's real role.
 
 ## Documentation Workflow
 
@@ -593,8 +674,8 @@ When the user names a changed API or namespace:
 8. Locate availability include files.
 9. Locate relevant tests that demonstrate the API.
 10. Convert test usage into real-life documentation examples.
-11. Update XML documentation where needed.
-12. Update or create namespace overview pages.
+11. Update XML documentation where needed, especially purpose-first type/member summaries for public entry points and high-traffic APIs.
+12. Update or create namespace overview pages with conceptual orientation and start-here cues.
 13. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
 14. Update extension-member tables.
 15. Update or create overwrite files, including type-page example sections for public non-abstraction types and example sections for public extension methods.
@@ -620,7 +701,7 @@ When no specific API or namespace is named:
 8. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
 9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
 10. Determine every public non-abstraction type and every public extension method that requires an example.
-11. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins.
+11. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins that lead with purpose, use case, and start-here guidance.
 12. Audit related namespace pages together so fixes are consistent across the public API family.
 13. Add or repair `Extension Members` tables for namespaces with public extension methods.
 14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
@@ -646,7 +727,9 @@ Use this template when creating a new namespace overview page:
 uid: X.Y.Z
 summary: *content
 ---
-The `X.Y.Z` namespace contains types that ...
+The `X.Y.Z` namespace helps you ...
+Use it when ...
+If you're trying to ..., start with `PrimaryType` or `PrimaryExtensions`.
 
 [!INCLUDE [availability-default](../../includes/availability-default.md)]
 
@@ -657,7 +740,7 @@ The `X.Y.Z` namespace contains types that ...
 |String|⬇️|`ExampleMethod`|
 ```
 
-Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path based on the actual file location.
+Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path based on the actual file location. Mirror the same purpose-first narrative in any nearby type summaries or entry-point member summaries you touch so the namespace page and generated API pages orient readers consistently.
 
 ## Type Example Template
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 99ee560..a688704 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -208,6 +208,18 @@
         "Still surfaces stale namespace-page and Extension Members diagnostics after a build.overwrite glob change",
         "Keeps required-example validation aligned with the same changed `docfx.json` trigger"
       ]
+    },
+    {
+      "id": 17,
+      "prompt": "The `Acme.OpenApi.ModelContextProtocol` namespace page currently says `Contains types and extension methods for MCP integration.` The public type `McpServerOptions` says `Represents options for the server.` The extension method `AddMcpServer(this IServiceCollection services)` says `Adds MCP server services.` Use dotnet-docfx-digest to rewrite the documentation so a developer new to this domain immediately understands what each API is for.",
+      "expected_output": "Agent rewrites the namespace overview and affected API summaries with conceptual orientation instead of structural inventory. The namespace fly-in leads with the problem solved, when to use the namespace, and a start-here cue such as AddMcpServer. The type and member summaries explain the role and likely use of the API in consumer terms, while keeping every claim grounded in the real public API and still following the normal script-and-verification workflow.",
+      "expectations": [
+        "Rewrites the namespace overview so it leads with the problem or outcome the namespace enables instead of only saying what it contains",
+        "Explains when a developer would use the namespace and includes a newcomer-oriented start-here cue that points to a representative type or entry-point member",
+        "Rewrites type or member summaries so they explain the API's role and likely use instead of generic structural labels such as `Represents options` or `Adds services`",
+        "Keeps the summaries grounded in actual public API behavior rather than inventing capabilities or marketing language",
+        "Applies the same conceptual-orientation pattern consistently across the namespace page and the touched API summaries"
+      ]
     }
   ]
 }

From a4c3b3fc6d5badb9d787fe5e21fe4647623dced9 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 00:20:55 +0200
Subject: [PATCH 30/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refine=20docfx=20pro?=
 =?UTF-8?q?ject=20discovery=20logic?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Locate projects within src/ path to exclude tools/, scripts/, and root folders from API documentation discovery. Refine git diff filter to exclude deleted files per current repository state.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 83ab1b3..67769e1 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -978,12 +978,16 @@ private static bool HasRootStrongNameKey(string repoRoot)
     private static List<ProjectInfo> DiscoverProjects(string repoRoot)
     {
         var projects = new List<ProjectInfo>();
-        foreach (var proj in EnumerateFiles(repoRoot, "*.csproj"))
+        var srcPath = Path.Combine(repoRoot, "src");
+        if (!Directory.Exists(srcPath))
+        {
+            return projects;
+        }
+        foreach (var proj in EnumerateFiles(srcPath, "*.csproj"))
         {
             var info = ReadProject(proj);
             projects.Add(info);
         }
-
         return projects;
     }
 
@@ -2237,7 +2241,7 @@ private static bool IsInsufficientSkipReason(string reason)
             return null;
         }
 
-        var diff = RunProcess("git", "diff --name-only --diff-filter=ACMRTUXBD HEAD", repoRoot);
+        var diff = RunProcess("git", "diff --name-only --diff-filter=ACMRTUXB HEAD", repoRoot);
         if (diff.ExitCode != 0)
         {
             return null;

From c52957ade7c1786ab334fee506ed3bf518c55fea Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 00:21:03 +0200
Subject: [PATCH 31/88] =?UTF-8?q?=F0=9F=94=A7=20refine=20docfx=20configura?=
 =?UTF-8?q?tion=20in=20library=20scaffold?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restrict API documentation source to src/ folder via docfx.json metadata source setting. Update build configuration to process namespace overwrites separately from content files, preventing API docs from being emitted as conceptual pages. Add corresponding validation expectations to evals.
---
 .../dotnet-new-lib-slnx/assets/library/.docfx/docfx.json | 9 ++++++---
 skills/dotnet-new-lib-slnx/evals/evals.json              | 2 ++
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json b/skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json
index e1cc683..78feea6 100644
--- a/skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json
+++ b/skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json
@@ -21,13 +21,15 @@
       {
         "files": [
           "api/**/*.yml",
-          "api/**/*.md",
+          "packages/**/*.md",
           "toc.yml",
           "*.md"
         ],
         "exclude": [
           "bin/**",
-          "obj/**"
+          "obj/**",
+          "wwwroot/**",
+          "api/namespaces/**"
         ]
       }
     ],
@@ -59,9 +61,10 @@
     "overwrite": [
       {
         "files": [
-          "api/namespaces/**.md"
+          "api/namespaces/**/*.md"
         ],
         "exclude": [
+          "bin/**",
           "obj/**",
           "wwwroot/**"
         ]
diff --git a/skills/dotnet-new-lib-slnx/evals/evals.json b/skills/dotnet-new-lib-slnx/evals/evals.json
index ac6e794..9d8b110 100644
--- a/skills/dotnet-new-lib-slnx/evals/evals.json
+++ b/skills/dotnet-new-lib-slnx/evals/evals.json
@@ -10,6 +10,8 @@
         "Offers all active non-preview LTS and STS target framework quick picks before free text",
         "Resolves package-specific version placeholders from NuGet before writing Directory.Packages.props",
         "Creates DocFX config using {DOCFX_TARGET_FRAMEWORK} rather than a hardcoded net10.0",
+        "Locks DocFX metadata source to ../src (relative to .docfx/) so ONLY code in the src folder is digested for API documentation, excluding tools/, scripts/, and other root folders",
+        "Keeps api/namespaces/**/*.md under build.overwrite and excludes api/**/*.md from build.content so API overwrites are not emitted as standalone conceptual pages",
         "Uses the current working directory as the scaffold root instead of creating a nested MyLibrary folder"
       ]
     },

From 4313207565b7df3777d8c5d49bff7283e2ca5ffd Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 01:55:42 +0200
Subject: [PATCH 32/88] =?UTF-8?q?=F0=9F=92=AC=20update=20README=20with=20d?=
 =?UTF-8?q?otnet-docfx-digest=20skill?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add dotnet-docfx-digest skill to Available Skills table in repository README per AGENTS.md sync requirements.
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 57adab2..73c04c4 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, and C# documentation samples, keeps `--changed-only` namespace-page and example validation scoped to affected docs/APIs while revalidating when `docfx.json` changes, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, requires buildable copy/paste-ready examples for concrete types in separate per-type files by default, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite inclusion diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, Codebelt namespace-folder overwrite layout (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and C# documentation samples, keeps `--changed-only` namespace-page and example validation scoped to affected docs/APIs while revalidating when `docfx.json` changes, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, and managed-reference-safe completion gates for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -540,7 +540,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
-- **Mandatory per-type overwrite examples** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in separate per-type files such as `.docfx/api/X.Y.Z.Class1.md` by default, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace-only overwrite globs must be widened to include required API files, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics are fixed or exact blockers are reported,
+- **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/namespaces/`, legacy authored `.docfx/api/*.md` overwrite files are moved into that folder instead of widening the glob to `api/**/*.md`, `api/namespaces/**/*.md` stays under `build.overwrite` only while `build.content` excludes `api/namespaces/**`, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
 - **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,

From e7049dcb6db915fce8c6caa7cfb2a765cec9780a Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 01:55:53 +0200
Subject: [PATCH 33/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20enhance=20dotnet-doc?=
 =?UTF-8?q?fx-digest=20workflow=20and=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Improve SKILL.md instructions for DocFX overwrite file sourcing and script behavior. Expand script.md reference with Git pattern guidance. Update evals with additional validation expectations. Enhance docfx.cs helper script with improved overwrite file discovery and repository path handling. Align documentation with current best practices.
---
 skills/dotnet-docfx-digest/SKILL.md           |  26 ++--
 skills/dotnet-docfx-digest/evals/evals.json   |  43 ++++--
 .../references/docfx-overwrite-files.md       |   4 +-
 .../dotnet-docfx-digest/references/scripts.md |   6 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 134 +++++++++++++++++-
 5 files changed, 177 insertions(+), 36 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 47ba4bb..ef571ce 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -40,8 +40,8 @@ Do not stop at namespace pages, extension-member tables, or a first-pass documen
 
 1. Run `docfx.cs --json` after edits and read the remaining diagnostics.
 2. If diagnostics include `EXAMPLE_MISSING`, missing namespace pages, stale extension-member tables, sample compile failures, missing availability, or overwrite inclusion problems, treat them as the next work queue rather than final notes.
-3. For every `EXAMPLE_MISSING` public non-abstraction type, create or update the type-page overwrite file for that type UID, such as `.docfx/api/ApplicationHostFactory.md`, and put the example in that file or another overwrite section that targets the type UID directly.
-4. For every required example file, verify `build.overwrite` includes the file path or a glob that reaches it. Widen namespace-only overwrite globs when needed.
+3. For every `EXAMPLE_MISSING` public non-abstraction type, create or update the type-page overwrite file for that type UID under `.docfx/api/namespaces/`, such as `.docfx/api/namespaces/ApplicationHostFactory.md`, and put the example in that file or another overwrite section that targets the type UID directly.
+4. For every required example file, verify `docfx.json` keeps `api/namespaces/**/*.md` under `build.overwrite`, excludes `api/namespaces/**` from `build.content`, and does not use `api/**/*.md` under either `content` or `overwrite`. Move legacy authored `.docfx/api/*.md` overwrite files into `.docfx/api/namespaces/` instead of widening the glob.
 5. Update the example inventory so each required public non-abstraction type and public extension method maps to the exact example file and UID.
 6. Rerun the validator and repeat the loop until required diagnostics are gone, or stop and report the exact blocker, command, exit code, and remaining diagnostic codes.
 
@@ -113,17 +113,17 @@ Before editing examples, build a small example inventory from validator output a
 ```markdown
 | UID | Kind | Required example location | Source evidence | Status |
 |---|---|---|---|---|
-| Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | ApplicationHostFactoryTest | Missing |
+| Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | ApplicationHostFactoryTest | Missing |
 ```
 
-For every public non-abstraction type, the required example location is a type UID overwrite section. In Codebelt repositories, default to a separate file named `.docfx/api/{TypeUid}.md`. For example, when the missing type is `ApplicationHostFactory`, create `.docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or the exact UID path reported by the validator. Do not put the only example in `.docfx/api/namespaces/*.md`, because that improves the namespace page while leaving the generated type page incomplete.
+For every public non-abstraction type, the required example location is a type UID overwrite section. In Codebelt repositories, keep those authored overwrite files under `.docfx/api/namespaces/` using readable filenames such as `.docfx/api/namespaces/{TypeUid}.md`. For example, when the missing type is `ApplicationHostFactory`, create `.docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or the exact UID path reported by the validator. The file may live under `api/namespaces/` while still merging into the generated type page, because the YAML front matter `uid` determines the target model. Do not put the only example on the namespace UID page, because that improves the namespace page while leaving the generated type page incomplete.
 
 For public extension methods, the inventory must name the method and the section that demonstrates it. Prefer a readable overwrite file for the declaring extension class UID, or the namespace page when that is the existing extension-method documentation surface. Method UIDs can contain signatures, generic parameters, hashes, or URL-encoded characters — **never create filenames that mirror these synthetic UIDs** (e.g., `MyExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md` or `MyExtensions.%3CT%3E...md`). Always use the declaring extension class UID in front matter and keep the file at the readable class path. See the "Hash-Suffix Filenames Are Prohibited" section. The example must explicitly call the extension method.
 
 Do not mark the inventory item complete until all of these are true:
 
 - The overwrite section targets the required type UID or an allowed extension-method location such as the declaring extension class UID or namespace UID.
-- `build.overwrite` includes the file by exact path or a glob such as `api/**/*.md`.
+- `build.overwrite` includes the file through the namespace-folder convention, normally `api/namespaces/**/*.md`, and `build.content` excludes `api/namespaces/**`.
 - The example code fence compiles or carries an explicit, justified skip marker.
 - A rerun of `docfx.cs --json` no longer reports `EXAMPLE_MISSING` for that UID.
 
@@ -273,13 +273,13 @@ Every automatically documented public non-abstraction type and every public exte
 
 Do not treat an `Extension Members` table as documentation completion. A table answers "what exists"; an example answers "how a consumer uses it." For each public extension method discovered or listed in a namespace page, create or verify an example before moving to final verification. If several related namespace pages are updated together, build an example inventory that maps every public extension method and every public non-abstraction type to the exact overwrite file and UID where its example lives.
 
-Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create a separate per-type Markdown overwrite file by default. For Codebelt repositories, the default type example file is:
+Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create a separate per-type Markdown overwrite file by default. For Codebelt repositories, keep authored API overwrite files under `.docfx/api/namespaces/`, so the default type example file is:
 
 ```text
-.docfx/api/{TypeUid}.md
+.docfx/api/namespaces/{TypeUid}.md
 ```
 
-For example, create `.docfx/api/Codebelt.Bootstrapper.ProgramRoot.md` for uid `Codebelt.Bootstrapper.ProgramRoot`. If `build.overwrite` does not include the chosen per-type file path, update `docfx.json` so the overwrite glob includes both namespace pages and per-type API overwrite files, such as `api/**/*.md`. Do not hide type examples in namespace pages because the current overwrite glob only includes namespace files.
+For example, create `.docfx/api/namespaces/Codebelt.Bootstrapper.ProgramRoot.md` for uid `Codebelt.Bootstrapper.ProgramRoot`. Keep `docfx.json` on the namespace-folder convention: `build.content` excludes `api/namespaces/**`, `build.overwrite` includes `api/namespaces/**/*.md`, and neither section uses `api/**/*.md`. If legacy authored overwrite Markdown exists directly under `.docfx/api/*.md`, move it into `.docfx/api/namespaces/` without deleting the content. Do not hide type examples on the namespace UID page.
 
 For public non-abstraction types, the example must belong to the generated type page/overwrite section for that type `uid`. For example, if `Class1` is public and not an abstraction, add an `Examples` section to the DocFX overwrite content for `Class1` so the example appears on `Class1.md` at the bottom of the generated API page. A namespace page example does not satisfy the type-page example requirement for `Class1`.
 
@@ -532,7 +532,7 @@ Do not use overwrite files to conceal inaccurate XML documentation. Correct the
 
 When the validator reports `EXAMPLE_MISSING`, create or update DocFX overwrite content for the reported UID instead of treating the missing example as a prose-only issue.
 
-When a repository has namespace overview files but no per-type overwrite files, create the per-type files. Do not treat the absence of existing type files as a signal to skip examples. For Codebelt repositories, place new type files beside generated API metadata under `.docfx/api/` and update `build.overwrite` if it currently points only at `.docfx/api/namespaces/**/*.md`.
+When a repository has namespace overview files but no type-targeting overwrite files, create the missing type files. Do not treat the absence of existing type files as a signal to skip examples. For Codebelt repositories, place new type-targeting overwrite files under `.docfx/api/namespaces/`, move legacy authored `.docfx/api/*.md` overwrite files into that folder, and keep `build.overwrite` on `.docfx/api/namespaces/**/*.md` instead of widening it to `.docfx/api/**/*.md`.
 
 ## Namespace Coverage
 
@@ -705,8 +705,8 @@ When no specific API or namespace is named:
 12. Audit related namespace pages together so fixes are consistent across the public API family.
 13. Add or repair `Extension Members` tables for namespaces with public extension methods.
 14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
-15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, using `.docfx/api/{TypeUid}.md` in Codebelt repositories unless the repo has a stronger existing convention.
-16. Ensure `build.overwrite` includes the per-type overwrite files you create; update a namespace-only overwrite glob to include API overwrite files when needed.
+15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, using `.docfx/api/namespaces/{TypeUid}.md` in Codebelt repositories unless the repo has a stronger existing convention.
+16. Ensure `docfx.json` keeps `.docfx/api/namespaces/**/*.md` under `build.overwrite` only, excludes `.docfx/api/namespaces/**` from `build.content`, and move legacy authored `.docfx/api/*.md` overwrite files into `.docfx/api/namespaces/` when needed.
 17. Create example sections for public extension methods that have no example yet.
 18. Build an example inventory that maps each required public type and extension method to its example location.
 19. Preserve manual edits and correct stale contradictions instead of replacing whole files.
@@ -750,7 +750,7 @@ Use this shape for public non-abstraction type examples. The overwrite file **mu
 
 **Do not include a `### Examples` heading inside the body.** DocFX renders the "Examples" section header automatically from the `example` property; adding one manually creates a redundant nested heading.
 
-Put this on the generated type page/overwrite section for the type `uid`; for a public `Class1`, the example belongs on the `Class1` API page, not only on the namespace page. When no type overwrite file exists yet, create a separate per-type file such as `.docfx/api/X.Y.Z.Class1.md` and ensure `build.overwrite` includes that file.
+Put this on the generated type page/overwrite section for the type `uid`; for a public `Class1`, the example belongs on the `Class1` API page, not only on the namespace page. When no type overwrite file exists yet, create a separate per-type file such as `.docfx/api/namespaces/X.Y.Z.Class1.md`. The file location stays under `api/namespaces/`, but the type `uid` still makes the content merge into the generated type page.
 
 ````markdown
 ---
@@ -807,7 +807,7 @@ Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.%3CT%3EWithRespon
 - `EndpointConventionBuilderExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md`
 - `EndpointConventionBuilderExtensions.%3CT%3E....md`
 
-DocFX resolves overwrites by the `uid` value in front matter, not by filename. Place the extension method example in the **declaring extension class** overwrite file (e.g., `.docfx/api/X.Y.Z.EndpointConventionBuilderExtensions.md`) or the namespace page, and use the class or namespace UID in front matter. If a validator reports a hash-suffix method UID, document that method's example in the declaring class file using the class UID — never create a per-method file with the encoded or hashed UID as the filename.
+DocFX resolves overwrites by the `uid` value in front matter, not by filename. Place the extension method example in the **declaring extension class** overwrite file under `.docfx/api/namespaces/` (for example, `.docfx/api/namespaces/X.Y.Z.EndpointConventionBuilderExtensions.md`) or the namespace page, and use the class or namespace UID in front matter. If a validator reports a hash-suffix method UID, document that method's example in the declaring class file using the class UID — never create a per-method file with the encoded or hashed UID as the filename.
 
 ## Verification Checklist
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index a688704..1b04969 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -77,16 +77,16 @@
     },
     {
       "id": 7,
-      "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but public non-abstraction types such as `ApplicationHostFactory` and public extension methods have no examples. The DocFX config currently has build.overwrite pointing only at .docfx/api/namespaces/**/*.md, and there are no existing per-type overwrite files.",
-      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates separate per-type DocFX overwrite files such as .docfx/api/Acme.ApplicationHostFactory.md for missing concrete-type examples, updates build.overwrite so those per-type files are included, puts type examples on the generated type page/overwrite section rather than namespace pages, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, runs the Completion Repair Loop by rerunning scripts/docfx.cs --json after edits, fixes remaining EXAMPLE_MISSING or overwrite inclusion diagnostics instead of listing them as final notes, and uses --verify-docfx-build before completion so DocFX output is generated in temp space.",
+      "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but public non-abstraction types such as `ApplicationHostFactory` and public extension methods have no examples. The DocFX config already points `build.overwrite` at `.docfx/api/namespaces/**/*.md`, but some earlier authored overwrite Markdown still lives directly under `.docfx/api/*.md`.",
+      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates or moves readable overwrite files under `.docfx/api/namespaces/` for missing concrete-type examples, keeps `api/namespaces/**/*.md` under `build.overwrite` only, keeps `api/namespaces/**` excluded from `build.content`, puts type examples on the generated type page/overwrite section rather than the namespace UID page, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, runs the Completion Repair Loop by rerunning scripts/docfx.cs --json after edits, fixes remaining EXAMPLE_MISSING or overwrite-layout diagnostics instead of listing them as final notes, and uses --verify-docfx-build before completion so DocFX output is generated in temp space.",
       "expectations": [
         "Treats namespace overview pages and Extension Members tables as insufficient when examples are missing",
-        "Creates separate per-type DocFX overwrite files for public non-abstraction type examples when no type files exist yet",
-        "Updates a namespace-only build.overwrite glob so the new per-type overwrite files are included",
+        "Creates or moves readable type-targeting DocFX overwrite files under `.docfx/api/namespaces/` for public non-abstraction type examples",
+        "Keeps `api/namespaces/**/*.md` under `build.overwrite` only and excludes `api/namespaces/**` from `build.content`",
         "Places a public ApplicationHostFactory example on the ApplicationHostFactory type page/overwrite section rather than only on the namespace page",
         "Creates or updates overwrite content for public extension method examples, or places the example on the extension class or namespace page while explicitly demonstrating the method",
         "Uses generated DocFX UIDs or verified metadata instead of inventing overwrite UIDs",
-        "Runs the Completion Repair Loop after edits by rerunning scripts/docfx.cs --json, fixing remaining EXAMPLE_MISSING and overwrite inclusion diagnostics, and updating the example inventory before claiming completion",
+        "Runs the Completion Repair Loop after edits by rerunning scripts/docfx.cs --json, fixing remaining EXAMPLE_MISSING and overwrite-layout diagnostics, and updating the example inventory before claiming completion",
         "Uses --verify-docfx-build for final DocFX build verification",
         "Compiles changed C# examples or reports the exact verification failure"
       ]
@@ -105,8 +105,8 @@
     },
     {
       "id": 9,
-      "prompt": "Use dotnet-docfx-digest on a Codebelt.Bootstrapper-style repository. During the run you create `.docfx/api/Codebelt.Bootstrapper.ProgramRoot.md` and `.docfx/api/namespaces/Codebelt.Bootstrapper.md`, then validation leaves generated DocFX metadata files beside those authored markdown files. Clean up generated artifacts before completion.",
-      "expected_output": "Agent preserves all authored Markdown overwrite and namespace files, including files created earlier in the same run, and cleans only known generated DocFX metadata or safe generated site output. It does not delete `.docfx/api/**/*.md`, does not recursively delete DocFX directories that contain Markdown or source/configuration files, uses `docfx.cs --verify-docfx-build` for temp-workspace verification, classifies any remaining `git status` paths before deletion, and leaves ambiguous cleanup candidates in place with a note instead of deleting them.",
+      "prompt": "Use dotnet-docfx-digest on a Codebelt.Bootstrapper-style repository. During the run you create `.docfx/api/namespaces/Codebelt.Bootstrapper.ProgramRoot.md` and `.docfx/api/namespaces/Codebelt.Bootstrapper.md`, then validation leaves generated DocFX metadata files beside those authored markdown files. Clean up generated artifacts before completion.",
+      "expected_output": "Agent preserves all authored Markdown overwrite and namespace files, including files created earlier in the same run, and cleans only known generated DocFX metadata or safe generated site output. It does not delete `.docfx/api/namespaces/**/*.md`, does not recursively delete DocFX directories that contain Markdown or source/configuration files, uses `docfx.cs --verify-docfx-build` for temp-workspace verification, classifies any remaining `git status` paths before deletion, and leaves ambiguous cleanup candidates in place with a note instead of deleting them.",
       "expectations": [
         "Treats newly created `.docfx/**/*.md` files as documentation deliverables rather than cleanup targets",
         "Does not run broad manual cleanup commands that delete DocFX directories by name",
@@ -162,13 +162,13 @@
     {
       "id": 13,
       "prompt": "A previous run of dotnet-docfx-digest enhanced only `.docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.md` and added examples there, but the validator still reports `EXAMPLE_MISSING` for the public concrete type `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory`. Fix the documentation gap and explain why namespace examples were insufficient.",
-      "expected_output": "Agent treats the remaining EXAMPLE_MISSING diagnostic as an unfinished work item, creates or updates `.docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` with DocFX front matter for uid `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory`, adds a buildable ApplicationHostFactory example derived from source or tests, updates build.overwrite when needed so `.docfx/api/**/*.md` files are included, reruns scripts/docfx.cs --json until the diagnostic is gone, and explains that namespace examples and Extension Members tables complement but do not replace examples on generated type pages.",
+      "expected_output": "Agent treats the remaining EXAMPLE_MISSING diagnostic as an unfinished work item, creates or updates `.docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` with DocFX front matter for uid `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory`, adds a buildable ApplicationHostFactory example derived from source or tests, keeps `.docfx/api/namespaces/**/*.md` under `build.overwrite` only, reruns scripts/docfx.cs --json until the diagnostic is gone, and explains that namespace examples and Extension Members tables complement but do not replace examples on generated type pages.",
       "expectations": [
         "Does not treat the namespace page examples as sufficient for the ApplicationHostFactory concrete type",
-        "Creates or updates the per-type overwrite file `.docfx/api/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or an equivalent file that targets the exact ApplicationHostFactory UID",
+        "Creates or updates the type-targeting overwrite file `.docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or an equivalent file that targets the exact ApplicationHostFactory UID",
         "Uses DocFX front matter with uid `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory` for the type example section",
         "Adds a realistic, copy/paste-ready C# example for ApplicationHostFactory based on actual source, tests, or public behavior",
-        "Updates build.overwrite when the existing glob only includes `.docfx/api/namespaces/**/*.md`",
+        "Keeps `api/namespaces/**/*.md` under `build.overwrite` only and does not widen it to `api/**/*.md`",
         "Reruns scripts/docfx.cs --json after the edit and treats any remaining EXAMPLE_MISSING diagnostic as blocking completion",
         "Explains that namespace overview examples and Extension Members tables are complementary surfaces, not substitutes for type-page examples"
       ]
@@ -176,7 +176,7 @@
     {
       "id": 14,
       "prompt": "Use dotnet-docfx-digest on a Carter-style repository where `EndpointConventionBuilderExtensions` has generic extension methods whose generated DocFX method UIDs look like `Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.<G>$6D0D8037DBBD61D10816ECA5F93B896F`. The previous run created `.docfx/api/Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.%3CG%3E%246D0D8037DBBD61D10816ECA5F93B896F.md`, added `// dotnet-docfx-digest:skip-compile - Full example requires Cuemon.Extensions.AspNetCore.Text.Yaml package`, and left the namespace page as a thin table. Repair the docs.",
-      "expected_output": "Agent removes or avoids the encoded/hash-like method UID filename, places extension-method examples in a readable declaring-class overwrite file such as `.docfx/api/Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.md` or the namespace page, does not use a package-requirement skip marker as a compile escape hatch, either makes the sample compile or reports a precise deterministic blocker, and restores the namespace page as a curated overview with developer-friendly purpose, type-family context, extension-method groups, availability, and pointers to detailed examples.",
+      "expected_output": "Agent removes or avoids the encoded/hash-like method UID filename, places extension-method examples in a readable declaring-class overwrite file such as `.docfx/api/namespaces/Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.md` or the namespace page, does not use a package-requirement skip marker as a compile escape hatch, either makes the sample compile or reports a precise deterministic blocker, and restores the namespace page as a curated overview with developer-friendly purpose, type-family context, extension-method groups, availability, and pointers to detailed examples.",
       "expectations": [
         "Does not create or keep URL-encoded/hash-like method UID filenames for generic extension methods such as `%3CG%3E%24...`",
         "Uses a readable declaring extension class overwrite file or namespace page for extension-method examples",
@@ -189,26 +189,39 @@
     },
     {
       "id": 15,
-      "prompt": "Run dotnet-docfx-digest validation on a .NET repository where `docfx.json` lives at the repository root. The DocFX config includes only `.docfx/api/**/*.md` in `build.overwrite`, but the repository also has `README.md` and `CHANGELOG.md` files with YAML front matter UIDs that happen to match public API targets.",
+      "prompt": "Run dotnet-docfx-digest validation on a .NET repository where `docfx.json` lives at the repository root. The DocFX config includes only `.docfx/api/namespaces/**/*.md` in `build.overwrite`, but the repository also has `README.md` and `CHANGELOG.md` files with YAML front matter UIDs that happen to match public API targets.",
       "expected_output": "Agent relies on scripts/docfx.cs resolving Markdown from configured DocFX `build.content` and `build.overwrite` inputs instead of treating every repository Markdown file as overwrite content. Unrelated root Markdown files do not satisfy required example checks, so missing per-type or extension examples still surface as `EXAMPLE_MISSING` diagnostics.",
       "expectations": [
         "Does not treat the repository root as the Markdown scan scope merely because `docfx.json` is at the root",
-        "Uses configured DocFX Markdown inputs such as `.docfx/api/**/*.md` as the overwrite discovery scope",
+        "Uses configured DocFX Markdown inputs such as `.docfx/api/namespaces/**/*.md` as the overwrite discovery scope",
         "Does not allow README.md or CHANGELOG.md front matter to satisfy required examples unless those files are included by DocFX config",
         "Still reports `EXAMPLE_MISSING` for public API targets whose configured overwrite files lack examples"
       ]
     },
     {
       "id": 16,
-      "prompt": "Run dotnet-docfx-digest validation with `--changed-only` after I changed only `docfx.json` to widen `build.overwrite` from namespace pages to per-type files. Existing namespace pages still contain stale Extension Members content, but the namespace page files themselves are not changed.",
+      "prompt": "Run dotnet-docfx-digest validation with `--changed-only` after I changed only `docfx.json` to exclude `api/namespaces/**` from `build.content` and keep `api/namespaces/**/*.md` under `build.overwrite`. Existing namespace pages still contain stale Extension Members content, but the namespace page files themselves are not changed.",
       "expected_output": "Agent runs scripts/docfx.cs with `--changed-only` and still revalidates namespace pages when `docfx.json` changes, because DocFX config changes can change which overwrite files and namespace pages participate in the documentation build. Stale namespace-page diagnostics are surfaced instead of being silently skipped.",
       "expectations": [
         "Treats a changed `docfx.json` as a reason to rerun namespace-page validation under `--changed-only`",
         "Does not require the namespace Markdown file itself to be in the changed file set when DocFX config changed",
-        "Still surfaces stale namespace-page and Extension Members diagnostics after a build.overwrite glob change",
+        "Still surfaces stale namespace-page and Extension Members diagnostics after a DocFX overwrite-layout change",
         "Keeps required-example validation aligned with the same changed `docfx.json` trigger"
       ]
     },
+    {
+      "id": 18,
+      "prompt": "Fix the DocFX overwrite setup in a Codebelt-style repository where `.docfx/docfx.json` currently uses `api/**/*.md` under both `build.content` and `build.overwrite`, and authored overwrite Markdown files like `.docfx/api/Codebelt.Extensions.Swashbuckle.AspNetCore.ConfigureSwaggerGenOptions.md` still sit directly under `.docfx/api/`. Move the authored overwrite Markdown into `.docfx/api/namespaces/`, preserve the YAML front matter and example content, keep generated `.yml` metadata in place, and verify that `docfx build --exportRawModel` still treats the API page as managed reference rather than conceptual-only.",
+      "expected_output": "Agent rewrites `docfx.json` so `api/namespaces/**/*.md` is treated as overwrite-only content, excludes `api/namespaces/**` from `build.content`, moves authored API overwrite Markdown from `.docfx/api/*.md` into `.docfx/api/namespaces/` without dropping content, preserves generated `.yml` files, reruns verification, and confirms the raw model remains a managed API page with overwrite content merged into it rather than collapsing to `{ \"type\": \"Conceptual\" }`.",
+      "expectations": [
+        "Moves authored API overwrite Markdown files from `.docfx/api/*.md` into `.docfx/api/namespaces/`",
+        "Preserves YAML front matter, UID targeting, and Markdown example content while moving the files",
+        "Keeps generated `.yml` metadata files in place",
+        "Ensures `api/namespaces/**/*.md` appears only under `build.overwrite` and that `build.content` excludes `api/namespaces/**`",
+        "Does not use `api/**/*.md` under `build.content` or `build.overwrite`",
+        "Verifies the affected API page remains managed reference output with merged overwrite content instead of conceptual-only raw model output"
+      ]
+    },
     {
       "id": 17,
       "prompt": "The `Acme.OpenApi.ModelContextProtocol` namespace page currently says `Contains types and extension methods for MCP integration.` The public type `McpServerOptions` says `Represents options for the server.` The extension method `AddMcpServer(this IServiceCollection services)` says `Adds MCP server services.` Use dotnet-docfx-digest to rewrite the documentation so a developer new to this domain immediately understands what each API is for.",
diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
index bc675b0..237ef89 100644
--- a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -57,7 +57,7 @@ The `build.overwrite` entry in `docfx.json` tells DocFX which conceptual Markdow
 
 When a repository has no obvious overwrite location, inspect `docfx.json` first. Look at `build.content`, `build.overwrite`, `metadata.dest`, include paths, and existing Markdown layout before deciding where a new namespace page belongs.
 
-If a public non-abstraction type lacks an example, create a matching type-UID overwrite section in a separate per-type Markdown file by default, and make sure that file is included by `build.overwrite` so the example appears on the generated type API page. In Codebelt repositories, create new type example files under `.docfx/api/{TypeUid}.md`, such as `.docfx/api/X.Y.Z.Class1.md`. If `build.overwrite` only includes namespace files such as `api/namespaces/**/*.md`, update it to include per-type API overwrite files too, such as `api/**/*.md`. Namespace overview pages and `Extension Members` tables complement examples; they do not replace type-page examples.
+If a public non-abstraction type lacks an example, create a matching type-UID overwrite section in a separate per-type Markdown file by default, and make sure that file is included by `build.overwrite` so the example appears on the generated type API page. In Codebelt repositories, keep authored API overwrite files under `.docfx/api/namespaces/{TypeUid}.md`, such as `.docfx/api/namespaces/X.Y.Z.Class1.md`. File location does not decide whether the page is a namespace page or a type page; the YAML front matter `uid` does. Keep `api/namespaces/**/*.md` under `build.overwrite`, exclude `api/namespaces/**` from `build.content`, and do not use `api/**/*.md` under either section. If authored overwrite Markdown already exists directly under `.docfx/api/*.md`, move it into `.docfx/api/namespaces/` without deleting the content. Namespace overview pages and `Extension Members` tables complement examples; they do not replace type-page examples.
 
 ## Practical Rules
 
@@ -67,6 +67,8 @@ If a public non-abstraction type lacks an example, create a matching type-UID ov
 - Use namespace overview pages for namespace fly-ins and extension-member tables.
 - Keep examples and remarks close to the API item or namespace they explain.
 - Create per-type overwrite files for missing concrete-type examples even when the repository currently has only namespace overview files.
+- Keep authored API overwrite Markdown under `.docfx/api/namespaces/` and move legacy `.docfx/api/*.md` files there.
+- Keep `api/namespaces/**/*.md` under `build.overwrite` only; do not use `api/**/*.md` under `build.content` or `build.overwrite`.
 - Add examples through overwrite sections when XML comments or generated metadata do not already provide developer-friendly examples.
 - Preserve existing hand-written overwrite sections unless they are stale or contradictory.
 - Prefer additive edits, but remove or revise contradictions.
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index cecdde5..34d873a 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -44,7 +44,7 @@ Exit codes:
 
 ## docfx.cs
 
-Validates the deterministic documentation requirements against the compiled repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies, prefers reference assemblies, loads metadata through `System.Reflection.MetadataLoadContext`, resolves dependencies from project assets, deps files, and installed .NET reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, and compiles every C# documentation sample as a file-based app. For Codebelt strong-name signed repositories, repository and sample builds use the root `.snk` when present and automatically pass `-p:SkipSignAssembly=true` when no root `.snk` exists, so missing local signing keys do not masquerade as documentation failures.
+Validates the deterministic documentation requirements against the compiled repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies, prefers reference assemblies, loads metadata through `System.Reflection.MetadataLoadContext`, resolves dependencies from project assets, deps files, and installed .NET reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, the Codebelt namespace-folder overwrite convention (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and compiles every C# documentation sample as a file-based app. For Codebelt strong-name signed repositories, repository and sample builds use the root `.snk` when present and automatically pass `-p:SkipSignAssembly=true` when no root `.snk` exists, so missing local signing keys do not masquerade as documentation failures.
 
 ```bash
 dotnet run --file docfx.cs -- --repo-root .
@@ -60,7 +60,7 @@ Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--f
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, a required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected per-type overwrite path such as `.docfx/api/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
+`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, a required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/namespaces/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics keep `api/namespaces/**/*.md` under `build.overwrite` only while moving legacy `.docfx/api/*.md` authored overwrite files into `.docfx/api/namespaces/`. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
 
 `--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files and namespace pages are documentation output, not cleanup targets.
 
@@ -80,7 +80,7 @@ Exit codes:
 | 7 | Sample compilation failed |
 | 8 | Unexpected internal error |
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Validation warnings can also include `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
 
 ### Sample opt-out
 
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 67769e1..5c4be8f 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -118,6 +118,7 @@ private static int Validate(Options options)
         var docfxWorkspace = Path.GetDirectoryName(docfxPath)!;
         options.Framework ??= ResolveDefaultFramework(docfxPath, report);
         CleanupGeneratedMetadata(repoRoot, docfxPath, docfxWorkspace, options, report);
+        ValidateApiOverwriteLayout(repoRoot, docfxPath, docfxWorkspace, report);
 
         // 3. Verify AGENTS.md contains the managed block.
         var agentsPath = Path.Combine(repoRoot, "AGENTS.md");
@@ -268,6 +269,131 @@ private static int Validate(Options options)
         return null;
     }
 
+    private static void ValidateApiOverwriteLayout(string repoRoot, string docfxPath, string docfxWorkspace, Report report)
+    {
+        var apiDirectory = Path.Combine(docfxWorkspace, "api");
+        var namespacesDirectory = Path.Combine(apiDirectory, "namespaces");
+        bool shouldValidateConvention =
+            PathsEqual(docfxWorkspace, Path.Combine(repoRoot, ".docfx")) ||
+            Directory.Exists(namespacesDirectory) ||
+            Directory.Exists(apiDirectory);
+
+        if (!shouldValidateConvention)
+        {
+            return;
+        }
+
+        JsonDocument doc;
+        try
+        {
+            doc = JsonDocument.Parse(File.ReadAllText(docfxPath), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+        }
+        catch (Exception ex) when (ex is IOException or JsonException)
+        {
+            report.Warnings.Add(new Diagnostic("API_OVERWRITE_CONFIG_UNREADABLE", docfxPath, null,
+                $"Unable to validate the DocFX overwrite layout: {ex.Message}"));
+            return;
+        }
+
+        using (doc)
+        {
+            if (!doc.RootElement.TryGetProperty("build", out var build) || build.ValueKind != JsonValueKind.Object)
+            {
+                return;
+            }
+
+            var contentFiles = ReadDocfxBuildPatterns(build, "content", "files");
+            var contentExclude = ReadDocfxBuildPatterns(build, "content", "exclude");
+            var overwriteFiles = ReadDocfxBuildPatterns(build, "overwrite", "files");
+
+            var configProblems = new List<string>();
+            if (contentFiles.Any(pattern => DocfxPatternEquals(pattern, "api/**/*.md") || DocfxPatternEquals(pattern, "api/namespaces/**/*.md")))
+            {
+                configProblems.Add("Do not include `api/**/*.md` or `api/namespaces/**/*.md` under `build.content`.");
+            }
+
+            if (!contentExclude.Any(pattern => DocfxPatternEquals(pattern, "api/namespaces/**")))
+            {
+                configProblems.Add("Add `api/namespaces/**` to the `build.content` exclusions.");
+            }
+
+            if (!overwriteFiles.Any(pattern => DocfxPatternEquals(pattern, "api/namespaces/**/*.md")))
+            {
+                configProblems.Add("Include `api/namespaces/**/*.md` under `build.overwrite`.");
+            }
+
+            if (overwriteFiles.Any(pattern => DocfxPatternEquals(pattern, "api/**/*.md")))
+            {
+                configProblems.Add("Do not include `api/**/*.md` under `build.overwrite`.");
+            }
+
+            if (configProblems.Count > 0)
+            {
+                report.Errors.Add(new Diagnostic("API_OVERWRITE_CONFIG_INVALID", docfxPath, null,
+                    $"DocFX API overwrite Markdown must use the namespace-folder convention so overwrite content merges into managed API pages without being treated as normal content. {string.Join(" ", configProblems)}"));
+            }
+        }
+
+        if (!Directory.Exists(apiDirectory))
+        {
+            return;
+        }
+
+        foreach (var file in Directory.EnumerateFiles(apiDirectory, "*.md", SearchOption.TopDirectoryOnly)
+                     .Where(path => !string.Equals(Path.GetFileName(path), "toc.md", StringComparison.OrdinalIgnoreCase)))
+        {
+            var destination = Rel(repoRoot, Path.Combine(namespacesDirectory, Path.GetFileName(file)));
+            report.Errors.Add(new Diagnostic("API_OVERWRITE_FILE_MISPLACED", file, null,
+                $"Authored API overwrite Markdown must not live directly under `{Rel(repoRoot, apiDirectory)}`. Move this file to `{destination}` and keep its YAML front matter and Markdown content intact. Do not move generated `.yml` metadata files."));
+        }
+    }
+
+    private static List<string> ReadDocfxBuildPatterns(JsonElement build, string propertyName, string nestedPropertyName)
+    {
+        var patterns = new List<string>();
+        if (!build.TryGetProperty(propertyName, out var entries))
+        {
+            return patterns;
+        }
+
+        foreach (var entry in EnumerateDocfxFileMappingEntries(entries))
+        {
+            if (entry.ValueKind == JsonValueKind.String)
+            {
+                if (string.Equals(nestedPropertyName, "files", StringComparison.Ordinal))
+                {
+                    patterns.Add(entry.GetString() ?? string.Empty);
+                }
+
+                continue;
+            }
+
+            if (entry.ValueKind == JsonValueKind.Object &&
+                entry.TryGetProperty(nestedPropertyName, out var nested))
+            {
+                patterns.AddRange(ReadDocfxGlobPatterns(nested));
+            }
+        }
+
+        return patterns;
+    }
+
+    private static bool DocfxPatternEquals(string actual, string expected)
+    {
+        return string.Equals(NormalizeDocfxPattern(actual), NormalizeDocfxPattern(expected), StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static string NormalizeDocfxPattern(string pattern)
+    {
+        return (pattern ?? string.Empty)
+            .Replace('\\', '/')
+            .Trim();
+    }
+
     private static string? ResolveDefaultFramework(string docfxPath, Report report)
     {
         try
@@ -1864,13 +1990,13 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
                 ? target.Uid
                 : target.DeclaringTypeUid ?? target.Uid;
             var expectedPath = target.Kind == ApiTargetKind.Type
-                ? Rel(repoRoot, Path.Combine(docfxWorkspace, "api", $"{target.Uid}.md"))
+                ? Rel(repoRoot, Path.Combine(docfxWorkspace, "api", "namespaces", $"{target.Uid}.md"))
                 : target.DeclaringTypeUid is null
                     ? null
-                    : Rel(repoRoot, Path.Combine(docfxWorkspace, "api", $"{target.DeclaringTypeUid}.md"));
+                    : Rel(repoRoot, Path.Combine(docfxWorkspace, "api", "namespaces", $"{target.DeclaringTypeUid}.md"));
 
             var message = target.Kind == ApiTargetKind.Type
-                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}` in `{expectedPath}` or another overwrite file that targets this exact type UID. Namespace overview examples do not satisfy this diagnostic. Ensure build.overwrite includes the file, for example with `api/**/*.md`."
+                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}` in `{expectedPath}` or another overwrite file under `api/namespaces/` that targets this exact type UID. Namespace overview examples do not satisfy this diagnostic. Keep `api/namespaces/**/*.md` under `build.overwrite`, exclude `api/namespaces/**` from `build.content`, and do not use `api/**/*.md` under either section."
                 : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to the declaring extension class uid `{expectedUid}` or the namespace page `{target.Namespace}` by default. The example must explicitly call `{target.DisplayName}`. Do not create URL-encoded or hash-like method UID filenames; use a method UID section only when the exact generated UID is verified and can live in a readable overwrite file.";
 
             report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", expectedPath, target.Namespace, message));
@@ -2592,7 +2718,7 @@ private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerab
             var path = EscapeTable(string.IsNullOrWhiteSpace(diagnostic.Path) ? "(method UID, declaring type UID, or namespace page)" : diagnostic.Path);
             var message = EscapeTable(diagnostic.Message);
             var action = diagnostic.Message.Contains("Public non-abstraction type", StringComparison.Ordinal)
-                ? "Create or update the per-type UID overwrite file, include it in build.overwrite, add a compiling Examples section, then rerun validation."
+                ? "Create or update the type-targeting overwrite file under `api/namespaces/`, keep `api/namespaces/**/*.md` under `build.overwrite` only, add a compiling Examples section, then rerun validation."
                 : "Add a compiling Examples section on the declaring extension class or namespace page that explicitly calls the extension method, then rerun validation.";
             sb.AppendLine($"| {ns} | `{path}` | `EXAMPLE_MISSING` | {EscapeTable(action)} {message} |");
         }

From e2cf28c74054a0a2867e865b280ddeaca911ab42 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 01:59:58 +0200
Subject: [PATCH 34/88] =?UTF-8?q?=F0=9F=92=AC=20document=20blocking=20comp?=
 =?UTF-8?q?letion=20gates=20policy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add Blocking Completion Gates section to AGENTS.md defining required script and verification steps that block task completion. Update README.md with high-level guidance on completion gates, specifically referencing the DocFX workflow scripts as mandatory checkpoints. These enforce that script-backed workflows cannot skip verification steps.
---
 AGENTS.md | 8 ++++++++
 README.md | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 3ff421a..22e4f11 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -151,6 +151,14 @@ All markdown files in this repository must use natural paragraph flow. Do not ar
 
 After modifying any skill (`SKILL.md`, `FORMS.md`) or repo-level config (`AGENTS.md`), **always update `README.md` before considering the task done**. This is a mandatory gate — not a nice-to-have. The README's "Available Skills" table, install examples, and "Why" sections must reflect the current state of all skills. A new skill without a README entry is incomplete work.
 
+## Blocking Completion Gates
+
+When repository guidance, an active skill, or a conversation summary identifies required follow-up work as pending, critical, blocking, or equivalent, treat those items as the active completion checklist for the current task rather than as background context. Do not call `task_complete`, describe the task as complete, or claim verification succeeded until every blocking item has either run successfully or been reported with the exact command, exit code, and remaining blocker.
+
+Before any completion message, reread the skill instructions and the current conversation summary's pending-task or blocker sections. If either one names a required script, validator, or maintenance step, that step is a hard gate, not optional polish.
+
+For script-backed workflows, creating or editing files is not enough on its own. If a skill requires deterministic maintenance or verification commands, run them before completion and report their concrete outcome. For `dotnet-docfx-digest`, `scripts/agents.cs` and `scripts/docfx.cs --verify-docfx-build` are blocking completion gates whenever the skill or task summary says they are required.
+
 ## User Input UX
 
 When a skill collects parameters from the user, define the form in a dedicated `FORMS.md` file (Level 3 resource) rather than inlining field definitions in `SKILL.md`. This separates form structure from workflow logic and gives agents a parseable format to present fields correctly.
diff --git a/README.md b/README.md
index 73c04c4..ecc7dac 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,8 @@ One more consistency rule matters for form-driven skills: native input fields ar
 
 Repo-level agent guidance also keeps progress updates user-facing: agents should report meaningful progress, evidence, blockers, and next steps without narrating sandbox mechanics, approved command paths, or retry plumbing unless those details affect approval, reproducibility, validation, or the final outcome.
 
+Completion gates are equally strict: if repository guidance, a loaded skill, or the conversation summary marks a script-backed step as pending, critical, or blocking, agents must treat it as an active checklist item and may not claim completion until that command has run or the exact blocker has been reported. In the DocFX workflow, that means `scripts/agents.cs` and `scripts/docfx.cs --verify-docfx-build` are completion gates, not optional cleanup after the documentation files look done.
+
 Validation follows the same philosophy: run `scripts/validate-skill-templates.ps1` locally for the fast feedback loop, and let GitHub Actions rerun that same script on pull requests as the safety net. That validator also checks skill frontmatter metadata such as per-skill `evals/evals.json` files, optional eval fixture paths declared through `files`, and the 1024-character YAML description limit; it does not replace the paired benchmark review workflow.
 
 ## Install a skill

From 267eaff0d81ad8f78ea6d7938332689fbbb9a523 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 02:39:45 +0200
Subject: [PATCH 35/88] =?UTF-8?q?=F0=9F=92=AC=20update=20dotnet-docfx-dige?=
 =?UTF-8?q?st=20skill=20description?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refine README skill entry description to reflect enhanced workflow details, validation scope, and reference documentation organization.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ecc7dac..644e6b5 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, Codebelt namespace-folder overwrite layout (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and C# documentation samples, keeps `--changed-only` namespace-page and example validation scoped to affected docs/APIs while revalidating when `docfx.json` changes, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, and managed-reference-safe completion gates for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, Codebelt namespace-folder overwrite layout (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and C# documentation samples, keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown so new samples compile before staging, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, and managed-reference-safe completion gates for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 

From 4c8e7a6b5dd6936f90e9a2365bf54978f47a75fc Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 02:39:52 +0200
Subject: [PATCH 36/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20skill=20structure=20and=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extract detailed DocFX workflow guidance into dedicated workflow.md reference file to reduce SKILL.md verbosity and improve progressive disclosure. Restructure SKILL.md with clearer sectioning and improved readability. Enhance docfx.cs script with refined validation logic. Update evals and scripts reference with corresponding adjustments. Align skill resources with improved documentation organization.
---
 skills/dotnet-docfx-digest/SKILL.md           | 1053 +++--------------
 skills/dotnet-docfx-digest/evals/evals.json   |   11 +-
 .../dotnet-docfx-digest/references/scripts.md |    2 +-
 .../references/workflow.md                    |  196 +++
 skills/dotnet-docfx-digest/scripts/docfx.cs   |   11 +
 5 files changed, 406 insertions(+), 867 deletions(-)
 create mode 100644 skills/dotnet-docfx-digest/references/workflow.md

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index ef571ce..79af450 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -1,861 +1,192 @@
----
-name: dotnet-docfx-digest
-description: >
-  Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including repo-wide no-input audits, concept-led namespace overview pages, purpose-first type/member summaries, extension-member documentation, overwrite files, examples, availability notes, AGENTS.md maintenance, and verification. Use when the user asks to document a .NET API, create or update DocFX documentation, write namespace overview pages, improve API summaries, add extension-method tables, update XML documentation comments, add API examples, maintain DocFX overwrite files, or verify documentation builds. Treat requests like "use dotnet-docfx-digest", "update the DocFX docs", "complete missing documentation", "create namespace pages", "improve these API summaries", "add examples for this type", "update the extension members table", or "verify the documentation builds" as automatic triggers. Also use whenever public .NET API surface changes and documentation needs to stay aligned with source code.
----
-
-# .NET DocFX Digest Steward
-
-## Description
-
-Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including concept-led namespace overview pages, purpose-first type/member summaries, extension-member documentation, overwrite files, examples, availability notes, and verification. Preserve manual edits, document public API only, require buildable copy/paste-ready examples for concrete APIs, and keep documentation aligned with actual source code and tests.
-
-## Activation Requirements
-
-This skill is autonomous by default. If the user invokes the skill without naming a namespace, type, member, or changed API, do not ask what to document first. Treat the request as a repo-wide DocFX documentation audit and repair task:
-
-1. Run the repository-instruction script.
-2. Inspect repository guidance, `docfx.json`, source projects, generated metadata, tests, samples, existing overwrite files, namespace pages, and availability includes.
-3. Run the validator to discover missing or stale complementary documentation.
-4. Fill the missing DocFX pieces that can be derived from source evidence, including type-page overwrite examples for public non-abstraction types and public extension methods.
-5. Ask a concise clarifying question only when inspection exposes a correctness-affecting choice that cannot be resolved from repository evidence.
-
-When this skill is invoked against a repository, resolve the target repository root and bundled script paths before running any validation. Prefer the loaded `dotnet-docfx-digest` skill directory as the script source, for example `<skill-dir>/scripts/agents.cs` and `<skill-dir>/scripts/docfx.cs`. If the loaded skill directory is unavailable and the target repository contains the repo-managed source copy, use `skills/dotnet-docfx-digest/scripts/*.cs`. Do not conclude a script is unavailable until both locations have been checked.
-
-Run the deterministic repository-instruction script before completing the task:
-
-```bash
-dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-root>
-```
-
-Before reporting completion, the agent must run the deterministic validator:
-
-```bash
-dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --verify-docfx-build
-```
-
-## Completion Repair Loop
-
-Do not stop at namespace pages, extension-member tables, or a first-pass documentation edit. Those surfaces are useful discovery aids, but they do not prove that generated type pages have the required examples. Before deeming a DocFX documentation request complete, run a closure loop:
-
-1. Run `docfx.cs --json` after edits and read the remaining diagnostics.
-2. If diagnostics include `EXAMPLE_MISSING`, missing namespace pages, stale extension-member tables, sample compile failures, missing availability, or overwrite inclusion problems, treat them as the next work queue rather than final notes.
-3. For every `EXAMPLE_MISSING` public non-abstraction type, create or update the type-page overwrite file for that type UID under `.docfx/api/namespaces/`, such as `.docfx/api/namespaces/ApplicationHostFactory.md`, and put the example in that file or another overwrite section that targets the type UID directly.
-4. For every required example file, verify `docfx.json` keeps `api/namespaces/**/*.md` under `build.overwrite`, excludes `api/namespaces/**` from `build.content`, and does not use `api/**/*.md` under either `content` or `overwrite`. Move legacy authored `.docfx/api/*.md` overwrite files into `.docfx/api/namespaces/` instead of widening the glob.
-5. Update the example inventory so each required public non-abstraction type and public extension method maps to the exact example file and UID.
-6. Rerun the validator and repeat the loop until required diagnostics are gone, or stop and report the exact blocker, command, exit code, and remaining diagnostic codes.
-
-The completion loop is the guard against the common failure where an agent finishes namespace overview pages but forgets per-type API overwrite pages. Namespace-level examples do not satisfy `EXAMPLE_MISSING` for public non-abstraction types.
-
-## Complementary Documentation Surfaces
-
-Do not trade one documentation surface for the other. Namespace pages and per-type pages have different jobs, and both must remain useful:
-
-- Namespace pages explain the package or namespace shape: what problem the namespace solves, when to use it, important type families, extension-method groups, availability, and links or references to representative type pages.
-- Per-type pages explain what a specific public concrete type is for, when a developer would reach for it, and how to use it with copy/paste-ready examples.
-- Extension-method examples normally live on the declaring extension class page or the namespace page, but the namespace page must still read like curated API documentation, not a dumping ground for examples.
-
-When per-type examples are added, revisit the related namespace page and keep its fly-in well-versed and developer-friendly. Moving examples out of the namespace page must not leave the namespace page as a generic sentence plus table. Preserve or improve the curated namespace overview that helps readers choose the right type before they drill into generated type pages.
-
-## Conceptual Orientation
-
-Namespace pages, type summaries, and member summaries should orient a developer to purpose, not just inventory API shape. Use an inverted-pyramid writing order:
-
-1. Lead with the biggest idea: what problem this namespace, type, or member solves, or what outcome it enables.
-2. Follow with when a developer would use it in normal work.
-3. Give quick orientation such as "If you're trying to do X, start with Y" when an entry-point type, option type, or extension method helps readers choose where to go next.
-4. Then add structural detail such as important type families, representative members, or constraints.
-
-Write for a developer who is new to the domain, not for someone who already knows why the API exists. A strong summary should answer "why would I care?" before it answers "what names live here?"
-
-Avoid filing-cabinet labels such as "contains types and extension methods for..." or generic blurbs such as "represents options..." and "adds services..." when they are not followed by concrete purpose. Those phrases are acceptable only when the rest of the sentence explains the real job of the API.
-
-Bad namespace summary:
-
-```markdown
-The `Acme.OpenApi.ModelContextProtocol` namespace contains types and extension methods for MCP integration.
-```
-
-Better namespace summary:
-
-```markdown
-The `Acme.OpenApi.ModelContextProtocol` namespace bridges Model Context Protocol servers with OpenAPI documentation. Use it when you want MCP-enabled services to stay discoverable through standard Swagger/OpenAPI tooling. If you're wiring the integration into an ASP.NET Core app, start with `AddMcpServer`.
-```
-
-Bad type/member summaries:
-
-```csharp
-/// <summary>
-/// Represents options for the server.
-/// </summary>
-
-/// <summary>
-/// Adds MCP server services.
-/// </summary>
-```
-
-Better type/member summaries:
-
-```csharp
-/// <summary>
-/// Configures how the MCP server is exposed through the application's OpenAPI pipeline.
-/// </summary>
-
-/// <summary>
-/// Registers the MCP/OpenAPI integration during service configuration so MCP endpoints appear in generated API documentation.
-/// </summary>
-```
-
-## Type-Page Example Gate
-
-Before editing examples, build a small example inventory from validator output and source evidence. This inventory is the task queue, not a summary for the final response. Each required item should have this shape:
-
-```markdown
-| UID | Kind | Required example location | Source evidence | Status |
-|---|---|---|---|---|
-| Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | ApplicationHostFactoryTest | Missing |
-```
-
-For every public non-abstraction type, the required example location is a type UID overwrite section. In Codebelt repositories, keep those authored overwrite files under `.docfx/api/namespaces/` using readable filenames such as `.docfx/api/namespaces/{TypeUid}.md`. For example, when the missing type is `ApplicationHostFactory`, create `.docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or the exact UID path reported by the validator. The file may live under `api/namespaces/` while still merging into the generated type page, because the YAML front matter `uid` determines the target model. Do not put the only example on the namespace UID page, because that improves the namespace page while leaving the generated type page incomplete.
-
-For public extension methods, the inventory must name the method and the section that demonstrates it. Prefer a readable overwrite file for the declaring extension class UID, or the namespace page when that is the existing extension-method documentation surface. Method UIDs can contain signatures, generic parameters, hashes, or URL-encoded characters — **never create filenames that mirror these synthetic UIDs** (e.g., `MyExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md` or `MyExtensions.%3CT%3E...md`). Always use the declaring extension class UID in front matter and keep the file at the readable class path. See the "Hash-Suffix Filenames Are Prohibited" section. The example must explicitly call the extension method.
-
-Do not mark the inventory item complete until all of these are true:
-
-- The overwrite section targets the required type UID or an allowed extension-method location such as the declaring extension class UID or namespace UID.
-- `build.overwrite` includes the file through the namespace-folder convention, normally `api/namespaces/**/*.md`, and `build.content` excludes `api/namespaces/**`.
-- The example code fence compiles or carries an explicit, justified skip marker.
-- A rerun of `docfx.cs --json` no longer reports `EXAMPLE_MISSING` for that UID.
-
-For repo-wide audits or any validation run that produces more than a small number of diagnostics, the agent must also ask the validator to write a deterministic repair plan and use that plan as the authoritative work queue:
-
-```bash
-dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --json --repair-plan <temp-path>/docfx-repair-plan.md
-```
-
-If either script cannot run, the agent must report the exact command, exit code, and failure output. Do not claim repository instructions or documentation were verified unless the scripts ran successfully.
-
-Read `references/scripts.md` when you need the exact CLI surface, exit codes, JSON diagnostics, or validator behavior for `agents.cs` and `docfx.cs`.
-
-## Core Principles
-
-Documentation is part of the public contract. When changing public .NET APIs, the agent must update the corresponding documentation in the same change set. This includes XML documentation comments, DocFX overwrite files, namespace overview pages, examples, extension-method listings, and availability information.
-
-The documentation must reflect the actual code, not intended code. Do not invent APIs, overloads, target frameworks, behaviors, exceptions, or examples. Verify every documented claim against source code, tests, project files, generated metadata, or existing documentation.
-
-Manual documentation is authoritative context. Preserve existing manual edits unless they are factually incorrect. Prefer additive changes. When information is stale, update the stale portion while retaining nearby human-written explanations, tone, and structure.
-
-## Safety Gates
-
-Before making documentation changes, capture the current repository state:
-
-1. Run `git status --short` and identify modified, staged, and untracked documentation files.
-2. If source documentation files already have uncommitted changes, treat them as user work. Do not overwrite, restore, reformat, or regenerate them wholesale.
-3. Read each affected Markdown file before editing it.
-4. For cleanup candidates, list the exact files or directories first and classify them as generated metadata, generated site output, build artifacts, or authored documentation.
-
-Before any git operation that can discard or overwrite content, stop and report the exact files that would be affected. Do not run broad `git restore`, `git checkout --`, `git reset`, or whole-directory recovery commands on documentation source directories. If recovery is needed, recover only the specific generated or accidentally removed file after inspecting `git status` and `git diff`.
-
-After modifications, run `git diff` for the touched documentation paths and verify the diff contains only intended documentation changes. If the work cannot be completed without partial, inconsistent, or unverifiable documentation, stop and report the limitation instead of proceeding partially.
-
-## Scope
-
-Apply this skill to:
-
-- Public .NET types,
-- Public constructors,
-- Public properties,
-- Public methods,
-- Public fields,
-- Public events,
-- Public delegates,
-- Public enums and enum members,
-- Public extension methods,
-- Public namespaces containing public API,
-- DocFX overwrite Markdown files,
-- DocFX namespace overview Markdown files,
-- XML documentation comments,
-- API examples,
-- availability includes or availability statements.
-
-Do not document:
-
-- Private types,
-- Internal types,
-- Private members,
-- Internal members,
-- Implementation-only helpers,
-- Test-only fixtures unless they are part of a documented public test-support API,
-- Namespaces that contain no public API.
-
-If a namespace contains only private or internal types, do not create a namespace overview page for it.
-
-## Repository Discovery
-
-Before editing documentation, locate the DocFX workspace.
-
-For Codebelt repositories, the DocFX workspace is always:
-
-```text
-.docfx
-```
-
-The DocFX configuration file is always:
-
-```text
-.docfx/docfx.json
-```
-
-For other repositories, locate `docfx.json` before making DocFX-specific changes.
-
-Inspect `docfx.json` to understand:
-
-- Content roots,
-- API metadata inputs,
-- Overwrite file locations,
-- Include file locations,
-- Resource paths,
-- Output conventions.
-
-Do not assume paths beyond the repository's actual DocFX configuration, except for Codebelt repositories where `.docfx/docfx.json` is the convention.
-
-When creating or repairing overwrite files, read `references/docfx-overwrite-files.md` for the DocFX overwrite and `docfx.json` rules that matter most to agents.
-
-## AGENTS.md Maintenance
-
-Persistent repository guidance is enforced by script, not by AI memory. When this skill is invoked, run:
-
-```bash
-dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-root>
-```
-
-The script must create or update a marker-bounded DocFX documentation maintenance section in the repository root `AGENTS.md`. Resolve `<repo-root>` from the actual repository being documented, not from a temp workspace or the skill install folder. If the current working directory is already the target repository root, `<repo-root>` may be `.` after confirming it with repository evidence such as `git rev-parse --show-toplevel` or equivalent path inspection. Do not manually duplicate this section. If the script fails, report the exact command, exit code, and output, and do not claim `AGENTS.md` was updated.
-
-## Public API Rule
-
-Only public API is documented. Before adding or updating documentation, determine whether the item is public from source code or generated metadata.
-
-A type is documentable only when it is externally visible. A member is documentable only when it is public and belongs to a documentable public type.
-
-Do not add documentation pages for namespaces that contain no public types. Do not add extension-method documentation for non-public extension methods.
-
-## Required Documentation Updates
-
-When a public API is added or materially changed, update all relevant documentation surfaces:
-
-1. XML documentation comments in source code.
-2. DocFX overwrite files when manual API documentation exists or is needed.
-3. Namespace overview page.
-4. Extension members table when extension methods are involved.
-5. Availability information.
-6. At least one usage example in DocFX overwrite content unless the documented item is an abstraction.
-7. Verification artifacts or commands proving the documentation remains buildable and accurate.
-
-A "material change" includes:
-
-- New public API,
-- Removed public API,
-- Changed public signature,
-- Changed behavior,
-- Changed exception behavior,
-- Changed generic constraints,
-- Changed nullability contract,
-- Changed target framework availability,
-- Changed platform availability,
-- Changed extension-method availability,
-- Changed obsolete/deprecation status,
-- Changed default values,
-- Changed thread-safety or lifecycle expectations.
-
-## Examples Are Mandatory
-
-Every automatically documented public non-abstraction type and every public extension method must include at least one example showing how to use it. A namespace overview fly-in or `Extension Members` table is not enough.
-
-Do not treat an `Extension Members` table as documentation completion. A table answers "what exists"; an example answers "how a consumer uses it." For each public extension method discovered or listed in a namespace page, create or verify an example before moving to final verification. If several related namespace pages are updated together, build an example inventory that maps every public extension method and every public non-abstraction type to the exact overwrite file and UID where its example lives.
-
-Create or repair DocFX overwrite content for missing examples. If an overwrite section for the target `uid` does not exist, create a separate per-type Markdown overwrite file by default. For Codebelt repositories, keep authored API overwrite files under `.docfx/api/namespaces/`, so the default type example file is:
-
-```text
-.docfx/api/namespaces/{TypeUid}.md
-```
-
-For example, create `.docfx/api/namespaces/Codebelt.Bootstrapper.ProgramRoot.md` for uid `Codebelt.Bootstrapper.ProgramRoot`. Keep `docfx.json` on the namespace-folder convention: `build.content` excludes `api/namespaces/**`, `build.overwrite` includes `api/namespaces/**/*.md`, and neither section uses `api/**/*.md`. If legacy authored overwrite Markdown exists directly under `.docfx/api/*.md`, move it into `.docfx/api/namespaces/` without deleting the content. Do not hide type examples on the namespace UID page.
-
-For public non-abstraction types, the example must belong to the generated type page/overwrite section for that type `uid`. For example, if `Class1` is public and not an abstraction, add an `Examples` section to the DocFX overwrite content for `Class1` so the example appears on `Class1.md` at the bottom of the generated API page. A namespace page example does not satisfy the type-page example requirement for `Class1`.
-
-For public extension methods, add the example to the declaring extension class UID or the namespace page by default, but the example must name and demonstrate the extension method. Add a generated method UID section only when the exact UID is verified and it can be kept in a readable overwrite file. Do not create URL-encoded or hash-like filenames just to mirror a method UID; DocFX cares about the `uid` in front matter, not that the filename repeats the UID.
-
-An example may be omitted only when the item is an abstraction, such as:
-
-- Interface,
-- Abstract class,
-- Abstract member,
-- Attribute intended only for framework discovery,
-- Marker type with no direct usage,
-- Pure contract type where concrete usage belongs on implementations.
-
-When omitting an example for an abstraction, the documentation must make that reason clear.
-
-Preferred source for examples:
-
-1. Existing unit tests,
-2. Existing functional tests,
-3. Existing integration tests,
-4. Existing samples,
-5. Minimal new sample derived from actual public API behavior.
-
-Examples derived from tests must be converted into real-life usage. Do not paste raw assertion-heavy test code as documentation unless the documentation is specifically explaining testing. Convert Arrange/Act/Assert test structure into developer-oriented sample code.
-
-The example must be:
-
-- Realistic,
-- Minimal,
-- Deterministic,
-- Copy/paste-ready,
-- Buildable in a normal consuming project,
-- Free of hidden repository-specific helpers unless those helpers are also public and documented,
-- Free of pseudo-code,
-- Free of ellipses inside code blocks,
-- Free of unexplained magic values,
-- Valid for the documented target framework availability.
-
-Bad example pattern:
-
-```csharp
-// Arrange
-var sut = new Foo();
-
-// Act
-var actual = sut.Bar();
-
-// Assert
-Assert.Equal("baz", actual);
-```
-
-Preferred documentation pattern:
-
-```csharp
-using My.Library;
-
-var formatter = new Foo();
-string value = formatter.Bar();
-Console.WriteLine(value);
-```
-
-If assertions are useful, use them only when the sample is explicitly framed as a test sample and can compile in that test context.
-
-## Example Verification
-
-Every code sample added or changed must be verified. A C# code sample must compile.
-
-The deterministic validator compiles C# documentation samples as .NET 10 file-based apps. When completing DocFX documentation work, also ask it to verify the DocFX build in a temporary copy of the repository so generated metadata and site output stay outside the working tree. Run:
-
-```bash
-dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --verify-docfx-build
-```
-
-A sample may opt out only when the code fence includes:
-
-```csharp
-// dotnet-docfx-digest:skip-compile - <reason>
-```
-
-The reason is mandatory. Do not use silent opt-outs.
-
-Use skip markers sparingly. A reason such as "shows the framework pattern", "full example requires X package", or "example only" is not enough; it explains intent or setup, not why compilation is impossible. Prefer making the sample compile by adding normal public setup code, public package imports already available to the repository, or a smaller example. Reserve skip markers for samples that cannot be compiled deterministically by the validator, such as snippets that require a live external service, generated credentials, an OS-specific runtime service, or a host environment the file-based sample compiler cannot provide.
-
-Do not claim a sample compiles unless the validator or an equivalent repository verification command has compiled it successfully.
-
-## Codebelt Signing Keys
-
-Codebelt solutions are normally strong-name signed with a `.snk` file in the repository root on the main author's codespace. When building a Codebelt repository or a temporary copy of one, preserve and copy the root `.snk` file when it is present. If the target repository or temp copy does not have a root `.snk`, run build and test verification with signing disabled:
-
-```bash
-dotnet build -p:SkipSignAssembly=true
-dotnet test -p:SkipSignAssembly=true
-```
-
-Use the same MSBuild property for any equivalent repository build that documentation validation performs. This avoids reporting signing-key failures as documentation failures while preserving normal signed builds when the key is available.
-
-## Namespace Overview Pages
-
-Every namespace containing public API must have a namespace overview Markdown page.
-
-The namespace overview page must be named after the namespace:
-
-```text
-X.Y.Z.md
-```
-
-The page must live in the appropriate DocFX documentation folder for namespace overwrite/custom content. For Codebelt repositories, place namespace overview pages under the `.docfx` documentation structure according to the existing repository layout.
-
-The namespace page must use DocFX overwrite front matter with the namespace UID:
-
-```markdown
----
-uid: X.Y.Z
-summary: *content
----
-```
-
-The page must provide a developer-friendly fly-in explaining what the namespace is for. The fly-in should be similar in usefulness and tone to Microsoft .NET API documentation:
-
-- Lead with the developer problem or outcome the namespace exists for.
-- Explain when to use it.
-- Give quick orientation for a newcomer, such as "If you're trying to do X, start with Y."
-- Mention important concepts or type families.
-- Mention representative concrete types or extension-method groups when that helps readers choose where to go next.
-- Link or refer to type pages that carry detailed examples when examples are intentionally kept out of the namespace page.
-- Avoid marketing language.
-- Avoid inventory-only wording that merely restates type names without explaining purpose.
-- Keep the explanation accurate to the public API.
-- Use the inverted-pyramid structure from the Conceptual Orientation section before falling back to structural detail.
-
-Minimum namespace overview structure:
-
-```markdown
----
-uid: X.Y.Z
-summary: *content
----
-The `X.Y.Z` namespace helps you ...
-Use it when ...
-If you're trying to ..., start with `PrimaryType` or `PrimaryExtensions`.
-
-[!INCLUDE [availability-default](../../includes/availability-default.md)]
-```
-
-If the namespace contains extension methods, include an `Extension Members` section.
-
-## Extension Method Documentation
-
-Extension methods must be documented at namespace level.
-
-If any public type exposes public extension members in namespace `X.Y.Z`, then the DocFX documentation must include:
-
-```text
-X.Y.Z.md
-```
-
-This file must contain an `Extension Members` section. The section must list public extension methods exposed by that namespace.
-
-Required table format:
-
-```markdown
-### Extension Members
-
-|Type|Ext|Methods|
-|--:|:-:|---|
-|ITestOutputHelper|⬇️|`WriteLines`|
-|String|⬇️|`ReplaceLineEndings` (TFM netstandard2.0)|
-```
-
-Rules for the table:
-
-- `Type` is the extended type, not the static extension class.
-- `Ext` must use `⬇️`.
-- `Methods` lists public extension methods.
-- Use backticks around method names.
-- Include TFM-specific availability when a method is conditional.
-- Group overloads under the same method name unless overload distinction is essential.
-- Do not include internal/private extension methods.
-- Do not include extension classes as the primary documentation target unless the class itself has relevant public API beyond extension methods.
-
-Example:
-
-```markdown
-### Extension Members
-
-|Type|Ext|Methods|
-|--:|:-:|---|
-|String|⬇️|`ToSlug`, `NormalizeLineEndings`|
-|IEnumerable<T>|⬇️|`ForEach`, `Batch`|
-```
-
-## Availability Documentation
-
-Availability information must be present for public API documentation.
-
-Availability can be documented in either of two ways:
-
-1. By referencing an existing include file.
-2. By writing explicit availability text when no suitable include exists.
-
-Prefer include files when the repository has an `includes` folder with Markdown files that define availability.
-
-Example include:
-
-```markdown
-[!INCLUDE [availability-default](../../includes/availability-default.md)]
-```
-
-Example explicit availability:
-
-```markdown
-Availability: .NET 10, .NET 9 and .NET Standard 2.0.
-```
-
-If a suitable include exists, reference it instead of duplicating availability text. If no suitable include exists, explicit availability is acceptable.
-
-Do not add redundant availability text if the page already references an availability include that covers the same API surface.
-
-When availability differs by type, member, target framework, or platform, document the difference close to the affected item.
-
-Availability must reflect actual project files, conditional compilation, target frameworks, package metadata, and source code.
-
-## DocFX Overwrite Files
-
-Use DocFX overwrite files to modify or add content for generated API items without editing generated metadata directly.
-
-Overwrite files must include YAML front matter with the target `uid`. Example:
-
-```markdown
----
-uid: X.Y.Z.MyType
-summary: *content
----
-```
-
-The `uid` must match the generated DocFX UID. Do not guess UIDs. Verify them from generated metadata, existing API pages, source conventions, or DocFX output.
-
-Use overwrite files for:
-
-- Namespace overview pages,
-- Additional conceptual remarks,
-- Examples,
-- Corrected summaries,
-- Extension-method namespace documentation,
-- Availability notes,
-- Developer-oriented usage guidance.
-
-Do not use overwrite files to conceal inaccurate XML documentation. Correct the source XML documentation when it is wrong.
-
-When the validator reports `EXAMPLE_MISSING`, create or update DocFX overwrite content for the reported UID instead of treating the missing example as a prose-only issue.
-
-When a repository has namespace overview files but no type-targeting overwrite files, create the missing type files. Do not treat the absence of existing type files as a signal to skip examples. For Codebelt repositories, place new type-targeting overwrite files under `.docfx/api/namespaces/`, move legacy authored `.docfx/api/*.md` overwrite files into that folder, and keep `build.overwrite` on `.docfx/api/namespaces/**/*.md` instead of widening it to `.docfx/api/**/*.md`.
-
-## Namespace Coverage
-
-When one namespace page in a public API family needs repair, audit the sibling namespace pages before finishing. For example, if `Codebelt.Bootstrapper.md` is touched, also inspect related namespace pages such as `Codebelt.Bootstrapper.Console.md`, `Codebelt.Bootstrapper.Web.md`, and `Codebelt.Bootstrapper.Worker.md` when they exist. Apply the same correctness rules to every affected namespace page: accurate fly-in, availability, extension-member table, and required examples.
-
-Do not update only the first namespace file that exposes the problem. If only one namespace is intentionally changed, state why the other related namespace pages were inspected and left unchanged.
-
-## XML Documentation Comments
-
-Public API should have useful XML documentation comments. Prefer concise source-level XML comments and richer examples/remarks in DocFX overwrite files when documentation becomes long.
-
-XML documentation should describe:
-
-- Purpose,
-- Parameters,
-- Return value,
-- Exceptions,
-- Type parameters,
-- Important behavior,
-- Nullability expectations,
-- Thread-safety or lifecycle behavior when relevant.
-
-The opening summary sentence should explain the API's job in consumer terms. Lead with purpose and likely use, especially for entry-point extension methods, option types, factories, builders, and orchestration types. Prefer "what this enables and when to call it" over empty structural labels.
-
-Do not use empty boilerplate summaries.
-
-Bad:
-
-```csharp
-/// <summary>
-/// Gets or sets the value.
-/// </summary>
-```
-
-Better:
-
-```csharp
-/// <summary>
-/// Gets or sets the normalized name used when matching configuration keys.
-/// </summary>
-```
-
-Bad:
-
-```csharp
-/// <summary>
-/// Represents options for the server.
-/// </summary>
-
-/// <summary>
-/// Adds MCP server services.
-/// </summary>
-```
-
-Better:
-
-```csharp
-/// <summary>
-/// Configures how the MCP server is exposed through the application's OpenAPI pipeline.
-/// </summary>
-
-/// <summary>
-/// Registers the MCP/OpenAPI integration during service configuration so MCP endpoints appear in generated API documentation.
-/// </summary>
-```
-
-## Preservation Rules
-
-Manual edits must be preserved.
-
-Before editing an existing Markdown file:
-
-1. Read the entire file.
-2. Identify manually written sections.
-3. Preserve structure and tone where possible.
-4. Add new information in the most appropriate existing section.
-5. Avoid replacing the whole file unless the file is clearly generated or corrupt.
-6. Keep existing includes, admonitions, links, and examples unless they are stale.
-7. Update stale statements instead of appending contradictory new statements.
-
-Documentation must stay current. If additive-only editing would leave conflicting or stale information, update the stale information. Accuracy is more important than blindly appending content. Never leave two conflicting descriptions of the same API behavior.
-
-## Cleanup Boundary
-
-Authored DocFX Markdown is documentation output, not disposable build output. This includes namespace overview pages, per-type overwrite files, conceptual pages, includes, and Markdown files created earlier in the same run. Do not delete `.md` or `.mdoc` files, `docfx.json`, `toc.yml`, includes, images, examples, or directories that contain authored documentation while cleaning generated artifacts unless the user explicitly asks for that deletion.
-
-Prefer `docfx.cs --verify-docfx-build` because it runs DocFX in a temp copy and removes that temp workspace itself. After verification, do not run broad manual cleanup commands such as deleting DocFX directories by name. If `git status` shows remaining files, classify each path first:
-
-- Generated metadata cleanup is limited to DocFX-generated `*.yml`, `.manifest`, and `*.manifest` files under configured metadata destinations.
-- Generated site cleanup is limited to the configured `build.dest` directory when it is clearly generated output and contains no authored Markdown, source, project, solution, or DocFX configuration files.
-- Build artifacts such as `bin/` and `obj/` directories may be cleanup candidates only after confirming they are build output and not documentation source.
-- Authored documentation changes, especially Markdown files included by `build.content` or `build.overwrite`, must be kept and reported as created or updated documentation.
-
-If a cleanup candidate is ambiguous, leave it in place and report the ambiguity instead of deleting it.
-
-If a cleanup command accidentally deletes authored documentation, stop and inspect `git status` and `git diff` before attempting recovery. Do not run broad `git restore`, `git checkout --`, or equivalent whole-directory restores to hide the mistake. Those commands can discard already checked-out documentation work and make the final files worse than before. Recover only the exact files that were incorrectly removed, preserve any edits made earlier in the run, and report the recovery steps honestly.
-
-## Style Rules
-
-Use developer-friendly documentation style.
-
-Prefer:
-
-- Direct explanations,
-- Practical examples,
-- Concrete behavior,
-- Accurate terminology,
-- Small complete samples,
-- Links to related APIs when useful,
-- Namespace-level fly-ins that explain purpose,
-- Purpose-first type/member summaries that explain why a developer would use the API.
-
-Avoid:
-
-- Marketing language,
-- Placeholder text,
-- "Simply",
-- "Just",
-- "Obviously",
-- Pseudo-code,
-- Incomplete snippets,
-- Unverified claims,
-- Duplicating generated API signatures manually,
-- Restating the namespace name without explaining its purpose,
-- Filing-cabinet summaries that only say what a namespace or type contains,
-- Generic verbs like "represents", "provides", or "adds" when they do not explain the API's real role.
-
-## Documentation Workflow
-
-When the user names a changed API or namespace:
-
-1. Run `agents.cs`.
-2. Run the safety gates: capture `git status`, identify existing documentation changes, and avoid broad restore/recovery commands.
-3. Inspect the changed public API.
-4. Determine affected namespaces.
-5. Determine whether public extension methods are involved.
-6. Locate `.docfx/docfx.json` or repository-specific DocFX config.
-7. Locate existing overwrite files and namespace pages.
-8. Locate availability include files.
-9. Locate relevant tests that demonstrate the API.
-10. Convert test usage into real-life documentation examples.
-11. Update XML documentation where needed, especially purpose-first type/member summaries for public entry points and high-traffic APIs.
-12. Update or create namespace overview pages with conceptual orientation and start-here cues.
-13. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
-14. Update extension-member tables.
-15. Update or create overwrite files, including type-page example sections for public non-abstraction types and example sections for public extension methods.
-16. Build an example inventory that maps each required public type and extension method to its example location.
-17. Preserve manual edits.
-18. Run `git diff` for touched documentation paths and confirm the diff is intentional.
-19. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-20. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-21. Run the Completion Repair Loop: rerun `docfx.cs --json`, read remaining diagnostics, repair missing per-type examples and overwrite inclusion issues, update the example inventory, and repeat until required diagnostics are gone or a precise blocker is reported.
-22. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
-23. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
-24. Report verification results.
-
-When no specific API or namespace is named:
-
-1. Run `agents.cs`.
-2. Run the safety gates: capture `git status`, identify existing documentation changes, and avoid broad restore/recovery commands.
-3. Read repository guidance, especially root `AGENTS.md`.
-4. Locate `.docfx/docfx.json` or repository-specific DocFX config.
-5. Read `references/docfx-overwrite-files.md`.
-6. Run `dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --json` to collect deterministic missing-doc findings when the repository is buildable.
-7. If the validator reports multiple diagnostics, rerun it with `--repair-plan <temp-path>/docfx-repair-plan.md`, read that plan, and treat it as the work queue.
-8. If the validator fails before documentation diagnostics can be produced, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
-9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
-10. Determine every public non-abstraction type and every public extension method that requires an example.
-11. Create or update missing namespace overview pages using DocFX overwrite front matter and developer-friendly fly-ins that lead with purpose, use case, and start-here guidance.
-12. Audit related namespace pages together so fixes are consistent across the public API family.
-13. Add or repair `Extension Members` tables for namespaces with public extension methods.
-14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
-15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, using `.docfx/api/namespaces/{TypeUid}.md` in Codebelt repositories unless the repo has a stronger existing convention.
-16. Ensure `docfx.json` keeps `.docfx/api/namespaces/**/*.md` under `build.overwrite` only, excludes `.docfx/api/namespaces/**` from `build.content`, and move legacy authored `.docfx/api/*.md` overwrite files into `.docfx/api/namespaces/` when needed.
-17. Create example sections for public extension methods that have no example yet.
-18. Build an example inventory that maps each required public type and extension method to its example location.
-19. Preserve manual edits and correct stale contradictions instead of replacing whole files.
-20. Run `git diff` for touched documentation paths and confirm the diff is intentional.
-21. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-22. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-23. Run the Completion Repair Loop: rerun `docfx.cs --json`, read remaining diagnostics, repair missing per-type examples and overwrite inclusion issues, update the example inventory, and repeat until required diagnostics are gone or a precise blocker is reported.
-24. Run `docfx.cs --verify-docfx-build` so the DocFX CLI runs against a temp copy of the repository.
-25. Inspect `git status` and confirm no disposable generated DocFX metadata or build output remained in the working tree; preserve authored Markdown and other documentation files.
-26. Report verification results and any remaining findings.
-
-## Namespace Page Template
-
-Use this template when creating a new namespace overview page:
-
-```markdown
----
-uid: X.Y.Z
-summary: *content
----
-The `X.Y.Z` namespace helps you ...
-Use it when ...
-If you're trying to ..., start with `PrimaryType` or `PrimaryExtensions`.
-
-[!INCLUDE [availability-default](../../includes/availability-default.md)]
-
-### Extension Members
-
-|Type|Ext|Methods|
-|--:|:-:|---|
-|String|⬇️|`ExampleMethod`|
-```
-
-Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path based on the actual file location. Mirror the same purpose-first narrative in any nearby type summaries or entry-point member summaries you touch so the namespace page and generated API pages orient readers consistently.
-
-## Type Example Template
-
-Use this shape for public non-abstraction type examples. The overwrite file **must** begin with YAML front matter that maps the body to the `example` property using `example:\n- *content`. This maps the Markdown body to the first slot in the `example` array, which DocFX renders as the "Examples" section **alongside** the auto-generated content (constructors, methods, etc.).
-
-**Critical**: Do NOT use `summary: *content` and do NOT omit the property mapping. Without `example:\n- *content`, the Markdown body maps to the `conceptual` property. In managed reference pages this suppresses the auto-generated API members, leaving only the custom content on the rendered page.
-
-**Do not include a `### Examples` heading inside the body.** DocFX renders the "Examples" section header automatically from the `example` property; adding one manually creates a redundant nested heading.
-
-Put this on the generated type page/overwrite section for the type `uid`; for a public `Class1`, the example belongs on the `Class1` API page, not only on the namespace page. When no type overwrite file exists yet, create a separate per-type file such as `.docfx/api/namespaces/X.Y.Z.Class1.md`. The file location stays under `api/namespaces/`, but the type `uid` still makes the content merge into the generated type page.
-
-````markdown
----
-uid: X.Y.Z.MyType
-example:
-- *content
----
-The following example shows how to use `MyType` in a consuming application.
-
-```csharp
-using X.Y.Z;
-
-var value = new MyType();
-Console.WriteLine(value);
-```
-````
-
-The sample must compile. Do not include `using` directives for namespaces that do not exist. Do not use APIs that are internal to the repository unless the sample is explicitly for contributors and not public API consumers.
-
-## Extension Method Example Template
-
-Use this shape for extension-method examples. Apply the same YAML front matter rule as type examples: use `example:\n- *content` so the body maps to the `example` property and not to `conceptual`. Do not include a `### Examples` heading in the body.
-
-````markdown
----
-uid: X.Y.Z.MyExtensions
-example:
-- *content
----
-The following example shows how to call `NormalizeLineEndings` on a string.
-
-```csharp
-using X.Y.Z;
-
-string text = "first\r\nsecond";
-string normalized = text.NormalizeLineEndings();
-Console.WriteLine(normalized);
-```
-````
-
-The namespace containing the extension method must be imported. The sample must compile in a consuming project.
-
-## Hash-Suffix Filenames Are Prohibited
-
-DocFX generates synthetic UIDs for generic or overloaded extension methods that contain hash fragments, encoding characters, or computed suffixes. These UIDs look like:
-
-```
-Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F
-Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.%3CT%3EWithResponseNegotiator...
-```
-
-**Never create an overwrite file whose name mirrors such a synthetic UID.** That means never creating filenames such as:
-
-- `EndpointConventionBuilderExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md`
-- `EndpointConventionBuilderExtensions.%3CT%3E....md`
-
-DocFX resolves overwrites by the `uid` value in front matter, not by filename. Place the extension method example in the **declaring extension class** overwrite file under `.docfx/api/namespaces/` (for example, `.docfx/api/namespaces/X.Y.Z.EndpointConventionBuilderExtensions.md`) or the namespace page, and use the class or namespace UID in front matter. If a validator reports a hash-suffix method UID, document that method's example in the declaring class file using the class UID — never create a per-method file with the encoded or hashed UID as the filename.
-
-## Verification Checklist
-
-Before completing documentation work, verify:
-
-- [ ] `agents.cs` has run successfully.
-- [ ] `AGENTS.md` contains the managed DocFX documentation maintenance block.
-- [ ] Initial `git status --short` was inspected and existing documentation changes were treated as user work.
-- [ ] For multi-diagnostic audits, `docfx.cs --repair-plan` was written, read, and used as the authoritative work queue.
-- [ ] Only public API is documented.
-- [ ] Every namespace with public API has a namespace overview page.
-- [ ] Related namespace pages in the same public API family were inspected and updated consistently, or intentionally left unchanged with a reason.
-- [ ] Namespaces with public extension methods have an `Extension Members` section.
-- [ ] Extension methods are documented by extended type, not extension class.
-- [ ] Public non-abstraction types have at least one type-page example.
-- [ ] Public extension methods have at least one example, not only a table entry.
-- [ ] An example inventory maps every required public type and extension method to its example file and UID.
-- [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`.
-- [ ] The Completion Repair Loop was run after edits, and remaining `EXAMPLE_MISSING` or overwrite inclusion diagnostics were fixed or reported as exact blockers.
-- [ ] Abstractions without examples have a clear reason.
-- [ ] Examples are realistic and copy/paste-ready.
-- [ ] Examples compile.
-- [ ] Examples are preferably derived from passing tests.
-- [ ] Availability is included or explicitly stated.
-- [ ] Availability matches actual target frameworks and conditions.
-- [ ] Existing manual edits are preserved.
-- [ ] Stale documentation is corrected.
-- [ ] No contradictory documentation remains.
-- [ ] `git diff` for touched documentation paths was inspected before final verification.
-- [ ] `dotnet build` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
-- [ ] `dotnet test` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
-- [ ] `docfx.cs --verify-docfx-build` has run successfully, including the temp-workspace DocFX build, or the failure is reported.
-- [ ] Generated DocFX metadata files and build output directories did not remain in the working tree after verification, and authored Markdown or documentation assets were not deleted as cleanup.
-- [ ] No broad restore or checkout command discarded authored documentation changes.
-
-## Completion Response
-
-When reporting completion, include:
-
-- Public APIs documented,
-- Namespace pages added or updated,
-- Extension-member tables added or updated,
-- Examples added, their source test/sample when applicable, and the example inventory by public type or extension method,
-- Availability handling,
-- Related namespace pages inspected and whether each was updated or left unchanged,
-- `AGENTS.md` created, updated, already compliant, or failed,
-- Signing-key handling: whether a root `.snk` was used/copied or `-p:SkipSignAssembly=true` was used because no root `.snk` was present,
-- Verification commands run,
-- Any verification failures or skipped checks.
-
-Do not claim documentation was verified unless the relevant command actually ran successfully.
+---
+name: dotnet-docfx-digest
+description: >
+  Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including repo-wide no-input audits, concept-led namespace overview pages, purpose-first type/member summaries, extension-member documentation, overwrite files, examples, availability notes, AGENTS.md maintenance, and verification. Use when the user asks to document a .NET API, create or update DocFX documentation, write namespace overview pages, improve API summaries, add extension-method tables, update XML documentation comments, add API examples, maintain DocFX overwrite files, or verify documentation builds. Treat requests like "use dotnet-docfx-digest", "update the DocFX docs", "complete missing documentation", "create namespace pages", "improve these API summaries", "add examples for this type", "update the extension members table", or "verify the documentation builds" as automatic triggers. Also use whenever public .NET API surface changes and documentation needs to stay aligned with source code.
+---
+
+# .NET DocFX Digest Steward
+
+## Description
+
+Create and maintain developer-friendly DocFX documentation digests for .NET public APIs. Keep namespace pages, generated API pages, examples, availability notes, and verification aligned with the actual source code and tests.
+
+## Critical
+
+- This skill is autonomous by default. If the user invokes it without naming a namespace, type, member, or changed API, treat the request as a repo-wide DocFX audit and repair task instead of asking what to document first.
+- Resolve bundled scripts from the loaded `dotnet-docfx-digest` skill directory first. If that install path is unavailable and the target repository contains the repo-managed source copy, fall back to `skills/dotnet-docfx-digest/scripts/*.cs`. Do not claim the scripts are unavailable until both locations have been checked.
+- Before claiming completion, run:
+
+```bash
+dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-root>
+dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --verify-docfx-build
+```
+
+- After edits, run `docfx.cs --json` and treat any remaining diagnostics as the next work queue, not as final notes. For noisy audits, also write and read a deterministic `--repair-plan`.
+- If either script cannot run, report the exact command, exit code, and failure output. Do not claim repository guidance or documentation was verified unless the scripts actually ran successfully.
+- Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape.
+
+## Completion Repair Loop
+
+Do not stop at namespace pages, extension-member tables, or a first-pass documentation edit.
+
+1. Run `docfx.cs --json` after edits and read the remaining diagnostics.
+2. If diagnostics include `EXAMPLE_MISSING`, missing namespace pages, stale extension-member tables, sample compile failures, missing availability, or overwrite inclusion problems, treat them as blocking follow-up work.
+3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/namespaces/`.
+4. For each missing extension-method example, document it on the declaring extension class page or the namespace page, and explicitly demonstrate the method call.
+5. Rerun the validator until the required diagnostics are gone, or stop and report the exact blocker, command, exit code, and remaining diagnostic codes.
+
+Namespace pages and `Extension Members` tables complement type-page examples; they do not replace them.
+
+## Core Principles
+
+Documentation is part of the public contract. When public .NET API changes, update the corresponding XML comments, DocFX overwrite content, namespace pages, examples, availability notes, and verification steps in the same change set.
+
+Document only what the code actually exposes. Do not invent APIs, overloads, target frameworks, behaviors, exceptions, or examples. Verify claims against source code, generated metadata, project files, tests, or existing documentation.
+
+Manual documentation is authoritative context. Preserve hand-written Markdown and overwrite content unless it is stale or incorrect. Prefer additive edits, but fix contradictions instead of appending conflicting prose.
+
+Namespace pages and type pages have different jobs. Namespace pages orient readers to the problem space and where to start; generated type pages explain concrete public APIs and must carry concrete examples for public non-abstraction types.
+
+Write with an inverted-pyramid structure. Lead with the problem solved, explain when to use the API, give a short “start here” cue when helpful, then add structural detail.
+
+## Safety Gates
+
+Before editing documentation:
+
+1. Run `git status --short` and identify modified, staged, and untracked documentation files.
+2. Treat existing uncommitted documentation changes as user work.
+3. Read each Markdown file before editing it.
+4. Classify any cleanup candidate as generated metadata, generated site output, build artifacts, or authored documentation before deleting anything.
+
+Do not use broad `git restore`, `git checkout --`, `git reset`, or whole-directory recovery commands on documentation source directories. If recovery is needed, recover only the specific generated or accidentally removed file after inspecting `git status` and `git diff`.
+
+After modifications, inspect `git diff` for touched documentation paths and confirm the diff contains only intended changes.
+
+## Scope
+
+Apply this skill to:
+
+- public .NET namespaces that contain public API
+- public types and delegates
+- public constructors, properties, methods, fields, events, and enum members
+- public extension methods
+- DocFX overwrite Markdown files
+- namespace overview pages
+- XML documentation comments
+- API examples
+- availability includes or availability statements
+
+Do not document private or internal API, implementation-only helpers, or namespaces that contain no public API.
+
+## DocFX Discovery and Script Usage
+
+For Codebelt repositories, the DocFX workspace is `.docfx` and the configuration file is `.docfx/docfx.json`. For other repositories, locate `docfx.json` before making DocFX-specific changes.
+
+Inspect `docfx.json` before editing so you understand content roots, overwrite file locations, include paths, metadata inputs, and output conventions. When creating or repairing overwrite files, read `references/docfx-overwrite-files.md`. When you need exact CLI arguments, exit codes, JSON diagnostics, or validator behavior for `agents.cs` and `docfx.cs`, read `references/scripts.md`.
+
+Run `agents.cs` against the actual repository root being documented, not a temp workspace or the skill install directory. The script manages a marker-bounded DocFX maintenance block in the repository root `AGENTS.md`; do not hand-edit or duplicate that block.
+
+## Required Documentation Surfaces
+
+When public API is added or materially changed, update every relevant surface:
+
+1. XML documentation comments in source code.
+2. Namespace overview pages for namespaces that contain public API.
+3. `Extension Members` tables for namespaces that expose public extension methods.
+4. Type-targeting overwrite content for public non-abstraction types that require examples or richer guidance.
+5. Extension-method examples on the declaring extension class page or the namespace page.
+6. Availability information.
+7. Verification commands or artifacts that prove the documentation remains accurate and buildable.
+
+Material changes include new or removed public API, signature or nullability changes, behavioral changes, exception changes, changed availability, conditional extension-method availability, deprecation changes, default-value changes, or meaningful lifecycle and thread-safety changes.
+
+## Examples and Overwrites
+
+Every public non-abstraction type and every public extension method needs at least one realistic, minimal, copy/paste-ready example. A namespace fly-in or `Extension Members` table alone is not enough.
+
+Prefer examples derived from existing unit, functional, or integration tests, then from samples, then from a minimal new example based on actual public behavior. Convert Arrange/Act/Assert test structure into consumer-oriented sample code instead of pasting raw assertions.
+
+For public non-abstraction types, put the example on the generated type page by targeting the type UID in DocFX overwrite content. In Codebelt repositories, keep authored overwrite Markdown under `.docfx/api/namespaces/`, typically as `.docfx/api/namespaces/{TypeUid}.md`.
+
+For public extension methods, place examples on the declaring extension class page or the namespace page. The example must explicitly call the method.
+
+Never mirror synthetic method UIDs that contain hashes, encoding, or generated suffixes in filenames. Keep filenames readable and let the YAML `uid` decide what DocFX model the content targets.
+
+Keep `api/namespaces/**/*.md` under `build.overwrite` only, exclude `api/namespaces/**` from `build.content`, and do not widen either entry to `api/**/*.md`. Move legacy authored `.docfx/api/*.md` overwrite files into `.docfx/api/namespaces/` instead of widening the glob.
+
+For managed reference pages, map type and extension-method examples to the `example` property rather than to `summary` or implicit conceptual content. Read `references/docfx-overwrite-files.md` for the exact front-matter shape.
+
+## Example Verification
+
+Every added or changed C# sample must compile. The validator compiles documentation samples as .NET 10 file-based apps.
+
+Use a skip marker only when compilation is genuinely impossible in deterministic validation:
+
+```csharp
+// dotnet-docfx-digest:skip-compile - <reason>
+```
+
+The reason is mandatory and must explain the actual blocker. Reasons such as “full example requires package X” or “shows the framework pattern” are insufficient. Prefer making the sample compile by adding normal public setup code or reducing the sample to the smallest compiling example.
+
+Do not claim a sample compiles unless the validator or an equivalent repository verification command compiled it successfully.
+
+## Namespace and Summary Style
+
+Namespace overview pages must explain what problem the namespace solves, when to use it, and where a newcomer should start. Avoid inventory-only blurbs such as “contains types and extension methods for...”
+
+Type and member summaries should explain the API’s job in consumer terms. Prefer purpose-first summaries for entry points, builders, factories, options, and extension methods. Avoid empty labels such as “represents options” or “adds services” unless the rest of the sentence explains the actual outcome enabled.
+
+If one namespace page in a public API family needs repair, inspect sibling namespace pages in that family before finishing and keep them consistent. If you intentionally leave a sibling page unchanged, say why.
+
+## XML Documentation Comments
+
+Public API should have useful XML comments. Keep source summaries concise and move longer examples or remarks into DocFX overwrite content when that keeps the source readable.
+
+XML comments should cover purpose, parameters, return value, exceptions, type parameters, important behavior, nullability expectations, and lifecycle or thread-safety details when relevant.
+
+## Cleanup Boundary
+
+Authored DocFX Markdown is documentation output, not disposable build output. Do not delete `.md` or `.mdoc` files, `docfx.json`, `toc.yml`, includes, images, examples, or directories that contain authored documentation while cleaning generated artifacts unless the user explicitly asks for that deletion.
+
+Prefer `docfx.cs --verify-docfx-build` because it builds DocFX in a temp copy and cleans that workspace itself. If `git status` still shows leftover generated files afterward, classify each path before deleting it. Generated metadata cleanup is limited to DocFX-generated `*.yml`, `.manifest`, and `*.manifest` files under configured metadata destinations. Generated site cleanup is limited to the configured build output directory when that directory is clearly generated output and contains no authored Markdown, source, project, solution, or DocFX configuration files.
+
+If a cleanup candidate is ambiguous, leave it in place and report the ambiguity instead of deleting it.
+
+## Codebelt Signing Keys
+
+Codebelt solutions are normally strong-name signed with a repository-root `.snk` file. Preserve and copy that file when it exists. If a Codebelt repository or temp copy does not contain the root `.snk`, use the skip-sign fallback for verification commands:
+
+```bash
+dotnet build -p:SkipSignAssembly=true
+dotnet test -p:SkipSignAssembly=true
+```
+
+Use the same fallback for equivalent builds triggered by documentation validation so missing local signing keys do not masquerade as documentation failures.
+
+## Workflow Summary
+
+When the user names a changed API or namespace:
+
+1. Run `agents.cs`.
+2. Run the safety gates and inspect existing documentation edits.
+3. Inspect the changed public API, affected namespaces, availability inputs, tests, samples, and current overwrite files.
+4. Update XML comments, namespace pages, extension-member tables, examples, and availability notes as required.
+5. Build an example inventory for required public concrete types and extension methods.
+6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run `docfx.cs --verify-docfx-build`.
+
+When the user does not name a specific target:
+
+1. Run `agents.cs`.
+2. Run the safety gates and inspect repository guidance.
+3. Inspect DocFX configuration, overwrite files, tests, samples, and current documentation state.
+4. Run `docfx.cs --json`, and for multi-diagnostic output rerun with `--repair-plan` and use that plan as the work queue.
+5. Repair missing namespace pages, extension-member tables, examples, overwrite layout, summaries, and availability notes that can be derived from evidence.
+6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run `docfx.cs --verify-docfx-build`.
+
+Read `references/workflow.md` before creating new namespace pages, writing type or extension examples, preparing the final verification checklist, or shaping the completion response.
+
+## Reference Files
+
+- `references/workflow.md` — detailed targeted/audit workflows, example inventory shape, templates, verification checklist, and completion response.
+- `references/docfx-overwrite-files.md` — overwrite-file model rules, `example: - *content` usage, and Codebelt overwrite layout guidance.
+- `references/scripts.md` — exact `agents.cs` and `docfx.cs` commands, arguments, exit codes, diagnostics, and validator behavior.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 1b04969..4538ada 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -93,13 +93,14 @@
     },
     {
       "id": 8,
-      "prompt": "Run dotnet-docfx-digest validation with `--changed-only` after I added a new public concrete type `Acme.Http.RetryPolicy` and a public extension method `WithRetry(this HttpClient client, int attempts)`, but I still have not added the required overwrite examples. Git is available and only the changed source files, the namespace page, and docfx.json should be considered.",
-      "expected_output": "Agent runs scripts/docfx.cs with --changed-only and still surfaces EXAMPLE_MISSING for the affected changed public APIs instead of skipping required-example validation wholesale. It scopes the check to the changed APIs and related DocFX inputs, explains which examples are still missing, and uses --verify-docfx-build before claiming the docs are verified.",
+      "prompt": "Run dotnet-docfx-digest validation with `--changed-only` after I added a new public concrete type `Acme.Http.RetryPolicy` and a public extension method `WithRetry(this HttpClient client, int attempts)`. I also created a brand-new untracked overwrite file `.docfx/api/namespaces/Acme.Http.RetryPolicy.md`, but its C# example still does not compile and I have not run `git add` yet.",
+      "expected_output": "Agent runs scripts/docfx.cs with --changed-only and still validates the new untracked overwrite file instead of skipping it because git has not started tracking it yet. It surfaces SAMPLE_COMPILE_FAILED for the broken C# sample, still scopes the check to the changed APIs and related DocFX inputs, and uses --verify-docfx-build before claiming the docs are verified.",
       "expectations": [
         "Runs scripts/docfx.cs with --changed-only when collecting incremental findings",
-        "Still surfaces EXAMPLE_MISSING for the changed concrete type and extension method when their overwrite examples are absent",
-        "Does not silently skip all required-example validation just because git returned a changed file set",
-        "Scopes the example validation to changed APIs or related DocFX inputs rather than re-reporting the whole repository by default",
+        "Includes the new untracked `.docfx/api/namespaces/Acme.Http.RetryPolicy.md` file in the changed-file scope even though it has not been staged or committed",
+        "Surfaces SAMPLE_COMPILE_FAILED for the broken sample in the untracked overwrite file instead of silently skipping it",
+        "Does not silently skip changed-only sample validation just because git returned only tracked changes in `git diff`",
+        "Scopes the example and sample validation to changed APIs or related DocFX inputs rather than re-reporting the whole repository by default",
         "Uses --verify-docfx-build before claiming final verification"
       ]
     },
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 34d873a..f83103b 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -58,7 +58,7 @@ dotnet run --file docfx.cs -- --repo-root . --configuration Debug --framework ne
 
 Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--framework`, `--validate-samples` / `--no-validate-samples` (default on), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
-`--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
+`--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
 `--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, a required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/namespaces/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics keep `api/namespaces/**/*.md` under `build.overwrite` only while moving legacy `.docfx/api/*.md` authored overwrite files into `.docfx/api/namespaces/`. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
new file mode 100644
index 0000000..2b0a20c
--- /dev/null
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -0,0 +1,196 @@
+# dotnet-docfx-digest workflow reference
+
+Use this reference when you need the full step-by-step workflow, example inventory shape, ready-to-adapt templates, or the final completion checklist.
+
+## Example inventory shape
+
+Build a small example inventory from validator output and source evidence before writing examples. Treat it as a work queue, not as final-response prose.
+
+```markdown
+| UID | Kind | Required example location | Source evidence | Status |
+|---|---|---|---|---|
+| Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | ApplicationHostFactoryTest | Missing |
+```
+
+Do not mark an item complete until the overwrite section targets the correct UID or approved extension-method location, the file is included by `build.overwrite`, the sample compiles or has a justified skip marker, and `docfx.cs --json` no longer reports the relevant missing-example diagnostic.
+
+## Targeted workflow
+
+Use this path when the user names a changed API or namespace.
+
+1. Run `agents.cs`.
+2. Run the safety gates: inspect `git status --short`, identify existing documentation work, and avoid broad restore or recovery commands.
+3. Inspect the changed public API and determine affected namespaces.
+4. Determine whether public extension methods are involved.
+5. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
+6. Locate existing overwrite files, namespace pages, availability includes, tests, and samples.
+7. Convert test usage into consumer-oriented examples when relevant.
+8. Update XML documentation comments where purpose-first summaries are needed.
+9. Update or create namespace overview pages with conceptual orientation and start-here cues.
+10. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
+11. Update `Extension Members` tables when public extension methods are involved.
+12. Update or create overwrite content, including type-page examples for public non-abstraction types and explicit examples for public extension methods.
+13. Build or refresh the example inventory.
+14. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+15. Run `git diff` for touched documentation paths and confirm the diff is intentional.
+16. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+17. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+18. Run the Completion Repair Loop by rerunning `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
+19. Run `docfx.cs --verify-docfx-build` so DocFX builds in a temp copy.
+20. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
+21. Report verification results and any remaining deterministic findings.
+
+## Repo-wide audit workflow
+
+Use this path when the user invokes the skill without naming a specific API or namespace.
+
+1. Run `agents.cs`.
+2. Run the safety gates: inspect `git status --short`, identify existing documentation work, and avoid broad restore or recovery commands.
+3. Read repository guidance, especially root `AGENTS.md`.
+4. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
+5. Read `references/docfx-overwrite-files.md`.
+6. Run `docfx.cs --json` to collect deterministic findings when the repository is buildable.
+7. If the validator reports more than a small number of diagnostics, rerun it with `--repair-plan <temp-path>/docfx-repair-plan.md`, read that plan, and use it as the authoritative work queue.
+8. If the validator fails before producing documentation diagnostics, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
+9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
+10. Determine every public non-abstraction type and every public extension method that requires an example.
+11. Create or update missing namespace overview pages with purpose-first fly-ins and start-here guidance.
+12. Audit related namespace pages together so fixes are consistent across the public API family.
+13. Add or repair `Extension Members` tables for namespaces with public extension methods.
+14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
+15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, normally under `.docfx/api/namespaces/{TypeUid}.md` in Codebelt repositories.
+16. Ensure `docfx.json` keeps `.docfx/api/namespaces/**/*.md` under `build.overwrite`, excludes `.docfx/api/namespaces/**` from `build.content`, and moves legacy authored `.docfx/api/*.md` files into `.docfx/api/namespaces/` when needed.
+17. Create explicit examples for public extension methods that still have none.
+18. Build or refresh the example inventory.
+19. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+20. Run `git diff` for touched documentation paths and confirm the diff is intentional.
+21. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+22. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+23. Run the Completion Repair Loop by rerunning `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
+24. Run `docfx.cs --verify-docfx-build` so DocFX builds in a temp copy.
+25. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
+26. Report verification results and any remaining deterministic findings.
+
+## Namespace page template
+
+Use this template when creating a new namespace overview page:
+
+```markdown
+---
+uid: X.Y.Z
+summary: *content
+---
+The `X.Y.Z` namespace helps you ...
+Use it when ...
+If you're trying to ..., start with `PrimaryType` or `PrimaryExtensions`.
+
+[!INCLUDE [availability-default](../../includes/availability-default.md)]
+
+### Extension Members
+
+|Type|Ext|Methods|
+|--:|:-:|---|
+|String|⬇️|`ExampleMethod`|
+```
+
+Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path to match the actual file location.
+
+## Type example template
+
+For public non-abstraction types, begin the overwrite file with front matter that maps the body to the `example` property:
+
+````markdown
+---
+uid: X.Y.Z.MyType
+example:
+- *content
+---
+The following example shows how to use `MyType` in a consuming application.
+
+```csharp
+using X.Y.Z;
+
+var value = new MyType();
+Console.WriteLine(value);
+```
+````
+
+Do not include a manual `### Examples` heading in the body. DocFX renders that heading automatically for the `example` property.
+
+## Extension method example template
+
+Apply the same `example: - *content` rule for extension-method examples:
+
+````markdown
+---
+uid: X.Y.Z.MyExtensions
+example:
+- *content
+---
+The following example shows how to call `NormalizeLineEndings` on a string.
+
+```csharp
+using X.Y.Z;
+
+string text = "first\r\nsecond";
+string normalized = text.NormalizeLineEndings();
+Console.WriteLine(normalized);
+```
+````
+
+The namespace containing the extension method must be imported, and the sample must compile in a consumer-style context.
+
+## Synthetic hash-suffix filenames are prohibited
+
+DocFX can generate synthetic method UIDs for generic or overloaded extension methods that contain hashes, encoding characters, or computed suffixes. Never mirror those UIDs directly in filenames.
+
+Bad examples:
+
+- `EndpointConventionBuilderExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md`
+- `EndpointConventionBuilderExtensions.%3CT%3E...md`
+
+Keep the filename readable, place the example in the declaring extension class file or the namespace page, and let the YAML `uid` determine what model receives the content.
+
+## Verification checklist
+
+Before completing documentation work, verify:
+
+- [ ] `agents.cs` ran successfully.
+- [ ] `AGENTS.md` contains the managed DocFX maintenance block.
+- [ ] Initial `git status --short` was inspected and existing documentation changes were treated as user work.
+- [ ] For multi-diagnostic audits, `docfx.cs --repair-plan` was written, read, and used as the work queue.
+- [ ] Only public API is documented.
+- [ ] Every namespace with public API has a namespace overview page.
+- [ ] Related namespace pages in the same public API family were inspected and updated consistently, or intentionally left unchanged with a reason.
+- [ ] Namespaces with public extension methods have an `Extension Members` section.
+- [ ] Public non-abstraction types have at least one type-page example.
+- [ ] Public extension methods have at least one explicit example, not only a table entry.
+- [ ] The example inventory maps each required public type and extension method to its example file and UID.
+- [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`.
+- [ ] The Completion Repair Loop was run after edits, and remaining `EXAMPLE_MISSING` or overwrite-layout diagnostics were fixed or reported as exact blockers.
+- [ ] Examples are realistic, copy/paste-ready, and compile unless a justified skip marker is present.
+- [ ] Availability is included or explicitly stated and matches actual target frameworks and conditions.
+- [ ] Existing manual edits are preserved, stale documentation is corrected, and no contradictory documentation remains.
+- [ ] `git diff` for touched documentation paths was inspected before final verification.
+- [ ] `dotnet build` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
+- [ ] `dotnet test` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
+- [ ] `docfx.cs --verify-docfx-build` ran successfully, or the failure is reported.
+- [ ] Generated metadata files and build output directories did not remain in the working tree after verification, and authored Markdown or documentation assets were not deleted as cleanup.
+- [ ] No broad restore or checkout command discarded authored documentation changes.
+
+## Completion response
+
+When reporting completion, include:
+
+- public APIs documented
+- namespace pages added or updated
+- extension-member tables added or updated
+- examples added, their source test or sample when applicable, and the example inventory by public type or extension method
+- availability handling
+- related namespace pages inspected and whether each was updated or left unchanged
+- `AGENTS.md` created, updated, already compliant, or failed
+- signing-key handling: whether a root `.snk` was used or `-p:SkipSignAssembly=true` was used because no root `.snk` was present
+- verification commands run
+- any verification failures or skipped checks
+
+Do not claim documentation was verified unless the relevant command actually ran successfully.
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 5c4be8f..c4a9951 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -2379,6 +2379,17 @@ private static bool IsInsufficientSkipReason(string reason)
             set.Add(Path.GetFullPath(Path.Combine(repoRoot, line)));
         }
 
+        // Include untracked files so --changed-only still validates samples in new
+        // documentation files that have not been staged yet.
+        var untracked = RunProcess("git", "ls-files --others --exclude-standard", repoRoot);
+        if (untracked.ExitCode == 0)
+        {
+            foreach (var line in untracked.StdOut.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+            {
+                set.Add(Path.GetFullPath(Path.Combine(repoRoot, line)));
+            }
+        }
+
         return set;
     }
 

From 8bf800981aa3ebb10b121d20df7dab53ccaaa6c0 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 19:01:20 +0200
Subject: [PATCH 37/88] =?UTF-8?q?=F0=9F=92=AC=20update=20README=20with=20d?=
 =?UTF-8?q?otnet-docfx-digest=20updates?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refine dotnet-docfx-digest skill description in Available Skills table to reflect script enhancements and validation improvements.
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 644e6b5..576df13 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, Codebelt namespace-folder overwrite layout (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and C# documentation samples, keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown so new samples compile before staging, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, and managed-reference-safe completion gates for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, Codebelt namespace-folder overwrite layout (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and C# documentation samples, keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown so new samples compile before staging, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, and managed-reference-safe completion gates for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -542,7 +542,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
-- **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/namespaces/`, legacy authored `.docfx/api/*.md` overwrite files are moved into that folder instead of widening the glob to `api/**/*.md`, `api/namespaces/**/*.md` stays under `build.overwrite` only while `build.content` excludes `api/namespaces/**`, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
+- **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/namespaces/`, legacy authored `.docfx/api/*.md` overwrite files are moved into that folder instead of widening the glob to `api/**/*.md`, `api/namespaces/**/*.md` stays under `build.overwrite` only while `build.content` excludes `api/namespaces/**`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
 - **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,

From c0ac53a5b3e02ef5adf4c9ba7e006da03b267d3f Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 19:01:28 +0200
Subject: [PATCH 38/88] =?UTF-8?q?=E2=9C=85=20enhance=20docfx=20validation?=
 =?UTF-8?q?=20and=20evals?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Improve docfx.cs with refined example validation scope to include new untracked overwrite Markdown during changed-only mode, ensuring samples compile before staging. Expand evals expectations to cover enhanced validation scenarios and validation edge cases.
---
 skills/dotnet-docfx-digest/evals/evals.json | 12 ++++
 skills/dotnet-docfx-digest/scripts/docfx.cs | 69 ++++++++++++++++++---
 2 files changed, 73 insertions(+), 8 deletions(-)

diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 4538ada..4077f34 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -234,6 +234,18 @@
         "Keeps the summaries grounded in actual public API behavior rather than inventing capabilities or marketing language",
         "Applies the same conceptual-orientation pattern consistently across the namespace page and the touched API summaries"
       ]
+    },
+    {
+      "id": 19,
+      "prompt": "Run dotnet-docfx-digest with `--changed-only` after I edited a C# 14 extension-block file in the `Codebelt.Extensions.Carter` namespace: `public static class EndpointConventionBuilderExtensions { extension(IEndpointConventionBuilder builder) { public IEndpointConventionBuilder Produces<TResponse>(int statusCode = StatusCodes.Status200OK, params string[] contentTypes) { ... } } }`. The previous run created `.docfx/api/namespaces/EndpointConventionBuilderExtensions.Produces-extensions.md` whose YAML `uid` is `Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.<G>$6D0D8037DBBD61D10816ECA5F93B896F`, and the namespace page still needs a real extension-method example.",
+      "expected_output": "Agent treats the compiler-generated `<G>$...` container as an implementation artifact of the outer `EndpointConventionBuilderExtensions` type, so the repair path stays on readable declaring-class or namespace overwrite pages. `--changed-only` still notices the edited extension-block source file, surfaces the missing example work, and avoids treating the synthetic nested type as a standalone documented API target.",
+      "expectations": [
+        "Collapses compiler-generated extension-block containers such as `<G>$...` back to the authored outer static class when choosing extension-method example targets",
+        "Does not treat the synthetic nested extension-block type as a required public type example target",
+        "Keeps the required example location on a readable declaring-class overwrite page or the namespace page instead of a synthetic method/type UID file",
+        "Under `--changed-only`, recognizes the edited extension-block source file as touching the `Produces` extension method even though the method declaration no longer uses `this` syntax",
+        "Still reports missing extension-method examples until a readable declaring-class or namespace overwrite file explicitly calls `Produces`"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index c4a9951..2f48776 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -1625,15 +1625,20 @@ private static void AddDepsRuntimeResolverPaths(JsonProperty dependency, List<st
 
     private static void CollectApiTargets(Type type, NamespaceInfo ns)
     {
-        var typeUid = TypeUid(type);
+        var documentedType = DocumentedApiOwnerType(type);
+        var typeUid = TypeUid(documentedType);
         if (typeUid is null)
         {
             return;
         }
 
-        if (IsExampleRequiredType(type))
+        if (ReferenceEquals(documentedType, type) && IsExampleRequiredType(documentedType))
         {
-            ns.RequiredExampleTargets.Add(new ApiTargetInfo(typeUid, ns.Name, ApiTargetKind.Type, SimpleTypeName(type)));
+            var typeTarget = new ApiTargetInfo(typeUid, ns.Name, ApiTargetKind.Type, SimpleTypeName(documentedType));
+            if (!ns.RequiredExampleTargets.Contains(typeTarget))
+            {
+                ns.RequiredExampleTargets.Add(typeTarget);
+            }
         }
 
         MethodInfo[] methods;
@@ -1653,18 +1658,24 @@ private static void CollectApiTargets(Type type, NamespaceInfo ns)
                 continue;
             }
 
-            ns.RequiredExampleTargets.Add(new ApiTargetInfo(MethodUid(typeUid, method), ns.Name, ApiTargetKind.ExtensionMethod, method.Name, typeUid));
+            var methodTarget = new ApiTargetInfo(MethodUid(typeUid, method), ns.Name, ApiTargetKind.ExtensionMethod, method.Name, typeUid);
+            if (!ns.RequiredExampleTargets.Contains(methodTarget))
+            {
+                ns.RequiredExampleTargets.Add(methodTarget);
+            }
         }
     }
 
     private static void CollectExtensionMethods(Type type, NamespaceInfo ns)
     {
-        // A public extension method lives on a public static (abstract+sealed) non-generic class.
-        if (!type.IsClass || !type.IsAbstract || !type.IsSealed || type.IsGenericType || !type.IsPublic)
+        if (!type.IsClass || type.IsGenericType || !IsExternallyVisible(type))
         {
             return;
         }
 
+        var documentedType = DocumentedApiOwnerType(type);
+        var declaringClass = SimpleTypeName(documentedType);
+
         MethodInfo[] methods;
         try
         {
@@ -1694,8 +1705,48 @@ private static void CollectExtensionMethods(Type type, NamespaceInfo ns)
             }
 
             var extendedType = SimpleTypeName(parameters[0].ParameterType);
-            ns.ExtensionMethods.Add(new ExtensionMethodInfo(method.Name, extendedType, type.Name));
+            var extensionInfo = new ExtensionMethodInfo(method.Name, extendedType, declaringClass);
+            if (!ns.ExtensionMethods.Contains(extensionInfo))
+            {
+                ns.ExtensionMethods.Add(extensionInfo);
+            }
+        }
+    }
+
+    private static Type DocumentedApiOwnerType(Type type)
+    {
+        while (IsSyntheticExtensionBlockContainer(type))
+        {
+            type = type.DeclaringType!;
+        }
+
+        return type;
+    }
+
+    private static bool IsSyntheticExtensionBlockContainer(Type type)
+    {
+        if (!type.IsNested || !type.Name.StartsWith("<", StringComparison.Ordinal) || type.DeclaringType is null)
+        {
+            return false;
         }
+
+        var declaringType = type.DeclaringType;
+        if (!declaringType.IsClass || !declaringType.IsAbstract || !declaringType.IsSealed || !IsExternallyVisible(declaringType))
+        {
+            return false;
+        }
+
+        MethodInfo[] methods;
+        try
+        {
+            methods = type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly);
+        }
+        catch
+        {
+            return false;
+        }
+
+        return methods.Any(HasExtensionAttribute);
     }
 
     private static bool HasExtensionAttribute(MemberInfo member)
@@ -2077,7 +2128,9 @@ private static bool ChangedSourceTouchesTarget(string path, ApiTargetInfo target
                 $@"(?m)\b(?:class|struct|interface|enum|delegate|record(?:\s+class|\s+struct)?)\s+{Regex.Escape(target.DisplayName)}\b");
         }
 
-        return Regex.IsMatch(sourceText, $@"(?s)\b{Regex.Escape(target.DisplayName)}\s*\([^)]*\bthis\b");
+        return Regex.IsMatch(sourceText, $@"(?s)\b{Regex.Escape(target.DisplayName)}\s*\([^)]*\bthis\b") ||
+               Regex.IsMatch(sourceText,
+                   $@"(?s)\bextension\s*\([^)]*\)\s*\{{.*?\b{Regex.Escape(target.DisplayName)}(?:\s*<[^>\r\n]+>)?\s*\(");
     }
 
     private static bool IsExampleCandidate(OverwriteSection section, ApiTargetInfo target)

From c600c4daae6856ba9b2f5f1d4cadbd6f90b5693c Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 19:41:30 +0200
Subject: [PATCH 39/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20implementation=20and=20contracts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Improve SKILL.md clarity and precision. Expand evals with comprehensive validation scenarios and edge cases. Enhance references with detailed scripts and workflow guidance. Refine agents.cs and docfx.cs scripts with improved logic, better error handling, and enhanced validation capabilities.
---
 skills/dotnet-docfx-digest/SKILL.md           |  14 ++-
 skills/dotnet-docfx-digest/evals/evals.json   | 112 ++++++++++++++++++
 .../dotnet-docfx-digest/references/scripts.md |  12 +-
 .../references/workflow.md                    |   8 +-
 skills/dotnet-docfx-digest/scripts/agents.cs  |  52 ++++----
 skills/dotnet-docfx-digest/scripts/docfx.cs   |  76 ++++++++++--
 6 files changed, 226 insertions(+), 48 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 79af450..c93cdb6 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -31,11 +31,11 @@ Do not stop at namespace pages, extension-member tables, or a first-pass documen
 
 1. Run `docfx.cs --json` after edits and read the remaining diagnostics.
 2. If diagnostics include `EXAMPLE_MISSING`, missing namespace pages, stale extension-member tables, sample compile failures, missing availability, or overwrite inclusion problems, treat them as blocking follow-up work.
-3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/namespaces/`.
+3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/types/`.
 4. For each missing extension-method example, document it on the declaring extension class page or the namespace page, and explicitly demonstrate the method call.
 5. Rerun the validator until the required diagnostics are gone, or stop and report the exact blocker, command, exit code, and remaining diagnostic codes.
 
-Namespace pages and `Extension Members` tables complement type-page examples; they do not replace them.
+Namespace pages and `Extension Members` tables complement type-page examples; they do not replace them. Both namespace pages (`api/namespaces/`) and type pages (`api/types/`) are required deliverables. Generating only one is incomplete work.
 
 ## Core Principles
 
@@ -91,13 +91,15 @@ Run `agents.cs` against the actual repository root being documented, not a temp
 When public API is added or materially changed, update every relevant surface:
 
 1. XML documentation comments in source code.
-2. Namespace overview pages for namespaces that contain public API.
+2. Namespace overview pages for namespaces that contain public API, under `.docfx/api/namespaces/`.
 3. `Extension Members` tables for namespaces that expose public extension methods.
-4. Type-targeting overwrite content for public non-abstraction types that require examples or richer guidance.
+4. Type-targeting overwrite content for public non-abstraction types that require examples or richer guidance, under `.docfx/api/types/`.
 5. Extension-method examples on the declaring extension class page or the namespace page.
 6. Availability information.
 7. Verification commands or artifacts that prove the documentation remains accurate and buildable.
 
+Namespace pages and type pages are both required deliverables in the same run. Do not generate namespace pages without type pages or vice versa.
+
 Material changes include new or removed public API, signature or nullability changes, behavioral changes, exception changes, changed availability, conditional extension-method availability, deprecation changes, default-value changes, or meaningful lifecycle and thread-safety changes.
 
 ## Examples and Overwrites
@@ -106,13 +108,13 @@ Every public non-abstraction type and every public extension method needs at lea
 
 Prefer examples derived from existing unit, functional, or integration tests, then from samples, then from a minimal new example based on actual public behavior. Convert Arrange/Act/Assert test structure into consumer-oriented sample code instead of pasting raw assertions.
 
-For public non-abstraction types, put the example on the generated type page by targeting the type UID in DocFX overwrite content. In Codebelt repositories, keep authored overwrite Markdown under `.docfx/api/namespaces/`, typically as `.docfx/api/namespaces/{TypeUid}.md`.
+For public non-abstraction types, put the example on the generated type page by targeting the type UID in DocFX overwrite content. In Codebelt repositories, keep authored type overwrite Markdown under `.docfx/api/types/`, typically as `.docfx/api/types/{TypeUid}.md`.
 
 For public extension methods, place examples on the declaring extension class page or the namespace page. The example must explicitly call the method.
 
 Never mirror synthetic method UIDs that contain hashes, encoding, or generated suffixes in filenames. Keep filenames readable and let the YAML `uid` decide what DocFX model the content targets.
 
-Keep `api/namespaces/**/*.md` under `build.overwrite` only, exclude `api/namespaces/**` from `build.content`, and do not widen either entry to `api/**/*.md`. Move legacy authored `.docfx/api/*.md` overwrite files into `.docfx/api/namespaces/` instead of widening the glob.
+Keep `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` only. Exclude both `api/namespaces/**` and `api/types/**` from `build.content`. Do not widen either entry to `api/**/*.md`. Move legacy authored `.docfx/api/*.md` overwrite files into either `api/namespaces/` (for namespace pages) or `api/types/` (for type pages) instead of widening the glob.
 
 For managed reference pages, map type and extension-method examples to the `example` property rather than to `summary` or implicit conceptual content. Read `references/docfx-overwrite-files.md` for the exact front-matter shape.
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 4077f34..bad0ef3 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -246,6 +246,118 @@
         "Under `--changed-only`, recognizes the edited extension-block source file as touching the `Produces` extension method even though the method declaration no longer uses `this` syntax",
         "Still reports missing extension-method examples until a readable declaring-class or namespace overwrite file explicitly calls `Produces`"
       ]
+    },
+    {
+      "id": 20,
+      "prompt": "Use dotnet-docfx-digest on a .NET library where the namespace `Acme.Core` contains a plain class `Options`, an enum `LogLevel`, a public struct `Range`, a public record `Result`, and a generic class `Repository<T>`. The library also has a static extension class `StringExtensions` with generic method `Parse<T>(this string input)`. The namespace currently has no DocFX documentation at all.",
+      "expected_output": "Agent generates both a namespace overview page at `.docfx/api/namespaces/Acme.Core.md` and type-targeting overwrite files at `.docfx/api/types/Acme.Core.Options.md`, `.docfx/api/types/Acme.Core.LogLevel.md`, `.docfx/api/types/Acme.Core.Range.md`, `.docfx/api/types/Acme.Core.Result.md`, `.docfx/api/types/Acme.Core.Repository.md`, and `.docfx/api/types/Acme.Core.StringExtensions.md` in the same run. The generic `Repository<T>` and generic extension method `Parse<T>` are included as valid documentation targets. Both `api/namespaces/**/*.md` and `api/types/**/*.md` are added under `build.overwrite`, and both directories are excluded from `build.content`.",
+      "expectations": [
+        "Generates the namespace overview page at `.docfx/api/namespaces/Acme.Core.md` with a uid front matter matching the namespace",
+        "Generates type overwrite files under `.docfx/api/types/` for every public non-abstraction type including Options, LogLevel, Range, Result, and Repository",
+        "Includes the generic class `Repository<T>` as a valid documentation target and does not skip it",
+        "Generates a type overwrite file for `StringExtensions` as a static extension container",
+        "Includes the generic extension method `Parse<T>` in the Extension Members table on the namespace page",
+        "Adds both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` in docfx.json",
+        "Excludes both `api/namespaces/**` and `api/types/**` from `build.content` in docfx.json",
+        "Does not treat namespace generation and type generation as mutually exclusive"
+      ]
+    },
+    {
+      "id": 21,
+      "prompt": "Use dotnet-docfx-digest on a .NET library containing a public abstract base class `ValidatorBase` and a public interface `IValidator<T>`. The same namespace also has a concrete class `EmailValidator` that extends `ValidatorBase` and a static class `ValidatorExtensions` with extension methods.",
+      "expected_output": "Agent excludes `ValidatorBase` and `IValidator<T>` from required example targets because they are an abstract base class and an interface respectively. It does include `EmailValidator` and `ValidatorExtensions` as documentation targets. The type overwrite files are created only for `EmailValidator` and `ValidatorExtensions` under `.docfx/api/types/`.",
+      "expectations": [
+        "Does not create a required example target for `ValidatorBase` because it is an abstract base class",
+        "Does not create a required example target for `IValidator<T>` because it is an interface",
+        "Creates a required example target for the concrete class `EmailValidator`",
+        "Creates a required example target for `ValidatorExtensions` as a static extension container",
+        "Places type overwrite files under `.docfx/api/types/` only for included types"
+      ]
+    },
+    {
+      "id": 22,
+      "prompt": "Use dotnet-docfx-digest on a library where `docfx.json` currently has only `api/namespaces/**/*.md` under `build.overwrite` and only `api/namespaces/**` excluded from `build.content`. This is the first run for this repository.",
+      "expected_output": "Agent updates `docfx.json` on the first run to add `api/types/**/*.md` under `build.overwrite` and `api/types/**` to the `build.content` exclusions. It also creates the namespace overwrite pages and type overwrite pages in the same run. Running the skill a second time produces no further changes to `docfx.json`.",
+      "expectations": [
+        "Updates `docfx.json` to include `api/types/**/*.md` under `build.overwrite`",
+        "Updates `docfx.json` to exclude `api/types/**` from `build.content`",
+        "Creates namespace pages under `.docfx/api/namespaces/` and type pages under `.docfx/api/types/` in the same run",
+        "A second run does not change `docfx.json` again because it is already compliant",
+        "Does not use `api/**/*.md` as a catch-all pattern"
+      ]
+    },
+    {
+      "id": 23,
+      "prompt": "Use dotnet-docfx-digest on a library where a previous run created type overwrite files under `.docfx/api/namespaces/Acme.Core.MyType.md` (the old single-directory convention). The new convention places type overwrite files under `.docfx/api/types/`. Migrate the repository to the new convention.",
+      "expected_output": "Agent moves the type overwrite file from `.docfx/api/namespaces/Acme.Core.MyType.md` to `.docfx/api/types/Acme.Core.MyType.md`, preserves the YAML front matter and example content, updates `docfx.json` to include both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite`, and excludes `api/types/**` from `build.content`. The namespace page `Acme.Core.md` remains in `api/namespaces/`.",
+      "expectations": [
+        "Moves type overwrite files from `api/namespaces/` to `api/types/` when they contain a type UID rather than a namespace UID",
+        "Keeps namespace overview pages under `api/namespaces/`",
+        "Preserves YAML front matter and Markdown content when moving files",
+        "Updates `docfx.json` to have both namespace and type globs under `build.overwrite`",
+        "Verifies that the validator no longer reports `API_OVERWRITE_CONFIG_INVALID` after the migration"
+      ]
+    },
+    {
+      "id": 24,
+      "prompt": "Use dotnet-docfx-digest on a library that exposes a static class `HttpClientExtensions` with generic extension methods `AddPolicy<TPolicy>(this IHttpClientBuilder builder)` and `UseTimeout<T>(this HttpClient client, TimeSpan timeout)`. The previous run skipped these because they were incorrectly filtered out as generic types.",
+      "expected_output": "Agent includes both generic extension methods in the Extension Members table and requires examples for both. It does not skip `HttpClientExtensions` or its methods because the declaring type is generic or the methods are generic. The type overwrite file for `HttpClientExtensions` is created under `.docfx/api/types/`.",
+      "expectations": [
+        "Does not skip `HttpClientExtensions` because it is a static class (abstract sealed in IL)",
+        "Includes `AddPolicy<TPolicy>` and `UseTimeout<T>` in the Extension Members table",
+        "Creates a type overwrite file for `HttpClientExtensions` under `.docfx/api/types/`",
+        "Generates `EXAMPLE_MISSING` for the extension methods until examples are provided",
+        "Does not depend on a `IsGenericType` filter to exclude valid API targets"
+      ]
+    },
+    {
+      "id": 25,
+      "prompt": "Run dotnet-docfx-digest on a library that uses C# 14 extension blocks. The compiler generates a synthetic nested type `EndpointExtensions.<G>$AB12CD34` for the extension block. docfx.cs detects this during API discovery.",
+      "expected_output": "Agent emits a `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` warning for the namespace explaining that DocFX issue #11010 means extension block metadata may be missing. It continues documenting all other discoverable public APIs without skipping them, collapses the synthetic container back to the outer `EndpointExtensions` class for documentation purposes, and does not try to fix DocFX metadata gaps by excluding APIs.",
+      "expectations": [
+        "Emits `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` as a warning, not an error, for the affected namespace",
+        "Does not stop or skip other API targets because of the C# 14 extension block detection",
+        "Collapses the synthetic `<G>$...` nested type to the outer static class for example targeting",
+        "Does not create a separate overwrite file for the synthetic nested type",
+        "Continues generating namespace and type overwrite files for all other public APIs in the same run",
+        "Does not try to fix DocFX issue #11010 by excluding extension methods or inventing special rules"
+      ]
+    },
+    {
+      "id": 26,
+      "prompt": "Run dotnet-docfx-digest twice on a correctly configured repository where all namespace pages, type overwrite files, and docfx.json settings are already present and valid. Confirm idempotency.",
+      "expected_output": "The second run produces no changes to `docfx.json`, no new overwrite files, and the validator exits with status `passed` with zero errors on both runs. The agent reports that the repository is already compliant and does not make spurious edits.",
+      "expectations": [
+        "Second run reports validation passed with zero errors",
+        "Second run makes no changes to `docfx.json`",
+        "Second run creates no new namespace or type overwrite files",
+        "Second run does not report spurious `API_OVERWRITE_CONFIG_INVALID` after `docfx.json` was already updated on the first run",
+        "Agent reports that the documentation is already in a compliant state"
+      ]
+    },
+    {
+      "id": 27,
+      "prompt": "Run dotnet-docfx-digest on a repository. Confirm that the validator does not depend on DocFX-generated hash filenames like `*.md.G-*` or URL-encoded method UID filenames as source truth.",
+      "expected_output": "Agent discovers required example targets from compiled assembly metadata, not from DocFX-generated hash filenames. It reports `EXAMPLE_MISSING` when no overwrite file under `api/types/` or the namespace page has an example for the required UID. Hash-named files that may exist from a previous run do not satisfy the example requirement.",
+      "expectations": [
+        "Discovers required example targets from compiled assembly reflection, not from DocFX hash filenames",
+        "Does not use `*.md.G-*` files as evidence that an example exists",
+        "Reports `EXAMPLE_MISSING` even if a hash-named file exists but the correct UID is not in an overwrite file under `api/types/` or the namespace page",
+        "Does not create hash-named overwrite files as repair actions"
+      ]
+    },
+    {
+      "id": 28,
+      "prompt": "Use dotnet-docfx-digest. During the run the skill creates `.docfx/api/namespaces/Acme.Core.md` and `.docfx/api/types/Acme.Core.MyClass.md`. Run agents.cs and confirm AGENTS.md is created or updated with the new managed block content that mentions both namespace and type overwrite files.",
+      "expected_output": "agents.cs creates or updates AGENTS.md with a managed block that explicitly states: both namespace overwrite files (`api/namespaces/`) and type overwrite files (`api/types/`) are required; generic public APIs are valid targets; extension members are rendered under `Extension Members`; and `docfx.json` must include both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite`.",
+      "expectations": [
+        "AGENTS.md is created or updated by agents.cs before documentation validation",
+        "The managed block states that both namespace pages and type pages are required deliverables",
+        "The managed block states that generic public APIs are valid documentation targets",
+        "The managed block states that extension members are rendered under the heading `Extension Members`",
+        "The managed block states that `build.overwrite` must include both `api/namespaces/**/*.md` and `api/types/**/*.md`",
+        "The managed block states that type overwrite files live under `.docfx/api/types/`"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index f83103b..4490473 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -44,7 +44,7 @@ Exit codes:
 
 ## docfx.cs
 
-Validates the deterministic documentation requirements against the compiled repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies, prefers reference assemblies, loads metadata through `System.Reflection.MetadataLoadContext`, resolves dependencies from project assets, deps files, and installed .NET reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, the Codebelt namespace-folder overwrite convention (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and compiles every C# documentation sample as a file-based app. For Codebelt strong-name signed repositories, repository and sample builds use the root `.snk` when present and automatically pass `-p:SkipSignAssembly=true` when no root `.snk` exists, so missing local signing keys do not masquerade as documentation failures.
+Validates the deterministic documentation requirements against the compiled repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies, prefers reference assemblies, loads metadata through `System.Reflection.MetadataLoadContext`, resolves dependencies from project assets, deps files, and installed .NET reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, the Codebelt overwrite convention (`api/namespaces/**/*.md` for namespace pages and `api/types/**/*.md` for type pages, both under `build.overwrite` only), and compiles every C# documentation sample as a file-based app. For Codebelt strong-name signed repositories, repository and sample builds use the root `.snk` when present and automatically pass `-p:SkipSignAssembly=true` when no root `.snk` exists, so missing local signing keys do not masquerade as documentation failures.
 
 ```bash
 dotnet run --file docfx.cs -- --repo-root .
@@ -60,9 +60,9 @@ Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--f
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, a required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/namespaces/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics keep `api/namespaces/**/*.md` under `build.overwrite` only while moving legacy `.docfx/api/*.md` authored overwrite files into `.docfx/api/namespaces/`. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
+`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, a required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
 
-`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files and namespace pages are documentation output, not cleanup targets.
+`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files, namespace pages, and type pages are documentation output, not cleanup targets.
 
 Process execution drains stdout and stderr concurrently so verbose `dotnet build` or DocFX runs cannot deadlock on a full pipe while the validator waits for exit.
 
@@ -80,7 +80,7 @@ Exit codes:
 | 7 | Sample compilation failed |
 | 8 | Unexpected internal error |
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Validation warnings can also include `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010). Validation warnings can also include `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
 
 ### Sample opt-out
 
@@ -96,4 +96,6 @@ A skip marker with a weak reason such as "full example requires X package" or "e
 
 ### Extension-method detection note
 
-Extension methods are detected from compiled metadata: a public static method, carrying `System.Runtime.CompilerServices.ExtensionAttribute`, declared on a public static non-generic class, with at least one parameter. The first parameter's type is recorded as the extended type. The C# compiler marks the method, not the first parameter, with `ExtensionAttribute`, so detection keys off the method attribute to match real metadata.
+Extension methods are detected from compiled metadata: a public static method carrying `System.Runtime.CompilerServices.ExtensionAttribute`, declared on a public class (which may be generic or a static extension container) with at least one parameter. The first parameter's type is recorded as the extended type. The C# compiler marks the method, not the first parameter, with `ExtensionAttribute`, so detection keys off the method attribute to match real metadata. Generic declaring classes and generic extension methods are both valid targets and are not excluded.
+
+C# 14 extension-block types are collapsed back to their authored outer static class so that synthetic compiler-generated nested types such as `<G>$...` are never treated as standalone documentation targets. When C# 14 extension blocks are detected the validator emits a `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` warning noting that DocFX issue #11010 means generated API metadata for those members may be missing. Classic `this`-parameter extension methods remain fully supported and unaffected.
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 2b0a20c..55b53d9 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -9,7 +9,7 @@ Build a small example inventory from validator output and source evidence before
 ```markdown
 | UID | Kind | Required example location | Source evidence | Status |
 |---|---|---|---|---|
-| Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | ApplicationHostFactoryTest | Missing |
+| Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/types/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | ApplicationHostFactoryTest | Missing |
 ```
 
 Do not mark an item complete until the overwrite section targets the correct UID or approved extension-method location, the file is included by `build.overwrite`, the sample compiles or has a justified skip marker, and `docfx.cs --json` no longer reports the relevant missing-example diagnostic.
@@ -58,8 +58,8 @@ Use this path when the user invokes the skill without naming a specific API or n
 12. Audit related namespace pages together so fixes are consistent across the public API family.
 13. Add or repair `Extension Members` tables for namespaces with public extension methods.
 14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
-15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, normally under `.docfx/api/namespaces/{TypeUid}.md` in Codebelt repositories.
-16. Ensure `docfx.json` keeps `.docfx/api/namespaces/**/*.md` under `build.overwrite`, excludes `.docfx/api/namespaces/**` from `build.content`, and moves legacy authored `.docfx/api/*.md` files into `.docfx/api/namespaces/` when needed.
+15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, under `.docfx/api/types/{TypeUid}.md` in Codebelt repositories.
+16. Ensure `docfx.json` includes both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite`, excludes both `api/namespaces/**` and `api/types/**` from `build.content`, and moves legacy authored `.docfx/api/*.md` files into either `api/namespaces/` (namespace pages) or `api/types/` (type pages).
 17. Create explicit examples for public extension methods that still have none.
 18. Build or refresh the example inventory.
 19. Preserve manual edits and correct stale contradictions instead of replacing whole files.
@@ -166,7 +166,7 @@ Before completing documentation work, verify:
 - [ ] Public non-abstraction types have at least one type-page example.
 - [ ] Public extension methods have at least one explicit example, not only a table entry.
 - [ ] The example inventory maps each required public type and extension method to its example file and UID.
-- [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`.
+- [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`. Namespace pages are under `api/namespaces/` and type pages are under `api/types/`.
 - [ ] The Completion Repair Loop was run after edits, and remaining `EXAMPLE_MISSING` or overwrite-layout diagnostics were fixed or reported as exact blockers.
 - [ ] Examples are realistic, copy/paste-ready, and compile unless a justified skip marker is present.
 - [ ] Availability is included or explicitly stated and matches actual target frameworks and conditions.
diff --git a/skills/dotnet-docfx-digest/scripts/agents.cs b/skills/dotnet-docfx-digest/scripts/agents.cs
index 066573e..88ac326 100644
--- a/skills/dotnet-docfx-digest/scripts/agents.cs
+++ b/skills/dotnet-docfx-digest/scripts/agents.cs
@@ -30,36 +30,42 @@ internal static class AgentsScript
 
         Documentation updates must cover public API only. Do not document private or internal types or members. Do not create namespace overview pages for namespaces that contain no public API.
 
-        For public non-abstraction types, include at least one realistic, copy/paste-ready usage example on the generated type page/overwrite section for that type UID. For example, a public `Class1` requires an example on the `Class1` API page, not only on the namespace page. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage.
-
-        Missing type examples must be added through separate per-type DocFX overwrite files by default, such as `.docfx/api/{TypeUid}.md` in Codebelt repositories. If `build.overwrite` only includes namespace files, update `docfx.json` so it includes the per-type overwrite files too, for example with `api/**/*.md`. Namespace overview text and `Extension Members` tables are not substitutes for type-page examples.
-
-        Public extension methods must have examples too. Listing an extension method in an `Extension Members` table is required, but it is not enough.
-
-        All added or changed code samples must be deterministic and verified to compile. Do not add pseudo-code, ellipses, hidden test helpers, or examples that rely on unverified behavior.
+        Public non-abstraction types — including enums, structs, records, plain classes, and static extension containers — are valid documentation targets. Generic public types and generic extension methods are valid documentation targets too. Do not exclude a type solely because it is generic or because reflection reports it as abstract and sealed (that is the IL pattern for a static class).
 
-        Every namespace containing public API must have a DocFX namespace overview page named after the namespace, such as `X.Y.Z.md`, using DocFX overwrite front matter with the namespace `uid`.
+        For public non-abstraction types, include at least one realistic, copy/paste-ready usage example on the generated type page/overwrite section for that type UID. For example, a public `Class1` requires an example on the `Class1` API page, not only on the namespace page. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage.
 
-        Namespaces exposing public extension methods must document those extension members at namespace level. The namespace page must include an `Extension Members` table listing the extended type, the extension marker, and the public extension methods.
+        Missing type examples must be added through per-type DocFX overwrite files under `.docfx/api/types/{TypeUid}.md` in Codebelt repositories. Namespace overview text and `Extension Members` tables are not substitutes for type-page examples.
+
+        Public extension methods must have examples too. Listing an extension method in an `Extension Members` table is required, but it is not enough.
+
+        All added or changed code samples must be deterministic and verified to compile. Do not add pseudo-code, ellipses, hidden test helpers, or examples that rely on unverified behavior.
+
+        Every namespace containing public API must have a DocFX namespace overview page named after the namespace, such as `X.Y.Z.md`, under `.docfx/api/namespaces/`, using DocFX overwrite front matter with the namespace `uid`.
+
+        Namespaces exposing public extension methods must document those extension members at namespace level. The namespace page must include an `Extension Members` table listing the extended type, the extension marker, and the public extension methods. Extension members are rendered under the heading `Extension Members`.
+
+        Both namespace overwrite files and type overwrite files are required deliverables in the same run. Generating only namespace pages or only type pages is incomplete.
+
+        `docfx.json` must keep namespace and type overwrite files in separate subdirectories. `build.overwrite` must include both `api/namespaces/**/*.md` (for namespace pages) and `api/types/**/*.md` (for type pages). `build.content` must exclude both `api/namespaces/**` and `api/types/**` to prevent overwrite Markdown from being treated as conceptual content. Do not use `api/**/*.md` under `build.overwrite` or `build.content`.
 
         Availability must be documented by referencing the appropriate include file when one exists, or by adding explicit availability text when no suitable include exists. Availability must reflect the actual target frameworks, conditional compilation, and project configuration.
 
         Preserve manual documentation edits. Prefer additive changes, but correct stale or contradictory information so documentation remains accurate.
 
-        Before completing documentation work, run the relevant verification commands, normally:
-
-        ```bash
-        dotnet build
-        dotnet test
-        dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --verify-docfx-build
-        ```
-
-        Codebelt repositories are normally strong-name signed with a `.snk` file in the repository root on the main author's codespace. Preserve and copy that root `.snk` file when building a temporary copy. If the repository or temp copy has no root `.snk`, run build and test verification with `-p:SkipSignAssembly=true`, for example `dotnet build -p:SkipSignAssembly=true` and `dotnet test -p:SkipSignAssembly=true`.
-
-        The DocFX build verification must run outside the working tree when possible. The `--verify-docfx-build` option copies the repository to a temp workspace, runs DocFX against the resolved `docfx.json` there, and removes the temp workspace afterward so generated API YAML, manifest files, and site output do not flood git status.
-
-        If a command cannot be run, report the exact limitation or failure instead of claiming the documentation was verified.
-        <!-- dotnet-docfx-digest:end -->
+        Before completing documentation work, run the relevant verification commands, normally:
+
+        ```bash
+        dotnet build
+        dotnet test
+        dotnet run --file skills/dotnet-docfx-digest/scripts/docfx.cs -- --repo-root . --verify-docfx-build
+        ```
+
+        Codebelt repositories are normally strong-name signed with a `.snk` file in the repository root on the main author's codespace. Preserve and copy that root `.snk` file when building a temporary copy. If the repository or temp copy has no root `.snk`, run build and test verification with `-p:SkipSignAssembly=true`, for example `dotnet build -p:SkipSignAssembly=true` and `dotnet test -p:SkipSignAssembly=true`.
+
+        The DocFX build verification must run outside the working tree when possible. The `--verify-docfx-build` option copies the repository to a temp workspace, runs DocFX against the resolved `docfx.json` there, and removes the temp workspace afterward so generated API YAML, manifest files, and site output do not flood git status.
+
+        If a command cannot be run, report the exact limitation or failure instead of claiming the documentation was verified.
+        <!-- dotnet-docfx-digest:end -->
         """;
 
     public static int Run(string[] args)
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 2f48776..854a5e4 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -311,9 +311,9 @@ private static void ValidateApiOverwriteLayout(string repoRoot, string docfxPath
             var overwriteFiles = ReadDocfxBuildPatterns(build, "overwrite", "files");
 
             var configProblems = new List<string>();
-            if (contentFiles.Any(pattern => DocfxPatternEquals(pattern, "api/**/*.md") || DocfxPatternEquals(pattern, "api/namespaces/**/*.md")))
+            if (contentFiles.Any(pattern => DocfxPatternEquals(pattern, "api/**/*.md") || DocfxPatternEquals(pattern, "api/namespaces/**/*.md") || DocfxPatternEquals(pattern, "api/types/**/*.md")))
             {
-                configProblems.Add("Do not include `api/**/*.md` or `api/namespaces/**/*.md` under `build.content`.");
+                configProblems.Add("Do not include `api/**/*.md`, `api/namespaces/**/*.md`, or `api/types/**/*.md` under `build.content`.");
             }
 
             if (!contentExclude.Any(pattern => DocfxPatternEquals(pattern, "api/namespaces/**")))
@@ -321,11 +321,21 @@ private static void ValidateApiOverwriteLayout(string repoRoot, string docfxPath
                 configProblems.Add("Add `api/namespaces/**` to the `build.content` exclusions.");
             }
 
+            if (!contentExclude.Any(pattern => DocfxPatternEquals(pattern, "api/types/**")))
+            {
+                configProblems.Add("Add `api/types/**` to the `build.content` exclusions.");
+            }
+
             if (!overwriteFiles.Any(pattern => DocfxPatternEquals(pattern, "api/namespaces/**/*.md")))
             {
                 configProblems.Add("Include `api/namespaces/**/*.md` under `build.overwrite`.");
             }
 
+            if (!overwriteFiles.Any(pattern => DocfxPatternEquals(pattern, "api/types/**/*.md")))
+            {
+                configProblems.Add("Include `api/types/**/*.md` under `build.overwrite`.");
+            }
+
             if (overwriteFiles.Any(pattern => DocfxPatternEquals(pattern, "api/**/*.md")))
             {
                 configProblems.Add("Do not include `api/**/*.md` under `build.overwrite`.");
@@ -334,7 +344,7 @@ private static void ValidateApiOverwriteLayout(string repoRoot, string docfxPath
             if (configProblems.Count > 0)
             {
                 report.Errors.Add(new Diagnostic("API_OVERWRITE_CONFIG_INVALID", docfxPath, null,
-                    $"DocFX API overwrite Markdown must use the namespace-folder convention so overwrite content merges into managed API pages without being treated as normal content. {string.Join(" ", configProblems)}"));
+                    $"DocFX API overwrite Markdown must use separate namespace and type subdirectories so overwrite content merges into managed API pages without being treated as normal content. {string.Join(" ", configProblems)}"));
             }
         }
 
@@ -343,12 +353,12 @@ private static void ValidateApiOverwriteLayout(string repoRoot, string docfxPath
             return;
         }
 
+        var typesDirectory = Path.Combine(apiDirectory, "types");
         foreach (var file in Directory.EnumerateFiles(apiDirectory, "*.md", SearchOption.TopDirectoryOnly)
                      .Where(path => !string.Equals(Path.GetFileName(path), "toc.md", StringComparison.OrdinalIgnoreCase)))
         {
-            var destination = Rel(repoRoot, Path.Combine(namespacesDirectory, Path.GetFileName(file)));
             report.Errors.Add(new Diagnostic("API_OVERWRITE_FILE_MISPLACED", file, null,
-                $"Authored API overwrite Markdown must not live directly under `{Rel(repoRoot, apiDirectory)}`. Move this file to `{destination}` and keep its YAML front matter and Markdown content intact. Do not move generated `.yml` metadata files."));
+                $"Authored API overwrite Markdown must not live directly under `{Rel(repoRoot, apiDirectory)}`. Move namespace overwrite files to `{Rel(repoRoot, namespacesDirectory)}` and type overwrite files to `{Rel(repoRoot, typesDirectory)}`. Preserve YAML front matter and Markdown content. Do not move generated `.yml` metadata files."));
         }
     }
 
@@ -1284,11 +1294,26 @@ private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string co
                     namespaces[nsName] = info;
                 }
 
+                // Track synthetic C# 14 extension-block containers so we can warn about DocFX #11010.
+                if (IsSyntheticExtensionBlockContainer(type))
+                {
+                    info.HasCSharp14ExtensionBlocks = true;
+                }
+
                 CollectApiTargets(type, info);
                 CollectExtensionMethods(type, info);
             }
         }
 
+        // Emit a warning for namespaces that contain C# 14 extension blocks: DocFX issue #11010
+        // means those blocks do not yet generate correct API metadata. Extension methods declared
+        // with the classic `this` pattern are unaffected and remain supported.
+        foreach (var ns in namespaces.Values.Where(n => n.HasCSharp14ExtensionBlocks))
+        {
+            report.Warnings.Add(new Diagnostic("DOCFX_EXTENSION_BLOCK_UNSUPPORTED", null, ns.Name,
+                $"Namespace {ns.Name} contains C# 14 extension-block types. DocFX (issue #11010) does not currently generate correct API metadata for extension blocks, so generated UIDs for those members may be missing or synthetic. Classic static extension methods with 'this' parameters remain fully supported. Do not exclude these APIs or invent special rules; continue generating docs for all discoverable public APIs and document the limitation in the overwrite file when needed."));
+        }
+
         var requiredExampleTargets = namespaces.Values
             .SelectMany(ns => ns.RequiredExampleTargets)
             .OrderBy(t => t.Uid, StringComparer.Ordinal)
@@ -1668,7 +1693,7 @@ private static void CollectApiTargets(Type type, NamespaceInfo ns)
 
     private static void CollectExtensionMethods(Type type, NamespaceInfo ns)
     {
-        if (!type.IsClass || type.IsGenericType || !IsExternallyVisible(type))
+        if (!type.IsClass || !IsExternallyVisible(type))
         {
             return;
         }
@@ -1788,7 +1813,15 @@ private static bool IsExternallyVisible(Type type)
 
     private static bool IsExampleRequiredType(Type type)
     {
-        if (type.IsInterface || type.IsAbstract)
+        if (type.IsInterface)
+        {
+            return false;
+        }
+
+        // Exclude abstract types, but allow static extension containers (abstract+sealed class
+        // with public static [Extension] members). These are valid documentation targets even
+        // though reflection reports IsAbstract == true for sealed abstract classes.
+        if (type.IsAbstract && !IsStaticExtensionContainer(type))
         {
             return false;
         }
@@ -1796,6 +1829,28 @@ private static bool IsExampleRequiredType(Type type)
         return true;
     }
 
+    private static bool IsStaticExtensionContainer(Type type)
+    {
+        // A static extension container is a sealed abstract class (static class in C# terms)
+        // that has at least one public static member with [ExtensionAttribute].
+        if (!type.IsClass || !type.IsAbstract || !type.IsSealed)
+        {
+            return false;
+        }
+
+        MethodInfo[] methods;
+        try
+        {
+            methods = type.GetMethods(BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly);
+        }
+        catch
+        {
+            return false;
+        }
+
+        return methods.Any(HasExtensionAttribute);
+    }
+
     private static string? TypeUid(Type type)
     {
         var fullName = type.FullName;
@@ -2041,13 +2096,13 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
                 ? target.Uid
                 : target.DeclaringTypeUid ?? target.Uid;
             var expectedPath = target.Kind == ApiTargetKind.Type
-                ? Rel(repoRoot, Path.Combine(docfxWorkspace, "api", "namespaces", $"{target.Uid}.md"))
+                ? Rel(repoRoot, Path.Combine(docfxWorkspace, "api", "types", $"{target.Uid}.md"))
                 : target.DeclaringTypeUid is null
                     ? null
                     : Rel(repoRoot, Path.Combine(docfxWorkspace, "api", "namespaces", $"{target.DeclaringTypeUid}.md"));
 
             var message = target.Kind == ApiTargetKind.Type
-                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}` in `{expectedPath}` or another overwrite file under `api/namespaces/` that targets this exact type UID. Namespace overview examples do not satisfy this diagnostic. Keep `api/namespaces/**/*.md` under `build.overwrite`, exclude `api/namespaces/**` from `build.content`, and do not use `api/**/*.md` under either section."
+                ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}` in `{expectedPath}` or another overwrite file under `api/types/` that targets this exact type UID. Namespace overview examples do not satisfy this diagnostic. Keep `api/types/**/*.md` under `build.overwrite`, exclude `api/types/**` from `build.content`, and do not use `api/**/*.md` under either section."
                 : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to the declaring extension class uid `{expectedUid}` or the namespace page `{target.Namespace}` by default. The example must explicitly call `{target.DisplayName}`. Do not create URL-encoded or hash-like method UID filenames; use a method UID section only when the exact generated UID is verified and can live in a readable overwrite file.";
 
             report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", expectedPath, target.Namespace, message));
@@ -2782,7 +2837,7 @@ private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerab
             var path = EscapeTable(string.IsNullOrWhiteSpace(diagnostic.Path) ? "(method UID, declaring type UID, or namespace page)" : diagnostic.Path);
             var message = EscapeTable(diagnostic.Message);
             var action = diagnostic.Message.Contains("Public non-abstraction type", StringComparison.Ordinal)
-                ? "Create or update the type-targeting overwrite file under `api/namespaces/`, keep `api/namespaces/**/*.md` under `build.overwrite` only, add a compiling Examples section, then rerun validation."
+                ? "Create or update the type-targeting overwrite file under `api/types/`, keep `api/types/**/*.md` under `build.overwrite` only, add a compiling Examples section, then rerun validation."
                 : "Add a compiling Examples section on the declaring extension class or namespace page that explicitly calls the extension method, then rerun validation.";
             sb.AppendLine($"| {ns} | `{path}` | `EXAMPLE_MISSING` | {EscapeTable(action)} {message} |");
         }
@@ -2979,6 +3034,7 @@ private sealed class NamespaceInfo(string name)
         public string Name { get; } = name;
         public List<ApiTargetInfo> RequiredExampleTargets { get; } = new();
         public List<ExtensionMethodInfo> ExtensionMethods { get; } = new();
+        public bool HasCSharp14ExtensionBlocks { get; set; }
     }
 
     private sealed record ApiModel(List<NamespaceInfo> Namespaces, List<ApiTargetInfo> RequiredExampleTargets);

From d87c04caffee3aaedb3de34f42ab88e165fd064f Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 19:41:36 +0200
Subject: [PATCH 40/88] =?UTF-8?q?=F0=9F=94=A7=20refine=20library=20scaffol?=
 =?UTF-8?q?d=20docfx=20template?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extend docfx.json configuration to support api/types/ in addition to api/namespaces/, providing flexibility for type-level API documentation organization within scaffolded library projects.
---
 skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json b/skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json
index 78feea6..2b8961d 100644
--- a/skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json
+++ b/skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json
@@ -29,7 +29,8 @@
           "bin/**",
           "obj/**",
           "wwwroot/**",
-          "api/namespaces/**"
+          "api/namespaces/**",
+          "api/types/**"
         ]
       }
     ],
@@ -61,7 +62,8 @@
     "overwrite": [
       {
         "files": [
-          "api/namespaces/**/*.md"
+          "api/namespaces/**/*.md",
+          "api/types/**/*.md"
         ],
         "exclude": [
           "bin/**",

From dfe75018f556ea7e0adac359084c7a5160d7f836 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 21:31:43 +0200
Subject: [PATCH 41/88] =?UTF-8?q?=E2=9C=85=20expand=20docfx=20validation?=
 =?UTF-8?q?=20and=20evals?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extend evals with comprehensive validation scenarios covering rare endpoint cases and edge conditions. Enhance docfx.cs script with refined validation logic, improved target matching, and expanded example-candidate detection to handle complex API documentation scenarios.
---
 skills/dotnet-docfx-digest/evals/evals.json |  72 ++++++++
 skills/dotnet-docfx-digest/scripts/docfx.cs | 173 ++++++++++++++++++--
 2 files changed, 235 insertions(+), 10 deletions(-)

diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index bad0ef3..cb16b32 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -358,6 +358,78 @@
         "The managed block states that `build.overwrite` must include both `api/namespaces/**/*.md` and `api/types/**/*.md`",
         "The managed block states that type overwrite files live under `.docfx/api/types/`"
       ]
+    },
+    {
+      "id": 29,
+      "prompt": "Run dotnet-docfx-digest on a repository where `docfx.json` has `metadata[].src[].files = [\"src/Acme.Core/*.csproj\", \"src/Acme.Abstractions/*.csproj\"]` but a third project `src/Acme.Benchmarks/Acme.Benchmarks.csproj` also exists under `src/`. Confirm that `Acme.Benchmarks` is never reflected over or documented.",
+      "expected_output": "The validator reads the active `docfx.json` metadata configuration and builds the project list exclusively from the `metadata[].src[].files` patterns. `Acme.Benchmarks` is not included in the project list because it is not matched by any `metadata[].src` pattern in `docfx.json`. No namespace page, type overwrite file, or example is generated for types defined in `Acme.Benchmarks`.",
+      "expectations": [
+        "Builds the candidate project list from docfx.json metadata[].src[].files patterns, not by scanning all src/**/*.csproj",
+        "Does not include Acme.Benchmarks in the project list because it is not referenced by docfx.json",
+        "Does not generate namespace pages, type overwrite files, or examples for types defined in Acme.Benchmarks",
+        "Documents only Acme.Core and Acme.Abstractions as they are explicitly included by docfx.json",
+        "Reports PROJECT_DISCOVERY_FAILED with the docfx.json path if no projects are resolved"
+      ]
+    },
+    {
+      "id": 30,
+      "prompt": "Run dotnet-docfx-digest on a repository where `docfx.json` has two separate `metadata` entries: the first entry includes `src/Acme.Core/*.csproj` and the second entry includes `src/Acme.Extensions/*.csproj`. Both entries use `metadata[].src[].src = \"../\"` to resolve paths relative to the `.docfx/` directory.",
+      "expected_output": "The validator resolves projects from both metadata entries and merges the results into a single de-duplicated, sorted project list. Namespaces from both `Acme.Core` and `Acme.Extensions` assemblies appear in the public API surface. Both namespace pages and required type overwrite files are generated for all public non-abstraction types in both assemblies.",
+      "expectations": [
+        "Reads and processes all metadata entries in docfx.json, not only the first one",
+        "Resolves projects from each metadata entry's src[] configuration independently",
+        "Merges projects from all metadata entries into a single de-duplicated list",
+        "Discovers public API from both Acme.Core and Acme.Extensions assemblies",
+        "Generates namespace pages and type overwrite files for public APIs in both assemblies"
+      ]
+    },
+    {
+      "id": 31,
+      "prompt": "Run dotnet-docfx-digest on a repository where `docfx.json` lives under `.docfx/` and its metadata section uses `\"src\": \"../\"` to point at the repository root, with `\"files\": [\"src/**.csproj\"]`. Confirm that project paths are resolved relative to the `.docfx/` directory and not relative to the process working directory.",
+      "expected_output": "The validator resolves the `src` base directory for each metadata entry relative to the `docfx.json` file location, not relative to the process CWD. When `docfx.json` is at `.docfx/docfx.json` and `metadata[].src[].src = \"../\"`, the effective base resolves to the repository root, and `files = [\"src/**.csproj\"]` discovers projects under `<repo-root>/src/`. All resolved project paths are full, normalised absolute paths.",
+      "expectations": [
+        "Resolves metadata[].src[].src paths relative to the docfx.json file location",
+        "Does not resolve paths relative to the process working directory",
+        "Correctly derives the repository root when src = \"../\" and docfx.json is at .docfx/docfx.json",
+        "Discovers .csproj files under the resolved base directory using the files glob patterns",
+        "Returns normalised absolute paths for all resolved projects"
+      ]
+    },
+    {
+      "id": 32,
+      "prompt": "Run dotnet-docfx-digest on a repository where `docfx.json` includes `src/**.csproj` in `metadata[].src[].files` but also has `metadata[].src[].exclude = [\"src/Acme.Tests/**\", \"src/Acme.Samples/**\"]`. Projects `Acme.Tests` and `Acme.Samples` exist under `src/` and would otherwise be matched. Confirm they are excluded from the documentation surface.",
+      "expected_output": "The validator honours the `exclude` patterns in each `metadata[].src` entry and removes `Acme.Tests` and `Acme.Samples` from the resolved project list. No namespace pages, type overwrite files, or examples are generated for types in those assemblies. The project list matches only the assemblies that pass both the include and exclude filter.",
+      "expectations": [
+        "Applies metadata[].src[].exclude patterns to filter out matching .csproj files",
+        "Does not include Acme.Tests in the project list because it is matched by the exclude pattern",
+        "Does not include Acme.Samples in the project list because it is matched by the exclude pattern",
+        "Does not generate documentation for types in excluded projects",
+        "Reports PROJECT_DISCOVERY_FAILED when all projects are excluded and no projects remain"
+      ]
+    },
+    {
+      "id": 33,
+      "prompt": "Run dotnet-docfx-digest twice in succession on a repository where `docfx.json` is already correctly configured with `metadata[].src[].files = [\"src/**.csproj\"]` and `metadata[].src[].exclude = [\"src/tools/**\"]`. On the first run, all namespace pages and type overwrite files are generated. Confirm that the second run resolves the same project set and produces no new changes.",
+      "expected_output": "Both runs resolve the same set of projects from `docfx.json`. The second run discovers the same public API surface, validates the same namespace pages and type overwrite files, and reports no new changes, no spurious diagnostics, and no new files created. The resolved project list is identical on both runs because the discovery is based solely on the static `docfx.json` configuration.",
+      "expectations": [
+        "Second run resolves the same project list as the first run",
+        "Second run discovers the same public API namespaces and types",
+        "Second run reports no new namespace or type overwrite files created",
+        "Second run reports validation passed with zero errors when the first run left the repository in a compliant state",
+        "Project discovery is deterministic: the same docfx.json always produces the same project list regardless of run order"
+      ]
+    },
+    {
+      "id": 34,
+      "prompt": "Run dotnet-docfx-digest on a repository whose `docfx.json` metadata section has no `src` key at all in any metadata entry. Confirm that the validator fails with a clear error explaining which `docfx.json` was read and what configuration is missing.",
+      "expected_output": "The validator reads the active `docfx.json`, finds no resolvable projects from the metadata section, and emits a `PROJECT_DISCOVERY_FAILED` diagnostic that includes the full path to `docfx.json` and guidance explaining that `metadata[].src[].files` must reference `.csproj` files. The exit code is non-zero. No fallback scan of `src/**/*.csproj` is attempted.",
+      "expectations": [
+        "Emits PROJECT_DISCOVERY_FAILED with the full path to docfx.json in the diagnostic message",
+        "Explains that metadata[].src[].files must be configured to reference .csproj files",
+        "Returns a non-zero exit code",
+        "Does not fall back to scanning src/**/*.csproj when docfx.json produces no projects",
+        "Does not attempt to document any projects or generate any overwrite files when project discovery fails"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 854a5e4..30da488 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -150,7 +150,15 @@ private static int Validate(Options options)
         }
 
         // 5-7. Discover public API, namespaces and extension methods from compiled metadata.
-        var projects = DiscoverProjects(repoRoot);
+        // Use docfx.json as the canonical documentation boundary: only projects referenced
+        // by metadata[].src[] in the active docfx.json are included. Projects under src/ that
+        // are not configured in docfx.json (test harnesses, benchmarks, samples, etc.) are excluded.
+        var projects = DiscoverProjects(docfxPath, docfxWorkspace, report);
+        if (projects.Count == 0)
+        {
+            return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Project discovery failed.");
+        }
+
         var libraryProjects = projects.Where(p => !p.IsTest).ToList();
         ApiModel api;
         try
@@ -1111,20 +1119,165 @@ private static bool HasRootStrongNameKey(string repoRoot)
     // Project + API discovery
     // ----------------------------------------------------------------------
 
-    private static List<ProjectInfo> DiscoverProjects(string repoRoot)
+    /// <summary>
+    /// Resolves the candidate project list exclusively from the active <c>docfx.json</c>
+    /// metadata configuration.  Only <c>.csproj</c> files matched by a
+    /// <c>metadata[].src[].files</c> include pattern and not excluded by a corresponding
+    /// <c>exclude</c> pattern are returned.  Paths are resolved relative to the
+    /// <c>docfx.json</c> file location, de-duplicated, and sorted by normalised full path
+    /// for deterministic ordering.
+    /// </summary>
+    private static List<ProjectInfo> DiscoverProjects(string docfxPath, string docfxWorkspace, Report report)
     {
-        var projects = new List<ProjectInfo>();
-        var srcPath = Path.Combine(repoRoot, "src");
-        if (!Directory.Exists(srcPath))
+        JsonDocument doc;
+        try
+        {
+            doc = JsonDocument.Parse(File.ReadAllText(docfxPath), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+        }
+        catch (Exception ex) when (ex is IOException or JsonException)
         {
-            return projects;
+            report.Errors.Add(new Diagnostic("PROJECT_DISCOVERY_FAILED", docfxPath, null,
+                $"Unable to read docfx.json at '{docfxPath}' for project discovery: {ex.Message}"));
+            return new List<ProjectInfo>();
         }
-        foreach (var proj in EnumerateFiles(srcPath, "*.csproj"))
+
+        var resolvedPaths = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        var resolvedProjects = new List<(string NormalizedPath, ProjectInfo Project)>();
+
+        using (doc)
         {
-            var info = ReadProject(proj);
-            projects.Add(info);
+            if (!doc.RootElement.TryGetProperty("metadata", out var metadata))
+            {
+                report.Errors.Add(new Diagnostic("PROJECT_DISCOVERY_FAILED", docfxPath, null,
+                    $"docfx.json at '{docfxPath}' has no 'metadata' section. " +
+                    "Cannot determine which projects are included in the documentation surface."));
+                return new List<ProjectInfo>();
+            }
+
+            foreach (var entry in EnumerateMetadataEntries(metadata))
+            {
+                if (entry.ValueKind != JsonValueKind.Object || !entry.TryGetProperty("src", out var srcArray))
+                {
+                    continue;
+                }
+
+                foreach (var srcEntry in EnumerateDocfxFileMappingEntries(srcArray))
+                {
+                    // Default base directory is the docfx.json workspace; overridden by src[].src.
+                    var baseDir = docfxWorkspace;
+                    var includePatterns = new List<string>();
+                    var excludePatterns = new List<string>();
+
+                    if (srcEntry.ValueKind == JsonValueKind.String)
+                    {
+                        includePatterns.Add(srcEntry.GetString() ?? string.Empty);
+                    }
+                    else if (srcEntry.ValueKind == JsonValueKind.Object)
+                    {
+                        if (srcEntry.TryGetProperty("src", out var srcBase) &&
+                            srcBase.ValueKind == JsonValueKind.String &&
+                            !string.IsNullOrWhiteSpace(srcBase.GetString()))
+                        {
+                            baseDir = Path.GetFullPath(srcBase.GetString()!, docfxWorkspace);
+                        }
+
+                        if (srcEntry.TryGetProperty("files", out var files))
+                        {
+                            includePatterns.AddRange(ReadDocfxGlobPatterns(files));
+                        }
+
+                        if (srcEntry.TryGetProperty("exclude", out var exclude))
+                        {
+                            excludePatterns.AddRange(ReadDocfxGlobPatterns(exclude));
+                        }
+                    }
+
+                    foreach (var projectPath in ResolveCsprojGlobPatterns(baseDir, includePatterns, excludePatterns))
+                    {
+                        var normalizedPath = Path.GetFullPath(projectPath);
+                        if (resolvedPaths.Add(normalizedPath))
+                        {
+                            resolvedProjects.Add((normalizedPath, ReadProject(normalizedPath)));
+                        }
+                    }
+                }
+            }
+        }
+
+        if (resolvedProjects.Count == 0)
+        {
+            report.Errors.Add(new Diagnostic("PROJECT_DISCOVERY_FAILED", docfxPath, null,
+                $"No projects were resolved from docfx.json at '{docfxPath}'. " +
+                "Review the metadata[].src[].files and metadata[].src[].exclude configuration to ensure " +
+                "it resolves to .csproj files in this repository. Projects not referenced by the active " +
+                "docfx.json metadata configuration are intentionally excluded."));
+            return new List<ProjectInfo>();
+        }
+
+        // Sort by normalised path for deterministic, idempotent ordering.
+        return resolvedProjects
+            .OrderBy(p => NormalizeDocfxPath(p.NormalizedPath), StringComparer.OrdinalIgnoreCase)
+            .Select(p => p.Project)
+            .ToList();
+    }
+
+    /// <summary>
+    /// Resolves <c>.csproj</c> files from <paramref name="srcRoot"/> using DocFX-style glob
+    /// <paramref name="includePatterns"/>, excluding paths matched by
+    /// <paramref name="excludePatterns"/>. All patterns are resolved relative to
+    /// <paramref name="srcRoot"/> and converted to case-insensitive regular expressions using
+    /// the same <see cref="GlobToRegex"/> logic used for Markdown inputs.
+    /// </summary>
+    private static IEnumerable<string> ResolveCsprojGlobPatterns(
+        string srcRoot,
+        IEnumerable<string> includePatterns,
+        IEnumerable<string> excludePatterns)
+    {
+        var excludes = excludePatterns
+            .Where(p => !string.IsNullOrWhiteSpace(p))
+            .Select(GlobToRegex)
+            .ToList();
+
+        foreach (var pattern in includePatterns)
+        {
+            if (string.IsNullOrWhiteSpace(pattern))
+            {
+                continue;
+            }
+
+            var searchRoot = ResolveGlobSearchRoot(srcRoot, pattern);
+
+            if (!Directory.Exists(searchRoot))
+            {
+                // May be an exact path rather than a glob.
+                var exactFile = Path.GetFullPath(pattern, srcRoot);
+                if (File.Exists(exactFile) &&
+                    string.Equals(Path.GetExtension(exactFile), ".csproj", StringComparison.OrdinalIgnoreCase))
+                {
+                    var rel = NormalizeDocfxPath(Path.GetRelativePath(srcRoot, exactFile));
+                    if (!excludes.Any(excl => excl.IsMatch(rel)))
+                    {
+                        yield return exactFile;
+                    }
+                }
+
+                continue;
+            }
+
+            var includeRegex = GlobToRegex(pattern);
+            foreach (var file in EnumerateFiles(searchRoot, "*.csproj"))
+            {
+                var relative = NormalizeDocfxPath(Path.GetRelativePath(srcRoot, file));
+                if (includeRegex.IsMatch(relative) && !excludes.Any(excl => excl.IsMatch(relative)))
+                {
+                    yield return Path.GetFullPath(file);
+                }
+            }
         }
-        return projects;
     }
 
     private static ProjectInfo ReadProject(string projectPath)

From 55b70bdd1b262f760569870511d86cf3e416f9a4 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 23:03:09 +0200
Subject: [PATCH 42/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20docfx=20validator:?=
 =?UTF-8?q?=20distinguish=20example=20forms=20in=20overwrite=20files?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Distinguish between Form A (example: *content front matter) and Form B (summary: *content front matter) when validating DocFX overwrite file examples. Form A requires only a bare C# fence; Form B requires an explicit heading. Update OverwriteSection record to track MappedToExample state and adjust validation logic accordingly.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 44 +++++++++++++++++++--
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 30da488..98438fb 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -2359,7 +2359,15 @@ private static bool IsExampleCandidate(OverwriteSection section, ApiTargetInfo t
 
     private static bool HasExampleForTarget(OverwriteSection section, ApiTargetInfo target)
     {
-        if (!HasExampleSectionWithCSharpFence(section.Body))
+        // MappedToExample (front-matter example: *content or - *content) only requires
+        // a bare csharp fence; the heading is added automatically by DocFX.
+        // The summary: *content form (MappedToExample=false) still requires the explicit
+        // heading to delimit the embedded example within conceptual content.
+        var hasFence = section.MappedToExample
+            ? HasCSharpFence(section.Body)
+            : HasExampleSectionWithCSharpFence(section.Body);
+
+        if (!hasFence)
         {
             return false;
         }
@@ -2373,6 +2381,11 @@ private static bool HasExampleForTarget(OverwriteSection section, ApiTargetInfo
         return true;
     }
 
+    private static bool HasCSharpFence(string body)
+    {
+        return Regex.IsMatch(body, @"(?im)^```\s*(csharp|cs)\s*$");
+    }
+
     private static bool HasExampleSectionWithCSharpFence(string body)
     {
         var match = Regex.Match(body, @"(?im)^#{2,5}\s+Examples?\s*$");
@@ -2568,12 +2581,37 @@ private static List<OverwriteSection> ExtractOverwriteSections(string mdFile)
 
             var bodyEnd = i + 1 < matches.Count ? matches[i + 1].Index : normalized.Length;
             var body = bodyEnd > bodyStart ? normalized[bodyStart..bodyEnd] : string.Empty;
-            sections.Add(new OverwriteSection(mdFile, uid, body));
+            sections.Add(new OverwriteSection(mdFile, uid, body, IsMappedToExample(yaml)));
         }
 
         return sections;
     }
 
+    private static bool IsMappedToExample(string yaml)
+    {
+        // Form A: example: *content  (inline scalar)
+        if (ReadYamlScalar(yaml, "example") is "*content")
+        {
+            return true;
+        }
+
+        // Form B: example:\n  - *content  (sequence / list form)
+        var lines = yaml.Split('\n');
+        for (var i = 0; i < lines.Length - 1; i++)
+        {
+            if (lines[i].Trim() == "example:")
+            {
+                var next = lines[i + 1].Trim();
+                if (next == "- *content")
+                {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
     private static (bool Found, string Reason) FindSkip(string code)
     {
         foreach (var line in code.Split('\n'))
@@ -3194,7 +3232,7 @@ private sealed record ApiModel(List<NamespaceInfo> Namespaces, List<ApiTargetInf
 
     private sealed record SampleFence(string File, int FenceIndex, int StartLine, string Code);
 
-    private sealed record OverwriteSection(string File, string Uid, string Body);
+    private sealed record OverwriteSection(string File, string Uid, string Body, bool MappedToExample = false);
 
     private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
 }

From 1cfc2bb60b30fc8ed3e480e4794a4b07690ed074 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 23:03:22 +0200
Subject: [PATCH 43/88] =?UTF-8?q?=F0=9F=93=9A=20docfx=20validator:=20docum?=
 =?UTF-8?q?ent=20example=20form=20detection?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the two DocFX overwrite file example forms: Form A (example: *content or example: [*content] front matter) for type pages requiring only a bare C# fence, and Form B (summary: *content with explicit heading) for conceptual content. Explain that Form A prevents duplicate headings because DocFX renders the section header automatically.
---
 .../references/docfx-overwrite-files.md                  | 8 ++++++++
 skills/dotnet-docfx-digest/references/scripts.md         | 9 +++++++++
 2 files changed, 17 insertions(+)

diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
index 237ef89..af1585f 100644
--- a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -47,6 +47,14 @@ Console.WriteLine(value);
 
 Do **not** include a `### Examples` heading in the body. DocFX adds the section header automatically from the template.
 
+> The validator distinguishes two example forms by the front matter, not by headings in the body. Do not rely on a body heading to make the validator happy.
+>
+> **Form A — front matter `example: *content` (or the `- *content` list form).** This is the recommended form for type pages and extension-class pages. The body must contain at least one fenced `csharp` (or `cs`) block. Do **not** add a `## Example` or `### Example` heading; DocFX renders the section header automatically and a manual heading produces a duplicate "Examples" heading on the rendered page.
+>
+> **Form B — front matter `summary: *content`.** The body must contain a `## Example` or `### Example` heading followed by a fenced `csharp` (or `cs`) block. This form is only for the rare case where the example is embedded inside conceptual content.
+>
+> The validator recognizes Form A by the YAML anchor, not by a body heading; Form B by the body heading. Mixing them produces duplicate sections or validator failures.
+
 Do **not** use `summary: *content` for type example files. That replaces only the summary text and does nothing to add a visible Examples section to the page.
 
 DocFX applies overwrite models by `uid`. If the same `uid` appears more than once in one overwrite file, later sections in that same file override earlier sections. Across different overwrite files, ordering is not deterministic, so keep competing sections for the same `uid` together or consolidate them.
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 4490473..6b20e2c 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -94,6 +94,15 @@ A skip marker without a reason is reported as `SAMPLE_SKIP_REASON_MISSING`.
 
 A skip marker with a weak reason such as "full example requires X package" or "example shows the framework pattern" is reported as `SAMPLE_SKIP_REASON_INSUFFICIENT`. Package requirements and framework setup belong in the documentation around a compiling sample; they are not enough to skip compilation by themselves.
 
+### Example detection
+
+The validator recognizes a complete example as one of:
+
+- A DocFX front-matter anchor (`example: *content` or the list form `example:\n- *content`) followed by a body that contains a fenced `csharp`/`cs` block; **or**
+- A `## Example` / `### Example` heading in the body followed by a fenced `csharp`/`cs` block.
+
+The first form is preferred for type pages and extension-class pages. Add a `### Examples` heading only when the front matter anchors the body to `summary` and you intend the heading to delimit the embedded example. The validator reports `EXAMPLE_MISSING` only when neither form is present. A run that reports `EXAMPLE_MISSING` while the rendered page clearly shows an example indicates a front-matter / heading mismatch — verify the YAML anchor before adding a body heading.
+
 ### Extension-method detection note
 
 Extension methods are detected from compiled metadata: a public static method carrying `System.Runtime.CompilerServices.ExtensionAttribute`, declared on a public class (which may be generic or a static extension container) with at least one parameter. The first parameter's type is recorded as the extended type. The C# compiler marks the method, not the first parameter, with `ExtensionAttribute`, so detection keys off the method attribute to match real metadata. Generic declaring classes and generic extension methods are both valid targets and are not excluded.

From 1f8bcb766f287c4421a684f7dc688adf92081aed Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Wed, 10 Jun 2026 23:03:35 +0200
Subject: [PATCH 44/88] =?UTF-8?q?=E2=9C=85=20add=20validator=20tests=20for?=
 =?UTF-8?q?=20docfx=20overwrite=20example=20forms?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add five new evaluation tests (IDs 35–39) covering DocFX overwrite file example validation: Form A with bare fence, Form A with list front matter, Form B with summary anchor and heading, Form A with redundant heading, and Form A with missing fence. Verify that validator correctly distinguishes forms and reports EXAMPLE_MISSING only when fence is absent.
---
 skills/dotnet-docfx-digest/evals/evals.json | 60 +++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index cb16b32..358f6c8 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -430,6 +430,66 @@
         "Does not fall back to scanning src/**/*.csproj when docfx.json produces no projects",
         "Does not attempt to document any projects or generate any overwrite files when project discovery fails"
       ]
+    },
+    {
+      "id": 35,
+      "prompt": "Create a DocFX overwrite file for type `Acme.Widgets.Spinner` using the recommended `example: *content` front-matter form. The body should contain only a bare csharp fence with no `### Examples` heading. Confirm that the validator accepts this as a complete example.",
+      "expected_output": "The agent writes the overwrite file with front matter `example: *content` and a bare csharp fence in the body (no `### Examples` heading). The validator runs and reports zero `EXAMPLE_MISSING` diagnostics for `Acme.Widgets.Spinner`. The agent does not add a heading because the skill instructs that DocFX renders the section header automatically.",
+      "expectations": [
+        "Front matter uses `example: *content` (or the `- *content` list form), not `summary: *content`",
+        "Body contains a csharp or cs fenced code block",
+        "Body does NOT contain a `### Examples` or `## Example` heading",
+        "Validator runs and does not emit EXAMPLE_MISSING for the target type",
+        "Agent explains that DocFX adds the Examples section header automatically so a manual heading is not needed"
+      ]
+    },
+    {
+      "id": 36,
+      "prompt": "Create a DocFX overwrite file for type `Acme.Widgets.Spinner` using the `example:` list form (front matter has `example:` on one line and `- *content` on the next). The body contains only a bare csharp fence. Confirm that the validator accepts this as a complete example.",
+      "expected_output": "The agent writes the overwrite file with a multi-line `example:\\n- *content` front matter block and a bare csharp fence in the body. The validator runs and reports zero `EXAMPLE_MISSING` diagnostics for `Acme.Widgets.Spinner`.",
+      "expectations": [
+        "Front matter uses the list form with `example:` on one line and `- *content` on the next",
+        "Body contains a csharp or cs fenced code block",
+        "Body does NOT contain a `### Examples` or `## Example` heading",
+        "Validator runs and does not emit EXAMPLE_MISSING for the target type",
+        "Agent recognizes both inline and list `example:` forms as equivalent for validation purposes"
+      ]
+    },
+    {
+      "id": 37,
+      "prompt": "Create a DocFX overwrite file for a namespace overview page using `summary: *content` front matter. The body should embed a usage example under a `### Example` heading followed by a csharp fence. Confirm that the validator accepts this as a complete example.",
+      "expected_output": "The agent writes the overwrite file with `summary: *content` front matter and a `### Example` heading with a csharp fence inside the body. The validator runs and does not emit EXAMPLE_MISSING, because the heading-delimited fence satisfies the Form B detection rule.",
+      "expectations": [
+        "Front matter uses `summary: *content`",
+        "Body contains a `### Example` or `## Example` heading followed by a csharp or cs fenced code block",
+        "Validator runs and does not emit EXAMPLE_MISSING for the target",
+        "Agent correctly identifies this as the Form B (summary-anchored conceptual) pattern",
+        "Agent notes that this form is for conceptual content and is not the recommended form for type pages"
+      ]
+    },
+    {
+      "id": 38,
+      "prompt": "A developer created a DocFX overwrite for `Acme.Widgets.Spinner` using `example: *content` front matter but accidentally added a `### Examples` heading before the csharp fence. Confirm that the validator still passes (the redundant heading is tolerated by the validator) and that the prose guidance advises removing it to prevent a duplicate heading on the rendered page.",
+      "expected_output": "The validator runs and does not emit EXAMPLE_MISSING because the csharp fence is present regardless of the redundant heading. The agent flags the redundant heading as producing a duplicate 'Examples' section on the rendered DocFX page and advises removing it, citing the Form A guidance. The validator result is a pass; the rendered-page duplication is a separate documentation quality concern.",
+      "expectations": [
+        "Validator does not emit EXAMPLE_MISSING because a csharp fence is present",
+        "Agent identifies the `### Examples` heading as redundant for Form A (example: *content) overwrites",
+        "Agent explains that DocFX adds the section header automatically, so the manual heading causes a duplicate on the rendered page",
+        "Agent recommends removing the heading to avoid the duplicate-heading rendering defect",
+        "Validator exit code is 0 (or non-EXAMPLE_MISSING failure) — the redundant heading does not itself cause a validation error"
+      ]
+    },
+    {
+      "id": 39,
+      "prompt": "A DocFX overwrite file for `Acme.Widgets.Spinner` uses `example: *content` front matter but the body contains only descriptive prose with no csharp fence at all. Confirm that the validator reports EXAMPLE_MISSING.",
+      "expected_output": "The validator detects that the section has `example: *content` front matter (MappedToExample=true) but no csharp or cs fenced code block in the body. It emits an EXAMPLE_MISSING diagnostic for `Acme.Widgets.Spinner`. The absence of a heading alone does not satisfy the example requirement; a csharp fence is required regardless of the form.",
+      "expectations": [
+        "Validator emits EXAMPLE_MISSING for the target type",
+        "Diagnostic message identifies the expected overwrite path and instructs adding a C# code fence",
+        "Agent recognizes that the YAML anchor alone (example: *content) is not sufficient — a csharp fence must also be present",
+        "Agent does not suggest adding a ### Examples heading as the fix; it correctly identifies the missing fence as the root cause",
+        "Validator returns a non-zero exit code"
+      ]
     }
   ]
 }

From 235a16b15bb8bec933ecb1d6879fa200be04b824 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Thu, 11 Jun 2026 00:28:00 +0200
Subject: [PATCH 45/88] =?UTF-8?q?=F0=9F=93=9A=20docfx=20sample=20validatio?=
 =?UTF-8?q?n:=20document=20structure=20and=20compilation=20gates?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document two validation gates for C# code blocks: Gate 1 (structure) enforces namespace and type declarations unless labelled 'Program.cs'; Gate 2 (compilation) requires successful build in a class library verification project. Update workflow examples to show complete compilable code with namespace and class declarations.
---
 skills/dotnet-docfx-digest/SKILL.md           | 56 +++++++++++++++++--
 .../references/workflow.md                    | 35 +++++++++---
 2 files changed, 79 insertions(+), 12 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index c93cdb6..32379ea 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -106,6 +106,19 @@ Material changes include new or removed public API, signature or nullability cha
 
 Every public non-abstraction type and every public extension method needs at least one realistic, minimal, copy/paste-ready example. A namespace fly-in or `Extension Members` table alone is not enough.
 
+Every generated `csharp` code block is a complete, copy/paste-ready compilation unit. The default is always a compilable unit (option 1). Only use intentionally incomplete excerpts (option 2) when explicitly requested by the user, and label them clearly.
+
+**Complete C# example contract:**
+
+- Includes all required `using` directives.
+- Declares a file-scoped namespace (e.g., `namespace X.Y;`).
+- Declares at least one concrete class, struct, or record containing the usage.
+- Does **not** use top-level statements unless the example is explicitly labelled `// Program.cs` at the very top of the code block.
+- Does **not** invent placeholder services, interfaces, classes, methods, or overloads that are not defined inside the same code block.
+- Does **not** derive from an abstract or generic base type without supplying the correct concrete type arguments.
+- Does **not** call members that do not exist on the resolved public API surface.
+- Compiles in a minimal class library verification project referencing the documented assemblies.
+
 Prefer examples derived from existing unit, functional, or integration tests, then from samples, then from a minimal new example based on actual public behavior. Convert Arrange/Act/Assert test structure into consumer-oriented sample code instead of pasting raw assertions.
 
 For public non-abstraction types, put the example on the generated type page by targeting the type UID in DocFX overwrite content. In Codebelt repositories, keep authored type overwrite Markdown under `.docfx/api/types/`, typically as `.docfx/api/types/{TypeUid}.md`.
@@ -120,17 +133,50 @@ For managed reference pages, map type and extension-method examples to the `exam
 
 ## Example Verification
 
-Every added or changed C# sample must compile. The validator compiles documentation samples as .NET 10 file-based apps.
+Every added or changed `csharp` code block must pass two validation gates before it is written to a markdown file. Do not write any `csharp` fence without first verifying both gates pass.
+
+**Gate 1 — Static structure (`SAMPLE_STRUCTURE_INVALID`):**
+
+Before attempting compilation, the validator rejects code that:
 
-Use a skip marker only when compilation is genuinely impossible in deterministic validation:
+- Contains top-level statements without a `// Program.cs` comment label at the top.
+- Lacks a namespace declaration.
+- Lacks a type declaration (class, struct, or record).
+
+A code block labelled `// Program.cs` at the very top passes Gate 1 and is compiled as a file-based app.
+
+**Gate 2 — Compilation (`SAMPLE_COMPILE_FAILED`):**
+
+Class-based examples that pass Gate 1 are compiled as a class library project referencing all assemblies from `docfx.json`. If compilation fails, the example is rejected. Either repair and re-run, or omit the example and add:
+
+```markdown
+<!-- No compile-valid example could be generated for this type. -->
+```
+
+**Example generation source priority:**
+
+1. Existing tests that reference the documented type or member.
+2. Existing samples or README usage in the repository.
+3. Synthesized examples only when the full public API shape is resolved and the synthesized sample compiles.
+4. Omit the example entirely if none of the above yields a compile-valid example.
+
+**Reflection and API-shape requirements:**
+
+Resolve constructors, generic arity, abstractness, constraints, and public members before writing examples:
+
+- Generic types: supply concrete type arguments (e.g., `Repository<Product>`, not `Repository<T>`).
+- Abstract types: do not instantiate directly; derive with a concrete class that supplies all required generic parameters.
+- Extension methods: show a valid receiver type.
+- Do not assume parameterless constructors or methods not present in the reflected API surface.
+- Do not invent members; if a member cannot be confirmed, omit the example.
+
+**Skip marker (last resort only):**
 
 ```csharp
 // dotnet-docfx-digest:skip-compile - <reason>
 ```
 
-The reason is mandatory and must explain the actual blocker. Reasons such as “full example requires package X” or “shows the framework pattern” are insufficient. Prefer making the sample compile by adding normal public setup code or reducing the sample to the smallest compiling example.
-
-Do not claim a sample compiles unless the validator or an equivalent repository verification command compiled it successfully.
+The reason is mandatory. Package requirements, "full example needs X", or "shows the framework pattern" are rejected. Prefer making the example compile. Do not claim an example compiles unless the validator actually ran it successfully.
 
 ## Namespace and Summary Style
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 55b53d9..634e1d8 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -110,12 +110,20 @@ The following example shows how to use `MyType` in a consuming application.
 ```csharp
 using X.Y.Z;
 
-var value = new MyType();
-Console.WriteLine(value);
+namespace MyNamespace;
+
+public class MyTypeExample
+{
+    public void ShowUsage()
+    {
+        var value = new MyType();
+        Console.WriteLine(value);
+    }
+}
 ```
 ````
 
-Do not include a manual `### Examples` heading in the body. DocFX renders that heading automatically for the `example` property.
+Do not include a manual `### Examples` heading in the body. DocFX renders that heading automatically for the `example` property. Every `csharp` code block must include a file-scoped namespace and at least one class declaration; top-level statements are not allowed unless the block is labelled `// Program.cs`.
 
 ## Extension method example template
 
@@ -132,13 +140,21 @@ The following example shows how to call `NormalizeLineEndings` on a string.
 ```csharp
 using X.Y.Z;
 
-string text = "first\r\nsecond";
-string normalized = text.NormalizeLineEndings();
-Console.WriteLine(normalized);
+namespace MyNamespace;
+
+public class MyExtensionsExample
+{
+    public void ShowUsage()
+    {
+        string text = "first\r\nsecond";
+        string normalized = text.NormalizeLineEndings();
+        Console.WriteLine(normalized);
+    }
+}
 ```
 ````
 
-The namespace containing the extension method must be imported, and the sample must compile in a consumer-style context.
+The namespace containing the extension method must be imported, the receiver type must be valid, and the sample must compile in a class library verification project.
 
 ## Synthetic hash-suffix filenames are prohibited
 
@@ -169,6 +185,11 @@ Before completing documentation work, verify:
 - [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`. Namespace pages are under `api/namespaces/` and type pages are under `api/types/`.
 - [ ] The Completion Repair Loop was run after edits, and remaining `EXAMPLE_MISSING` or overwrite-layout diagnostics were fixed or reported as exact blockers.
 - [ ] Examples are realistic, copy/paste-ready, and compile unless a justified skip marker is present.
+- [ ] Generated C# examples include a file-scoped namespace and a type declaration (class, struct, or record), or are explicitly labelled `// Program.cs`.
+- [ ] No generated C# example uses top-level statements without a `// Program.cs` label.
+- [ ] No generated C# example derives from a generic base type without concrete type arguments.
+- [ ] No generated C# example calls members that are not confirmed on the public API surface.
+- [ ] Where no compile-valid example could be generated, the overwrite file contains the appropriate omission comment.
 - [ ] Availability is included or explicitly stated and matches actual target frameworks and conditions.
 - [ ] Existing manual edits are preserved, stale documentation is corrected, and no contradictory documentation remains.
 - [ ] `git diff` for touched documentation paths was inspected before final verification.

From 1e1c92d7359009610b4090434c7fbeb9d4bab17a Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Thu, 11 Jun 2026 00:28:07 +0200
Subject: [PATCH 46/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20docfx=20validator:?=
 =?UTF-8?q?=20implement=20sample=20structure=20validation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add ValidateSampleStructure gate that rejects examples with top-level statements unless explicitly labelled '// Program.cs'. Enforce namespace and type declarations before compilation. Split sample compilation into two paths: file-based apps (Program.cs) and class libraries (all others). Pass framework parameter through compilation chain to respect docfx.json target framework.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 137 ++++++++++++++++++--
 1 file changed, 129 insertions(+), 8 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 98438fb..eae5aab 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -224,8 +224,8 @@ private static int Validate(Options options)
         }
 
         // 14-15. Produce report and return a deterministic exit code.
-        bool hasSampleError = report.Errors.Any(e => e.Code is "SAMPLE_COMPILE_FAILED");
-        bool hasOtherError = report.Errors.Any(e => e.Code is not "SAMPLE_COMPILE_FAILED");
+        bool hasSampleError = report.Errors.Any(e => e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_STRUCTURE_INVALID");
+        bool hasOtherError = report.Errors.Any(e => e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_STRUCTURE_INVALID");
 
         report.Status = report.Errors.Count == 0 ? "passed" : "failed";
         report.Summary.Errors = report.Errors.Count;
@@ -2456,7 +2456,15 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
                     continue;
                 }
 
-                var (ok, diagnostics, exitCode) = CompileSample(tempRoot, index, sample, libraryProjects, options.Configuration, repoRoot);
+                var structureError = ValidateSampleStructure(sample.Code);
+                if (structureError is not null)
+                {
+                    report.Errors.Add(new Diagnostic("SAMPLE_STRUCTURE_INVALID", Rel(repoRoot, sample.File), null,
+                        $"C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) failed structure validation: {structureError}"));
+                    continue;
+                }
+
+                var (ok, diagnostics, exitCode) = CompileSample(tempRoot, index, sample, libraryProjects, options.Configuration, options.Framework, repoRoot);
                 if (ok)
                 {
                     report.Summary.SamplesCompiled++;
@@ -2475,14 +2483,29 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
     }
 
     private static (bool Ok, string Diagnostics, int ExitCode) CompileSample(string tempRoot, int index, SampleFence sample,
-        List<ProjectInfo> libraryProjects, string configuration, string repoRoot)
+        List<ProjectInfo> libraryProjects, string configuration, string? framework, string repoRoot)
     {
         var dir = Path.Combine(tempRoot, "sample_" + index);
         Directory.CreateDirectory(dir);
+
+        // Examples labelled // Program.cs are compiled as file-based apps (top-level statements).
+        // All other examples (which have passed ValidateSampleStructure) are class-based and compiled
+        // as a class library project that references the documented assemblies.
+        if (IsProgramCsExample(sample.Code))
+        {
+            return CompileAsFileBasedApp(dir, sample, libraryProjects, framework, configuration, repoRoot);
+        }
+
+        return CompileAsClassLibrary(dir, sample, libraryProjects, framework, configuration, repoRoot);
+    }
+
+    private static (bool Ok, string Diagnostics, int ExitCode) CompileAsFileBasedApp(string dir, SampleFence sample,
+        List<ProjectInfo> libraryProjects, string? framework, string configuration, string repoRoot)
+    {
         var file = Path.Combine(dir, "sample.cs");
 
         var sb = new StringBuilder();
-        sb.Append("#:property TargetFramework=net10.0\n");
+        sb.Append("#:property TargetFramework=").Append(framework ?? "net10.0").Append('\n');
         sb.Append("#:property PublishAot=false\n");
         sb.Append("#:property Nullable=enable\n");
         foreach (var proj in libraryProjects)
@@ -2504,6 +2527,43 @@ private static (bool Ok, string Diagnostics, int ExitCode) CompileSample(string
         return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
     }
 
+    private static (bool Ok, string Diagnostics, int ExitCode) CompileAsClassLibrary(string dir, SampleFence sample,
+        List<ProjectInfo> libraryProjects, string? framework, string configuration, string repoRoot)
+    {
+        var csFile = Path.Combine(dir, "Example.cs");
+        File.WriteAllText(csFile, sample.Code, new UTF8Encoding(false));
+
+        var tfm = framework ?? "net10.0";
+        var sb = new StringBuilder();
+        sb.AppendLine("""<Project Sdk="Microsoft.NET.Sdk">""");
+        sb.AppendLine("  <PropertyGroup>");
+        sb.AppendLine($"    <TargetFramework>{tfm}</TargetFramework>");
+        sb.AppendLine("    <OutputType>Library</OutputType>");
+        sb.AppendLine("    <Nullable>enable</Nullable>");
+        sb.AppendLine("    <LangVersion>latest</LangVersion>");
+        sb.AppendLine("    <ImplicitUsings>disable</ImplicitUsings>");
+        sb.AppendLine("  </PropertyGroup>");
+        if (libraryProjects.Count > 0)
+        {
+            sb.AppendLine("  <ItemGroup>");
+            foreach (var proj in libraryProjects)
+            {
+                sb.AppendLine($"""    <ProjectReference Include="{proj.Path}" />""");
+            }
+
+            sb.AppendLine("  </ItemGroup>");
+        }
+
+        sb.AppendLine("</Project>");
+
+        var csprojFile = Path.Combine(dir, "SampleVerification.csproj");
+        File.WriteAllText(csprojFile, sb.ToString(), new UTF8Encoding(false));
+
+        var signingProperty = HasRootStrongNameKey(repoRoot) ? string.Empty : " -p:SkipSignAssembly=true";
+        var result = RunProcess("dotnet", $"build \"{csprojFile}\" -c {configuration} --nologo{signingProperty}", dir);
+        return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
+    }
+
     private static List<SampleFence> ExtractFences(string mdFile)
     {
         var fences = new List<SampleFence>();
@@ -2612,6 +2672,66 @@ private static bool IsMappedToExample(string yaml)
         return false;
     }
 
+    private static string? ValidateSampleStructure(string code)
+    {
+        // Examples explicitly labelled // Program.cs may use top-level statements.
+        if (IsProgramCsExample(code))
+        {
+            return null;
+        }
+
+        // A namespace declaration: file-scoped (namespace X;) or block-scoped (namespace X {)
+        bool hasNamespace = Regex.IsMatch(code, @"^\s*namespace\s+[\w.]+", RegexOptions.Multiline);
+
+        // A type declaration: class Foo, struct Foo, or record Foo (with or without access modifiers)
+        bool hasTypeDeclaration = Regex.IsMatch(code, @"\b(class|struct|record)\s+\w+");
+
+        if (!hasNamespace && !hasTypeDeclaration)
+        {
+            return "Example uses top-level statements without a namespace or type declaration. " +
+                   "All csharp code blocks must include a file-scoped namespace declaration (e.g., 'namespace X.Y;') " +
+                   "and at least one class, struct, or record declaration wrapping the usage code. " +
+                   "Label the example '// Program.cs' at the very top to allow top-level statements for console app examples.";
+        }
+
+        if (!hasNamespace)
+        {
+            return "Example has a type declaration but is missing a namespace declaration. " +
+                   "Add a file-scoped namespace such as 'namespace X.Y;' before the type declaration.";
+        }
+
+        if (!hasTypeDeclaration)
+        {
+            return "Example declares a namespace but contains no class, struct, or record declaration. " +
+                   "Wrap the usage code inside a class.";
+        }
+
+        return null;
+    }
+
+    private static bool IsProgramCsExample(string code)
+    {
+        foreach (var line in code.Split('\n'))
+        {
+            var trimmed = line.Trim();
+            if (trimmed.StartsWith("//", StringComparison.Ordinal) &&
+                trimmed.Contains("Program.cs", StringComparison.OrdinalIgnoreCase))
+            {
+                return true;
+            }
+
+            // Stop checking once non-blank, non-comment, non-directive content begins.
+            if (trimmed.Length > 0 &&
+                !trimmed.StartsWith("//", StringComparison.Ordinal) &&
+                !trimmed.StartsWith("#", StringComparison.Ordinal))
+            {
+                break;
+            }
+        }
+
+        return false;
+    }
+
     private static (bool Found, string Reason) FindSkip(string code)
     {
         foreach (var line in code.Split('\n'))
@@ -2947,13 +3067,13 @@ private static string BuildRepairPlan(Report report)
             e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal)));
         AppendRequiredExampleDiagnostics(sb, report.Errors.Where(e => e.Code is "EXAMPLE_MISSING"));
         AppendDiagnostics(sb, "Sample Compilation Repairs", report.Errors.Where(e =>
-            e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_SKIP_REASON_MISSING" or "SAMPLE_SKIP_REASON_INSUFFICIENT"));
+            e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_SKIP_REASON_MISSING" or "SAMPLE_SKIP_REASON_INSUFFICIENT" or "SAMPLE_STRUCTURE_INVALID"));
         AppendDiagnostics(sb, "Other Errors", report.Errors.Where(e =>
             e.Code is not "AGENTS_BLOCK_MISSING" &&
             !e.Code.StartsWith("NAMESPACE_", StringComparison.Ordinal) &&
             !e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal) &&
             e.Code is not "EXAMPLE_MISSING" &&
-            e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_SKIP_REASON_MISSING" and not "SAMPLE_SKIP_REASON_INSUFFICIENT"));
+            e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_SKIP_REASON_MISSING" and not "SAMPLE_SKIP_REASON_INSUFFICIENT" and not "SAMPLE_STRUCTURE_INVALID"));
         AppendDiagnostics(sb, "Warnings", report.Warnings);
 
         sb.AppendLine("## Completion Checklist");
@@ -2961,7 +3081,8 @@ e.Code is not "EXAMPLE_MISSING" &&
         sb.AppendLine("- [ ] `agents.cs` has run successfully when `AGENTS_BLOCK_MISSING` appears.");
         sb.AppendLine("- [ ] Every namespace diagnostic above has been resolved or intentionally excluded with evidence.");
         sb.AppendLine("- [ ] Every `EXAMPLE_MISSING` diagnostic above maps to a concrete example location.");
-        sb.AppendLine("- [ ] Changed C# examples compile.");
+        sb.AppendLine("- [ ] Changed C# examples pass structural validation (namespace + type declaration, or labelled `// Program.cs`).");
+        sb.AppendLine("- [ ] Changed C# examples compile as a class library project referencing the documented assemblies.");
         sb.AppendLine("- [ ] Authored Markdown files still exist after generated-artifact cleanup.");
         sb.AppendLine("- [ ] Final validation command and exit code are reported.");
 

From d0e8d52363f23569856e406bdfa8c8c0282cc5a9 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Thu, 11 Jun 2026 00:28:14 +0200
Subject: [PATCH 47/88] =?UTF-8?q?=E2=9C=85=20add=20validator=20tests=20for?=
 =?UTF-8?q?=20sample=20structure=20validation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add nine new evaluation tests (IDs 40–48) covering sample structure validation: examples with/without namespace, with/without type declarations, Program.cs labelled examples, missing structure elements, incomplete examples without // Program.cs label, and compilation success/failure scenarios. Verify structure gate rejects bare statements and compilation gate runs after structure passes.
---
 skills/dotnet-docfx-digest/evals/evals.json | 106 ++++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 358f6c8..1357483 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -490,6 +490,112 @@
         "Agent does not suggest adding a ### Examples heading as the fix; it correctly identifies the missing fence as the root cause",
         "Validator returns a non-zero exit code"
       ]
+    },
+    {
+      "id": 40,
+      "prompt": "A DocFX overwrite file for `Acme.Widgets.Spinner` contains the following csharp fence that uses only top-level statements:\n```csharp\nusing Acme.Widgets;\nvar spinner = new Spinner();\nspinner.Start();\n```\nRun scripts/docfx.cs validation and confirm the validator rejects this example.",
+      "expected_output": "The validator emits SAMPLE_STRUCTURE_INVALID for the top-level statement example because it lacks a namespace declaration and a type declaration. The exit code is non-zero. The diagnostic message instructs adding a file-scoped namespace and a class wrapper, or labelling the example '// Program.cs' if top-level statements are intentional.",
+      "expectations": [
+        "Validator emits SAMPLE_STRUCTURE_INVALID for the csharp fence that uses only top-level statements",
+        "Diagnostic message instructs adding a file-scoped namespace declaration (e.g., 'namespace X.Y;')",
+        "Diagnostic message instructs wrapping usage code in a class declaration",
+        "Validator returns a non-zero exit code",
+        "Validator does not attempt compilation for the structurally invalid example"
+      ]
+    },
+    {
+      "id": 41,
+      "prompt": "A DocFX overwrite file for `Acme.Widgets.Spinner` contains the following csharp fence that is labelled '// Program.cs' and uses top-level statements:\n```csharp\n// Program.cs\nusing Acme.Widgets;\nvar spinner = new Spinner();\nspinner.Start();\n```\nRun scripts/docfx.cs validation and confirm the validator allows this example.",
+      "expected_output": "The validator recognises the '// Program.cs' label and does not emit SAMPLE_STRUCTURE_INVALID. It compiles the example as a file-based app instead. Any compile errors are still reported as SAMPLE_COMPILE_FAILED.",
+      "expectations": [
+        "Validator does not emit SAMPLE_STRUCTURE_INVALID for the example labelled '// Program.cs'",
+        "Validator attempts compilation as a file-based app rather than a class library",
+        "Structural gate is bypassed for the // Program.cs label only",
+        "Compile errors in the labelled example are still reported as SAMPLE_COMPILE_FAILED"
+      ]
+    },
+    {
+      "id": 42,
+      "prompt": "Use dotnet-docfx-digest to generate an example for a public concrete class `Acme.Core.Options`. Confirm the generated example includes a file-scoped namespace, a class declaration, all required using directives, and compiles as a class library.",
+      "expected_output": "The generated csharp code block begins with using directives, then a file-scoped namespace declaration, then a class containing the usage code. The validator compiles it as a class library project referencing the documented assemblies. No SAMPLE_STRUCTURE_INVALID or SAMPLE_COMPILE_FAILED diagnostic is emitted.",
+      "expectations": [
+        "Generated example contains a 'using Acme.Core;' directive (or equivalent)",
+        "Generated example contains a file-scoped namespace declaration such as 'namespace AcmeExample;'",
+        "Generated example contains at least one class declaration wrapping the usage code",
+        "Generated example does not use top-level statements",
+        "Validator compiles the example as a class library project and emits no SAMPLE_STRUCTURE_INVALID or SAMPLE_COMPILE_FAILED diagnostic"
+      ]
+    },
+    {
+      "id": 43,
+      "prompt": "Use dotnet-docfx-digest to generate an example for a generic public type `Acme.Core.Repository<T>`. Confirm the generated example supplies a concrete type argument and compiles.",
+      "expected_output": "The generated example instantiates Repository with a concrete type argument (e.g., Repository<Product>), not the open generic Repository<T>. The example includes a namespace and class declaration. The validator compiles it without errors.",
+      "expectations": [
+        "Generated example provides a concrete type argument for Repository<T> (e.g., Repository<Product> or Repository<string>)",
+        "Generated example does not reference the open generic form Repository<T> as a concrete instantiation",
+        "Generated example includes a file-scoped namespace and class declaration",
+        "Validator compiles the example and emits no SAMPLE_STRUCTURE_INVALID or SAMPLE_COMPILE_FAILED diagnostic"
+      ]
+    },
+    {
+      "id": 44,
+      "prompt": "Use dotnet-docfx-digest on a library that has a public abstract generic base class `ApplicationTest<TEntryPoint, T>`. A previous run generated an example that derives from `ApplicationTest` (missing both generic arguments). Repair the documentation.",
+      "expected_output": "The agent recognises that ApplicationTest<TEntryPoint, T> requires two generic type arguments. It either generates a valid concrete derived class supplying both arguments (e.g., `public class MyAppTest : ApplicationTest<Program, HttpClient>`), or omits the example entirely with an omission comment. The validator does not emit SAMPLE_COMPILE_FAILED after the repair. No example is written that derives from ApplicationTest without generic arguments.",
+      "expectations": [
+        "Removes or repairs the example that derives from ApplicationTest without generic arguments",
+        "If an example is generated, it provides concrete values for both TEntryPoint and T",
+        "If no compile-valid example can be generated for the abstract type, the overwrite file omits the example and contains an omission comment",
+        "Validator emits no SAMPLE_COMPILE_FAILED after the repair",
+        "Agent explains that abstract generic base types require concrete type arguments in all derived-class examples"
+      ]
+    },
+    {
+      "id": 45,
+      "prompt": "Use dotnet-docfx-digest on a library where the public type `Acme.Http.Sender` has a constructor requiring two interface dependencies `ITransport` and `ILogger` that are not publicly constructible. No tests or samples exist for this type. Confirm the skill omits the example rather than inventing plausible but non-compiling code.",
+      "expected_output": "The agent does not generate a csharp code block that invents implementations of ITransport or ILogger that do not exist in the library. Instead, it omits the example for Acme.Http.Sender and adds the deterministic omission comment '<!-- No compile-valid example could be generated for this type. -->' to the overwrite file. It reports the omission as part of the example inventory.",
+      "expectations": [
+        "Does not write a csharp fence that invents ITransport or ILogger implementations not present in the documented API",
+        "Adds the omission comment to the type overwrite file instead of writing an unverified code block",
+        "Reports the omission in the example inventory summary",
+        "Does not emit a csharp fence that would fail SAMPLE_COMPILE_FAILED or SAMPLE_STRUCTURE_INVALID",
+        "Explains that the example was omitted because no compile-valid example could be derived from source evidence"
+      ]
+    },
+    {
+      "id": 46,
+      "prompt": "Run scripts/docfx.cs validation on a repository where an existing overwrite file has a correctly structured csharp example with a namespace and class declaration. Confirm the validator compiles it as a class library project, not as a file-based app.",
+      "expected_output": "The validator detects that the csharp sample has a namespace and class declaration, compiles it as a class library project (SampleVerification.csproj with OutputType=Library) referencing the documented assemblies from docfx.json, and reports SamplesCompiled incremented. No SAMPLE_STRUCTURE_INVALID is emitted.",
+      "expectations": [
+        "Validator does not emit SAMPLE_STRUCTURE_INVALID for the class-based example",
+        "Validator compiles the example as a class library project referencing library assemblies from docfx.json",
+        "Validator does not require a top-level statement or Main method in the example",
+        "Validator reports the sample as compiled (SamplesCompiled incremented in summary)",
+        "Validator does not emit SAMPLE_COMPILE_FAILED when the example is structurally and semantically correct"
+      ]
+    },
+    {
+      "id": 47,
+      "prompt": "Use dotnet-docfx-digest to generate a type example for a static extension class `Acme.Core.StringExtensions` that exposes a generic extension method `Parse<T>(this string input)`. Confirm the generated example shows a valid string receiver, supplies a concrete type argument, includes namespace and class structure, and compiles.",
+      "expected_output": "The generated example calls the extension method on a string receiver with a concrete type argument (e.g., '42'.Parse<int>() or var s = '3.14'; s.Parse<double>()). The example has a file-scoped namespace and a class declaration. The validator compiles it without SAMPLE_STRUCTURE_INVALID or SAMPLE_COMPILE_FAILED.",
+      "expectations": [
+        "Generated example calls Parse with a concrete type argument (e.g., Parse<int> or Parse<double>)",
+        "Generated example uses a valid string receiver (string literal or string variable)",
+        "Generated example includes a file-scoped namespace and a class declaration",
+        "Validator emits no SAMPLE_STRUCTURE_INVALID or SAMPLE_COMPILE_FAILED for the example",
+        "Generated example does not use the open generic form Parse<T> without a concrete type binding"
+      ]
+    },
+    {
+      "id": 48,
+      "prompt": "Run dotnet-docfx-digest twice on a repository where the first run generated structurally valid, compile-passing class-based examples. Confirm the second run emits no SAMPLE_STRUCTURE_INVALID, no SAMPLE_COMPILE_FAILED, and makes no changes to existing example overwrite files.",
+      "expected_output": "The second run validates all existing csharp code blocks, finds them structurally valid and compile-passing, and reports SamplesCompiled with zero errors. No overwrite files are modified. The validator exits with status 'passed'.",
+      "expectations": [
+        "Second run emits no SAMPLE_STRUCTURE_INVALID diagnostics",
+        "Second run emits no SAMPLE_COMPILE_FAILED diagnostics",
+        "Second run does not modify existing example overwrite files",
+        "Second run reports validation passed with zero errors",
+        "Example validation is deterministic: the same csharp content produces the same validation result on repeated runs"
+      ]
     }
   ]
 }

From cc5fd17d3554a680b4a99a8b5e3acb951611a075 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Thu, 11 Jun 2026 22:12:21 +0200
Subject: [PATCH 48/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20docfx=20v?=
 =?UTF-8?q?alidation=20to=20support=20parallel=20sample=20processing?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 514 +++++++++++++++-----
 1 file changed, 400 insertions(+), 114 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index eae5aab..792038d 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -22,6 +22,7 @@ internal static class DocfxValidator
     private const string EndMarker = "<!-- dotnet-docfx-digest:end -->";
     private const string ExtensionAttributeFullName = "System.Runtime.CompilerServices.ExtensionAttribute";
     private const string SkipMarker = "dotnet-docfx-digest:skip-compile";
+    private const int DefaultSampleValidationParallelism = 2;
 
     private static readonly string[] IgnoredDirectorySegments = ["bin", "obj", "_site", ".git", ".vs", ".vscode", ".idea", "node_modules"];
     private static readonly TimeSpan ProcessTimeout = TimeSpan.FromMinutes(10);
@@ -87,6 +88,7 @@ public static int Run(string[] args)
     private static int Validate(Options options)
     {
         var report = new Report { Script = ScriptId };
+        var phaseTimer = new Stopwatch();
 
         // 1. Resolve repository root.
         string repoRoot;
@@ -140,26 +142,35 @@ private static int Validate(Options options)
             }
         }
 
-        // 4. Build the repository before metadata inspection.
-        var (buildOk, buildOutput) = BuildRepository(repoRoot, options.Configuration);
-        if (!buildOk)
-        {
-            report.Errors.Add(new Diagnostic("BUILD_FAILED", null, null,
-                $"dotnet build failed (configuration {options.Configuration}).\n{Trim(buildOutput)}"));
-            return Emit(options, report, ExitCode.BuildFailed, "Build failed.");
-        }
+        // Cache: compute once for the full validation run so callers do not repeatedly scan the repo root.
+        var hasStrongNameKey = HasRootStrongNameKey(repoRoot);
 
-        // 5-7. Discover public API, namespaces and extension methods from compiled metadata.
-        // Use docfx.json as the canonical documentation boundary: only projects referenced
-        // by metadata[].src[] in the active docfx.json are included. Projects under src/ that
-        // are not configured in docfx.json (test harnesses, benchmarks, samples, etc.) are excluded.
+        // 4. Discover DocFX metadata projects BEFORE building so the build is scoped to only
+        //    the projects included in the documentation boundary.
+        phaseTimer.Restart();
         var projects = DiscoverProjects(docfxPath, docfxWorkspace, report);
+        WritePhase(options, "project discovery", phaseTimer.Elapsed);
         if (projects.Count == 0)
         {
             return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Project discovery failed.");
         }
 
         var libraryProjects = projects.Where(p => !p.IsTest).ToList();
+
+        // 5. Restore and build only the projects referenced by the active docfx.json.
+        //    This avoids building the full solution when it contains unrelated projects.
+        phaseTimer.Restart();
+        var (buildOk, buildOutput) = BuildDocfxProjects(libraryProjects, repoRoot, options.Configuration, hasStrongNameKey);
+        WritePhase(options, "repository build", phaseTimer.Elapsed);
+        if (!buildOk)
+        {
+            report.Errors.Add(new Diagnostic("BUILD_FAILED", null, null,
+                $"dotnet build failed (configuration {options.Configuration}).\n{Trim(buildOutput)}"));
+            return Emit(options, report, ExitCode.BuildFailed, "Build failed.");
+        }
+
+        // 6. Discover public API, namespaces and extension methods from compiled metadata.
+        phaseTimer.Restart();
         ApiModel api;
         try
         {
@@ -172,6 +183,7 @@ private static int Validate(Options options)
             return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
         }
 
+        WritePhase(options, "api discovery", phaseTimer.Elapsed);
         if (api.Namespaces.Count == 0)
         {
             report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
@@ -183,15 +195,24 @@ private static int Validate(Options options)
         report.Summary.RequiredExampleTargets = api.RequiredExampleTargets.Count;
         report.Summary.ExtensionMethods = api.Namespaces.Sum(n => n.ExtensionMethods.Count);
 
-        // 8. Discover DocFX Markdown files from the DocFX build inputs.
+        // 7. Discover DocFX Markdown files from the DocFX build inputs.
+        phaseTimer.Restart();
         var markdownFiles = DiscoverMarkdown(repoRoot, docfxPath, docfxWorkspace, report);
+        WritePhase(options, "markdown discovery", phaseTimer.Elapsed);
+
+        // Build a filename-keyed index to replace the O(N*M) FirstOrDefault scan per namespace.
+        var namespacePageIndex = markdownFiles
+            .GroupBy(f => Path.GetFileNameWithoutExtension(f), StringComparer.OrdinalIgnoreCase)
+            .ToDictionary(g => g.Key, g => g.First(), StringComparer.OrdinalIgnoreCase);
 
-        // 9-11. Validate namespace overview pages, extension tables and availability.
+        // Pre-extract all overwrite sections once — reused by both namespace and required-example validation.
+        var allOverwriteSections = markdownFiles.SelectMany(ExtractOverwriteSections).ToList();
+
+        // 8. Validate namespace overview pages, extension tables and availability.
+        phaseTimer.Restart();
         foreach (var ns in api.Namespaces.OrderBy(n => n.Name, StringComparer.Ordinal))
         {
-            var page = markdownFiles.FirstOrDefault(f =>
-                string.Equals(Path.GetFileNameWithoutExtension(f), ns.Name, StringComparison.Ordinal));
-
+            namespacePageIndex.TryGetValue(ns.Name, out var page);
             if (page is null)
             {
                 report.Errors.Add(new Diagnostic("NAMESPACE_PAGE_MISSING", null, ns.Name,
@@ -208,22 +229,28 @@ private static int Validate(Options options)
             report.Summary.NamespacePagesValidated++;
         }
 
-        // 12. Verify mandatory examples exist before compiling the examples that were found.
-        ValidateRequiredExamples(repoRoot, docfxWorkspace, markdownFiles, api, options, changedFiles, report);
+        WritePhase(options, "namespace validation", phaseTimer.Elapsed);
+
+        // 9. Verify mandatory examples exist before compiling the examples that were found.
+        phaseTimer.Restart();
+        ValidateRequiredExamples(repoRoot, docfxWorkspace, allOverwriteSections, api, options, changedFiles, report);
+        WritePhase(options, "required example validation", phaseTimer.Elapsed);
 
-        // 13. Extract and compile C# documentation samples.
+        // 10. Extract and compile C# documentation samples with bounded parallelism.
         if (options.ValidateSamples)
         {
-            ValidateSamples(repoRoot, markdownFiles, libraryProjects, options, changedFiles, report);
+            ValidateSamples(repoRoot, markdownFiles, libraryProjects, options, changedFiles, hasStrongNameKey, report);
         }
 
         // Optional DocFX build verification happens in a temp copy so generated output never lands in the working tree.
         if (options.VerifyDocfxBuild)
         {
-            VerifyDocfxBuild(repoRoot, docfxPath, report);
+            phaseTimer.Restart();
+            VerifyDocfxBuild(repoRoot, docfxPath, hasStrongNameKey, report);
+            WritePhase(options, "docfx build verification", phaseTimer.Elapsed);
         }
 
-        // 14-15. Produce report and return a deterministic exit code.
+        // 11. Produce report and return a deterministic exit code.
         bool hasSampleError = report.Errors.Any(e => e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_STRUCTURE_INVALID");
         bool hasOtherError = report.Errors.Any(e => e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_STRUCTURE_INVALID");
 
@@ -978,7 +1005,7 @@ private static IEnumerable<string> EnumerateFiles(string root, string pattern)
         }
     }
 
-    private static void VerifyDocfxBuild(string repoRoot, string docfxPath, Report report)
+    private static void VerifyDocfxBuild(string repoRoot, string docfxPath, bool hasStrongNameKey, Report report)
     {
         var docfxExecutable = ResolveDocfxExecutable();
         if (docfxExecutable is null)
@@ -994,7 +1021,7 @@ private static void VerifyDocfxBuild(string repoRoot, string docfxPath, Report r
             CopyDirectory(repoRoot, tempRoot);
             var relativeDocfxPath = Path.GetRelativePath(repoRoot, docfxPath);
             var tempDocfxPath = Path.Combine(tempRoot, relativeDocfxPath);
-            var environment = HasRootStrongNameKey(tempRoot)
+            var environment = hasStrongNameKey
                 ? null
                 : new Dictionary<string, string> { ["SkipSignAssembly"] = "true" };
             var result = RunProcess(docfxExecutable, $"\"{tempDocfxPath}\"", tempRoot, environment);
@@ -1091,16 +1118,64 @@ private static bool AgentsBlockPresent(string agentsPath)
     // Build
     // ----------------------------------------------------------------------
 
-    private static (bool Ok, string Output) BuildRepository(string repoRoot, string configuration)
+    /// <summary>
+    /// Restores and builds only the library projects referenced by the active docfx.json.
+    /// Restore runs once against the solution (when present) or each project individually.
+    /// Build runs per-project with <c>--no-restore</c> to avoid redundant NuGet evaluation.
+    /// </summary>
+    private static (bool Ok, string Output) BuildDocfxProjects(
+        List<ProjectInfo> libraryProjects, string repoRoot, string configuration, bool hasStrongNameKey)
     {
-        // Build a solution if one is present, otherwise let dotnet resolve the project in the repo root.
-        var target = Directory.GetFiles(repoRoot, "*.slnx").Concat(Directory.GetFiles(repoRoot, "*.sln")).FirstOrDefault();
-        var signingProperty = HasRootStrongNameKey(repoRoot) ? string.Empty : " -p:SkipSignAssembly=true";
-        var args = target is null
-            ? $"build -c {configuration} --nologo{signingProperty}"
-            : $"build \"{target}\" -c {configuration} --nologo{signingProperty}";
-        var result = RunProcess("dotnet", args, repoRoot);
-        return (result.ExitCode == 0, result.StdOut + result.StdErr);
+        if (libraryProjects.Count == 0)
+        {
+            return (true, string.Empty);
+        }
+
+        var signingProperty = hasStrongNameKey ? string.Empty : " -p:SkipSignAssembly=true";
+
+        // Prefer restoring the whole solution so the dependency graph for all documented
+        // projects is resolved in one pass; fall back to per-project restores when no
+        // solution exists.
+        var solutionFile = Directory.GetFiles(repoRoot, "*.slnx")
+            .Concat(Directory.GetFiles(repoRoot, "*.sln"))
+            .FirstOrDefault();
+
+        if (solutionFile is not null)
+        {
+            var restoreResult = RunProcess("dotnet",
+                $"restore \"{solutionFile}\" --nologo{signingProperty}", repoRoot);
+            if (restoreResult.ExitCode != 0)
+            {
+                return (false, restoreResult.StdOut + restoreResult.StdErr);
+            }
+        }
+        else
+        {
+            foreach (var proj in libraryProjects)
+            {
+                var restoreResult = RunProcess("dotnet",
+                    $"restore \"{proj.Path}\" --nologo{signingProperty}", repoRoot);
+                if (restoreResult.ExitCode != 0)
+                {
+                    return (false, restoreResult.StdOut + restoreResult.StdErr);
+                }
+            }
+        }
+
+        // Build each documented project individually with --no-restore.
+        var buildOutput = new StringBuilder();
+        foreach (var proj in libraryProjects)
+        {
+            var result = RunProcess("dotnet",
+                $"build \"{proj.Path}\" -c {configuration} --no-restore --nologo{signingProperty}", repoRoot);
+            buildOutput.Append(result.StdOut).Append(result.StdErr);
+            if (result.ExitCode != 0)
+            {
+                return (false, buildOutput.ToString());
+            }
+        }
+
+        return (true, buildOutput.ToString());
     }
 
     private static bool HasRootStrongNameKey(string repoRoot)
@@ -2221,15 +2296,9 @@ private static bool HasAvailability(string body)
     // Required example validation
     // ----------------------------------------------------------------------
 
-    private static void ValidateRequiredExamples(string repoRoot, string docfxWorkspace, List<string> markdownFiles, ApiModel api,
+    private static void ValidateRequiredExamples(string repoRoot, string docfxWorkspace, IReadOnlyList<OverwriteSection> sections, ApiModel api,
         Options options, HashSet<string>? changedFiles, Report report)
     {
-        var sections = new List<OverwriteSection>();
-        foreach (var md in markdownFiles)
-        {
-            sections.AddRange(ExtractOverwriteSections(md));
-        }
-
         foreach (var target in api.RequiredExampleTargets)
         {
             if (options.ChangedOnly && changedFiles is not null &&
@@ -2409,8 +2478,10 @@ private static bool HasExampleSectionWithCSharpFence(string body)
     // ----------------------------------------------------------------------
 
     private static void ValidateSamples(string repoRoot, List<string> markdownFiles, List<ProjectInfo> libraryProjects,
-        Options options, HashSet<string>? changedFiles, Report report)
+        Options options, HashSet<string>? changedFiles, bool hasStrongNameKey, Report report)
     {
+        // 1. Extract all C# samples from Markdown files.
+        var phaseTimer = Stopwatch.StartNew();
         var samples = new List<SampleFence>();
         foreach (var md in markdownFiles)
         {
@@ -2422,57 +2493,126 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
             samples.AddRange(ExtractFences(md));
         }
 
+        WritePhase(options, "sample extraction", phaseTimer.Elapsed);
         if (samples.Count == 0)
         {
             return;
         }
 
+        // 2. Pre-validate structure (skip/structure checks) — no compilation.
+        //    Record which samples need compilation and their original index for deterministic ordering.
+        var toCompile = new List<(SampleFence Sample, int OriginalIndex)>(samples.Count);
+        for (int i = 0; i < samples.Count; i++)
+        {
+            var sample = samples[i];
+            var skip = FindSkip(sample.Code);
+            if (skip.Found)
+            {
+                if (string.IsNullOrWhiteSpace(skip.Reason))
+                {
+                    report.Errors.Add(new Diagnostic("SAMPLE_SKIP_REASON_MISSING", Rel(repoRoot, sample.File), null,
+                        $"A C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) uses the skip-compile marker without a mandatory reason."));
+                }
+                else if (IsInsufficientSkipReason(skip.Reason))
+                {
+                    report.Errors.Add(new Diagnostic("SAMPLE_SKIP_REASON_INSUFFICIENT", Rel(repoRoot, sample.File), null,
+                        $"A C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) uses a weak skip-compile reason: '{skip.Reason}'. Package requirements, framework-pattern explanations, or full-example notes are documentation work, not a compile opt-out. Make the sample compile, document the package requirement outside the code fence, or use a deterministic blocker such as an external service or host environment that the sample compiler cannot provide."));
+                }
+                else
+                {
+                    report.Summary.SamplesSkipped++;
+                }
+
+                continue;
+            }
+
+            var structureError = ValidateSampleStructure(sample.Code);
+            if (structureError is not null)
+            {
+                report.Errors.Add(new Diagnostic("SAMPLE_STRUCTURE_INVALID", Rel(repoRoot, sample.File), null,
+                    $"C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) failed structure validation: {structureError}"));
+                continue;
+            }
+
+            toCompile.Add((sample, i));
+        }
+
+        if (toCompile.Count == 0)
+        {
+            return;
+        }
+
+        // 3. Resolve built assembly DLL paths so worker projects can use direct <Reference> items
+        //    instead of rebuilding the project graph for every sample.
+        var assemblyRefs = ResolveBuiltAssemblyReferences(libraryProjects, options.Configuration, options.Framework);
+        if (assemblyRefs.Count < libraryProjects.Count && libraryProjects.Count > 0)
+        {
+            report.Warnings.Add(new Diagnostic("SAMPLE_WORKER_ASSEMBLY_FALLBACK", null, null,
+                $"Built DLL paths could not be resolved for {libraryProjects.Count - assemblyRefs.Count} of {libraryProjects.Count} documented " +
+                "project(s). Sample validation workers will use ProjectReference instead of direct assembly references for those projects, which may reduce performance."));
+        }
+
+        // 4. Create reusable sample-validation worker pool and compile with bounded parallelism.
         var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-samples-" + Guid.NewGuid().ToString("N"));
         Directory.CreateDirectory(tempRoot);
         try
         {
-            int index = 0;
-            foreach (var sample in samples)
+            var parallelism = GetSampleValidationParallelism(options);
+            var workerCount = Math.Min(parallelism, toCompile.Count);
+            WritePhaseStart(options, "sample validation", workerCount, toCompile.Count);
+            phaseTimer.Restart();
+
+            // Create and restore each worker once.
+            var workers = new SampleWorkerInfo[workerCount];
+            for (int w = 0; w < workerCount; w++)
             {
-                index++;
-                var skip = FindSkip(sample.Code);
-                if (skip.Found)
+                workers[w] = CreateSampleWorker(
+                    tempRoot, w + 1, assemblyRefs, libraryProjects,
+                    options.Framework ?? "net10.0", options.Configuration, repoRoot, hasStrongNameKey, report);
+            }
+
+            // Assign samples to workers in round-robin order. Each worker processes its
+            // stripe sequentially, so no synchronization is needed within a worker.
+            // Results are stored in a pre-sized indexed array to guarantee deterministic
+            // diagnostic ordering regardless of worker completion order.
+            var results = new SampleCompileResult?[samples.Count];
+            var workerTasks = Enumerable.Range(0, workerCount)
+                .Select(workerIdx =>
                 {
-                    if (string.IsNullOrWhiteSpace(skip.Reason))
+                    var mySamples = toCompile.Where((_, si) => si % workerCount == workerIdx).ToList();
+                    var myWorker = workers[workerIdx];
+                    return Task.Run(() =>
                     {
-                        report.Errors.Add(new Diagnostic("SAMPLE_SKIP_REASON_MISSING", Rel(repoRoot, sample.File), null,
-                            $"A C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) uses the skip-compile marker without a mandatory reason."));
-                    }
-                    else if (IsInsufficientSkipReason(skip.Reason))
-                    {
-                        report.Errors.Add(new Diagnostic("SAMPLE_SKIP_REASON_INSUFFICIENT", Rel(repoRoot, sample.File), null,
-                            $"A C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) uses a weak skip-compile reason: '{skip.Reason}'. Package requirements, framework-pattern explanations, or full-example notes are documentation work, not a compile opt-out. Make the sample compile, document the package requirement outside the code fence, or use a deterministic blocker such as an external service or host environment that the sample compiler cannot provide."));
-                    }
-                    else
-                    {
-                        report.Summary.SamplesSkipped++;
-                    }
+                        foreach (var (sample, originalIndex) in mySamples)
+                        {
+                            var (ok, diags, exitCode) = CompileWithWorker(myWorker, sample, options.Configuration, hasStrongNameKey);
+                            results[originalIndex] = new SampleCompileResult(ok, diags, exitCode);
+                        }
+                    });
+                })
+                .ToArray();
 
-                    continue;
-                }
+            Task.WaitAll(workerTasks);
+            WritePhase(options, "sample validation", phaseTimer.Elapsed);
 
-                var structureError = ValidateSampleStructure(sample.Code);
-                if (structureError is not null)
+            // 5. Merge results in original sample order for deterministic diagnostics.
+            for (int i = 0; i < samples.Count; i++)
+            {
+                var result = results[i];
+                if (result is null)
                 {
-                    report.Errors.Add(new Diagnostic("SAMPLE_STRUCTURE_INVALID", Rel(repoRoot, sample.File), null,
-                        $"C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) failed structure validation: {structureError}"));
-                    continue;
+                    continue; // was skipped or had a structure error
                 }
 
-                var (ok, diagnostics, exitCode) = CompileSample(tempRoot, index, sample, libraryProjects, options.Configuration, options.Framework, repoRoot);
-                if (ok)
+                if (result.Ok)
                 {
                     report.Summary.SamplesCompiled++;
                 }
                 else
                 {
+                    var sample = samples[i];
                     report.Errors.Add(new Diagnostic("SAMPLE_COMPILE_FAILED", Rel(repoRoot, sample.File), null,
-                        $"C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) failed to compile (exit {exitCode}).\n{Trim(diagnostics)}"));
+                        $"C# sample at fence #{sample.FenceIndex} (line {sample.StartLine}) failed to compile (exit {result.ExitCode}).\n{Trim(result.Diagnostics)}"));
                 }
             }
         }
@@ -2482,86 +2622,207 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
         }
     }
 
-    private static (bool Ok, string Diagnostics, int ExitCode) CompileSample(string tempRoot, int index, SampleFence sample,
-        List<ProjectInfo> libraryProjects, string configuration, string? framework, string repoRoot)
+    private static int GetSampleValidationParallelism(Options options)
     {
-        var dir = Path.Combine(tempRoot, "sample_" + index);
-        Directory.CreateDirectory(dir);
+        var processorCount = Math.Max(1, Environment.ProcessorCount);
+        const int MaxSupportedParallelism = 8;
+        var defaultParallelism = Math.Min(DefaultSampleValidationParallelism, processorCount);
 
-        // Examples labelled // Program.cs are compiled as file-based apps (top-level statements).
-        // All other examples (which have passed ValidateSampleStructure) are class-based and compiled
-        // as a class library project that references the documented assemblies.
-        if (IsProgramCsExample(sample.Code))
+        // CLI argument takes precedence over the environment variable.
+        if (options.SampleParallelism.HasValue)
+        {
+            return Math.Max(1, Math.Min(options.SampleParallelism.Value, Math.Min(processorCount, MaxSupportedParallelism)));
+        }
+
+        var rawValue = Environment.GetEnvironmentVariable("DOCFX_DIGEST_SAMPLE_PARALLELISM");
+        if (int.TryParse(rawValue, System.Globalization.NumberStyles.Integer,
+                System.Globalization.CultureInfo.InvariantCulture, out var configured) && configured > 0)
         {
-            return CompileAsFileBasedApp(dir, sample, libraryProjects, framework, configuration, repoRoot);
+            return Math.Min(configured, Math.Min(processorCount, MaxSupportedParallelism));
         }
 
-        return CompileAsClassLibrary(dir, sample, libraryProjects, framework, configuration, repoRoot);
+        return defaultParallelism;
     }
 
-    private static (bool Ok, string Diagnostics, int ExitCode) CompileAsFileBasedApp(string dir, SampleFence sample,
-        List<ProjectInfo> libraryProjects, string? framework, string configuration, string repoRoot)
+    private static List<(string AssemblyName, string DllPath)> ResolveBuiltAssemblyReferences(
+        List<ProjectInfo> libraryProjects, string configuration, string? framework)
     {
-        var file = Path.Combine(dir, "sample.cs");
-
-        var sb = new StringBuilder();
-        sb.Append("#:property TargetFramework=").Append(framework ?? "net10.0").Append('\n');
-        sb.Append("#:property PublishAot=false\n");
-        sb.Append("#:property Nullable=enable\n");
+        var refs = new List<(string, string)>(libraryProjects.Count);
         foreach (var proj in libraryProjects)
         {
-            sb.Append("#:project ").Append(proj.Path).Append('\n');
+            var dll = FindAssembly(proj, configuration, framework);
+            if (dll is not null && File.Exists(dll))
+            {
+                refs.Add((proj.AssemblyName, dll));
+            }
         }
 
-        sb.Append('\n');
-        sb.Append(sample.Code);
-        if (!sample.Code.EndsWith('\n'))
+        return refs;
+    }
+
+    /// <summary>
+    /// Creates a reusable sample-validation worker under <paramref name="tempRoot"/> and
+    /// performs a one-time restore so all subsequent sample builds can use <c>--no-restore</c>.
+    /// </summary>
+    private static SampleWorkerInfo CreateSampleWorker(
+        string tempRoot, int workerNumber,
+        List<(string AssemblyName, string DllPath)> assemblyRefs,
+        List<ProjectInfo> libraryProjects,
+        string framework, string configuration,
+        string repoRoot, bool hasStrongNameKey, Report report)
+    {
+        var workerDir = Path.Combine(tempRoot, "docfx-sample-workers", $"worker-{workerNumber:D4}");
+        var libDir = Path.Combine(workerDir, "lib");
+        var appDir = Path.Combine(workerDir, "app");
+        Directory.CreateDirectory(libDir);
+        Directory.CreateDirectory(appDir);
+
+        // Determine which documented projects need ProjectReference fallback (DLL not resolved).
+        var projectRefFallbacks = libraryProjects
+            .Where(p => !assemblyRefs.Any(r =>
+                string.Equals(r.AssemblyName, p.AssemblyName, StringComparison.OrdinalIgnoreCase)))
+            .ToList();
+
+        // Class-library project — for class-based samples (namespace + type declaration).
+        var libProjPath = Path.Combine(libDir, "DocfxSampleLib.csproj");
+        File.WriteAllText(libProjPath, GenerateSampleLibProject(assemblyRefs, projectRefFallbacks, framework),
+            new UTF8Encoding(false));
+        // Compilable placeholder; overwritten per sample.
+        File.WriteAllText(Path.Combine(libDir, "Sample.cs"),
+            "namespace DocfxSamplePlaceholder { internal static class _Placeholder { } }",
+            new UTF8Encoding(false));
+
+        // Console-app project — for Program.cs / top-level-statement samples.
+        var appProjPath = Path.Combine(appDir, "DocfxSampleApp.csproj");
+        File.WriteAllText(appProjPath, GenerateSampleAppProject(assemblyRefs, projectRefFallbacks, framework),
+            new UTF8Encoding(false));
+        // Compilable placeholder; overwritten per sample.
+        File.WriteAllText(Path.Combine(appDir, "Program.cs"), "// placeholder", new UTF8Encoding(false));
+
+        // Restore once so --no-restore works for all subsequent sample builds.
+        var signingProperty = hasStrongNameKey ? string.Empty : " -p:SkipSignAssembly=true";
+        var libRestoreOk = RunProcess("dotnet",
+            $"restore \"{libProjPath}\" --nologo{signingProperty}", libDir).ExitCode == 0;
+        var appRestoreOk = RunProcess("dotnet",
+            $"restore \"{appProjPath}\" --nologo{signingProperty}", appDir).ExitCode == 0;
+
+        if (!libRestoreOk || !appRestoreOk)
         {
-            sb.Append('\n');
+            report.Warnings.Add(new Diagnostic("SAMPLE_WORKER_RESTORE_FAILED", workerDir, null,
+                $"Sample validation worker {workerNumber} restore failed; affected samples will build without --no-restore and may be slower."));
         }
 
-        File.WriteAllText(file, sb.ToString(), new UTF8Encoding(false));
-
-        var signingProperty = HasRootStrongNameKey(repoRoot) ? string.Empty : " -p:SkipSignAssembly=true";
-        var result = RunProcess("dotnet", $"build \"{file}\" -c {configuration} --nologo{signingProperty}", dir);
-        return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
+        return new SampleWorkerInfo(libDir, appDir, libProjPath, appProjPath, libRestoreOk, appRestoreOk);
     }
 
-    private static (bool Ok, string Diagnostics, int ExitCode) CompileAsClassLibrary(string dir, SampleFence sample,
-        List<ProjectInfo> libraryProjects, string? framework, string configuration, string repoRoot)
+    private static string GenerateSampleLibProject(
+        List<(string AssemblyName, string DllPath)> assemblyRefs,
+        List<ProjectInfo> projectRefFallbacks,
+        string framework)
     {
-        var csFile = Path.Combine(dir, "Example.cs");
-        File.WriteAllText(csFile, sample.Code, new UTF8Encoding(false));
-
-        var tfm = framework ?? "net10.0";
         var sb = new StringBuilder();
         sb.AppendLine("""<Project Sdk="Microsoft.NET.Sdk">""");
         sb.AppendLine("  <PropertyGroup>");
-        sb.AppendLine($"    <TargetFramework>{tfm}</TargetFramework>");
+        sb.AppendLine($"    <TargetFramework>{framework}</TargetFramework>");
         sb.AppendLine("    <OutputType>Library</OutputType>");
         sb.AppendLine("    <Nullable>enable</Nullable>");
         sb.AppendLine("    <LangVersion>latest</LangVersion>");
         sb.AppendLine("    <ImplicitUsings>disable</ImplicitUsings>");
         sb.AppendLine("  </PropertyGroup>");
-        if (libraryProjects.Count > 0)
+        AppendReferenceItems(sb, assemblyRefs, projectRefFallbacks);
+        sb.AppendLine("</Project>");
+        return sb.ToString();
+    }
+
+    private static string GenerateSampleAppProject(
+        List<(string AssemblyName, string DllPath)> assemblyRefs,
+        List<ProjectInfo> projectRefFallbacks,
+        string framework)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine("""<Project Sdk="Microsoft.NET.Sdk">""");
+        sb.AppendLine("  <PropertyGroup>");
+        sb.AppendLine($"    <TargetFramework>{framework}</TargetFramework>");
+        sb.AppendLine("    <OutputType>Exe</OutputType>");
+        sb.AppendLine("    <Nullable>enable</Nullable>");
+        sb.AppendLine("    <LangVersion>latest</LangVersion>");
+        sb.AppendLine("    <PublishAot>false</PublishAot>");
+        sb.AppendLine("  </PropertyGroup>");
+        AppendReferenceItems(sb, assemblyRefs, projectRefFallbacks);
+        sb.AppendLine("</Project>");
+        return sb.ToString();
+    }
+
+    private static void AppendReferenceItems(
+        StringBuilder sb,
+        List<(string AssemblyName, string DllPath)> assemblyRefs,
+        List<ProjectInfo> projectRefFallbacks)
+    {
+        if (assemblyRefs.Count > 0)
         {
             sb.AppendLine("  <ItemGroup>");
-            foreach (var proj in libraryProjects)
+            foreach (var (assemblyName, dllPath) in assemblyRefs)
             {
-                sb.AppendLine($"""    <ProjectReference Include="{proj.Path}" />""");
+                sb.AppendLine($"    <Reference Include=\"{assemblyName}\">");
+                sb.AppendLine($"      <HintPath>{dllPath}</HintPath>");
+                sb.AppendLine("      <Private>false</Private>");
+                sb.AppendLine("    </Reference>");
             }
 
             sb.AppendLine("  </ItemGroup>");
         }
 
-        sb.AppendLine("</Project>");
+        if (projectRefFallbacks.Count > 0)
+        {
+            sb.AppendLine("  <ItemGroup>");
+            foreach (var proj in projectRefFallbacks)
+            {
+                sb.AppendLine($"    <ProjectReference Include=\"{proj.Path}\" />");
+            }
+
+            sb.AppendLine("  </ItemGroup>");
+        }
+    }
+
+    private static (bool Ok, string Diagnostics, int ExitCode) CompileWithWorker(
+        SampleWorkerInfo worker, SampleFence sample, string configuration, bool hasStrongNameKey)
+    {
+        var signingProperty = hasStrongNameKey ? string.Empty : " -p:SkipSignAssembly=true";
 
-        var csprojFile = Path.Combine(dir, "SampleVerification.csproj");
-        File.WriteAllText(csprojFile, sb.ToString(), new UTF8Encoding(false));
+        if (IsProgramCsExample(sample.Code))
+        {
+            // Top-level statement sample: write to Program.cs and build the app project.
+            var noRestoreFlag = worker.AppRestoreSucceeded ? " --no-restore" : string.Empty;
+            File.WriteAllText(Path.Combine(worker.AppDirectory, "Program.cs"), sample.Code, new UTF8Encoding(false));
+            var result = RunProcess("dotnet",
+                $"build \"{worker.AppProjectPath}\" -c {configuration}{noRestoreFlag} --nologo{signingProperty}",
+                worker.AppDirectory);
+            return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
+        }
+
+        // Class-based sample: write to Sample.cs and build the library project.
+        var libNoRestoreFlag = worker.LibRestoreSucceeded ? " --no-restore" : string.Empty;
+        File.WriteAllText(Path.Combine(worker.LibDirectory, "Sample.cs"), sample.Code, new UTF8Encoding(false));
+        var libResult = RunProcess("dotnet",
+            $"build \"{worker.LibProjectPath}\" -c {configuration}{libNoRestoreFlag} --nologo{signingProperty}",
+            worker.LibDirectory);
+        return (libResult.ExitCode == 0, libResult.StdOut + libResult.StdErr, libResult.ExitCode);
+    }
+
+    private static void WritePhase(Options options, string name, TimeSpan elapsed)
+    {
+        if (!options.Json)
+        {
+            Console.WriteLine($"  [phase] {name}: {elapsed.TotalSeconds:F2}s");
+        }
+    }
 
-        var signingProperty = HasRootStrongNameKey(repoRoot) ? string.Empty : " -p:SkipSignAssembly=true";
-        var result = RunProcess("dotnet", $"build \"{csprojFile}\" -c {configuration} --nologo{signingProperty}", dir);
-        return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
+    private static void WritePhaseStart(Options options, string name, int workers, int count)
+    {
+        if (!options.Json)
+        {
+            Console.WriteLine($"  [phase] {name}: {count} sample(s), {workers} worker(s)");
+        }
     }
 
     private static List<SampleFence> ExtractFences(string mdFile)
@@ -3214,6 +3475,11 @@ private static bool TryParse(string[] args, out Options options, out string erro
                     if (!Next(args, ref i, out var rp)) { error = "--repair-plan requires a path."; return false; }
                     options.RepairPlanPath = rp;
                     break;
+                case "--sample-parallelism":
+                    if (!Next(args, ref i, out var sp)) { error = "--sample-parallelism requires a count."; return false; }
+                    if (!int.TryParse(sp, out var spv) || spv < 1) { error = "--sample-parallelism must be a positive integer."; return false; }
+                    options.SampleParallelism = spv;
+                    break;
                 case "--clean-generated-metadata":
                     options.CleanGeneratedMetadata = true;
                     break;
@@ -3229,6 +3495,13 @@ private static bool TryParse(string[] args, out Options options, out string erro
                     if (TrySplit(arg, "--configuration", out var v3)) { options.Configuration = v3; break; }
                     if (TrySplit(arg, "--framework", out var v4)) { options.Framework = v4; break; }
                     if (TrySplit(arg, "--repair-plan", out var v5)) { options.RepairPlanPath = v5; break; }
+                    if (TrySplit(arg, "--sample-parallelism", out var v6) &&
+                        int.TryParse(v6, out var spvInline) && spvInline >= 1)
+                    {
+                        options.SampleParallelism = spvInline;
+                        break;
+                    }
+
                     error = $"Unknown argument: {arg}";
                     return false;
             }
@@ -3278,6 +3551,8 @@ dotnet run --file docfx.cs -- [options]
               --framework <tfm>        Optional target framework to validate against.
               --validate-samples       Compile C# samples. Default: enabled.
               --no-validate-samples    Skip C# sample compilation.
+              --sample-parallelism <n> Number of parallel sample-validation workers (1-8). Default: 2.
+                                       Override with env var DOCFX_DIGEST_SAMPLE_PARALLELISM.
               --changed-only           Validate only files changed according to git.
               --verify-docfx-build     Run DocFX against a temp copy of the repository so generated output stays outside the working tree.
               --repair-plan <path>     Write a deterministic Markdown repair plan from validation diagnostics.
@@ -3327,6 +3602,7 @@ private sealed class Options
         public bool CleanGeneratedMetadata { get; set; } = true;
         public bool Json { get; set; }
         public bool Help { get; set; }
+        public int? SampleParallelism { get; set; }
     }
 
     private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest);
@@ -3356,6 +3632,16 @@ private sealed record SampleFence(string File, int FenceIndex, int StartLine, st
     private sealed record OverwriteSection(string File, string Uid, string Body, bool MappedToExample = false);
 
     private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
+
+    private sealed record SampleWorkerInfo(
+        string LibDirectory,
+        string AppDirectory,
+        string LibProjectPath,
+        string AppProjectPath,
+        bool LibRestoreSucceeded,
+        bool AppRestoreSucceeded);
+
+    private sealed record SampleCompileResult(bool Ok, string Diagnostics, int ExitCode);
 }
 
 internal sealed class Diagnostic

From 412f4d49187c8cff778182b36113d569346e88ce Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Thu, 11 Jun 2026 22:56:30 +0200
Subject: [PATCH 49/88] =?UTF-8?q?=F0=9F=93=9D=20refresh=20docfx=20digest?=
 =?UTF-8?q?=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update docfx digest references and eval expectations to match the current workflow and validation guidance.
---
 skills/dotnet-docfx-digest/SKILL.md           | 19 +++++++++++++-----
 skills/dotnet-docfx-digest/evals/evals.json   | 20 +++++++++----------
 .../references/docfx-overwrite-files.md       | 10 +++++++---
 .../references/workflow.md                    | 12 ++++++-----
 skills/dotnet-new-lib-slnx/evals/evals.json   |  2 +-
 5 files changed, 39 insertions(+), 24 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 32379ea..ccf2b22 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -106,6 +106,8 @@ Material changes include new or removed public API, signature or nullability cha
 
 Every public non-abstraction type and every public extension method needs at least one realistic, minimal, copy/paste-ready example. A namespace fly-in or `Extension Members` table alone is not enough.
 
+**Tests are evidence, not output.** Do not add `ShowUsage`, `Usage`, `Example`, or documentation-only methods to test files. Use tests to understand the documented type's behavior, then transform that knowledge into consumer-facing DocFX overwrite examples.
+
 Every generated `csharp` code block is a complete, copy/paste-ready compilation unit. The default is always a compilable unit (option 1). Only use intentionally incomplete excerpts (option 2) when explicitly requested by the user, and label them clearly.
 
 **Complete C# example contract:**
@@ -119,7 +121,7 @@ Every generated `csharp` code block is a complete, copy/paste-ready compilation
 - Does **not** call members that do not exist on the resolved public API surface.
 - Compiles in a minimal class library verification project referencing the documented assemblies.
 
-Prefer examples derived from existing unit, functional, or integration tests, then from samples, then from a minimal new example based on actual public behavior. Convert Arrange/Act/Assert test structure into consumer-oriented sample code instead of pasting raw assertions.
+Prefer examples derived from existing unit, functional, or integration tests as behavioral evidence, then from samples, then from a minimal new example based on actual public behavior. Convert Arrange/Act/Assert test structure into consumer-oriented sample code instead of pasting raw test assertions, mocks, or fixture setup.
 
 For public non-abstraction types, put the example on the generated type page by targeting the type UID in DocFX overwrite content. In Codebelt repositories, keep authored type overwrite Markdown under `.docfx/api/types/`, typically as `.docfx/api/types/{TypeUid}.md`.
 
@@ -155,10 +157,17 @@ Class-based examples that pass Gate 1 are compiled as a class library project re
 
 **Example generation source priority:**
 
-1. Existing tests that reference the documented type or member.
-2. Existing samples or README usage in the repository.
-3. Synthesized examples only when the full public API shape is resolved and the synthesized sample compiles.
-4. Omit the example entirely if none of the above yields a compile-valid example.
+Derive examples from these sources, in order:
+
+1. Public API surface and XML documentation comments — establish the supported constructor signatures, method signatures, and types.
+2. Existing unit or functional tests that reference the documented type or member — use as behavioral evidence only; do not copy Arrange/Act/Assert structure, test fixtures, mocks, or test helper patterns into the final example unless the public API is specifically about testing.
+3. README, package documentation, samples, or existing conceptual docs in the repository.
+4. Implementation source, only when the public surface alone is insufficient to construct a valid calling example.
+5. Official upstream documentation when the library wraps an external framework or library.
+6. Synthesized examples only when all of the above confirm the full public API shape and the synthesized sample compiles.
+7. Omit the example entirely if none of the above yields a compile-valid, consumer-facing example.
+
+Final examples must be consumer-facing, realistic, and compile. They must read like production calling code, not test scaffolding.
 
 **Reflection and API-shape requirements:**
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 1357483..1cffea8 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -78,11 +78,11 @@
     {
       "id": 7,
       "prompt": "Use dotnet-docfx-digest on a .NET library whose namespace pages and Extension Members tables are present, but public non-abstraction types such as `ApplicationHostFactory` and public extension methods have no examples. The DocFX config already points `build.overwrite` at `.docfx/api/namespaces/**/*.md`, but some earlier authored overwrite Markdown still lives directly under `.docfx/api/*.md`.",
-      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates or moves readable overwrite files under `.docfx/api/namespaces/` for missing concrete-type examples, keeps `api/namespaces/**/*.md` under `build.overwrite` only, keeps `api/namespaces/**` excluded from `build.content`, puts type examples on the generated type page/overwrite section rather than the namespace UID page, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, runs the Completion Repair Loop by rerunning scripts/docfx.cs --json after edits, fixes remaining EXAMPLE_MISSING or overwrite-layout diagnostics instead of listing them as final notes, and uses --verify-docfx-build before completion so DocFX output is generated in temp space.",
+      "expected_output": "Agent does not stop after confirming namespace pages and extension tables. It audits public non-abstraction types and public extension methods for examples, creates or moves readable overwrite files under `.docfx/api/types/` for missing concrete-type examples, keeps `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` only, keeps `api/namespaces/**` and `api/types/**` excluded from `build.content`, puts type examples on the generated type page/overwrite section rather than the namespace UID page, uses generated UIDs rather than guessing, derives buildable examples from tests or actual public API behavior, runs the Completion Repair Loop by rerunning scripts/docfx.cs --json after edits, fixes remaining EXAMPLE_MISSING or overwrite-layout diagnostics instead of listing them as final notes, and uses --verify-docfx-build before completion so DocFX output is generated in temp space.",
       "expectations": [
         "Treats namespace overview pages and Extension Members tables as insufficient when examples are missing",
-        "Creates or moves readable type-targeting DocFX overwrite files under `.docfx/api/namespaces/` for public non-abstraction type examples",
-        "Keeps `api/namespaces/**/*.md` under `build.overwrite` only and excludes `api/namespaces/**` from `build.content`",
+        "Creates or moves readable type-targeting DocFX overwrite files under `.docfx/api/types/` for public non-abstraction type examples",
+        "Keeps `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` only and excludes `api/namespaces/**` and `api/types/**` from `build.content`",
         "Places a public ApplicationHostFactory example on the ApplicationHostFactory type page/overwrite section rather than only on the namespace page",
         "Creates or updates overwrite content for public extension method examples, or places the example on the extension class or namespace page while explicitly demonstrating the method",
         "Uses generated DocFX UIDs or verified metadata instead of inventing overwrite UIDs",
@@ -163,13 +163,13 @@
     {
       "id": 13,
       "prompt": "A previous run of dotnet-docfx-digest enhanced only `.docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.md` and added examples there, but the validator still reports `EXAMPLE_MISSING` for the public concrete type `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory`. Fix the documentation gap and explain why namespace examples were insufficient.",
-      "expected_output": "Agent treats the remaining EXAMPLE_MISSING diagnostic as an unfinished work item, creates or updates `.docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` with DocFX front matter for uid `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory`, adds a buildable ApplicationHostFactory example derived from source or tests, keeps `.docfx/api/namespaces/**/*.md` under `build.overwrite` only, reruns scripts/docfx.cs --json until the diagnostic is gone, and explains that namespace examples and Extension Members tables complement but do not replace examples on generated type pages.",
+      "expected_output": "Agent treats the remaining EXAMPLE_MISSING diagnostic as an unfinished work item, creates or updates `.docfx/api/types/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` with DocFX front matter for uid `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory`, adds a buildable ApplicationHostFactory example derived from source or tests, keeps both `.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite`, reruns scripts/docfx.cs --json until the diagnostic is gone, and explains that namespace examples and Extension Members tables complement but do not replace examples on generated type pages.",
       "expectations": [
         "Does not treat the namespace page examples as sufficient for the ApplicationHostFactory concrete type",
-        "Creates or updates the type-targeting overwrite file `.docfx/api/namespaces/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or an equivalent file that targets the exact ApplicationHostFactory UID",
+        "Creates or updates the type-targeting overwrite file `.docfx/api/types/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md` or an equivalent file that targets the exact ApplicationHostFactory UID",
         "Uses DocFX front matter with uid `Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory` for the type example section",
         "Adds a realistic, copy/paste-ready C# example for ApplicationHostFactory based on actual source, tests, or public behavior",
-        "Keeps `api/namespaces/**/*.md` under `build.overwrite` only and does not widen it to `api/**/*.md`",
+        "Keeps `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` and does not widen to `api/**/*.md`",
         "Reruns scripts/docfx.cs --json after the edit and treats any remaining EXAMPLE_MISSING diagnostic as blocking completion",
         "Explains that namespace overview examples and Extension Members tables are complementary surfaces, not substitutes for type-page examples"
       ]
@@ -212,13 +212,13 @@
     },
     {
       "id": 18,
-      "prompt": "Fix the DocFX overwrite setup in a Codebelt-style repository where `.docfx/docfx.json` currently uses `api/**/*.md` under both `build.content` and `build.overwrite`, and authored overwrite Markdown files like `.docfx/api/Codebelt.Extensions.Swashbuckle.AspNetCore.ConfigureSwaggerGenOptions.md` still sit directly under `.docfx/api/`. Move the authored overwrite Markdown into `.docfx/api/namespaces/`, preserve the YAML front matter and example content, keep generated `.yml` metadata in place, and verify that `docfx build --exportRawModel` still treats the API page as managed reference rather than conceptual-only.",
-      "expected_output": "Agent rewrites `docfx.json` so `api/namespaces/**/*.md` is treated as overwrite-only content, excludes `api/namespaces/**` from `build.content`, moves authored API overwrite Markdown from `.docfx/api/*.md` into `.docfx/api/namespaces/` without dropping content, preserves generated `.yml` files, reruns verification, and confirms the raw model remains a managed API page with overwrite content merged into it rather than collapsing to `{ \"type\": \"Conceptual\" }`.",
+      "prompt": "Fix the DocFX overwrite setup in a Codebelt-style repository where `.docfx/docfx.json` currently uses `api/**/*.md` under both `build.content` and `build.overwrite`, and authored overwrite Markdown files like `.docfx/api/Codebelt.Extensions.Swashbuckle.AspNetCore.ConfigureSwaggerGenOptions.md` still sit directly under `.docfx/api/`. Move the authored overwrite Markdown into the correct overwrite subdirectory based on its `uid` front matter, preserve the YAML front matter and example content, keep generated `.yml` metadata in place, and verify that `docfx build --exportRawModel` still treats the API page as managed reference rather than conceptual-only.",
+      "expected_output": "Agent rewrites `docfx.json` so both `api/namespaces/**/*.md` and `api/types/**/*.md` are treated as overwrite-only content, excludes both `api/namespaces/**` and `api/types/**` from `build.content`, moves authored type overwrite Markdown such as `ConfigureSwaggerGenOptions.md` from `.docfx/api/*.md` into `.docfx/api/types/` without dropping content, preserves generated `.yml` files, reruns verification, and confirms the raw model remains a managed API page with overwrite content merged into it rather than collapsing to `{ \"type\": \"Conceptual\" }`.",
       "expectations": [
-        "Moves authored API overwrite Markdown files from `.docfx/api/*.md` into `.docfx/api/namespaces/`",
+        "Moves authored type overwrite Markdown files from `.docfx/api/*.md` into `.docfx/api/types/` when the uid front matter targets a type",
         "Preserves YAML front matter, UID targeting, and Markdown example content while moving the files",
         "Keeps generated `.yml` metadata files in place",
-        "Ensures `api/namespaces/**/*.md` appears only under `build.overwrite` and that `build.content` excludes `api/namespaces/**`",
+        "Ensures both `api/namespaces/**/*.md` and `api/types/**/*.md` appear only under `build.overwrite` and that `build.content` excludes both `api/namespaces/**` and `api/types/**`",
         "Does not use `api/**/*.md` under `build.content` or `build.overwrite`",
         "Verifies the affected API page remains managed reference output with merged overwrite content instead of conceptual-only raw model output"
       ]
diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
index af1585f..05f182b 100644
--- a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -65,7 +65,7 @@ The `build.overwrite` entry in `docfx.json` tells DocFX which conceptual Markdow
 
 When a repository has no obvious overwrite location, inspect `docfx.json` first. Look at `build.content`, `build.overwrite`, `metadata.dest`, include paths, and existing Markdown layout before deciding where a new namespace page belongs.
 
-If a public non-abstraction type lacks an example, create a matching type-UID overwrite section in a separate per-type Markdown file by default, and make sure that file is included by `build.overwrite` so the example appears on the generated type API page. In Codebelt repositories, keep authored API overwrite files under `.docfx/api/namespaces/{TypeUid}.md`, such as `.docfx/api/namespaces/X.Y.Z.Class1.md`. File location does not decide whether the page is a namespace page or a type page; the YAML front matter `uid` does. Keep `api/namespaces/**/*.md` under `build.overwrite`, exclude `api/namespaces/**` from `build.content`, and do not use `api/**/*.md` under either section. If authored overwrite Markdown already exists directly under `.docfx/api/*.md`, move it into `.docfx/api/namespaces/` without deleting the content. Namespace overview pages and `Extension Members` tables complement examples; they do not replace type-page examples.
+If a public non-abstraction type lacks an example, create a matching type-UID overwrite section in a separate per-type Markdown file by default, and make sure that file is included by `build.overwrite` so the example appears on the generated type API page. In Codebelt repositories, keep type overwrite files under `.docfx/api/types/{TypeUid}.md`, such as `.docfx/api/types/X.Y.Z.Class1.md`, and namespace overview pages under `.docfx/api/namespaces/{Namespace}.md`. File location does not decide whether the page is a namespace page or a type page; the YAML front matter `uid` does. Keep both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite`, exclude both `api/namespaces/**` and `api/types/**` from `build.content`, and do not use `api/**/*.md` under either section. If authored overwrite Markdown already exists directly under `.docfx/api/*.md`, move it into either `api/namespaces/` (for namespace UIDs) or `api/types/` (for type UIDs) without deleting the content. Namespace overview pages and `Extension Members` tables complement examples; they do not replace type-page examples.
 
 ## Practical Rules
 
@@ -75,9 +75,13 @@ If a public non-abstraction type lacks an example, create a matching type-UID ov
 - Use namespace overview pages for namespace fly-ins and extension-member tables.
 - Keep examples and remarks close to the API item or namespace they explain.
 - Create per-type overwrite files for missing concrete-type examples even when the repository currently has only namespace overview files.
-- Keep authored API overwrite Markdown under `.docfx/api/namespaces/` and move legacy `.docfx/api/*.md` files there.
-- Keep `api/namespaces/**/*.md` under `build.overwrite` only; do not use `api/**/*.md` under `build.content` or `build.overwrite`.
+- Keep namespace overview Markdown under `.docfx/api/namespaces/` and type overwrite Markdown under `.docfx/api/types/`. Move legacy `.docfx/api/*.md` files into the appropriate subdirectory: namespace UIDs go to `api/namespaces/`, type UIDs go to `api/types/`.
+- Keep `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` only; do not use `api/**/*.md` under `build.content` or `build.overwrite`.
 - Add examples through overwrite sections when XML comments or generated metadata do not already provide developer-friendly examples.
 - Preserve existing hand-written overwrite sections unless they are stale or contradictory.
 - Prefer additive edits, but remove or revise contradictions.
 - Re-run `docfx.cs` after edits so missing namespace pages, extension tables, availability, and sample compilation are checked deterministically.
+
+## Section rendering order
+
+Overwrite files control what content is merged into the DocFX model. DocFX templates control where each property renders on the output page. Do not attempt to fix the order of sections such as "Examples before See Also" through overwrite paths, body headings, or front matter — that order is determined by the active template. If section ordering is wrong, the fix belongs in the template, not in the overwrite file.
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 634e1d8..d68ffeb 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -95,7 +95,9 @@ If you're trying to ..., start with `PrimaryType` or `PrimaryExtensions`.
 
 Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path to match the actual file location.
 
-## Type example template
+## Type example shape
+
+> **DocFX overwrite Markdown only.** This shape is for writing DocFX overwrite content. Do not create tests from it. Tests are evidence, not output — use tests to understand behavior, then transform that knowledge into consumer-facing examples.
 
 For public non-abstraction types, begin the overwrite file with front matter that maps the body to the `example` property:
 
@@ -112,9 +114,9 @@ using X.Y.Z;
 
 namespace MyNamespace;
 
-public class MyTypeExample
+public class Consumer
 {
-    public void ShowUsage()
+    public void Run()
     {
         var value = new MyType();
         Console.WriteLine(value);
@@ -142,9 +144,9 @@ using X.Y.Z;
 
 namespace MyNamespace;
 
-public class MyExtensionsExample
+public class Consumer
 {
-    public void ShowUsage()
+    public void Run()
     {
         string text = "first\r\nsecond";
         string normalized = text.NormalizeLineEndings();
diff --git a/skills/dotnet-new-lib-slnx/evals/evals.json b/skills/dotnet-new-lib-slnx/evals/evals.json
index 9d8b110..f1b8079 100644
--- a/skills/dotnet-new-lib-slnx/evals/evals.json
+++ b/skills/dotnet-new-lib-slnx/evals/evals.json
@@ -11,7 +11,7 @@
         "Resolves package-specific version placeholders from NuGet before writing Directory.Packages.props",
         "Creates DocFX config using {DOCFX_TARGET_FRAMEWORK} rather than a hardcoded net10.0",
         "Locks DocFX metadata source to ../src (relative to .docfx/) so ONLY code in the src folder is digested for API documentation, excluding tools/, scripts/, and other root folders",
-        "Keeps api/namespaces/**/*.md under build.overwrite and excludes api/**/*.md from build.content so API overwrites are not emitted as standalone conceptual pages",
+        "Keeps api/namespaces/**/*.md and api/types/**/*.md under build.overwrite and excludes api/namespaces/** and api/types/** from build.content so API overwrites are not emitted as standalone conceptual pages",
         "Uses the current working directory as the scaffold root instead of creating a nested MyLibrary folder"
       ]
     },

From d3d8d3a8c0ed970ae39778a17d30ae8f9393b80c Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Fri, 12 Jun 2026 00:02:29 +0200
Subject: [PATCH 50/88] =?UTF-8?q?=F0=9F=93=9D=20update=20docfx=20validatio?=
 =?UTF-8?q?n=20guidance?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refresh the docfx digest workflow notes and validation script to reflect the current sample-check behavior.
---
 skills/dotnet-docfx-digest/SKILL.md           |   2 +-
 skills/dotnet-docfx-digest/evals/evals.json   |  24 ++++
 .../dotnet-docfx-digest/references/scripts.md |   2 +
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 126 ++++++++----------
 4 files changed, 83 insertions(+), 71 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index ccf2b22..1c2f285 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -185,7 +185,7 @@ Resolve constructors, generic arity, abstractness, constraints, and public membe
 // dotnet-docfx-digest:skip-compile - <reason>
 ```
 
-The reason is mandatory. Package requirements, "full example needs X", or "shows the framework pattern" are rejected. Prefer making the example compile. Do not claim an example compiles unless the validator actually ran it successfully.
+The reason is mandatory. Package requirements, "full example needs X", "shows the framework pattern", or missing assembly/transitive/referenced assembly reasons are all rejected — these are authoring or validator-setup problems, not genuine blockers. Prefer making the example compile. Do not claim an example compiles unless the validator actually ran it successfully.
 
 ## Namespace and Summary Style
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 1cffea8..7eae0d8 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -596,6 +596,30 @@
         "Second run reports validation passed with zero errors",
         "Example validation is deterministic: the same csharp content produces the same validation result on repeated runs"
       ]
+    },
+    {
+      "id": 49,
+      "prompt": "Run dotnet-docfx-digest on a library where a documented public class `Acme.Console.AppHost` derives from `Codebelt.Bootstrapper.Console.ConsoleProgram` and its example calls a DI helper `services.AddHostedService<Worker>()` that requires `Microsoft.Extensions.DependencyInjection.Abstractions`. The example does not contain a `dotnet-docfx-digest:skip-compile` marker. Confirm the sample compiles without errors.",
+      "expected_output": "The validator compiles the example without SAMPLE_COMPILE_FAILED. The worker project references the documented library project via ProjectReference, so NuGet restores the full transitive closure including `Codebelt.Bootstrapper.Console` and `Microsoft.Extensions.DependencyInjection.Abstractions`. No skip marker is needed or present.",
+      "expectations": [
+        "Validator compiles the example without SAMPLE_COMPILE_FAILED",
+        "No SAMPLE_SKIP_REASON_INSUFFICIENT or SAMPLE_SKIP_REASON_MISSING is emitted",
+        "Worker project uses ProjectReference so transitive NuGet dependencies such as Microsoft.Extensions.DependencyInjection.Abstractions are available at compile time",
+        "No dotnet-docfx-digest:skip-compile marker is required to compile an example that uses types from transitive NuGet dependencies",
+        "Validator exits with status passed when the only samples are this class-based DI registration example"
+      ]
+    },
+    {
+      "id": 50,
+      "prompt": "Run dotnet-docfx-digest on a repository where one csharp documentation sample contains the comment `// dotnet-docfx-digest:skip-compile - sample worker does not include that assembly`. Confirm the validator reports SAMPLE_SKIP_REASON_INSUFFICIENT.",
+      "expected_output": "The validator detects the skip-compile marker with the reason 'sample worker does not include that assembly' and emits SAMPLE_SKIP_REASON_INSUFFICIENT. The diagnostic message explains that missing assembly references are a validator defect, not a valid blocker. The exit code is non-zero.",
+      "expectations": [
+        "Validator emits SAMPLE_SKIP_REASON_INSUFFICIENT for the fence containing 'sample worker does not include that assembly'",
+        "Diagnostic message explains that missing compile-time assembly references are not a valid skip reason",
+        "Validator returns a non-zero exit code",
+        "No SAMPLE_COMPILE_FAILED is emitted because the sample is rejected at the skip-reason gate, not attempted for compilation",
+        "Diagnostic points to the file and fence index of the offending skip marker"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 6b20e2c..0fe6dc4 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -94,6 +94,8 @@ A skip marker without a reason is reported as `SAMPLE_SKIP_REASON_MISSING`.
 
 A skip marker with a weak reason such as "full example requires X package" or "example shows the framework pattern" is reported as `SAMPLE_SKIP_REASON_INSUFFICIENT`. Package requirements and framework setup belong in the documentation around a compiling sample; they are not enough to skip compilation by themselves.
 
+Reasons involving missing compile-time references are also rejected as insufficient. These include wording such as "transitive assembly", "transitive dependency", "sample worker does not include", "missing assembly", "referenced assembly", "does not include that assembly", "public signature includes", or "base class from a transitive assembly". Ordinary NuGet package references, project references, framework references, base classes, and extension-method dependencies all resolve correctly because sample worker projects reference documented library projects via `ProjectReference` items, which gives the full compile-time dependency closure. If a sample fails to compile because a dependency type is unresolved, that is a validator defect or a sample authoring error to fix — not a valid skip reason. Fix the example, or fix the validator worker setup; do not add `dotnet-docfx-digest:skip-compile` to hide the gap.
+
 ### Example detection
 
 The validator recognizes a complete example as one of:
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 792038d..0182911 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -2542,17 +2542,10 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
             return;
         }
 
-        // 3. Resolve built assembly DLL paths so worker projects can use direct <Reference> items
-        //    instead of rebuilding the project graph for every sample.
-        var assemblyRefs = ResolveBuiltAssemblyReferences(libraryProjects, options.Configuration, options.Framework);
-        if (assemblyRefs.Count < libraryProjects.Count && libraryProjects.Count > 0)
-        {
-            report.Warnings.Add(new Diagnostic("SAMPLE_WORKER_ASSEMBLY_FALLBACK", null, null,
-                $"Built DLL paths could not be resolved for {libraryProjects.Count - assemblyRefs.Count} of {libraryProjects.Count} documented " +
-                "project(s). Sample validation workers will use ProjectReference instead of direct assembly references for those projects, which may reduce performance."));
-        }
-
-        // 4. Create reusable sample-validation worker pool and compile with bounded parallelism.
+        // 3. Create reusable sample-validation worker pool and compile with bounded parallelism.
+        //    Workers use ProjectReference for all documented library projects so the full
+        //    compile-time dependency closure (NuGet packages, transitive references, framework
+        //    assemblies exposed through public signatures) is available without manual DLL enumeration.
         var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-samples-" + Guid.NewGuid().ToString("N"));
         Directory.CreateDirectory(tempRoot);
         try
@@ -2567,7 +2560,7 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
             for (int w = 0; w < workerCount; w++)
             {
                 workers[w] = CreateSampleWorker(
-                    tempRoot, w + 1, assemblyRefs, libraryProjects,
+                    tempRoot, w + 1, libraryProjects,
                     options.Framework ?? "net10.0", options.Configuration, repoRoot, hasStrongNameKey, report);
             }
 
@@ -2644,29 +2637,12 @@ private static int GetSampleValidationParallelism(Options options)
         return defaultParallelism;
     }
 
-    private static List<(string AssemblyName, string DllPath)> ResolveBuiltAssemblyReferences(
-        List<ProjectInfo> libraryProjects, string configuration, string? framework)
-    {
-        var refs = new List<(string, string)>(libraryProjects.Count);
-        foreach (var proj in libraryProjects)
-        {
-            var dll = FindAssembly(proj, configuration, framework);
-            if (dll is not null && File.Exists(dll))
-            {
-                refs.Add((proj.AssemblyName, dll));
-            }
-        }
-
-        return refs;
-    }
-
     /// <summary>
     /// Creates a reusable sample-validation worker under <paramref name="tempRoot"/> and
     /// performs a one-time restore so all subsequent sample builds can use <c>--no-restore</c>.
     /// </summary>
     private static SampleWorkerInfo CreateSampleWorker(
         string tempRoot, int workerNumber,
-        List<(string AssemblyName, string DllPath)> assemblyRefs,
         List<ProjectInfo> libraryProjects,
         string framework, string configuration,
         string repoRoot, bool hasStrongNameKey, Report report)
@@ -2677,15 +2653,9 @@ private static SampleWorkerInfo CreateSampleWorker(
         Directory.CreateDirectory(libDir);
         Directory.CreateDirectory(appDir);
 
-        // Determine which documented projects need ProjectReference fallback (DLL not resolved).
-        var projectRefFallbacks = libraryProjects
-            .Where(p => !assemblyRefs.Any(r =>
-                string.Equals(r.AssemblyName, p.AssemblyName, StringComparison.OrdinalIgnoreCase)))
-            .ToList();
-
         // Class-library project — for class-based samples (namespace + type declaration).
         var libProjPath = Path.Combine(libDir, "DocfxSampleLib.csproj");
-        File.WriteAllText(libProjPath, GenerateSampleLibProject(assemblyRefs, projectRefFallbacks, framework),
+        File.WriteAllText(libProjPath, GenerateSampleLibProject(libraryProjects, framework),
             new UTF8Encoding(false));
         // Compilable placeholder; overwritten per sample.
         File.WriteAllText(Path.Combine(libDir, "Sample.cs"),
@@ -2694,7 +2664,7 @@ private static SampleWorkerInfo CreateSampleWorker(
 
         // Console-app project — for Program.cs / top-level-statement samples.
         var appProjPath = Path.Combine(appDir, "DocfxSampleApp.csproj");
-        File.WriteAllText(appProjPath, GenerateSampleAppProject(assemblyRefs, projectRefFallbacks, framework),
+        File.WriteAllText(appProjPath, GenerateSampleAppProject(libraryProjects, framework),
             new UTF8Encoding(false));
         // Compilable placeholder; overwritten per sample.
         File.WriteAllText(Path.Combine(appDir, "Program.cs"), "// placeholder", new UTF8Encoding(false));
@@ -2715,10 +2685,7 @@ private static SampleWorkerInfo CreateSampleWorker(
         return new SampleWorkerInfo(libDir, appDir, libProjPath, appProjPath, libRestoreOk, appRestoreOk);
     }
 
-    private static string GenerateSampleLibProject(
-        List<(string AssemblyName, string DllPath)> assemblyRefs,
-        List<ProjectInfo> projectRefFallbacks,
-        string framework)
+    private static string GenerateSampleLibProject(List<ProjectInfo> libraryProjects, string framework)
     {
         var sb = new StringBuilder();
         sb.AppendLine("""<Project Sdk="Microsoft.NET.Sdk">""");
@@ -2729,15 +2696,12 @@ private static string GenerateSampleLibProject(
         sb.AppendLine("    <LangVersion>latest</LangVersion>");
         sb.AppendLine("    <ImplicitUsings>disable</ImplicitUsings>");
         sb.AppendLine("  </PropertyGroup>");
-        AppendReferenceItems(sb, assemblyRefs, projectRefFallbacks);
+        AppendProjectReferences(sb, libraryProjects);
         sb.AppendLine("</Project>");
         return sb.ToString();
     }
 
-    private static string GenerateSampleAppProject(
-        List<(string AssemblyName, string DllPath)> assemblyRefs,
-        List<ProjectInfo> projectRefFallbacks,
-        string framework)
+    private static string GenerateSampleAppProject(List<ProjectInfo> libraryProjects, string framework)
     {
         var sb = new StringBuilder();
         sb.AppendLine("""<Project Sdk="Microsoft.NET.Sdk">""");
@@ -2748,40 +2712,25 @@ private static string GenerateSampleAppProject(
         sb.AppendLine("    <LangVersion>latest</LangVersion>");
         sb.AppendLine("    <PublishAot>false</PublishAot>");
         sb.AppendLine("  </PropertyGroup>");
-        AppendReferenceItems(sb, assemblyRefs, projectRefFallbacks);
+        AppendProjectReferences(sb, libraryProjects);
         sb.AppendLine("</Project>");
         return sb.ToString();
     }
 
-    private static void AppendReferenceItems(
-        StringBuilder sb,
-        List<(string AssemblyName, string DllPath)> assemblyRefs,
-        List<ProjectInfo> projectRefFallbacks)
+    private static void AppendProjectReferences(StringBuilder sb, List<ProjectInfo> libraryProjects)
     {
-        if (assemblyRefs.Count > 0)
+        if (libraryProjects.Count == 0)
         {
-            sb.AppendLine("  <ItemGroup>");
-            foreach (var (assemblyName, dllPath) in assemblyRefs)
-            {
-                sb.AppendLine($"    <Reference Include=\"{assemblyName}\">");
-                sb.AppendLine($"      <HintPath>{dllPath}</HintPath>");
-                sb.AppendLine("      <Private>false</Private>");
-                sb.AppendLine("    </Reference>");
-            }
-
-            sb.AppendLine("  </ItemGroup>");
+            return;
         }
 
-        if (projectRefFallbacks.Count > 0)
+        sb.AppendLine("  <ItemGroup>");
+        foreach (var proj in libraryProjects)
         {
-            sb.AppendLine("  <ItemGroup>");
-            foreach (var proj in projectRefFallbacks)
-            {
-                sb.AppendLine($"    <ProjectReference Include=\"{proj.Path}\" />");
-            }
-
-            sb.AppendLine("  </ItemGroup>");
+            sb.AppendLine($"    <ProjectReference Include=\"{proj.Path}\" />");
         }
+
+        sb.AppendLine("  </ItemGroup>");
     }
 
     private static (bool Ok, string Diagnostics, int ExitCode) CompileWithWorker(
@@ -3032,6 +2981,43 @@ private static bool IsInsufficientSkipReason(string reason)
             return true;
         }
 
+        // Missing compile-time references are validator defects, not valid skip reasons.
+        // All ordinary NuGet, project, and framework references resolve through ProjectReference items.
+        if (Regex.IsMatch(reason, @"(?i)\btransitive\s+(assembly|dependency)\b"))
+        {
+            return true;
+        }
+
+        if (Regex.IsMatch(reason, @"(?i)\bsample\s+worker\s+does\s+not\s+include\b"))
+        {
+            return true;
+        }
+
+        if (Regex.IsMatch(reason, @"(?i)\bmissing\s+assembly\b"))
+        {
+            return true;
+        }
+
+        if (Regex.IsMatch(reason, @"(?i)\breferenced\s+assembly\b"))
+        {
+            return true;
+        }
+
+        if (Regex.IsMatch(reason, @"(?i)\bdoes\s+not\s+include\s+that\s+assembly\b"))
+        {
+            return true;
+        }
+
+        if (Regex.IsMatch(reason, @"(?i)\bpublic\s+signature\s+includes\b"))
+        {
+            return true;
+        }
+
+        if (Regex.IsMatch(reason, @"(?i)\bbase\s+class\s+from\s+a\s+transitive\s+assembly\b"))
+        {
+            return true;
+        }
+
         return false;
     }
 

From 42ae0b6012a2bc714c611b149cc3200595a9e172 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Fri, 12 Jun 2026 00:44:13 +0200
Subject: [PATCH 51/88] =?UTF-8?q?=F0=9F=93=9D=20refresh=20docfx=20readme?=
 =?UTF-8?q?=20guidance?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refresh the README and docfx digest guidance so the current workflow and validation notes stay aligned.
---
 README.md                                     |  3 +-
 skills/dotnet-docfx-digest/SKILL.md           | 32 +++++----
 skills/dotnet-docfx-digest/evals/evals.json   | 16 +++++
 .../references/workflow.md                    | 70 ++++++++++++-------
 4 files changed, 80 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index 576df13..2f3c9b5 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, Codebelt namespace-folder overwrite layout (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and C# documentation samples, keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown so new samples compile before staging, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, and managed-reference-safe completion gates for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, Codebelt namespace-folder overwrite layout (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and C# documentation samples, keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown so new samples compile before staging, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -544,6 +544,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
 - **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/namespaces/`, legacy authored `.docfx/api/*.md` overwrite files are moved into that folder instead of widening the glob to `api/**/*.md`, `api/namespaces/**/*.md` stays under `build.overwrite` only while `build.content` excludes `api/namespaces/**`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
 - **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
+- **Examples that teach a real workflow** — examples start from package IDs and package-level evidence before falling back to type/member-only searches, prefer README, package docs, tooling, tuning, functional-test, and external GitHub usage when available, and may include multiple related public types when that is what makes the consumer scenario understandable,
 - **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 1c2f285..64a51fc 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -104,9 +104,13 @@ Material changes include new or removed public API, signature or nullability cha
 
 ## Examples and Overwrites
 
-Every public non-abstraction type and every public extension method needs at least one realistic, minimal, copy/paste-ready example. A namespace fly-in or `Extension Members` table alone is not enough.
-
-**Tests are evidence, not output.** Do not add `ShowUsage`, `Usage`, `Example`, or documentation-only methods to test files. Use tests to understand the documented type's behavior, then transform that knowledge into consumer-facing DocFX overwrite examples.
+Every public non-abstraction type and every public extension method needs at least one realistic, copy/paste-ready example. A namespace fly-in or `Extension Members` table alone is not enough.
+
+Prefer scenario examples over isolated constructor or method-call snippets. A strong type-page example shows the documented API inside the workflow a consumer is trying to complete, even when that means including nearby public types, a small local helper type, dependency-injection setup, configuration objects, or a short host entry point. The example should still be compact, but it should carry enough context that a developer can understand why the type exists and how it cooperates with the package.
+
+Before writing examples for a package, identify the package ID or IDs from packable project metadata, `.nuget/*/README.md`, package release notes, `Directory.Packages.props`, or `PackageReference` usage. Search local repository evidence by package ID first, then by namespace/type/member name. When internet or GitHub search is available and the user has not forbidden it, search for the exact package ID and exclude the target repository or treat self-repo hits as lower-priority evidence. Package-ID searches often find real `Program.cs`, `PackageReference`, README, and package-documentation usage that type-name searches miss.
+
+**Tests are evidence, not output.** Do not add `ShowUsage`, `Usage`, `Example`, or documentation-only methods to test files. Use tests to understand the documented type's behavior, then transform that knowledge into consumer-facing DocFX overwrite examples.
 
 Every generated `csharp` code block is a complete, copy/paste-ready compilation unit. The default is always a compilable unit (option 1). Only use intentionally incomplete excerpts (option 2) when explicitly requested by the user, and label them clearly.
 
@@ -121,7 +125,7 @@ Every generated `csharp` code block is a complete, copy/paste-ready compilation
 - Does **not** call members that do not exist on the resolved public API surface.
 - Compiles in a minimal class library verification project referencing the documented assemblies.
 
-Prefer examples derived from existing unit, functional, or integration tests as behavioral evidence, then from samples, then from a minimal new example based on actual public behavior. Convert Arrange/Act/Assert test structure into consumer-oriented sample code instead of pasting raw test assertions, mocks, or fixture setup.
+Prefer examples derived from existing unit, functional, or integration tests as behavioral evidence, then from package-level usage evidence, samples, README content, and real consumer usage, then from a minimal new example based on actual public behavior. Convert Arrange/Act/Assert test structure into consumer-oriented sample code instead of pasting raw test assertions, mocks, or fixture setup.
 
 For public non-abstraction types, put the example on the generated type page by targeting the type UID in DocFX overwrite content. In Codebelt repositories, keep authored type overwrite Markdown under `.docfx/api/types/`, typically as `.docfx/api/types/{TypeUid}.md`.
 
@@ -159,15 +163,17 @@ Class-based examples that pass Gate 1 are compiled as a class library project re
 
 Derive examples from these sources, in order:
 
-1. Public API surface and XML documentation comments — establish the supported constructor signatures, method signatures, and types.
-2. Existing unit or functional tests that reference the documented type or member — use as behavioral evidence only; do not copy Arrange/Act/Assert structure, test fixtures, mocks, or test helper patterns into the final example unless the public API is specifically about testing.
-3. README, package documentation, samples, or existing conceptual docs in the repository.
-4. Implementation source, only when the public surface alone is insufficient to construct a valid calling example.
-5. Official upstream documentation when the library wraps an external framework or library.
-6. Synthesized examples only when all of the above confirm the full public API shape and the synthesized sample compiles.
-7. Omit the example entirely if none of the above yields a compile-valid, consumer-facing example.
-
-Final examples must be consumer-facing, realistic, and compile. They must read like production calling code, not test scaffolding.
+1. Package IDs and package-family context — determine what a consumer installs and search local evidence for the exact package ID before narrowing to individual types.
+2. Public API surface and XML documentation comments — establish the supported constructor signatures, method signatures, and types.
+3. Existing unit, functional, or integration tests that reference the documented type or member — use as behavioral evidence only; do not copy Arrange/Act/Assert structure, test fixtures, mocks, or test helper patterns into the final example unless the public API is specifically about testing.
+4. README, `.nuget/*/README.md`, package documentation, samples, tuning/tooling projects, or existing conceptual docs in the repository.
+5. Real consumer usage found by exact package-ID search, preferring repositories other than the target repository when available; use self-repo hits only as package-authored documentation or sample evidence.
+6. Implementation source, only when the public surface alone is insufficient to construct a valid calling example.
+7. Official upstream documentation when the library wraps an external framework or library.
+8. Synthesized examples only when all of the above confirm the full public API shape and the synthesized sample compiles.
+9. Omit the example entirely if none of the above yields a compile-valid, consumer-facing example.
+
+Final examples must be consumer-facing, realistic, and compile. They must read like production calling code or Microsoft Learn-style task examples, not test scaffolding, placeholder `Consumer` shells, or one-line smoke tests. Avoid unused locals, `MyNamespace` when a domain-specific namespace is obvious, fake "sample" values that obscure the workflow, and examples that instantiate the documented type without showing the result or next step a real caller cares about.
 
 **Reflection and API-shape requirements:**
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 7eae0d8..661381b 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -620,6 +620,22 @@
         "No SAMPLE_COMPILE_FAILED is emitted because the sample is rejected at the skip-reason gate, not attempted for compilation",
         "Diagnostic points to the file and fence index of the offending skip marker"
       ]
+    },
+    {
+      "id": 51,
+      "prompt": "Use dotnet-docfx-digest on a BenchmarkDotNet-style library that ships NuGet packages `Codebelt.Extensions.BenchmarkDotNet` and `Codebelt.Extensions.BenchmarkDotNet.Console`. The validator reports missing type examples for `BenchmarkWorkspace`, `BenchmarkWorkspaceOptions`, `BenchmarkWorkspaceOptionsExtensions`, `ServiceCollectionExtensions`, `BenchmarkContext`, and `BenchmarkProgram`. Existing generated examples compile but are thin: they use `MyNamespace`, `Consumer`, isolated constructors, and unused locals. Improve the type-specific DocFX samples so they fit real consumer context.",
+      "expected_output": "The agent identifies the package IDs from project/package metadata, searches local evidence by `Codebelt.Extensions.BenchmarkDotNet` and `Codebelt.Extensions.BenchmarkDotNet.Console` before type-only searches, uses package README, tooling/tuning projects, functional tests, and available GitHub/package-ID usage as source evidence, and rewrites type-page examples as compact scenario examples. The examples may include multiple related public types when needed, such as `BenchmarkProgram.Run`, `BenchmarkWorkspaceOptions.Slim`, `ConfigureBenchmarkDotNet`, `BenchmarkContext`, `IBenchmarkWorkspace`, and dependency-injection registration, while remaining compile-valid. The agent avoids placeholder-only `Consumer`/`MyNamespace` shells, unused locals, raw test assertions, and isolated constructor smoke tests, updates the example inventory with source evidence and scenario, then reruns `docfx.cs --json` and `--verify-docfx-build` before claiming completion.",
+      "expectations": [
+        "Determines and searches for the exact package IDs `Codebelt.Extensions.BenchmarkDotNet` and `Codebelt.Extensions.BenchmarkDotNet.Console` before relying on type/member-only searches",
+        "Inspects package-level local evidence such as `.nuget/*/README.md`, README content, tooling runner programs, tuning projects, functional tests, or package documentation pages",
+        "Uses external GitHub/package-ID search when available and treats self-repository hits as lower-priority package-authored evidence rather than independent consumer proof",
+        "Creates scenario examples that explain a real workflow, such as configuring a benchmark runner, registering a workspace through DI, applying BenchmarkDotNet jobs, carrying command-line context, or post-processing artifacts",
+        "Allows a type-page example to include multiple related public types when that is the clearest way to show real usage",
+        "Avoids generic `MyNamespace` and `Consumer` wrappers when a domain-specific namespace or class name is obvious",
+        "Avoids unused locals and examples that only instantiate a type without showing a meaningful next step or result",
+        "Keeps every changed csharp example structurally valid and compile-verified through `docfx.cs`",
+        "Updates the example inventory with UID, required file, source evidence, chosen scenario, and final status"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index d68ffeb..3ef56ae 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -2,17 +2,31 @@
 
 Use this reference when you need the full step-by-step workflow, example inventory shape, ready-to-adapt templates, or the final completion checklist.
 
-## Example inventory shape
-
-Build a small example inventory from validator output and source evidence before writing examples. Treat it as a work queue, not as final-response prose.
-
-```markdown
-| UID | Kind | Required example location | Source evidence | Status |
-|---|---|---|---|---|
-| Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/types/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | ApplicationHostFactoryTest | Missing |
-```
-
-Do not mark an item complete until the overwrite section targets the correct UID or approved extension-method location, the file is included by `build.overwrite`, the sample compiles or has a justified skip marker, and `docfx.cs --json` no longer reports the relevant missing-example diagnostic.
+## Example inventory shape
+
+Build a small example inventory from validator output and source evidence before writing examples. Treat it as a work queue, not as final-response prose.
+
+```markdown
+| UID | Kind | Required example location | Source evidence | Scenario | Status |
+|---|---|---|---|---|---|
+| Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/types/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | Package README, ApplicationHostFactoryTest | Host a test server and create a client | Missing |
+```
+
+Do not mark an item complete until the overwrite section targets the correct UID or approved extension-method location, the file is included by `build.overwrite`, the sample compiles or has a justified skip marker, and `docfx.cs --json` no longer reports the relevant missing-example diagnostic.
+
+## Scenario example design
+
+Before writing a type or extension-method example, choose the smallest real task that explains the API in context. Start from package-level evidence, then narrow to type-level evidence:
+
+1. Determine the NuGet package ID or IDs from packable projects, `.nuget/*/README.md`, package release notes, `Directory.Packages.props`, or `PackageReference` usage.
+2. Search local evidence for the exact package ID first, including README files, package docs, samples, tooling projects, tuning projects, functional tests, and generated package documentation.
+3. When internet or GitHub search is available and allowed, search for the exact package ID and prefer consumer repositories outside the target repository. Treat self-repo hits as package-authored docs or samples, not independent usage proof.
+4. Search by namespace, type, and member name only after package-ID evidence has been inspected.
+5. Pick a scenario that connects the documented type to the package workflow. A good sample can include multiple related public types, a small local helper type, dependency-injection setup, host setup, options configuration, file/path setup, or result inspection when that is what a real caller would do.
+6. Remove test-only structure, raw assertions, mocks, fixture base classes, and unused locals. Keep meaningful setup and result inspection.
+7. Prefer domain-specific names such as `BenchmarkRunner`, `WorkspaceUsage`, or `HttpRetryExample` over `Consumer` and `MyNamespace` when the package domain is clear.
+
+A scenario example is still concise. It should show one coherent task, not a tour of every member. If a compile-valid scenario cannot be produced from evidence, omit the example with the documented omission comment rather than inventing a plausible workflow.
 
 ## Targeted workflow
 
@@ -107,19 +121,19 @@ uid: X.Y.Z.MyType
 example:
 - *content
 ---
-The following example shows how to use `MyType` in a consuming application.
-
-```csharp
-using X.Y.Z;
-
-namespace MyNamespace;
-
-public class Consumer
-{
-    public void Run()
-    {
-        var value = new MyType();
-        Console.WriteLine(value);
+The following example shows how to use `MyType` as part of a real consuming workflow.
+
+```csharp
+using X.Y.Z;
+
+namespace MyProject.Workflows;
+
+public class WidgetWorkflow
+{
+    public void Run()
+    {
+        var value = new MyType();
+        Console.WriteLine(value);
     }
 }
 ```
@@ -181,9 +195,11 @@ Before completing documentation work, verify:
 - [ ] Every namespace with public API has a namespace overview page.
 - [ ] Related namespace pages in the same public API family were inspected and updated consistently, or intentionally left unchanged with a reason.
 - [ ] Namespaces with public extension methods have an `Extension Members` section.
-- [ ] Public non-abstraction types have at least one type-page example.
-- [ ] Public extension methods have at least one explicit example, not only a table entry.
-- [ ] The example inventory maps each required public type and extension method to its example file and UID.
+- [ ] Public non-abstraction types have at least one type-page example.
+- [ ] Public extension methods have at least one explicit example, not only a table entry.
+- [ ] Package IDs and package-level usage evidence were inspected before type/member-only sample synthesis.
+- [ ] The example inventory maps each required public type and extension method to its example file, UID, source evidence, and chosen scenario.
+- [ ] Examples show a coherent consumer workflow, use related public types when helpful, and avoid placeholder-only `Consumer`/`MyNamespace` shells when a domain name is available.
 - [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`. Namespace pages are under `api/namespaces/` and type pages are under `api/types/`.
 - [ ] The Completion Repair Loop was run after edits, and remaining `EXAMPLE_MISSING` or overwrite-layout diagnostics were fixed or reported as exact blockers.
 - [ ] Examples are realistic, copy/paste-ready, and compile unless a justified skip marker is present.

From f4c1fbd7453ff9db2900ded1005cfb5d8d11a016 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Fri, 12 Jun 2026 01:20:39 +0200
Subject: [PATCH 52/88] =?UTF-8?q?=F0=9F=93=9D=20refresh=20docfx=20skill=20?=
 =?UTF-8?q?notes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refresh the docfx digest skill guidance to reflect the latest validation and workflow notes.
---
 skills/dotnet-docfx-digest/SKILL.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 64a51fc..07022b9 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -62,6 +62,20 @@ Do not use broad `git restore`, `git checkout --`, `git reset`, or whole-directo
 
 After modifications, inspect `git diff` for touched documentation paths and confirm the diff contains only intended changes.
 
+## File Encoding Safety
+
+DocFX documentation files in Codebelt repositories use UTF-8 with BOM and LF line endings. When any tool must rewrite a documentation file to add or change encoding:
+
+- **Never use `Get-Content` + `[System.Text.Encoding]::UTF8.GetBytes()` round-trips.** On Windows, `Get-Content` reads in the OEM/ANSI code page by default. Multi-byte UTF-8 sequences — including emoji such as ⬇️ in `Extension Members` tables — are misread as Latin-1 and re-encoded as mojibake. The corruption is invisible until `git diff` reveals scrambled bytes.
+- **Use byte-level operations** to prepend a BOM without re-encoding content:
+  ```powershell
+  [System.IO.File]::WriteAllBytes($path, [byte[]](0xEF,0xBB,0xBF) + [System.IO.File]::ReadAllBytes($path))
+  ```
+- **Prefer the `edit` tool** for all Markdown content edits; it preserves bytes correctly and avoids encoding round-trip issues entirely.
+- **Check `git status` before any encoding-rewriting operation.** If bytes are corrupted and the file was committed, `git checkout HEAD -- <file>` restores the committed version — but discards any uncommitted in-flight changes. Do not use that recovery if there are unsaved edits.
+
+**Line ending inconsistency**: `.docfx/*.md` files may have mixed BOM presence or CRLF/LF line endings across a repository (pre-existing, not introduced by documentation edits). The DocFX validator does not enforce line endings, but mixed state increases encoding-corruption risk. If you discover mixed line endings during an audit, normalize all `.docfx/*.md` files to BOM + LF using the byte-level approach above, not `Set-Content` or `Out-File`.
+
 ## Scope
 
 Apply this skill to:

From 00b2d04f568cb6faded535bd09ad969fc41a3813 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Fri, 12 Jun 2026 02:49:21 +0200
Subject: [PATCH 53/88] =?UTF-8?q?=F0=9F=93=9A=20add=20encoding=20and=20git?=
 =?UTF-8?q?hub=20search=20guidance=20to=20docfx-digest=20skill?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation for the new --repair-plan and --search-examples workflow, including guidance on ENCODING_CORRUPTION and EXTENSION_TABLE_ENCODING diagnostics. These notes ensure agents understand how to use encoding validation and GitHub search evidence when maintaining DocFX documentation.
---
 skills/dotnet-docfx-digest/SKILL.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 07022b9..8418f46 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -21,7 +21,16 @@ dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-ro
 dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --verify-docfx-build
 ```
 
-- After edits, run `docfx.cs --json` and treat any remaining diagnostics as the next work queue, not as final notes. For noisy audits, also write and read a deterministic `--repair-plan`.
+- After edits, run `docfx.cs --json` and treat any remaining diagnostics as the next work queue, not as final notes. For noisy audits, write and read a deterministic `--repair-plan`:
+
+```bash
+dotnet run --file docfx.cs -- --repo-root <repo-root> --json --repair-plan /tmp/docfx-repair-plan.md --search-examples
+```
+
+The repair plan includes a "GitHub Example Sources" section with pre-computed `gh search code` commands and GitHub search URLs for each documented package. Read that section before writing any new example — do not write examples from memory or invention when real source evidence is available. If `--search-examples` is provided and `gh` is authenticated, actual search results are embedded; otherwise, the search commands are ready to run.
+
+- `ENCODING_CORRUPTION` in the JSON output means a documentation file has double-encoded UTF-8 (mojibake). Restore with `git checkout HEAD -- <file>` if the committed version was correct, or use the edit tool or byte-level operations to rewrite the file safely. Never pipe content through `Get-Content` + `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes()` on documentation files that contain multi-byte characters or emoji.
+- `EXTENSION_TABLE_ENCODING` means the ⬇️ emoji (U+2B07) is missing or corrupted in an Extension Members table data row. Use the literal `⬇️` character, not HTML entities or text substitutes.
 - If either script cannot run, report the exact command, exit code, and failure output. Do not claim repository guidance or documentation was verified unless the scripts actually ran successfully.
 - Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape.
 

From 95296c333bfde46f9a6c0ee973b1478543dbf605 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Fri, 12 Jun 2026 02:49:27 +0200
Subject: [PATCH 54/88] =?UTF-8?q?=F0=9F=93=96=20update=20docfx-digest=20re?=
 =?UTF-8?q?ference=20docs=20for=20encoding=20and=20search?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update scripts.md and workflow.md to document the --search-examples flag, new diagnostic codes (ENCODING_CORRUPTION, EXTENSION_TABLE_ENCODING, ENCODING_BOM_MISSING), and the GitHub Example Sources section in repair plans. Workflow steps now include the encoding-aware repair loop and GitHub search as an evidence source for examples.
---
 .../dotnet-docfx-digest/references/scripts.md | 15 +++++--
 .../references/workflow.md                    | 39 ++++++++++---------
 2 files changed, 32 insertions(+), 22 deletions(-)

diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 0fe6dc4..ab718fa 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -53,14 +53,17 @@ dotnet run --file docfx.cs -- --repo-root . --no-validate-samples
 dotnet run --file docfx.cs -- --repo-root . --changed-only
 dotnet run --file docfx.cs -- --repo-root . --verify-docfx-build
 dotnet run --file docfx.cs -- --repo-root . --json --repair-plan /tmp/docfx-repair-plan.md
+dotnet run --file docfx.cs -- --repo-root . --json --repair-plan /tmp/docfx-repair-plan.md --search-examples
 dotnet run --file docfx.cs -- --repo-root . --configuration Debug --framework net10.0
 ```
 
-Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--framework`, `--validate-samples` / `--no-validate-samples` (default on), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
+Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--framework`, `--validate-samples` / `--no-validate-samples` (default on), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, namespace and extension-table repairs, a required-example inventory, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the plan to a temp path unless the user explicitly wants a checked-in artifact.
+`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, encoding repairs, namespace and extension-table repairs, a required-example inventory with GitHub search commands, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the plan to a temp path unless the user explicitly wants a checked-in artifact. The plan always includes a "GitHub Example Sources" section with `gh search code` commands and GitHub search URLs for each documented package, even when no `EXAMPLE_MISSING` diagnostics are present.
+
+`--search-examples` runs `gh search code` for each discovered package ID and embeds the top matching file paths in the repair plan under "GitHub Search Results". Requires the `gh` CLI to be authenticated. Combine with `--repair-plan` so results are written to a file the agent can read. If `gh` is unavailable or returns no results, the plan still includes the pre-computed search URLs and CLI commands.
 
 `--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files, namespace pages, and type pages are documentation output, not cleanup targets.
 
@@ -80,7 +83,13 @@ Exit codes:
 | 7 | Sample compilation failed |
 | 8 | Unexpected internal error |
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_METHOD_MISSING`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010). Validation warnings can also include `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `ENCODING_BOM_MISSING` when a DocFX API overwrite file is missing a UTF-8 BOM, `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+
+`ENCODING_CORRUPTION` fires when a documentation file contains the byte sequence `C3 A2 C2 AC` — the UTF-8 re-encoding of the `â¬` pair produced by a Windows-1252 round-trip of `U+2B07` (⬇, the Extension Members table arrow). Restore the affected file with `git checkout HEAD -- <file>` if the committed version was correct, or rewrite the content using the edit tool or byte-level operations. Never use `Get-Content` / `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes(Get-Content)` to rewrite documentation files that contain multi-byte characters.
+
+`EXTENSION_TABLE_ENCODING` fires when a data row in an Extension Members table is missing the `U+2B07` (⬇️) character in the Ext column, indicating that the emoji is either absent or has been corrupted. The correct literal is `⬇️`, not an HTML entity, a Unicode escape, or a look-alike character.
+
+`ENCODING_BOM_MISSING` warns when a DocFX API overwrite file under `api/` is missing a UTF-8 BOM. Add the BOM using byte-level operations to avoid re-encoding content.
 
 ### Sample opt-out
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 3ef56ae..2b25e3a 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -38,21 +38,22 @@ Use this path when the user names a changed API or namespace.
 4. Determine whether public extension methods are involved.
 5. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
 6. Locate existing overwrite files, namespace pages, availability includes, tests, and samples.
-7. Convert test usage into consumer-oriented examples when relevant.
-8. Update XML documentation comments where purpose-first summaries are needed.
-9. Update or create namespace overview pages with conceptual orientation and start-here cues.
-10. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
-11. Update `Extension Members` tables when public extension methods are involved.
-12. Update or create overwrite content, including type-page examples for public non-abstraction types and explicit examples for public extension methods.
-13. Build or refresh the example inventory.
-14. Preserve manual edits and correct stale contradictions instead of replacing whole files.
-15. Run `git diff` for touched documentation paths and confirm the diff is intentional.
-16. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-17. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-18. Run the Completion Repair Loop by rerunning `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
-19. Run `docfx.cs --verify-docfx-build` so DocFX builds in a temp copy.
-20. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
-21. Report verification results and any remaining deterministic findings.
+7. Run `docfx.cs --json --repair-plan /tmp/docfx-repair-plan.md --search-examples` and read the repair plan. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs; use those results as evidence before writing examples.
+8. Convert test usage into consumer-oriented examples when relevant.
+9. Update XML documentation comments where purpose-first summaries are needed.
+10. Update or create namespace overview pages with conceptual orientation and start-here cues.
+11. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
+12. Update `Extension Members` tables when public extension methods are involved. Use the literal `⬇️` (U+2B07 U+FE0F) in the Ext column — the validator now rejects corrupted or missing emoji with `EXTENSION_TABLE_ENCODING`.
+13. Update or create overwrite content, including type-page examples for public non-abstraction types and explicit examples for public extension methods.
+14. Build or refresh the example inventory.
+15. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+16. Run `git diff` for touched documentation paths and confirm the diff is intentional.
+17. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+18. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+19. Run the Completion Repair Loop by rerunning `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
+20. Run `docfx.cs --verify-docfx-build` so DocFX builds in a temp copy.
+21. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
+22. Report verification results and any remaining deterministic findings.
 
 ## Repo-wide audit workflow
 
@@ -63,14 +64,14 @@ Use this path when the user invokes the skill without naming a specific API or n
 3. Read repository guidance, especially root `AGENTS.md`.
 4. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
 5. Read `references/docfx-overwrite-files.md`.
-6. Run `docfx.cs --json` to collect deterministic findings when the repository is buildable.
-7. If the validator reports more than a small number of diagnostics, rerun it with `--repair-plan <temp-path>/docfx-repair-plan.md`, read that plan, and use it as the authoritative work queue.
-8. If the validator fails before producing documentation diagnostics, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
+6. Run `docfx.cs --json --repair-plan /tmp/docfx-repair-plan.md --search-examples` and read the repair plan. The plan is the authoritative work queue. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs for each documented package — run or open these searches before writing any new example.
+7. If the validator fails before producing documentation diagnostics, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
+8. Check for `ENCODING_CORRUPTION` or `EXTENSION_TABLE_ENCODING` diagnostics first; restore affected files from git before doing any further editing.
 9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
 10. Determine every public non-abstraction type and every public extension method that requires an example.
 11. Create or update missing namespace overview pages with purpose-first fly-ins and start-here guidance.
 12. Audit related namespace pages together so fixes are consistent across the public API family.
-13. Add or repair `Extension Members` tables for namespaces with public extension methods.
+13. Add or repair `Extension Members` tables for namespaces with public extension methods. Use the literal `⬇️` (U+2B07 U+FE0F) in the Ext column.
 14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
 15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, under `.docfx/api/types/{TypeUid}.md` in Codebelt repositories.
 16. Ensure `docfx.json` includes both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite`, excludes both `api/namespaces/**` and `api/types/**` from `build.content`, and moves legacy authored `.docfx/api/*.md` files into either `api/namespaces/` (namespace pages) or `api/types/` (type pages).

From 6a9ede61a0fcc9b4543a631504e81609cd47dc2c Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Fri, 12 Jun 2026 02:49:32 +0200
Subject: [PATCH 55/88] =?UTF-8?q?=F0=9F=94=A7=20implement=20encoding=20val?=
 =?UTF-8?q?idation=20and=20github=20example=20search?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add ValidateDocumentationEncoding() to detect mojibake patterns and missing UTF-8 BOMs in documentation files, with specific error codes ENCODING_CORRUPTION and ENCODING_BOM_MISSING. Add SearchGitHubForExamples() to collect real usage evidence for each discovered package ID when --search-examples is enabled. Package IDs are now collected and passed through the report so repair plans can include pre-computed gh search code commands and URLs.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 274 +++++++++++++++++++-
 1 file changed, 267 insertions(+), 7 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 0182911..06df4ad 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -157,6 +157,13 @@ private static int Validate(Options options)
 
         var libraryProjects = projects.Where(p => !p.IsTest).ToList();
 
+        // Store package IDs for use in the repair plan GitHub search section.
+        report.PackageIds.AddRange(
+            libraryProjects
+                .Select(p => p.PackageId ?? p.AssemblyName)
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .OrderBy(id => id, StringComparer.OrdinalIgnoreCase));
+
         // 5. Restore and build only the projects referenced by the active docfx.json.
         //    This avoids building the full solution when it contains unrelated projects.
         phaseTimer.Restart();
@@ -200,6 +207,9 @@ private static int Validate(Options options)
         var markdownFiles = DiscoverMarkdown(repoRoot, docfxPath, docfxWorkspace, report);
         WritePhase(options, "markdown discovery", phaseTimer.Elapsed);
 
+        // 7.5. Validate documentation file encoding (mojibake, missing BOM).
+        ValidateDocumentationEncoding(repoRoot, markdownFiles, report);
+
         // Build a filename-keyed index to replace the O(N*M) FirstOrDefault scan per namespace.
         var namespacePageIndex = markdownFiles
             .GroupBy(f => Path.GetFileNameWithoutExtension(f), StringComparer.OrdinalIgnoreCase)
@@ -250,6 +260,14 @@ private static int Validate(Options options)
             WritePhase(options, "docfx build verification", phaseTimer.Elapsed);
         }
 
+        // Optional GitHub example search to embed real usage snippets in the repair plan.
+        if (options.SearchExamples && report.PackageIds.Count > 0)
+        {
+            phaseTimer.Restart();
+            SearchGitHubForExamples(report.PackageIds, report);
+            WritePhase(options, "github example search", phaseTimer.Elapsed);
+        }
+
         // 11. Produce report and return a deterministic exit code.
         bool hasSampleError = report.Errors.Any(e => e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_STRUCTURE_INVALID");
         bool hasOtherError = report.Errors.Any(e => e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_STRUCTURE_INVALID");
@@ -1115,9 +1133,78 @@ private static bool AgentsBlockPresent(string agentsPath)
     }
 
     // ----------------------------------------------------------------------
-    // Build
+    // File encoding validation
     // ----------------------------------------------------------------------
 
+    private static void ValidateDocumentationEncoding(string repoRoot, List<string> markdownFiles, Report report)
+    {
+        foreach (var file in markdownFiles)
+        {
+            byte[] bytes;
+            try
+            {
+                bytes = File.ReadAllBytes(file);
+            }
+            catch
+            {
+                continue;
+            }
+
+            if (bytes.Length == 0)
+            {
+                continue;
+            }
+
+            var rel = Rel(repoRoot, file);
+
+            // Check for double-encoded UTF-8 sequences (mojibake).
+            // The most reliable indicator for Codebelt documentation files is C3 A2 C2 AC:
+            // the UTF-8 re-encoding of 'â' (U+00E2) followed by '¬' (U+00AC), which is what
+            // U+2B07 ⬇ (UTF-8: E2 AC 87) looks like after a Windows-1252 round-trip.
+            if (HasMojibakePattern(bytes))
+            {
+                report.Errors.Add(new Diagnostic("ENCODING_CORRUPTION", rel, null,
+                    $"File contains double-encoded UTF-8 sequences (mojibake). Multi-byte characters such as ⬇️ " +
+                    $"were likely written through a PowerShell Get-Content/Set-Content round-trip, which re-encodes " +
+                    $"UTF-8 bytes through Windows-1252. Restore: `git checkout HEAD -- {rel}` if the committed " +
+                    $"version was correct. To add or rewrite content safely, use the edit tool or byte-level operations: " +
+                    $"[System.IO.File]::WriteAllBytes($path, ...). Never use Get-Content + [System.Text.Encoding]::UTF8.GetBytes()."));
+            }
+
+            // Warn about missing UTF-8 BOM on DocFX API overwrite files.
+            var hasBom = bytes.Length >= 3 && bytes[0] == 0xEF && bytes[1] == 0xBB && bytes[2] == 0xBF;
+            if (!hasBom && IsDocfxApiOverwritePath(file))
+            {
+                report.Warnings.Add(new Diagnostic("ENCODING_BOM_MISSING", rel, null,
+                    "DocFX API overwrite file is missing a UTF-8 BOM. Codebelt DocFX files use UTF-8 with BOM. " +
+                    "Add BOM without re-encoding: [System.IO.File]::WriteAllBytes($path, [byte[]](0xEF,0xBB,0xBF) + [System.IO.File]::ReadAllBytes($path))"));
+            }
+        }
+    }
+
+    private static bool HasMojibakePattern(byte[] bytes)
+    {
+        // C3 A2 C2 AC is the UTF-8 encoding of â (U+00E2) followed by ¬ (U+00AC).
+        // This sequence is the mojibake fingerprint of U+2B07 (⬇, UTF-8: E2 AC 87) after a
+        // Windows-1252 round-trip: E2→â→C3A2, AC→¬→C2AC. Highly specific to the Extension
+        // Members table arrow emoji and unlikely to appear legitimately in .NET API documentation.
+        for (int i = 0; i + 3 < bytes.Length; i++)
+        {
+            if (bytes[i] == 0xC3 && bytes[i + 1] == 0xA2 && bytes[i + 2] == 0xC2 && bytes[i + 3] == 0xAC)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private static bool IsDocfxApiOverwritePath(string filePath)
+    {
+        return filePath.Contains(Path.DirectorySeparatorChar + "api" + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase) ||
+               filePath.Contains(Path.AltDirectorySeparatorChar + "api" + Path.AltDirectorySeparatorChar, StringComparison.OrdinalIgnoreCase);
+    }
+
     /// <summary>
     /// Restores and builds only the library projects referenced by the active docfx.json.
     /// Restore runs once against the solution (when present) or each project individually.
@@ -1358,6 +1445,7 @@ private static IEnumerable<string> ResolveCsprojGlobPatterns(
     private static ProjectInfo ReadProject(string projectPath)
     {
         string? assemblyName = null;
+        string? packageId = null;
         var tfms = new List<string>();
         bool isTest = false;
 
@@ -1370,6 +1458,13 @@ private static ProjectInfo ReadProject(string projectPath)
                 {
                     case "AssemblyName":
                         assemblyName = el.Value.Trim();
+                        break;
+                    case "PackageId":
+                        if (!string.IsNullOrWhiteSpace(el.Value))
+                        {
+                            packageId = el.Value.Trim();
+                        }
+
                         break;
                     case "TargetFramework":
                         if (!string.IsNullOrWhiteSpace(el.Value))
@@ -1424,7 +1519,7 @@ private static ProjectInfo ReadProject(string projectPath)
             isTest = true;
         }
 
-        return new ProjectInfo(projectPath, assemblyName, tfms, isTest);
+        return new ProjectInfo(projectPath, assemblyName, tfms, isTest, packageId);
     }
 
     private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string configuration, string? framework, Report report)
@@ -2237,6 +2332,39 @@ private static void ValidateExtensionSection(string rel, string body, NamespaceI
             return;
         }
 
+        // Validate that data rows use the correct ⬇️ emoji (U+2B07 U+FE0F) in the Ext column.
+        // A missing or mojibake-encoded emoji passes the table-header check but renders incorrectly.
+        bool dataRowChecked = false;
+        foreach (Match row in Regex.Matches(section, @"^\|([^|\r\n]+)\|([^|\r\n]+)\|([^|\r\n]+)\|", RegexOptions.Multiline))
+        {
+            var extCell = row.Groups[2].Value.Trim();
+            // Skip the header row and separator rows.
+            if (extCell.Equals("Ext", StringComparison.OrdinalIgnoreCase) ||
+                Regex.IsMatch(extCell, @"^[\-: ]+$"))
+            {
+                continue;
+            }
+
+            dataRowChecked = true;
+            if (!extCell.Contains('\u2B07'))
+            {
+                report.Errors.Add(new Diagnostic("EXTENSION_TABLE_ENCODING", rel, ns.Name,
+                    $"A data row in the 'Extension Members' table for namespace {ns.Name} is missing the ⬇️ (U+2B07) " +
+                    $"character in the Ext column. Either the emoji is absent or it has been corrupted through an ANSI/OEM " +
+                    $"encoding round-trip (mojibake). Use the literal ⬇️ character: |TypeName|⬇️|MethodName|. " +
+                    $"Do not use HTML entities, Unicode escapes, or text substitutes. " +
+                    $"If the file was recently written by PowerShell, check for ENCODING_CORRUPTION and restore with git checkout."));
+                break;
+            }
+        }
+
+        if (!dataRowChecked && ns.ExtensionMethods.Count > 0)
+        {
+            report.Errors.Add(new Diagnostic("EXTENSION_TABLE_MISSING", rel, ns.Name,
+                $"The 'Extension Members' table for namespace {ns.Name} has a header row but no data rows listing extension methods."));
+            return;
+        }
+
         // Every discovered extension method name must appear (backticked) in the section.
         foreach (var group in ns.ExtensionMethods.GroupBy(m => m.MethodName, StringComparer.Ordinal))
         {
@@ -3059,6 +3187,78 @@ private static bool IsInsufficientSkipReason(string reason)
         return set;
     }
 
+    // ----------------------------------------------------------------------
+    // GitHub example search
+    // ----------------------------------------------------------------------
+
+    private static void SearchGitHubForExamples(List<string> packageIds, Report report)
+    {
+        if (packageIds.Count == 0)
+        {
+            return;
+        }
+
+        report.ExampleSearchSnippets.Add("## GitHub Search Results");
+        report.ExampleSearchSnippets.Add(string.Empty);
+        report.ExampleSearchSnippets.Add("Results from `gh search code` for documented packages. Prefer usage from repositories other than the target repository.");
+        report.ExampleSearchSnippets.Add(string.Empty);
+
+        foreach (var packageId in packageIds)
+        {
+            report.ExampleSearchSnippets.Add($"### Package: `{packageId}`");
+            report.ExampleSearchSnippets.Add(string.Empty);
+
+            var result = RunProcess(
+                "gh",
+                $"search code \"{packageId}\" --language C# --limit 5 --json path,repository",
+                Directory.GetCurrentDirectory());
+
+            if (result.ExitCode != 0 || string.IsNullOrWhiteSpace(result.StdOut))
+            {
+                report.ExampleSearchSnippets.Add($"Search unavailable (gh exit {result.ExitCode}). Use the URL below.");
+                report.ExampleSearchSnippets.Add(string.Empty);
+                continue;
+            }
+
+            try
+            {
+                using var doc = JsonDocument.Parse(result.StdOut);
+                if (doc.RootElement.ValueKind != JsonValueKind.Array || doc.RootElement.GetArrayLength() == 0)
+                {
+                    report.ExampleSearchSnippets.Add("No results found.");
+                    report.ExampleSearchSnippets.Add(string.Empty);
+                    continue;
+                }
+
+                foreach (var hit in doc.RootElement.EnumerateArray())
+                {
+                    var path = hit.TryGetProperty("path", out var pathEl) ? pathEl.GetString() ?? string.Empty : string.Empty;
+                    var repoName = string.Empty;
+                    if (hit.TryGetProperty("repository", out var repoEl) && repoEl.ValueKind == JsonValueKind.Object)
+                    {
+                        repoName = repoEl.TryGetProperty("fullName", out var fn) ? fn.GetString() ?? string.Empty : string.Empty;
+                        if (string.IsNullOrEmpty(repoName))
+                        {
+                            repoName = repoEl.TryGetProperty("nameWithOwner", out var nwo) ? nwo.GetString() ?? string.Empty : string.Empty;
+                        }
+                    }
+
+                    if (!string.IsNullOrEmpty(repoName) || !string.IsNullOrEmpty(path))
+                    {
+                        report.ExampleSearchSnippets.Add($"- `{repoName}`: `{path}`");
+                    }
+                }
+
+                report.ExampleSearchSnippets.Add(string.Empty);
+            }
+            catch
+            {
+                report.ExampleSearchSnippets.Add("Unable to parse search results.");
+                report.ExampleSearchSnippets.Add(string.Empty);
+            }
+        }
+    }
+
     // ----------------------------------------------------------------------
     // YAML / markdown helpers
     // ----------------------------------------------------------------------
@@ -3309,14 +3509,18 @@ private static string BuildRepairPlan(Report report)
         sb.AppendLine();
 
         AppendDiagnostics(sb, "Repository Guidance", report.Errors.Where(e => e.Code is "AGENTS_BLOCK_MISSING"));
+        AppendDiagnostics(sb, "Encoding Repairs", report.Errors.Where(e =>
+            e.Code.StartsWith("ENCODING_", StringComparison.Ordinal)));
         AppendDiagnostics(sb, "Namespace And Extension Table Repairs", report.Errors.Where(e =>
             e.Code.StartsWith("NAMESPACE_", StringComparison.Ordinal) ||
             e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal)));
-        AppendRequiredExampleDiagnostics(sb, report.Errors.Where(e => e.Code is "EXAMPLE_MISSING"));
+        AppendRequiredExampleDiagnostics(sb, report.Errors.Where(e => e.Code is "EXAMPLE_MISSING"), report.PackageIds);
+        AppendGitHubExampleSources(sb, report.PackageIds, report.ExampleSearchSnippets);
         AppendDiagnostics(sb, "Sample Compilation Repairs", report.Errors.Where(e =>
             e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_SKIP_REASON_MISSING" or "SAMPLE_SKIP_REASON_INSUFFICIENT" or "SAMPLE_STRUCTURE_INVALID"));
         AppendDiagnostics(sb, "Other Errors", report.Errors.Where(e =>
             e.Code is not "AGENTS_BLOCK_MISSING" &&
+            !e.Code.StartsWith("ENCODING_", StringComparison.Ordinal) &&
             !e.Code.StartsWith("NAMESPACE_", StringComparison.Ordinal) &&
             !e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal) &&
             e.Code is not "EXAMPLE_MISSING" &&
@@ -3326,7 +3530,9 @@ e.Code is not "EXAMPLE_MISSING" &&
         sb.AppendLine("## Completion Checklist");
         sb.AppendLine();
         sb.AppendLine("- [ ] `agents.cs` has run successfully when `AGENTS_BLOCK_MISSING` appears.");
+        sb.AppendLine("- [ ] `ENCODING_CORRUPTION` files restored from git or rewritten using byte-level operations.");
         sb.AppendLine("- [ ] Every namespace diagnostic above has been resolved or intentionally excluded with evidence.");
+        sb.AppendLine("- [ ] GitHub example sources consulted before writing any new example (see 'GitHub Example Sources' section).");
         sb.AppendLine("- [ ] Every `EXAMPLE_MISSING` diagnostic above maps to a concrete example location.");
         sb.AppendLine("- [ ] Changed C# examples pass structural validation (namespace + type declaration, or labelled `// Program.cs`).");
         sb.AppendLine("- [ ] Changed C# examples compile as a class library project referencing the documented assemblies.");
@@ -3336,6 +3542,49 @@ e.Code is not "EXAMPLE_MISSING" &&
         return sb.ToString();
     }
 
+    private static void AppendGitHubExampleSources(StringBuilder sb, List<string> packageIds, List<string> searchSnippets)
+    {
+        sb.AppendLine("## GitHub Example Sources");
+        sb.AppendLine();
+        sb.AppendLine("Search for real consumer usage of the documented packages **before** writing examples. " +
+                      "Prefer hits from repositories other than the target repository. " +
+                      "Use package-ID searches first, then type-name or method-name searches only as fallback.");
+        sb.AppendLine();
+
+        if (packageIds.Count > 0)
+        {
+            sb.AppendLine("### Search Commands");
+            sb.AppendLine();
+            sb.AppendLine("Run with the `gh` CLI (requires authentication):");
+            sb.AppendLine();
+            sb.AppendLine("```bash");
+            foreach (var pkg in packageIds)
+            {
+                sb.AppendLine($"gh search code \"{pkg}\" --language \"C#\" --limit 10 --json path,repository,textMatches");
+            }
+
+            sb.AppendLine("```");
+            sb.AppendLine();
+            sb.AppendLine("### GitHub Search URLs");
+            sb.AppendLine();
+            foreach (var pkg in packageIds)
+            {
+                var encoded = Uri.EscapeDataString($"\"{pkg}\"");
+                sb.AppendLine($"- [{pkg}](https://github.com/search?q={encoded}+language%3AC%23&type=code)");
+            }
+
+            sb.AppendLine();
+        }
+
+        if (searchSnippets.Count > 0)
+        {
+            foreach (var line in searchSnippets)
+            {
+                sb.AppendLine(line);
+            }
+        }
+    }
+
     private static void AppendDiagnostics(StringBuilder sb, string title, IEnumerable<Diagnostic> diagnostics)
     {
         var items = diagnostics
@@ -3368,7 +3617,7 @@ private static void AppendDiagnostics(StringBuilder sb, string title, IEnumerabl
         }
     }
 
-    private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerable<Diagnostic> diagnostics)
+    private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerable<Diagnostic> diagnostics, List<string> packageIds)
     {
         var items = diagnostics
             .OrderBy(d => d.Namespace ?? string.Empty, StringComparer.Ordinal)
@@ -3387,6 +3636,9 @@ private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerab
 
         sb.AppendLine("Treat this section as the authoritative example work queue. Namespace overview pages and `Extension Members` tables are not complete until each item below maps to a concrete overwrite example and rerunning `docfx.cs --json` removes the diagnostic.");
         sb.AppendLine();
+        sb.AppendLine("**Before writing any example:** search GitHub for real consumer usage using the 'GitHub Example Sources' section below. " +
+                      "Base examples on actual evidence — do not invent API members, constructor signatures, or methods that are not verified in source or tests.");
+        sb.AppendLine();
         sb.AppendLine("| Namespace | Expected overwrite location | Diagnostic | Required action |");
         sb.AppendLine("|---|---|---|---|");
 
@@ -3396,8 +3648,8 @@ private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerab
             var path = EscapeTable(string.IsNullOrWhiteSpace(diagnostic.Path) ? "(method UID, declaring type UID, or namespace page)" : diagnostic.Path);
             var message = EscapeTable(diagnostic.Message);
             var action = diagnostic.Message.Contains("Public non-abstraction type", StringComparison.Ordinal)
-                ? "Create or update the type-targeting overwrite file under `api/types/`, keep `api/types/**/*.md` under `build.overwrite` only, add a compiling Examples section, then rerun validation."
-                : "Add a compiling Examples section on the declaring extension class or namespace page that explicitly calls the extension method, then rerun validation.";
+                ? "Search GitHub (see below), verify public API surface, create or update the type-targeting overwrite file under `api/types/`, keep `api/types/**/*.md` under `build.overwrite` only, add a compiling Examples section, then rerun validation."
+                : "Search GitHub (see below), verify public API surface, add a compiling Examples section on the declaring extension class or namespace page that explicitly calls the extension method, then rerun validation.";
             sb.AppendLine($"| {ns} | `{path}` | `EXAMPLE_MISSING` | {EscapeTable(action)} {message} |");
         }
 
@@ -3461,6 +3713,9 @@ private static bool TryParse(string[] args, out Options options, out string erro
                     if (!Next(args, ref i, out var rp)) { error = "--repair-plan requires a path."; return false; }
                     options.RepairPlanPath = rp;
                     break;
+                case "--search-examples":
+                    options.SearchExamples = true;
+                    break;
                 case "--sample-parallelism":
                     if (!Next(args, ref i, out var sp)) { error = "--sample-parallelism requires a count."; return false; }
                     if (!int.TryParse(sp, out var spv) || spv < 1) { error = "--sample-parallelism must be a positive integer."; return false; }
@@ -3542,6 +3797,8 @@ Override with env var DOCFX_DIGEST_SAMPLE_PARALLELISM.
               --changed-only           Validate only files changed according to git.
               --verify-docfx-build     Run DocFX against a temp copy of the repository so generated output stays outside the working tree.
               --repair-plan <path>     Write a deterministic Markdown repair plan from validation diagnostics.
+              --search-examples        Run GitHub code search for each documented package and embed real usage snippets in the
+                                       repair plan. Requires the gh CLI to be authenticated. Use together with --repair-plan.
               --clean-generated-metadata
                                       Remove DocFX-generated *.yml and manifest files under metadata.dest. Default: enabled.
               --no-clean-generated-metadata
@@ -3585,13 +3842,14 @@ private sealed class Options
         public bool ValidateSamples { get; set; } = true;
         public bool ChangedOnly { get; set; }
         public bool VerifyDocfxBuild { get; set; }
+        public bool SearchExamples { get; set; }
         public bool CleanGeneratedMetadata { get; set; } = true;
         public bool Json { get; set; }
         public bool Help { get; set; }
         public int? SampleParallelism { get; set; }
     }
 
-    private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest);
+    private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest, string? PackageId = null);
 
     private sealed record ExtensionMethodInfo(string MethodName, string ExtendedType, string DeclaringClass);
 
@@ -3672,4 +3930,6 @@ internal sealed class Report
     public Summary Summary { get; set; } = new();
     public List<Diagnostic> Errors { get; set; } = new();
     public List<Diagnostic> Warnings { get; set; } = new();
+    public List<string> PackageIds { get; set; } = new();
+    public List<string> ExampleSearchSnippets { get; set; } = new();
 }

From 6643965e52e620f360020112408c2a6459599d50 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sat, 13 Jun 2026 02:17:17 +0200
Subject: [PATCH 56/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20docfx=20v?=
 =?UTF-8?q?alidation=20to=20fast-by-default=20with=20layered=20opt-in=20op?=
 =?UTF-8?q?erations?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructure docfx.cs to complete fast validation (Markdown, prose, DocFX layout, namespace pages, extension tables, required examples) without invoking dotnet, msbuild, docfx, or gh, discovering public API from existing DocFX YAML or conservative source scan. Compilation and network access are now strictly opt-in: --validate-samples compiles C# samples, --build-api-model (alias --strict-api-discovery) enables reflection-backed discovery, --verify-docfx-build runs the DocFX CLI, and --search-examples runs gh code search. Update skill instructions and reference documentation to clarify the fast-by-default architecture and opt-in paths for each operation.
---
 skills/dotnet-docfx-digest/SKILL.md           |   24 +-
 .../dotnet-docfx-digest/references/scripts.md |   41 +-
 .../references/workflow.md                    |   12 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 1740 ++++++++++++++---
 4 files changed, 1528 insertions(+), 289 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 8418f46..fb54a7e 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -14,14 +14,22 @@ Create and maintain developer-friendly DocFX documentation digests for .NET publ
 
 - This skill is autonomous by default. If the user invokes it without naming a namespace, type, member, or changed API, treat the request as a repo-wide DocFX audit and repair task instead of asking what to document first.
 - Resolve bundled scripts from the loaded `dotnet-docfx-digest` skill directory first. If that install path is unavailable and the target repository contains the repo-managed source copy, fall back to `skills/dotnet-docfx-digest/scripts/*.cs`. Do not claim the scripts are unavailable until both locations have been checked.
-- Before claiming completion, run:
+- `docfx.cs` is fast by default: a plain run validates Markdown, prose, DocFX overwrite layout, namespace pages, extension tables, and required examples **without building, restoring, or running DocFX/gh**. Use it freely during iteration — it discovers the public API from existing DocFX YAML metadata or a conservative source scan, and ends with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary. Compilation and network access are opt-in.
+- Iterate quickly with the fast path, reading diagnostics as the next work queue:
+
+```bash
+dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --json
+```
+
+- Before claiming completion, run `agents.cs`, then a thorough build-backed verification that compiles samples, uses reflection-backed API discovery, and verifies the DocFX build:
 
 ```bash
 dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-root>
-dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --verify-docfx-build
+dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --build-api-model --validate-samples --verify-docfx-build
 ```
 
-- After edits, run `docfx.cs --json` and treat any remaining diagnostics as the next work queue, not as final notes. For noisy audits, write and read a deterministic `--repair-plan`:
+- `--build-api-model` makes API discovery reflection-precise (the fast source-scan path is conservative and may under-report), `--validate-samples` compiles every C# documentation sample, and `--verify-docfx-build` confirms the DocFX build succeeds. Treat `API_MODEL_SOURCE_SCANNER_LIMITED` in a fast run as a reminder to run the build-backed verification before completion, not as a failure.
+- For noisy audits, write and read a deterministic `--repair-plan` (works on the fast path; add `--search-examples` to embed real GitHub usage):
 
 ```bash
 dotnet run --file docfx.cs -- --repo-root <repo-root> --json --repair-plan /tmp/docfx-repair-plan.md --search-examples
@@ -38,11 +46,11 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 
 Do not stop at namespace pages, extension-member tables, or a first-pass documentation edit.
 
-1. Run `docfx.cs --json` after edits and read the remaining diagnostics.
-2. If diagnostics include `EXAMPLE_MISSING`, missing namespace pages, stale extension-member tables, sample compile failures, missing availability, or overwrite inclusion problems, treat them as blocking follow-up work.
+1. Run `docfx.cs --json` (fast, no-build) after edits and read the remaining diagnostics.
+2. If diagnostics include `EXAMPLE_MISSING`, missing namespace pages, stale extension-member tables, missing availability, or overwrite inclusion problems, treat them as blocking follow-up work.
 3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/types/`.
 4. For each missing extension-method example, document it on the declaring extension class page or the namespace page, and explicitly demonstrate the method call.
-5. Rerun the validator until the required diagnostics are gone, or stop and report the exact blocker, command, exit code, and remaining diagnostic codes.
+5. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too, or stop and report the exact blocker, command, exit code, and remaining diagnostic codes.
 
 Namespace pages and `Extension Members` tables complement type-page examples; they do not replace them. Both namespace pages (`api/namespaces/`) and type pages (`api/types/`) are required deliverables. Generating only one is incomplete work.
 
@@ -258,7 +266,7 @@ When the user names a changed API or namespace:
 3. Inspect the changed public API, affected namespaces, availability inputs, tests, samples, and current overwrite files.
 4. Update XML comments, namespace pages, extension-member tables, examples, and availability notes as required.
 5. Build an example inventory for required public concrete types and extension methods.
-6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run `docfx.cs --verify-docfx-build`.
+6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`).
 
 When the user does not name a specific target:
 
@@ -267,7 +275,7 @@ When the user does not name a specific target:
 3. Inspect DocFX configuration, overwrite files, tests, samples, and current documentation state.
 4. Run `docfx.cs --json`, and for multi-diagnostic output rerun with `--repair-plan` and use that plan as the work queue.
 5. Repair missing namespace pages, extension-member tables, examples, overwrite layout, summaries, and availability notes that can be derived from evidence.
-6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run `docfx.cs --verify-docfx-build`.
+6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`).
 
 Read `references/workflow.md` before creating new namespace pages, writing type or extension examples, preparing the final verification checklist, or shaping the completion response.
 
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index ab718fa..cb3d5be 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -44,28 +44,43 @@ Exit codes:
 
 ## docfx.cs
 
-Validates the deterministic documentation requirements against the compiled repository, not against text in `SKILL.md`. It builds the solution, discovers public API from compiled assemblies, prefers reference assemblies, loads metadata through `System.Reflection.MetadataLoadContext`, resolves dependencies from project assets, deps files, and installed .NET reference packs, then checks namespace overview pages, extension-member tables, availability, required per-type overwrite examples for public non-abstraction types and public extension methods, the Codebelt overwrite convention (`api/namespaces/**/*.md` for namespace pages and `api/types/**/*.md` for type pages, both under `build.overwrite` only), and compiles every C# documentation sample as a file-based app. For Codebelt strong-name signed repositories, repository and sample builds use the root `.snk` when present and automatically pass `-p:SkipSignAssembly=true` when no root `.snk` exists, so missing local signing keys do not masquerade as documentation failures.
+Validates the deterministic documentation requirements against the repository. By default it runs a **fast, no-build path**: it validates Markdown, prose, DocFX API-overwrite layout, encoding, namespace overview pages, extension-member tables, availability, and required per-type/extension-method examples **without compiling the product**. The default path never invokes `dotnet`, `msbuild`, `docfx`, or `gh`. A process guard enforces this: any attempt to launch one of those tools outside an explicitly enabled mode throws immediately, and every run ends with a `[processes] dotnet=… msbuild=… docfx=… gh=…` summary (mirrored in JSON under `summary.processes`) plus per-phase timings under `summary.phases`.
+
+The public API model the fast path validates against is discovered without building, in this preference order: (1) existing DocFX ManagedReference YAML under the configured `metadata.dest` (typically `.docfx/api/**/*.yml`); (2) a conservative source scan of the `.cs` files in the projects referenced by `docfx.json` when no YAML metadata exists. The source scanner discovers public namespaces, public non-abstraction types that require examples, classic `this`-parameter extension methods, and static extension containers; it intentionally errs toward under-reporting and emits an `API_MODEL_SOURCE_SCANNER_LIMITED` warning noting that `--build-api-model` provides reflection-backed precision. The fast path never deletes existing YAML metadata.
+
+Compilation and network access are strictly opt-in, and each option enables exactly one class of external process:
+
+- `--validate-samples` compiles the generated C# documentation samples (`dotnet`). This is the only default-supported path that compiles samples. Samples are grouped by their resolved dependency set so each group references only the documented project(s) that own the sample's namespace (and their transitive references resolved by MSBuild), never every documented library project. Each group restores once and builds each sample with `--no-restore`.
+- `--build-api-model` (alias `--strict-api-discovery`) performs reflection-backed API discovery from compiled assemblies (`dotnet`). It builds only the documented project graph through a single temporary `.slnx` graph build rather than N per-project builds, then loads metadata through `System.Reflection.MetadataLoadContext`. Use it when conservative no-build discovery is not enough.
+- `--verify-docfx-build` runs DocFX against a temp copy of the repository (`docfx`).
+- `--search-examples` runs GitHub code search per documented package (`gh`).
+
+For Codebelt strong-name signed repositories, build and sample paths use the root `.snk` when present and automatically pass `-p:SkipSignAssembly=true` when no root `.snk` exists, so missing local signing keys do not masquerade as documentation failures.
 
 ```bash
-dotnet run --file docfx.cs -- --repo-root .
+dotnet run --file docfx.cs -- --repo-root .                                  # fast, no-build (default)
 dotnet run --file docfx.cs -- --repo-root . --json
-dotnet run --file docfx.cs -- --repo-root . --no-validate-samples
+dotnet run --file docfx.cs -- --repo-root . --validate-samples              # compile C# samples (dotnet)
+dotnet run --file docfx.cs -- --repo-root . --build-api-model               # reflection-backed API discovery (dotnet)
 dotnet run --file docfx.cs -- --repo-root . --changed-only
-dotnet run --file docfx.cs -- --repo-root . --verify-docfx-build
+dotnet run --file docfx.cs -- --repo-root . --verify-docfx-build            # DocFX build verification (docfx)
 dotnet run --file docfx.cs -- --repo-root . --json --repair-plan /tmp/docfx-repair-plan.md
 dotnet run --file docfx.cs -- --repo-root . --json --repair-plan /tmp/docfx-repair-plan.md --search-examples
-dotnet run --file docfx.cs -- --repo-root . --configuration Debug --framework net10.0
+dotnet run --file docfx.cs -- --repo-root . --validate-samples --sample-reference-mode package
+dotnet run --file docfx.cs -- --repo-root . --build-api-model --configuration Debug --framework net10.0
 ```
 
-Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`), `--framework`, `--validate-samples` / `--no-validate-samples` (default on), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default on), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
+Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only used by build/sample paths), `--framework`, `--validate-samples` / `--no-validate-samples` (default off — opt-in), `--sample-reference-mode <project|package>` (default `project`), `--sample-parallelism <n>` (1-8, default 2; env `DOCFX_DIGEST_SAMPLE_PARALLELISM`), `--build-api-model` / `--strict-api-discovery` (default off — opt-in), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default off — opt-in), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
-`--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
+`--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It still does not build by default: Markdown/overwrite-only changes are validated against the no-build API model, and it uses `git` (read-only) to discover changes. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled (under `--validate-samples`) before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
 `--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, encoding repairs, namespace and extension-table repairs, a required-example inventory with GitHub search commands, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the plan to a temp path unless the user explicitly wants a checked-in artifact. The plan always includes a "GitHub Example Sources" section with `gh search code` commands and GitHub search URLs for each documented package, even when no `EXAMPLE_MISSING` diagnostics are present.
 
 `--search-examples` runs `gh search code` for each discovered package ID and embeds the top matching file paths in the repair plan under "GitHub Search Results". Requires the `gh` CLI to be authenticated. Combine with `--repair-plan` so results are written to a file the agent can read. If `gh` is unavailable or returns no results, the plan still includes the pre-computed search URLs and CLI commands.
 
-`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces. The default generated-output cleanup remains as a fallback for direct in-repo DocFX runs: it derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files, namespace pages, and type pages are documentation output, not cleanup targets.
+`--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces.
+
+`--clean-generated-metadata` is opt-in and disabled by default, so the fast path never deletes existing DocFX YAML metadata it may have read for API discovery. When enabled, cleanup runs only after the API model has been built and all validation has completed, so it never removes metadata the current run depended on and never deletes-then-rebuilds. It derives `metadata[].dest` and `build.dest` from `docfx.json`, removes generated `*.yml`, `.manifest`, and `*.manifest` files under metadata destinations, and removes the configured build output directory only when it is safely inside the repository and does not contain authored Markdown, source, project, solution, or DocFX configuration files. Authored `.md` overwrite files, namespace pages, and type pages are documentation output, not cleanup targets.
 
 Process execution drains stdout and stderr concurrently so verbose `dotnet build` or DocFX runs cannot deadlock on a full pipe while the validator waits for exit.
 
@@ -78,12 +93,14 @@ Exit codes:
 | 2 | Invalid arguments |
 | 3 | Repository root does not exist |
 | 4 | DocFX configuration file not found |
-| 5 | Build failed |
-| 6 | Public API discovery failed |
-| 7 | Sample compilation failed |
+| 5 | Build failed (only reachable with `--build-api-model`) |
+| 6 | Public API discovery failed (only reachable with `--build-api-model`) |
+| 7 | Sample compilation failed (only reachable with `--validate-samples`) |
 | 8 | Unexpected internal error |
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `ENCODING_BOM_MISSING` when a DocFX API overwrite file is missing a UTF-8 BOM, `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+Every run records a process tally and per-phase timings. Non-JSON output prints a `[processes] dotnet=… msbuild=… docfx=… gh=…` line and `[phase] <name>: <seconds>s` lines; JSON output exposes the same data under `summary.processes` (an object with `dotnet`, `msbuild`, `docfx`, `gh`, `git` counts) and `summary.phases` (an ordered list of `{ name, seconds, detail }`). `summary.validationMode` is `fast-markdown` or `build-backed-api-model`, and `summary.apiModelSource` is `docfx-yaml`, `source-scan`, or `build-backed`. For a default fast run on any repository, the process counts for `dotnet`, `msbuild`, `docfx`, and `gh` are all `0`.
+
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `SAMPLE_WORKER_RESTORE_FAILED` when a sample group's one-time restore fails, `ENCODING_BOM_MISSING` when a DocFX API overwrite file is missing a UTF-8 BOM, `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
 
 `ENCODING_CORRUPTION` fires when a documentation file contains the byte sequence `C3 A2 C2 AC` — the UTF-8 re-encoding of the `â¬` pair produced by a Windows-1252 round-trip of `U+2B07` (⬇, the Extension Members table arrow). Restore the affected file with `git checkout HEAD -- <file>` if the committed version was correct, or rewrite the content using the edit tool or byte-level operations. Never use `Get-Content` / `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes(Get-Content)` to rewrite documentation files that contain multi-byte characters.
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 2b25e3a..d95e335 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -12,7 +12,7 @@ Build a small example inventory from validator output and source evidence before
 | Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/types/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | Package README, ApplicationHostFactoryTest | Host a test server and create a client | Missing |
 ```
 
-Do not mark an item complete until the overwrite section targets the correct UID or approved extension-method location, the file is included by `build.overwrite`, the sample compiles or has a justified skip marker, and `docfx.cs --json` no longer reports the relevant missing-example diagnostic.
+Do not mark an item complete until the overwrite section targets the correct UID or approved extension-method location, the file is included by `build.overwrite`, the sample compiles under `docfx.cs --validate-samples` (or has a justified skip marker), and `docfx.cs --json` no longer reports the relevant missing-example diagnostic.
 
 ## Scenario example design
 
@@ -50,8 +50,8 @@ Use this path when the user names a changed API or namespace.
 16. Run `git diff` for touched documentation paths and confirm the diff is intentional.
 17. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 18. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-19. Run the Completion Repair Loop by rerunning `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
-20. Run `docfx.cs --verify-docfx-build` so DocFX builds in a temp copy.
+19. Run the Completion Repair Loop by rerunning the fast `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
+20. Run the build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` so samples compile, API discovery is reflection-precise, and DocFX builds in a temp copy.
 21. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
 22. Report verification results and any remaining deterministic findings.
 
@@ -81,8 +81,8 @@ Use this path when the user invokes the skill without naming a specific API or n
 20. Run `git diff` for touched documentation paths and confirm the diff is intentional.
 21. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 22. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-23. Run the Completion Repair Loop by rerunning `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
-24. Run `docfx.cs --verify-docfx-build` so DocFX builds in a temp copy.
+23. Run the Completion Repair Loop by rerunning the fast `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
+24. Run the build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` so samples compile, API discovery is reflection-precise, and DocFX builds in a temp copy.
 25. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
 26. Report verification results and any remaining deterministic findings.
 
@@ -214,7 +214,7 @@ Before completing documentation work, verify:
 - [ ] `git diff` for touched documentation paths was inspected before final verification.
 - [ ] `dotnet build` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
 - [ ] `dotnet test` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
-- [ ] `docfx.cs --verify-docfx-build` ran successfully, or the failure is reported.
+- [ ] The build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` ran successfully (samples compiled, reflection-backed API discovery clean, DocFX built), or the failure is reported.
 - [ ] Generated metadata files and build output directories did not remain in the working tree after verification, and authored Markdown or documentation assets were not deleted as cleanup.
 - [ ] No broad restore or checkout command discarded authored documentation changes.
 
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 06df4ad..23236f3 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -10,6 +10,7 @@
 using System.Text.Json;
 using System.Text.Json.Serialization;
 using System.Text.RegularExpressions;
+using System.Threading;
 using System.Threading.Tasks;
 using System.Xml.Linq;
 
@@ -28,6 +29,14 @@ internal static class DocfxValidator
     private static readonly TimeSpan ProcessTimeout = TimeSpan.FromMinutes(10);
     private static readonly TimeSpan ProcessStreamDrainTimeout = TimeSpan.FromSeconds(5);
 
+    // Process guard state. The fast (default) path forbids dotnet/msbuild/docfx/gh entirely;
+    // each external process is tagged with the permission that authorizes it, and the set of
+    // allowed permissions is configured from the parsed options before any process runs.
+    private static readonly object ProcessGuardLock = new();
+    private static readonly Dictionary<string, int> ProcessCounts =
+        new(StringComparer.OrdinalIgnoreCase) { ["dotnet"] = 0, ["msbuild"] = 0, ["docfx"] = 0, ["gh"] = 0, ["git"] = 0 };
+    private static HashSet<ProcessPermission> _allowedPermissions = new() { ProcessPermission.Git };
+
     private static readonly JsonSerializerOptions JsonOptions = new()
     {
         WriteIndented = true,
@@ -90,6 +99,15 @@ private static int Validate(Options options)
         var report = new Report { Script = ScriptId };
         var phaseTimer = new Stopwatch();
 
+        var mode = options.BuildApiModel ? ValidationMode.BuildBackedApiModel : ValidationMode.FastMarkdown;
+        report.Summary.ValidationMode = mode == ValidationMode.BuildBackedApiModel
+            ? "build-backed-api-model"
+            : "fast-markdown";
+
+        // Configure the process guard from options BEFORE anything can shell out. In the default
+        // fast path this leaves dotnet/msbuild/docfx/gh entirely disallowed.
+        ConfigureProcessGuard(options);
+
         // 1. Resolve repository root.
         string repoRoot;
         try
@@ -118,8 +136,11 @@ private static int Validate(Options options)
 
         report.DocfxPath = docfxPath;
         var docfxWorkspace = Path.GetDirectoryName(docfxPath)!;
+        phaseTimer.Restart();
         options.Framework ??= ResolveDefaultFramework(docfxPath, report);
-        CleanupGeneratedMetadata(repoRoot, docfxPath, docfxWorkspace, options, report);
+        WritePhase(options, report, "docfx config", phaseTimer.Elapsed);
+
+        // No-build layout validation: confirm the overwrite directory split without compiling.
         ValidateApiOverwriteLayout(repoRoot, docfxPath, docfxWorkspace, report);
 
         // 3. Verify AGENTS.md contains the managed block.
@@ -130,7 +151,7 @@ private static int Validate(Options options)
                 "AGENTS.md does not contain the dotnet-docfx-digest managed block. Run scripts/agents.cs first."));
         }
 
-        // Optional changed-only scoping.
+        // Optional changed-only scoping (git only — read-only, allowed on the fast path).
         HashSet<string>? changedFiles = null;
         if (options.ChangedOnly)
         {
@@ -145,11 +166,10 @@ private static int Validate(Options options)
         // Cache: compute once for the full validation run so callers do not repeatedly scan the repo root.
         var hasStrongNameKey = HasRootStrongNameKey(repoRoot);
 
-        // 4. Discover DocFX metadata projects BEFORE building so the build is scoped to only
-        //    the projects included in the documentation boundary.
+        // 4. Discover DocFX metadata projects from the active docfx.json (no build required).
         phaseTimer.Restart();
         var projects = DiscoverProjects(docfxPath, docfxWorkspace, report);
-        WritePhase(options, "project discovery", phaseTimer.Elapsed);
+        WritePhase(options, report, "project discovery", phaseTimer.Elapsed);
         if (projects.Count == 0)
         {
             return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Project discovery failed.");
@@ -164,61 +184,97 @@ private static int Validate(Options options)
                 .Distinct(StringComparer.OrdinalIgnoreCase)
                 .OrderBy(id => id, StringComparer.OrdinalIgnoreCase));
 
-        // 5. Restore and build only the projects referenced by the active docfx.json.
-        //    This avoids building the full solution when it contains unrelated projects.
+        // Discover and cache DocFX Markdown inputs + overwrite sections once.
         phaseTimer.Restart();
-        var (buildOk, buildOutput) = BuildDocfxProjects(libraryProjects, repoRoot, options.Configuration, hasStrongNameKey);
-        WritePhase(options, "repository build", phaseTimer.Elapsed);
-        if (!buildOk)
+        var markdownFiles = DiscoverMarkdown(repoRoot, docfxPath, docfxWorkspace, report);
+        var workspace = new ValidationWorkspace
+        {
+            RepoRoot = repoRoot,
+            DocfxPath = docfxPath,
+            DocfxWorkspace = docfxWorkspace,
+            Projects = projects,
+            LibraryProjects = libraryProjects,
+            MarkdownFiles = markdownFiles,
+            MarkdownTextByPath = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase),
+            OverwriteSections = new List<OverwriteSection>()
+        };
+        foreach (var md in markdownFiles)
         {
-            report.Errors.Add(new Diagnostic("BUILD_FAILED", null, null,
-                $"dotnet build failed (configuration {options.Configuration}).\n{Trim(buildOutput)}"));
-            return Emit(options, report, ExitCode.BuildFailed, "Build failed.");
+            var text = workspace.ReadMarkdown(md);
+            workspace.OverwriteSections.AddRange(ExtractOverwriteSections(md, text));
         }
 
-        // 6. Discover public API, namespaces and extension methods from compiled metadata.
+        WritePhase(options, report, "markdown discovery", phaseTimer.Elapsed,
+            $"{markdownFiles.Count} file(s)");
+
+        // 5. Build the API model. The default fast path never builds: it reads existing DocFX
+        //    YAML metadata when present, otherwise falls back to a conservative source scan.
+        //    --build-api-model opts into reflection-backed discovery from compiled assemblies.
         phaseTimer.Restart();
         ApiModel api;
-        try
+        if (mode == ValidationMode.BuildBackedApiModel)
         {
-            api = DiscoverApi(libraryProjects, options.Configuration, options.Framework, report);
+            var (buildOk, buildOutput) = BuildDocfxProjects(libraryProjects, repoRoot, options.Configuration, hasStrongNameKey);
+            if (!buildOk)
+            {
+                report.Errors.Add(new Diagnostic("BUILD_FAILED", null, null,
+                    $"dotnet build failed (configuration {options.Configuration}).\n{Trim(buildOutput)}"));
+                return Emit(options, report, ExitCode.BuildFailed, "Build failed.");
+            }
+
+            try
+            {
+                api = DiscoverApi(libraryProjects, options.Configuration, options.Framework, report);
+            }
+            catch (Exception ex)
+            {
+                report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
+                    $"Public API discovery failed: {ex.Message}"));
+                return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
+            }
+
+            report.Summary.ApiModelSource = "build-backed";
+            WritePhase(options, report, "api model", phaseTimer.Elapsed, "build-backed");
+
+            if (api.Namespaces.Count == 0)
+            {
+                report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
+                    "No public API could be discovered from the compiled library assemblies. Ensure the repository builds and exposes public types."));
+                return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
+            }
         }
-        catch (Exception ex)
+        else
         {
-            report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
-                $"Public API discovery failed: {ex.Message}"));
-            return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
-        }
+            api = BuildNoBuildApiModel(workspace, report, out var apiSource);
+            report.Summary.ApiModelSource = apiSource == ApiModelSource.DocfxYaml ? "docfx-yaml" : "source-scan";
+            WritePhase(options, report, "api model", phaseTimer.Elapsed, report.Summary.ApiModelSource);
 
-        WritePhase(options, "api discovery", phaseTimer.Elapsed);
-        if (api.Namespaces.Count == 0)
-        {
-            report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
-                "No public API could be discovered from the compiled library assemblies. Ensure the repository builds and exposes public types."));
-            return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
+            if (api.Namespaces.Count == 0)
+            {
+                // Conservative: do not fail the whole run just because no-build discovery found
+                // nothing. Markdown/overwrite/encoding/layout checks above still apply.
+                report.Warnings.Add(new Diagnostic("API_MODEL_EMPTY", null, null,
+                    "No public API was discovered without building. Markdown, encoding, and overwrite-layout checks still ran. Use --build-api-model for reflection-backed namespace and required-example validation."));
+            }
         }
 
         report.Summary.PublicNamespaces = api.Namespaces.Count;
         report.Summary.RequiredExampleTargets = api.RequiredExampleTargets.Count;
         report.Summary.ExtensionMethods = api.Namespaces.Sum(n => n.ExtensionMethods.Count);
 
-        // 7. Discover DocFX Markdown files from the DocFX build inputs.
+        // 6. Validate documentation file encoding (mojibake, missing BOM).
         phaseTimer.Restart();
-        var markdownFiles = DiscoverMarkdown(repoRoot, docfxPath, docfxWorkspace, report);
-        WritePhase(options, "markdown discovery", phaseTimer.Elapsed);
-
-        // 7.5. Validate documentation file encoding (mojibake, missing BOM).
         ValidateDocumentationEncoding(repoRoot, markdownFiles, report);
+        WritePhase(options, report, "encoding validation", phaseTimer.Elapsed);
 
         // Build a filename-keyed index to replace the O(N*M) FirstOrDefault scan per namespace.
         var namespacePageIndex = markdownFiles
             .GroupBy(f => Path.GetFileNameWithoutExtension(f), StringComparer.OrdinalIgnoreCase)
             .ToDictionary(g => g.Key, g => g.First(), StringComparer.OrdinalIgnoreCase);
 
-        // Pre-extract all overwrite sections once — reused by both namespace and required-example validation.
-        var allOverwriteSections = markdownFiles.SelectMany(ExtractOverwriteSections).ToList();
+        var allOverwriteSections = workspace.OverwriteSections;
 
-        // 8. Validate namespace overview pages, extension tables and availability.
+        // 7. Validate namespace overview pages, extension tables and availability.
         phaseTimer.Restart();
         foreach (var ns in api.Namespaces.OrderBy(n => n.Name, StringComparer.Ordinal))
         {
@@ -235,21 +291,25 @@ private static int Validate(Options options)
                 continue;
             }
 
-            ValidateNamespacePage(repoRoot, page, ns, report);
+            ValidateNamespacePage(repoRoot, page, workspace.ReadMarkdown(page), ns, report);
             report.Summary.NamespacePagesValidated++;
         }
 
-        WritePhase(options, "namespace validation", phaseTimer.Elapsed);
+        WritePhase(options, report, "namespace validation", phaseTimer.Elapsed);
 
-        // 9. Verify mandatory examples exist before compiling the examples that were found.
+        // 8. Verify mandatory examples exist before compiling the examples that were found.
         phaseTimer.Restart();
         ValidateRequiredExamples(repoRoot, docfxWorkspace, allOverwriteSections, api, options, changedFiles, report);
-        WritePhase(options, "required example validation", phaseTimer.Elapsed);
+        WritePhase(options, report, "required example validation", phaseTimer.Elapsed);
 
-        // 10. Extract and compile C# documentation samples with bounded parallelism.
+        // 9. Extract and compile C# documentation samples (opt-in: the only path that compiles).
         if (options.ValidateSamples)
         {
-            ValidateSamples(repoRoot, markdownFiles, libraryProjects, options, changedFiles, hasStrongNameKey, report);
+            ValidateSamples(workspace, options, changedFiles, hasStrongNameKey, report);
+        }
+        else
+        {
+            WriteSkippedPhase(options, report, "sample validation", "pass --validate-samples to compile");
         }
 
         // Optional DocFX build verification happens in a temp copy so generated output never lands in the working tree.
@@ -257,7 +317,7 @@ private static int Validate(Options options)
         {
             phaseTimer.Restart();
             VerifyDocfxBuild(repoRoot, docfxPath, hasStrongNameKey, report);
-            WritePhase(options, "docfx build verification", phaseTimer.Elapsed);
+            WritePhase(options, report, "docfx build verification", phaseTimer.Elapsed);
         }
 
         // Optional GitHub example search to embed real usage snippets in the repair plan.
@@ -265,7 +325,16 @@ private static int Validate(Options options)
         {
             phaseTimer.Restart();
             SearchGitHubForExamples(report.PackageIds, report);
-            WritePhase(options, "github example search", phaseTimer.Elapsed);
+            WritePhase(options, report, "github example search", phaseTimer.Elapsed);
+        }
+
+        // 10. Optional generated-metadata cleanup. Opt-in only, and only after the API model has
+        //     been built so we never delete YAML the fast path may have relied on.
+        if (options.CleanGeneratedMetadata)
+        {
+            phaseTimer.Restart();
+            CleanupGeneratedMetadata(repoRoot, docfxPath, docfxWorkspace, options, report);
+            WritePhase(options, report, "generated metadata cleanup", phaseTimer.Elapsed);
         }
 
         // 11. Produce report and return a deterministic exit code.
@@ -1042,7 +1111,8 @@ private static void VerifyDocfxBuild(string repoRoot, string docfxPath, bool has
             var environment = hasStrongNameKey
                 ? null
                 : new Dictionary<string, string> { ["SkipSignAssembly"] = "true" };
-            var result = RunProcess(docfxExecutable, $"\"{tempDocfxPath}\"", tempRoot, environment);
+            var result = RunProcess(docfxExecutable, $"\"{tempDocfxPath}\"", tempRoot, environment,
+                ProcessPermission.DocfxBuild);
             if (result.ExitCode != 0)
             {
                 report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
@@ -1207,8 +1277,10 @@ private static bool IsDocfxApiOverwritePath(string filePath)
 
     /// <summary>
     /// Restores and builds only the library projects referenced by the active docfx.json.
-    /// Restore runs once against the solution (when present) or each project individually.
-    /// Build runs per-project with <c>--no-restore</c> to avoid redundant NuGet evaluation.
+    /// A single temporary <c>.slnx</c> graph build is preferred so the whole documented
+    /// dependency graph is restored and compiled in one pass instead of N per-project builds,
+    /// and the unrelated remainder of a large product solution is never built. Only reached
+    /// when the caller passes <c>--build-api-model</c>.
     /// </summary>
     private static (bool Ok, string Output) BuildDocfxProjects(
         List<ProjectInfo> libraryProjects, string repoRoot, string configuration, bool hasStrongNameKey)
@@ -1220,49 +1292,50 @@ private static (bool Ok, string Output) BuildDocfxProjects(
 
         var signingProperty = hasStrongNameKey ? string.Empty : " -p:SkipSignAssembly=true";
 
-        // Prefer restoring the whole solution so the dependency graph for all documented
-        // projects is resolved in one pass; fall back to per-project restores when no
-        // solution exists.
-        var solutionFile = Directory.GetFiles(repoRoot, "*.slnx")
-            .Concat(Directory.GetFiles(repoRoot, "*.sln"))
-            .FirstOrDefault();
-
-        if (solutionFile is not null)
+        // Build the documented projects through a temporary .slnx so MSBuild restores and
+        // compiles the documented dependency graph in a single pass. This keeps the build
+        // scoped to docfx.json inputs and avoids building the entire product solution.
+        var tempSolution = Path.Combine(Path.GetTempPath(), "docfx-digest-build-" + Guid.NewGuid().ToString("N") + ".slnx");
+        try
         {
-            var restoreResult = RunProcess("dotnet",
-                $"restore \"{solutionFile}\" --nologo{signingProperty}", repoRoot);
-            if (restoreResult.ExitCode != 0)
+            var sln = new StringBuilder();
+            sln.AppendLine("<Solution>");
+            foreach (var proj in libraryProjects)
             {
-                return (false, restoreResult.StdOut + restoreResult.StdErr);
+                sln.AppendLine($"  <Project Path=\"{proj.Path}\" />");
             }
+
+            sln.AppendLine("</Solution>");
+            File.WriteAllText(tempSolution, sln.ToString(), new UTF8Encoding(false));
+
+            var result = RunProcess("dotnet",
+                $"build \"{tempSolution}\" -c {configuration} --nologo{signingProperty}", repoRoot,
+                permission: ProcessPermission.BuildApiModel);
+            if (result.ExitCode != 0)
+            {
+                return (false, result.StdOut + result.StdErr);
+            }
+
+            return (true, result.StdOut + result.StdErr);
         }
-        else
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
         {
-            foreach (var proj in libraryProjects)
+            return (false, $"Unable to prepare a scoped build solution: {ex.Message}");
+        }
+        finally
+        {
+            try
             {
-                var restoreResult = RunProcess("dotnet",
-                    $"restore \"{proj.Path}\" --nologo{signingProperty}", repoRoot);
-                if (restoreResult.ExitCode != 0)
+                if (File.Exists(tempSolution))
                 {
-                    return (false, restoreResult.StdOut + restoreResult.StdErr);
+                    File.Delete(tempSolution);
                 }
             }
-        }
-
-        // Build each documented project individually with --no-restore.
-        var buildOutput = new StringBuilder();
-        foreach (var proj in libraryProjects)
-        {
-            var result = RunProcess("dotnet",
-                $"build \"{proj.Path}\" -c {configuration} --no-restore --nologo{signingProperty}", repoRoot);
-            buildOutput.Append(result.StdOut).Append(result.StdErr);
-            if (result.ExitCode != 0)
+            catch
             {
-                return (false, buildOutput.ToString());
+                // best effort
             }
         }
-
-        return (true, buildOutput.ToString());
     }
 
     private static bool HasRootStrongNameKey(string repoRoot)
@@ -1611,38 +1684,847 @@ private static ApiModel DiscoverApi(List<ProjectInfo> libraryProjects, string co
                     continue;
                 }
 
-                if (!namespaces.TryGetValue(nsName, out var info))
+                if (!namespaces.TryGetValue(nsName, out var info))
+                {
+                    info = new NamespaceInfo(nsName);
+                    namespaces[nsName] = info;
+                }
+
+                // Track synthetic C# 14 extension-block containers so we can warn about DocFX #11010.
+                if (IsSyntheticExtensionBlockContainer(type))
+                {
+                    info.HasCSharp14ExtensionBlocks = true;
+                }
+
+                CollectApiTargets(type, info);
+                CollectExtensionMethods(type, info);
+            }
+        }
+
+        // Emit a warning for namespaces that contain C# 14 extension blocks: DocFX issue #11010
+        // means those blocks do not yet generate correct API metadata. Extension methods declared
+        // with the classic `this` pattern are unaffected and remain supported.
+        foreach (var ns in namespaces.Values.Where(n => n.HasCSharp14ExtensionBlocks))
+        {
+            report.Warnings.Add(new Diagnostic("DOCFX_EXTENSION_BLOCK_UNSUPPORTED", null, ns.Name,
+                $"Namespace {ns.Name} contains C# 14 extension-block types. DocFX (issue #11010) does not currently generate correct API metadata for extension blocks, so generated UIDs for those members may be missing or synthetic. Classic static extension methods with 'this' parameters remain fully supported. Do not exclude these APIs or invent special rules; continue generating docs for all discoverable public APIs and document the limitation in the overwrite file when needed."));
+        }
+
+        var requiredExampleTargets = namespaces.Values
+            .SelectMany(ns => ns.RequiredExampleTargets)
+            .OrderBy(t => t.Uid, StringComparer.Ordinal)
+            .ToList();
+
+        return new ApiModel(namespaces.Values.ToList(), requiredExampleTargets);
+    }
+
+    // ----------------------------------------------------------------------
+    // No-build API model (YAML metadata + source scanner)
+    // ----------------------------------------------------------------------
+
+    private static readonly string[] YamlTypeKinds = ["Class", "Struct", "Interface", "Enum", "Delegate"];
+
+    /// <summary>
+    /// Builds the API model without compiling. Prefers existing DocFX ManagedReference YAML under
+    /// the configured metadata destinations; falls back to a conservative source scan of the
+    /// projects referenced by <c>docfx.json</c>. Never builds, restores, or deletes YAML.
+    /// </summary>
+    private static ApiModel BuildNoBuildApiModel(ValidationWorkspace ws, Report report, out ApiModelSource source)
+    {
+        var yaml = DiscoverApiFromYaml(ws, report);
+        if (yaml is not null && yaml.Namespaces.Count > 0)
+        {
+            source = ApiModelSource.DocfxYaml;
+            return yaml;
+        }
+
+        source = ApiModelSource.SourceScan;
+        report.Warnings.Add(new Diagnostic("API_MODEL_SOURCE_SCANNER_LIMITED", null, null,
+            "Fast source-based API discovery is conservative and may miss generic, nested, or conditionally compiled members. Run with --build-api-model for reflection-backed validation."));
+        return DiscoverApiFromSource(ws, report);
+    }
+
+    private static ApiModel? DiscoverApiFromYaml(ValidationWorkspace ws, Report report)
+    {
+        var yamlFiles = new List<string>();
+        foreach (var dest in ResolveMetadataDestinations(ws.DocfxPath, ws.DocfxWorkspace, report)
+                     .Distinct(StringComparer.OrdinalIgnoreCase))
+        {
+            if (!Directory.Exists(dest))
+            {
+                continue;
+            }
+
+            foreach (var file in EnumerateFiles(dest, "*.yml"))
+            {
+                if (string.Equals(Path.GetFileName(file), "toc.yml", StringComparison.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
+                yamlFiles.Add(file);
+            }
+        }
+
+        if (yamlFiles.Count == 0)
+        {
+            return null;
+        }
+
+        var namespaces = new Dictionary<string, NamespaceInfo>(StringComparer.Ordinal);
+        var staticClassExtensionCounts = new Dictionary<string, (string Namespace, string DisplayName, int Count)>(StringComparer.Ordinal);
+        var allItems = new List<YamlApiItem>();
+        foreach (var file in yamlFiles.OrderBy(f => f, StringComparer.OrdinalIgnoreCase))
+        {
+            allItems.AddRange(ParseManagedReferenceItems(file));
+        }
+
+        var typeContextByUid = new Dictionary<string, (string Namespace, bool IsStatic)>(StringComparer.Ordinal);
+        foreach (var item in allItems)
+        {
+            if (item.Type is null || !YamlTypeKinds.Contains(item.Type, StringComparer.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            var nsName = !string.IsNullOrEmpty(item.Namespace) ? item.Namespace! : NamespaceFromUid(item.Uid);
+            if (string.IsNullOrEmpty(nsName))
+            {
+                continue;
+            }
+
+            var ns = GetOrAddNamespace(namespaces, nsName);
+            var isStatic = Regex.IsMatch(item.Syntax, @"\bstatic\b");
+            typeContextByUid[item.Uid] = (nsName, isStatic);
+
+            if (isStatic && string.Equals(item.Type, "Class", StringComparison.OrdinalIgnoreCase))
+            {
+                staticClassExtensionCounts.TryAdd(item.Uid, (nsName, SimpleNameFromUid(item.Uid), 0));
+            }
+            else if (IsExampleRequiredKind(item.Type, item.Syntax))
+            {
+                AddTypeTarget(ns, item.Uid, nsName, SimpleNameFromUid(item.Uid));
+            }
+        }
+
+        foreach (var item in allItems)
+        {
+            if (!string.Equals(item.Type, "Method", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            if (!TryParseExtensionSignature(item.Syntax, out var extendedType))
+            {
+                continue;
+            }
+
+            var declaringUid = !string.IsNullOrEmpty(item.Parent) ? item.Parent! : DeclaringTypeUidFromMethodUid(item.Uid);
+            if (string.IsNullOrEmpty(declaringUid))
+            {
+                continue;
+            }
+
+            var nsName = typeContextByUid.TryGetValue(declaringUid, out var ctx) && !string.IsNullOrEmpty(ctx.Namespace)
+                ? ctx.Namespace
+                : (!string.IsNullOrEmpty(item.Namespace) ? item.Namespace! : NamespaceFromUid(declaringUid));
+            if (string.IsNullOrEmpty(nsName))
+            {
+                continue;
+            }
+
+            var ns = GetOrAddNamespace(namespaces, nsName);
+            var methodName = MethodNameFromUid(item.Uid);
+            var declaringClass = SimpleNameFromUid(declaringUid);
+            AddExtensionMethod(ns, methodName, extendedType, declaringClass);
+            AddExtensionTarget(ns, item.Uid, nsName, methodName, declaringUid);
+
+            if (staticClassExtensionCounts.TryGetValue(declaringUid, out var sc))
+            {
+                staticClassExtensionCounts[declaringUid] = (sc.Namespace, sc.DisplayName, sc.Count + 1);
+            }
+        }
+
+        // Static extension containers (static classes that declare extension methods) are
+        // themselves documentation targets that require a type-level example, mirroring the
+        // reflection-backed model.
+        foreach (var (uid, info) in staticClassExtensionCounts)
+        {
+            if (info.Count > 0 && namespaces.TryGetValue(info.Namespace, out var ns))
+            {
+                AddTypeTarget(ns, uid, info.Namespace, info.DisplayName);
+            }
+        }
+
+        if (namespaces.Count == 0)
+        {
+            return null;
+        }
+
+        var requiredExampleTargets = namespaces.Values
+            .SelectMany(ns => ns.RequiredExampleTargets)
+            .OrderBy(t => t.Uid, StringComparer.Ordinal)
+            .ToList();
+
+        return new ApiModel(namespaces.Values.ToList(), requiredExampleTargets);
+    }
+
+    private static ApiModel DiscoverApiFromSource(ValidationWorkspace ws, Report report)
+    {
+        var namespaces = new Dictionary<string, NamespaceInfo>(StringComparer.Ordinal);
+        var staticExtensionContainers = new Dictionary<string, (string Namespace, string DisplayName, int Count)>(StringComparer.Ordinal);
+
+        foreach (var project in ws.LibraryProjects)
+        {
+            foreach (var file in EnumerateProjectSourceFiles(project))
+            {
+                string text;
+                try
+                {
+                    text = File.ReadAllText(file);
+                }
+                catch
+                {
+                    continue;
+                }
+
+                ScanSourceFile(text, namespaces, staticExtensionContainers, ws, project);
+            }
+        }
+
+        foreach (var (key, info) in staticExtensionContainers)
+        {
+            if (info.Count > 0 && namespaces.TryGetValue(info.Namespace, out var ns))
+            {
+                AddTypeTarget(ns, key, info.Namespace, info.DisplayName);
+            }
+        }
+
+        foreach (var ns in namespaces.Values.Where(n => n.HasCSharp14ExtensionBlocks))
+        {
+            report.Warnings.Add(new Diagnostic("DOCFX_EXTENSION_BLOCK_UNSUPPORTED", null, ns.Name,
+                $"Namespace {ns.Name} contains C# 14 extension-block types. DocFX (issue #11010) does not currently generate correct API metadata for extension blocks, so generated UIDs for those members may be missing or synthetic. Classic static extension methods with 'this' parameters remain fully supported. Do not exclude these APIs or invent special rules; continue generating docs for all discoverable public APIs and document the limitation in the overwrite file when needed."));
+        }
+
+        var requiredExampleTargets = namespaces.Values
+            .SelectMany(ns => ns.RequiredExampleTargets)
+            .OrderBy(t => t.Uid, StringComparer.Ordinal)
+            .ToList();
+
+        return new ApiModel(namespaces.Values.ToList(), requiredExampleTargets);
+    }
+
+    private static void ScanSourceFile(
+        string text,
+        Dictionary<string, NamespaceInfo> namespaces,
+        Dictionary<string, (string Namespace, string DisplayName, int Count)> staticExtensionContainers,
+        ValidationWorkspace ws,
+        ProjectInfo project)
+    {
+        var lines = text.Replace("\r\n", "\n").Replace("\r", "\n").Split('\n');
+        var cleaned = StripCommentsAndStrings(lines);
+
+        string? currentNamespace = null;
+        var namespaceBodyDepth = 0;
+        var depth = 0;
+        string? currentTopLevelStaticClass = null;
+        var currentTopLevelStaticClassDepth = -1;
+        var currentStaticClassEntered = false;
+
+        for (var i = 0; i < lines.Length; i++)
+        {
+            var clean = cleaned[i];
+
+            var nsMatch = Regex.Match(clean, @"^\s*namespace\s+(?<ns>[\w.]+)\s*(?<brace>\{)?\s*;?\s*$");
+            if (nsMatch.Success)
+            {
+                currentNamespace = nsMatch.Groups["ns"].Value;
+                RegisterNamespaceProject(ws, currentNamespace, project);
+                GetOrAddNamespace(namespaces, currentNamespace);
+                namespaceBodyDepth = nsMatch.Groups["brace"].Success ? depth + 1 : depth;
+                depth += CountChar(clean, '{') - CountChar(clean, '}');
+                continue;
+            }
+
+            if (currentNamespace is not null)
+            {
+                var isTopLevel = depth == namespaceBodyDepth;
+
+                if (isTopLevel && Regex.IsMatch(clean, @"\bextension\s*\("))
+                {
+                    GetOrAddNamespace(namespaces, currentNamespace).HasCSharp14ExtensionBlocks = true;
+                }
+
+                var typeMatch = Regex.Match(clean,
+                    @"(?<mods>(?:public|abstract|sealed|static|partial|readonly|unsafe|ref|\s)*)\b(?<kind>class|struct|interface|enum|record)\b(?:\s+(?<recstruct>struct|class))?\s+(?<name>\w+)(?<generic><[^>]*>)?");
+                if (isTopLevel && typeMatch.Success && Regex.IsMatch(typeMatch.Groups["mods"].Value, @"\bpublic\b"))
+                {
+                    var ns = GetOrAddNamespace(namespaces, currentNamespace);
+                    var name = typeMatch.Groups["name"].Value;
+                    var arity = CountGenericArity(typeMatch.Groups["generic"].Value);
+                    var uid = currentNamespace + "." + name + (arity > 0 ? "`" + arity : string.Empty);
+                    var mods = typeMatch.Groups["mods"].Value;
+                    var kind = typeMatch.Groups["kind"].Value;
+                    var isStatic = Regex.IsMatch(mods, @"\bstatic\b");
+
+                    if (isStatic && string.Equals(kind, "class", StringComparison.Ordinal))
+                    {
+                        currentTopLevelStaticClass = uid;
+                        currentTopLevelStaticClassDepth = depth;
+                        currentStaticClassEntered = false;
+                        staticExtensionContainers.TryAdd(uid, (currentNamespace, name, 0));
+                    }
+                    else if (IsExampleRequiredSourceKind(kind, mods))
+                    {
+                        AddTypeTarget(ns, uid, currentNamespace, name);
+                    }
+                }
+
+                // Classic extension methods inside the current top-level static class.
+                if (currentTopLevelStaticClass is not null)
+                {
+                    var extMatch = Regex.Match(clean,
+                        @"\bpublic\s+static\s+[^\n;{=]*?\b(?<name>\w+)\s*(?:<[^>]*>)?\s*\(\s*(?:\[[^\]]*\]\s*)*this\s+(?<ext>[\w.]+(?:<[^>]{0,120}>)?)");
+                    if (extMatch.Success)
+                    {
+                        var ns = GetOrAddNamespace(namespaces, currentNamespace);
+                        var methodName = extMatch.Groups["name"].Value;
+                        var extendedType = SimpleNameFromTypeRef(extMatch.Groups["ext"].Value);
+                        AddExtensionMethod(ns, methodName, extendedType, SimpleNameFromUid(currentTopLevelStaticClass));
+                        AddExtensionTarget(ns, currentTopLevelStaticClass + "." + methodName, currentNamespace, methodName, currentTopLevelStaticClass);
+                        if (staticExtensionContainers.TryGetValue(currentTopLevelStaticClass, out var sc))
+                        {
+                            staticExtensionContainers[currentTopLevelStaticClass] = (sc.Namespace, sc.DisplayName, sc.Count + 1);
+                        }
+                    }
+                }
+            }
+
+            depth += CountChar(clean, '{') - CountChar(clean, '}');
+            if (currentTopLevelStaticClass is not null)
+            {
+                if (depth > currentTopLevelStaticClassDepth)
+                {
+                    currentStaticClassEntered = true;
+                }
+                else if (currentStaticClassEntered && depth <= currentTopLevelStaticClassDepth)
+                {
+                    currentTopLevelStaticClass = null;
+                    currentTopLevelStaticClassDepth = -1;
+                    currentStaticClassEntered = false;
+                }
+            }
+        }
+    }
+
+    private static IEnumerable<string> EnumerateProjectSourceFiles(ProjectInfo project)
+    {
+        var projectDir = Path.GetDirectoryName(project.Path);
+        if (string.IsNullOrEmpty(projectDir) || !Directory.Exists(projectDir))
+        {
+            yield break;
+        }
+
+        foreach (var file in EnumerateFiles(projectDir, "*.cs"))
+        {
+            var name = Path.GetFileName(file);
+            if (name.EndsWith(".g.cs", StringComparison.OrdinalIgnoreCase) ||
+                name.EndsWith(".Designer.cs", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("AssemblyInfo.cs", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("GlobalUsings.cs", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            yield return file;
+        }
+    }
+
+    private static void EnsureNamespaceProjectMap(ValidationWorkspace ws)
+    {
+        if (ws.NamespaceProjects.Count > 0)
+        {
+            return;
+        }
+
+        foreach (var project in ws.LibraryProjects)
+        {
+            foreach (var file in EnumerateProjectSourceFiles(project))
+            {
+                string text;
+                try
+                {
+                    text = File.ReadAllText(file);
+                }
+                catch
+                {
+                    continue;
+                }
+
+                foreach (Match m in Regex.Matches(text, @"(?m)^\s*namespace\s+(?<ns>[\w.]+)"))
+                {
+                    RegisterNamespaceProject(ws, m.Groups["ns"].Value, project);
+                }
+            }
+        }
+    }
+
+    private static void RegisterNamespaceProject(ValidationWorkspace ws, string ns, ProjectInfo project)
+    {
+        if (string.IsNullOrEmpty(ns))
+        {
+            return;
+        }
+
+        if (!ws.NamespaceProjects.TryGetValue(ns, out var list))
+        {
+            list = new List<ProjectInfo>();
+            ws.NamespaceProjects[ns] = list;
+        }
+
+        if (!list.Any(p => PathsEqual(p.Path, project.Path)))
+        {
+            list.Add(project);
+        }
+    }
+
+    private static NamespaceInfo GetOrAddNamespace(Dictionary<string, NamespaceInfo> namespaces, string name)
+    {
+        if (!namespaces.TryGetValue(name, out var info))
+        {
+            info = new NamespaceInfo(name);
+            namespaces[name] = info;
+        }
+
+        return info;
+    }
+
+    private static void AddTypeTarget(NamespaceInfo ns, string uid, string nsName, string displayName)
+    {
+        var target = new ApiTargetInfo(uid, nsName, ApiTargetKind.Type, displayName);
+        if (!ns.RequiredExampleTargets.Contains(target))
+        {
+            ns.RequiredExampleTargets.Add(target);
+        }
+    }
+
+    private static void AddExtensionTarget(NamespaceInfo ns, string uid, string nsName, string displayName, string declaringTypeUid)
+    {
+        var target = new ApiTargetInfo(uid, nsName, ApiTargetKind.ExtensionMethod, displayName, declaringTypeUid);
+        if (!ns.RequiredExampleTargets.Contains(target))
+        {
+            ns.RequiredExampleTargets.Add(target);
+        }
+    }
+
+    private static void AddExtensionMethod(NamespaceInfo ns, string methodName, string extendedType, string declaringClass)
+    {
+        var info = new ExtensionMethodInfo(methodName, extendedType, declaringClass);
+        if (!ns.ExtensionMethods.Contains(info))
+        {
+            ns.ExtensionMethods.Add(info);
+        }
+    }
+
+    private static bool IsExampleRequiredKind(string yamlType, string syntax)
+    {
+        if (string.Equals(yamlType, "Interface", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (Regex.IsMatch(syntax, @"\bstatic\b"))
+        {
+            // Static containers are added separately only when they declare extension methods.
+            return false;
+        }
+
+        if (Regex.IsMatch(syntax, @"\babstract\b"))
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static bool IsExampleRequiredSourceKind(string kind, string mods)
+    {
+        if (string.Equals(kind, "interface", StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        if (Regex.IsMatch(mods, @"\bstatic\b") || Regex.IsMatch(mods, @"\babstract\b"))
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static bool TryParseExtensionSignature(string syntax, out string extendedType)
+    {
+        extendedType = string.Empty;
+        if (!Regex.IsMatch(syntax, @"\bstatic\b"))
+        {
+            return false;
+        }
+
+        var m = Regex.Match(syntax, @"\(\s*(?:\[[^\]]*\]\s*)*this\s+(?<ext>[\w.]+(?:<[^>]{0,120}>)?)");
+        if (!m.Success)
+        {
+            return false;
+        }
+
+        extendedType = SimpleNameFromTypeRef(m.Groups["ext"].Value);
+        return true;
+    }
+
+    private static string SimpleNameFromTypeRef(string typeRef)
+    {
+        var trimmed = typeRef.Trim();
+        var generic = trimmed.IndexOf('<');
+        if (generic >= 0)
+        {
+            trimmed = trimmed[..generic];
+        }
+
+        var lastDot = trimmed.LastIndexOf('.');
+        if (lastDot >= 0)
+        {
+            trimmed = trimmed[(lastDot + 1)..];
+        }
+
+        var tick = trimmed.IndexOf('`');
+        return tick >= 0 ? trimmed[..tick] : trimmed;
+    }
+
+    private static string SimpleNameFromUid(string uid)
+    {
+        var beforeGeneric = uid;
+        var tick = beforeGeneric.IndexOf('`');
+        if (tick >= 0)
+        {
+            beforeGeneric = beforeGeneric[..tick];
+        }
+
+        var lastDot = beforeGeneric.LastIndexOf('.');
+        return lastDot >= 0 ? beforeGeneric[(lastDot + 1)..] : beforeGeneric;
+    }
+
+    private static string NamespaceFromUid(string uid)
+    {
+        var lastDot = uid.LastIndexOf('.');
+        return lastDot > 0 ? uid[..lastDot] : string.Empty;
+    }
+
+    private static string MethodNameFromUid(string methodUid)
+    {
+        var paren = methodUid.IndexOf('(');
+        var head = paren >= 0 ? methodUid[..paren] : methodUid;
+        return SimpleNameFromUid(head);
+    }
+
+    private static string DeclaringTypeUidFromMethodUid(string methodUid)
+    {
+        var paren = methodUid.IndexOf('(');
+        var head = paren >= 0 ? methodUid[..paren] : methodUid;
+        var lastDot = head.LastIndexOf('.');
+        return lastDot > 0 ? head[..lastDot] : string.Empty;
+    }
+
+    private static int CountGenericArity(string generic)
+    {
+        if (string.IsNullOrEmpty(generic))
+        {
+            return 0;
+        }
+
+        var inner = generic.Trim();
+        if (inner.StartsWith('<') && inner.EndsWith('>'))
+        {
+            inner = inner[1..^1];
+        }
+
+        if (string.IsNullOrWhiteSpace(inner))
+        {
+            return 0;
+        }
+
+        var depth = 0;
+        var count = 1;
+        foreach (var c in inner)
+        {
+            if (c == '<')
+            {
+                depth++;
+            }
+            else if (c == '>')
+            {
+                depth--;
+            }
+            else if (c == ',' && depth == 0)
+            {
+                count++;
+            }
+        }
+
+        return count;
+    }
+
+    private static int CountChar(string text, char c)
+    {
+        var count = 0;
+        foreach (var ch in text)
+        {
+            if (ch == c)
+            {
+                count++;
+            }
+        }
+
+        return count;
+    }
+
+    /// <summary>
+    /// Returns a copy of <paramref name="lines"/> with line comments, block comments, and string
+    /// and character literals blanked so brace counting and declaration matching ignore braces or
+    /// keywords that appear inside comments or strings. Conservative, not a full C# lexer.
+    /// </summary>
+    private static string[] StripCommentsAndStrings(string[] lines)
+    {
+        var result = new string[lines.Length];
+        var inBlockComment = false;
+        for (var i = 0; i < lines.Length; i++)
+        {
+            var line = lines[i];
+            var sb = new StringBuilder(line.Length);
+            for (var j = 0; j < line.Length; j++)
+            {
+                var c = line[j];
+                if (inBlockComment)
+                {
+                    if (c == '*' && j + 1 < line.Length && line[j + 1] == '/')
+                    {
+                        inBlockComment = false;
+                        j++;
+                    }
+
+                    continue;
+                }
+
+                if (c == '/' && j + 1 < line.Length && line[j + 1] == '/')
+                {
+                    break;
+                }
+
+                if (c == '/' && j + 1 < line.Length && line[j + 1] == '*')
+                {
+                    inBlockComment = true;
+                    j++;
+                    continue;
+                }
+
+                if (c == '"')
+                {
+                    j = SkipStringLiteral(line, j);
+                    sb.Append("\"\"");
+                    continue;
+                }
+
+                if (c == '\'')
+                {
+                    j = SkipCharLiteral(line, j);
+                    sb.Append("' '");
+                    continue;
+                }
+
+                sb.Append(c);
+            }
+
+            result[i] = sb.ToString();
+        }
+
+        return result;
+    }
+
+    private static int SkipStringLiteral(string line, int start)
+    {
+        for (var j = start + 1; j < line.Length; j++)
+        {
+            if (line[j] == '\\')
+            {
+                j++;
+                continue;
+            }
+
+            if (line[j] == '"')
+            {
+                return j;
+            }
+        }
+
+        return line.Length - 1;
+    }
+
+    private static int SkipCharLiteral(string line, int start)
+    {
+        for (var j = start + 1; j < line.Length; j++)
+        {
+            if (line[j] == '\\')
+            {
+                j++;
+                continue;
+            }
+
+            if (line[j] == '\'')
+            {
+                return j;
+            }
+        }
+
+        return line.Length - 1;
+    }
+
+    private sealed record YamlApiItem(string Uid, string? Type, string? Namespace, string? Name, string? Parent, string Syntax);
+
+    private static List<YamlApiItem> ParseManagedReferenceItems(string yamlFile)
+    {
+        string[] lines;
+        try
+        {
+            lines = File.ReadAllLines(yamlFile);
+        }
+        catch
+        {
+            return new List<YamlApiItem>();
+        }
+
+        var items = new List<YamlApiItem>();
+        var inItems = false;
+        string? uid = null, type = null, ns = null, name = null, parent = null, syntax = null;
+
+        void Flush()
+        {
+            if (uid is not null)
+            {
+                items.Add(new YamlApiItem(uid, type, ns, name, parent, syntax ?? string.Empty));
+            }
+
+            uid = type = ns = name = parent = syntax = null;
+        }
+
+        for (var i = 0; i < lines.Length; i++)
+        {
+            var line = lines[i];
+            if (!inItems)
+            {
+                if (line.StartsWith("items:", StringComparison.Ordinal))
+                {
+                    inItems = true;
+                }
+
+                continue;
+            }
+
+            if (line.Length > 0 && line[0] != ' ' && line[0] != '-' && line[0] != '#')
+            {
+                // references: / shouldSkipMarkup: etc. — end of the items section.
+                break;
+            }
+
+            var itemStart = Regex.Match(line, @"^- uid:\s*(.+?)\s*$");
+            if (itemStart.Success)
+            {
+                Flush();
+                uid = StripYamlScalar(itemStart.Groups[1].Value);
+                continue;
+            }
+
+            if (uid is null)
+            {
+                continue;
+            }
+
+            var prop = Regex.Match(line, @"^  (?<key>[\w.]+):\s?(?<val>.*)$");
+            if (prop.Success)
+            {
+                var key = prop.Groups["key"].Value;
+                var val = prop.Groups["val"].Value;
+                switch (key)
+                {
+                    case "type":
+                        type ??= StripYamlScalar(val.Trim());
+                        break;
+                    case "namespace":
+                        ns = StripYamlScalar(val.Trim());
+                        break;
+                    case "name":
+                        name ??= StripYamlScalar(val.Trim());
+                        break;
+                    case "parent":
+                        parent = StripYamlScalar(val.Trim());
+                        break;
+                }
+
+                continue;
+            }
+
+            var content = Regex.Match(line, @"^    content:\s?(?<val>.*)$");
+            if (content.Success && syntax is null)
+            {
+                var val = content.Groups["val"].Value.Trim();
+                if (val.Length == 0 || val is ">" or ">-" or ">+" or "|" or "|-" or "|+")
                 {
-                    info = new NamespaceInfo(nsName);
-                    namespaces[nsName] = info;
-                }
+                    var sb = new StringBuilder();
+                    var j = i + 1;
+                    while (j < lines.Length)
+                    {
+                        var bl = lines[j];
+                        if (bl.Trim().Length == 0)
+                        {
+                            j++;
+                            continue;
+                        }
 
-                // Track synthetic C# 14 extension-block containers so we can warn about DocFX #11010.
-                if (IsSyntheticExtensionBlockContainer(type))
+                        var indent = bl.Length - bl.TrimStart().Length;
+                        if (indent <= 4)
+                        {
+                            break;
+                        }
+
+                        if (sb.Length > 0)
+                        {
+                            sb.Append(' ');
+                        }
+
+                        sb.Append(bl.Trim());
+                        j++;
+                    }
+
+                    syntax = sb.ToString();
+                    i = j - 1;
+                }
+                else
                 {
-                    info.HasCSharp14ExtensionBlocks = true;
+                    syntax = StripYamlScalar(val);
                 }
-
-                CollectApiTargets(type, info);
-                CollectExtensionMethods(type, info);
             }
         }
 
-        // Emit a warning for namespaces that contain C# 14 extension blocks: DocFX issue #11010
-        // means those blocks do not yet generate correct API metadata. Extension methods declared
-        // with the classic `this` pattern are unaffected and remain supported.
-        foreach (var ns in namespaces.Values.Where(n => n.HasCSharp14ExtensionBlocks))
+        Flush();
+        return items;
+    }
+
+    private static string StripYamlScalar(string value)
+    {
+        var v = value.Trim();
+        if (v.Length >= 2 && ((v[0] == '"' && v[^1] == '"') || (v[0] == '\'' && v[^1] == '\'')))
         {
-            report.Warnings.Add(new Diagnostic("DOCFX_EXTENSION_BLOCK_UNSUPPORTED", null, ns.Name,
-                $"Namespace {ns.Name} contains C# 14 extension-block types. DocFX (issue #11010) does not currently generate correct API metadata for extension blocks, so generated UIDs for those members may be missing or synthetic. Classic static extension methods with 'this' parameters remain fully supported. Do not exclude these APIs or invent special rules; continue generating docs for all discoverable public APIs and document the limitation in the overwrite file when needed."));
+            v = v[1..^1];
         }
 
-        var requiredExampleTargets = namespaces.Values
-            .SelectMany(ns => ns.RequiredExampleTargets)
-            .OrderBy(t => t.Uid, StringComparer.Ordinal)
-            .ToList();
-
-        return new ApiModel(namespaces.Values.ToList(), requiredExampleTargets);
+        return v;
     }
 
     private static List<string> DistinctResolverPaths(IEnumerable<string> paths)
@@ -2250,17 +3132,12 @@ private static string SimpleTypeName(Type type)
     // Namespace page validation
     // ----------------------------------------------------------------------
 
-    private static void ValidateNamespacePage(string repoRoot, string page, NamespaceInfo ns, Report report)
+    private static void ValidateNamespacePage(string repoRoot, string page, string text, NamespaceInfo ns, Report report)
     {
         var rel = Rel(repoRoot, page);
-        string text;
-        try
-        {
-            text = File.ReadAllText(page);
-        }
-        catch (Exception ex)
+        if (string.IsNullOrEmpty(text))
         {
-            report.Errors.Add(new Diagnostic("NAMESPACE_PAGE_MISSING", rel, ns.Name, $"Unable to read namespace page: {ex.Message}"));
+            report.Errors.Add(new Diagnostic("NAMESPACE_PAGE_MISSING", rel, ns.Name, "Unable to read namespace page."));
             return;
         }
 
@@ -2605,25 +3482,28 @@ private static bool HasExampleSectionWithCSharpFence(string body)
     // Sample validation
     // ----------------------------------------------------------------------
 
-    private static void ValidateSamples(string repoRoot, List<string> markdownFiles, List<ProjectInfo> libraryProjects,
-        Options options, HashSet<string>? changedFiles, bool hasStrongNameKey, Report report)
+    private static void ValidateSamples(ValidationWorkspace ws, Options options, HashSet<string>? changedFiles,
+        bool hasStrongNameKey, Report report)
     {
-        // 1. Extract all C# samples from Markdown files.
+        var repoRoot = ws.RepoRoot;
+
+        // 1. Extract all C# samples from cached Markdown text.
         var phaseTimer = Stopwatch.StartNew();
         var samples = new List<SampleFence>();
-        foreach (var md in markdownFiles)
+        foreach (var md in ws.MarkdownFiles)
         {
             if (options.ChangedOnly && changedFiles is not null && !changedFiles.Contains(Path.GetFullPath(md)))
             {
                 continue;
             }
 
-            samples.AddRange(ExtractFences(md));
+            samples.AddRange(ExtractFences(md, ws.ReadMarkdown(md)));
         }
 
-        WritePhase(options, "sample extraction", phaseTimer.Elapsed);
+        WritePhase(options, report, "sample extraction", phaseTimer.Elapsed, $"{samples.Count} fence(s)");
         if (samples.Count == 0)
         {
+            WriteSkippedPhase(options, report, "sample validation", "no C# samples found");
             return;
         }
 
@@ -2667,56 +3547,79 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
 
         if (toCompile.Count == 0)
         {
+            WriteSkippedPhase(options, report, "sample validation", "no compilable samples");
             return;
         }
 
-        // 3. Create reusable sample-validation worker pool and compile with bounded parallelism.
-        //    Workers use ProjectReference for all documented library projects so the full
-        //    compile-time dependency closure (NuGet packages, transitive references, framework
-        //    assemblies exposed through public signatures) is available without manual DLL enumeration.
+        // 3. Resolve a scoped project/package reference set per sample, then group samples that
+        //    share a reference set. Each group compiles against ONLY the documented project(s)
+        //    that own the sample's namespace (and their transitive references resolved by MSBuild),
+        //    never every documented library project. Samples whose owner cannot be resolved fall
+        //    back to the full documented project set, which forms a single shared group.
+        EnsureNamespaceProjectMap(ws);
+        var framework = options.Framework ?? "net10.0";
+        var packageMode = string.Equals(options.SampleReferenceMode, "package", StringComparison.OrdinalIgnoreCase);
+
+        var groups = new Dictionary<string, List<(SampleFence Sample, int OriginalIndex)>>(StringComparer.Ordinal);
+        var groupRefs = new Dictionary<string, SampleReferenceSet>(StringComparer.Ordinal);
+        foreach (var entry in toCompile)
+        {
+            var kind = IsProgramCsExample(entry.Sample.Code) ? "app" : "lib";
+            var refSet = ResolveSampleReferenceSet(entry.Sample, ws, kind, packageMode);
+            var key = $"{kind}::{(refSet.IsPackageMode ? "pkg" : "proj")}::{string.Join(";", refSet.Items)}";
+            if (!groups.TryGetValue(key, out var list))
+            {
+                list = new List<(SampleFence, int)>();
+                groups[key] = list;
+                groupRefs[key] = refSet;
+            }
+
+            list.Add(entry);
+        }
+
         var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-samples-" + Guid.NewGuid().ToString("N"));
         Directory.CreateDirectory(tempRoot);
         try
         {
             var parallelism = GetSampleValidationParallelism(options);
-            var workerCount = Math.Min(parallelism, toCompile.Count);
+            var workerCount = Math.Min(parallelism, groups.Count);
             WritePhaseStart(options, "sample validation", workerCount, toCompile.Count);
             phaseTimer.Restart();
 
-            // Create and restore each worker once.
-            var workers = new SampleWorkerInfo[workerCount];
-            for (int w = 0; w < workerCount; w++)
-            {
-                workers[w] = CreateSampleWorker(
-                    tempRoot, w + 1, libraryProjects,
-                    options.Framework ?? "net10.0", options.Configuration, repoRoot, hasStrongNameKey, report);
-            }
-
-            // Assign samples to workers in round-robin order. Each worker processes its
-            // stripe sequentially, so no synchronization is needed within a worker.
             // Results are stored in a pre-sized indexed array to guarantee deterministic
-            // diagnostic ordering regardless of worker completion order.
+            // diagnostic ordering regardless of group completion order.
             var results = new SampleCompileResult?[samples.Count];
-            var workerTasks = Enumerable.Range(0, workerCount)
-                .Select(workerIdx =>
+            var orderedGroups = groups.Keys.OrderBy(k => k, StringComparer.Ordinal).ToList();
+            using var throttler = new SemaphoreSlim(Math.Max(1, parallelism));
+            var tasks = new List<Task>();
+            for (var g = 0; g < orderedGroups.Count; g++)
+            {
+                var key = orderedGroups[g];
+                var groupNumber = g + 1;
+                throttler.Wait();
+                tasks.Add(Task.Run(() =>
                 {
-                    var mySamples = toCompile.Where((_, si) => si % workerCount == workerIdx).ToList();
-                    var myWorker = workers[workerIdx];
-                    return Task.Run(() =>
+                    try
                     {
-                        foreach (var (sample, originalIndex) in mySamples)
+                        var worker = CreateSampleGroupWorker(tempRoot, groupNumber, groupRefs[key], framework, hasStrongNameKey, report);
+                        foreach (var (sample, originalIndex) in groups[key])
                         {
-                            var (ok, diags, exitCode) = CompileWithWorker(myWorker, sample, options.Configuration, hasStrongNameKey);
+                            var (ok, diags, exitCode) = CompileSampleInGroup(worker, sample, options.Configuration, hasStrongNameKey);
                             results[originalIndex] = new SampleCompileResult(ok, diags, exitCode);
                         }
-                    });
-                })
-                .ToArray();
+                    }
+                    finally
+                    {
+                        throttler.Release();
+                    }
+                }));
+            }
 
-            Task.WaitAll(workerTasks);
-            WritePhase(options, "sample validation", phaseTimer.Elapsed);
+            Task.WaitAll(tasks.ToArray());
+            WritePhase(options, report, "sample validation", phaseTimer.Elapsed,
+                $"{groups.Count} group(s), {toCompile.Count} sample(s)");
 
-            // 5. Merge results in original sample order for deterministic diagnostics.
+            // 4. Merge results in original sample order for deterministic diagnostics.
             for (int i = 0; i < samples.Count; i++)
             {
                 var result = results[i];
@@ -2743,6 +3646,110 @@ private static void ValidateSamples(string repoRoot, List<string> markdownFiles,
         }
     }
 
+    /// <summary>
+    /// Resolves the minimal set of documented project (or package) references a sample needs by
+    /// mapping the sample's owning namespace to the project(s) that declare it. Falls back to the
+    /// full documented project set only when the owner cannot be determined.
+    /// </summary>
+    private static SampleReferenceSet ResolveSampleReferenceSet(SampleFence sample, ValidationWorkspace ws, string kind, bool packageMode)
+    {
+        var owners = ResolveOwningProjects(sample, ws);
+        if (owners.Count == 0)
+        {
+            owners = ws.LibraryProjects;
+        }
+
+        owners = owners
+            .GroupBy(p => Path.GetFullPath(p.Path), StringComparer.OrdinalIgnoreCase)
+            .Select(g => g.First())
+            .OrderBy(p => Path.GetFullPath(p.Path), StringComparer.OrdinalIgnoreCase)
+            .ToList();
+
+        if (packageMode)
+        {
+            var packageRefs = new List<(string Id, string Version)>();
+            var projectRefs = new List<ProjectInfo>();
+            foreach (var owner in owners)
+            {
+                if (!string.IsNullOrWhiteSpace(owner.PackageId))
+                {
+                    packageRefs.Add((owner.PackageId!, "*"));
+                }
+                else
+                {
+                    projectRefs.Add(owner);
+                }
+            }
+
+            var items = packageRefs.Select(p => $"pkg:{p.Id}@{p.Version}")
+                .Concat(projectRefs.Select(p => $"proj:{Path.GetFullPath(p.Path)}"))
+                .OrderBy(s => s, StringComparer.OrdinalIgnoreCase)
+                .ToList();
+            return new SampleReferenceSet(kind, true, items, projectRefs, packageRefs);
+        }
+
+        var projectItems = owners.Select(p => Path.GetFullPath(p.Path))
+            .OrderBy(s => s, StringComparer.OrdinalIgnoreCase)
+            .ToList();
+        return new SampleReferenceSet(kind, false, projectItems, owners, new List<(string, string)>());
+    }
+
+    private static List<ProjectInfo> ResolveOwningProjects(SampleFence sample, ValidationWorkspace ws)
+    {
+        var ns = ResolveSampleNamespace(sample, ws);
+        if (ns is not null && ws.NamespaceProjects.TryGetValue(ns, out var projects) && projects.Count > 0)
+        {
+            return projects.ToList();
+        }
+
+        return new List<ProjectInfo>();
+    }
+
+    private static string? ResolveSampleNamespace(SampleFence sample, ValidationWorkspace ws)
+    {
+        // Prefer the overwrite uid(s) authored in the sample's file.
+        foreach (var section in ws.OverwriteSections.Where(s => PathsEqual(s.File, sample.File)))
+        {
+            if (ws.NamespaceProjects.ContainsKey(section.Uid))
+            {
+                return section.Uid;
+            }
+
+            var prefix = LongestNamespacePrefix(section.Uid, ws);
+            if (prefix is not null)
+            {
+                return prefix;
+            }
+        }
+
+        // Fall back to the file stem (namespace pages are named after the namespace).
+        var stem = Path.GetFileNameWithoutExtension(sample.File);
+        if (ws.NamespaceProjects.ContainsKey(stem))
+        {
+            return stem;
+        }
+
+        return LongestNamespacePrefix(stem, ws);
+    }
+
+    private static string? LongestNamespacePrefix(string uid, ValidationWorkspace ws)
+    {
+        string? best = null;
+        foreach (var ns in ws.NamespaceProjects.Keys)
+        {
+            if (string.Equals(uid, ns, StringComparison.Ordinal) ||
+                uid.StartsWith(ns + ".", StringComparison.Ordinal))
+            {
+                if (best is null || ns.Length > best.Length)
+                {
+                    best = ns;
+                }
+            }
+        }
+
+        return best;
+    }
+
     private static int GetSampleValidationParallelism(Options options)
     {
         var processorCount = Math.Max(1, Environment.ProcessorCount);
@@ -2766,131 +3773,101 @@ private static int GetSampleValidationParallelism(Options options)
     }
 
     /// <summary>
-    /// Creates a reusable sample-validation worker under <paramref name="tempRoot"/> and
-    /// performs a one-time restore so all subsequent sample builds can use <c>--no-restore</c>.
+    /// Creates a single-kind (lib or app) sample worker for a dependency group under
+    /// <paramref name="tempRoot"/>, referencing only the resolved scoped project/package set,
+    /// and restores it once so subsequent sample builds in the group can use <c>--no-restore</c>.
     /// </summary>
-    private static SampleWorkerInfo CreateSampleWorker(
-        string tempRoot, int workerNumber,
-        List<ProjectInfo> libraryProjects,
-        string framework, string configuration,
-        string repoRoot, bool hasStrongNameKey, Report report)
-    {
-        var workerDir = Path.Combine(tempRoot, "docfx-sample-workers", $"worker-{workerNumber:D4}");
-        var libDir = Path.Combine(workerDir, "lib");
-        var appDir = Path.Combine(workerDir, "app");
-        Directory.CreateDirectory(libDir);
-        Directory.CreateDirectory(appDir);
-
-        // Class-library project — for class-based samples (namespace + type declaration).
-        var libProjPath = Path.Combine(libDir, "DocfxSampleLib.csproj");
-        File.WriteAllText(libProjPath, GenerateSampleLibProject(libraryProjects, framework),
-            new UTF8Encoding(false));
-        // Compilable placeholder; overwritten per sample.
-        File.WriteAllText(Path.Combine(libDir, "Sample.cs"),
-            "namespace DocfxSamplePlaceholder { internal static class _Placeholder { } }",
-            new UTF8Encoding(false));
+    private static SampleGroupWorker CreateSampleGroupWorker(
+        string tempRoot, int groupNumber, SampleReferenceSet refSet,
+        string framework, bool hasStrongNameKey, Report report)
+    {
+        var isApp = string.Equals(refSet.Kind, "app", StringComparison.Ordinal);
+        var workerDir = Path.Combine(tempRoot, "docfx-sample-workers", $"group-{groupNumber:D4}");
+        Directory.CreateDirectory(workerDir);
+
+        var projPath = Path.Combine(workerDir, isApp ? "DocfxSampleApp.csproj" : "DocfxSampleLib.csproj");
+        File.WriteAllText(projPath, GenerateSampleGroupProject(refSet, framework, isApp), new UTF8Encoding(false));
 
-        // Console-app project — for Program.cs / top-level-statement samples.
-        var appProjPath = Path.Combine(appDir, "DocfxSampleApp.csproj");
-        File.WriteAllText(appProjPath, GenerateSampleAppProject(libraryProjects, framework),
+        var sourceName = isApp ? "Program.cs" : "Sample.cs";
+        File.WriteAllText(Path.Combine(workerDir, sourceName),
+            isApp ? "// placeholder" : "namespace DocfxSamplePlaceholder { internal static class _Placeholder { } }",
             new UTF8Encoding(false));
-        // Compilable placeholder; overwritten per sample.
-        File.WriteAllText(Path.Combine(appDir, "Program.cs"), "// placeholder", new UTF8Encoding(false));
 
-        // Restore once so --no-restore works for all subsequent sample builds.
         var signingProperty = hasStrongNameKey ? string.Empty : " -p:SkipSignAssembly=true";
-        var libRestoreOk = RunProcess("dotnet",
-            $"restore \"{libProjPath}\" --nologo{signingProperty}", libDir).ExitCode == 0;
-        var appRestoreOk = RunProcess("dotnet",
-            $"restore \"{appProjPath}\" --nologo{signingProperty}", appDir).ExitCode == 0;
+        var restoreOk = RunProcess("dotnet",
+            $"restore \"{projPath}\" --nologo{signingProperty}", workerDir,
+            permission: ProcessPermission.SampleCompile).ExitCode == 0;
 
-        if (!libRestoreOk || !appRestoreOk)
+        if (!restoreOk)
         {
             report.Warnings.Add(new Diagnostic("SAMPLE_WORKER_RESTORE_FAILED", workerDir, null,
-                $"Sample validation worker {workerNumber} restore failed; affected samples will build without --no-restore and may be slower."));
+                $"Sample validation group {groupNumber} restore failed; affected samples will build without --no-restore and may be slower."));
         }
 
-        return new SampleWorkerInfo(libDir, appDir, libProjPath, appProjPath, libRestoreOk, appRestoreOk);
-    }
-
-    private static string GenerateSampleLibProject(List<ProjectInfo> libraryProjects, string framework)
-    {
-        var sb = new StringBuilder();
-        sb.AppendLine("""<Project Sdk="Microsoft.NET.Sdk">""");
-        sb.AppendLine("  <PropertyGroup>");
-        sb.AppendLine($"    <TargetFramework>{framework}</TargetFramework>");
-        sb.AppendLine("    <OutputType>Library</OutputType>");
-        sb.AppendLine("    <Nullable>enable</Nullable>");
-        sb.AppendLine("    <LangVersion>latest</LangVersion>");
-        sb.AppendLine("    <ImplicitUsings>disable</ImplicitUsings>");
-        sb.AppendLine("  </PropertyGroup>");
-        AppendProjectReferences(sb, libraryProjects);
-        sb.AppendLine("</Project>");
-        return sb.ToString();
+        return new SampleGroupWorker(workerDir, projPath, isApp, restoreOk);
     }
 
-    private static string GenerateSampleAppProject(List<ProjectInfo> libraryProjects, string framework)
+    private static string GenerateSampleGroupProject(SampleReferenceSet refSet, string framework, bool isApp)
     {
         var sb = new StringBuilder();
         sb.AppendLine("""<Project Sdk="Microsoft.NET.Sdk">""");
         sb.AppendLine("  <PropertyGroup>");
         sb.AppendLine($"    <TargetFramework>{framework}</TargetFramework>");
-        sb.AppendLine("    <OutputType>Exe</OutputType>");
+        sb.AppendLine(isApp ? "    <OutputType>Exe</OutputType>" : "    <OutputType>Library</OutputType>");
         sb.AppendLine("    <Nullable>enable</Nullable>");
         sb.AppendLine("    <LangVersion>latest</LangVersion>");
-        sb.AppendLine("    <PublishAot>false</PublishAot>");
+        sb.AppendLine(isApp ? "    <PublishAot>false</PublishAot>" : "    <ImplicitUsings>disable</ImplicitUsings>");
         sb.AppendLine("  </PropertyGroup>");
-        AppendProjectReferences(sb, libraryProjects);
-        sb.AppendLine("</Project>");
-        return sb.ToString();
-    }
 
-    private static void AppendProjectReferences(StringBuilder sb, List<ProjectInfo> libraryProjects)
-    {
-        if (libraryProjects.Count == 0)
+        if (refSet.ProjectReferences.Count > 0 || refSet.PackageReferences.Count > 0)
         {
-            return;
-        }
+            sb.AppendLine("  <ItemGroup>");
+            foreach (var proj in refSet.ProjectReferences)
+            {
+                sb.AppendLine($"    <ProjectReference Include=\"{proj.Path}\" />");
+            }
 
-        sb.AppendLine("  <ItemGroup>");
-        foreach (var proj in libraryProjects)
-        {
-            sb.AppendLine($"    <ProjectReference Include=\"{proj.Path}\" />");
+            foreach (var (id, version) in refSet.PackageReferences)
+            {
+                sb.AppendLine($"    <PackageReference Include=\"{id}\" Version=\"{version}\" />");
+            }
+
+            sb.AppendLine("  </ItemGroup>");
         }
 
-        sb.AppendLine("  </ItemGroup>");
+        sb.AppendLine("</Project>");
+        return sb.ToString();
     }
 
-    private static (bool Ok, string Diagnostics, int ExitCode) CompileWithWorker(
-        SampleWorkerInfo worker, SampleFence sample, string configuration, bool hasStrongNameKey)
+    private static (bool Ok, string Diagnostics, int ExitCode) CompileSampleInGroup(
+        SampleGroupWorker worker, SampleFence sample, string configuration, bool hasStrongNameKey)
     {
         var signingProperty = hasStrongNameKey ? string.Empty : " -p:SkipSignAssembly=true";
+        var noRestoreFlag = worker.RestoreOk ? " --no-restore" : string.Empty;
+        var sourceName = worker.IsApp ? "Program.cs" : "Sample.cs";
+        File.WriteAllText(Path.Combine(worker.Directory, sourceName), sample.Code, new UTF8Encoding(false));
+        var result = RunProcess("dotnet",
+            $"build \"{worker.ProjectPath}\" -c {configuration}{noRestoreFlag} --nologo{signingProperty}",
+            worker.Directory, permission: ProcessPermission.SampleCompile);
+        return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
+    }
 
-        if (IsProgramCsExample(sample.Code))
+    private static void WritePhase(Options options, Report report, string name, TimeSpan elapsed, string? detail = null)
+    {
+        report.Summary.Phases.Add(new PhaseTiming(name, Math.Round(elapsed.TotalSeconds, 2), detail));
+        if (!options.Json)
         {
-            // Top-level statement sample: write to Program.cs and build the app project.
-            var noRestoreFlag = worker.AppRestoreSucceeded ? " --no-restore" : string.Empty;
-            File.WriteAllText(Path.Combine(worker.AppDirectory, "Program.cs"), sample.Code, new UTF8Encoding(false));
-            var result = RunProcess("dotnet",
-                $"build \"{worker.AppProjectPath}\" -c {configuration}{noRestoreFlag} --nologo{signingProperty}",
-                worker.AppDirectory);
-            return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
+            var suffix = string.IsNullOrEmpty(detail) ? string.Empty : $" {detail}";
+            Console.WriteLine($"  [phase] {name}: {elapsed.TotalSeconds:F2}s{suffix}");
         }
-
-        // Class-based sample: write to Sample.cs and build the library project.
-        var libNoRestoreFlag = worker.LibRestoreSucceeded ? " --no-restore" : string.Empty;
-        File.WriteAllText(Path.Combine(worker.LibDirectory, "Sample.cs"), sample.Code, new UTF8Encoding(false));
-        var libResult = RunProcess("dotnet",
-            $"build \"{worker.LibProjectPath}\" -c {configuration}{libNoRestoreFlag} --nologo{signingProperty}",
-            worker.LibDirectory);
-        return (libResult.ExitCode == 0, libResult.StdOut + libResult.StdErr, libResult.ExitCode);
     }
 
-    private static void WritePhase(Options options, string name, TimeSpan elapsed)
+    private static void WriteSkippedPhase(Options options, Report report, string name, string reason)
     {
+        report.Summary.Phases.Add(new PhaseTiming(name, 0, reason));
         if (!options.Json)
         {
-            Console.WriteLine($"  [phase] {name}: {elapsed.TotalSeconds:F2}s");
+            Console.WriteLine($"  [phase] {name}: skipped ({reason})");
         }
     }
 
@@ -2904,7 +3881,6 @@ private static void WritePhaseStart(Options options, string name, int workers, i
 
     private static List<SampleFence> ExtractFences(string mdFile)
     {
-        var fences = new List<SampleFence>();
         string[] lines;
         try
         {
@@ -2912,9 +3888,21 @@ private static List<SampleFence> ExtractFences(string mdFile)
         }
         catch
         {
-            return fences;
+            return new List<SampleFence>();
         }
 
+        return ExtractFencesFromLines(mdFile, lines);
+    }
+
+    private static List<SampleFence> ExtractFences(string mdFile, string text)
+    {
+        var lines = text.Replace("\r\n", "\n").Replace("\r", "\n").Split('\n');
+        return ExtractFencesFromLines(mdFile, lines);
+    }
+
+    private static List<SampleFence> ExtractFencesFromLines(string mdFile, string[] lines)
+    {
+        var fences = new List<SampleFence>();
         int fenceIndex = 0;
         for (int i = 0; i < lines.Length; i++)
         {
@@ -2948,13 +3936,23 @@ private static List<SampleFence> ExtractFences(string mdFile)
 
     private static List<OverwriteSection> ExtractOverwriteSections(string mdFile)
     {
-        var sections = new List<OverwriteSection>();
         string text;
         try
         {
             text = File.ReadAllText(mdFile);
         }
         catch
+        {
+            return new List<OverwriteSection>();
+        }
+
+        return ExtractOverwriteSections(mdFile, text);
+    }
+
+    private static List<OverwriteSection> ExtractOverwriteSections(string mdFile, string text)
+    {
+        var sections = new List<OverwriteSection>();
+        if (string.IsNullOrEmpty(text))
         {
             return sections;
         }
@@ -3155,13 +4153,13 @@ private static bool IsInsufficientSkipReason(string reason)
 
     private static HashSet<string>? GetChangedFiles(string repoRoot, Report report)
     {
-        var result = RunProcess("git", "rev-parse --verify HEAD", repoRoot);
+        var result = RunProcess("git", "rev-parse --verify HEAD", repoRoot, permission: ProcessPermission.Git);
         if (result.ExitCode != 0)
         {
             return null;
         }
 
-        var diff = RunProcess("git", "diff --name-only --diff-filter=ACMRTUXB HEAD", repoRoot);
+        var diff = RunProcess("git", "diff --name-only --diff-filter=ACMRTUXB HEAD", repoRoot, permission: ProcessPermission.Git);
         if (diff.ExitCode != 0)
         {
             return null;
@@ -3175,7 +4173,7 @@ private static bool IsInsufficientSkipReason(string reason)
 
         // Include untracked files so --changed-only still validates samples in new
         // documentation files that have not been staged yet.
-        var untracked = RunProcess("git", "ls-files --others --exclude-standard", repoRoot);
+        var untracked = RunProcess("git", "ls-files --others --exclude-standard", repoRoot, permission: ProcessPermission.Git);
         if (untracked.ExitCode == 0)
         {
             foreach (var line in untracked.StdOut.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
@@ -3211,7 +4209,8 @@ private static void SearchGitHubForExamples(List<string> packageIds, Report repo
             var result = RunProcess(
                 "gh",
                 $"search code \"{packageId}\" --language C# --limit 5 --json path,repository",
-                Directory.GetCurrentDirectory());
+                Directory.GetCurrentDirectory(),
+                permission: ProcessPermission.GitHubSearch);
 
             if (result.ExitCode != 0 || string.IsNullOrWhiteSpace(result.StdOut))
             {
@@ -3302,9 +4301,83 @@ private static (string FrontMatter, string Body) SplitFrontMatter(string text)
     // Process + output helpers
     // ----------------------------------------------------------------------
 
+    private static void ConfigureProcessGuard(Options options)
+    {
+        var allowed = new HashSet<ProcessPermission> { ProcessPermission.Git };
+        if (options.BuildApiModel)
+        {
+            allowed.Add(ProcessPermission.BuildApiModel);
+        }
+
+        if (options.ValidateSamples)
+        {
+            allowed.Add(ProcessPermission.SampleCompile);
+        }
+
+        if (options.VerifyDocfxBuild)
+        {
+            allowed.Add(ProcessPermission.DocfxBuild);
+        }
+
+        if (options.SearchExamples)
+        {
+            allowed.Add(ProcessPermission.GitHubSearch);
+        }
+
+        lock (ProcessGuardLock)
+        {
+            _allowedPermissions = allowed;
+            foreach (var key in ProcessCounts.Keys.ToList())
+            {
+                ProcessCounts[key] = 0;
+            }
+        }
+    }
+
+    private static Dictionary<string, int> SnapshotProcessCounts()
+    {
+        lock (ProcessGuardLock)
+        {
+            return new Dictionary<string, int>(ProcessCounts, StringComparer.OrdinalIgnoreCase);
+        }
+    }
+
+    private static string NormalizeProcessKey(string fileName)
+    {
+        var name = Path.GetFileNameWithoutExtension(fileName);
+        return string.IsNullOrWhiteSpace(name) ? fileName : name.ToLowerInvariant();
+    }
+
+    private static string DescribePermissionOption(ProcessPermission permission) => permission switch
+    {
+        ProcessPermission.BuildApiModel => "--build-api-model",
+        ProcessPermission.SampleCompile => "--validate-samples",
+        ProcessPermission.DocfxBuild => "--verify-docfx-build",
+        ProcessPermission.GitHubSearch => "--search-examples",
+        _ => "an explicit build option"
+    };
+
     private static ProcessResult RunProcess(string fileName, string arguments, string workingDirectory,
-        IReadOnlyDictionary<string, string>? environment = null)
+        IReadOnlyDictionary<string, string>? environment = null,
+        ProcessPermission permission = ProcessPermission.NoBuild)
     {
+        // Process guard: count every external process and refuse to launch build/doc/network
+        // tooling unless the active options explicitly authorize the corresponding permission.
+        // This keeps the default fast path honest — it can never silently shell out to a build.
+        lock (ProcessGuardLock)
+        {
+            var key = NormalizeProcessKey(fileName);
+            ProcessCounts[key] = ProcessCounts.TryGetValue(key, out var current) ? current + 1 : 1;
+
+            if (!_allowedPermissions.Contains(permission))
+            {
+                throw new InvalidOperationException(
+                    $"Process '{fileName}' was blocked by the no-build guard (permission '{permission}'). " +
+                    $"The fast Markdown/API-overwrite validation path must not run dotnet, msbuild, docfx, or gh. " +
+                    $"Enable the matching option ({DescribePermissionOption(permission)}) to allow it.");
+            }
+        }
+
         var psi = new ProcessStartInfo
         {
             FileName = fileName,
@@ -3407,6 +4480,18 @@ private static int Emit(Options options, Report report, ExitCode code, string co
         report.Summary.Errors = report.Errors.Count;
         report.Summary.Warnings = report.Warnings.Count;
 
+        // Capture the process tally on every exit path so the result always proves whether the
+        // fast path actually shelled out to dotnet/msbuild/docfx/gh.
+        var processCounts = SnapshotProcessCounts();
+        report.Summary.Processes = new Dictionary<string, int>
+        {
+            ["dotnet"] = processCounts.GetValueOrDefault("dotnet"),
+            ["msbuild"] = processCounts.GetValueOrDefault("msbuild"),
+            ["docfx"] = processCounts.GetValueOrDefault("docfx"),
+            ["gh"] = processCounts.GetValueOrDefault("gh"),
+            ["git"] = processCounts.GetValueOrDefault("git")
+        };
+
         if (options.Json)
         {
             Console.WriteLine(JsonSerializer.Serialize(report, JsonOptions));
@@ -3425,12 +4510,17 @@ private static int Emit(Options options, Report report, ExitCode code, string co
             }
 
             Console.WriteLine(
-                $"  Summary: namespaces={report.Summary.PublicNamespaces}, pages={report.Summary.NamespacePagesValidated}, " +
+                $"  Summary: mode={report.Summary.ValidationMode}, apiModel={report.Summary.ApiModelSource ?? "n/a"}, " +
+                $"namespaces={report.Summary.PublicNamespaces}, pages={report.Summary.NamespacePagesValidated}, " +
                 $"requiredExampleTargets={report.Summary.RequiredExampleTargets}, requiredExamples={report.Summary.RequiredExamples}, " +
                 $"extMethods={report.Summary.ExtensionMethods}, samplesCompiled={report.Summary.SamplesCompiled}, " +
                 $"samplesSkipped={report.Summary.SamplesSkipped}, generatedMetadataRemoved={report.Summary.GeneratedMetadataFilesRemoved}, " +
                 $"generatedOutputDirectoriesRemoved={report.Summary.GeneratedOutputDirectoriesRemoved}, " +
                 $"docfxBuildsVerified={report.Summary.DocfxBuildsVerified}, errors={report.Summary.Errors}, warnings={report.Summary.Warnings}");
+
+            Console.WriteLine(
+                $"  [processes] dotnet={report.Summary.Processes["dotnet"]} msbuild={report.Summary.Processes["msbuild"]} " +
+                $"docfx={report.Summary.Processes["docfx"]} gh={report.Summary.Processes["gh"]}");
         }
 
         return (int)code;
@@ -3716,6 +4806,15 @@ private static bool TryParse(string[] args, out Options options, out string erro
                 case "--search-examples":
                     options.SearchExamples = true;
                     break;
+                case "--build-api-model":
+                case "--strict-api-discovery":
+                    options.BuildApiModel = true;
+                    break;
+                case "--sample-reference-mode":
+                    if (!Next(args, ref i, out var srm)) { error = "--sample-reference-mode requires 'project' or 'package'."; return false; }
+                    if (!IsValidSampleReferenceMode(srm)) { error = "--sample-reference-mode must be 'project' or 'package'."; return false; }
+                    options.SampleReferenceMode = srm.ToLowerInvariant();
+                    break;
                 case "--sample-parallelism":
                     if (!Next(args, ref i, out var sp)) { error = "--sample-parallelism requires a count."; return false; }
                     if (!int.TryParse(sp, out var spv) || spv < 1) { error = "--sample-parallelism must be a positive integer."; return false; }
@@ -3736,6 +4835,12 @@ private static bool TryParse(string[] args, out Options options, out string erro
                     if (TrySplit(arg, "--configuration", out var v3)) { options.Configuration = v3; break; }
                     if (TrySplit(arg, "--framework", out var v4)) { options.Framework = v4; break; }
                     if (TrySplit(arg, "--repair-plan", out var v5)) { options.RepairPlanPath = v5; break; }
+                    if (TrySplit(arg, "--sample-reference-mode", out var v7))
+                    {
+                        if (!IsValidSampleReferenceMode(v7)) { error = "--sample-reference-mode must be 'project' or 'package'."; return false; }
+                        options.SampleReferenceMode = v7.ToLowerInvariant();
+                        break;
+                    }
                     if (TrySplit(arg, "--sample-parallelism", out var v6) &&
                         int.TryParse(v6, out var spvInline) && spvInline >= 1)
                     {
@@ -3751,6 +4856,10 @@ private static bool TryParse(string[] args, out Options options, out string erro
         return true;
     }
 
+    private static bool IsValidSampleReferenceMode(string value) =>
+        string.Equals(value, "project", StringComparison.OrdinalIgnoreCase) ||
+        string.Equals(value, "package", StringComparison.OrdinalIgnoreCase);
+
     private static bool Next(string[] args, ref int i, out string value)
     {
         if (i + 1 >= args.Length)
@@ -3782,28 +4891,48 @@ private static void PrintUsage()
             $"""
             {ScriptId} - validate DocFX documentation for .NET public APIs.
 
+            By default this performs FAST, no-build validation of Markdown, prose, and DocFX
+            API-overwrite layout. The default path never runs dotnet, msbuild, docfx, or gh; it
+            reads existing DocFX YAML metadata when present and otherwise scans source for a
+            conservative API model. Compilation and network access are strictly opt-in.
+
             Usage:
               dotnet run --file docfx.cs -- [options]
 
+            Modes (opt-in, each enables exactly one class of external process):
+              (default)                Fast Markdown/overwrite/API-overwrite validation. No build.
+              --validate-samples       Compile generated C# documentation samples (dotnet). The only
+                                      default-supported path that compiles samples. Each sample group
+                                      references only the documented project(s) that own its namespace.
+              --build-api-model        Reflection-backed API discovery from compiled assemblies. Builds
+                                      only the documented project graph (dotnet). Alias: --strict-api-discovery.
+              --verify-docfx-build     Run DocFX against a temp copy of the repository (docfx).
+              --search-examples        Run GitHub code search per documented package (gh). Use with --repair-plan.
+
             Options:
               --repo-root <path>       Repository root. Default: current directory.
               --docfx <path>           Path to docfx.json. Default: .docfx/docfx.json under repo root.
-              --configuration <name>   Build configuration. Default: Release.
+              --configuration <name>   Build configuration (only used by build/sample paths). Default: Release.
               --framework <tfm>        Optional target framework to validate against.
-              --validate-samples       Compile C# samples. Default: enabled.
-              --no-validate-samples    Skip C# sample compilation.
-              --sample-parallelism <n> Number of parallel sample-validation workers (1-8). Default: 2.
-                                       Override with env var DOCFX_DIGEST_SAMPLE_PARALLELISM.
-              --changed-only           Validate only files changed according to git.
-              --verify-docfx-build     Run DocFX against a temp copy of the repository so generated output stays outside the working tree.
+              --validate-samples       Compile C# samples (opt-in). Default: disabled.
+              --no-validate-samples    Explicitly disable sample compilation (already the default).
+              --sample-reference-mode <project|package>
+                                      Sample reference resolution. project (default) references the owning
+                                      documented project(s); package references NuGet package ids where available.
+              --sample-parallelism <n> Number of parallel sample-validation groups (1-8). Default: 2.
+                                      Override with env var DOCFX_DIGEST_SAMPLE_PARALLELISM.
+              --build-api-model        Reflection-backed API discovery (opt-in). Default: no-build discovery.
+              --changed-only           Validate only files changed according to git (git is read-only and allowed).
+              --verify-docfx-build     Run DocFX against a temp copy of the repository (opt-in).
               --repair-plan <path>     Write a deterministic Markdown repair plan from validation diagnostics.
               --search-examples        Run GitHub code search for each documented package and embed real usage snippets in the
-                                       repair plan. Requires the gh CLI to be authenticated. Use together with --repair-plan.
+                                      repair plan. Requires the gh CLI to be authenticated. Use together with --repair-plan.
               --clean-generated-metadata
-                                      Remove DocFX-generated *.yml and manifest files under metadata.dest. Default: enabled.
+                                      Remove DocFX-generated *.yml and manifest files under metadata.dest (opt-in).
+                                      Runs only after the API model is built, so it never deletes YAML the fast path used.
               --no-clean-generated-metadata
-                                      Leave DocFX-generated metadata files untouched.
-              --json                   Emit a machine-readable JSON summary.
+                                      Leave DocFX-generated metadata files untouched (already the default).
+              --json                   Emit a machine-readable JSON summary (includes processes + phase timings).
               --help                   Print this usage.
 
             Exit codes:
@@ -3812,9 +4941,9 @@ 1  Validation failed.
               2  Invalid arguments.
               3  Repository root does not exist.
               4  DocFX configuration file not found.
-              5  Build failed.
-              6  Public API discovery failed.
-              7  Sample compilation failed.
+              5  Build failed (only reachable with --build-api-model).
+              6  Public API discovery failed (only reachable with --build-api-model).
+              7  Sample compilation failed (only reachable with --validate-samples).
               8  Unexpected internal error.
             """);
     }
@@ -3839,14 +4968,16 @@ private sealed class Options
         public string Configuration { get; set; } = "Release";
         public string? Framework { get; set; }
         public string? RepairPlanPath { get; set; }
-        public bool ValidateSamples { get; set; } = true;
+        public bool ValidateSamples { get; set; }
         public bool ChangedOnly { get; set; }
         public bool VerifyDocfxBuild { get; set; }
         public bool SearchExamples { get; set; }
-        public bool CleanGeneratedMetadata { get; set; } = true;
+        public bool BuildApiModel { get; set; }
+        public bool CleanGeneratedMetadata { get; set; }
         public bool Json { get; set; }
         public bool Help { get; set; }
         public int? SampleParallelism { get; set; }
+        public string SampleReferenceMode { get; set; } = "project";
     }
 
     private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest, string? PackageId = null);
@@ -3861,6 +4992,29 @@ private enum ApiTargetKind
         ExtensionMethod
     }
 
+    private enum ProcessPermission
+    {
+        NoBuild,
+        Git,
+        BuildApiModel,
+        SampleCompile,
+        DocfxBuild,
+        GitHubSearch
+    }
+
+    private enum ValidationMode
+    {
+        FastMarkdown,
+        BuildBackedApiModel
+    }
+
+    private enum ApiModelSource
+    {
+        DocfxYaml,
+        SourceScan,
+        BuildBacked
+    }
+
     private sealed class NamespaceInfo(string name)
     {
         public string Name { get; } = name;
@@ -3871,19 +5025,61 @@ private sealed class NamespaceInfo(string name)
 
     private sealed record ApiModel(List<NamespaceInfo> Namespaces, List<ApiTargetInfo> RequiredExampleTargets);
 
+    /// <summary>
+    /// Per-run cache of repository and documentation inputs. Built once so callers never
+    /// re-parse <c>docfx.json</c>, re-enumerate Markdown, re-read Markdown, re-extract overwrite
+    /// sections, or re-scan project files. The namespace-to-project map is filled by whichever
+    /// API-model discovery runs and is used to scope sample compilation.
+    /// </summary>
+    private sealed class ValidationWorkspace
+    {
+        public required string RepoRoot { get; init; }
+        public required string DocfxPath { get; init; }
+        public required string DocfxWorkspace { get; init; }
+        public required List<ProjectInfo> Projects { get; init; }
+        public required List<ProjectInfo> LibraryProjects { get; init; }
+        public required List<string> MarkdownFiles { get; init; }
+        public required Dictionary<string, string> MarkdownTextByPath { get; init; }
+        public required List<OverwriteSection> OverwriteSections { get; init; }
+        public Dictionary<string, List<ProjectInfo>> NamespaceProjects { get; } =
+            new(StringComparer.Ordinal);
+
+        public string ReadMarkdown(string path)
+        {
+            var full = Path.GetFullPath(path);
+            if (MarkdownTextByPath.TryGetValue(full, out var cached))
+            {
+                return cached;
+            }
+
+            try
+            {
+                cached = File.ReadAllText(full);
+            }
+            catch
+            {
+                cached = string.Empty;
+            }
+
+            MarkdownTextByPath[full] = cached;
+            return cached;
+        }
+    }
+
     private sealed record SampleFence(string File, int FenceIndex, int StartLine, string Code);
 
     private sealed record OverwriteSection(string File, string Uid, string Body, bool MappedToExample = false);
 
     private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
 
-    private sealed record SampleWorkerInfo(
-        string LibDirectory,
-        string AppDirectory,
-        string LibProjectPath,
-        string AppProjectPath,
-        bool LibRestoreSucceeded,
-        bool AppRestoreSucceeded);
+    private sealed record SampleGroupWorker(string Directory, string ProjectPath, bool IsApp, bool RestoreOk);
+
+    private sealed record SampleReferenceSet(
+        string Kind,
+        bool IsPackageMode,
+        List<string> Items,
+        List<ProjectInfo> ProjectReferences,
+        List<(string Id, string Version)> PackageReferences);
 
     private sealed record SampleCompileResult(bool Ok, string Diagnostics, int ExitCode);
 }
@@ -3906,6 +5102,8 @@ public Diagnostic(string code, string? path, string? @namespace, string message)
 
 internal sealed class Summary
 {
+    public string? ValidationMode { get; set; }
+    public string? ApiModelSource { get; set; }
     public int PublicNamespaces { get; set; }
     public int NamespacePagesValidated { get; set; }
     public int RequiredExampleTargets { get; set; }
@@ -3918,6 +5116,22 @@ internal sealed class Summary
     public int DocfxBuildsVerified { get; set; }
     public int Errors { get; set; }
     public int Warnings { get; set; }
+    public Dictionary<string, int> Processes { get; set; } = new();
+    public List<PhaseTiming> Phases { get; set; } = new();
+}
+
+internal sealed class PhaseTiming
+{
+    public PhaseTiming(string name, double seconds, string? detail = null)
+    {
+        Name = name;
+        Seconds = seconds;
+        Detail = detail;
+    }
+
+    [JsonPropertyName("name")] public string Name { get; }
+    [JsonPropertyName("seconds")] public double Seconds { get; }
+    [JsonPropertyName("detail")] public string? Detail { get; }
 }
 
 internal sealed class Report

From 79e6665070cfa57ea2967a25dca8dfff88f272a2 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sat, 13 Jun 2026 02:17:25 +0200
Subject: [PATCH 57/88] =?UTF-8?q?=F0=9F=92=AC=20clarify=20docfx-digest=20i?=
 =?UTF-8?q?s=20fast=20by=20default=20with=20opt-in=20build/network=20opera?=
 =?UTF-8?q?tions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update the skill description and capability list in README to emphasize that docfx.cs runs fast without invoking dotnet, msbuild, docfx, or gh by default. Compilation and network access are strictly opt-in via --validate-samples, --build-api-model, --verify-docfx-build, and --search-examples. Update the DocFX completion-gate guidance to reference the build-backed verification flags that make the final gate authoritative.
---
 README.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 2f3c9b5..1c5536e 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ One more consistency rule matters for form-driven skills: native input fields ar
 
 Repo-level agent guidance also keeps progress updates user-facing: agents should report meaningful progress, evidence, blockers, and next steps without narrating sandbox mechanics, approved command paths, or retry plumbing unless those details affect approval, reproducibility, validation, or the final outcome.
 
-Completion gates are equally strict: if repository guidance, a loaded skill, or the conversation summary marks a script-backed step as pending, critical, or blocking, agents must treat it as an active checklist item and may not claim completion until that command has run or the exact blocker has been reported. In the DocFX workflow, that means `scripts/agents.cs` and `scripts/docfx.cs --verify-docfx-build` are completion gates, not optional cleanup after the documentation files look done.
+Completion gates are equally strict: if repository guidance, a loaded skill, or the conversation summary marks a script-backed step as pending, critical, or blocking, agents must treat it as an active checklist item and may not claim completion until that command has run or the exact blocker has been reported. In the DocFX workflow, that means `scripts/agents.cs` and the build-backed `scripts/docfx.cs --build-api-model --validate-samples --verify-docfx-build` verification are completion gates, not optional cleanup after the documentation files look done. (The plain `scripts/docfx.cs` run is fast and build-free for iteration; the build-backed flags are what make the final gate authoritative.)
 
 Validation follows the same philosophy: run `scripts/validate-skill-templates.ps1` locally for the fast feedback loop, and let GitHub Actions rerun that same script on pull requests as the safety net. That validator also checks skill frontmatter metadata such as per-skill `evals/evals.json` files, optional eval fixture paths declared through `files`, and the 1024-character YAML description limit; it does not replace the paired benchmark review workflow.
 
@@ -99,7 +99,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` builds the solution, honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, discovers public API, namespaces, and extension methods from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace overview pages (uid front matter, concept-led fly-ins that explain the problem solved, when to use the namespace, and where to start, availability), `Extension Members` tables, purpose-first type/member summaries, required per-type overwrite examples, Codebelt namespace-folder overwrite layout (`.docfx/api/namespaces/**/*.md` under `build.overwrite` only), and C# documentation samples, keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown so new samples compile before staging, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, and can run the DocFX CLI in a temp copy with `--verify-docfx-build` so generated API YAML, manifests, and configured site output stay out of git status. Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed or exact blockers are reported, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles C# samples (grouping each sample so it references only the documented project that owns its namespace), `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns the fast `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -536,20 +536,21 @@ API documentation rots the moment code changes. A new public type ships without
 **dotnet-docfx-digest** moves the rules from prose into deterministic .NET 10 tooling, so guidance persists and verification is real.
 
 - **No-input audits by default** — `Use dotnet-docfx-digest` means inspect the repository, DocFX config, public API, tests, samples, overwrite files, namespace pages, and availability includes, then repair missing complementary documentation that can be derived from evidence before asking any clarifying questions,
+- **Fast by default, builds only on demand** — a plain `scripts/docfx.cs` run validates Markdown, prose, DocFX overwrite layout, namespace pages, extension tables, and required examples **without invoking `dotnet`, `msbuild`, `docfx`, or `gh`**, discovering the public API from existing DocFX YAML metadata or a conservative source scan and proving it with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings on every run. Five clearly separated paths layer on cost only when asked: fast Markdown validation (default), `--validate-samples` for C# sample compilation, `--build-api-model` for reflection-backed API discovery, `--verify-docfx-build` for the DocFX build, and `--search-examples` for GitHub usage search,
 - **Persistent guidance by script, not memory** — `scripts/agents.cs` is resolved from the loaded skill directory, with a repo-managed source fallback when present, then writes an idempotent, marker-bounded DocFX maintenance block into the target repository `AGENTS.md`; running it twice never duplicates the block, and `--check` gates it in CI,
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
-- **Verification from compiled metadata** — `scripts/docfx.cs` builds the solution and discovers public API, namespaces, and extension methods from compiled assemblies (preferring reference assemblies) via `MetadataLoadContext`, resolving NuGet package dependencies, deps files, and installed .NET framework reference packs instead of guessing from text,
+- **Verification without a build, precision on demand** — by default `scripts/docfx.cs` discovers public API, namespaces, and extension methods without compiling: it reads existing DocFX ManagedReference YAML under `metadata.dest` when present, otherwise runs a conservative source scan over the projects referenced by `docfx.json`, and warns (`API_MODEL_SOURCE_SCANNER_LIMITED`) that the precise path is opt-in. Adding `--build-api-model` (alias `--strict-api-discovery`) builds only the documented project graph through a single scoped `.slnx` graph build and discovers from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution,
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
 - **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/namespaces/`, legacy authored `.docfx/api/*.md` overwrite files are moved into that folder instead of widening the glob to `api/**/*.md`, `api/namespaces/**/*.md` stays under `build.overwrite` only while `build.content` excludes `api/namespaces/**`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
 - **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
 - **Examples that teach a real workflow** — examples start from package IDs and package-level evidence before falling back to type/member-only searches, prefer README, package docs, tooling, tuning, functional-test, and external GitHub usage when available, and may include multiple related public types when that is what makes the consumer scenario understandable,
-- **Examples that actually compile** — every `csharp`/`cs` documentation fence is compiled as a file-based app referencing the real library projects; failures report the file, fence index, line, exit code, and compiler diagnostics,
+- **Examples that actually compile** — under the opt-in `--validate-samples` path, every `csharp`/`cs` documentation fence is compiled; samples are grouped by dependency set so each references only the documented project(s) that own its namespace rather than every library project, and failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
 - **Preserves manual edits** — additive by default, correcting stale or contradictory statements rather than overwriting hand-written documentation,
-- **Cleanup keeps authored docs** — `.docfx/**/*.md` overwrite files, namespace pages, includes, and config are documentation outputs, not disposable build artifacts; generated cleanup is limited to known metadata files and safe site-output directories that contain no authored documentation or source files,
+- **Cleanup keeps authored docs and is opt-in** — generated-metadata cleanup runs only when `--clean-generated-metadata` is explicitly passed, and even then only after the API model is built so it never deletes YAML the run relied on; `.docfx/**/*.md` overwrite files, namespace pages, includes, and config are documentation outputs, not disposable build artifacts, and cleanup is limited to known metadata files and safe site-output directories that contain no authored documentation or source files,
 - **CI-friendly** — deterministic exit codes plus `--json` reports let pipelines fail on actual documentation drift instead of trusting an agent's claim that it checked.
 
 ## Repository structure

From 04d2ae8d3798bd5f0117ba524da31862a216e18e Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sat, 13 Jun 2026 13:48:08 +0200
Subject: [PATCH 58/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20sample=20?=
 =?UTF-8?q?compilation=20to=20isolated=20projects=20in=20one=20graph=20bui?=
 =?UTF-8?q?ld?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace per-dependency-set grouping with isolated projects per sample, batching all sample projects into one temporary .slnx graph build. Shared dependencies now restore and build once while --sample-parallelism bounds MSBuild concurrency. Isolation preserves per-sample compiler diagnostics without one process per fence. Update docfx.cs implementation, add eval test case 52 for the new strategy, and clarify SKILL.md and references/scripts.md documentation. Removes SAMPLE_WORKER_RESTORE_FAILED from error codes as the new batched strategy no longer has per-sample workers.
---
 skills/dotnet-docfx-digest/SKILL.md           |   2 +-
 skills/dotnet-docfx-digest/evals/evals.json   |  13 ++
 .../dotnet-docfx-digest/references/scripts.md |   6 +-
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 145 ++++++++++--------
 4 files changed, 94 insertions(+), 72 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index fb54a7e..e021e27 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -28,7 +28,7 @@ dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-ro
 dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --build-api-model --validate-samples --verify-docfx-build
 ```
 
-- `--build-api-model` makes API discovery reflection-precise (the fast source-scan path is conservative and may under-report), `--validate-samples` compiles every C# documentation sample, and `--verify-docfx-build` confirms the DocFX build succeeds. Treat `API_MODEL_SOURCE_SCANNER_LIMITED` in a fast run as a reminder to run the build-backed verification before completion, not as a failure.
+- `--build-api-model` makes API discovery reflection-precise (the fast source-scan path is conservative and may under-report), `--validate-samples` compiles every C# documentation sample through isolated projects in one temporary `.slnx` graph build with bounded MSBuild parallelism, and `--verify-docfx-build` confirms the DocFX build succeeds. Treat `API_MODEL_SOURCE_SCANNER_LIMITED` in a fast run as a reminder to run the build-backed verification before completion, not as a failure.
 - For noisy audits, write and read a deterministic `--repair-plan` (works on the fast path; add `--search-examples` to embed real GitHub usage):
 
 ```bash
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 661381b..597ced0 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -636,6 +636,19 @@
         "Keeps every changed csharp example structurally valid and compile-verified through `docfx.cs`",
         "Updates the example inventory with UID, required file, source evidence, chosen scenario, and final status"
       ]
+    },
+    {
+      "id": 52,
+      "prompt": "Run `scripts/docfx.cs --validate-samples --json` on a repository with at least 20 C# documentation fences spread across three dependency sets. Confirm that every sample remains compilation-isolated, but validation no longer launches one restore and one build per sample.",
+      "expected_output": "The validator creates one temporary project per sample, adds all sample projects to one temporary `.slnx`, and performs one bounded-parallel graph build. JSON reports all compile-passing samples, `summary.processes.dotnet` is 1 for sample-only validation, and the sample-validation phase detail reports one batch plus the sample and reference-set counts. A failing sample still produces SAMPLE_COMPILE_FAILED for its original Markdown file and fence without contaminating other sample results.",
+      "expectations": [
+        "Creates a separate temporary project for every compilable C# documentation fence",
+        "Builds all temporary sample projects through one `.slnx` graph build instead of one dotnet build per sample",
+        "Uses `--sample-parallelism` or `DOCFX_DIGEST_SAMPLE_PARALLELISM` as the bounded MSBuild maximum node count",
+        "Reports `summary.processes.dotnet` as 1 when `--validate-samples` is the only build-backed option",
+        "Preserves per-sample SAMPLE_COMPILE_FAILED diagnostics with the original Markdown file and fence index",
+        "Reports sample-validation phase detail containing `1 batch` and the sample count"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index cb3d5be..e842826 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -50,7 +50,7 @@ The public API model the fast path validates against is discovered without build
 
 Compilation and network access are strictly opt-in, and each option enables exactly one class of external process:
 
-- `--validate-samples` compiles the generated C# documentation samples (`dotnet`). This is the only default-supported path that compiles samples. Samples are grouped by their resolved dependency set so each group references only the documented project(s) that own the sample's namespace (and their transitive references resolved by MSBuild), never every documented library project. Each group restores once and builds each sample with `--no-restore`.
+- `--validate-samples` compiles the generated C# documentation samples (`dotnet`). This is the only default-supported path that compiles samples. Every sample gets an isolated project with only the documented project(s) that own its namespace (and their transitive references resolved by MSBuild), never every documented library project. The validator writes those projects into one temporary `.slnx` and launches one graph build, so shared dependencies restore and build once while `--sample-parallelism` bounds MSBuild concurrency. Isolation preserves per-sample compiler diagnostics without paying for one `dotnet build` process per fence.
 - `--build-api-model` (alias `--strict-api-discovery`) performs reflection-backed API discovery from compiled assemblies (`dotnet`). It builds only the documented project graph through a single temporary `.slnx` graph build rather than N per-project builds, then loads metadata through `System.Reflection.MetadataLoadContext`. Use it when conservative no-build discovery is not enough.
 - `--verify-docfx-build` runs DocFX against a temp copy of the repository (`docfx`).
 - `--search-examples` runs GitHub code search per documented package (`gh`).
@@ -70,7 +70,7 @@ dotnet run --file docfx.cs -- --repo-root . --validate-samples --sample-referenc
 dotnet run --file docfx.cs -- --repo-root . --build-api-model --configuration Debug --framework net10.0
 ```
 
-Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only used by build/sample paths), `--framework`, `--validate-samples` / `--no-validate-samples` (default off — opt-in), `--sample-reference-mode <project|package>` (default `project`), `--sample-parallelism <n>` (1-8, default 2; env `DOCFX_DIGEST_SAMPLE_PARALLELISM`), `--build-api-model` / `--strict-api-discovery` (default off — opt-in), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default off — opt-in), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
+Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only used by build/sample paths), `--framework`, `--validate-samples` / `--no-validate-samples` (default off — opt-in), `--sample-reference-mode <project|package>` (default `project`), `--sample-parallelism <n>` (1-8, default 2; env `DOCFX_DIGEST_SAMPLE_PARALLELISM`; passed as the maximum node count for the batched sample graph build), `--build-api-model` / `--strict-api-discovery` (default off — opt-in), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default off — opt-in), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It still does not build by default: Markdown/overwrite-only changes are validated against the no-build API model, and it uses `git` (read-only) to discover changes. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled (under `--validate-samples`) before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
@@ -100,7 +100,7 @@ Exit codes:
 
 Every run records a process tally and per-phase timings. Non-JSON output prints a `[processes] dotnet=… msbuild=… docfx=… gh=…` line and `[phase] <name>: <seconds>s` lines; JSON output exposes the same data under `summary.processes` (an object with `dotnet`, `msbuild`, `docfx`, `gh`, `git` counts) and `summary.phases` (an ordered list of `{ name, seconds, detail }`). `summary.validationMode` is `fast-markdown` or `build-backed-api-model`, and `summary.apiModelSource` is `docfx-yaml`, `source-scan`, or `build-backed`. For a default fast run on any repository, the process counts for `dotnet`, `msbuild`, `docfx`, and `gh` are all `0`.
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `SAMPLE_WORKER_RESTORE_FAILED` when a sample group's one-time restore fails, `ENCODING_BOM_MISSING` when a DocFX API overwrite file is missing a UTF-8 BOM, `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `ENCODING_BOM_MISSING` when a DocFX API overwrite file is missing a UTF-8 BOM, `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
 
 `ENCODING_CORRUPTION` fires when a documentation file contains the byte sequence `C3 A2 C2 AC` — the UTF-8 re-encoding of the `â¬` pair produced by a Windows-1252 round-trip of `U+2B07` (⬇, the Extension Members table arrow). Restore the affected file with `git checkout HEAD -- <file>` if the committed version was correct, or rewrite the content using the edit tool or byte-level operations. Never use `Get-Content` / `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes(Get-Content)` to rewrite documentation files that contain multi-byte characters.
 
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 23236f3..01b99fc 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -3561,7 +3561,7 @@ private static void ValidateSamples(ValidationWorkspace ws, Options options, Has
         var packageMode = string.Equals(options.SampleReferenceMode, "package", StringComparison.OrdinalIgnoreCase);
 
         var groups = new Dictionary<string, List<(SampleFence Sample, int OriginalIndex)>>(StringComparer.Ordinal);
-        var groupRefs = new Dictionary<string, SampleReferenceSet>(StringComparer.Ordinal);
+        var sampleRefs = new Dictionary<int, SampleReferenceSet>();
         foreach (var entry in toCompile)
         {
             var kind = IsProgramCsExample(entry.Sample.Code) ? "app" : "lib";
@@ -3571,10 +3571,10 @@ private static void ValidateSamples(ValidationWorkspace ws, Options options, Has
             {
                 list = new List<(SampleFence, int)>();
                 groups[key] = list;
-                groupRefs[key] = refSet;
             }
 
             list.Add(entry);
+            sampleRefs[entry.OriginalIndex] = refSet;
         }
 
         var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-samples-" + Guid.NewGuid().ToString("N"));
@@ -3582,42 +3582,34 @@ private static void ValidateSamples(ValidationWorkspace ws, Options options, Has
         try
         {
             var parallelism = GetSampleValidationParallelism(options);
-            var workerCount = Math.Min(parallelism, groups.Count);
+            var workerCount = Math.Min(parallelism, toCompile.Count);
             WritePhaseStart(options, "sample validation", workerCount, toCompile.Count);
             phaseTimer.Restart();
 
             // Results are stored in a pre-sized indexed array to guarantee deterministic
-            // diagnostic ordering regardless of group completion order.
+            // diagnostic ordering regardless of MSBuild project completion order.
             var results = new SampleCompileResult?[samples.Count];
-            var orderedGroups = groups.Keys.OrderBy(k => k, StringComparer.Ordinal).ToList();
-            using var throttler = new SemaphoreSlim(Math.Max(1, parallelism));
-            var tasks = new List<Task>();
-            for (var g = 0; g < orderedGroups.Count; g++)
-            {
-                var key = orderedGroups[g];
-                var groupNumber = g + 1;
-                throttler.Wait();
-                tasks.Add(Task.Run(() =>
-                {
-                    try
-                    {
-                        var worker = CreateSampleGroupWorker(tempRoot, groupNumber, groupRefs[key], framework, hasStrongNameKey, report);
-                        foreach (var (sample, originalIndex) in groups[key])
-                        {
-                            var (ok, diags, exitCode) = CompileSampleInGroup(worker, sample, options.Configuration, hasStrongNameKey);
-                            results[originalIndex] = new SampleCompileResult(ok, diags, exitCode);
-                        }
-                    }
-                    finally
-                    {
-                        throttler.Release();
-                    }
-                }));
+            var workers = new List<SampleWorker>(toCompile.Count);
+            for (var i = 0; i < toCompile.Count; i++)
+            {
+                var (sample, originalIndex) = toCompile[i];
+                workers.Add(CreateSampleWorker(tempRoot, i + 1, originalIndex, sample,
+                    sampleRefs[originalIndex], framework));
+            }
+
+            var batchResult = CompileSampleBatch(tempRoot, workers, options.Configuration,
+                parallelism, hasStrongNameKey);
+            foreach (var worker in workers)
+            {
+                var outputAssembly = Path.Combine(worker.Directory, "bin", options.Configuration,
+                    framework, worker.AssemblyName + ".dll");
+                var ok = batchResult.ExitCode == 0 || File.Exists(outputAssembly);
+                var diagnostics = ok ? string.Empty : ExtractSampleDiagnostics(batchResult, worker);
+                results[worker.OriginalIndex] = new SampleCompileResult(ok, diagnostics, batchResult.ExitCode);
             }
 
-            Task.WaitAll(tasks.ToArray());
             WritePhase(options, report, "sample validation", phaseTimer.Elapsed,
-                $"{groups.Count} group(s), {toCompile.Count} sample(s)");
+                $"1 batch, {groups.Count} reference set(s), {toCompile.Count} sample(s), max {parallelism} worker(s)");
 
             // 4. Merge results in original sample order for deterministic diagnostics.
             for (int i = 0; i < samples.Count; i++)
@@ -3773,41 +3765,30 @@ private static int GetSampleValidationParallelism(Options options)
     }
 
     /// <summary>
-    /// Creates a single-kind (lib or app) sample worker for a dependency group under
-    /// <paramref name="tempRoot"/>, referencing only the resolved scoped project/package set,
-    /// and restores it once so subsequent sample builds in the group can use <c>--no-restore</c>.
+    /// Creates an isolated sample project under <paramref name="tempRoot"/> that references only
+    /// the resolved scoped project/package set. All sample projects are later restored and built
+    /// together through one temporary solution graph.
     /// </summary>
-    private static SampleGroupWorker CreateSampleGroupWorker(
-        string tempRoot, int groupNumber, SampleReferenceSet refSet,
-        string framework, bool hasStrongNameKey, Report report)
+    private static SampleWorker CreateSampleWorker(
+        string tempRoot, int sampleNumber, int originalIndex, SampleFence sample,
+        SampleReferenceSet refSet, string framework)
     {
         var isApp = string.Equals(refSet.Kind, "app", StringComparison.Ordinal);
-        var workerDir = Path.Combine(tempRoot, "docfx-sample-workers", $"group-{groupNumber:D4}");
+        var assemblyName = $"DocfxSample{sampleNumber:D4}";
+        var workerDir = Path.Combine(tempRoot, "docfx-sample-workers", assemblyName);
         Directory.CreateDirectory(workerDir);
 
-        var projPath = Path.Combine(workerDir, isApp ? "DocfxSampleApp.csproj" : "DocfxSampleLib.csproj");
-        File.WriteAllText(projPath, GenerateSampleGroupProject(refSet, framework, isApp), new UTF8Encoding(false));
+        var projPath = Path.Combine(workerDir, assemblyName + ".csproj");
+        File.WriteAllText(projPath, GenerateSampleProject(refSet, framework, isApp), new UTF8Encoding(false));
 
         var sourceName = isApp ? "Program.cs" : "Sample.cs";
-        File.WriteAllText(Path.Combine(workerDir, sourceName),
-            isApp ? "// placeholder" : "namespace DocfxSamplePlaceholder { internal static class _Placeholder { } }",
-            new UTF8Encoding(false));
-
-        var signingProperty = hasStrongNameKey ? string.Empty : " -p:SkipSignAssembly=true";
-        var restoreOk = RunProcess("dotnet",
-            $"restore \"{projPath}\" --nologo{signingProperty}", workerDir,
-            permission: ProcessPermission.SampleCompile).ExitCode == 0;
+        var sourcePath = Path.Combine(workerDir, sourceName);
+        File.WriteAllText(sourcePath, sample.Code, new UTF8Encoding(false));
 
-        if (!restoreOk)
-        {
-            report.Warnings.Add(new Diagnostic("SAMPLE_WORKER_RESTORE_FAILED", workerDir, null,
-                $"Sample validation group {groupNumber} restore failed; affected samples will build without --no-restore and may be slower."));
-        }
-
-        return new SampleGroupWorker(workerDir, projPath, isApp, restoreOk);
+        return new SampleWorker(originalIndex, workerDir, projPath, sourcePath, assemblyName);
     }
 
-    private static string GenerateSampleGroupProject(SampleReferenceSet refSet, string framework, bool isApp)
+    private static string GenerateSampleProject(SampleReferenceSet refSet, string framework, bool isApp)
     {
         var sb = new StringBuilder();
         sb.AppendLine("""<Project Sdk="Microsoft.NET.Sdk">""");
@@ -3839,17 +3820,40 @@ private static string GenerateSampleGroupProject(SampleReferenceSet refSet, stri
         return sb.ToString();
     }
 
-    private static (bool Ok, string Diagnostics, int ExitCode) CompileSampleInGroup(
-        SampleGroupWorker worker, SampleFence sample, string configuration, bool hasStrongNameKey)
+    private static ProcessResult CompileSampleBatch(
+        string tempRoot, List<SampleWorker> workers, string configuration, int parallelism,
+        bool hasStrongNameKey)
     {
+        var solutionPath = Path.Combine(tempRoot, "DocfxSamples.slnx");
+        var solution = new StringBuilder();
+        solution.AppendLine("<Solution>");
+        foreach (var worker in workers)
+        {
+            solution.AppendLine($"  <Project Path=\"{worker.ProjectPath}\" />");
+        }
+
+        solution.AppendLine("</Solution>");
+        File.WriteAllText(solutionPath, solution.ToString(), new UTF8Encoding(false));
+
         var signingProperty = hasStrongNameKey ? string.Empty : " -p:SkipSignAssembly=true";
-        var noRestoreFlag = worker.RestoreOk ? " --no-restore" : string.Empty;
-        var sourceName = worker.IsApp ? "Program.cs" : "Sample.cs";
-        File.WriteAllText(Path.Combine(worker.Directory, sourceName), sample.Code, new UTF8Encoding(false));
-        var result = RunProcess("dotnet",
-            $"build \"{worker.ProjectPath}\" -c {configuration}{noRestoreFlag} --nologo{signingProperty}",
-            worker.Directory, permission: ProcessPermission.SampleCompile);
-        return (result.ExitCode == 0, result.StdOut + result.StdErr, result.ExitCode);
+        return RunProcess("dotnet",
+            $"build \"{solutionPath}\" -c {configuration} --nologo -m:{parallelism}{signingProperty}",
+            tempRoot, permission: ProcessPermission.SampleCompile);
+    }
+
+    private static string ExtractSampleDiagnostics(ProcessResult result, SampleWorker worker)
+    {
+        var output = result.StdOut + result.StdErr;
+        var relevant = output
+            .Replace("\r\n", "\n", StringComparison.Ordinal)
+            .Replace('\r', '\n')
+            .Split('\n', StringSplitOptions.RemoveEmptyEntries)
+            .Where(line => line.Contains(worker.ProjectPath, StringComparison.OrdinalIgnoreCase) ||
+                           line.Contains(worker.SourcePath, StringComparison.OrdinalIgnoreCase))
+            .Distinct(StringComparer.Ordinal)
+            .ToList();
+
+        return relevant.Count > 0 ? string.Join(Environment.NewLine, relevant) : output;
     }
 
     private static void WritePhase(Options options, Report report, string name, TimeSpan elapsed, string? detail = null)
@@ -4902,8 +4906,8 @@ dotnet run --file docfx.cs -- [options]
             Modes (opt-in, each enables exactly one class of external process):
               (default)                Fast Markdown/overwrite/API-overwrite validation. No build.
               --validate-samples       Compile generated C# documentation samples (dotnet). The only
-                                      default-supported path that compiles samples. Each sample group
-                                      references only the documented project(s) that own its namespace.
+                                      default-supported path that compiles samples. Each sample has an
+                                      isolated project; one batched solution build compiles them all.
               --build-api-model        Reflection-backed API discovery from compiled assemblies. Builds
                                       only the documented project graph (dotnet). Alias: --strict-api-discovery.
               --verify-docfx-build     Run DocFX against a temp copy of the repository (docfx).
@@ -4919,7 +4923,7 @@ only the documented project graph (dotnet). Alias: --strict-api-discovery.
               --sample-reference-mode <project|package>
                                       Sample reference resolution. project (default) references the owning
                                       documented project(s); package references NuGet package ids where available.
-              --sample-parallelism <n> Number of parallel sample-validation groups (1-8). Default: 2.
+              --sample-parallelism <n> Maximum MSBuild nodes for the batched sample build (1-8). Default: 2.
                                       Override with env var DOCFX_DIGEST_SAMPLE_PARALLELISM.
               --build-api-model        Reflection-backed API discovery (opt-in). Default: no-build discovery.
               --changed-only           Validate only files changed according to git (git is read-only and allowed).
@@ -5072,7 +5076,12 @@ private sealed record OverwriteSection(string File, string Uid, string Body, boo
 
     private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
 
-    private sealed record SampleGroupWorker(string Directory, string ProjectPath, bool IsApp, bool RestoreOk);
+    private sealed record SampleWorker(
+        int OriginalIndex,
+        string Directory,
+        string ProjectPath,
+        string SourcePath,
+        string AssemblyName);
 
     private sealed record SampleReferenceSet(
         string Kind,

From 98ac4c0e0b743ec1f4192e00eceaec242823e9a6 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sat, 13 Jun 2026 13:48:19 +0200
Subject: [PATCH 59/88] =?UTF-8?q?=F0=9F=92=AC=20clarify=20sample=20compila?=
 =?UTF-8?q?tion=20strategy=20in=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update the dotnet-docfx-digest skill description and capability list to detail that samples are now compiled in isolated projects, batched into one temporary .slnx graph build with bounded MSBuild parallelism via --sample-parallelism. Clarify that all sample projects share the same temporary graph, so dependencies restore once while each sample maintains diagnostic isolation. Update the 'Examples that actually compile' capability description to match the refined implementation.
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1c5536e..3b5cdc1 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles C# samples (grouping each sample so it references only the documented project that owns its namespace), `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy `.docfx/api/*.md` authored overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns the fast `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns the fast `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -546,7 +546,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/namespaces/`, legacy authored `.docfx/api/*.md` overwrite files are moved into that folder instead of widening the glob to `api/**/*.md`, `api/namespaces/**/*.md` stays under `build.overwrite` only while `build.content` excludes `api/namespaces/**`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
 - **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
 - **Examples that teach a real workflow** — examples start from package IDs and package-level evidence before falling back to type/member-only searches, prefer README, package docs, tooling, tuning, functional-test, and external GitHub usage when available, and may include multiple related public types when that is what makes the consumer scenario understandable,
-- **Examples that actually compile** — under the opt-in `--validate-samples` path, every `csharp`/`cs` documentation fence is compiled; samples are grouped by dependency set so each references only the documented project(s) that own its namespace rather than every library project, and failures report the file, fence index, line, exit code, and compiler diagnostics,
+- **Examples that actually compile** — under the opt-in `--validate-samples` path, every `csharp`/`cs` documentation fence is compiled in its own isolated project; all sample projects are batched into one temporary `.slnx` graph build so shared dependencies restore and build once, `--sample-parallelism` bounds MSBuild concurrency, each sample references only the documented project(s) that own its namespace rather than every library project, and failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,
 - **Preserves manual edits** — additive by default, correcting stale or contradictory statements rather than overwriting hand-written documentation,

From c592c4350fd293776a43f0bb3efaec60d80765ea Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sat, 13 Jun 2026 15:59:22 +0200
Subject: [PATCH 60/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20workflow=20and=20test=20coverage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructures skill documentation, consolidates reference material, and adds comprehensive eval test cases for the dotnet-docfx-digest workflow. Improves clarity of workspace-level digest generation and documentation strategies.
---
 skills/dotnet-docfx-digest/SKILL.md           | 42 ++++++++++++-------
 skills/dotnet-docfx-digest/evals/evals.json   | 42 +++++++++++++++++++
 .../dotnet-docfx-digest/references/scripts.md | 14 +++++--
 .../references/workflow.md                    | 20 +++++----
 4 files changed, 92 insertions(+), 26 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index e021e27..a96e91f 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -39,8 +39,14 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 
 - `ENCODING_CORRUPTION` in the JSON output means a documentation file has double-encoded UTF-8 (mojibake). Restore with `git checkout HEAD -- <file>` if the committed version was correct, or use the edit tool or byte-level operations to rewrite the file safely. Never pipe content through `Get-Content` + `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes()` on documentation files that contain multi-byte characters or emoji.
 - `EXTENSION_TABLE_ENCODING` means the ⬇️ emoji (U+2B07) is missing or corrupted in an Extension Members table data row. Use the literal `⬇️` character, not HTML entities or text substitutes.
-- If either script cannot run, report the exact command, exit code, and failure output. Do not claim repository guidance or documentation was verified unless the scripts actually ran successfully.
-- Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape.
+- If either script cannot run, report the exact command, exit code, and failure output. Do not claim repository guidance or documentation was verified unless the scripts actually ran successfully.
+- Treat validator errors as the repo-wide repair queue, not as evidence that the repository is "blocked." A diagnostic being old, pre-existing, numerous, or outside the first files edited does not remove it from scope. A run with 1,228 `EXAMPLE_MISSING` findings means 1,228 documentation items remain; repairing one type page is a partial result, not a digest.
+- Use the JSON completion contract as the final authority: completion requires `summary.canClaimCompletion` to be `true`, `summary.remainingWorkItems` to be `0`, `summary.remainingGates` and `summary.remainingDiagnosticsByCode` to be empty, and the build-backed command to succeed. A clean fast run reports `completionState: verification-required`; it is an iteration checkpoint, not completion. Never describe `status: failed`, `completionState: incomplete`, or `completionState: verification-required` as completed work.
+- Continue documentation repair when `dotnet test` fails for an unrelated environmental dependency such as an unavailable database. Report that test failure separately. It is a blocker only if it prevents the documentation validator, source inspection, or required sample compilation from running.
+- Valid BOM-less UTF-8 is compliant. The validator must not emit `ENCODING_BOM_MISSING` (that diagnostic is intentionally unsupported), and an audit must not add/remove BOMs or normalize line endings solely for consistency. BOM presence has no documentation value; preserve the file's existing state and continue detecting actual `ENCODING_CORRUPTION` and `EXTENSION_TABLE_ENCODING` damage.
+- Final verification uses adaptive execution. In `auto`, machines with more than 8 available logical processors and more than 32 GiB available memory select `high-capacity`: DocFX verification runs concurrently in its isolated temp copy while the main lane builds/discovers API and then compiles samples, and MSBuild worker counts scale up to half the available processors (capped at 16). Smaller machines select `conservative` and keep the phases sequential with low worker counts. Override with `--execution-profile conservative|high-capacity` or `DOCFX_DIGEST_EXECUTION_PROFILE`.
+- Child processes time out after 30 minutes by default, configurable with `--process-timeout-minutes` or `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES`. Set the host/tool command timeout at least five minutes higher (35 minutes for the default) so the validator can kill a timed-out child and return a deterministic diagnostic instead of being terminated by the caller first.
+- Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape.
 
 ## Completion Repair Loop
 
@@ -50,9 +56,20 @@ Do not stop at namespace pages, extension-member tables, or a first-pass documen
 2. If diagnostics include `EXAMPLE_MISSING`, missing namespace pages, stale extension-member tables, missing availability, or overwrite inclusion problems, treat them as blocking follow-up work.
 3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/types/`.
 4. For each missing extension-method example, document it on the declaring extension class page or the namespace page, and explicitly demonstrate the method call.
-5. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too, or stop and report the exact blocker, command, exit code, and remaining diagnostic codes.
+5. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too and rerun until the JSON completion contract is clean.
+6. Do not convert repairable diagnostics into a blocker report. Stop incomplete only when the user pauses the task or an external condition still prevents progress after concrete attempts; report the exact blocker without claiming completion.
 
-Namespace pages and `Extension Members` tables complement type-page examples; they do not replace them. Both namespace pages (`api/namespaces/`) and type pages (`api/types/`) are required deliverables. Generating only one is incomplete work.
+Namespace pages and `Extension Members` tables complement type-page examples; they do not replace them. Both namespace pages (`api/namespaces/`) and type pages (`api/types/`) are required deliverables. Generating only one is incomplete work.
+
+### Restarting Partial Audits
+
+When continuing after another agent stopped with diagnostics remaining:
+
+1. Inspect `git status --short --untracked-files=all` and preserve every existing tracked and untracked documentation edit, not only the newly created namespace/type files.
+2. Rerun the fast validator with `--json --repair-plan <temp-path>` and read the generated plan.
+3. Use the repair plan and example inventory as the active queue across all affected namespaces, type pages, extension classes, and extension methods.
+4. Repair manageable batches, then rerun the fast validator after each batch so the queue measurably shrinks; do not stop after a representative subset.
+5. Run the exact final command `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json` and continue until the completion contract is clean.
 
 ## Core Principles
 
@@ -81,17 +98,12 @@ After modifications, inspect `git diff` for touched documentation paths and conf
 
 ## File Encoding Safety
 
-DocFX documentation files in Codebelt repositories use UTF-8 with BOM and LF line endings. When any tool must rewrite a documentation file to add or change encoding:
-
-- **Never use `Get-Content` + `[System.Text.Encoding]::UTF8.GetBytes()` round-trips.** On Windows, `Get-Content` reads in the OEM/ANSI code page by default. Multi-byte UTF-8 sequences — including emoji such as ⬇️ in `Extension Members` tables — are misread as Latin-1 and re-encoded as mojibake. The corruption is invisible until `git diff` reveals scrambled bytes.
-- **Use byte-level operations** to prepend a BOM without re-encoding content:
-  ```powershell
-  [System.IO.File]::WriteAllBytes($path, [byte[]](0xEF,0xBB,0xBF) + [System.IO.File]::ReadAllBytes($path))
-  ```
-- **Prefer the `edit` tool** for all Markdown content edits; it preserves bytes correctly and avoids encoding round-trip issues entirely.
-- **Check `git status` before any encoding-rewriting operation.** If bytes are corrupted and the file was committed, `git checkout HEAD -- <file>` restores the committed version — but discards any uncommitted in-flight changes. Do not use that recovery if there are unsaved edits.
-
-**Line ending inconsistency**: `.docfx/*.md` files may have mixed BOM presence or CRLF/LF line endings across a repository (pre-existing, not introduced by documentation edits). The DocFX validator does not enforce line endings, but mixed state increases encoding-corruption risk. If you discover mixed line endings during an audit, normalize all `.docfx/*.md` files to BOM + LF using the byte-level approach above, not `Set-Content` or `Out-File`.
+Use UTF-8 for DocFX documentation, but treat the BOM as optional. DocFX does not need a UTF-8 BOM, and adding or removing one across existing files creates noisy diffs with no documentation value. Preserve each file's existing BOM and line-ending state unless the user explicitly requests normalization.
+
+- **Never use an encoding-ambiguous `Get-Content` / `Set-Content` round-trip.** Legacy Windows PowerShell can interpret BOM-less UTF-8 through an ANSI code page. Multi-byte UTF-8 sequences, including ⬇️ in `Extension Members` tables, can become mojibake even though the original file was valid.
+- **Prefer the `edit` tool** for all Markdown content edits; it preserves bytes correctly and avoids encoding round-trip issues entirely.
+- **Check `git status` before any encoding-rewriting operation.** If bytes are corrupted and the file was committed, `git checkout HEAD -- <file>` restores the committed version — but discards any uncommitted in-flight changes. Do not use that recovery if there are unsaved edits.
+- **Do not normalize encoding or line endings as part of a documentation audit.** A BOM-only or line-ending-only diff obscures substantive work. The validator reports actual corruption such as `ENCODING_CORRUPTION`; it does not report BOM absence.
 
 ## Scope
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 597ced0..2e8ef21 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -649,6 +649,48 @@
         "Preserves per-sample SAMPLE_COMPILE_FAILED diagnostics with the original Markdown file and fence index",
         "Reports sample-validation phase detail containing `1 batch` and the sample count"
       ]
+    },
+    {
+      "id": 53,
+      "prompt": "Use dotnet-docfx-digest for a repo-wide audit. The previous agent added 8 missing namespace pages and only 1 type overwrite page, then stopped after the build-backed validator reported 62 EXTENSION_SECTION_MISSING, 1228 EXAMPLE_MISSING, and 1 DOCFX_BUILD_FAILED diagnostic. It called those findings pre-existing documentation gaps. `dotnet build` passes, while `dotnet test` fails only because an integration test cannot connect to SQL Server. Inspect the untracked DocFX work and finish the full digest.",
+      "expected_output": "The agent identifies the existing work as a partial digest, preserves it, and treats all 1291 validator errors as the active repo-wide repair queue rather than as pre-existing blockers. It uses the repair plan and example inventory to continue across every affected namespace, extension section, concrete type, and extension method. The unrelated SQL Server test failure is reported separately and does not end documentation work. The agent reruns fast validation during repair and treats a clean fast result as verification-required, then runs the build-backed command at the end. It does not claim completion until JSON reports summary.canClaimCompletion=true, summary.remainingWorkItems=0, empty summary.remainingGates and summary.remainingDiagnosticsByCode collections, and the build-backed command exits 0.",
+      "expectations": [
+        "Inspects and preserves the 8 untracked namespace pages, 1 untracked type page, and other existing documentation edits instead of discarding or overwriting them wholesale",
+        "Explicitly identifies the prior output as partial because 62 extension-section, 1228 example, and 1 DocFX-build diagnostics remain",
+        "Does not describe pre-existing diagnostics, diagnostic volume, or the size of the work queue as a blocker",
+        "Uses the deterministic repair plan and complete validator queue to continue repairing every missing extension section and example across the affected documentation surfaces",
+        "Reports the SQL Server integration-test failure separately and continues DocFX repair because the failure does not prevent documentation validation or source inspection",
+        "Reruns the fast validator after batches of edits instead of stopping after the first namespace or type subset",
+        "Treats fast validation as an iteration checkpoint and still requires the final build-backed command before completion",
+        "Runs the final build-backed command with --build-api-model --validate-samples --verify-docfx-build",
+        "Does not claim a full digest until summary.canClaimCompletion is true, summary.remainingWorkItems is 0, summary.remainingGates and summary.remainingDiagnosticsByCode are empty, and the final command exits 0"
+      ]
+    },
+    {
+      "id": 54,
+      "prompt": "Run dotnet-docfx-digest on a repository whose DocFX overwrite Markdown is valid UTF-8 without BOM. The files contain the ⬇️ extension-table marker and have no mojibake. Do not make unrelated documentation changes.",
+      "expected_output": "The validator accepts BOM-less UTF-8 without prescribing an ENCODING_BOM_MISSING repair or rewriting files only to add a BOM. It continues to distinguish intact extension-table markers from actual encoding corruption. The agent preserves existing BOM and line-ending state, and git diff contains no encoding-only changes.",
+      "expectations": [
+        "Treats valid BOM-less UTF-8 as compliant and prescribes no missing-BOM repair",
+        "Does not add a UTF-8 BOM or normalize line endings solely as part of the DocFX audit",
+        "Preserves the literal ⬇️ marker and distinguishes intact content from actual encoding corruption",
+        "Does not treat BOM presence as documentation work or a completion requirement",
+        "Leaves git diff free of BOM-only and line-ending-only changes"
+      ]
+    },
+    {
+      "id": 55,
+      "prompt": "Run the final dotnet-docfx-digest verification on a machine where Environment.ProcessorCount is 24 and GC.GetGCMemoryInfo().TotalAvailableMemoryBytes is 128 GiB. The agent host previously killed the command after 10 minutes before the validator could report a DocFX timeout. Confirm the adaptive scheduling and timeout behavior.",
+      "expected_output": "Auto selects the high-capacity profile because the process has more than 8 available logical processors and more than 32 GiB available memory. DocFX verification runs concurrently in its isolated temp copy while the primary lane builds/discovers API and then compiles samples. Build and sample parallelism default to 12 workers (half of 24, capped below 16). Child-process timeout is 30 minutes by default, and the outer tool timeout is set to at least 35 minutes. JSON exposes the selected execution settings and phase timing. The sample phase is not started before API discovery because scoped references depend on the namespace-to-project map.",
+      "expectations": [
+        "Selects high-capacity automatically for 24 available logical processors and 128 GiB available memory",
+        "Starts isolated DocFX verification concurrently with the primary API/sample lane",
+        "Keeps sample compilation after API discovery because scoped sample references depend on the namespace-to-project map",
+        "Uses an adaptive default of 12 MSBuild workers for both documented-project and sample graph builds on this machine",
+        "Uses a 30-minute child-process timeout and requires an outer command timeout of at least 35 minutes",
+        "Reports profile, processors, memory, worker counts, timeout, concurrency choice, process counts, and phase timings in JSON",
+        "Allows explicit conservative/high-capacity, worker-count, and timeout overrides through CLI or environment variables"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index e842826..088ff2f 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -55,6 +55,10 @@ Compilation and network access are strictly opt-in, and each option enables exac
 - `--verify-docfx-build` runs DocFX against a temp copy of the repository (`docfx`).
 - `--search-examples` runs GitHub code search per documented package (`gh`).
 
+Final verification is machine-adaptive. `--execution-profile auto` is the default. It selects `high-capacity` when `Environment.ProcessorCount` reports more than 8 processors available to the process and `GC.GetGCMemoryInfo().TotalAvailableMemoryBytes` reports more than 32 GiB. In that profile, DocFX verification starts in its isolated temp copy while the primary lane builds the documented project graph, discovers API, and compiles samples; the sample phase still follows API discovery because project-scoped sample references depend on the discovered namespace-to-project map. Build and sample MSBuild parallelism default to half the available processors, capped at 16. Other machines use `conservative`, which keeps final phases sequential and defaults to at most 2 workers. Force a profile with `--execution-profile` or `DOCFX_DIGEST_EXECUTION_PROFILE`; override workers with `--build-parallelism`, `DOCFX_DIGEST_BUILD_PARALLELISM`, `--sample-parallelism`, or `DOCFX_DIGEST_SAMPLE_PARALLELISM`.
+
+External child processes have a 30-minute default timeout. Override it with `--process-timeout-minutes` or `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES` (1-180). The calling agent/tool must use an outer command timeout at least five minutes longer than the validator timeout; otherwise the caller can terminate the validator before it kills the child process and emits `DOCFX_BUILD_FAILED` or another deterministic diagnostic.
+
 For Codebelt strong-name signed repositories, build and sample paths use the root `.snk` when present and automatically pass `-p:SkipSignAssembly=true` when no root `.snk` exists, so missing local signing keys do not masquerade as documentation failures.
 
 ```bash
@@ -70,7 +74,7 @@ dotnet run --file docfx.cs -- --repo-root . --validate-samples --sample-referenc
 dotnet run --file docfx.cs -- --repo-root . --build-api-model --configuration Debug --framework net10.0
 ```
 
-Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only used by build/sample paths), `--framework`, `--validate-samples` / `--no-validate-samples` (default off — opt-in), `--sample-reference-mode <project|package>` (default `project`), `--sample-parallelism <n>` (1-8, default 2; env `DOCFX_DIGEST_SAMPLE_PARALLELISM`; passed as the maximum node count for the batched sample graph build), `--build-api-model` / `--strict-api-discovery` (default off — opt-in), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default off — opt-in), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
+Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only used by build/sample paths), `--framework`, `--validate-samples` / `--no-validate-samples` (default off — opt-in), `--sample-reference-mode <project|package>` (default `project`), `--sample-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_SAMPLE_PARALLELISM`; passed as the maximum node count for the batched sample graph build), `--build-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_BUILD_PARALLELISM`), `--execution-profile <auto|conservative|high-capacity>` (env `DOCFX_DIGEST_EXECUTION_PROFILE`), `--process-timeout-minutes <n>` (1-180, default 30; env `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES`), `--build-api-model` / `--strict-api-discovery` (default off — opt-in), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default off — opt-in), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It still does not build by default: Markdown/overwrite-only changes are validated against the no-build API model, and it uses `git` (read-only) to discover changes. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled (under `--validate-samples`) before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
@@ -98,15 +102,17 @@ Exit codes:
 | 7 | Sample compilation failed (only reachable with `--validate-samples`) |
 | 8 | Unexpected internal error |
 
-Every run records a process tally and per-phase timings. Non-JSON output prints a `[processes] dotnet=… msbuild=… docfx=… gh=…` line and `[phase] <name>: <seconds>s` lines; JSON output exposes the same data under `summary.processes` (an object with `dotnet`, `msbuild`, `docfx`, `gh`, `git` counts) and `summary.phases` (an ordered list of `{ name, seconds, detail }`). `summary.validationMode` is `fast-markdown` or `build-backed-api-model`, and `summary.apiModelSource` is `docfx-yaml`, `source-scan`, or `build-backed`. For a default fast run on any repository, the process counts for `dotnet`, `msbuild`, `docfx`, and `gh` are all `0`.
+Every run records a process tally, per-phase timings, and execution settings. Non-JSON output prints a `[processes] dotnet=… msbuild=… docfx=… gh=…` line and `[phase] <name>: <seconds>s` lines; JSON output exposes the same data under `summary.processes`, `summary.phases`, and `summary.execution`. The execution object reports profile, logical processors, available memory bytes, build/sample parallelism, process timeout, and whether DocFX verification used the concurrent lane. `summary.validationMode` is `fast-markdown` or `build-backed-api-model`, and `summary.apiModelSource` is `docfx-yaml`, `source-scan`, or `build-backed`. For a default fast run on any repository, the process counts for `dotnet`, `msbuild`, `docfx`, and `gh` are all `0`.
+
+Every report also carries a deterministic completion contract. `summary.completionState` is `complete` only when there are no errors and the run enabled `--build-api-model`, `--validate-samples`, and `--verify-docfx-build`. A clean fast run reports `verification-required`. `summary.canClaimCompletion` must be `true`; `summary.remainingWorkItems` must be `0`; and both `summary.remainingGates` and `summary.remainingDiagnosticsByCode` must be empty before an agent can claim a full digest. Any other result is an active repair or verification queue. Diagnostic age, pre-existing status, and volume do not convert repair work into an external blocker.
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `ENCODING_BOM_MISSING` when a DocFX API overwrite file is missing a UTF-8 BOM, `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
 
 `ENCODING_CORRUPTION` fires when a documentation file contains the byte sequence `C3 A2 C2 AC` — the UTF-8 re-encoding of the `â¬` pair produced by a Windows-1252 round-trip of `U+2B07` (⬇, the Extension Members table arrow). Restore the affected file with `git checkout HEAD -- <file>` if the committed version was correct, or rewrite the content using the edit tool or byte-level operations. Never use `Get-Content` / `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes(Get-Content)` to rewrite documentation files that contain multi-byte characters.
 
 `EXTENSION_TABLE_ENCODING` fires when a data row in an Extension Members table is missing the `U+2B07` (⬇️) character in the Ext column, indicating that the emoji is either absent or has been corrupted. The correct literal is `⬇️`, not an HTML entity, a Unicode escape, or a look-alike character.
 
-`ENCODING_BOM_MISSING` warns when a DocFX API overwrite file under `api/` is missing a UTF-8 BOM. Add the BOM using byte-level operations to avoid re-encoding content.
+UTF-8 BOM presence is not validated. `ENCODING_BOM_MISSING` is intentionally not emitted. The BOM is optional for DocFX and has no documentation value by itself, so the validator preserves existing BOM and line-ending state rather than creating encoding-only diffs. `ENCODING_CORRUPTION` and `EXTENSION_TABLE_ENCODING` remain active checks because they detect damaged content rather than a harmless encoding marker difference.
 
 ### Sample opt-out
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index d95e335..366a4c2 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -50,12 +50,12 @@ Use this path when the user names a changed API or namespace.
 16. Run `git diff` for touched documentation paths and confirm the diff is intentional.
 17. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 18. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-19. Run the Completion Repair Loop by rerunning the fast `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
+19. Run the Completion Repair Loop by rerunning the fast `docfx.cs --json`, repairing every remaining diagnostic, and updating the example inventory until `summary.canClaimCompletion` is `true`. Diagnostic age and volume are not blockers.
 20. Run the build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` so samples compile, API discovery is reflection-precise, and DocFX builds in a temp copy.
 21. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
 22. Report verification results and any remaining deterministic findings.
 
-## Repo-wide audit workflow
+## Repo-wide audit workflow
 
 Use this path when the user invokes the skill without naming a specific API or namespace.
 
@@ -81,10 +81,14 @@ Use this path when the user invokes the skill without naming a specific API or n
 20. Run `git diff` for touched documentation paths and confirm the diff is intentional.
 21. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 22. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-23. Run the Completion Repair Loop by rerunning the fast `docfx.cs --json`, repairing remaining diagnostics, and updating the example inventory until required diagnostics are gone or a precise blocker remains.
+23. Run the Completion Repair Loop by rerunning the fast `docfx.cs --json`, repairing every remaining diagnostic, and updating the example inventory until `summary.canClaimCompletion` is `true`. A large queue is still the task, not a reason to stop.
 24. Run the build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` so samples compile, API discovery is reflection-precise, and DocFX builds in a temp copy.
 25. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
-26. Report verification results and any remaining deterministic findings.
+26. Report verification results and any remaining deterministic findings.
+
+When resuming a partial repo-wide audit, begin by inventorying all tracked and untracked documentation changes and preserving them as in-flight work. Regenerate the deterministic repair plan and example inventory, use both as the authoritative queue, and work in batches with a fast validator rerun after every batch. The exact final command is `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json`; descriptive references to those activities do not replace running the flags together.
+
+For the final command, let `auto` choose the execution profile unless the user requests a specific resource policy. High-capacity machines run the isolated DocFX verification lane concurrently with API/sample work; conservative machines remain sequential. Give the outer command a timeout at least five minutes above the validator's child-process timeout (35 minutes with the default 30-minute setting) so timeout diagnostics can be returned normally.
 
 ## Namespace page template
 
@@ -202,7 +206,7 @@ Before completing documentation work, verify:
 - [ ] The example inventory maps each required public type and extension method to its example file, UID, source evidence, and chosen scenario.
 - [ ] Examples show a coherent consumer workflow, use related public types when helpful, and avoid placeholder-only `Consumer`/`MyNamespace` shells when a domain name is available.
 - [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`. Namespace pages are under `api/namespaces/` and type pages are under `api/types/`.
-- [ ] The Completion Repair Loop was run after edits, and remaining `EXAMPLE_MISSING` or overwrite-layout diagnostics were fixed or reported as exact blockers.
+- [ ] The Completion Repair Loop was run after edits, and the final report has zero `EXAMPLE_MISSING`, namespace, extension, availability, overwrite-layout, sample, and DocFX-build diagnostics.
 - [ ] Examples are realistic, copy/paste-ready, and compile unless a justified skip marker is present.
 - [ ] Generated C# examples include a file-scoped namespace and a type declaration (class, struct, or record), or are explicitly labelled `// Program.cs`.
 - [ ] No generated C# example uses top-level statements without a `// Program.cs` label.
@@ -214,7 +218,7 @@ Before completing documentation work, verify:
 - [ ] `git diff` for touched documentation paths was inspected before final verification.
 - [ ] `dotnet build` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
 - [ ] `dotnet test` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
-- [ ] The build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` ran successfully (samples compiled, reflection-backed API discovery clean, DocFX built), or the failure is reported.
+- [ ] The build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` ran successfully, and final JSON reports `summary.canClaimCompletion: true`, `summary.remainingWorkItems: 0`, an empty `summary.remainingGates`, and an empty `summary.remainingDiagnosticsByCode`.
 - [ ] Generated metadata files and build output directories did not remain in the working tree after verification, and authored Markdown or documentation assets were not deleted as cleanup.
 - [ ] No broad restore or checkout command discarded authored documentation changes.
 
@@ -233,4 +237,6 @@ When reporting completion, include:
 - verification commands run
 - any verification failures or skipped checks
 
-Do not claim documentation was verified unless the relevant command actually ran successfully.
+Do not claim documentation was verified unless the relevant command actually ran successfully.
+
+If work must stop incomplete, distinguish a true external blocker from repair work. Pre-existing documentation gaps, large diagnostic counts, sample compile failures, and `DOCFX_BUILD_FAILED` output caused by the documentation/configuration being repaired are active work items. Only a user pause or an external condition that still prevents progress after concrete attempts justifies stopping, and that response must say the digest remains incomplete.

From 5013f4cb0247bf097706cf3863219bf253f1510e Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sat, 13 Jun 2026 15:59:31 +0200
Subject: [PATCH 61/88] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20enhance=20docfx=20sc?=
 =?UTF-8?q?ript=20implementation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Significantly expands docfx.cs with improved functionality for documentation generation, analysis, and validation. Adds enhanced error handling, performance improvements, and better output formatting for DocFX digest operations.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 413 +++++++++++++++++---
 1 file changed, 352 insertions(+), 61 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 01b99fc..cf04057 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -24,9 +24,11 @@ internal static class DocfxValidator
     private const string ExtensionAttributeFullName = "System.Runtime.CompilerServices.ExtensionAttribute";
     private const string SkipMarker = "dotnet-docfx-digest:skip-compile";
     private const int DefaultSampleValidationParallelism = 2;
+    private const int DefaultProcessTimeoutMinutes = 30;
+    private const long HighCapacityMemoryThresholdBytes = 32L * 1024 * 1024 * 1024;
 
     private static readonly string[] IgnoredDirectorySegments = ["bin", "obj", "_site", ".git", ".vs", ".vscode", ".idea", "node_modules"];
-    private static readonly TimeSpan ProcessTimeout = TimeSpan.FromMinutes(10);
+    private static TimeSpan _processTimeout = TimeSpan.FromMinutes(DefaultProcessTimeoutMinutes);
     private static readonly TimeSpan ProcessStreamDrainTimeout = TimeSpan.FromSeconds(5);
 
     // Process guard state. The fast (default) path forbids dotnet/msbuild/docfx/gh entirely;
@@ -103,6 +105,18 @@ private static int Validate(Options options)
         report.Summary.ValidationMode = mode == ValidationMode.BuildBackedApiModel
             ? "build-backed-api-model"
             : "fast-markdown";
+        var execution = ResolveExecutionSettings(options);
+        _processTimeout = TimeSpan.FromMinutes(execution.ProcessTimeoutMinutes);
+        report.Summary.Execution = new ExecutionSummary
+        {
+            Profile = execution.Profile,
+            LogicalProcessors = execution.LogicalProcessors,
+            AvailableMemoryBytes = execution.AvailableMemoryBytes,
+            BuildParallelism = execution.BuildParallelism,
+            SampleParallelism = execution.SampleParallelism,
+            ProcessTimeoutMinutes = execution.ProcessTimeoutMinutes,
+            ConcurrentDocfxVerification = execution.ConcurrentDocfxVerification
+        };
 
         // Configure the process guard from options BEFORE anything can shell out. In the default
         // fast path this leaves dotnet/msbuild/docfx/gh entirely disallowed.
@@ -207,6 +221,19 @@ private static int Validate(Options options)
         WritePhase(options, report, "markdown discovery", phaseTimer.Elapsed,
             $"{markdownFiles.Count} file(s)");
 
+        CancellationTokenSource? concurrentDocfxCancellation = null;
+        Task<DocfxVerificationResult>? concurrentDocfxTask = null;
+        if (options.VerifyDocfxBuild && execution.ConcurrentDocfxVerification)
+        {
+            concurrentDocfxCancellation = new CancellationTokenSource();
+            var cancellationToken = concurrentDocfxCancellation.Token;
+            concurrentDocfxTask = Task.Run(
+                () => VerifyDocfxBuild(repoRoot, docfxPath, hasStrongNameKey, cancellationToken),
+                cancellationToken);
+        }
+
+        try
+        {
         // 5. Build the API model. The default fast path never builds: it reads existing DocFX
         //    YAML metadata when present, otherwise falls back to a conservative source scan.
         //    --build-api-model opts into reflection-backed discovery from compiled assemblies.
@@ -214,9 +241,11 @@ private static int Validate(Options options)
         ApiModel api;
         if (mode == ValidationMode.BuildBackedApiModel)
         {
-            var (buildOk, buildOutput) = BuildDocfxProjects(libraryProjects, repoRoot, options.Configuration, hasStrongNameKey);
+            var (buildOk, buildOutput) = BuildDocfxProjects(libraryProjects, repoRoot, options.Configuration,
+                hasStrongNameKey, execution.BuildParallelism);
             if (!buildOk)
             {
+                CancelConcurrentDocfxVerification(concurrentDocfxTask, concurrentDocfxCancellation);
                 report.Errors.Add(new Diagnostic("BUILD_FAILED", null, null,
                     $"dotnet build failed (configuration {options.Configuration}).\n{Trim(buildOutput)}"));
                 return Emit(options, report, ExitCode.BuildFailed, "Build failed.");
@@ -228,6 +257,7 @@ private static int Validate(Options options)
             }
             catch (Exception ex)
             {
+                CancelConcurrentDocfxVerification(concurrentDocfxTask, concurrentDocfxCancellation);
                 report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
                     $"Public API discovery failed: {ex.Message}"));
                 return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
@@ -238,6 +268,7 @@ private static int Validate(Options options)
 
             if (api.Namespaces.Count == 0)
             {
+                CancelConcurrentDocfxVerification(concurrentDocfxTask, concurrentDocfxCancellation);
                 report.Errors.Add(new Diagnostic("PUBLIC_API_DISCOVERY_FAILED", null, null,
                     "No public API could be discovered from the compiled library assemblies. Ensure the repository builds and exposes public types."));
                 return Emit(options, report, ExitCode.PublicApiDiscoveryFailed, "Public API discovery failed.");
@@ -262,7 +293,7 @@ private static int Validate(Options options)
         report.Summary.RequiredExampleTargets = api.RequiredExampleTargets.Count;
         report.Summary.ExtensionMethods = api.Namespaces.Sum(n => n.ExtensionMethods.Count);
 
-        // 6. Validate documentation file encoding (mojibake, missing BOM).
+        // 6. Validate documentation file encoding corruption (mojibake).
         phaseTimer.Restart();
         ValidateDocumentationEncoding(repoRoot, markdownFiles, report);
         WritePhase(options, report, "encoding validation", phaseTimer.Elapsed);
@@ -305,7 +336,7 @@ private static int Validate(Options options)
         // 9. Extract and compile C# documentation samples (opt-in: the only path that compiles).
         if (options.ValidateSamples)
         {
-            ValidateSamples(workspace, options, changedFiles, hasStrongNameKey, report);
+            ValidateSamples(workspace, options, changedFiles, hasStrongNameKey, execution.SampleParallelism, report);
         }
         else
         {
@@ -315,9 +346,13 @@ private static int Validate(Options options)
         // Optional DocFX build verification happens in a temp copy so generated output never lands in the working tree.
         if (options.VerifyDocfxBuild)
         {
-            phaseTimer.Restart();
-            VerifyDocfxBuild(repoRoot, docfxPath, hasStrongNameKey, report);
-            WritePhase(options, report, "docfx build verification", phaseTimer.Elapsed);
+            var result = concurrentDocfxTask is null
+                ? VerifyDocfxBuild(repoRoot, docfxPath, hasStrongNameKey, CancellationToken.None)
+                : concurrentDocfxTask.GetAwaiter().GetResult();
+            MergeDocfxVerification(result, docfxPath, report);
+            WritePhase(options, report, "docfx build verification", result.Elapsed,
+                concurrentDocfxTask is null ? "sequential" : "concurrent lane");
+            concurrentDocfxCancellation?.Dispose();
         }
 
         // Optional GitHub example search to embed real usage snippets in the repair plan.
@@ -356,6 +391,12 @@ private static int Validate(Options options)
         }
 
         return Emit(options, report, ExitCode.Success, "Validation passed.");
+        }
+        catch
+        {
+            CancelConcurrentDocfxVerification(concurrentDocfxTask, concurrentDocfxCancellation);
+            throw;
+        }
     }
 
     // ----------------------------------------------------------------------
@@ -1092,40 +1133,46 @@ private static IEnumerable<string> EnumerateFiles(string root, string pattern)
         }
     }
 
-    private static void VerifyDocfxBuild(string repoRoot, string docfxPath, bool hasStrongNameKey, Report report)
+    private static DocfxVerificationResult VerifyDocfxBuild(
+        string repoRoot, string docfxPath, bool hasStrongNameKey, CancellationToken cancellationToken)
     {
+        var stopwatch = Stopwatch.StartNew();
         var docfxExecutable = ResolveDocfxExecutable();
         if (docfxExecutable is null)
         {
-            report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
-                "Unable to find the DocFX CLI on PATH. Install the docfx .NET tool or make docfx.exe available on PATH."));
-            return;
+            return new DocfxVerificationResult(false,
+                "Unable to find the DocFX CLI on PATH. Install the docfx .NET tool or make docfx.exe available on PATH.",
+                stopwatch.Elapsed);
         }
 
         var tempRoot = Path.Combine(Path.GetTempPath(), "docfx-digest-build-" + Guid.NewGuid().ToString("N"));
         try
         {
-            CopyDirectory(repoRoot, tempRoot);
+            CopyDirectory(repoRoot, tempRoot, cancellationToken);
             var relativeDocfxPath = Path.GetRelativePath(repoRoot, docfxPath);
             var tempDocfxPath = Path.Combine(tempRoot, relativeDocfxPath);
             var environment = hasStrongNameKey
                 ? null
                 : new Dictionary<string, string> { ["SkipSignAssembly"] = "true" };
             var result = RunProcess(docfxExecutable, $"\"{tempDocfxPath}\"", tempRoot, environment,
-                ProcessPermission.DocfxBuild);
+                ProcessPermission.DocfxBuild, cancellationToken);
             if (result.ExitCode != 0)
             {
-                report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
-                    $"DocFX build failed in a temp workspace (exit {result.ExitCode}).\n{Trim(result.StdOut + result.StdErr)}"));
-                return;
+                return new DocfxVerificationResult(false,
+                    $"DocFX build failed in a temp workspace (exit {result.ExitCode}).\n{Trim(result.StdOut + result.StdErr)}",
+                    stopwatch.Elapsed, result.ExitCode == -2);
             }
 
-            report.Summary.DocfxBuildsVerified++;
+            return new DocfxVerificationResult(true, null, stopwatch.Elapsed);
+        }
+        catch (OperationCanceledException)
+        {
+            return new DocfxVerificationResult(false, "DocFX build verification was cancelled.", stopwatch.Elapsed, true);
         }
         catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
         {
-            report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
-                $"Unable to verify DocFX build in a temp workspace: {ex.Message}"));
+            return new DocfxVerificationResult(false,
+                $"Unable to verify DocFX build in a temp workspace: {ex.Message}", stopwatch.Elapsed);
         }
         finally
         {
@@ -1133,6 +1180,51 @@ private static void VerifyDocfxBuild(string repoRoot, string docfxPath, bool has
         }
     }
 
+    private static void MergeDocfxVerification(DocfxVerificationResult result, string docfxPath, Report report)
+    {
+        if (result.Success)
+        {
+            report.Summary.DocfxBuildsVerified++;
+            return;
+        }
+
+        if (!result.Cancelled)
+        {
+            report.Errors.Add(new Diagnostic("DOCFX_BUILD_FAILED", docfxPath, null,
+                result.Error ?? "DocFX build verification failed."));
+        }
+    }
+
+    private static void CancelConcurrentDocfxVerification(
+        Task<DocfxVerificationResult>? task, CancellationTokenSource? cancellation)
+    {
+        if (task is null || cancellation is null)
+        {
+            return;
+        }
+
+        try
+        {
+            cancellation.Cancel();
+        }
+        catch (ObjectDisposedException)
+        {
+            return;
+        }
+        try
+        {
+            task.GetAwaiter().GetResult();
+        }
+        catch (OperationCanceledException)
+        {
+            // Expected when the primary validation lane fails before final verification can complete.
+        }
+        finally
+        {
+            cancellation.Dispose();
+        }
+    }
+
     private static string? ResolveDocfxExecutable()
     {
         var currentProcess = Environment.ProcessPath;
@@ -1170,12 +1262,15 @@ private static void VerifyDocfxBuild(string repoRoot, string docfxPath, bool has
         return null;
     }
 
-    private static void CopyDirectory(string sourceDirectory, string destinationDirectory)
+    private static void CopyDirectory(
+        string sourceDirectory, string destinationDirectory, CancellationToken cancellationToken)
     {
+        cancellationToken.ThrowIfCancellationRequested();
         Directory.CreateDirectory(destinationDirectory);
 
         foreach (var file in Directory.GetFiles(sourceDirectory))
         {
+            cancellationToken.ThrowIfCancellationRequested();
             File.Copy(file, Path.Combine(destinationDirectory, Path.GetFileName(file)), overwrite: true);
         }
 
@@ -1187,7 +1282,7 @@ private static void CopyDirectory(string sourceDirectory, string destinationDire
                 continue;
             }
 
-            CopyDirectory(directory, Path.Combine(destinationDirectory, name));
+            CopyDirectory(directory, Path.Combine(destinationDirectory, name), cancellationToken);
         }
     }
 
@@ -1241,14 +1336,6 @@ private static void ValidateDocumentationEncoding(string repoRoot, List<string>
                     $"[System.IO.File]::WriteAllBytes($path, ...). Never use Get-Content + [System.Text.Encoding]::UTF8.GetBytes()."));
             }
 
-            // Warn about missing UTF-8 BOM on DocFX API overwrite files.
-            var hasBom = bytes.Length >= 3 && bytes[0] == 0xEF && bytes[1] == 0xBB && bytes[2] == 0xBF;
-            if (!hasBom && IsDocfxApiOverwritePath(file))
-            {
-                report.Warnings.Add(new Diagnostic("ENCODING_BOM_MISSING", rel, null,
-                    "DocFX API overwrite file is missing a UTF-8 BOM. Codebelt DocFX files use UTF-8 with BOM. " +
-                    "Add BOM without re-encoding: [System.IO.File]::WriteAllBytes($path, [byte[]](0xEF,0xBB,0xBF) + [System.IO.File]::ReadAllBytes($path))"));
-            }
         }
     }
 
@@ -1269,12 +1356,6 @@ private static bool HasMojibakePattern(byte[] bytes)
         return false;
     }
 
-    private static bool IsDocfxApiOverwritePath(string filePath)
-    {
-        return filePath.Contains(Path.DirectorySeparatorChar + "api" + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase) ||
-               filePath.Contains(Path.AltDirectorySeparatorChar + "api" + Path.AltDirectorySeparatorChar, StringComparison.OrdinalIgnoreCase);
-    }
-
     /// <summary>
     /// Restores and builds only the library projects referenced by the active docfx.json.
     /// A single temporary <c>.slnx</c> graph build is preferred so the whole documented
@@ -1283,7 +1364,8 @@ private static bool IsDocfxApiOverwritePath(string filePath)
     /// when the caller passes <c>--build-api-model</c>.
     /// </summary>
     private static (bool Ok, string Output) BuildDocfxProjects(
-        List<ProjectInfo> libraryProjects, string repoRoot, string configuration, bool hasStrongNameKey)
+        List<ProjectInfo> libraryProjects, string repoRoot, string configuration, bool hasStrongNameKey,
+        int parallelism)
     {
         if (libraryProjects.Count == 0)
         {
@@ -1309,7 +1391,7 @@ private static (bool Ok, string Output) BuildDocfxProjects(
             File.WriteAllText(tempSolution, sln.ToString(), new UTF8Encoding(false));
 
             var result = RunProcess("dotnet",
-                $"build \"{tempSolution}\" -c {configuration} --nologo{signingProperty}", repoRoot,
+                $"build \"{tempSolution}\" -c {configuration} --nologo -m:{parallelism}{signingProperty}", repoRoot,
                 permission: ProcessPermission.BuildApiModel);
             if (result.ExitCode != 0)
             {
@@ -3483,7 +3565,7 @@ private static bool HasExampleSectionWithCSharpFence(string body)
     // ----------------------------------------------------------------------
 
     private static void ValidateSamples(ValidationWorkspace ws, Options options, HashSet<string>? changedFiles,
-        bool hasStrongNameKey, Report report)
+        bool hasStrongNameKey, int defaultParallelism, Report report)
     {
         var repoRoot = ws.RepoRoot;
 
@@ -3581,7 +3663,7 @@ private static void ValidateSamples(ValidationWorkspace ws, Options options, Has
         Directory.CreateDirectory(tempRoot);
         try
         {
-            var parallelism = GetSampleValidationParallelism(options);
+            var parallelism = GetSampleValidationParallelism(options, defaultParallelism);
             var workerCount = Math.Min(parallelism, toCompile.Count);
             WritePhaseStart(options, "sample validation", workerCount, toCompile.Count);
             phaseTimer.Restart();
@@ -3742,11 +3824,10 @@ private static List<ProjectInfo> ResolveOwningProjects(SampleFence sample, Valid
         return best;
     }
 
-    private static int GetSampleValidationParallelism(Options options)
+    private static int GetSampleValidationParallelism(Options options, int defaultParallelism)
     {
         var processorCount = Math.Max(1, Environment.ProcessorCount);
-        const int MaxSupportedParallelism = 8;
-        var defaultParallelism = Math.Min(DefaultSampleValidationParallelism, processorCount);
+        const int MaxSupportedParallelism = 16;
 
         // CLI argument takes precedence over the environment variable.
         if (options.SampleParallelism.HasValue)
@@ -4305,6 +4386,64 @@ private static (string FrontMatter, string Body) SplitFrontMatter(string text)
     // Process + output helpers
     // ----------------------------------------------------------------------
 
+    private static ExecutionSettings ResolveExecutionSettings(Options options)
+    {
+        var logicalProcessors = Math.Max(1, Environment.ProcessorCount);
+        var availableMemoryBytes = Math.Max(0, GC.GetGCMemoryInfo().TotalAvailableMemoryBytes);
+        var detectedHighCapacity = logicalProcessors > 8 && availableMemoryBytes > HighCapacityMemoryThresholdBytes;
+
+        var requestedProfile = options.ExecutionProfile ??
+                               Environment.GetEnvironmentVariable("DOCFX_DIGEST_EXECUTION_PROFILE") ??
+                               "auto";
+        var highCapacity = requestedProfile.ToLowerInvariant() switch
+        {
+            "high-capacity" => true,
+            "conservative" => false,
+            _ => detectedHighCapacity
+        };
+
+        var adaptiveParallelism = highCapacity
+            ? Math.Clamp(logicalProcessors / 2, 4, 16)
+            : Math.Min(DefaultSampleValidationParallelism, logicalProcessors);
+        var buildParallelism = ResolveParallelism(options.BuildParallelism,
+            "DOCFX_DIGEST_BUILD_PARALLELISM", adaptiveParallelism, logicalProcessors, 16);
+        var sampleParallelism = ResolveParallelism(options.SampleParallelism,
+            "DOCFX_DIGEST_SAMPLE_PARALLELISM", adaptiveParallelism, logicalProcessors, 16);
+        var timeoutMinutes = ResolvePositiveInteger(options.ProcessTimeoutMinutes,
+            "DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES", DefaultProcessTimeoutMinutes, 1, 180);
+
+        return new ExecutionSettings(
+            highCapacity ? "high-capacity" : "conservative",
+            logicalProcessors,
+            availableMemoryBytes,
+            buildParallelism,
+            sampleParallelism,
+            timeoutMinutes,
+            highCapacity && options.VerifyDocfxBuild);
+    }
+
+    private static int ResolveParallelism(
+        int? optionValue, string environmentVariable, int fallback, int processorCount, int maximum)
+    {
+        var requested = optionValue ?? ParsePositiveInteger(Environment.GetEnvironmentVariable(environmentVariable));
+        return Math.Clamp(requested ?? fallback, 1, Math.Min(processorCount, maximum));
+    }
+
+    private static int ResolvePositiveInteger(
+        int? optionValue, string environmentVariable, int fallback, int minimum, int maximum)
+    {
+        var requested = optionValue ?? ParsePositiveInteger(Environment.GetEnvironmentVariable(environmentVariable));
+        return Math.Clamp(requested ?? fallback, minimum, maximum);
+    }
+
+    private static int? ParsePositiveInteger(string? value)
+    {
+        return int.TryParse(value, System.Globalization.NumberStyles.Integer,
+                   System.Globalization.CultureInfo.InvariantCulture, out var parsed) && parsed > 0
+            ? parsed
+            : null;
+    }
+
     private static void ConfigureProcessGuard(Options options)
     {
         var allowed = new HashSet<ProcessPermission> { ProcessPermission.Git };
@@ -4363,7 +4502,8 @@ private static string NormalizeProcessKey(string fileName)
 
     private static ProcessResult RunProcess(string fileName, string arguments, string workingDirectory,
         IReadOnlyDictionary<string, string>? environment = null,
-        ProcessPermission permission = ProcessPermission.NoBuild)
+        ProcessPermission permission = ProcessPermission.NoBuild,
+        CancellationToken cancellationToken = default)
     {
         // Process guard: count every external process and refuse to launch build/doc/network
         // tooling unless the active options explicitly authorize the corresponding permission.
@@ -4411,22 +4551,24 @@ private static ProcessResult RunProcess(string fileName, string arguments, strin
 
             var stdoutTask = Task.Run(() => process.StandardOutput.ReadToEnd());
             var stderrTask = Task.Run(() => process.StandardError.ReadToEnd());
-            if (!process.WaitForExit(ProcessTimeout))
+            using var timeout = new CancellationTokenSource(_processTimeout);
+            using var linked = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, timeout.Token);
+            try
             {
-                try
-                {
-                    process.Kill(entireProcessTree: true);
-                }
-                catch
-                {
-                    // ignore
-                }
-
+                process.WaitForExitAsync(linked.Token).GetAwaiter().GetResult();
+            }
+            catch (OperationCanceledException)
+            {
+                TryKillProcess(process);
                 process.WaitForExit(ProcessStreamDrainTimeout);
                 Task.WaitAll([stdoutTask, stderrTask], ProcessStreamDrainTimeout);
                 var stdout = stdoutTask.IsCompletedSuccessfully ? stdoutTask.Result : string.Empty;
                 var stderr = stderrTask.IsCompletedSuccessfully ? stderrTask.Result : string.Empty;
-                return new ProcessResult(-1, stdout, stderr + $"\nProcess '{fileName}' timed out after {ProcessTimeout.TotalMinutes} minutes.");
+                var reason = cancellationToken.IsCancellationRequested
+                    ? "was cancelled"
+                    : $"timed out after {_processTimeout.TotalMinutes:0.##} minutes";
+                return new ProcessResult(cancellationToken.IsCancellationRequested ? -2 : -1,
+                    stdout, stderr + $"\nProcess '{fileName}' {reason}.");
             }
 
             Task.WaitAll([stdoutTask, stderrTask]);
@@ -4438,6 +4580,18 @@ private static ProcessResult RunProcess(string fileName, string arguments, strin
         }
     }
 
+    private static void TryKillProcess(Process process)
+    {
+        try
+        {
+            process.Kill(entireProcessTree: true);
+        }
+        catch
+        {
+            // best effort
+        }
+    }
+
     private static void TryDeleteDirectory(string path)
     {
         try
@@ -4479,10 +4633,37 @@ private static int Emit(Options options, Report report, ExitCode code, string co
             report.Status = code == ExitCode.Success ? "passed" : "failed";
         }
 
-        WriteRepairPlanIfRequested(options, report);
-
         report.Summary.Errors = report.Errors.Count;
         report.Summary.Warnings = report.Warnings.Count;
+        report.Summary.RemainingGates = new List<string>();
+        if (!options.BuildApiModel)
+        {
+            report.Summary.RemainingGates.Add("--build-api-model");
+        }
+
+        if (!options.ValidateSamples)
+        {
+            report.Summary.RemainingGates.Add("--validate-samples");
+        }
+
+        if (!options.VerifyDocfxBuild)
+        {
+            report.Summary.RemainingGates.Add("--verify-docfx-build");
+        }
+
+        report.Summary.CanClaimCompletion = code == ExitCode.Success &&
+                                            report.Errors.Count == 0 &&
+                                            report.Summary.RemainingGates.Count == 0;
+        report.Summary.CompletionState = report.Summary.CanClaimCompletion
+            ? "complete"
+            : report.Errors.Count > 0 ? "incomplete" : "verification-required";
+        report.Summary.RemainingWorkItems = report.Errors.Count + report.Summary.RemainingGates.Count;
+        report.Summary.RemainingDiagnosticsByCode = report.Errors
+            .GroupBy(error => error.Code, StringComparer.Ordinal)
+            .OrderBy(group => group.Key, StringComparer.Ordinal)
+            .ToDictionary(group => group.Key, group => group.Count(), StringComparer.Ordinal);
+
+        WriteRepairPlanIfRequested(options, report);
 
         // Capture the process tally on every exit path so the result always proves whether the
         // fast path actually shelled out to dotnet/msbuild/docfx/gh.
@@ -4514,7 +4695,9 @@ private static int Emit(Options options, Report report, ExitCode code, string co
             }
 
             Console.WriteLine(
-                $"  Summary: mode={report.Summary.ValidationMode}, apiModel={report.Summary.ApiModelSource ?? "n/a"}, " +
+                $"  Summary: completion={report.Summary.CompletionState}, canClaimCompletion={report.Summary.CanClaimCompletion.ToString().ToLowerInvariant()}, " +
+                $"remainingWorkItems={report.Summary.RemainingWorkItems}, remainingGates={string.Join(',', report.Summary.RemainingGates)}, " +
+                $"mode={report.Summary.ValidationMode}, apiModel={report.Summary.ApiModelSource ?? "n/a"}, " +
                 $"namespaces={report.Summary.PublicNamespaces}, pages={report.Summary.NamespacePagesValidated}, " +
                 $"requiredExampleTargets={report.Summary.RequiredExampleTargets}, requiredExamples={report.Summary.RequiredExamples}, " +
                 $"extMethods={report.Summary.ExtensionMethods}, samplesCompiled={report.Summary.SamplesCompiled}, " +
@@ -4522,9 +4705,23 @@ private static int Emit(Options options, Report report, ExitCode code, string co
                 $"generatedOutputDirectoriesRemoved={report.Summary.GeneratedOutputDirectoriesRemoved}, " +
                 $"docfxBuildsVerified={report.Summary.DocfxBuildsVerified}, errors={report.Summary.Errors}, warnings={report.Summary.Warnings}");
 
+            Console.WriteLine(
+                $"  [execution] profile={report.Summary.Execution.Profile} processors={report.Summary.Execution.LogicalProcessors} " +
+                $"memoryGiB={report.Summary.Execution.AvailableMemoryBytes / (1024d * 1024 * 1024):F1} " +
+                $"buildWorkers={report.Summary.Execution.BuildParallelism} sampleWorkers={report.Summary.Execution.SampleParallelism} " +
+                $"timeoutMinutes={report.Summary.Execution.ProcessTimeoutMinutes} " +
+                $"concurrentDocfx={report.Summary.Execution.ConcurrentDocfxVerification.ToString().ToLowerInvariant()}");
+
             Console.WriteLine(
                 $"  [processes] dotnet={report.Summary.Processes["dotnet"]} msbuild={report.Summary.Processes["msbuild"]} " +
                 $"docfx={report.Summary.Processes["docfx"]} gh={report.Summary.Processes["gh"]}");
+
+            if (!report.Summary.CanClaimCompletion)
+            {
+                Console.WriteLine(
+                    "  [completion] INCOMPLETE: treat every remaining diagnostic as repair work. " +
+                    "Diagnostic age or volume is not a blocker and does not justify stopping after a partial digest.");
+            }
         }
 
         return (int)code;
@@ -4577,6 +4774,18 @@ private static string BuildRepairPlan(Report report)
 
         sb.AppendLine($"Status: `{report.Status ?? "unknown"}`");
         sb.AppendLine();
+        sb.AppendLine("## Completion Contract");
+        sb.AppendLine();
+        sb.AppendLine($"- Completion state: `{report.Summary.CompletionState ?? "unknown"}`");
+        sb.AppendLine($"- Can claim completion: `{report.Summary.CanClaimCompletion.ToString().ToLowerInvariant()}`");
+        sb.AppendLine($"- Remaining work items: {report.Summary.RemainingWorkItems}");
+        sb.AppendLine($"- Remaining final-verification gates: {(report.Summary.RemainingGates.Count == 0 ? "none" : string.Join(", ", report.Summary.RemainingGates.Select(gate => $"`{gate}`")))}");
+        sb.AppendLine($"- Execution profile: `{report.Summary.Execution.Profile}` ({report.Summary.Execution.LogicalProcessors} processors, {report.Summary.Execution.AvailableMemoryBytes / (1024d * 1024 * 1024):F1} GiB available, build workers {report.Summary.Execution.BuildParallelism}, sample workers {report.Summary.Execution.SampleParallelism}, timeout {report.Summary.Execution.ProcessTimeoutMinutes} minutes, concurrent DocFX `{report.Summary.Execution.ConcurrentDocfxVerification.ToString().ToLowerInvariant()}`)");
+        sb.AppendLine("- Every error below is an active repair item. Its age, pre-existing status, or the number of similar diagnostics does not make it a blocker or move it out of scope for a repo-wide digest.");
+        sb.AppendLine("- Do not stop after repairing only a sample of namespaces, types, extension sections, or examples. Rerun the validator and continue until `canClaimCompletion` is `true`.");
+        sb.AppendLine("- An unrelated build or test failure may be reported separately, but it does not end documentation repair unless it prevents the validator or required evidence inspection from running.");
+        sb.AppendLine("- Stop incomplete only when the user pauses the task or an external condition still prevents progress after concrete repair attempts. Report the exact command, exit code, blocker, and remaining diagnostic counts; never describe that state as complete.");
+        sb.AppendLine();
         sb.AppendLine("## Summary");
         sb.AppendLine();
         sb.AppendLine($"- Public namespaces: {report.Summary.PublicNamespaces}");
@@ -4598,8 +4807,8 @@ private static string BuildRepairPlan(Report report)
         sb.AppendLine("- Treat `Extension Members` tables as incomplete until required examples exist.");
         sb.AppendLine("- Repair related namespace pages together; do not update only the first page that exposes a shared issue.");
         sb.AppendLine("- After edits, inspect `git diff` for the touched documentation paths before final verification.");
-        sb.AppendLine("- If examples cannot be sourced or compiled, report the limitation instead of claiming completion.");
-        sb.AppendLine("- Rerun validation with `--verify-docfx-build` before claiming completion.");
+        sb.AppendLine("- If an example does not compile, inspect the API shape, project references, tests, and package evidence and repair it; a compile diagnostic is work, not a reason to skip the rest of the queue.");
+        sb.AppendLine("- Rerun build-backed validation with `--build-api-model --validate-samples --verify-docfx-build` before claiming completion.");
         sb.AppendLine();
 
         AppendDiagnostics(sb, "Repository Guidance", report.Errors.Where(e => e.Code is "AGENTS_BLOCK_MISSING"));
@@ -4625,12 +4834,13 @@ e.Code is not "EXAMPLE_MISSING" &&
         sb.AppendLine();
         sb.AppendLine("- [ ] `agents.cs` has run successfully when `AGENTS_BLOCK_MISSING` appears.");
         sb.AppendLine("- [ ] `ENCODING_CORRUPTION` files restored from git or rewritten using byte-level operations.");
-        sb.AppendLine("- [ ] Every namespace diagnostic above has been resolved or intentionally excluded with evidence.");
+        sb.AppendLine("- [ ] Every namespace and extension diagnostic above has been resolved; zero remain in the final report.");
         sb.AppendLine("- [ ] GitHub example sources consulted before writing any new example (see 'GitHub Example Sources' section).");
         sb.AppendLine("- [ ] Every `EXAMPLE_MISSING` diagnostic above maps to a concrete example location.");
         sb.AppendLine("- [ ] Changed C# examples pass structural validation (namespace + type declaration, or labelled `// Program.cs`).");
         sb.AppendLine("- [ ] Changed C# examples compile as a class library project referencing the documented assemblies.");
         sb.AppendLine("- [ ] Authored Markdown files still exist after generated-artifact cleanup.");
+        sb.AppendLine("- [ ] Final JSON reports `canClaimCompletion: true`, `remainingWorkItems: 0`, no remaining gates, and no remaining diagnostic counts.");
         sb.AppendLine("- [ ] Final validation command and exit code are reported.");
 
         return sb.ToString();
@@ -4824,6 +5034,21 @@ private static bool TryParse(string[] args, out Options options, out string erro
                     if (!int.TryParse(sp, out var spv) || spv < 1) { error = "--sample-parallelism must be a positive integer."; return false; }
                     options.SampleParallelism = spv;
                     break;
+                case "--build-parallelism":
+                    if (!Next(args, ref i, out var bp)) { error = "--build-parallelism requires a count."; return false; }
+                    if (!int.TryParse(bp, out var bpv) || bpv < 1) { error = "--build-parallelism must be a positive integer."; return false; }
+                    options.BuildParallelism = bpv;
+                    break;
+                case "--process-timeout-minutes":
+                    if (!Next(args, ref i, out var pt)) { error = "--process-timeout-minutes requires a count."; return false; }
+                    if (!int.TryParse(pt, out var ptv) || ptv < 1 || ptv > 180) { error = "--process-timeout-minutes must be between 1 and 180."; return false; }
+                    options.ProcessTimeoutMinutes = ptv;
+                    break;
+                case "--execution-profile":
+                    if (!Next(args, ref i, out var ep)) { error = "--execution-profile requires auto, conservative, or high-capacity."; return false; }
+                    if (!IsValidExecutionProfile(ep)) { error = "--execution-profile must be auto, conservative, or high-capacity."; return false; }
+                    options.ExecutionProfile = ep.ToLowerInvariant();
+                    break;
                 case "--clean-generated-metadata":
                     options.CleanGeneratedMetadata = true;
                     break;
@@ -4851,6 +5076,23 @@ private static bool TryParse(string[] args, out Options options, out string erro
                         options.SampleParallelism = spvInline;
                         break;
                     }
+                    if (TrySplit(arg, "--build-parallelism", out var v8) &&
+                        int.TryParse(v8, out var bpvInline) && bpvInline >= 1)
+                    {
+                        options.BuildParallelism = bpvInline;
+                        break;
+                    }
+                    if (TrySplit(arg, "--process-timeout-minutes", out var v9) &&
+                        int.TryParse(v9, out var ptvInline) && ptvInline is >= 1 and <= 180)
+                    {
+                        options.ProcessTimeoutMinutes = ptvInline;
+                        break;
+                    }
+                    if (TrySplit(arg, "--execution-profile", out var v10) && IsValidExecutionProfile(v10))
+                    {
+                        options.ExecutionProfile = v10.ToLowerInvariant();
+                        break;
+                    }
 
                     error = $"Unknown argument: {arg}";
                     return false;
@@ -4864,6 +5106,11 @@ private static bool IsValidSampleReferenceMode(string value) =>
         string.Equals(value, "project", StringComparison.OrdinalIgnoreCase) ||
         string.Equals(value, "package", StringComparison.OrdinalIgnoreCase);
 
+    private static bool IsValidExecutionProfile(string value) =>
+        string.Equals(value, "auto", StringComparison.OrdinalIgnoreCase) ||
+        string.Equals(value, "conservative", StringComparison.OrdinalIgnoreCase) ||
+        string.Equals(value, "high-capacity", StringComparison.OrdinalIgnoreCase);
+
     private static bool Next(string[] args, ref int i, out string value)
     {
         if (i + 1 >= args.Length)
@@ -4923,8 +5170,20 @@ only the documented project graph (dotnet). Alias: --strict-api-discovery.
               --sample-reference-mode <project|package>
                                       Sample reference resolution. project (default) references the owning
                                       documented project(s); package references NuGet package ids where available.
-              --sample-parallelism <n> Maximum MSBuild nodes for the batched sample build (1-8). Default: 2.
+              --sample-parallelism <n> Maximum MSBuild nodes for the batched sample build (1-16).
+                                      Default: adaptive (2 conservative; up to half the available processors,
+                                      capped at 16, on high-capacity machines).
                                       Override with env var DOCFX_DIGEST_SAMPLE_PARALLELISM.
+              --build-parallelism <n> Maximum MSBuild nodes for the documented project build (1-16).
+                                      Override with env var DOCFX_DIGEST_BUILD_PARALLELISM.
+              --execution-profile <auto|conservative|high-capacity>
+                                      auto (default) selects high-capacity above 8 available logical processors
+                                      and 32 GiB available memory; high-capacity overlaps DocFX verification with
+                                      API/sample work and favors resource use over wall-clock time.
+                                      Override with env var DOCFX_DIGEST_EXECUTION_PROFILE.
+              --process-timeout-minutes <n>
+                                      Child-process timeout from 1-180 minutes. Default: 30.
+                                      Override with env var DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES.
               --build-api-model        Reflection-backed API discovery (opt-in). Default: no-build discovery.
               --changed-only           Validate only files changed according to git (git is read-only and allowed).
               --verify-docfx-build     Run DocFX against a temp copy of the repository (opt-in).
@@ -4981,6 +5240,9 @@ private sealed class Options
         public bool Json { get; set; }
         public bool Help { get; set; }
         public int? SampleParallelism { get; set; }
+        public int? BuildParallelism { get; set; }
+        public int? ProcessTimeoutMinutes { get; set; }
+        public string? ExecutionProfile { get; set; }
         public string SampleReferenceMode { get; set; } = "project";
     }
 
@@ -5076,6 +5338,18 @@ private sealed record OverwriteSection(string File, string Uid, string Body, boo
 
     private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
 
+    private sealed record DocfxVerificationResult(
+        bool Success, string? Error, TimeSpan Elapsed, bool Cancelled = false);
+
+    private sealed record ExecutionSettings(
+        string Profile,
+        int LogicalProcessors,
+        long AvailableMemoryBytes,
+        int BuildParallelism,
+        int SampleParallelism,
+        int ProcessTimeoutMinutes,
+        bool ConcurrentDocfxVerification);
+
     private sealed record SampleWorker(
         int OriginalIndex,
         string Directory,
@@ -5111,6 +5385,12 @@ public Diagnostic(string code, string? path, string? @namespace, string message)
 
 internal sealed class Summary
 {
+    public string? CompletionState { get; set; }
+    public bool CanClaimCompletion { get; set; }
+    public int RemainingWorkItems { get; set; }
+    public Dictionary<string, int> RemainingDiagnosticsByCode { get; set; } = new();
+    public List<string> RemainingGates { get; set; } = new();
+    public ExecutionSummary Execution { get; set; } = new();
     public string? ValidationMode { get; set; }
     public string? ApiModelSource { get; set; }
     public int PublicNamespaces { get; set; }
@@ -5129,6 +5409,17 @@ internal sealed class Summary
     public List<PhaseTiming> Phases { get; set; } = new();
 }
 
+internal sealed class ExecutionSummary
+{
+    public string Profile { get; set; } = "conservative";
+    public int LogicalProcessors { get; set; }
+    public long AvailableMemoryBytes { get; set; }
+    public int BuildParallelism { get; set; }
+    public int SampleParallelism { get; set; }
+    public int ProcessTimeoutMinutes { get; set; }
+    public bool ConcurrentDocfxVerification { get; set; }
+}
+
 internal sealed class PhaseTiming
 {
     public PhaseTiming(string name, double seconds, string? detail = null)

From 43206502104617eae160496a987a6e9bda2148db Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sat, 13 Jun 2026 15:59:40 +0200
Subject: [PATCH 62/88] =?UTF-8?q?=F0=9F=93=9D=20update=20available=20skill?=
 =?UTF-8?q?s=20in=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refreshes the dotnet-docfx-digest skill entry in the Available Skills table to reflect recent enhancements to the workflow documentation and script implementation.
---
 README.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3b5cdc1..ab7ceba 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,11 @@ One more consistency rule matters for form-driven skills: native input fields ar
 
 Repo-level agent guidance also keeps progress updates user-facing: agents should report meaningful progress, evidence, blockers, and next steps without narrating sandbox mechanics, approved command paths, or retry plumbing unless those details affect approval, reproducibility, validation, or the final outcome.
 
-Completion gates are equally strict: if repository guidance, a loaded skill, or the conversation summary marks a script-backed step as pending, critical, or blocking, agents must treat it as an active checklist item and may not claim completion until that command has run or the exact blocker has been reported. In the DocFX workflow, that means `scripts/agents.cs` and the build-backed `scripts/docfx.cs --build-api-model --validate-samples --verify-docfx-build` verification are completion gates, not optional cleanup after the documentation files look done. (The plain `scripts/docfx.cs` run is fast and build-free for iteration; the build-backed flags are what make the final gate authoritative.)
+Completion gates are equally strict: if repository guidance, a loaded skill, or the conversation summary marks a script-backed step as pending, critical, or blocking, agents must treat it as an active checklist item and may not claim completion until that command has run or the exact external blocker has been reported. In the DocFX workflow, that means `scripts/agents.cs` and the build-backed `scripts/docfx.cs --build-api-model --validate-samples --verify-docfx-build` verification are completion gates, not optional cleanup after the documentation files look done. The validator now emits a deterministic completion contract: `summary.canClaimCompletion` must be `true`, `summary.remainingWorkItems` must be `0`, and both `summary.remainingGates` and `summary.remainingDiagnosticsByCode` must be empty. A clean fast run reports `verification-required`, not completion. Pre-existing gaps, large diagnostic counts, sample failures, and documentation-caused DocFX build failures remain repair work; they are not permission to stop after a partial digest. (The plain `scripts/docfx.cs` run is fast and build-free for iteration; the build-backed flags are what make the final gate authoritative.)
+
+Resumed DocFX audits preserve every tracked and untracked documentation edit, regenerate the repair plan and example inventory, and process that queue in batches with a fast rerun after each batch. Encoding checks focus on actual damage: valid BOM-less UTF-8 is accepted, `ENCODING_BOM_MISSING` is not emitted, and audits do not create BOM-only or line-ending-only diffs.
+
+Final DocFX verification is machine-adaptive: `auto` selects a high-capacity profile above 8 available logical processors and 32 GiB available memory, overlaps isolated DocFX verification with API/sample work, and scales MSBuild workers up to half the available processors (capped at 16). Smaller machines stay conservative. Child-process timeout defaults to 30 minutes, and callers must allow at least 35 minutes so the validator can return its own timeout diagnostics.
 
 Validation follows the same philosophy: run `scripts/validate-skill-templates.ps1` locally for the fast feedback loop, and let GitHub Actions rerun that same script on pull requests as the safety net. That validator also checks skill frontmatter metadata such as per-skill `evals/evals.json` files, optional eval fixture paths declared through `files`, and the 1024-character YAML description limit; it does not replace the paired benchmark review workflow.
 
@@ -99,7 +103,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that reruns the fast `docfx.cs --json` after edits until `EXAMPLE_MISSING` and overwrite-layout diagnostics are fixed then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 

From bbf0ca8583275cb95930662878fc735c6286b606 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sun, 14 Jun 2026 02:42:20 +0200
Subject: [PATCH 63/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20workflow=20and=20test=20coverage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refines skill documentation structure, consolidates reference material, and expands eval test cases. Improves clarity of workspace digest generation and documentation strategies.
---
 skills/dotnet-docfx-digest/SKILL.md               |  5 ++++-
 skills/dotnet-docfx-digest/evals/evals.json       | 14 ++++++++++++++
 skills/dotnet-docfx-digest/references/scripts.md  |  4 +++-
 skills/dotnet-docfx-digest/references/workflow.md |  2 ++
 4 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index a96e91f..c2d5b65 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -46,6 +46,9 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 - Valid BOM-less UTF-8 is compliant. The validator must not emit `ENCODING_BOM_MISSING` (that diagnostic is intentionally unsupported), and an audit must not add/remove BOMs or normalize line endings solely for consistency. BOM presence has no documentation value; preserve the file's existing state and continue detecting actual `ENCODING_CORRUPTION` and `EXTENSION_TABLE_ENCODING` damage.
 - Final verification uses adaptive execution. In `auto`, machines with more than 8 available logical processors and more than 32 GiB available memory select `high-capacity`: DocFX verification runs concurrently in its isolated temp copy while the main lane builds/discovers API and then compiles samples, and MSBuild worker counts scale up to half the available processors (capped at 16). Smaller machines select `conservative` and keep the phases sequential with low worker counts. Override with `--execution-profile conservative|high-capacity` or `DOCFX_DIGEST_EXECUTION_PROFILE`.
 - Child processes time out after 30 minutes by default, configurable with `--process-timeout-minutes` or `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES`. Set the host/tool command timeout at least five minutes higher (35 minutes for the default) so the validator can kill a timed-out child and return a deterministic diagnostic instead of being terminated by the caller first.
+- Long-running API builds, sample compilation, and DocFX verification write progress to `stderr`: an initial `[ ]` line, a heartbeat every 10 seconds, and a final `[✓]` or `[x]` line. Heartbeats name the active phase, workload size, runner count, PID, elapsed time, time since the child last produced output, and its latest output line when available. Do not suppress `stderr` during interactive runs; `--json` remains a single parseable document on `stdout`.
+- When reporting adaptive execution, include the selected profile, processor and memory inputs, build/sample worker counts, timeout, concurrent/sequential choice, process counts, and phase timings from JSON. State that sample compilation follows API discovery because scoped references depend on the namespace-to-project map. Name CLI and environment overrides for profile, worker counts, and timeout when the user asks how to tune the run.
+- When reporting heartbeat behavior, state the complete contract: append-only `stderr`, no cursor-rewritten table, start and 10-second heartbeat events, final success/failure marker for all three long phases, latest non-empty child-output line when available, and plain redirected-log markers that do not depend on ANSI color. When reporting encoding safety, explicitly confirm the diff contains neither BOM-only nor line-ending-only changes.
 - Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape.
 
 ## Completion Repair Loop
@@ -65,7 +68,7 @@ Namespace pages and `Extension Members` tables complement type-page examples; th
 
 When continuing after another agent stopped with diagnostics remaining:
 
-1. Inspect `git status --short --untracked-files=all` and preserve every existing tracked and untracked documentation edit, not only the newly created namespace/type files.
+1. Inspect `git status --short --untracked-files=all`, enumerate the stated counts and paths, and preserve every existing tracked and untracked documentation edit, not only the newly created namespace/type files. Do not collapse a concrete inventory such as “8 namespace pages and 1 type page” into a generic promise to preserve work.
 2. Rerun the fast validator with `--json --repair-plan <temp-path>` and read the generated plan.
 3. Use the repair plan and example inventory as the active queue across all affected namespaces, type pages, extension classes, and extension methods.
 4. Repair manageable batches, then rerun the fast validator after each batch so the queue measurably shrinks; do not stop after a representative subset.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 2e8ef21..efad493 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -691,6 +691,20 @@
         "Reports profile, processors, memory, worker counts, timeout, concurrency choice, process counts, and phase timings in JSON",
         "Allows explicit conservative/high-capacity, worker-count, and timeout overrides through CLI or environment variables"
       ]
+    },
+    {
+      "id": 56,
+      "prompt": "Run final dotnet-docfx-digest verification in --json mode on a repository where API build, sample compilation, and DocFX build each take several minutes. The previous command appeared frozen because it emitted no progress until completion. Keep the machine-readable report parseable while giving me enough live information to decide whether a child process is progressing or stale.",
+      "expected_output": "Long-running API build, sample compilation, and DocFX verification write append-only progress to stderr without mixing progress text into JSON stdout. Each child emits an initial [ ] event, a heartbeat every 10 seconds, and a final green [✓] success or [x] failure event. Heartbeats identify the phase, workload size, runner count, PID, elapsed time, time since the child last produced output, and the latest non-empty child-output line when available. Redirected logs remain readable without ANSI dependence, and stdout still parses as exactly one JSON report.",
+      "expectations": [
+        "Writes long-running child-process progress to stderr so --json stdout remains a single parseable report",
+        "Emits a start event, 10-second heartbeat events, and a final success or failure event for API build, sample compilation, and DocFX verification",
+        "Reports the active phase, project or sample workload, runner count, child PID, and elapsed time",
+        "Reports time since the child last produced output so a quiet process can be distinguished from a stale process",
+        "Includes the latest non-empty child-output line when available to show what is currently being processed",
+        "Uses a green check marker for interactive success while keeping redirected output readable without requiring ANSI color support",
+        "Does not use terminal cursor rewriting or an in-place table that becomes unreadable in CI logs"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 088ff2f..38dea84 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -59,6 +59,8 @@ Final verification is machine-adaptive. `--execution-profile auto` is the defaul
 
 External child processes have a 30-minute default timeout. Override it with `--process-timeout-minutes` or `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES` (1-180). The calling agent/tool must use an outer command timeout at least five minutes longer than the validator timeout; otherwise the caller can terminate the validator before it kills the child process and emits `DOCFX_BUILD_FAILED` or another deterministic diagnostic.
 
+API builds, sample graph builds, and DocFX verification emit append-only progress events to `stderr`. The validator writes `[ ]` when a child starts, another `[ ]` heartbeat every 10 seconds, and `[✓]` or `[x]` when it completes. Each heartbeat includes the phase, project/sample workload, runner count, child PID, elapsed time, time since the child last wrote output, and the latest non-empty output line when available. This makes a quiet restore/build distinguishable from a stale process without corrupting `--json`, which remains exclusively on `stdout`. Redirected logs use plain markers; interactive terminals color the completion marker when ANSI color is available.
+
 For Codebelt strong-name signed repositories, build and sample paths use the root `.snk` when present and automatically pass `-p:SkipSignAssembly=true` when no root `.snk` exists, so missing local signing keys do not masquerade as documentation failures.
 
 ```bash
@@ -102,7 +104,7 @@ Exit codes:
 | 7 | Sample compilation failed (only reachable with `--validate-samples`) |
 | 8 | Unexpected internal error |
 
-Every run records a process tally, per-phase timings, and execution settings. Non-JSON output prints a `[processes] dotnet=… msbuild=… docfx=… gh=…` line and `[phase] <name>: <seconds>s` lines; JSON output exposes the same data under `summary.processes`, `summary.phases`, and `summary.execution`. The execution object reports profile, logical processors, available memory bytes, build/sample parallelism, process timeout, and whether DocFX verification used the concurrent lane. `summary.validationMode` is `fast-markdown` or `build-backed-api-model`, and `summary.apiModelSource` is `docfx-yaml`, `source-scan`, or `build-backed`. For a default fast run on any repository, the process counts for `dotnet`, `msbuild`, `docfx`, and `gh` are all `0`.
+Every run records a process tally, per-phase timings, and execution settings. Non-JSON output prints a `[processes] dotnet=… msbuild=… docfx=… gh=…` line and `[phase] <name>: <seconds>s` lines; JSON output exposes the same data under `summary.processes`, `summary.phases`, and `summary.execution`. Long-running child progress is intentionally written to `stderr`, not embedded in the JSON report. The execution object reports profile, logical processors, available memory bytes, build/sample parallelism, process timeout, and whether DocFX verification used the concurrent lane. `summary.validationMode` is `fast-markdown` or `build-backed-api-model`, and `summary.apiModelSource` is `docfx-yaml`, `source-scan`, or `build-backed`. For a default fast run on any repository, the process counts for `dotnet`, `msbuild`, `docfx`, and `gh` are all `0`.
 
 Every report also carries a deterministic completion contract. `summary.completionState` is `complete` only when there are no errors and the run enabled `--build-api-model`, `--validate-samples`, and `--verify-docfx-build`. A clean fast run reports `verification-required`. `summary.canClaimCompletion` must be `true`; `summary.remainingWorkItems` must be `0`; and both `summary.remainingGates` and `summary.remainingDiagnosticsByCode` must be empty before an agent can claim a full digest. Any other result is an active repair or verification queue. Diagnostic age, pre-existing status, and volume do not convert repair work into an external blocker.
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 366a4c2..10255ab 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -89,6 +89,8 @@ Use this path when the user invokes the skill without naming a specific API or n
 When resuming a partial repo-wide audit, begin by inventorying all tracked and untracked documentation changes and preserving them as in-flight work. Regenerate the deterministic repair plan and example inventory, use both as the authoritative queue, and work in batches with a fast validator rerun after every batch. The exact final command is `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json`; descriptive references to those activities do not replace running the flags together.
 
 For the final command, let `auto` choose the execution profile unless the user requests a specific resource policy. High-capacity machines run the isolated DocFX verification lane concurrently with API/sample work; conservative machines remain sequential. Give the outer command a timeout at least five minutes above the validator's child-process timeout (35 minutes with the default 30-minute setting) so timeout diagnostics can be returned normally.
+
+Keep `stderr` visible during the final command. API build, sample compilation, and DocFX verification print a start event, 10-second heartbeats, and a final success/failure event there. Use the phase, PID, elapsed time, last-output age, and current output line to decide whether work is progressing or a child appears stale. Capturing `stdout` for `--json` is safe because progress never enters the JSON stream.
 
 ## Namespace page template
 

From 6908bafdf6f24e888a761fd61c6f0b68c9eeb624 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sun, 14 Jun 2026 02:42:27 +0200
Subject: [PATCH 64/88] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20enhance=20docfx=20sc?=
 =?UTF-8?q?ript=20implementation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Expands docfx.cs with additional functionality for documentation generation. Improves handling, validation logic, and output formatting for DocFX digest operations.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 172 ++++++++++++++++++--
 1 file changed, 162 insertions(+), 10 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index cf04057..414d031 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -30,6 +30,7 @@ internal static class DocfxValidator
     private static readonly string[] IgnoredDirectorySegments = ["bin", "obj", "_site", ".git", ".vs", ".vscode", ".idea", "node_modules"];
     private static TimeSpan _processTimeout = TimeSpan.FromMinutes(DefaultProcessTimeoutMinutes);
     private static readonly TimeSpan ProcessStreamDrainTimeout = TimeSpan.FromSeconds(5);
+    private static readonly TimeSpan ProcessHeartbeatInterval = TimeSpan.FromSeconds(10);
 
     // Process guard state. The fast (default) path forbids dotnet/msbuild/docfx/gh entirely;
     // each external process is tagged with the permission that authorizes it, and the set of
@@ -1155,7 +1156,8 @@ private static DocfxVerificationResult VerifyDocfxBuild(
                 ? null
                 : new Dictionary<string, string> { ["SkipSignAssembly"] = "true" };
             var result = RunProcess(docfxExecutable, $"\"{tempDocfxPath}\"", tempRoot, environment,
-                ProcessPermission.DocfxBuild, cancellationToken);
+                ProcessPermission.DocfxBuild, cancellationToken,
+                new ProcessProgress("DocFX build", "isolated temp workspace"));
             if (result.ExitCode != 0)
             {
                 return new DocfxVerificationResult(false,
@@ -1392,7 +1394,9 @@ private static (bool Ok, string Output) BuildDocfxProjects(
 
             var result = RunProcess("dotnet",
                 $"build \"{tempSolution}\" -c {configuration} --nologo -m:{parallelism}{signingProperty}", repoRoot,
-                permission: ProcessPermission.BuildApiModel);
+                permission: ProcessPermission.BuildApiModel,
+                progress: new ProcessProgress("API build",
+                    $"{libraryProjects.Count} project(s), {parallelism} runner(s)"));
             if (result.ExitCode != 0)
             {
                 return (false, result.StdOut + result.StdErr);
@@ -3919,7 +3923,9 @@ private static ProcessResult CompileSampleBatch(
         var signingProperty = hasStrongNameKey ? string.Empty : " -p:SkipSignAssembly=true";
         return RunProcess("dotnet",
             $"build \"{solutionPath}\" -c {configuration} --nologo -m:{parallelism}{signingProperty}",
-            tempRoot, permission: ProcessPermission.SampleCompile);
+            tempRoot, permission: ProcessPermission.SampleCompile,
+            progress: new ProcessProgress("sample compilation",
+                $"{workers.Count} sample project(s), {parallelism} runner(s)"));
     }
 
     private static string ExtractSampleDiagnostics(ProcessResult result, SampleWorker worker)
@@ -4503,7 +4509,8 @@ private static string NormalizeProcessKey(string fileName)
     private static ProcessResult RunProcess(string fileName, string arguments, string workingDirectory,
         IReadOnlyDictionary<string, string>? environment = null,
         ProcessPermission permission = ProcessPermission.NoBuild,
-        CancellationToken cancellationToken = default)
+        CancellationToken cancellationToken = default,
+        ProcessProgress? progress = null)
     {
         // Process guard: count every external process and refuse to launch build/doc/network
         // tooling unless the active options explicitly authorize the corresponding permission.
@@ -4549,8 +4556,22 @@ private static ProcessResult RunProcess(string fileName, string arguments, strin
                 return new ProcessResult(-1, string.Empty, $"Failed to start process '{fileName}'.");
             }
 
-            var stdoutTask = Task.Run(() => process.StandardOutput.ReadToEnd());
-            var stderrTask = Task.Run(() => process.StandardError.ReadToEnd());
+            var stopwatch = Stopwatch.StartNew();
+            var progressState = new ProcessProgressState();
+            var stdout = new StringBuilder();
+            var stderr = new StringBuilder();
+            var stdoutTask = PumpProcessOutputAsync(process.StandardOutput, stdout, progressState);
+            var stderrTask = PumpProcessOutputAsync(process.StandardError, stderr, progressState);
+            using var heartbeatCancellation = new CancellationTokenSource();
+            var heartbeatTask = progress is null
+                ? Task.CompletedTask
+                : ReportProcessProgressAsync(process, progress, stopwatch, progressState, heartbeatCancellation.Token);
+
+            if (progress is not null)
+            {
+                WriteProcessProgress("pending", progress, process.Id, stopwatch.Elapsed, TimeSpan.Zero, null);
+            }
+
             using var timeout = new CancellationTokenSource(_processTimeout);
             using var linked = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, timeout.Token);
             try
@@ -4562,17 +4583,43 @@ private static ProcessResult RunProcess(string fileName, string arguments, strin
                 TryKillProcess(process);
                 process.WaitForExit(ProcessStreamDrainTimeout);
                 Task.WaitAll([stdoutTask, stderrTask], ProcessStreamDrainTimeout);
-                var stdout = stdoutTask.IsCompletedSuccessfully ? stdoutTask.Result : string.Empty;
-                var stderr = stderrTask.IsCompletedSuccessfully ? stderrTask.Result : string.Empty;
                 var reason = cancellationToken.IsCancellationRequested
                     ? "was cancelled"
                     : $"timed out after {_processTimeout.TotalMinutes:0.##} minutes";
+
+                if (progress is not null)
+                {
+                    WriteProcessProgress("failed", progress, process.Id, stopwatch.Elapsed,
+                        progressState.TimeSinceLastOutput, reason);
+                }
+
+                var stdoutText = stdoutTask.IsCompletedSuccessfully ? stdout.ToString() : string.Empty;
+                var stderrText = stderrTask.IsCompletedSuccessfully ? stderr.ToString() : string.Empty;
                 return new ProcessResult(cancellationToken.IsCancellationRequested ? -2 : -1,
-                    stdout, stderr + $"\nProcess '{fileName}' {reason}.");
+                    stdoutText, stderrText + $"\nProcess '{fileName}' {reason}.");
+            }
+            finally
+            {
+                heartbeatCancellation.Cancel();
+                try
+                {
+                    heartbeatTask.GetAwaiter().GetResult();
+                }
+                catch (OperationCanceledException)
+                {
+                    // Expected when the process completes between heartbeat intervals.
+                }
             }
 
             Task.WaitAll([stdoutTask, stderrTask]);
-            return new ProcessResult(process.ExitCode, stdoutTask.Result, stderrTask.Result);
+            if (progress is not null)
+            {
+                WriteProcessProgress(process.ExitCode == 0 ? "completed" : "failed", progress, process.Id,
+                    stopwatch.Elapsed, progressState.TimeSinceLastOutput,
+                    process.ExitCode == 0 ? null : $"exit {process.ExitCode}");
+            }
+
+            return new ProcessResult(process.ExitCode, stdout.ToString(), stderr.ToString());
         }
         catch (Exception ex)
         {
@@ -4580,6 +4627,78 @@ private static ProcessResult RunProcess(string fileName, string arguments, strin
         }
     }
 
+    private static async Task PumpProcessOutputAsync(
+        StreamReader reader, StringBuilder output, ProcessProgressState progressState)
+    {
+        while (await reader.ReadLineAsync() is { } line)
+        {
+            output.AppendLine(line);
+            progressState.Record(line);
+        }
+    }
+
+    private static async Task ReportProcessProgressAsync(
+        Process process,
+        ProcessProgress progress,
+        Stopwatch stopwatch,
+        ProcessProgressState progressState,
+        CancellationToken cancellationToken)
+    {
+        while (true)
+        {
+            await Task.Delay(ProcessHeartbeatInterval, cancellationToken);
+            var snapshot = progressState.Snapshot();
+            WriteProcessProgress("working", progress, process.Id, stopwatch.Elapsed,
+                snapshot.TimeSinceLastOutput, snapshot.LastOutputLine);
+        }
+    }
+
+    private static void WriteProcessProgress(
+        string state,
+        ProcessProgress progress,
+        int processId,
+        TimeSpan elapsed,
+        TimeSpan timeSinceLastOutput,
+        string? status)
+    {
+        var marker = state switch
+        {
+            "completed" => ColorizeProgressMarker("[\u2713]", "32"),
+            "failed" => ColorizeProgressMarker("[x]", "31"),
+            "working" => ColorizeProgressMarker("[ ]", "33"),
+            _ => "[ ]"
+        };
+        var idle = state == "pending"
+            ? string.Empty
+            : $" | last output {FormatElapsed(timeSinceLastOutput)} ago";
+        var current = string.IsNullOrWhiteSpace(status)
+            ? string.Empty
+            : $" | current: {SanitizeProgressText(status)}";
+
+        Console.Error.WriteLine(
+            $"  {marker} {progress.Phase} | {progress.Detail} | pid {processId} | elapsed {FormatElapsed(elapsed)}{idle}{current}");
+    }
+
+    private static string ColorizeProgressMarker(string marker, string ansiColor)
+    {
+        return Console.IsErrorRedirected ? marker : $"\u001b[{ansiColor}m{marker}\u001b[0m";
+    }
+
+    private static string FormatElapsed(TimeSpan elapsed)
+    {
+        return elapsed.TotalHours >= 1
+            ? elapsed.ToString(@"hh\:mm\:ss", System.Globalization.CultureInfo.InvariantCulture)
+            : elapsed.ToString(@"mm\:ss", System.Globalization.CultureInfo.InvariantCulture);
+    }
+
+    private static string SanitizeProgressText(string text)
+    {
+        var withoutAnsi = Regex.Replace(text, @"\x1B\[[0-?]*[ -/]*[@-~]", string.Empty);
+        var sanitized = Regex.Replace(withoutAnsi.Trim(), @"\s+", " ");
+        const int maxLength = 180;
+        return sanitized.Length <= maxLength ? sanitized : sanitized[..maxLength] + "...";
+    }
+
     private static void TryKillProcess(Process process)
     {
         try
@@ -5338,6 +5457,39 @@ private sealed record OverwriteSection(string File, string Uid, string Body, boo
 
     private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
 
+    private sealed record ProcessProgress(string Phase, string Detail);
+
+    private sealed class ProcessProgressState
+    {
+        private readonly object _lock = new();
+        private long _lastOutputTimestamp = Stopwatch.GetTimestamp();
+        private string? _lastOutputLine;
+
+        public TimeSpan TimeSinceLastOutput => Stopwatch.GetElapsedTime(Volatile.Read(ref _lastOutputTimestamp));
+
+        public void Record(string line)
+        {
+            if (string.IsNullOrWhiteSpace(line))
+            {
+                return;
+            }
+
+            lock (_lock)
+            {
+                _lastOutputLine = line;
+                Volatile.Write(ref _lastOutputTimestamp, Stopwatch.GetTimestamp());
+            }
+        }
+
+        public (TimeSpan TimeSinceLastOutput, string? LastOutputLine) Snapshot()
+        {
+            lock (_lock)
+            {
+                return (Stopwatch.GetElapsedTime(_lastOutputTimestamp), _lastOutputLine);
+            }
+        }
+    }
+
     private sealed record DocfxVerificationResult(
         bool Success, string? Error, TimeSpan Elapsed, bool Cancelled = false);
 

From bc62bdeee379750e4452048633f82ee120d3636a Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sun, 14 Jun 2026 02:42:33 +0200
Subject: [PATCH 65/88] =?UTF-8?q?=F0=9F=93=9D=20update=20available=20skill?=
 =?UTF-8?q?s=20in=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refreshes the dotnet-docfx-digest skill entry to reflect recent refinements to the workflow documentation and script implementation.
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ab7ceba..3850e0b 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ Completion gates are equally strict: if repository guidance, a loaded skill, or
 
 Resumed DocFX audits preserve every tracked and untracked documentation edit, regenerate the repair plan and example inventory, and process that queue in batches with a fast rerun after each batch. Encoding checks focus on actual damage: valid BOM-less UTF-8 is accepted, `ENCODING_BOM_MISSING` is not emitted, and audits do not create BOM-only or line-ending-only diffs.
 
-Final DocFX verification is machine-adaptive: `auto` selects a high-capacity profile above 8 available logical processors and 32 GiB available memory, overlaps isolated DocFX verification with API/sample work, and scales MSBuild workers up to half the available processors (capped at 16). Smaller machines stay conservative. Child-process timeout defaults to 30 minutes, and callers must allow at least 35 minutes so the validator can return its own timeout diagnostics.
+Final DocFX verification is machine-adaptive: `auto` selects a high-capacity profile above 8 available logical processors and 32 GiB available memory, overlaps isolated DocFX verification with API/sample work, and scales MSBuild workers up to half the available processors (capped at 16). Smaller machines stay conservative. Child-process timeout defaults to 30 minutes, and callers must allow at least 35 minutes so the validator can return its own timeout diagnostics. Long-running build, sample, and DocFX children also emit 10-second `stderr` heartbeats with phase, workload, runner count, PID, elapsed time, last-output age, and current output while keeping JSON stdout parseable.
 
 Validation follows the same philosophy: run `scripts/validate-skill-templates.ps1` locally for the fast feedback loop, and let GitHub Actions rerun that same script on pull requests as the safety net. That validator also checks skill frontmatter metadata such as per-skill `evals/evals.json` files, optional eval fixture paths declared through `files`, and the 1024-character YAML description limit; it does not replace the paired benchmark review workflow.
 
@@ -103,7 +103,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 

From 2388a77a28f7292f781c640c695dea6d4b95fc97 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sun, 14 Jun 2026 03:17:04 +0200
Subject: [PATCH 66/88] =?UTF-8?q?=F0=9F=94=A8=20add=20repo=20validation=20?=
 =?UTF-8?q?tooling?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extends validate-skill-templates.ps1 with additional validation checks for repo-managed skills. Ensures consistency and compliance across the skill repository.
---
 scripts/validate-skill-templates.ps1 | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1
index 9282c84..eacc361 100644
--- a/scripts/validate-skill-templates.ps1
+++ b/scripts/validate-skill-templates.ps1
@@ -1107,6 +1107,14 @@ Add-ValidationResult -Results $results -Name 'Rendered library templates leave n
     }
 }
 
+Add-ValidationResult -Results $results -Name 'DocFX digest rejects metadata scaffolds and accepts scenario-led documentation' -Action {
+    $qualityTest = Join-Path $repoRoot 'skills/dotnet-docfx-digest/scripts/test-quality.ps1'
+    & $qualityTest
+    if ($LASTEXITCODE -ne 0) {
+        throw "DocFX semantic quality regression failed with exit code $LASTEXITCODE."
+    }
+}
+
 $passed = @($results | Where-Object { $_.Status -eq 'PASS' }).Count
 $failed = @($results | Where-Object { $_.Status -eq 'FAIL' }).Count
 $label = if ([string]::IsNullOrWhiteSpace($Ref)) { 'WORKTREE' } else { $Ref }

From 6c0db36b846047abbaec00eb8e2855079fc5fb81 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sun, 14 Jun 2026 03:17:13 +0200
Subject: [PATCH 67/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20skill=20contract?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructures skill documentation with improved workflow clarity, consolidates reference material, and expands eval test coverage. Aligns with progressive disclosure patterns and Anthropic skill conventions.
---
 skills/dotnet-docfx-digest/SKILL.md           | 19 ++++++--
 skills/dotnet-docfx-digest/evals/evals.json   | 28 +++++++++++
 .../dotnet-docfx-digest/references/scripts.md |  8 ++--
 .../references/workflow.md                    | 48 ++++++++++---------
 4 files changed, 72 insertions(+), 31 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index c2d5b65..0993b03 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -41,6 +41,8 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 - `EXTENSION_TABLE_ENCODING` means the ⬇️ emoji (U+2B07) is missing or corrupted in an Extension Members table data row. Use the literal `⬇️` character, not HTML entities or text substitutes.
 - If either script cannot run, report the exact command, exit code, and failure output. Do not claim repository guidance or documentation was verified unless the scripts actually ran successfully.
 - Treat validator errors as the repo-wide repair queue, not as evidence that the repository is "blocked." A diagnostic being old, pre-existing, numerous, or outside the first files edited does not remove it from scope. A run with 1,228 `EXAMPLE_MISSING` findings means 1,228 documentation items remain; repairing one type page is a partial result, not a digest.
+- Passing compilation is necessary but not sufficient. `EXAMPLE_PLACEHOLDER`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, and `EXAMPLE_UID_DUPLICATE` are blocking quality failures. Never satisfy the inventory with `Type.GetType`, assembly metadata inspection, `DocumentedTypeExample`, `DocumentedExtensionExample`, generic `Describe()` helpers, repeated UID sections, or prose that merely names the target.
+- Namespace prose must be decision-useful. `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING` mean the page still needs a problem/outcome opening, concrete "when to use" guidance, and a named starting API when the namespace has multiple entry points.
 - Use the JSON completion contract as the final authority: completion requires `summary.canClaimCompletion` to be `true`, `summary.remainingWorkItems` to be `0`, `summary.remainingGates` and `summary.remainingDiagnosticsByCode` to be empty, and the build-backed command to succeed. A clean fast run reports `completionState: verification-required`; it is an iteration checkpoint, not completion. Never describe `status: failed`, `completionState: incomplete`, or `completionState: verification-required` as completed work.
 - Continue documentation repair when `dotnet test` fails for an unrelated environmental dependency such as an unavailable database. Report that test failure separately. It is a blocker only if it prevents the documentation validator, source inspection, or required sample compilation from running.
 - Valid BOM-less UTF-8 is compliant. The validator must not emit `ENCODING_BOM_MISSING` (that diagnostic is intentionally unsupported), and an audit must not add/remove BOMs or normalize line endings solely for consistency. BOM presence has no documentation value; preserve the file's existing state and continue detecting actual `ENCODING_CORRUPTION` and `EXTENSION_TABLE_ENCODING` damage.
@@ -56,7 +58,7 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 Do not stop at namespace pages, extension-member tables, or a first-pass documentation edit.
 
 1. Run `docfx.cs --json` (fast, no-build) after edits and read the remaining diagnostics.
-2. If diagnostics include `EXAMPLE_MISSING`, missing namespace pages, stale extension-member tables, missing availability, or overwrite inclusion problems, treat them as blocking follow-up work.
+2. Treat every missing, placeholder, reflection-only, target-use, extension-invocation, duplicate-UID, namespace-prose, extension-table, availability, and overwrite-layout diagnostic as blocking follow-up work.
 3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/types/`.
 4. For each missing extension-method example, document it on the declaring extension class page or the namespace page, and explicitly demonstrate the method call.
 5. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too and rerun until the JSON completion contract is clean.
@@ -156,6 +158,8 @@ Prefer scenario examples over isolated constructor or method-call snippets. A st
 
 Before writing examples for a package, identify the package ID or IDs from packable project metadata, `.nuget/*/README.md`, package release notes, `Directory.Packages.props`, or `PackageReference` usage. Search local repository evidence by package ID first, then by namespace/type/member name. When internet or GitHub search is available and the user has not forbidden it, search for the exact package ID and exclude the target repository or treat self-repo hits as lower-priority evidence. Package-ID searches often find real `Program.cs`, `PackageReference`, README, and package-documentation usage that type-name searches miss.
 
+For each repair batch, maintain an evidence ledger in the example inventory: record the exact test, package README, sample, XML comment, or source path inspected and the consumer task derived from it. Do not mark a scenario ready when its evidence cell contains only a type name, generated metadata, or the overwrite file being repaired.
+
 **Tests are evidence, not output.** Do not add `ShowUsage`, `Usage`, `Example`, or documentation-only methods to test files. Use tests to understand the documented type's behavior, then transform that knowledge into consumer-facing DocFX overwrite examples.
 
 Every generated `csharp` code block is a complete, copy/paste-ready compilation unit. The default is always a compilable unit (option 1). Only use intentionally incomplete excerpts (option 2) when explicitly requested by the user, and label them clearly.
@@ -168,8 +172,11 @@ Every generated `csharp` code block is a complete, copy/paste-ready compilation
 - Does **not** use top-level statements unless the example is explicitly labelled `// Program.cs` at the very top of the code block.
 - Does **not** invent placeholder services, interfaces, classes, methods, or overloads that are not defined inside the same code block.
 - Does **not** derive from an abstract or generic base type without supplying the correct concrete type arguments.
-- Does **not** call members that do not exist on the resolved public API surface.
-- Compiles in a minimal class library verification project referencing the documented assemblies.
+- Does **not** call members that do not exist on the resolved public API surface.
+- Uses the documented type or invokes the documented extension method inside the C# fence. A target name in prose, comments, or string literals does not count.
+- Shows a consumer-visible operation, result, configuration, or next action. Reflection-only discovery and metadata inspection do not count as usage.
+- Contains one coherent example mapping per UID. Merge related calls into one scenario instead of repeating `example: *content` sections for the same UID.
+- Compiles in a minimal class library verification project referencing the documented assemblies.
 
 Prefer examples derived from existing unit, functional, or integration tests as behavioral evidence, then from package-level usage evidence, samples, README content, and real consumer usage, then from a minimal new example based on actual public behavior. Convert Arrange/Act/Assert test structure into consumer-oriented sample code instead of pasting raw test assertions, mocks, or fixture setup.
 
@@ -220,6 +227,8 @@ Derive examples from these sources, in order:
 9. Omit the example entirely if none of the above yields a compile-valid, consumer-facing example.
 
 Final examples must be consumer-facing, realistic, and compile. They must read like production calling code or Microsoft Learn-style task examples, not test scaffolding, placeholder `Consumer` shells, or one-line smoke tests. Avoid unused locals, `MyNamespace` when a domain-specific namespace is obvious, fake "sample" values that obscure the workflow, and examples that instantiate the documented type without showing the result or next step a real caller cares about.
+
+Compilation-valid metadata scaffolds are still failures. Never generate a family of examples that differs only by UID while calling `Type.GetType`, returning `Type.FullName`, or wrapping the lookup in `DocumentedTypeExample`, `DocumentedExtensionExample`, or `Describe()`. These patterns conceal missing product knowledge instead of teaching the API.
 
 **Reflection and API-shape requirements:**
 
@@ -241,7 +250,9 @@ The reason is mandatory. Package requirements, "full example needs X", "shows th
 
 ## Namespace and Summary Style
 
-Namespace overview pages must explain what problem the namespace solves, when to use it, and where a newcomer should start. Avoid inventory-only blurbs such as “contains types and extension methods for...”
+Namespace overview pages must explain what problem the namespace solves, when to use it, and where a newcomer should start. Avoid inventory-only blurbs such as “contains types and extension methods for...”
+
+The opening paragraph should name the developer problem and outcome. The next paragraph should identify a concrete starting type or method and distinguish nearby alternatives. Do not use a type inventory as a substitute for this guidance; tables and generated API lists already provide inventory.
 
 Type and member summaries should explain the API’s job in consumer terms. Prefer purpose-first summaries for entry points, builders, factories, options, and extension methods. Avoid empty labels such as “represents options” or “adds services” unless the rest of the sentence explains the actual outcome enabled.
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index efad493..39a7ed5 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -705,6 +705,34 @@
         "Uses a green check marker for interactive success while keeping redirected output readable without requiring ANSI color support",
         "Does not use terminal cursor rewriting or an in-place table that becomes unreadable in CI logs"
       ]
+    },
+    {
+      "id": 57,
+      "prompt": "Audit a prior dotnet-docfx-digest run that created hundreds of compile-valid overwrite files. Nearly every type example calls `Type.GetType(\"Namespace.Type, Assembly\")` from a class named `DocumentedTypeExample`; extension files use `DocumentedExtensionExample.Describe()`, mention the method only in prose or string literals, and repeat the same UID in multiple `example: *content` sections. The namespace pages mostly say that the namespace contains types or extension methods. Repair the skill-driven output rather than accepting it because it compiles.",
+      "expected_output": "The agent identifies the output as metadata scaffolding rather than API documentation, inventories and preserves the existing work, and uses validator diagnostics to replace it systematically. Reflection-only examples produce EXAMPLE_REFLECTION_ONLY, generic generated scaffolds produce EXAMPLE_PLACEHOLDER, repeated mappings produce EXAMPLE_UID_DUPLICATE, type examples that never use the target produce EXAMPLE_TARGET_NOT_USED, and extension examples that never invoke the method in C# produce EXTENSION_EXAMPLE_NOT_INVOKED. Inventory-only namespace prose produces the namespace prose/usage/start-here diagnostics. The agent derives replacement scenarios from exact tests, package READMEs, samples, XML comments, or source paths, records that evidence and consumer task in the inventory, reruns validation in batches, and does not claim completion while any quality diagnostic remains.",
+      "expectations": [
+        "Does not accept compilation as proof that reflection or metadata lookup is a useful API example",
+        "Rejects Type.GetType, assembly metadata lookup, DocumentedTypeExample, DocumentedExtensionExample, and generic Describe helpers as final examples",
+        "Requires the documented type to be used inside the C# fence and the documented extension method to be invoked inside the C# fence",
+        "Rejects repeated example mappings for the same UID instead of preserving duplicate generated sections",
+        "Treats inventory-only namespace blurbs as unfinished and adds problem/outcome, when-to-use, and start-here guidance",
+        "Records exact source evidence paths and a consumer task for each repair batch",
+        "Reruns the validator until EXAMPLE_REFLECTION_ONLY, EXAMPLE_PLACEHOLDER, EXAMPLE_UID_DUPLICATE, EXAMPLE_TARGET_NOT_USED, EXTENSION_EXAMPLE_NOT_INVOKED, and namespace quality diagnostics are gone"
+      ]
+    },
+    {
+      "id": 58,
+      "prompt": "Document a namespace `Acme.Text` with `TextOptions` and `Normalize(this string value)`. Tests show normalization before identifier comparison, and the package README configures `TextOptions` for imported records. Write the namespace overview and examples with dotnet-docfx-digest.",
+      "expected_output": "The namespace overview leads with the text-ingress problem and stable comparison/storage outcome, explains when to use the namespace, and directs newcomers to TextOptions for import policy and Normalize for boundary cleanup. The inventory cites the exact test and package README paths and names the consumer task. The TextOptions type example configures options as part of an import workflow and shows the next action or result. The extension example invokes Normalize in C# on a realistic receiver before comparison or storage. No reflection, metadata-only lookup, generic Consumer/MyNamespace shell, duplicate UID section, invented member, or prose-only method mention appears. Fast semantic validation and build-backed sample verification both pass before completion.",
+      "expectations": [
+        "Writes namespace prose around a developer problem and outcome rather than listing contained types",
+        "Explains when to use Acme.Text and names TextOptions and Normalize as distinct starting points",
+        "Cites exact test and package README evidence paths in the example inventory",
+        "Shows TextOptions in a coherent import configuration workflow with a visible next action or result",
+        "Invokes Normalize inside the C# fence on a realistic string receiver",
+        "Avoids reflection, metadata-only examples, generic wrappers, duplicate UID mappings, and invented API members",
+        "Runs semantic validation and sample compilation before claiming completion"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 38dea84..cbbd3e0 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -80,7 +80,7 @@ Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It still does not build by default: Markdown/overwrite-only changes are validated against the no-build API model, and it uses `git` (read-only) to discover changes. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled (under `--validate-samples`) before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, encoding repairs, namespace and extension-table repairs, a required-example inventory with GitHub search commands, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory is a concrete work queue: for public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the plan to a temp path unless the user explicitly wants a checked-in artifact. The plan always includes a "GitHub Example Sources" section with `gh search code` commands and GitHub search URLs for each documented package, even when no `EXAMPLE_MISSING` diagnostics are present.
+`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, encoding repairs, namespace and extension-table repairs, a required-example inventory with GitHub search commands, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory includes missing examples and semantic failures such as duplicate UID mappings, placeholders, reflection-only scaffolds, target types that are never used, and extension methods that are never invoked. For public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the plan to a temp path unless the user explicitly wants a checked-in artifact. The plan always includes a "GitHub Example Sources" section with `gh search code` commands and GitHub search URLs for each documented package, even when no `EXAMPLE_MISSING` diagnostics are present.
 
 `--search-examples` runs `gh search code` for each discovered package ID and embeds the top matching file paths in the repair plan under "GitHub Search Results". Requires the `gh` CLI to be authenticated. Combine with `--repair-plan` so results are written to a file the agent can read. If `gh` is unavailable or returns no results, the plan still includes the pre-computed search URLs and CLI commands.
 
@@ -108,7 +108,7 @@ Every run records a process tally, per-phase timings, and execution settings. No
 
 Every report also carries a deterministic completion contract. `summary.completionState` is `complete` only when there are no errors and the run enabled `--build-api-model`, `--validate-samples`, and `--verify-docfx-build`. A clean fast run reports `verification-required`. `summary.canClaimCompletion` must be `true`; `summary.remainingWorkItems` must be `0`; and both `summary.remainingGates` and `summary.remainingDiagnosticsByCode` must be empty before an agent can claim a full digest. Any other result is an active repair or verification queue. Diagnostic age, pre-existing status, and volume do not convert repair work into an external blocker.
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, `NAMESPACE_START_HERE_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `EXAMPLE_UID_DUPLICATE`, `EXAMPLE_PLACEHOLDER`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
 
 `ENCODING_CORRUPTION` fires when a documentation file contains the byte sequence `C3 A2 C2 AC` — the UTF-8 re-encoding of the `â¬` pair produced by a Windows-1252 round-trip of `U+2B07` (⬇, the Extension Members table arrow). Restore the affected file with `git checkout HEAD -- <file>` if the committed version was correct, or rewrite the content using the edit tool or byte-level operations. Never use `Get-Content` / `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes(Get-Content)` to rewrite documentation files that contain multi-byte characters.
 
@@ -132,12 +132,12 @@ Reasons involving missing compile-time references are also rejected as insuffici
 
 ### Example detection
 
-The validator recognizes a complete example as one of:
+The validator first locates example code in one of:
 
 - A DocFX front-matter anchor (`example: *content` or the list form `example:\n- *content`) followed by a body that contains a fenced `csharp`/`cs` block; **or**
 - A `## Example` / `### Example` heading in the body followed by a fenced `csharp`/`cs` block.
 
-The first form is preferred for type pages and extension-class pages. Add a `### Examples` heading only when the front matter anchors the body to `summary` and you intend the heading to delimit the embedded example. The validator reports `EXAMPLE_MISSING` only when neither form is present. A run that reports `EXAMPLE_MISSING` while the rendered page clearly shows an example indicates a front-matter / heading mismatch — verify the YAML anchor before adding a body heading.
+The first form is preferred for type pages and extension-class pages. Add a `### Examples` heading only when the front matter anchors the body to `summary` and you intend the heading to delimit the embedded example. Locating a fence is only the structural gate. The validator then rejects duplicate example mappings for the same UID, generated placeholder phrases and helper names, reflection-only metadata lookup, type examples that never use the target in C# code, and extension examples that never invoke the method. Prose, comments, and string literals do not prove target use.
 
 ### Extension-method detection note
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 10255ab..1c41b0b 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -12,7 +12,7 @@ Build a small example inventory from validator output and source evidence before
 | Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory | Type | .docfx/api/types/Codebelt.Extensions.Xunit.Hosting.ApplicationHostFactory.md | Package README, ApplicationHostFactoryTest | Host a test server and create a client | Missing |
 ```
 
-Do not mark an item complete until the overwrite section targets the correct UID or approved extension-method location, the file is included by `build.overwrite`, the sample compiles under `docfx.cs --validate-samples` (or has a justified skip marker), and `docfx.cs --json` no longer reports the relevant missing-example diagnostic.
+Do not mark an item complete until the evidence cell names concrete repository paths, the scenario states a consumer task, the overwrite section targets the correct UID or approved extension-method location, the file is included by `build.overwrite`, the sample compiles under `docfx.cs --validate-samples` (or has a justified skip marker), and `docfx.cs --json` no longer reports any missing, placeholder, reflection-only, target-use, invocation, or duplicate-UID diagnostic.
 
 ## Scenario example design
 
@@ -25,6 +25,8 @@ Before writing a type or extension-method example, choose the smallest real task
 5. Pick a scenario that connects the documented type to the package workflow. A good sample can include multiple related public types, a small local helper type, dependency-injection setup, host setup, options configuration, file/path setup, or result inspection when that is what a real caller would do.
 6. Remove test-only structure, raw assertions, mocks, fixture base classes, and unused locals. Keep meaningful setup and result inspection.
 7. Prefer domain-specific names such as `BenchmarkRunner`, `WorkspaceUsage`, or `HttpRetryExample` over `Consumer` and `MyNamespace` when the package domain is clear.
+8. Reject metadata-only substitutes before writing: `Type.GetType`, assembly lookup, `typeof`/`nameof` as the only operation, generic `Describe()` helpers, and repeated UID sections do not demonstrate a consumer task.
+9. Confirm the C# fence itself uses the documented type or invokes the documented extension method. Mentions outside the fence do not count.
 
 A scenario example is still concise. It should show one coherent task, not a tour of every member. If a compile-valid scenario cannot be produced from evidence, omit the example with the documented omission comment rather than inventing a plausible workflow.
 
@@ -41,7 +43,7 @@ Use this path when the user names a changed API or namespace.
 7. Run `docfx.cs --json --repair-plan /tmp/docfx-repair-plan.md --search-examples` and read the repair plan. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs; use those results as evidence before writing examples.
 8. Convert test usage into consumer-oriented examples when relevant.
 9. Update XML documentation comments where purpose-first summaries are needed.
-10. Update or create namespace overview pages with conceptual orientation and start-here cues.
+10. Update or create namespace overview pages whose opening names the developer problem and outcome, followed by concrete when-to-use and start-here guidance.
 11. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
 12. Update `Extension Members` tables when public extension methods are involved. Use the literal `⬇️` (U+2B07 U+FE0F) in the Ext column — the validator now rejects corrupted or missing emoji with `EXTENSION_TABLE_ENCODING`.
 13. Update or create overwrite content, including type-page examples for public non-abstraction types and explicit examples for public extension methods.
@@ -69,7 +71,7 @@ Use this path when the user invokes the skill without naming a specific API or n
 8. Check for `ENCODING_CORRUPTION` or `EXTENSION_TABLE_ENCODING` diagnostics first; restore affected files from git before doing any further editing.
 9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
 10. Determine every public non-abstraction type and every public extension method that requires an example.
-11. Create or update missing namespace overview pages with purpose-first fly-ins and start-here guidance.
+11. Create or update missing namespace overview pages with a problem/outcome opening, concrete when-to-use guidance, and a named starting API. Inventory-only prose is unfinished.
 12. Audit related namespace pages together so fixes are consistent across the public API family.
 13. Add or repair `Extension Members` tables for namespaces with public extension methods. Use the literal `⬇️` (U+2B07 U+FE0F) in the Ext column.
 14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
@@ -128,21 +130,20 @@ uid: X.Y.Z.MyType
 example:
 - *content
 ---
-The following example shows how to use `MyType` as part of a real consuming workflow.
+The following schematic shows the overwrite shape only. Replace it with a source-backed consumer task; do not copy the generic names into product documentation.
 
 ```csharp
 using X.Y.Z;
 
 namespace MyProject.Workflows;
 
-public class WidgetWorkflow
+public class WidgetFactory
 {
-    public void Run()
+    public MyType Create()
     {
-        var value = new MyType();
-        Console.WriteLine(value);
-    }
-}
+        return new MyType();
+    }
+}
 ```
 ````
 
@@ -158,22 +159,20 @@ uid: X.Y.Z.MyExtensions
 example:
 - *content
 ---
-The following example shows how to call `NormalizeLineEndings` on a string.
+The following example normalizes text before persisting it, making the operation and its next step visible.
 
 ```csharp
 using X.Y.Z;
 
-namespace MyNamespace;
-
-public class Consumer
-{
-    public void Run()
-    {
-        string text = "first\r\nsecond";
-        string normalized = text.NormalizeLineEndings();
-        Console.WriteLine(normalized);
-    }
-}
+namespace TextImport;
+
+public class ImportedNote
+{
+    public string PrepareForStorage(string text)
+    {
+        return text.NormalizeLineEndings();
+    }
+}
 ```
 ````
 
@@ -205,10 +204,13 @@ Before completing documentation work, verify:
 - [ ] Public non-abstraction types have at least one type-page example.
 - [ ] Public extension methods have at least one explicit example, not only a table entry.
 - [ ] Package IDs and package-level usage evidence were inspected before type/member-only sample synthesis.
+- [ ] Every inventory row names exact evidence paths and a consumer task; generated metadata and the target overwrite file are not the sole evidence.
 - [ ] The example inventory maps each required public type and extension method to its example file, UID, source evidence, and chosen scenario.
 - [ ] Examples show a coherent consumer workflow, use related public types when helpful, and avoid placeholder-only `Consumer`/`MyNamespace` shells when a domain name is available.
+- [ ] No example is reflection-only, metadata-only, duplicated by UID, or built from `DocumentedTypeExample`, `DocumentedExtensionExample`, or generic `Describe()` scaffolding.
+- [ ] The C# fence itself uses the documented type or invokes the documented extension method; prose, comments, and strings are not counted as usage.
 - [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`. Namespace pages are under `api/namespaces/` and type pages are under `api/types/`.
-- [ ] The Completion Repair Loop was run after edits, and the final report has zero `EXAMPLE_MISSING`, namespace, extension, availability, overwrite-layout, sample, and DocFX-build diagnostics.
+- [ ] The Completion Repair Loop was run after edits, and the final report has zero missing/low-quality example, namespace-prose, extension, availability, overwrite-layout, sample, and DocFX-build diagnostics.
 - [ ] Examples are realistic, copy/paste-ready, and compile unless a justified skip marker is present.
 - [ ] Generated C# examples include a file-scoped namespace and a type declaration (class, struct, or record), or are explicitly labelled `// Program.cs`.
 - [ ] No generated C# example uses top-level statements without a `// Program.cs` label.

From e72d8b8bfaa15b4322352480ab409fde53fde8ba Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sun, 14 Jun 2026 03:17:23 +0200
Subject: [PATCH 68/88] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20enhance=20docfx=20sk?=
 =?UTF-8?q?ill=20implementation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Significantly expands docfx.cs with enhanced functionality for documentation analysis and generation. Adds test-quality.ps1 helper script for quality validation. Improves error handling, validation logic, and output formatting.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 281 +++++++++++++++---
 .../scripts/test-quality.ps1                  | 230 ++++++++++++++
 2 files changed, 474 insertions(+), 37 deletions(-)
 create mode 100644 skills/dotnet-docfx-digest/scripts/test-quality.ps1

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 414d031..362880a 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -3249,12 +3249,38 @@ private static void ValidateNamespacePage(string repoRoot, string page, string t
                 "Namespace page front matter is missing a 'summary' key (expected 'summary: *content')."));
         }
 
-        // fly-in paragraph
-        if (!HasFlyIn(body))
+        // Concept-led namespace prose. A namespace inventory is useful reference material, but it
+        // is not a developer-facing overview unless it explains when to use the surface and where
+        // a newcomer should begin.
+        var proseParagraphs = ExtractNamespaceProseParagraphs(body);
+        if (proseParagraphs.Count == 0)
         {
             report.Errors.Add(new Diagnostic("NAMESPACE_FLYIN_MISSING", rel, ns.Name,
                 "Namespace page has no human-written fly-in paragraph, or contains only placeholder text."));
         }
+        else
+        {
+            var firstParagraph = proseParagraphs[0];
+            var prose = string.Join(" ", proseParagraphs.Take(3));
+            if (IsInventoryOnlyNamespaceProse(firstParagraph))
+            {
+                report.Errors.Add(new Diagnostic("NAMESPACE_PROSE_INVENTORY_ONLY", rel, ns.Name,
+                    "The namespace overview only inventories types or extension methods. Rewrite the opening around the developer problem it solves, the outcome it enables, and when a consumer should use it."));
+            }
+
+            if (!HasNamespaceUsageGuidance(prose))
+            {
+                report.Errors.Add(new Diagnostic("NAMESPACE_USAGE_GUIDANCE_MISSING", rel, ns.Name,
+                    "The namespace overview does not explain when or why a developer should use this API surface. Add concrete usage guidance grounded in source, tests, or package documentation."));
+            }
+
+            var surfaceSize = ns.RequiredExampleTargets.Count + ns.ExtensionMethods.Count;
+            if (surfaceSize > 1 && !HasNamespaceStartHereGuidance(prose))
+            {
+                report.Errors.Add(new Diagnostic("NAMESPACE_START_HERE_MISSING", rel, ns.Name,
+                    "The namespace exposes multiple public entry points but does not direct a newcomer to a useful starting type or method. Name the API to start with and distinguish the nearby alternatives."));
+            }
+        }
 
         // availability
         if (!HasAvailability(body))
@@ -3341,36 +3367,85 @@ private static void ValidateExtensionSection(string rel, string body, NamespaceI
         }
     }
 
-    private static bool HasFlyIn(string body)
+    private static List<string> ExtractNamespaceProseParagraphs(string body)
     {
-        foreach (var raw in body.Split('\n'))
+        var paragraphs = new List<string>();
+        var current = new List<string>();
+        var inFence = false;
+
+        void Flush()
+        {
+            if (current.Count == 0)
+            {
+                return;
+            }
+
+            var paragraph = string.Join(" ", current).Trim();
+            current.Clear();
+            if (paragraph.Length >= 20 &&
+                !paragraph.Contains("...", StringComparison.Ordinal) &&
+                !paragraph.Contains("TODO", StringComparison.OrdinalIgnoreCase) &&
+                !paragraph.EndsWith("contains types that", StringComparison.OrdinalIgnoreCase))
+            {
+                paragraphs.Add(paragraph);
+            }
+        }
+
+        foreach (var raw in body.Replace("\r\n", "\n", StringComparison.Ordinal).Replace('\r', '\n').Split('\n'))
         {
             var line = raw.Trim();
-            if (line.Length == 0)
+            if (line.StartsWith("```", StringComparison.Ordinal))
             {
+                Flush();
+                inFence = !inFence;
                 continue;
             }
 
-            if (line.StartsWith('#') || line.StartsWith('|') || line.StartsWith("[!INCLUDE", StringComparison.OrdinalIgnoreCase) ||
-                line.StartsWith("```", StringComparison.Ordinal) || line.StartsWith("---", StringComparison.Ordinal))
+            if (inFence)
             {
                 continue;
             }
 
-            // Reject template placeholders like "contains types that ..." or bare ellipses / TODO.
-            if (line.Contains("...", StringComparison.Ordinal) || line.Contains("TODO", StringComparison.OrdinalIgnoreCase) ||
-                line.EndsWith("contains types that", StringComparison.OrdinalIgnoreCase))
+            if (line.Length == 0)
             {
+                Flush();
                 continue;
             }
 
-            if (line.Length >= 20)
+            if (line.StartsWith('#') || line.StartsWith('|') || line.StartsWith("[!INCLUDE", StringComparison.OrdinalIgnoreCase) ||
+                line.StartsWith("---", StringComparison.Ordinal) || line.StartsWith("<!--", StringComparison.Ordinal) ||
+                line.StartsWith("Availability:", StringComparison.OrdinalIgnoreCase) ||
+                line.StartsWith("Complements:", StringComparison.OrdinalIgnoreCase) ||
+                line.StartsWith("Related:", StringComparison.OrdinalIgnoreCase))
             {
-                return true;
+                Flush();
+                continue;
             }
+
+            current.Add(line);
         }
 
-        return false;
+        Flush();
+        return paragraphs;
+    }
+
+    private static bool IsInventoryOnlyNamespaceProse(string paragraph)
+    {
+        return Regex.IsMatch(paragraph,
+            @"(?i)^(?:the\s+)?(?:`?[\w.]+`?\s+)?namespace\s+(?:contains|provides|includes|exposes|groups|collects)\b") &&
+               !HasNamespaceUsageGuidance(paragraph);
+    }
+
+    private static bool HasNamespaceUsageGuidance(string prose)
+    {
+        return Regex.IsMatch(prose,
+            @"(?i)\b(?:use(?:ful)?\b|when\b|choose\b|prefer\b|reach for\b|designed for\b|suited for\b|helps?\b|enables?\b|lets?\s+you\b|so that\b|without having to\b)");
+    }
+
+    private static bool HasNamespaceStartHereGuidance(string prose)
+    {
+        return Regex.IsMatch(prose,
+            @"(?i)\b(?:start with|begin with|entry point|first reach for|reach for|choose|prefer|use\s+`?[A-Z][A-Za-z0-9_]*(?:<[^>]+>)?`?\s+(?:to|when|for|as))\b");
     }
 
     private static bool HasAvailability(string body)
@@ -3390,6 +3465,22 @@ private static bool HasAvailability(string body)
     private static void ValidateRequiredExamples(string repoRoot, string docfxWorkspace, IReadOnlyList<OverwriteSection> sections, ApiModel api,
         Options options, HashSet<string>? changedFiles, Report report)
     {
+        foreach (var duplicate in sections
+                     .Where(section => section.MappedToExample)
+                     .Where(section => !options.ChangedOnly || changedFiles is null ||
+                                       changedFiles.Contains(Path.GetFullPath(section.File)) ||
+                                       changedFiles.Any(IsChangedDocfxConfig))
+                     .GroupBy(section => section.Uid, StringComparer.Ordinal)
+                     .Where(group => group.Count() > 1))
+        {
+            var paths = duplicate.Select(section => Rel(repoRoot, section.File))
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase)
+                .ToList();
+            report.Errors.Add(new Diagnostic("EXAMPLE_UID_DUPLICATE", string.Join(", ", paths), NamespaceFromUid(duplicate.Key),
+                $"UID `{duplicate.Key}` is mapped to {duplicate.Count()} example sections. Keep one coherent, scenario-led example for a UID; merge or remove the duplicate `example: *content` sections."));
+        }
+
         foreach (var target in api.RequiredExampleTargets)
         {
             if (options.ChangedOnly && changedFiles is not null &&
@@ -3399,7 +3490,18 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
             }
 
             var candidates = sections.Where(s => IsExampleCandidate(s, target)).ToList();
-            if (candidates.Any(s => HasExampleForTarget(s, target)))
+            var relatedExtensionMethods = target.Kind == ApiTargetKind.Type
+                ? api.RequiredExampleTargets
+                    .Where(candidate => candidate.Kind == ApiTargetKind.ExtensionMethod &&
+                                        string.Equals(candidate.DeclaringTypeUid, target.Uid, StringComparison.Ordinal))
+                    .Select(candidate => candidate.DisplayName)
+                    .Distinct(StringComparer.Ordinal)
+                    .ToList()
+                : new List<string>();
+            var qualityResults = candidates
+                .Select(section => ValidateExampleQuality(section, target, relatedExtensionMethods))
+                .ToList();
+            if (qualityResults.Any(result => result.Valid))
             {
                 report.Summary.RequiredExamples++;
                 continue;
@@ -3414,6 +3516,20 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
                     ? null
                     : Rel(repoRoot, Path.Combine(docfxWorkspace, "api", "namespaces", $"{target.DeclaringTypeUid}.md"));
 
+            if (qualityResults.Count > 0)
+            {
+                var qualityFailure = qualityResults
+                    .Where(result => !result.Valid && result.Code is not null)
+                    .OrderBy(result => result.Priority)
+                    .FirstOrDefault();
+                if (qualityFailure is not null)
+                {
+                    report.Errors.Add(new Diagnostic(qualityFailure.Code!, expectedPath, target.Namespace,
+                        qualityFailure.Message ?? "The example does not demonstrate the documented API."));
+                    continue;
+                }
+            }
+
             var message = target.Kind == ApiTargetKind.Type
                 ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}` in `{expectedPath}` or another overwrite file under `api/types/` that targets this exact type UID. Namespace overview examples do not satisfy this diagnostic. Keep `api/types/**/*.md` under `build.overwrite`, exclude `api/types/**` from `build.content`, and do not use `api/**/*.md` under either section."
                 : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to the declaring extension class uid `{expectedUid}` or the namespace page `{target.Namespace}` by default. The example must explicitly call `{target.DisplayName}`. Do not create URL-encoded or hash-like method UID filenames; use a method UID section only when the exact generated UID is verified and can live in a readable overwrite file.";
@@ -3517,41 +3633,113 @@ private static bool IsExampleCandidate(OverwriteSection section, ApiTargetInfo t
         return false;
     }
 
-    private static bool HasExampleForTarget(OverwriteSection section, ApiTargetInfo target)
+    private static ExampleQualityResult ValidateExampleQuality(
+        OverwriteSection section, ApiTargetInfo target, IReadOnlyList<string> relatedExtensionMethods)
     {
         // MappedToExample (front-matter example: *content or - *content) only requires
         // a bare csharp fence; the heading is added automatically by DocFX.
         // The summary: *content form (MappedToExample=false) still requires the explicit
         // heading to delimit the embedded example within conceptual content.
-        var hasFence = section.MappedToExample
-            ? HasCSharpFence(section.Body)
-            : HasExampleSectionWithCSharpFence(section.Body);
+        var scope = section.MappedToExample ? section.Body : ExtractExampleSection(section.Body);
+        var codeBlocks = ExtractCSharpCodeBlocks(scope);
+        if (codeBlocks.Count == 0)
+        {
+            return new ExampleQualityResult(false, "EXAMPLE_MISSING",
+                $"The overwrite section for `{target.DisplayName}` does not contain a C# fence in its mapped example content.", 50);
+        }
 
-        if (!hasFence)
+        var combinedCode = string.Join(Environment.NewLine, codeBlocks);
+        if (Regex.IsMatch(section.Body,
+                @"(?i)\b(?:the documented type|the documented extension method|documented API at runtime|starting point for the extension surface)\b") ||
+            Regex.IsMatch(combinedCode,
+                @"(?i)\b(?:DocumentedTypeExample|DocumentedExtensionExample|Cuemon\.DocFxExamples)\b") ||
+            Regex.IsMatch(combinedCode,
+                @"(?is)\bclass\s+\w*(?:Documented|Example)\w*\b.*\b(?:string|Type)\s+Describe\s*\(\s*\)"))
         {
-            return false;
+            return new ExampleQualityResult(false, "EXAMPLE_PLACEHOLDER",
+                $"The example for `{target.DisplayName}` contains generic generated scaffolding instead of a consumer scenario. Replace placeholder prose and helper names with a focused example derived from tests, source, or package documentation.", 10);
         }
 
-        if (target.Kind == ApiTargetKind.ExtensionMethod &&
-            !section.Body.Contains(target.DisplayName, StringComparison.Ordinal))
+        var codeWithoutCommentsOrStrings = StripCodeCommentsAndStrings(combinedCode);
+        var hasReflectionLookup = Regex.IsMatch(combinedCode, @"\b(?:Type|Assembly)\.GetType\s*\(") ||
+                                  Regex.IsMatch(combinedCode, @"\.Assembly\.GetType\s*\(");
+
+        if (target.Kind == ApiTargetKind.ExtensionMethod)
         {
-            return false;
+            if (!HasMethodInvocation(codeWithoutCommentsOrStrings, target.DisplayName))
+            {
+                if (hasReflectionLookup)
+                {
+                    return new ExampleQualityResult(false, "EXAMPLE_REFLECTION_ONLY",
+                        $"The example for `{target.DisplayName}` substitutes reflection metadata lookup for an extension-method call. Show a real receiver and invoke the method in C#.", 20);
+                }
+
+                return new ExampleQualityResult(false, "EXTENSION_EXAMPLE_NOT_INVOKED",
+                    $"The C# example for extension method `{target.DisplayName}` never invokes that method. Mentions in prose, comments, strings, or metadata lookups do not satisfy the example requirement.", 30);
+            }
+
+            return ExampleQualityResult.Success;
         }
 
-        return true;
+        var usesTargetType = Regex.IsMatch(codeWithoutCommentsOrStrings,
+            $@"\b{Regex.Escape(target.DisplayName)}\b");
+        var invokesRelatedExtension = relatedExtensionMethods.Any(method =>
+            HasMethodInvocation(codeWithoutCommentsOrStrings, method));
+        if (!usesTargetType && !invokesRelatedExtension)
+        {
+            if (hasReflectionLookup)
+            {
+                return new ExampleQualityResult(false, "EXAMPLE_REFLECTION_ONLY",
+                    $"The example for `{target.DisplayName}` substitutes reflection metadata lookup for real API use. Show a real input, construct or call the API, and make the result or next action visible.", 20);
+            }
+
+            return new ExampleQualityResult(false, "EXAMPLE_TARGET_NOT_USED",
+                $"The C# example mapped to `{target.Uid}` does not use `{target.DisplayName}`. Reference or exercise the documented type in code; mentions in prose, comments, strings, `typeof`, `nameof`, or reflection do not count.", 40);
+        }
+
+        var metadataOnly = Regex.Replace(codeWithoutCommentsOrStrings,
+            $@"\b(?:typeof|nameof)\s*\(\s*{Regex.Escape(target.DisplayName)}(?:<[^>]+>)?\s*\)", string.Empty);
+        if (!invokesRelatedExtension && !Regex.IsMatch(metadataOnly, $@"\b{Regex.Escape(target.DisplayName)}\b"))
+        {
+            return new ExampleQualityResult(false, "EXAMPLE_TARGET_NOT_USED",
+                $"The C# example for `{target.DisplayName}` only names the type as metadata. Construct it, call it, configure it, or otherwise demonstrate a consumer-visible operation.", 40);
+        }
+
+        return ExampleQualityResult.Success;
+    }
+
+    private static string StripCodeCommentsAndStrings(string code)
+    {
+        var lines = code.Replace("\r\n", "\n", StringComparison.Ordinal).Replace('\r', '\n').Split('\n');
+        return string.Join("\n", StripCommentsAndStrings(lines));
     }
 
-    private static bool HasCSharpFence(string body)
+    private static bool HasMethodInvocation(string code, string methodName)
     {
-        return Regex.IsMatch(body, @"(?im)^```\s*(csharp|cs)\s*$");
+        return Regex.IsMatch(code,
+            $@"(?:\.|\b){Regex.Escape(methodName)}(?:\s*<[^>\r\n]+>)?\s*\(");
     }
 
-    private static bool HasExampleSectionWithCSharpFence(string body)
+    private static List<string> ExtractCSharpCodeBlocks(string body)
+    {
+        if (string.IsNullOrEmpty(body))
+        {
+            return new List<string>();
+        }
+
+        var normalized = body.Replace("\r\n", "\n", StringComparison.Ordinal).Replace('\r', '\n');
+        return Regex.Matches(normalized,
+                @"(?ms)^```\s*(?:csharp|cs)\s*$\n(?<code>.*?)^```\s*$")
+            .Select(match => match.Groups["code"].Value)
+            .ToList();
+    }
+
+    private static string ExtractExampleSection(string body)
     {
         var match = Regex.Match(body, @"(?im)^#{2,5}\s+Examples?\s*$");
         if (!match.Success)
         {
-            return false;
+            return string.Empty;
         }
 
         var section = body[match.Index..];
@@ -3561,7 +3749,7 @@ private static bool HasExampleSectionWithCSharpFence(string body)
             section = section[..(match.Length + nextHeading.Index)];
         }
 
-        return Regex.IsMatch(section, @"(?im)^```\s*(csharp|cs)\s*$");
+        return section;
     }
 
     // ----------------------------------------------------------------------
@@ -4935,8 +5123,8 @@ private static string BuildRepairPlan(Report report)
             e.Code.StartsWith("ENCODING_", StringComparison.Ordinal)));
         AppendDiagnostics(sb, "Namespace And Extension Table Repairs", report.Errors.Where(e =>
             e.Code.StartsWith("NAMESPACE_", StringComparison.Ordinal) ||
-            e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal)));
-        AppendRequiredExampleDiagnostics(sb, report.Errors.Where(e => e.Code is "EXAMPLE_MISSING"), report.PackageIds);
+            e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal) && !IsExampleQualityDiagnostic(e)));
+        AppendRequiredExampleDiagnostics(sb, report.Errors.Where(IsExampleQualityDiagnostic), report.PackageIds);
         AppendGitHubExampleSources(sb, report.PackageIds, report.ExampleSearchSnippets);
         AppendDiagnostics(sb, "Sample Compilation Repairs", report.Errors.Where(e =>
             e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_SKIP_REASON_MISSING" or "SAMPLE_SKIP_REASON_INSUFFICIENT" or "SAMPLE_STRUCTURE_INVALID"));
@@ -4945,7 +5133,7 @@ e.Code is not "AGENTS_BLOCK_MISSING" &&
             !e.Code.StartsWith("ENCODING_", StringComparison.Ordinal) &&
             !e.Code.StartsWith("NAMESPACE_", StringComparison.Ordinal) &&
             !e.Code.StartsWith("EXTENSION_", StringComparison.Ordinal) &&
-            e.Code is not "EXAMPLE_MISSING" &&
+            !IsExampleQualityDiagnostic(e) &&
             e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_SKIP_REASON_MISSING" and not "SAMPLE_SKIP_REASON_INSUFFICIENT" and not "SAMPLE_STRUCTURE_INVALID"));
         AppendDiagnostics(sb, "Warnings", report.Warnings);
 
@@ -4955,7 +5143,7 @@ e.Code is not "EXAMPLE_MISSING" &&
         sb.AppendLine("- [ ] `ENCODING_CORRUPTION` files restored from git or rewritten using byte-level operations.");
         sb.AppendLine("- [ ] Every namespace and extension diagnostic above has been resolved; zero remain in the final report.");
         sb.AppendLine("- [ ] GitHub example sources consulted before writing any new example (see 'GitHub Example Sources' section).");
-        sb.AppendLine("- [ ] Every `EXAMPLE_MISSING` diagnostic above maps to a concrete example location.");
+        sb.AppendLine("- [ ] Every missing, duplicate, placeholder, reflection-only, target-use, and extension-invocation example diagnostic above has been resolved.");
         sb.AppendLine("- [ ] Changed C# examples pass structural validation (namespace + type declaration, or labelled `// Program.cs`).");
         sb.AppendLine("- [ ] Changed C# examples compile as a class library project referencing the documented assemblies.");
         sb.AppendLine("- [ ] Authored Markdown files still exist after generated-artifact cleanup.");
@@ -5070,15 +5258,29 @@ private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerab
             var ns = EscapeTable(diagnostic.Namespace ?? "(repository)");
             var path = EscapeTable(string.IsNullOrWhiteSpace(diagnostic.Path) ? "(method UID, declaring type UID, or namespace page)" : diagnostic.Path);
             var message = EscapeTable(diagnostic.Message);
-            var action = diagnostic.Message.Contains("Public non-abstraction type", StringComparison.Ordinal)
-                ? "Search GitHub (see below), verify public API surface, create or update the type-targeting overwrite file under `api/types/`, keep `api/types/**/*.md` under `build.overwrite` only, add a compiling Examples section, then rerun validation."
-                : "Search GitHub (see below), verify public API surface, add a compiling Examples section on the declaring extension class or namespace page that explicitly calls the extension method, then rerun validation.";
-            sb.AppendLine($"| {ns} | `{path}` | `EXAMPLE_MISSING` | {EscapeTable(action)} {message} |");
+            var action = diagnostic.Code switch
+            {
+                "EXAMPLE_UID_DUPLICATE" => "Merge the duplicate mappings into one coherent example section for the UID, then rerun validation.",
+                "EXAMPLE_PLACEHOLDER" or "EXAMPLE_REFLECTION_ONLY" or "EXAMPLE_TARGET_NOT_USED" =>
+                    "Inspect exact test, package README, sample, XML-comment, or source evidence; replace the scaffold with a consumer task that uses the target in C# and exposes a result or next action.",
+                "EXTENSION_EXAMPLE_NOT_INVOKED" =>
+                    "Replace prose-only or metadata-only coverage with a C# scenario that invokes the extension method on a valid receiver.",
+                _ when diagnostic.Message.Contains("Public non-abstraction type", StringComparison.Ordinal) =>
+                    "Search GitHub (see below), verify public API surface, create or update the type-targeting overwrite file under `api/types/`, keep `api/types/**/*.md` under `build.overwrite` only, add a compiling Examples section, then rerun validation.",
+                _ => "Search GitHub (see below), verify public API surface, add a compiling Examples section on the declaring extension class or namespace page that explicitly calls the extension method, then rerun validation."
+            };
+            sb.AppendLine($"| {ns} | `{path}` | `{diagnostic.Code}` | {EscapeTable(action)} {message} |");
         }
 
         sb.AppendLine();
     }
 
+    private static bool IsExampleQualityDiagnostic(Diagnostic diagnostic)
+    {
+        return diagnostic.Code is "EXAMPLE_MISSING" or "EXAMPLE_UID_DUPLICATE" or "EXAMPLE_PLACEHOLDER" or
+            "EXAMPLE_REFLECTION_ONLY" or "EXAMPLE_TARGET_NOT_USED" or "EXTENSION_EXAMPLE_NOT_INVOKED";
+    }
+
     private static string EscapeTable(string value)
     {
         return value.Replace("|", "\\|", StringComparison.Ordinal).ReplaceLineEndings(" ");
@@ -5455,6 +5657,11 @@ private sealed record SampleFence(string File, int FenceIndex, int StartLine, st
 
     private sealed record OverwriteSection(string File, string Uid, string Body, bool MappedToExample = false);
 
+    private sealed record ExampleQualityResult(bool Valid, string? Code, string? Message, int Priority)
+    {
+        public static ExampleQualityResult Success { get; } = new(true, null, null, int.MaxValue);
+    }
+
     private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr);
 
     private sealed record ProcessProgress(string Phase, string Detail);
diff --git a/skills/dotnet-docfx-digest/scripts/test-quality.ps1 b/skills/dotnet-docfx-digest/scripts/test-quality.ps1
new file mode 100644
index 0000000..cda5771
--- /dev/null
+++ b/skills/dotnet-docfx-digest/scripts/test-quality.ps1
@@ -0,0 +1,230 @@
+param(
+    [string]$ValidatorPath = (Join-Path $PSScriptRoot 'docfx.cs')
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+$utf8NoBom = [System.Text.UTF8Encoding]::new($false)
+$workspace = Join-Path ([System.IO.Path]::GetTempPath()) ('dotnet-docfx-quality-' + [guid]::NewGuid().ToString('N'))
+
+function Write-Utf8File {
+    param([string]$Path, [string]$Content)
+
+    $directory = Split-Path -Parent $Path
+    if (-not (Test-Path $directory)) {
+        New-Item -ItemType Directory -Path $directory -Force | Out-Null
+    }
+
+    [System.IO.File]::WriteAllText($Path, $Content, $utf8NoBom)
+}
+
+function Invoke-Validator {
+    $output = & dotnet run --file $ValidatorPath -- --repo-root $workspace --json 2>$null
+    if ([string]::IsNullOrWhiteSpace(($output -join "`n"))) {
+        throw 'DocFX validator returned no JSON output.'
+    }
+
+    return (($output -join "`n") | ConvertFrom-Json)
+}
+
+function Assert-Diagnostic {
+    param([object]$Report, [string]$Code)
+
+    if (-not @($Report.errors | Where-Object code -eq $Code)) {
+        throw "Expected diagnostic '$Code' was not reported."
+    }
+}
+
+try {
+    $arrow = "$([char]0x2B07)$([char]0xFE0F)"
+    Write-Utf8File (Join-Path $workspace 'AGENTS.md') @'
+<!-- dotnet-docfx-digest:start -->
+Managed DocFX guidance.
+<!-- dotnet-docfx-digest:end -->
+'@
+    Write-Utf8File (Join-Path $workspace 'src/Acme.Core.csproj') @'
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+  </PropertyGroup>
+</Project>
+'@
+    Write-Utf8File (Join-Path $workspace 'src/Api.cs') @'
+namespace Acme.Core;
+
+public sealed class Options
+{
+    public int Attempts { get; set; }
+}
+
+public static class StringExtensions
+{
+    public static string Normalize(this string value)
+    {
+        return value.Trim().ToUpperInvariant();
+    }
+}
+'@
+    Write-Utf8File (Join-Path $workspace '.docfx/docfx.json') @'
+{
+  "metadata": [{
+    "src": [{ "src": "../", "files": ["src/Acme.Core.csproj"] }],
+    "dest": "api",
+    "properties": { "TargetFramework": "net10.0" }
+  }],
+  "build": {
+    "content": [{ "files": ["*.md"], "exclude": ["api/namespaces/**", "api/types/**"] }],
+    "overwrite": [{ "files": ["api/namespaces/**/*.md", "api/types/**/*.md"] }],
+    "dest": "_site"
+  }
+}
+'@
+
+    Write-Utf8File (Join-Path $workspace '.docfx/api/namespaces/Acme.Core.md') @"
+---
+uid: Acme.Core
+summary: *content
+---
+The Acme.Core namespace contains types and extension methods for common work.
+
+Availability: `Acme.Core`
+
+## Extension Members
+
+|Type|Ext|Methods|
+|---|---|---|
+|String|$arrow|``Normalize``|
+"@
+    Write-Utf8File (Join-Path $workspace '.docfx/api/types/Acme.Core.Options.md') @'
+---
+uid: Acme.Core.Options
+example: *content
+---
+```csharp
+namespace Samples;
+
+public static class MetadataLookup
+{
+    public static Type? Find() => Type.GetType("Acme.Core.Options, Acme.Core");
+}
+```
+'@
+    Write-Utf8File (Join-Path $workspace '.docfx/api/namespaces/Acme.Core.StringExtensions.md') @'
+---
+uid: Acme.Core.StringExtensions
+example: *content
+---
+The documented extension method is available at runtime.
+
+```csharp
+namespace Cuemon.DocFxExamples;
+
+public static class DocumentedExtensionExample
+{
+    public static string Describe() => "Normalize";
+}
+```
+
+---
+uid: Acme.Core.StringExtensions
+example: *content
+---
+The documented type is an extension surface.
+
+```csharp
+namespace Cuemon.DocFxExamples;
+
+public static class DocumentedTypeExample
+{
+    public static string Describe() => "StringExtensions";
+}
+```
+'@
+
+    $bad = Invoke-Validator
+    foreach ($code in @(
+        'NAMESPACE_PROSE_INVENTORY_ONLY',
+        'NAMESPACE_USAGE_GUIDANCE_MISSING',
+        'NAMESPACE_START_HERE_MISSING',
+        'EXAMPLE_UID_DUPLICATE',
+        'EXAMPLE_REFLECTION_ONLY',
+        'EXAMPLE_PLACEHOLDER'
+    )) {
+        Assert-Diagnostic -Report $bad -Code $code
+    }
+
+    Write-Utf8File (Join-Path $workspace '.docfx/api/namespaces/Acme.Core.md') @"
+---
+uid: Acme.Core
+summary: *content
+---
+Use ``Options`` when a caller needs to keep retry policy values together before configuring a client. It gives validation and composition code one explicit object to pass across boundaries.
+
+Start with ``Options`` for policy values; use ``Normalize`` at text-ingress boundaries when identifiers need stable casing and whitespace before comparison or storage.
+
+Availability: `Acme.Core`
+
+## Extension Members
+
+|Type|Ext|Methods|
+|---|---|---|
+|String|$arrow|``Normalize``|
+"@
+    Write-Utf8File (Join-Path $workspace '.docfx/api/types/Acme.Core.Options.md') @'
+---
+uid: Acme.Core.Options
+example: *content
+---
+```csharp
+namespace Samples;
+
+using Acme.Core;
+
+public static class RetryConfiguration
+{
+    public static Options Create() => new() { Attempts = 3 };
+}
+```
+'@
+    Write-Utf8File (Join-Path $workspace '.docfx/api/namespaces/Acme.Core.StringExtensions.md') @'
+---
+uid: Acme.Core.StringExtensions
+example: *content
+---
+```csharp
+namespace Samples;
+
+using Acme.Core;
+
+public static class IdentifierInput
+{
+    public static string Prepare(string value) => value.Normalize();
+}
+```
+'@
+
+    $good = Invoke-Validator
+    $qualityCodes = @(
+        'NAMESPACE_FLYIN_MISSING',
+        'NAMESPACE_PROSE_INVENTORY_ONLY',
+        'NAMESPACE_USAGE_GUIDANCE_MISSING',
+        'NAMESPACE_START_HERE_MISSING',
+        'EXAMPLE_UID_DUPLICATE',
+        'EXAMPLE_PLACEHOLDER',
+        'EXAMPLE_REFLECTION_ONLY',
+        'EXAMPLE_TARGET_NOT_USED',
+        'EXTENSION_EXAMPLE_NOT_INVOKED',
+        'EXAMPLE_MISSING'
+    )
+    $remaining = @($good.errors | Where-Object { $_.code -in $qualityCodes })
+    if ($remaining.Count -gt 0) {
+        throw "Scenario-led fixture still has quality diagnostics: $($remaining.code -join ', ')"
+    }
+
+    Write-Host 'DocFX semantic quality regression passed.'
+} finally {
+    if (Test-Path $workspace) {
+        Remove-Item -Path $workspace -Recurse -Force
+    }
+}

From bf9018e5863fc56c1951921fbbb74c0f8d82c666 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Sun, 14 Jun 2026 03:17:31 +0200
Subject: [PATCH 69/88] =?UTF-8?q?=F0=9F=93=9D=20update=20available=20skill?=
 =?UTF-8?q?s=20in=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refreshes the dotnet-docfx-digest skill entry to reflect recent enhancements to workflow documentation, contract structure, and implementation capabilities.
---
 README.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3850e0b..65b1be2 100644
--- a/README.md
+++ b/README.md
@@ -545,11 +545,12 @@ API documentation rots the moment code changes. A new public type ships without
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
 - **Verification without a build, precision on demand** — by default `scripts/docfx.cs` discovers public API, namespaces, and extension methods without compiling: it reads existing DocFX ManagedReference YAML under `metadata.dest` when present, otherwise runs a conservative source scan over the projects referenced by `docfx.json`, and warns (`API_MODEL_SOURCE_SCANNER_LIMITED`) that the precise path is opt-in. Adding `--build-api-model` (alias `--strict-api-discovery`) builds only the documented project graph through a single scoped `.slnx` graph build and discovers from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution,
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
-- **Real namespace-page checks** — uid front matter, a human-written fly-in, availability, and `Extension Members` tables are validated against the actual public surface, with deterministic error codes like `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISMATCH`, and `EXTENSION_METHOD_MISSING`,
+- **Decision-useful namespace checks** — uid front matter, availability, and `Extension Members` tables are validated against the actual public surface, while semantic gates reject inventory-only prose and require concrete when-to-use and start-here guidance with diagnostics such as `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
-- **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/namespaces/`, legacy authored `.docfx/api/*.md` overwrite files are moved into that folder instead of widening the glob to `api/**/*.md`, `api/namespaces/**/*.md` stays under `build.overwrite` only while `build.content` excludes `api/namespaces/**`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, namespace examples and tables alone are treated as incomplete documentation and reported as `EXAMPLE_MISSING`, and agents must rerun the completion repair loop until those diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
+- **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/types/`, legacy authored `.docfx/api/*.md` overwrite files move into `api/namespaces/` or `api/types/` instead of widening the glob to `api/**/*.md`, both overwrite trees stay excluded from `build.content`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, and agents must rerun the completion repair loop until diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
 - **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
 - **Examples that teach a real workflow** — examples start from package IDs and package-level evidence before falling back to type/member-only searches, prefer README, package docs, tooling, tuning, functional-test, and external GitHub usage when available, and may include multiple related public types when that is what makes the consumer scenario understandable,
+- **Semantic example quality gates** — compilation-valid filler no longer passes: the validator rejects duplicate UID mappings, `Type.GetType`/assembly metadata scaffolds, generic `DocumentedTypeExample`/`Describe()` templates, type examples that never use the target in code, and extension examples that mention a method only in prose instead of invoking it,
 - **Examples that actually compile** — under the opt-in `--validate-samples` path, every `csharp`/`cs` documentation fence is compiled in its own isolated project; all sample projects are batched into one temporary `.slnx` graph build so shared dependencies restore and build once, `--sample-parallelism` bounds MSBuild concurrency, each sample references only the documented project(s) that own its namespace rather than every library project, and failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,

From 355ed970c9bdce04dbf85d99d5900a607afe8673 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 00:02:06 +0200
Subject: [PATCH 70/88] =?UTF-8?q?=F0=9F=94=A8=20extend=20repo=20validation?=
 =?UTF-8?q?=20tooling?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds additional validation checks to validate-skill-templates.ps1 for ensuring repository-managed skill consistency and Anthropic convention compliance.
---
 scripts/validate-skill-templates.ps1 | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1
index eacc361..6fcf1ed 100644
--- a/scripts/validate-skill-templates.ps1
+++ b/scripts/validate-skill-templates.ps1
@@ -1115,6 +1115,14 @@ Add-ValidationResult -Results $results -Name 'DocFX digest rejects metadata scaf
     }
 }
 
+Add-ValidationResult -Results $results -Name 'DocFX digest project-scoped packets, dry run, families, and overwrite writer behave deterministically' -Action {
+    $scopeTest = Join-Path $repoRoot 'skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1'
+    & $scopeTest
+    if ($LASTEXITCODE -ne 0) {
+        throw "DocFX project-scoped regression failed with exit code $LASTEXITCODE."
+    }
+}
+
 $passed = @($results | Where-Object { $_.Status -eq 'PASS' }).Count
 $failed = @($results | Where-Object { $_.Status -eq 'FAIL' }).Count
 $label = if ([string]::IsNullOrWhiteSpace($Ref)) { 'WORKTREE' } else { $Ref }

From aad6a5b6db612d01c8a4a96d44477a597bbe119a Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 00:02:16 +0200
Subject: [PATCH 71/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comprehensively restructures SKILL.md with improved progressive disclosure, consolidates workflow and script references, expands eval test coverage, and enhances reference material for DocFX digest generation patterns.
---
 skills/dotnet-docfx-digest/SKILL.md           | 503 +++++++++---------
 skills/dotnet-docfx-digest/evals/evals.json   | 154 ++++++
 .../references/docfx-overwrite-files.md       |  26 +
 .../dotnet-docfx-digest/references/scripts.md |  26 +-
 .../references/workflow.md                    | 416 +++++++++------
 5 files changed, 703 insertions(+), 422 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 0993b03..274dbc0 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -1,48 +1,48 @@
----
-name: dotnet-docfx-digest
-description: >
-  Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including repo-wide no-input audits, concept-led namespace overview pages, purpose-first type/member summaries, extension-member documentation, overwrite files, examples, availability notes, AGENTS.md maintenance, and verification. Use when the user asks to document a .NET API, create or update DocFX documentation, write namespace overview pages, improve API summaries, add extension-method tables, update XML documentation comments, add API examples, maintain DocFX overwrite files, or verify documentation builds. Treat requests like "use dotnet-docfx-digest", "update the DocFX docs", "complete missing documentation", "create namespace pages", "improve these API summaries", "add examples for this type", "update the extension members table", or "verify the documentation builds" as automatic triggers. Also use whenever public .NET API surface changes and documentation needs to stay aligned with source code.
----
-
-# .NET DocFX Digest Steward
-
-## Description
-
-Create and maintain developer-friendly DocFX documentation digests for .NET public APIs. Keep namespace pages, generated API pages, examples, availability notes, and verification aligned with the actual source code and tests.
-
-## Critical
-
-- This skill is autonomous by default. If the user invokes it without naming a namespace, type, member, or changed API, treat the request as a repo-wide DocFX audit and repair task instead of asking what to document first.
-- Resolve bundled scripts from the loaded `dotnet-docfx-digest` skill directory first. If that install path is unavailable and the target repository contains the repo-managed source copy, fall back to `skills/dotnet-docfx-digest/scripts/*.cs`. Do not claim the scripts are unavailable until both locations have been checked.
-- `docfx.cs` is fast by default: a plain run validates Markdown, prose, DocFX overwrite layout, namespace pages, extension tables, and required examples **without building, restoring, or running DocFX/gh**. Use it freely during iteration — it discovers the public API from existing DocFX YAML metadata or a conservative source scan, and ends with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary. Compilation and network access are opt-in.
-- Iterate quickly with the fast path, reading diagnostics as the next work queue:
-
-```bash
-dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --json
-```
-
-- Before claiming completion, run `agents.cs`, then a thorough build-backed verification that compiles samples, uses reflection-backed API discovery, and verifies the DocFX build:
-
-```bash
-dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-root>
-dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --build-api-model --validate-samples --verify-docfx-build
-```
-
+---
+name: dotnet-docfx-digest
+description: >
+  Create and maintain developer-friendly DocFX documentation digests for .NET public APIs, including repo-wide no-input audits, concept-led namespace overview pages, purpose-first type/member summaries, extension-member documentation, overwrite files, examples, availability notes, AGENTS.md maintenance, and verification. Use when the user asks to document a .NET API, create or update DocFX documentation, write namespace overview pages, improve API summaries, add extension-method tables, update XML documentation comments, add API examples, maintain DocFX overwrite files, or verify documentation builds. Treat requests like "use dotnet-docfx-digest", "update the DocFX docs", "complete missing documentation", "create namespace pages", "improve these API summaries", "add examples for this type", "update the extension members table", or "verify the documentation builds" as automatic triggers. Also use whenever public .NET API surface changes and documentation needs to stay aligned with source code.
+---
+
+# .NET DocFX Digest Steward
+
+## Description
+
+Create and maintain developer-friendly DocFX documentation digests for .NET public APIs. Keep namespace pages, generated API pages, examples, availability notes, and verification aligned with the actual source code and tests.
+
+## Critical
+
+- This skill is autonomous by default. If the user invokes it without naming a namespace, type, member, or changed API, treat the request as a repo-wide DocFX audit and repair task instead of asking what to document first.
+- Resolve bundled scripts from the loaded `dotnet-docfx-digest` skill directory first. If that install path is unavailable and the target repository contains the repo-managed source copy, fall back to `skills/dotnet-docfx-digest/scripts/*.cs`. Do not claim the scripts are unavailable until both locations have been checked.
+- `docfx.cs` is fast by default: a plain run validates Markdown, prose, DocFX overwrite layout, namespace pages, extension tables, and required examples **without building, restoring, or running DocFX/gh**. Use it freely during iteration — it discovers the public API from existing DocFX YAML metadata or a conservative source scan, and ends with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary. Compilation and network access are opt-in.
+- Iterate quickly with the fast path, reading diagnostics as the next work queue:
+
+```bash
+dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --json
+```
+
+- Before claiming completion, run `agents.cs`, then a thorough build-backed verification that compiles samples, uses reflection-backed API discovery, and verifies the DocFX build:
+
+```bash
+dotnet run --file <resolved-skill-dir>/scripts/agents.cs -- --repo-root <repo-root>
+dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-root> --build-api-model --validate-samples --verify-docfx-build
+```
+
 - `--build-api-model` makes API discovery reflection-precise (the fast source-scan path is conservative and may under-report), `--validate-samples` compiles every C# documentation sample through isolated projects in one temporary `.slnx` graph build with bounded MSBuild parallelism, and `--verify-docfx-build` confirms the DocFX build succeeds. Treat `API_MODEL_SOURCE_SCANNER_LIMITED` in a fast run as a reminder to run the build-backed verification before completion, not as a failure.
-- For noisy audits, write and read a deterministic `--repair-plan` (works on the fast path; add `--search-examples` to embed real GitHub usage):
-
-```bash
-dotnet run --file docfx.cs -- --repo-root <repo-root> --json --repair-plan /tmp/docfx-repair-plan.md --search-examples
-```
-
-The repair plan includes a "GitHub Example Sources" section with pre-computed `gh search code` commands and GitHub search URLs for each documented package. Read that section before writing any new example — do not write examples from memory or invention when real source evidence is available. If `--search-examples` is provided and `gh` is authenticated, actual search results are embedded; otherwise, the search commands are ready to run.
-
-- `ENCODING_CORRUPTION` in the JSON output means a documentation file has double-encoded UTF-8 (mojibake). Restore with `git checkout HEAD -- <file>` if the committed version was correct, or use the edit tool or byte-level operations to rewrite the file safely. Never pipe content through `Get-Content` + `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes()` on documentation files that contain multi-byte characters or emoji.
-- `EXTENSION_TABLE_ENCODING` means the ⬇️ emoji (U+2B07) is missing or corrupted in an Extension Members table data row. Use the literal `⬇️` character, not HTML entities or text substitutes.
+- For noisy audits, write and read a deterministic `--repair-plan` (works on the fast path; add `--search-examples` to embed real GitHub usage):
+
+```bash
+dotnet run --file docfx.cs -- --repo-root <repo-root> --json --repair-plan /tmp/docfx-repair-plan.md --search-examples
+```
+
+The repair plan includes a "GitHub Example Sources" section with pre-computed `gh search code` commands and GitHub search URLs for each documented package. Read that section before writing any new example — do not write examples from memory or invention when real source evidence is available. If `--search-examples` is provided and `gh` is authenticated, actual search results are embedded; otherwise, the search commands are ready to run.
+
+- `ENCODING_CORRUPTION` in the JSON output means a documentation file has double-encoded UTF-8 (mojibake). Restore with `git checkout HEAD -- <file>` if the committed version was correct, or use the edit tool or byte-level operations to rewrite the file safely. Never pipe content through `Get-Content` + `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes()` on documentation files that contain multi-byte characters or emoji.
+- `EXTENSION_TABLE_ENCODING` means the ⬇️ emoji (U+2B07) is missing or corrupted in an Extension Members table data row. Use the literal `⬇️` character, not HTML entities or text substitutes.
 - If either script cannot run, report the exact command, exit code, and failure output. Do not claim repository guidance or documentation was verified unless the scripts actually ran successfully.
 - Treat validator errors as the repo-wide repair queue, not as evidence that the repository is "blocked." A diagnostic being old, pre-existing, numerous, or outside the first files edited does not remove it from scope. A run with 1,228 `EXAMPLE_MISSING` findings means 1,228 documentation items remain; repairing one type page is a partial result, not a digest.
-- Passing compilation is necessary but not sufficient. `EXAMPLE_PLACEHOLDER`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, and `EXAMPLE_UID_DUPLICATE` are blocking quality failures. Never satisfy the inventory with `Type.GetType`, assembly metadata inspection, `DocumentedTypeExample`, `DocumentedExtensionExample`, generic `Describe()` helpers, repeated UID sections, or prose that merely names the target.
-- Namespace prose must be decision-useful. `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING` mean the page still needs a problem/outcome opening, concrete "when to use" guidance, and a named starting API when the namespace has multiple entry points.
+- Passing compilation is necessary but not sufficient. `EXAMPLE_PLACEHOLDER`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, and `EXAMPLE_UID_DUPLICATE` are blocking quality failures. Never satisfy the inventory with `Type.GetType`, assembly metadata inspection, `DocumentedTypeExample`, `DocumentedExtensionExample`, generic `Describe()` helpers, repeated UID sections, prose that merely names the target, a `default!`/`null!` holder property that only parks the type, a class that just constructs or returns the target with no observable result, a mass-forwarding shell of one-line pass-through members, or one normalized code skeleton reused across unrelated types.
+- Namespace prose must be decision-useful. `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING` mean the page still needs a problem/outcome opening, a cohesively rewritten lead instead of a weak inventory sentence with guidance appended below it, an opening written from the namespace's own purpose rather than a shared template, concrete "when to use" guidance, and a named starting API when the namespace has multiple entry points.
 - Use the JSON completion contract as the final authority: completion requires `summary.canClaimCompletion` to be `true`, `summary.remainingWorkItems` to be `0`, `summary.remainingGates` and `summary.remainingDiagnosticsByCode` to be empty, and the build-backed command to succeed. A clean fast run reports `completionState: verification-required`; it is an iteration checkpoint, not completion. Never describe `status: failed`, `completionState: incomplete`, or `completionState: verification-required` as completed work.
 - Continue documentation repair when `dotnet test` fails for an unrelated environmental dependency such as an unavailable database. Report that test failure separately. It is a blocker only if it prevents the documentation validator, source inspection, or required sample compilation from running.
 - Valid BOM-less UTF-8 is compliant. The validator must not emit `ENCODING_BOM_MISSING` (that diagnostic is intentionally unsupported), and an audit must not add/remove BOMs or normalize line endings solely for consistency. BOM presence has no documentation value; preserve the file's existing state and continue detecting actual `ENCODING_CORRUPTION` and `EXTENSION_TABLE_ENCODING` damage.
@@ -52,18 +52,23 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 - When reporting adaptive execution, include the selected profile, processor and memory inputs, build/sample worker counts, timeout, concurrent/sequential choice, process counts, and phase timings from JSON. State that sample compilation follows API discovery because scoped references depend on the namespace-to-project map. Name CLI and environment overrides for profile, worker counts, and timeout when the user asks how to tune the run.
 - When reporting heartbeat behavior, state the complete contract: append-only `stderr`, no cursor-rewritten table, start and 10-second heartbeat events, final success/failure marker for all three long phases, latest non-empty child-output line when available, and plain redirected-log markers that do not depend on ANSI color. When reporting encoding safety, explicitly confirm the diff contains neither BOM-only nor line-ending-only changes.
 - Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape.
-
-## Completion Repair Loop
-
-Do not stop at namespace pages, extension-member tables, or a first-pass documentation edit.
-
-1. Run `docfx.cs --json` (fast, no-build) after edits and read the remaining diagnostics.
+- Prefer bounded project packets over one repository-sized authoring context. Discover packets with `docfx.cs --json` (`scope.packets`) or persist them with `--project-manifest <path>`; process one packet at a time and stop the whole run the moment a packet fails its quality gates. Establish reflection-precise scope with `--build-api-model` before authoring — when `summary.scopeState` is `provisional` and `BUILD_BACKED_SCOPE_REQUIRED` fires, the source-scan inventory must not authorize a full authoring run.
+- Honor the high-risk pilot stop. When `qualityRisk.highRisk` is true and `QUALITY_RISK_REVIEW_REQUIRED` is reported (more than 100 standalone or extension targets, a missing-to-existing ratio above 10:1, or any unresolved `SYMBOL_COLLISION_UNRESOLVED`/`EXTENSION_OWNER_AMBIGUOUS`), limit the first pass to one packet or 20 newly authored targets, manually review every changed namespace and type page, and get explicit user approval before continuing. Pass `--allow-high-risk` only as a deliberate, reviewed decision.
+- Dry run is a real run scoped to a representative subset, with identical evidence, authoring, quality, and compilation gates. Start it with `--dry-run --build-api-model --project-manifest <temp-path>`; this also emits a sibling `<name>.review.json` template. Author every selected packet, read every changed page, complete every review entry with evidence, page-specific purpose/outcome, observable result, and sibling prose/code comparison, then finish with `--resume-project-manifest <temp-path> --review-report <review-path> --build-api-model --validate-samples --verify-docfx-build`. The baseline protects pre-existing dirty work while allowing current-run files to verify. No-hint dry runs select one clean project per metadata destination group via a seed; explicit names override selection. Report `dry-run-passed` only after every gate passes, and include the completed `Changed-page review` table in the response; a validator summary is not a manual review. Never claim repository completion. Do not ask for hints when none were supplied. For large repositories, dry run is the mandatory quality pilot.
+- Use the safe structured overwrite writer (`docfx.cs --write-overwrite <request.json>`) for repeatable overwrite creation: it preserves BOM/line endings, rejects duplicate UIDs and unbalanced fences, and refuses to replace dirty files. It writes only content you authored — it never generates prose or examples.
+- Declare narrow family exemptions in `.docfx/family-exemptions.json` only for coherent generic-arity, inherited, overload, or type-parameter series. The anchor needs a real example and the namespace page must name it and explain sibling selection; category alone never exempts options, exceptions, delegates, records, or data carriers. See `references/workflow.md`.
+
+## Completion Repair Loop
+
+Do not stop at namespace pages, extension-member tables, or a first-pass documentation edit.
+
+1. Run `docfx.cs --json` (fast, no-build) after edits and read the remaining diagnostics.
 2. Treat every missing, placeholder, reflection-only, target-use, extension-invocation, duplicate-UID, namespace-prose, extension-table, availability, and overwrite-layout diagnostic as blocking follow-up work.
-3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/types/`.
-4. For each missing extension-method example, document it on the declaring extension class page or the namespace page, and explicitly demonstrate the method call.
+3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/types/`.
+4. For each missing extension-method example, document it on the declaring extension class page or the namespace page, and explicitly demonstrate the method call.
 5. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too and rerun until the JSON completion contract is clean.
 6. Do not convert repairable diagnostics into a blocker report. Stop incomplete only when the user pauses the task or an external condition still prevents progress after concrete attempts; report the exact blocker without claiming completion.
-
+
 Namespace pages and `Extension Members` tables complement type-page examples; they do not replace them. Both namespace pages (`api/namespaces/`) and type pages (`api/types/`) are required deliverables. Generating only one is incomplete work.
 
 ### Restarting Partial Audits
@@ -75,83 +80,83 @@ When continuing after another agent stopped with diagnostics remaining:
 3. Use the repair plan and example inventory as the active queue across all affected namespaces, type pages, extension classes, and extension methods.
 4. Repair manageable batches, then rerun the fast validator after each batch so the queue measurably shrinks; do not stop after a representative subset.
 5. Run the exact final command `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json` and continue until the completion contract is clean.
-
-## Core Principles
-
-Documentation is part of the public contract. When public .NET API changes, update the corresponding XML comments, DocFX overwrite content, namespace pages, examples, availability notes, and verification steps in the same change set.
-
-Document only what the code actually exposes. Do not invent APIs, overloads, target frameworks, behaviors, exceptions, or examples. Verify claims against source code, generated metadata, project files, tests, or existing documentation.
-
-Manual documentation is authoritative context. Preserve hand-written Markdown and overwrite content unless it is stale or incorrect. Prefer additive edits, but fix contradictions instead of appending conflicting prose.
-
-Namespace pages and type pages have different jobs. Namespace pages orient readers to the problem space and where to start; generated type pages explain concrete public APIs and must carry concrete examples for public non-abstraction types.
-
-Write with an inverted-pyramid structure. Lead with the problem solved, explain when to use the API, give a short “start here” cue when helpful, then add structural detail.
-
-## Safety Gates
-
-Before editing documentation:
-
-1. Run `git status --short` and identify modified, staged, and untracked documentation files.
-2. Treat existing uncommitted documentation changes as user work.
-3. Read each Markdown file before editing it.
-4. Classify any cleanup candidate as generated metadata, generated site output, build artifacts, or authored documentation before deleting anything.
-
-Do not use broad `git restore`, `git checkout --`, `git reset`, or whole-directory recovery commands on documentation source directories. If recovery is needed, recover only the specific generated or accidentally removed file after inspecting `git status` and `git diff`.
-
-After modifications, inspect `git diff` for touched documentation paths and confirm the diff contains only intended changes.
-
-## File Encoding Safety
-
+
+## Core Principles
+
+Documentation is part of the public contract. When public .NET API changes, update the corresponding XML comments, DocFX overwrite content, namespace pages, examples, availability notes, and verification steps in the same change set.
+
+Document only what the code actually exposes. Do not invent APIs, overloads, target frameworks, behaviors, exceptions, or examples. Verify claims against source code, generated metadata, project files, tests, or existing documentation.
+
+Manual documentation is authoritative context. Preserve hand-written Markdown and overwrite content unless it is stale or incorrect. Prefer additive edits, but fix contradictions instead of appending conflicting prose.
+
+Namespace pages and type pages have different jobs. Namespace pages orient readers to the problem space and where to start; generated type pages explain concrete public APIs and must carry concrete examples for public non-abstraction types.
+
+Write with an inverted-pyramid structure. Lead with the problem solved, explain when to use the API, give a short “start here” cue when helpful, then add structural detail.
+
+## Safety Gates
+
+Before editing documentation:
+
+1. Run `git status --short` and identify modified, staged, and untracked documentation files.
+2. Treat existing uncommitted documentation changes as user work.
+3. Read each Markdown file before editing it.
+4. Classify any cleanup candidate as generated metadata, generated site output, build artifacts, or authored documentation before deleting anything.
+
+Do not use broad `git restore`, `git checkout --`, `git reset`, or whole-directory recovery commands on documentation source directories. If recovery is needed, recover only the specific generated or accidentally removed file after inspecting `git status` and `git diff`.
+
+After modifications, inspect `git diff` for touched documentation paths and confirm the diff contains only intended changes.
+
+## File Encoding Safety
+
 Use UTF-8 for DocFX documentation, but treat the BOM as optional. DocFX does not need a UTF-8 BOM, and adding or removing one across existing files creates noisy diffs with no documentation value. Preserve each file's existing BOM and line-ending state unless the user explicitly requests normalization.
 
 - **Never use an encoding-ambiguous `Get-Content` / `Set-Content` round-trip.** Legacy Windows PowerShell can interpret BOM-less UTF-8 through an ANSI code page. Multi-byte UTF-8 sequences, including ⬇️ in `Extension Members` tables, can become mojibake even though the original file was valid.
 - **Prefer the `edit` tool** for all Markdown content edits; it preserves bytes correctly and avoids encoding round-trip issues entirely.
 - **Check `git status` before any encoding-rewriting operation.** If bytes are corrupted and the file was committed, `git checkout HEAD -- <file>` restores the committed version — but discards any uncommitted in-flight changes. Do not use that recovery if there are unsaved edits.
 - **Do not normalize encoding or line endings as part of a documentation audit.** A BOM-only or line-ending-only diff obscures substantive work. The validator reports actual corruption such as `ENCODING_CORRUPTION`; it does not report BOM absence.
-
-## Scope
-
-Apply this skill to:
-
-- public .NET namespaces that contain public API
-- public types and delegates
-- public constructors, properties, methods, fields, events, and enum members
-- public extension methods
-- DocFX overwrite Markdown files
-- namespace overview pages
-- XML documentation comments
-- API examples
-- availability includes or availability statements
-
-Do not document private or internal API, implementation-only helpers, or namespaces that contain no public API.
-
-## DocFX Discovery and Script Usage
-
-For Codebelt repositories, the DocFX workspace is `.docfx` and the configuration file is `.docfx/docfx.json`. For other repositories, locate `docfx.json` before making DocFX-specific changes.
-
-Inspect `docfx.json` before editing so you understand content roots, overwrite file locations, include paths, metadata inputs, and output conventions. When creating or repairing overwrite files, read `references/docfx-overwrite-files.md`. When you need exact CLI arguments, exit codes, JSON diagnostics, or validator behavior for `agents.cs` and `docfx.cs`, read `references/scripts.md`.
-
-Run `agents.cs` against the actual repository root being documented, not a temp workspace or the skill install directory. The script manages a marker-bounded DocFX maintenance block in the repository root `AGENTS.md`; do not hand-edit or duplicate that block.
-
-## Required Documentation Surfaces
-
-When public API is added or materially changed, update every relevant surface:
-
-1. XML documentation comments in source code.
-2. Namespace overview pages for namespaces that contain public API, under `.docfx/api/namespaces/`.
-3. `Extension Members` tables for namespaces that expose public extension methods.
-4. Type-targeting overwrite content for public non-abstraction types that require examples or richer guidance, under `.docfx/api/types/`.
-5. Extension-method examples on the declaring extension class page or the namespace page.
-6. Availability information.
-7. Verification commands or artifacts that prove the documentation remains accurate and buildable.
-
-Namespace pages and type pages are both required deliverables in the same run. Do not generate namespace pages without type pages or vice versa.
-
-Material changes include new or removed public API, signature or nullability changes, behavioral changes, exception changes, changed availability, conditional extension-method availability, deprecation changes, default-value changes, or meaningful lifecycle and thread-safety changes.
-
-## Examples and Overwrites
-
+
+## Scope
+
+Apply this skill to:
+
+- public .NET namespaces that contain public API
+- public types and delegates
+- public constructors, properties, methods, fields, events, and enum members
+- public extension methods
+- DocFX overwrite Markdown files
+- namespace overview pages
+- XML documentation comments
+- API examples
+- availability includes or availability statements
+
+Do not document private or internal API, implementation-only helpers, or namespaces that contain no public API.
+
+## DocFX Discovery and Script Usage
+
+For Codebelt repositories, the DocFX workspace is `.docfx` and the configuration file is `.docfx/docfx.json`. For other repositories, locate `docfx.json` before making DocFX-specific changes.
+
+Inspect `docfx.json` before editing so you understand content roots, overwrite file locations, include paths, metadata inputs, and output conventions. When creating or repairing overwrite files, read `references/docfx-overwrite-files.md`. When you need exact CLI arguments, exit codes, JSON diagnostics, or validator behavior for `agents.cs` and `docfx.cs`, read `references/scripts.md`.
+
+Run `agents.cs` against the actual repository root being documented, not a temp workspace or the skill install directory. The script manages a marker-bounded DocFX maintenance block in the repository root `AGENTS.md`; do not hand-edit or duplicate that block.
+
+## Required Documentation Surfaces
+
+When public API is added or materially changed, update every relevant surface:
+
+1. XML documentation comments in source code.
+2. Namespace overview pages for namespaces that contain public API, under `.docfx/api/namespaces/`.
+3. `Extension Members` tables for namespaces that expose public extension methods.
+4. Type-targeting overwrite content for public non-abstraction types that require examples or richer guidance, under `.docfx/api/types/`.
+5. Extension-method examples on the declaring extension class page or the namespace page.
+6. Availability information.
+7. Verification commands or artifacts that prove the documentation remains accurate and buildable.
+
+Namespace pages and type pages are both required deliverables in the same run. Do not generate namespace pages without type pages or vice versa.
+
+Material changes include new or removed public API, signature or nullability changes, behavioral changes, exception changes, changed availability, conditional extension-method availability, deprecation changes, default-value changes, or meaningful lifecycle and thread-safety changes.
+
+## Examples and Overwrites
+
 Every public non-abstraction type and every public extension method needs at least one realistic, copy/paste-ready example. A namespace fly-in or `Extension Members` table alone is not enough.
 
 Prefer scenario examples over isolated constructor or method-call snippets. A strong type-page example shows the documented API inside the workflow a consumer is trying to complete, even when that means including nearby public types, a small local helper type, dependency-injection setup, configuration objects, or a short host entry point. The example should still be compact, but it should carry enough context that a developer can understand why the type exists and how it cooperates with the package.
@@ -161,61 +166,61 @@ Before writing examples for a package, identify the package ID or IDs from packa
 For each repair batch, maintain an evidence ledger in the example inventory: record the exact test, package README, sample, XML comment, or source path inspected and the consumer task derived from it. Do not mark a scenario ready when its evidence cell contains only a type name, generated metadata, or the overwrite file being repaired.
 
 **Tests are evidence, not output.** Do not add `ShowUsage`, `Usage`, `Example`, or documentation-only methods to test files. Use tests to understand the documented type's behavior, then transform that knowledge into consumer-facing DocFX overwrite examples.
-
-Every generated `csharp` code block is a complete, copy/paste-ready compilation unit. The default is always a compilable unit (option 1). Only use intentionally incomplete excerpts (option 2) when explicitly requested by the user, and label them clearly.
-
-**Complete C# example contract:**
-
-- Includes all required `using` directives.
-- Declares a file-scoped namespace (e.g., `namespace X.Y;`).
-- Declares at least one concrete class, struct, or record containing the usage.
-- Does **not** use top-level statements unless the example is explicitly labelled `// Program.cs` at the very top of the code block.
-- Does **not** invent placeholder services, interfaces, classes, methods, or overloads that are not defined inside the same code block.
-- Does **not** derive from an abstract or generic base type without supplying the correct concrete type arguments.
+
+Every generated `csharp` code block is a complete, copy/paste-ready compilation unit. The default is always a compilable unit (option 1). Only use intentionally incomplete excerpts (option 2) when explicitly requested by the user, and label them clearly.
+
+**Complete C# example contract:**
+
+- Includes all required `using` directives.
+- Declares a file-scoped namespace (e.g., `namespace X.Y;`).
+- Declares at least one concrete class, struct, or record containing the usage.
+- Does **not** use top-level statements unless the example is explicitly labelled `// Program.cs` at the very top of the code block.
+- Does **not** invent placeholder services, interfaces, classes, methods, or overloads that are not defined inside the same code block.
+- Does **not** derive from an abstract or generic base type without supplying the correct concrete type arguments.
 - Does **not** call members that do not exist on the resolved public API surface.
 - Uses the documented type or invokes the documented extension method inside the C# fence. A target name in prose, comments, or string literals does not count.
 - Shows a consumer-visible operation, result, configuration, or next action. Reflection-only discovery and metadata inspection do not count as usage.
 - Contains one coherent example mapping per UID. Merge related calls into one scenario instead of repeating `example: *content` sections for the same UID.
 - Compiles in a minimal class library verification project referencing the documented assemblies.
-
+
 Prefer examples derived from existing unit, functional, or integration tests as behavioral evidence, then from package-level usage evidence, samples, README content, and real consumer usage, then from a minimal new example based on actual public behavior. Convert Arrange/Act/Assert test structure into consumer-oriented sample code instead of pasting raw test assertions, mocks, or fixture setup.
-
-For public non-abstraction types, put the example on the generated type page by targeting the type UID in DocFX overwrite content. In Codebelt repositories, keep authored type overwrite Markdown under `.docfx/api/types/`, typically as `.docfx/api/types/{TypeUid}.md`.
-
-For public extension methods, place examples on the declaring extension class page or the namespace page. The example must explicitly call the method.
-
-Never mirror synthetic method UIDs that contain hashes, encoding, or generated suffixes in filenames. Keep filenames readable and let the YAML `uid` decide what DocFX model the content targets.
-
-Keep `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` only. Exclude both `api/namespaces/**` and `api/types/**` from `build.content`. Do not widen either entry to `api/**/*.md`. Move legacy authored `.docfx/api/*.md` overwrite files into either `api/namespaces/` (for namespace pages) or `api/types/` (for type pages) instead of widening the glob.
-
-For managed reference pages, map type and extension-method examples to the `example` property rather than to `summary` or implicit conceptual content. Read `references/docfx-overwrite-files.md` for the exact front-matter shape.
-
-## Example Verification
-
-Every added or changed `csharp` code block must pass two validation gates before it is written to a markdown file. Do not write any `csharp` fence without first verifying both gates pass.
-
-**Gate 1 — Static structure (`SAMPLE_STRUCTURE_INVALID`):**
-
-Before attempting compilation, the validator rejects code that:
-
-- Contains top-level statements without a `// Program.cs` comment label at the top.
-- Lacks a namespace declaration.
-- Lacks a type declaration (class, struct, or record).
-
-A code block labelled `// Program.cs` at the very top passes Gate 1 and is compiled as a file-based app.
-
-**Gate 2 — Compilation (`SAMPLE_COMPILE_FAILED`):**
-
-Class-based examples that pass Gate 1 are compiled as a class library project referencing all assemblies from `docfx.json`. If compilation fails, the example is rejected. Either repair and re-run, or omit the example and add:
-
-```markdown
-<!-- No compile-valid example could be generated for this type. -->
-```
-
-**Example generation source priority:**
-
-Derive examples from these sources, in order:
-
+
+For public non-abstraction types, put the example on the generated type page by targeting the type UID in DocFX overwrite content. In Codebelt repositories, keep authored type overwrite Markdown under `.docfx/api/types/`, typically as `.docfx/api/types/{TypeUid}.md`.
+
+For public extension methods, place examples on the declaring extension class page or the namespace page. The example must explicitly call the method.
+
+Never mirror synthetic method UIDs that contain hashes, encoding, or generated suffixes in filenames. Keep filenames readable and let the YAML `uid` decide what DocFX model the content targets.
+
+Keep `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` only. Exclude both `api/namespaces/**` and `api/types/**` from `build.content`. Do not widen either entry to `api/**/*.md`. Move legacy authored `.docfx/api/*.md` overwrite files into either `api/namespaces/` (for namespace pages) or `api/types/` (for type pages) instead of widening the glob.
+
+For managed reference pages, map type and extension-method examples to the `example` property rather than to `summary` or implicit conceptual content. Read `references/docfx-overwrite-files.md` for the exact front-matter shape.
+
+## Example Verification
+
+Every added or changed `csharp` code block must pass two validation gates before it is written to a markdown file. Do not write any `csharp` fence without first verifying both gates pass.
+
+**Gate 1 — Static structure (`SAMPLE_STRUCTURE_INVALID`):**
+
+Before attempting compilation, the validator rejects code that:
+
+- Contains top-level statements without a `// Program.cs` comment label at the top.
+- Lacks a namespace declaration.
+- Lacks a type declaration (class, struct, or record).
+
+A code block labelled `// Program.cs` at the very top passes Gate 1 and is compiled as a file-based app.
+
+**Gate 2 — Compilation (`SAMPLE_COMPILE_FAILED`):**
+
+Class-based examples that pass Gate 1 are compiled as a class library project referencing all assemblies from `docfx.json`. If compilation fails, the example is rejected. Either repair and re-run, or omit the example and add:
+
+```markdown
+<!-- No compile-valid example could be generated for this type. -->
+```
+
+**Example generation source priority:**
+
+Derive examples from these sources, in order:
+
 1. Package IDs and package-family context — determine what a consumer installs and search local evidence for the exact package ID before narrowing to individual types.
 2. Public API surface and XML documentation comments — establish the supported constructor signatures, method signatures, and types.
 3. Existing unit, functional, or integration tests that reference the documented type or member — use as behavioral evidence only; do not copy Arrange/Act/Assert structure, test fixtures, mocks, or test helper patterns into the final example unless the public API is specifically about testing.
@@ -229,84 +234,84 @@ Derive examples from these sources, in order:
 Final examples must be consumer-facing, realistic, and compile. They must read like production calling code or Microsoft Learn-style task examples, not test scaffolding, placeholder `Consumer` shells, or one-line smoke tests. Avoid unused locals, `MyNamespace` when a domain-specific namespace is obvious, fake "sample" values that obscure the workflow, and examples that instantiate the documented type without showing the result or next step a real caller cares about.
 
 Compilation-valid metadata scaffolds are still failures. Never generate a family of examples that differs only by UID while calling `Type.GetType`, returning `Type.FullName`, or wrapping the lookup in `DocumentedTypeExample`, `DocumentedExtensionExample`, or `Describe()`. These patterns conceal missing product knowledge instead of teaching the API.
-
-**Reflection and API-shape requirements:**
-
-Resolve constructors, generic arity, abstractness, constraints, and public members before writing examples:
-
-- Generic types: supply concrete type arguments (e.g., `Repository<Product>`, not `Repository<T>`).
-- Abstract types: do not instantiate directly; derive with a concrete class that supplies all required generic parameters.
-- Extension methods: show a valid receiver type.
-- Do not assume parameterless constructors or methods not present in the reflected API surface.
-- Do not invent members; if a member cannot be confirmed, omit the example.
-
-**Skip marker (last resort only):**
-
-```csharp
-// dotnet-docfx-digest:skip-compile - <reason>
-```
-
-The reason is mandatory. Package requirements, "full example needs X", "shows the framework pattern", or missing assembly/transitive/referenced assembly reasons are all rejected — these are authoring or validator-setup problems, not genuine blockers. Prefer making the example compile. Do not claim an example compiles unless the validator actually ran it successfully.
-
-## Namespace and Summary Style
-
+
+**Reflection and API-shape requirements:**
+
+Resolve constructors, generic arity, abstractness, constraints, and public members before writing examples:
+
+- Generic types: supply concrete type arguments (e.g., `Repository<Product>`, not `Repository<T>`).
+- Abstract types: do not instantiate directly; derive with a concrete class that supplies all required generic parameters.
+- Extension methods: show a valid receiver type.
+- Do not assume parameterless constructors or methods not present in the reflected API surface.
+- Do not invent members; if a member cannot be confirmed, omit the example.
+
+**Skip marker (last resort only):**
+
+```csharp
+// dotnet-docfx-digest:skip-compile - <reason>
+```
+
+The reason is mandatory. Package requirements, "full example needs X", "shows the framework pattern", or missing assembly/transitive/referenced assembly reasons are all rejected — these are authoring or validator-setup problems, not genuine blockers. Prefer making the example compile. Do not claim an example compiles unless the validator actually ran it successfully.
+
+## Namespace and Summary Style
+
 Namespace overview pages must explain what problem the namespace solves, when to use it, and where a newcomer should start. Avoid inventory-only blurbs such as “contains types and extension methods for...”
 
 The opening paragraph should name the developer problem and outcome. The next paragraph should identify a concrete starting type or method and distinguish nearby alternatives. Do not use a type inventory as a substitute for this guidance; tables and generated API lists already provide inventory.
-
-Type and member summaries should explain the API’s job in consumer terms. Prefer purpose-first summaries for entry points, builders, factories, options, and extension methods. Avoid empty labels such as “represents options” or “adds services” unless the rest of the sentence explains the actual outcome enabled.
-
-If one namespace page in a public API family needs repair, inspect sibling namespace pages in that family before finishing and keep them consistent. If you intentionally leave a sibling page unchanged, say why.
-
-## XML Documentation Comments
-
-Public API should have useful XML comments. Keep source summaries concise and move longer examples or remarks into DocFX overwrite content when that keeps the source readable.
-
-XML comments should cover purpose, parameters, return value, exceptions, type parameters, important behavior, nullability expectations, and lifecycle or thread-safety details when relevant.
-
-## Cleanup Boundary
-
-Authored DocFX Markdown is documentation output, not disposable build output. Do not delete `.md` or `.mdoc` files, `docfx.json`, `toc.yml`, includes, images, examples, or directories that contain authored documentation while cleaning generated artifacts unless the user explicitly asks for that deletion.
-
-Prefer `docfx.cs --verify-docfx-build` because it builds DocFX in a temp copy and cleans that workspace itself. If `git status` still shows leftover generated files afterward, classify each path before deleting it. Generated metadata cleanup is limited to DocFX-generated `*.yml`, `.manifest`, and `*.manifest` files under configured metadata destinations. Generated site cleanup is limited to the configured build output directory when that directory is clearly generated output and contains no authored Markdown, source, project, solution, or DocFX configuration files.
-
-If a cleanup candidate is ambiguous, leave it in place and report the ambiguity instead of deleting it.
-
-## Codebelt Signing Keys
-
-Codebelt solutions are normally strong-name signed with a repository-root `.snk` file. Preserve and copy that file when it exists. If a Codebelt repository or temp copy does not contain the root `.snk`, use the skip-sign fallback for verification commands:
-
-```bash
-dotnet build -p:SkipSignAssembly=true
-dotnet test -p:SkipSignAssembly=true
-```
-
-Use the same fallback for equivalent builds triggered by documentation validation so missing local signing keys do not masquerade as documentation failures.
-
-## Workflow Summary
-
-When the user names a changed API or namespace:
-
-1. Run `agents.cs`.
-2. Run the safety gates and inspect existing documentation edits.
-3. Inspect the changed public API, affected namespaces, availability inputs, tests, samples, and current overwrite files.
-4. Update XML comments, namespace pages, extension-member tables, examples, and availability notes as required.
-5. Build an example inventory for required public concrete types and extension methods.
-6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`).
-
-When the user does not name a specific target:
-
-1. Run `agents.cs`.
-2. Run the safety gates and inspect repository guidance.
-3. Inspect DocFX configuration, overwrite files, tests, samples, and current documentation state.
-4. Run `docfx.cs --json`, and for multi-diagnostic output rerun with `--repair-plan` and use that plan as the work queue.
-5. Repair missing namespace pages, extension-member tables, examples, overwrite layout, summaries, and availability notes that can be derived from evidence.
-6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`).
-
-Read `references/workflow.md` before creating new namespace pages, writing type or extension examples, preparing the final verification checklist, or shaping the completion response.
-
-## Reference Files
-
-- `references/workflow.md` — detailed targeted/audit workflows, example inventory shape, templates, verification checklist, and completion response.
-- `references/docfx-overwrite-files.md` — overwrite-file model rules, `example: - *content` usage, and Codebelt overwrite layout guidance.
-- `references/scripts.md` — exact `agents.cs` and `docfx.cs` commands, arguments, exit codes, diagnostics, and validator behavior.
+
+Type and member summaries should explain the API’s job in consumer terms. Prefer purpose-first summaries for entry points, builders, factories, options, and extension methods. Avoid empty labels such as “represents options” or “adds services” unless the rest of the sentence explains the actual outcome enabled.
+
+If one namespace page in a public API family needs repair, inspect sibling namespace pages in that family before finishing and keep them consistent. If you intentionally leave a sibling page unchanged, say why.
+
+## XML Documentation Comments
+
+Public API should have useful XML comments. Keep source summaries concise and move longer examples or remarks into DocFX overwrite content when that keeps the source readable.
+
+XML comments should cover purpose, parameters, return value, exceptions, type parameters, important behavior, nullability expectations, and lifecycle or thread-safety details when relevant.
+
+## Cleanup Boundary
+
+Authored DocFX Markdown is documentation output, not disposable build output. Do not delete `.md` or `.mdoc` files, `docfx.json`, `toc.yml`, includes, images, examples, or directories that contain authored documentation while cleaning generated artifacts unless the user explicitly asks for that deletion.
+
+Prefer `docfx.cs --verify-docfx-build` because it builds DocFX in a temp copy and cleans that workspace itself. If `git status` still shows leftover generated files afterward, classify each path before deleting it. Generated metadata cleanup is limited to DocFX-generated `*.yml`, `.manifest`, and `*.manifest` files under configured metadata destinations. Generated site cleanup is limited to the configured build output directory when that directory is clearly generated output and contains no authored Markdown, source, project, solution, or DocFX configuration files.
+
+If a cleanup candidate is ambiguous, leave it in place and report the ambiguity instead of deleting it.
+
+## Codebelt Signing Keys
+
+Codebelt solutions are normally strong-name signed with a repository-root `.snk` file. Preserve and copy that file when it exists. If a Codebelt repository or temp copy does not contain the root `.snk`, use the skip-sign fallback for verification commands:
+
+```bash
+dotnet build -p:SkipSignAssembly=true
+dotnet test -p:SkipSignAssembly=true
+```
+
+Use the same fallback for equivalent builds triggered by documentation validation so missing local signing keys do not masquerade as documentation failures.
+
+## Workflow Summary
+
+When the user names a changed API or namespace:
+
+1. Run `agents.cs`.
+2. Run the safety gates and inspect existing documentation edits.
+3. Inspect the changed public API, affected namespaces, availability inputs, tests, samples, and current overwrite files.
+4. Update XML comments, namespace pages, extension-member tables, examples, and availability notes as required.
+5. Build an example inventory for required public concrete types and extension methods.
+6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`).
+
+When the user does not name a specific target:
+
+1. Run `agents.cs`.
+2. Run the safety gates and inspect repository guidance.
+3. Inspect DocFX configuration, overwrite files, tests, samples, and current documentation state.
+4. Run `docfx.cs --json`, and for multi-diagnostic output rerun with `--repair-plan` and use that plan as the work queue.
+5. Repair missing namespace pages, extension-member tables, examples, overwrite layout, summaries, and availability notes that can be derived from evidence.
+6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`).
+
+Read `references/workflow.md` before creating new namespace pages, writing type or extension examples, preparing the final verification checklist, or shaping the completion response.
+
+## Reference Files
+
+- `references/workflow.md` — detailed targeted/audit workflows, example inventory shape, templates, verification checklist, and completion response.
+- `references/docfx-overwrite-files.md` — overwrite-file model rules, `example: - *content` usage, and Codebelt overwrite layout guidance.
+- `references/scripts.md` — exact `agents.cs` and `docfx.cs` commands, arguments, exit codes, diagnostics, and validator behavior.
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 39a7ed5..f7364d8 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -733,6 +733,160 @@
         "Avoids reflection, metadata-only examples, generic wrappers, duplicate UID mappings, and invented API members",
         "Runs semantic validation and sample compilation before claiming completion"
       ]
+    },
+    {
+      "id": 59,
+      "prompt": "Use dotnet-docfx-digest in dry-run mode for my multi-project library. The DocFX config has two metadata destinations (api/core and api/net).",
+      "expected_output": "The agent runs docfx.cs with --dry-run --build-api-model --project-manifest (no invented project hints), reports the seed, and authors one clean selected project from each metadata destination group. It completes the generated review JSON for every changed page, then resumes with --review-report --build-api-model --validate-samples --verify-docfx-build until dry-run-passed and reports the same page-level review rather than repository completion.",
+      "expectations": [
+        "Runs docfx.cs --dry-run --build-api-model --project-manifest without inventing project hints the user did not give",
+        "Selects one clean project from each metadata destination group, reports the seed, and actually authors their namespace/type documentation",
+        "Completes the generated review report and resumes the same manifest with --review-report --build-api-model --validate-samples --verify-docfx-build until dry-run-passed",
+        "Reports a Changed-page review row for every authored page with evidence, page-specific purpose/outcome, observable example result, and sibling-pattern comparison without claiming repository-wide completion"
+      ]
+    },
+    {
+      "id": 60,
+      "prompt": "Run dotnet-docfx-digest in dry-run mode for Cuemon.Core and src/Cuemon.Net/Cuemon.Net.csproj specifically.",
+      "expected_output": "The agent resolves both explicit hints (by assembly/package name and by project path), persists exactly those two selected packets, authors both, and resumes the manifest through build-backed discovery, sample compilation, and DocFX verification. Explicit hints override automatic selection; the run remains scoped and never claims repository completion.",
+      "expectations": [
+        "Resolves both explicit --project hints, including the path-form hint, to exactly one project each",
+        "Persists and authors only the two named packets, overriding automatic selection",
+        "Completes the generated review report, resumes with --review-report, and passes build-backed discovery, sample compilation, DocFX verification, and page-level review",
+        "Does not claim repository-wide completion from the selected subset"
+      ]
+    },
+    {
+      "id": 61,
+      "prompt": "Use dotnet-docfx-digest in dry-run mode for `Common`, but I have two projects whose file names both resolve to Common.",
+      "expected_output": "The agent surfaces PROJECT_HINT_AMBIGUOUS with the candidate project paths and stops before editing, asking the user to disambiguate with a more specific path, assembly name, or package id instead of guessing.",
+      "expectations": [
+        "Surfaces PROJECT_HINT_AMBIGUOUS with the candidate matches before any editing",
+        "Does not guess or edit either candidate",
+        "Asks for a more specific hint (path, assembly, or package id)"
+      ]
+    },
+    {
+      "id": 62,
+      "prompt": "Run a dry-run DocFX digest. One project in a destination group already has uncommitted changes to its source and namespace page.",
+      "expected_output": "The agent's dry run skips the dirty project, selects another clean project from the same metadata group, and never edits the dirty project's related files. If a group has no clean candidate it reports DRY_RUN_GROUP_UNSELECTED for that group and makes no edits there.",
+      "expectations": [
+        "Skips the dirty candidate and selects a clean project from the same group",
+        "Never edits files that were already staged, modified, renamed, deleted, or untracked",
+        "Reports DRY_RUN_GROUP_UNSELECTED when a group has no clean project"
+      ]
+    },
+    {
+      "id": 63,
+      "prompt": "Document the `Cuemon.Collections` namespace which has a MutableTuple<T1> through MutableTuple<T7> generic-arity family plus a few unrelated types, using dotnet-docfx-digest.",
+      "expected_output": "The agent declares a narrow family exemption in .docfx/family-exemptions.json for the MutableTuple arity series with rationale generic-arity, writes one strong anchor example for MutableTuple<T1>, and a namespace page that names the anchor and explains how arity distinguishes the siblings. Covered siblings get purpose-first prose but not redundant standalone examples. Unrelated types still get their own examples.",
+      "expectations": [
+        "Declares a family exemption only for the coherent arity series, not the unrelated types",
+        "Provides one validated anchor example and deep namespace guidance that names the anchor and explains sibling selection",
+        "Gives covered siblings purpose-first prose without redundant standalone examples",
+        "Still requires standalone examples for the unrelated types"
+      ]
+    },
+    {
+      "id": 64,
+      "prompt": "I want to exempt my `Acme.Options` exceptions, options objects, and a delegate from needing examples by grouping them as one family. Set that up with dotnet-docfx-digest.",
+      "expected_output": "The agent refuses to create a blanket family exemption for unrelated difficult types. It explains that category alone (exceptions, options, delegates, records, data carriers) never qualifies, that a family must be a coherent generic-arity/inherited/overload/type-parameter series, and that such a declaration would fail validation with FAMILY_EXEMPTION_INVALID. It documents the types with real examples instead.",
+      "expectations": [
+        "Refuses the blanket exemption and explains category alone does not qualify",
+        "Notes the declaration would fail FAMILY_EXEMPTION_INVALID validation",
+        "Documents the types with real examples instead of exempting them"
+      ]
+    },
+    {
+      "id": 65,
+      "prompt": "My namespace page for `Acme.Caching` opens with 'The Acme.Caching namespace contains types and helpers that enable caching.' and then has a separate 'Start with `MemoryCacheStore`' paragraph. Fix it with dotnet-docfx-digest.",
+      "expected_output": "The agent recognizes NAMESPACE_APPEND_ONLY_REPAIR: the weak inventory lead was left intact with guidance appended below. It rewrites the opening cohesively around the caching problem and outcome rather than keeping the inventory sentence and a tacked-on start-here line.",
+      "expectations": [
+        "Rewrites the opening paragraph around the developer problem and outcome",
+        "Does not leave the inventory-led lead intact beneath an appended start-here sentence",
+        "Integrates the start-here guidance into cohesive prose"
+      ]
+    },
+    {
+      "id": 66,
+      "prompt": "Run a full DocFX digest across all my project packets, but stop and tell me if a packet produces low-quality output.",
+      "expected_output": "The agent processes packets one at a time, runs the scoped semantic and sample gates per packet, and stops the entire run immediately when a packet fails its quality gates or produces mechanical output (holder/forwarding/repeated templates). It reports which packet failed and why rather than continuing to author later packets.",
+      "expectations": [
+        "Processes packets one at a time with scoped quality gates",
+        "Stops the whole run immediately on the first failing packet",
+        "Does not continue authoring later packets after mechanical output is detected"
+      ]
+    },
+    {
+      "id": 67,
+      "prompt": "Run the complete DocFX digest for my repository using all project packets and verify it.",
+      "expected_output": "The agent documents every eligible clean project packet, preserves dirty project documentation without overwriting it, and finishes with the global build-backed verification (--build-api-model --validate-samples --verify-docfx-build) so the deterministic completion contract (canClaimCompletion true, zero remaining work items and gates) is satisfied before claiming completion.",
+      "expectations": [
+        "Documents all eligible clean packets and preserves dirty project work",
+        "Runs the global build-backed verification before claiming completion",
+        "Confirms the JSON completion contract (canClaimCompletion true, zero remaining work items/gates)"
+      ]
+    },
+    {
+      "id": 68,
+      "prompt": "The fast docfx.cs run reports only one required example target for my Cuemon-style repo where namespaces put the opening brace on the next line. Document the repo with dotnet-docfx-digest.",
+      "expected_output": "The agent recognizes the source scanner is provisional (BUILD_BACKED_SCOPE_REQUIRED / API_MODEL_SOURCE_SCANNER_LIMITED) and runs --build-api-model to establish reflection-precise scope before authoring, rather than trusting the under-reported fast count. It documents the full discovered surface.",
+      "expectations": [
+        "Recognizes the source-scan inventory as provisional and does not author from the under-reported count",
+        "Runs --build-api-model (or confirms DocFX YAML) before authoring scope",
+        "Documents the full reflection-backed surface, not just the single fast-reported target"
+      ]
+    },
+    {
+      "id": 69,
+      "prompt": "My library has over 400 public types needing examples. Document it with dotnet-docfx-digest.",
+      "expected_output": "The agent sees QUALITY_RISK_REVIEW_REQUIRED (standalone targets above 100) and does not start a bulk authoring pass. It limits the first pass to one project packet or 20 targets, manually reviews those changed pages, and asks for explicit approval before continuing the full run. It treats a dry run as the preferred pilot for the large surface.",
+      "expectations": [
+        "Detects the high-risk queue and stops for a bounded pilot instead of bulk authoring",
+        "Limits the first pass to one packet or about 20 targets and reviews the actual changed pages",
+        "Requests explicit approval before continuing the full run"
+      ]
+    },
+    {
+      "id": 70,
+      "prompt": "Two of my assemblies both declare a public static `Extensions` class with extension methods in different namespaces. Document both with dotnet-docfx-digest.",
+      "expected_output": "The agent recognizes EXTENSION_OWNER_AMBIGUOUS (and any SYMBOL_COLLISION_UNRESOLVED for duplicate type names) and resolves ownership by assembly/project. It prefers receiver extension syntax in examples and targets the uniquely owned overwrite UID so each documented method is unambiguous.",
+      "expectations": [
+        "Identifies the cross-assembly extension-container collision by owning assembly/project",
+        "Prefers receiver extension syntax over static-container qualification when names collide",
+        "Targets the uniquely owned overwrite UID for each method"
+      ]
+    },
+    {
+      "id": 71,
+      "prompt": "My `Cuemon.Core` assembly forwards a generic type family to another assembly via [assembly: TypeForwardedTo]. Document the affected types with dotnet-docfx-digest.",
+      "expected_output": "The agent surfaces TYPE_FORWARDING_UNRESOLVED for forwarded types it cannot attribute, and resolves which project and UID documents the forwarded family before authoring. It does not silently document the forwarded family under the wrong assembly.",
+      "expectations": [
+        "Surfaces unresolved type forwarding rather than mis-attributing the forwarded family",
+        "Resolves the documenting project and UID for the forwarded types before authoring",
+        "Records the forwarding source and destination relationship"
+      ]
+    },
+    {
+      "id": 72,
+      "prompt": "Write the DocFX overwrite example for `Acme.Core.Widget` for me, and make sure it doesn't corrupt the file encoding.",
+      "expected_output": "The agent uses the safe structured overwrite writer (docfx.cs --write-overwrite) with an authored prose+fence request. The writer preserves the target file's BOM and line endings, validates balanced fences, and refuses duplicate UIDs or dirty-file replacement. The agent does not hand-assemble fenced Markdown through brittle byte/encoding operations.",
+      "expectations": [
+        "Uses the structured overwrite writer rather than ad-hoc byte/encoding manipulation",
+        "Preserves BOM and line-ending state and validates the fence",
+        "Authors the prose and fence itself; the writer only validates and writes structured content"
+      ]
+    },
+    {
+      "id": 73,
+      "prompt": "Do the dry-run DocFX pilot and tell me it's good to proceed.",
+      "expected_output": "Before declaring the pilot good, the agent proves the selected packets were actually authored and the persisted manifest was resumed through build-backed discovery, sample compilation, and DocFX verification. It manually reviews every changed namespace and type page for repeated sentence/code structures, reports the actual prose and examples, and asks the user to review representative output before a full run rather than asserting quality from selector counts.",
+      "expectations": [
+        "Shows that selected packets produced real working-tree namespace/type documentation, a complete review report, and a resumed dry-run-passed result",
+        "Reports a complete Changed-page review table for the actual changed pages, not only the validator summary or a file list",
+        "Checks specifically for repeated sentence and code structures across the pilot",
+        "Presents representative output for human review before a full run"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
index 05f182b..3e7c485 100644
--- a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -59,6 +59,32 @@ Do **not** use `summary: *content` for type example files. That replaces only th
 
 DocFX applies overwrite models by `uid`. If the same `uid` appears more than once in one overwrite file, later sections in that same file override earlier sections. Across different overwrite files, ordering is not deterministic, so keep competing sections for the same `uid` together or consolidate them.
 
+## Safe structured overwrite writer
+
+For repeatable overwrite creation, prefer `docfx.cs --write-overwrite <request.json>` over hand-assembling fenced Markdown with ad-hoc scripts. The request is JSON with `file`, `uid`, `mapping` (`example`, `summary`, or `remarks`), optional `prose`, and optional `fence`. The writer validates the YAML and balanced fences, refuses duplicate UIDs in the same file (`OVERWRITE_UID_DUPLICATE`), refuses unbalanced fences (`OVERWRITE_FENCE_UNBALANCED`), refuses to replace a file that already had uncommitted changes (`OVERWRITE_DIRTY_REFUSED`), preserves the target file's existing BOM and line endings, and prints a change preview. It writes only structured content you already authored — it never generates prose, selects members, or synthesizes examples. Normal surgical edits may still use your editor; the writer exists for repeatable, encoding-safe overwrite creation.
+
+## Family exemptions
+
+A coherent type series whose members differ primarily by generic arity, inherited specialization, overload shape, or repeated type-parameter combinations may replace redundant per-type examples with one anchor example plus deep namespace guidance. Declare these explicitly in `.docfx/family-exemptions.json` so the policy is reviewable and validator-checkable:
+
+```json
+{
+  "families": [
+    {
+      "familyId": "tuple-arity",
+      "namespaceUid": "Cuemon.Collections",
+      "anchorUid": "Cuemon.Collections.MutableTuple`1",
+      "anchorExampleFile": ".docfx/api/types/Cuemon.Collections.MutableTuple`1.md",
+      "rationale": "generic-arity",
+      "coveredUids": ["Cuemon.Collections.MutableTuple`2", "Cuemon.Collections.MutableTuple`3"]
+    }
+  ]
+}
+```
+
+`rationale` must be one of `generic-arity`, `inherited-specialization`, `overload-series`, or `type-parameter-series`. The validator removes covered siblings from standalone-example obligations only after every UID resolves to a public type target in the declared namespace, with no duplicate or circular coverage (`FAMILY_EXEMPTION_INVALID` otherwise). The anchor must carry a real behavioral example (`FAMILY_ANCHOR_EXAMPLE_MISSING` otherwise), the namespace page must name the anchor and explain how consumers choose among siblings (`FAMILY_NAMESPACE_GUIDANCE_MISSING` otherwise), and every sibling still needs accurate purpose-first prose. Category alone never exempts options, exceptions, delegates, records, or data carriers; they are evaluated on their actual API role.
+
+
 Overwrite models should follow the target model shape. Existing properties can be replaced or merged depending on the DocFX model rules; properties not already present can be added. For managed reference docs, common useful overwrite targets include `summary`, `remarks`, `example`, `exceptions`, `see`, `seealso`, and parameter descriptions under `syntax`. The official managed reference model lists `example` as an overwriteable property, so usage examples can be added through overwrite sections when generated metadata lacks them.
 
 The `build.overwrite` entry in `docfx.json` tells DocFX which conceptual Markdown files contain overwrite sections. All relative paths in `docfx.json` are resolved relative to the directory containing `docfx.json`, not necessarily the repository root.
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index cbbd3e0..1edb223 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -78,9 +78,29 @@ dotnet run --file docfx.cs -- --repo-root . --build-api-model --configuration De
 
 Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only used by build/sample paths), `--framework`, `--validate-samples` / `--no-validate-samples` (default off — opt-in), `--sample-reference-mode <project|package>` (default `project`), `--sample-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_SAMPLE_PARALLELISM`; passed as the maximum node count for the batched sample graph build), `--build-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_BUILD_PARALLELISM`), `--execution-profile <auto|conservative|high-capacity>` (env `DOCFX_DIGEST_EXECUTION_PROFILE`), `--process-timeout-minutes <n>` (1-180, default 30; env `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES`), `--build-api-model` / `--strict-api-discovery` (default off — opt-in), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default off — opt-in), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
+Project-scoped authoring arguments: `--project <hint>` (repeatable; resolves against project path, file name, assembly name, or package id and must match exactly one project), `--dry-run` (select a representative working-tree run), `--seed <integer>` (reproducible dry-run selection; reported when generated), `--project-manifest <path>` (write a deterministic BOM-less packet manifest, initial dirty baseline, and sibling review template), `--resume-project-manifest <path>` (resume exactly those selected packets after authoring), `--review-report <path>` (required on resume; validates page-specific evidence, purpose/outcome, observable result, and pattern comparison), `--write-overwrite <path>` (safe structured overwrite-writer command), `--allow-high-risk` (proceed past the quality-risk pilot stop as an explicit decision), `--risk-standalone-threshold <n>` (default 100), `--risk-extension-threshold <n>` (default 100), and `--risk-missing-ratio-threshold <x>` (default 10). These appear in the report under `scope` and `qualityRisk`.
+
+```bash
+dotnet run --file docfx.cs -- --repo-root . --dry-run --build-api-model --project-manifest /tmp/dry-run.json
+                                                                            # select one clean project per dest group
+dotnet run --file docfx.cs -- --repo-root . --dry-run --seed 1234 --build-api-model --project-manifest /tmp/dry-run.json
+                                                                            # reproduce and persist selection
+dotnet run --file docfx.cs -- --repo-root . --project Cuemon.Core            # scoped run (no random selection)
+dotnet run --file docfx.cs -- --repo-root . --dry-run --project Cuemon.Core --project src/Cuemon.Net/Cuemon.Net.csproj --build-api-model --project-manifest /tmp/dry-run.json
+dotnet run --file docfx.cs -- --repo-root . --resume-project-manifest /tmp/dry-run.json --review-report /tmp/dry-run.review.json --build-api-model --validate-samples --verify-docfx-build --json
+dotnet run --file docfx.cs -- --repo-root . --build-api-model --project-manifest /tmp/packets.json
+dotnet run --file docfx.cs -- --repo-root . --write-overwrite /tmp/overwrite-request.json
+```
+
+The scanner correctly handles block namespaces whose opening brace is on the next line; when it cannot pair a declaration with its brace it warns `API_MODEL_SOURCE_SCANNER_INCOMPLETE`. Project discovery groups projects by their DocFX metadata destination (`metadata[].dest`, default `api`): a group is a sampling unit, and distinct destinations are never collapsed into one ownership-free list. A run is `full`, `scoped` (explicit `--project` hints), or `dry-run` (seeded one-per-group selection). When the API model is `source-scan` and authoring scope is requested, `summary.scopeState` is `provisional` and `BUILD_BACKED_SCOPE_REQUIRED` fires; DocFX YAML or `--build-api-model` make scope `authoritative`. A `dry-run`/`scoped` run never sets `summary.canClaimCompletion`; `*-passed` requires zero diagnostics and all three final gates (`--build-api-model`, `--validate-samples`, `--verify-docfx-build`), otherwise it is `*-failed`. Dirty related paths (staged, unstaged, renamed, deleted, untracked) mark a packet dirty so initial dry-run selection skips it (`DRY_RUN_GROUP_UNSELECTED` when a group has no clean candidate). A resumed manifest reuses only the initial dirty baseline, allowing newly authored files to be verified while continuing to protect pre-existing work; invalid manifests fail closed.
+
+The JSON `scope` object contains `mode`, `seed`, `scopeState`, `metadataGroups` (with the `selectedProject` per group), `selectedProjects`, `skippedProjects`, `packets` (project identity, metadata groups, owned/shared namespaces, target counts, overwrite paths, review paths, dirty related paths, per-packet diagnostic counts), `dirty`, `familyExemptions`, `reproduceCommand`, and, after manifest creation, `resumeCommand`. The top-level report includes `reviewReportPath`. `--project-manifest` writes the packet evidence and initial git baseline as schema version 2 plus a sibling schema-version-1 review template. The resumed run requires every changed selected page to have non-placeholder `evidence`, `purpose`, `observableOutcome`, and `patternComparison` fields before `dry-run-passed` or `scoped-passed` is possible.
+
+`--write-overwrite <path>` reads a JSON request (`file`, `uid`, `mapping` of `example`/`summary`/`remarks`, optional `prose`, optional `fence`), validates the YAML and balanced fences, refuses duplicate UIDs (`OVERWRITE_UID_DUPLICATE`), unbalanced fences (`OVERWRITE_FENCE_UNBALANCED`), and replacing a pre-existing dirty file (`OVERWRITE_DIRTY_REFUSED`), preserves the target's existing BOM and line endings, and prints a change preview. It only writes structured content the agent already authored; it never generates prose, selects members, or synthesizes examples.
+
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It still does not build by default: Markdown/overwrite-only changes are validated against the no-build API model, and it uses `git` (read-only) to discover changes. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled (under `--validate-samples`) before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, encoding repairs, namespace and extension-table repairs, a required-example inventory with GitHub search commands, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory includes missing examples and semantic failures such as duplicate UID mappings, placeholders, reflection-only scaffolds, target types that are never used, and extension methods that are never invoked. For public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the plan to a temp path unless the user explicitly wants a checked-in artifact. The plan always includes a "GitHub Example Sources" section with `gh search code` commands and GitHub search URLs for each documented package, even when no `EXAMPLE_MISSING` diagnostics are present.
+`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, encoding repairs, namespace and extension-table repairs, a required-example inventory with GitHub search commands, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory includes missing examples and semantic failures such as duplicate UID mappings, placeholders, `default!`/`null!` holders, no-observable-outcome and mass-forwarding scaffolds, repeated code templates across unrelated targets, reflection-only scaffolds, target types that are never used, and extension methods that are never invoked. For public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the plan to a temp path unless the user explicitly wants a checked-in artifact. The plan always includes a "GitHub Example Sources" section with `gh search code` commands and GitHub search URLs for each documented package, even when no `EXAMPLE_MISSING` diagnostics are present.
 
 `--search-examples` runs `gh search code` for each discovered package ID and embeds the top matching file paths in the repair plan under "GitHub Search Results". Requires the `gh` CLI to be authenticated. Combine with `--repair-plan` so results are written to a file the agent can read. If `gh` is unavailable or returns no results, the plan still includes the pre-computed search URLs and CLI commands.
 
@@ -108,7 +128,7 @@ Every run records a process tally, per-phase timings, and execution settings. No
 
 Every report also carries a deterministic completion contract. `summary.completionState` is `complete` only when there are no errors and the run enabled `--build-api-model`, `--validate-samples`, and `--verify-docfx-build`. A clean fast run reports `verification-required`. `summary.canClaimCompletion` must be `true`; `summary.remainingWorkItems` must be `0`; and both `summary.remainingGates` and `summary.remainingDiagnosticsByCode` must be empty before an agent can claim a full digest. Any other result is an active repair or verification queue. Diagnostic age, pre-existing status, and volume do not convert repair work into an external blocker.
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, `NAMESPACE_START_HERE_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `EXAMPLE_UID_DUPLICATE`, `EXAMPLE_PLACEHOLDER`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, `NAMESPACE_START_HERE_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `EXAMPLE_UID_DUPLICATE`, `EXAMPLE_PLACEHOLDER`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Project-scoped error codes are `PROJECT_HINT_NOT_FOUND` and `PROJECT_HINT_AMBIGUOUS` for `--project` hints, `FAMILY_EXEMPTION_INVALID`, `FAMILY_ANCHOR_EXAMPLE_MISSING`, and `FAMILY_NAMESPACE_GUIDANCE_MISSING` for `.docfx/family-exemptions.json`, and `OVERWRITE_UID_DUPLICATE`, `OVERWRITE_FENCE_UNBALANCED`, `OVERWRITE_DIRTY_REFUSED`, `OVERWRITE_REQUEST_MISSING`, and `OVERWRITE_REQUEST_INVALID` for the `--write-overwrite` writer. The semantic example codes reject the filler patterns that pass a naive token match: `EXAMPLE_DEFAULT_PLACEHOLDER` for a target parked in a `default!`/`null!` holder property or field, `EXAMPLE_NO_OBSERVABLE_OUTCOME` for an example that only holds, returns, or constructs the target with no visible result, `EXAMPLE_FORWARDING_SCAFFOLD` for a shell dominated by one-line pass-through members, and `EXAMPLE_TEMPLATE_REPETITION` for one normalized code skeleton reused across three or more unrelated targets. `NAMESPACE_APPEND_ONLY_REPAIR` flags an inventory-led opening left intact while usage or start-here guidance is appended below it (rewrite the opening cohesively instead), and `NAMESPACE_PROSE_TEMPLATE_REPETITION` flags three or more namespace overviews that share one normalized prose skeleton. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_SOURCE_SCANNER_INCOMPLETE` when the scanner cannot pair a block namespace declaration with its opening brace and may under-report public types, `BUILD_BACKED_SCOPE_REQUIRED` when authoring scope is requested on the provisional source-scan model, `PROJECT_DIRTY_SKIPPED` when an explicitly selected project has pre-existing related changes, `DRY_RUN_GROUP_UNSELECTED` when a metadata group has no clean project to sample, `QUALITY_RISK_REVIEW_REQUIRED` when the queue size or symbol complexity requires a pilot review, `SYMBOL_COLLISION_UNRESOLVED` / `TYPE_FORWARDING_UNRESOLVED` / `EXTENSION_OWNER_AMBIGUOUS` for unresolved symbol ownership, `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
 
 `ENCODING_CORRUPTION` fires when a documentation file contains the byte sequence `C3 A2 C2 AC` — the UTF-8 re-encoding of the `â¬` pair produced by a Windows-1252 round-trip of `U+2B07` (⬇, the Extension Members table arrow). Restore the affected file with `git checkout HEAD -- <file>` if the committed version was correct, or rewrite the content using the edit tool or byte-level operations. Never use `Get-Content` / `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes(Get-Content)` to rewrite documentation files that contain multi-byte characters.
 
@@ -137,7 +157,7 @@ The validator first locates example code in one of:
 - A DocFX front-matter anchor (`example: *content` or the list form `example:\n- *content`) followed by a body that contains a fenced `csharp`/`cs` block; **or**
 - A `## Example` / `### Example` heading in the body followed by a fenced `csharp`/`cs` block.
 
-The first form is preferred for type pages and extension-class pages. Add a `### Examples` heading only when the front matter anchors the body to `summary` and you intend the heading to delimit the embedded example. Locating a fence is only the structural gate. The validator then rejects duplicate example mappings for the same UID, generated placeholder phrases and helper names, reflection-only metadata lookup, type examples that never use the target in C# code, and extension examples that never invoke the method. Prose, comments, and string literals do not prove target use.
+The first form is preferred for type pages and extension-class pages. Add a `### Examples` heading only when the front matter anchors the body to `summary` and you intend the heading to delimit the embedded example. Locating a fence is only the structural gate. The validator then rejects duplicate example mappings for the same UID, generated placeholder phrases and helper names, reflection-only metadata lookup, type examples that never use the target in C# code, and extension examples that never invoke the method. It additionally rejects examples that name the target but never exercise it: `default!`/`null!` holder properties, classes whose only interaction is holding or returning the target with no observable result, mass-forwarding shells of one-line pass-through members, and a single normalized code skeleton reused across three or more unrelated targets. Prose, comments, and string literals do not prove target use.
 
 ### Extension-method detection note
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 1c41b0b..5335f00 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -1,7 +1,7 @@
-# dotnet-docfx-digest workflow reference
-
-Use this reference when you need the full step-by-step workflow, example inventory shape, ready-to-adapt templates, or the final completion checklist.
-
+# dotnet-docfx-digest workflow reference
+
+Use this reference when you need the full step-by-step workflow, example inventory shape, ready-to-adapt templates, or the final completion checklist.
+
 ## Example inventory shape
 
 Build a small example inventory from validator output and source evidence before writing examples. Treat it as a work queue, not as final-response prose.
@@ -29,63 +29,63 @@ Before writing a type or extension-method example, choose the smallest real task
 9. Confirm the C# fence itself uses the documented type or invokes the documented extension method. Mentions outside the fence do not count.
 
 A scenario example is still concise. It should show one coherent task, not a tour of every member. If a compile-valid scenario cannot be produced from evidence, omit the example with the documented omission comment rather than inventing a plausible workflow.
-
-## Targeted workflow
-
-Use this path when the user names a changed API or namespace.
-
-1. Run `agents.cs`.
-2. Run the safety gates: inspect `git status --short`, identify existing documentation work, and avoid broad restore or recovery commands.
-3. Inspect the changed public API and determine affected namespaces.
-4. Determine whether public extension methods are involved.
-5. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
-6. Locate existing overwrite files, namespace pages, availability includes, tests, and samples.
-7. Run `docfx.cs --json --repair-plan /tmp/docfx-repair-plan.md --search-examples` and read the repair plan. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs; use those results as evidence before writing examples.
-8. Convert test usage into consumer-oriented examples when relevant.
-9. Update XML documentation comments where purpose-first summaries are needed.
+
+## Targeted workflow
+
+Use this path when the user names a changed API or namespace.
+
+1. Run `agents.cs`.
+2. Run the safety gates: inspect `git status --short`, identify existing documentation work, and avoid broad restore or recovery commands.
+3. Inspect the changed public API and determine affected namespaces.
+4. Determine whether public extension methods are involved.
+5. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
+6. Locate existing overwrite files, namespace pages, availability includes, tests, and samples.
+7. Run `docfx.cs --json --repair-plan /tmp/docfx-repair-plan.md --search-examples` and read the repair plan. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs; use those results as evidence before writing examples.
+8. Convert test usage into consumer-oriented examples when relevant.
+9. Update XML documentation comments where purpose-first summaries are needed.
 10. Update or create namespace overview pages whose opening names the developer problem and outcome, followed by concrete when-to-use and start-here guidance.
-11. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
-12. Update `Extension Members` tables when public extension methods are involved. Use the literal `⬇️` (U+2B07 U+FE0F) in the Ext column — the validator now rejects corrupted or missing emoji with `EXTENSION_TABLE_ENCODING`.
-13. Update or create overwrite content, including type-page examples for public non-abstraction types and explicit examples for public extension methods.
-14. Build or refresh the example inventory.
-15. Preserve manual edits and correct stale contradictions instead of replacing whole files.
-16. Run `git diff` for touched documentation paths and confirm the diff is intentional.
-17. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-18. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+11. Inspect sibling namespace pages in the same public API family and repair each affected page consistently.
+12. Update `Extension Members` tables when public extension methods are involved. Use the literal `⬇️` (U+2B07 U+FE0F) in the Ext column — the validator now rejects corrupted or missing emoji with `EXTENSION_TABLE_ENCODING`.
+13. Update or create overwrite content, including type-page examples for public non-abstraction types and explicit examples for public extension methods.
+14. Build or refresh the example inventory.
+15. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+16. Run `git diff` for touched documentation paths and confirm the diff is intentional.
+17. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+18. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 19. Run the Completion Repair Loop by rerunning the fast `docfx.cs --json`, repairing every remaining diagnostic, and updating the example inventory until `summary.canClaimCompletion` is `true`. Diagnostic age and volume are not blockers.
-20. Run the build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` so samples compile, API discovery is reflection-precise, and DocFX builds in a temp copy.
-21. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
-22. Report verification results and any remaining deterministic findings.
-
+20. Run the build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` so samples compile, API discovery is reflection-precise, and DocFX builds in a temp copy.
+21. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
+22. Report verification results and any remaining deterministic findings.
+
 ## Repo-wide audit workflow
-
-Use this path when the user invokes the skill without naming a specific API or namespace.
-
-1. Run `agents.cs`.
-2. Run the safety gates: inspect `git status --short`, identify existing documentation work, and avoid broad restore or recovery commands.
-3. Read repository guidance, especially root `AGENTS.md`.
-4. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
-5. Read `references/docfx-overwrite-files.md`.
-6. Run `docfx.cs --json --repair-plan /tmp/docfx-repair-plan.md --search-examples` and read the repair plan. The plan is the authoritative work queue. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs for each documented package — run or open these searches before writing any new example.
-7. If the validator fails before producing documentation diagnostics, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
-8. Check for `ENCODING_CORRUPTION` or `EXTENSION_TABLE_ENCODING` diagnostics first; restore affected files from git before doing any further editing.
-9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
-10. Determine every public non-abstraction type and every public extension method that requires an example.
+
+Use this path when the user invokes the skill without naming a specific API or namespace.
+
+1. Run `agents.cs`.
+2. Run the safety gates: inspect `git status --short`, identify existing documentation work, and avoid broad restore or recovery commands.
+3. Read repository guidance, especially root `AGENTS.md`.
+4. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
+5. Read `references/docfx-overwrite-files.md`.
+6. Run `docfx.cs --json --repair-plan /tmp/docfx-repair-plan.md --search-examples` and read the repair plan. The plan is the authoritative work queue. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs for each documented package — run or open these searches before writing any new example.
+7. If the validator fails before producing documentation diagnostics, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
+8. Check for `ENCODING_CORRUPTION` or `EXTENSION_TABLE_ENCODING` diagnostics first; restore affected files from git before doing any further editing.
+9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
+10. Determine every public non-abstraction type and every public extension method that requires an example.
 11. Create or update missing namespace overview pages with a problem/outcome opening, concrete when-to-use guidance, and a named starting API. Inventory-only prose is unfinished.
-12. Audit related namespace pages together so fixes are consistent across the public API family.
-13. Add or repair `Extension Members` tables for namespaces with public extension methods. Use the literal `⬇️` (U+2B07 U+FE0F) in the Ext column.
-14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
-15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, under `.docfx/api/types/{TypeUid}.md` in Codebelt repositories.
-16. Ensure `docfx.json` includes both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite`, excludes both `api/namespaces/**` and `api/types/**` from `build.content`, and moves legacy authored `.docfx/api/*.md` files into either `api/namespaces/` (namespace pages) or `api/types/` (type pages).
-17. Create explicit examples for public extension methods that still have none.
-18. Build or refresh the example inventory.
-19. Preserve manual edits and correct stale contradictions instead of replacing whole files.
-20. Run `git diff` for touched documentation paths and confirm the diff is intentional.
-21. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
-22. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+12. Audit related namespace pages together so fixes are consistent across the public API family.
+13. Add or repair `Extension Members` tables for namespaces with public extension methods. Use the literal `⬇️` (U+2B07 U+FE0F) in the Ext column.
+14. Add or repair overwrite content for public API items that need examples, remarks, corrected summaries, or availability notes.
+15. Create separate type-page overwrite files for public non-abstraction types that have no example yet, under `.docfx/api/types/{TypeUid}.md` in Codebelt repositories.
+16. Ensure `docfx.json` includes both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite`, excludes both `api/namespaces/**` and `api/types/**` from `build.content`, and moves legacy authored `.docfx/api/*.md` files into either `api/namespaces/` (namespace pages) or `api/types/` (type pages).
+17. Create explicit examples for public extension methods that still have none.
+18. Build or refresh the example inventory.
+19. Preserve manual edits and correct stale contradictions instead of replacing whole files.
+20. Run `git diff` for touched documentation paths and confirm the diff is intentional.
+21. Run `dotnet build`, or `dotnet build -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
+22. Run `dotnet test`, or `dotnet test -p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`.
 23. Run the Completion Repair Loop by rerunning the fast `docfx.cs --json`, repairing every remaining diagnostic, and updating the example inventory until `summary.canClaimCompletion` is `true`. A large queue is still the task, not a reason to stop.
-24. Run the build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` so samples compile, API discovery is reflection-precise, and DocFX builds in a temp copy.
-25. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
+24. Run the build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` so samples compile, API discovery is reflection-precise, and DocFX builds in a temp copy.
+25. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
 26. Report verification results and any remaining deterministic findings.
 
 When resuming a partial repo-wide audit, begin by inventorying all tracked and untracked documentation changes and preserving them as in-flight work. Regenerate the deterministic repair plan and example inventory, use both as the authoritative queue, and work in batches with a fast validator rerun after every batch. The exact final command is `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json`; descriptive references to those activities do not replace running the flags together.
@@ -93,43 +93,119 @@ When resuming a partial repo-wide audit, begin by inventorying all tracked and u
 For the final command, let `auto` choose the execution profile unless the user requests a specific resource policy. High-capacity machines run the isolated DocFX verification lane concurrently with API/sample work; conservative machines remain sequential. Give the outer command a timeout at least five minutes above the validator's child-process timeout (35 minutes with the default 30-minute setting) so timeout diagnostics can be returned normally.
 
 Keep `stderr` visible during the final command. API build, sample compilation, and DocFX verification print a start event, 10-second heartbeats, and a final success/failure event there. Use the phase, PID, elapsed time, last-output age, and current output line to decide whether work is progressing or a child appears stale. Capturing `stdout` for `--json` is safe because progress never enters the JSON stream.
-
-## Namespace page template
-
-Use this template when creating a new namespace overview page:
-
-```markdown
----
-uid: X.Y.Z
-summary: *content
----
-The `X.Y.Z` namespace helps you ...
-Use it when ...
-If you're trying to ..., start with `PrimaryType` or `PrimaryExtensions`.
-
-[!INCLUDE [availability-default](../../includes/availability-default.md)]
-
-### Extension Members
-
-|Type|Ext|Methods|
-|--:|:-:|---|
-|String|⬇️|`ExampleMethod`|
-```
-
-Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path to match the actual file location.
-
-## Type example shape
-
-> **DocFX overwrite Markdown only.** This shape is for writing DocFX overwrite content. Do not create tests from it. Tests are evidence, not output — use tests to understand behavior, then transform that knowledge into consumer-facing examples.
-
-For public non-abstraction types, begin the overwrite file with front matter that maps the body to the `example` property:
-
-````markdown
----
-uid: X.Y.Z.MyType
-example:
-- *content
----
+
+## Project-scoped packets and representative dry runs
+
+A repository-sized authoring queue degrades quality as the target count grows. Process documentation in bounded **project packets** instead, where each packet is one resolved `.csproj` with its metadata group, owned and shared namespaces, public API targets, existing overwrite files, related dirty paths, and scoped diagnostics. Discover packets with `docfx.cs --json` (the `scope.packets` array) or persist them with `docfx.cs --project-manifest <path>`.
+
+Full and dry runs use **identical** evidence, authoring instructions, semantic-quality gates, and sample compilation. The only difference is which packets are selected.
+
+### Build-backed scope is a prerequisite for authoring
+
+The conservative source scanner is for fast Markdown iteration, not authoritative scope. When `summary.apiModelSource` is `source-scan`, scope is `provisional` and the validator emits `BUILD_BACKED_SCOPE_REQUIRED`. Before authoring a full run or a selected dry-run packet, establish reflection-precise scope with `--build-api-model` (or generate DocFX managed-reference YAML). Treat a material fast/build-backed discrepancy as a blocker, not a rounding error.
+
+### Quality-risk pilot stop
+
+Before editing, read `qualityRisk` in the JSON. A run is high-risk when standalone targets exceed 100, extension targets exceed 100, the missing-to-existing example ratio exceeds 10:1, or any symbol-ownership collision remains. In high-risk mode the validator emits `QUALITY_RISK_REVIEW_REQUIRED`: limit the first authoring pass to one project packet or 20 newly authored targets, run the scoped semantic and compilation gates, produce a review inventory of every changed namespace and type page, and obtain explicit user approval before continuing. A dry run is the preferred pilot for very large repositories. Only pass `--allow-high-risk` as an explicit, reviewed decision.
+
+### Working-tree dry run
+
+Dry run is a limited real run that writes useful documentation directly to the working tree. The validator selects and verifies; the agent performs the evidence-based authoring between those invocations:
+
+1. The user may name projects: "Use dotnet-docfx-digest in dry-run mode for Cuemon.Core and src/Cuemon.Net/Cuemon.Net.csproj." Explicit hints override automatic selection and resolve against project path, file name, assembly name, or package id. An unknown hint raises `PROJECT_HINT_NOT_FOUND`; an ambiguous one raises `PROJECT_HINT_AMBIGUOUS`. Resolve both before editing.
+2. With no hints ("Use dotnet-docfx-digest in dry-run mode."), the validator selects one **clean** project from every metadata destination group through a reported, reproducible seed. Do not ask for project hints when none were supplied.
+3. Related files that were already staged, modified, renamed, deleted, or untracked before the run are never edited. A dirty first candidate is skipped for the next clean one; a group with no clean candidate is reported as `DRY_RUN_GROUP_UNSELECTED`.
+4. Before editing, run `docfx.cs --repo-root <root> --dry-run --build-api-model --project-manifest <temp-manifest> --json` plus any supplied `--project` hints. Treat `scope.selectedProjects` and the persisted baseline as the complete write boundary. The command creates `<temp-manifest-name>.review.json` beside the manifest.
+5. Author every selected packet with the same evidence and quality standard as a full run. Do not stop after selection or manifest generation. Read every changed namespace and type page after authoring, compare normalized prose and code patterns across the whole pilot, and complete every entry in the generated review JSON: `evidence`, page-specific `purpose`, `observableOutcome` (use `namespace guidance` only for namespace pages), and `patternComparison`. Also prepare the same information as a `Changed-page review` table for the final response. A file list or clean validator summary is not this review.
+6. Resume the exact baseline with `docfx.cs --repo-root <root> --resume-project-manifest <temp-manifest> --review-report <temp-review> --build-api-model --validate-samples --verify-docfx-build --json`. This validates files created by the current run without reclassifying them as pre-existing dirty work. Missing, placeholder, or incomplete review entries raise `REVIEW_REPORT_MISSING`, `REVIEW_REPORT_INVALID`, or `REVIEW_REPORT_INCOMPLETE`; an invalid or stale manifest fails closed and selects no fallback projects.
+7. Continue repairing the selected packets until the resumed command reports `dry-run-passed`, zero remaining gates, compiled samples, and a verified DocFX build. Any error or omitted final gate is `dry-run-failed`.
+8. Dry run never claims the repository digest is complete. Report selected projects, seed, the complete changed-page review table, representative prose/examples, reproduction command, and resume command for human approval before a full run.
+
+Use `--dry-run [--seed <n>]` for automatic selection, `--dry-run --project <hint> [--project <hint> ...]` for explicit selection, and always pair the initial `--project-manifest` invocation with the final `--resume-project-manifest` invocation. Use `--project <hint>` without `--dry-run` only for a scoped non-random validation; it still cannot claim repository completion.
+
+### Packet authoring loop
+
+Process one packet at a time so the packet is the active context and write-ownership boundary. When the host supports fresh workers, assign each packet to a fresh worker with only packet-local evidence. For each packet: read the manifest and scoped diagnostics, read related Markdown before editing, read exact source/test/sample/package evidence, build an evidence ledger mapping each decision to a source path, classify targets into standalone-example or family-covered obligations, author namespace prose and overwrites, run the scoped semantic and sample gates, and review the diff. Stop the entire run immediately if a packet fails its quality gates — do not continue to later packets after mechanical output is detected.
+
+### Symbol ownership
+
+Duplicate simple type names across assemblies (`SYMBOL_COLLISION_UNRESOLVED`), forwarded type families that cannot be attributed (`TYPE_FORWARDING_UNRESOLVED`), and extension containers that cross project boundaries (`EXTENSION_OWNER_AMBIGUOUS`) require assembly/project-qualified resolution. Prefer receiver extension syntax over static-container qualification when container names collide, and target the uniquely owned overwrite UID.
+
+### Family exemptions
+
+A heavily generic, inherited, overloaded, or arity-based type series may replace redundant standalone examples with one anchor example plus deep namespace guidance. Declare exemptions explicitly in `.docfx/family-exemptions.json`:
+
+```json
+{
+  "families": [
+    {
+      "familyId": "tuple-arity",
+      "namespaceUid": "Cuemon.Collections",
+      "anchorUid": "Cuemon.Collections.MutableTuple`1",
+      "anchorExampleFile": ".docfx/api/types/Cuemon.Collections.MutableTuple`1.md",
+      "rationale": "generic-arity",
+      "coveredUids": ["Cuemon.Collections.MutableTuple`2", "Cuemon.Collections.MutableTuple`3"]
+    }
+  ]
+}
+```
+
+`rationale` must be one of `generic-arity`, `inherited-specialization`, `overload-series`, or `type-parameter-series`. The validator removes covered siblings from standalone-example obligations only after the declaration validates: all UIDs must exist, share the declared namespace, and avoid duplicate or circular coverage. A family is rejected (`FAMILY_EXEMPTION_INVALID`) when it groups unrelated or out-of-namespace types — category alone never exempts options, exceptions, delegates, records, or data carriers. The anchor must have a real behavioral example (`FAMILY_ANCHOR_EXAMPLE_MISSING` otherwise), and the namespace page must name the anchor and explain how consumers choose among siblings (`FAMILY_NAMESPACE_GUIDANCE_MISSING` otherwise). Every sibling still needs accurate purpose-first prose that relates it to the anchor.
+
+### Safe overwrite writer
+
+For repeatable overwrite creation, hand authored content to the structured writer instead of improvising fenced Markdown with ad-hoc scripts: write a request file with `file`, `uid`, `mapping` (`example`/`summary`/`remarks`), `prose`, and `fence`, then run `docfx.cs --write-overwrite <request.json>`. The writer validates YAML, rejects duplicate UIDs and unbalanced fences, preserves the file's BOM and line endings, refuses to replace a pre-existing dirty file, and prints a change preview. It never generates prose, selects members, or synthesizes examples — that remains your evidence-grounded editorial work.
+
+### Evidence-grounded scenario patterns
+
+These are search directions, not templates to emit verbatim. Confirm every pattern against packet-local source, tests, samples, or package documentation before writing, and reject generic `Workflow`, `Current`, `Consumer`, and mass-forwarding shells when they are not real concepts in the package:
+
+- **Options configuration** — bind or build an options object, then show the operation that consumes it.
+- **Middleware / DI registration** — register the service on a builder, then show the request or resolution it enables.
+- **Authentication header construction** — build the credential/header, then attach it to a request.
+- **MVC filters / results** — apply the filter or return the result, then show the observable response.
+- **Stream processing / compression** — wrap or transform a stream, then read or write the transformed bytes.
+- **Formatter setup** — configure the formatter, then serialize or deserialize a payload.
+- **Delegate / factory pipelines** — register the factory, then invoke it to produce a configured instance.
+
+Each chosen scenario must still produce, configure, transform, register, send, store, or validate something a real caller observes.
+
+
+
+Use this template when creating a new namespace overview page:
+
+```markdown
+---
+uid: X.Y.Z
+summary: *content
+---
+The `X.Y.Z` namespace helps you ...
+Use it when ...
+If you're trying to ..., start with `PrimaryType` or `PrimaryExtensions`.
+
+[!INCLUDE [availability-default](../../includes/availability-default.md)]
+
+### Extension Members
+
+|Type|Ext|Methods|
+|--:|:-:|---|
+|String|⬇️|`ExampleMethod`|
+```
+
+Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path to match the actual file location.
+
+## Type example shape
+
+> **DocFX overwrite Markdown only.** This shape is for writing DocFX overwrite content. Do not create tests from it. Tests are evidence, not output — use tests to understand behavior, then transform that knowledge into consumer-facing examples.
+
+For public non-abstraction types, begin the overwrite file with front matter that maps the body to the `example` property:
+
+````markdown
+---
+uid: X.Y.Z.MyType
+example:
+- *content
+---
 The following schematic shows the overwrite shape only. Replace it with a source-backed consumer task; do not copy the generic names into product documentation.
 
 ```csharp
@@ -144,26 +220,26 @@ public class WidgetFactory
         return new MyType();
     }
 }
-```
-````
-
-Do not include a manual `### Examples` heading in the body. DocFX renders that heading automatically for the `example` property. Every `csharp` code block must include a file-scoped namespace and at least one class declaration; top-level statements are not allowed unless the block is labelled `// Program.cs`.
-
-## Extension method example template
-
-Apply the same `example: - *content` rule for extension-method examples:
-
-````markdown
----
-uid: X.Y.Z.MyExtensions
-example:
-- *content
----
+```
+````
+
+Do not include a manual `### Examples` heading in the body. DocFX renders that heading automatically for the `example` property. Every `csharp` code block must include a file-scoped namespace and at least one class declaration; top-level statements are not allowed unless the block is labelled `// Program.cs`.
+
+## Extension method example template
+
+Apply the same `example: - *content` rule for extension-method examples:
+
+````markdown
+---
+uid: X.Y.Z.MyExtensions
+example:
+- *content
+---
 The following example normalizes text before persisting it, making the operation and its next step visible.
-
-```csharp
-using X.Y.Z;
-
+
+```csharp
+using X.Y.Z;
+
 namespace TextImport;
 
 public class ImportedNote
@@ -173,34 +249,34 @@ public class ImportedNote
         return text.NormalizeLineEndings();
     }
 }
-```
-````
-
-The namespace containing the extension method must be imported, the receiver type must be valid, and the sample must compile in a class library verification project.
-
-## Synthetic hash-suffix filenames are prohibited
-
-DocFX can generate synthetic method UIDs for generic or overloaded extension methods that contain hashes, encoding characters, or computed suffixes. Never mirror those UIDs directly in filenames.
-
-Bad examples:
-
-- `EndpointConventionBuilderExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md`
-- `EndpointConventionBuilderExtensions.%3CT%3E...md`
-
-Keep the filename readable, place the example in the declaring extension class file or the namespace page, and let the YAML `uid` determine what model receives the content.
-
-## Verification checklist
-
-Before completing documentation work, verify:
-
-- [ ] `agents.cs` ran successfully.
-- [ ] `AGENTS.md` contains the managed DocFX maintenance block.
-- [ ] Initial `git status --short` was inspected and existing documentation changes were treated as user work.
-- [ ] For multi-diagnostic audits, `docfx.cs --repair-plan` was written, read, and used as the work queue.
-- [ ] Only public API is documented.
-- [ ] Every namespace with public API has a namespace overview page.
-- [ ] Related namespace pages in the same public API family were inspected and updated consistently, or intentionally left unchanged with a reason.
-- [ ] Namespaces with public extension methods have an `Extension Members` section.
+```
+````
+
+The namespace containing the extension method must be imported, the receiver type must be valid, and the sample must compile in a class library verification project.
+
+## Synthetic hash-suffix filenames are prohibited
+
+DocFX can generate synthetic method UIDs for generic or overloaded extension methods that contain hashes, encoding characters, or computed suffixes. Never mirror those UIDs directly in filenames.
+
+Bad examples:
+
+- `EndpointConventionBuilderExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md`
+- `EndpointConventionBuilderExtensions.%3CT%3E...md`
+
+Keep the filename readable, place the example in the declaring extension class file or the namespace page, and let the YAML `uid` determine what model receives the content.
+
+## Verification checklist
+
+Before completing documentation work, verify:
+
+- [ ] `agents.cs` ran successfully.
+- [ ] `AGENTS.md` contains the managed DocFX maintenance block.
+- [ ] Initial `git status --short` was inspected and existing documentation changes were treated as user work.
+- [ ] For multi-diagnostic audits, `docfx.cs --repair-plan` was written, read, and used as the work queue.
+- [ ] Only public API is documented.
+- [ ] Every namespace with public API has a namespace overview page.
+- [ ] Related namespace pages in the same public API family were inspected and updated consistently, or intentionally left unchanged with a reason.
+- [ ] Namespaces with public extension methods have an `Extension Members` section.
 - [ ] Public non-abstraction types have at least one type-page example.
 - [ ] Public extension methods have at least one explicit example, not only a table entry.
 - [ ] Package IDs and package-level usage evidence were inspected before type/member-only sample synthesis.
@@ -209,38 +285,38 @@ Before completing documentation work, verify:
 - [ ] Examples show a coherent consumer workflow, use related public types when helpful, and avoid placeholder-only `Consumer`/`MyNamespace` shells when a domain name is available.
 - [ ] No example is reflection-only, metadata-only, duplicated by UID, or built from `DocumentedTypeExample`, `DocumentedExtensionExample`, or generic `Describe()` scaffolding.
 - [ ] The C# fence itself uses the documented type or invokes the documented extension method; prose, comments, and strings are not counted as usage.
-- [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`. Namespace pages are under `api/namespaces/` and type pages are under `api/types/`.
+- [ ] Missing examples are added through DocFX overwrite content included by `build.overwrite`. Namespace pages are under `api/namespaces/` and type pages are under `api/types/`.
 - [ ] The Completion Repair Loop was run after edits, and the final report has zero missing/low-quality example, namespace-prose, extension, availability, overwrite-layout, sample, and DocFX-build diagnostics.
-- [ ] Examples are realistic, copy/paste-ready, and compile unless a justified skip marker is present.
-- [ ] Generated C# examples include a file-scoped namespace and a type declaration (class, struct, or record), or are explicitly labelled `// Program.cs`.
-- [ ] No generated C# example uses top-level statements without a `// Program.cs` label.
-- [ ] No generated C# example derives from a generic base type without concrete type arguments.
-- [ ] No generated C# example calls members that are not confirmed on the public API surface.
-- [ ] Where no compile-valid example could be generated, the overwrite file contains the appropriate omission comment.
-- [ ] Availability is included or explicitly stated and matches actual target frameworks and conditions.
-- [ ] Existing manual edits are preserved, stale documentation is corrected, and no contradictory documentation remains.
-- [ ] `git diff` for touched documentation paths was inspected before final verification.
-- [ ] `dotnet build` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
-- [ ] `dotnet test` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
+- [ ] Examples are realistic, copy/paste-ready, and compile unless a justified skip marker is present.
+- [ ] Generated C# examples include a file-scoped namespace and a type declaration (class, struct, or record), or are explicitly labelled `// Program.cs`.
+- [ ] No generated C# example uses top-level statements without a `// Program.cs` label.
+- [ ] No generated C# example derives from a generic base type without concrete type arguments.
+- [ ] No generated C# example calls members that are not confirmed on the public API surface.
+- [ ] Where no compile-valid example could be generated, the overwrite file contains the appropriate omission comment.
+- [ ] Availability is included or explicitly stated and matches actual target frameworks and conditions.
+- [ ] Existing manual edits are preserved, stale documentation is corrected, and no contradictory documentation remains.
+- [ ] `git diff` for touched documentation paths was inspected before final verification.
+- [ ] `dotnet build` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
+- [ ] `dotnet test` has been run, using `-p:SkipSignAssembly=true` when a Codebelt repository has no root `.snk`, or the failure is reported.
 - [ ] The build-backed completion verification `docfx.cs --build-api-model --validate-samples --verify-docfx-build` ran successfully, and final JSON reports `summary.canClaimCompletion: true`, `summary.remainingWorkItems: 0`, an empty `summary.remainingGates`, and an empty `summary.remainingDiagnosticsByCode`.
-- [ ] Generated metadata files and build output directories did not remain in the working tree after verification, and authored Markdown or documentation assets were not deleted as cleanup.
-- [ ] No broad restore or checkout command discarded authored documentation changes.
-
-## Completion response
-
-When reporting completion, include:
-
-- public APIs documented
-- namespace pages added or updated
-- extension-member tables added or updated
-- examples added, their source test or sample when applicable, and the example inventory by public type or extension method
-- availability handling
-- related namespace pages inspected and whether each was updated or left unchanged
-- `AGENTS.md` created, updated, already compliant, or failed
-- signing-key handling: whether a root `.snk` was used or `-p:SkipSignAssembly=true` was used because no root `.snk` was present
-- verification commands run
-- any verification failures or skipped checks
-
+- [ ] Generated metadata files and build output directories did not remain in the working tree after verification, and authored Markdown or documentation assets were not deleted as cleanup.
+- [ ] No broad restore or checkout command discarded authored documentation changes.
+
+## Completion response
+
+When reporting completion, include:
+
+- public APIs documented
+- namespace pages added or updated
+- extension-member tables added or updated
+- examples added, their source test or sample when applicable, and the example inventory by public type or extension method
+- availability handling
+- related namespace pages inspected and whether each was updated or left unchanged
+- `AGENTS.md` created, updated, already compliant, or failed
+- signing-key handling: whether a root `.snk` was used or `-p:SkipSignAssembly=true` was used because no root `.snk` was present
+- verification commands run
+- any verification failures or skipped checks
+
 Do not claim documentation was verified unless the relevant command actually ran successfully.
 
 If work must stop incomplete, distinguish a true external blocker from repair work. Pre-existing documentation gaps, large diagnostic counts, sample compile failures, and `DOCFX_BUILD_FAILED` output caused by the documentation/configuration being repaired are active work items. Only a user pause or an external condition that still prevents progress after concrete attempts justifies stopping, and that response must say the digest remains incomplete.

From b3285a4c1281867670b2771f1807e4a18446c163 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 00:02:26 +0200
Subject: [PATCH 72/88] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20enhance=20docfx=20sk?=
 =?UTF-8?q?ill=20implementation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Significantly expands docfx.cs with improved functionality for namespace analysis, type documentation, and evidence collection. Enhances test-quality.ps1 with advanced validation. Adds test-project-scoped.ps1 for project-level testing.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 2209 ++++++++++++++++-
 .../scripts/test-project-scoped.ps1           |  659 +++++
 .../scripts/test-quality.ps1                  |  410 ++-
 3 files changed, 3205 insertions(+), 73 deletions(-)
 create mode 100644 skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 362880a..ea5e43d 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -78,6 +78,12 @@ public static int Run(string[] args)
 
         try
         {
+            if (options.WriteOverwriteRequestPath is not null)
+            {
+                ConfigureProcessGuard(options);
+                return WriteOverwriteCommand(options);
+            }
+
             return Validate(options);
         }
         catch (Exception ex)
@@ -183,7 +189,7 @@ private static int Validate(Options options)
 
         // 4. Discover DocFX metadata projects from the active docfx.json (no build required).
         phaseTimer.Restart();
-        var projects = DiscoverProjects(docfxPath, docfxWorkspace, report);
+        var projects = DiscoverProjects(docfxPath, docfxWorkspace, report, out var metadataGroups);
         WritePhase(options, report, "project discovery", phaseTimer.Elapsed);
         if (projects.Count == 0)
         {
@@ -240,6 +246,7 @@ private static int Validate(Options options)
         //    --build-api-model opts into reflection-backed discovery from compiled assemblies.
         phaseTimer.Restart();
         ApiModel api;
+        ApiModelSource apiModelSource;
         if (mode == ValidationMode.BuildBackedApiModel)
         {
             var (buildOk, buildOutput) = BuildDocfxProjects(libraryProjects, repoRoot, options.Configuration,
@@ -265,6 +272,7 @@ private static int Validate(Options options)
             }
 
             report.Summary.ApiModelSource = "build-backed";
+            apiModelSource = ApiModelSource.BuildBacked;
             WritePhase(options, report, "api model", phaseTimer.Elapsed, "build-backed");
 
             if (api.Namespaces.Count == 0)
@@ -278,6 +286,7 @@ private static int Validate(Options options)
         else
         {
             api = BuildNoBuildApiModel(workspace, report, out var apiSource);
+            apiModelSource = apiSource;
             report.Summary.ApiModelSource = apiSource == ApiModelSource.DocfxYaml ? "docfx-yaml" : "source-scan";
             WritePhase(options, report, "api model", phaseTimer.Elapsed, report.Summary.ApiModelSource);
 
@@ -306,10 +315,47 @@ private static int Validate(Options options)
 
         var allOverwriteSections = workspace.OverwriteSections;
 
+        // 6b. Project-scoped discovery: git state, packets, family exemptions, symbol ownership,
+        //     and scope selection (full / explicit hints / seeded dry-run) before validation so the
+        //     namespace and required-example checks can be scoped to the selected packets.
+        phaseTimer.Restart();
+        EnsureNamespaceProjectMap(workspace);
+        var gitState = GetGitState(repoRoot);
+        var resumeScope = options.ResumeProjectManifestPath is null
+            ? null
+            : LoadResumeProjectManifest(options.ResumeProjectManifestPath, repoRoot, report);
+        var packets = BuildProjectPackets(workspace, api, gitState, metadataGroups, repoRoot, docfxWorkspace,
+            resumeScope?.InitialDirtyPaths);
+        var families = LoadAndValidateFamilyExemptions(repoRoot, docfxWorkspace, api, workspace, namespacePageIndex, report);
+        ApplyFamilyExemptions(api, families);
+        report.Summary.RequiredExampleTargets = api.RequiredExampleTargets.Count;
+        ValidateSymbolOwnership(api, workspace, packets, report, out var symbolCollisions, out var typeForwarded, out var extensionAmbiguous);
+        var scope = ResolveScope(options, packets, metadataGroups, apiModelSource, repoRoot, report, resumeScope);
+        report.Summary.RunMode = scope.Mode;
+        report.Summary.Seed = scope.Seed;
+        report.Summary.ScopeState = scope.ScopeState;
+        WritePhase(options, report, "project scope", phaseTimer.Elapsed,
+            $"{scope.Mode}; {packets.Count(p => p.Selected)}/{packets.Count} packet(s)");
+
+        // Append-only packet selection status on stderr keeps the single-document JSON stdout clean
+        // while still giving a live view of which project packet is active (Phase 11 heartbeats).
+        var selectedPackets = packets.Where(p => p.Selected).ToList();
+        for (var pi = 0; pi < selectedPackets.Count; pi++)
+        {
+            var pkt = selectedPackets[pi];
+            Console.Error.WriteLine($"[ ] project {pi + 1}/{selectedPackets.Count} | {pkt.Project.AssemblyName} | scope={scope.Mode} | {pkt.Targets.Count} target(s){(pkt.SharedNamespaces.Count > 0 ? $" | shared:{string.Join(",", pkt.SharedNamespaces)}" : string.Empty)}");
+        }
+
         // 7. Validate namespace overview pages, extension tables and availability.
         phaseTimer.Restart();
+        var proseFingerprints = new List<(string Namespace, string Path, string Fingerprint)>();
         foreach (var ns in api.Namespaces.OrderBy(n => n.Name, StringComparer.Ordinal))
         {
+            if (!scope.IncludesNamespace(ns.Name))
+            {
+                continue;
+            }
+
             namespacePageIndex.TryGetValue(ns.Name, out var page);
             if (page is null)
             {
@@ -323,15 +369,17 @@ private static int Validate(Options options)
                 continue;
             }
 
-            ValidateNamespacePage(repoRoot, page, workspace.ReadMarkdown(page), ns, report);
+            ValidateNamespacePage(repoRoot, page, workspace.ReadMarkdown(page), ns, report, proseFingerprints);
             report.Summary.NamespacePagesValidated++;
         }
 
+        ValidateNamespaceProseRepetition(proseFingerprints, report);
+
         WritePhase(options, report, "namespace validation", phaseTimer.Elapsed);
 
         // 8. Verify mandatory examples exist before compiling the examples that were found.
         phaseTimer.Restart();
-        ValidateRequiredExamples(repoRoot, docfxWorkspace, allOverwriteSections, api, options, changedFiles, report);
+        ValidateRequiredExamples(repoRoot, docfxWorkspace, allOverwriteSections, api, options, changedFiles, scope, workspace.NamespaceProjects, report);
         WritePhase(options, report, "required example validation", phaseTimer.Elapsed);
 
         // 9. Extract and compile C# documentation samples (opt-in: the only path that compiles).
@@ -374,6 +422,29 @@ private static int Validate(Options options)
         }
 
         // 11. Produce report and return a deterministic exit code.
+        if (options.ResumeProjectManifestPath is not null)
+        {
+            ValidateChangedPageReview(options.ReviewReportPath, repoRoot, packets, gitState, report);
+        }
+
+        var qualityRisk = EvaluateQualityRisk(options, api, packets, report.Summary.RequiredExamples,
+            symbolCollisions, typeForwarded, extensionAmbiguous, scope, report);
+        report.QualityRisk = qualityRisk;
+        report.Scope = BuildScopeReport(scope, packets, metadataGroups, gitState, families, repoRoot, report);
+        if (options.ProjectManifestPath is not null)
+        {
+            try
+            {
+                WriteProjectManifest(options.ProjectManifestPath, repoRoot, docfxPath, report.Scope, qualityRisk,
+                    report.Summary.ApiModelSource ?? "unknown", report);
+            }
+            catch (Exception ex)
+            {
+                report.Warnings.Add(new Diagnostic("PROJECT_MANIFEST_WRITE_FAILED", options.ProjectManifestPath, null,
+                    $"Unable to write the project manifest: {ex.Message}"));
+            }
+        }
+
         bool hasSampleError = report.Errors.Any(e => e.Code is "SAMPLE_COMPILE_FAILED" or "SAMPLE_STRUCTURE_INVALID");
         bool hasOtherError = report.Errors.Any(e => e.Code is not "SAMPLE_COMPILE_FAILED" and not "SAMPLE_STRUCTURE_INVALID");
 
@@ -1449,7 +1520,12 @@ private static bool HasRootStrongNameKey(string repoRoot)
     /// for deterministic ordering.
     /// </summary>
     private static List<ProjectInfo> DiscoverProjects(string docfxPath, string docfxWorkspace, Report report)
+        => DiscoverProjects(docfxPath, docfxWorkspace, report, out _);
+
+    private static List<ProjectInfo> DiscoverProjects(string docfxPath, string docfxWorkspace, Report report,
+        out List<MetadataGroupInfo> groups)
     {
+        groups = new List<MetadataGroupInfo>();
         JsonDocument doc;
         try
         {
@@ -1468,6 +1544,7 @@ private static List<ProjectInfo> DiscoverProjects(string docfxPath, string docfx
 
         var resolvedPaths = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
         var resolvedProjects = new List<(string NormalizedPath, ProjectInfo Project)>();
+        var groupsByDest = new Dictionary<string, MetadataGroupInfo>(StringComparer.OrdinalIgnoreCase);
 
         using (doc)
         {
@@ -1479,13 +1556,40 @@ private static List<ProjectInfo> DiscoverProjects(string docfxPath, string docfx
                 return new List<ProjectInfo>();
             }
 
+            var metadataIndex = -1;
             foreach (var entry in EnumerateMetadataEntries(metadata))
             {
+                metadataIndex++;
                 if (entry.ValueKind != JsonValueKind.Object || !entry.TryGetProperty("src", out var srcArray))
                 {
                     continue;
                 }
 
+                // A metadata destination ("dest", default "api") defines a sampling group. Every
+                // src.files mapping feeding that destination belongs to it; distinct destinations
+                // are never collapsed into one ownership-free list.
+                var dest = entry.TryGetProperty("dest", out var destEl) && destEl.ValueKind == JsonValueKind.String &&
+                           !string.IsNullOrWhiteSpace(destEl.GetString())
+                    ? NormalizeDocfxPath(destEl.GetString()!.Trim())
+                    : "api";
+                if (!groupsByDest.TryGetValue(dest, out var group))
+                {
+                    group = new MetadataGroupInfo(dest, metadataIndex, dest);
+                    groupsByDest[dest] = group;
+                    groups.Add(group);
+                }
+
+                if (entry.TryGetProperty("properties", out var props) && props.ValueKind == JsonValueKind.Object)
+                {
+                    foreach (var prop in props.EnumerateObject())
+                    {
+                        if (prop.Value.ValueKind == JsonValueKind.String)
+                        {
+                            group.Properties[prop.Name] = prop.Value.GetString() ?? string.Empty;
+                        }
+                    }
+                }
+
                 foreach (var srcEntry in EnumerateDocfxFileMappingEntries(srcArray))
                 {
                     // Default base directory is the docfx.json workspace; overridden by src[].src.
@@ -1524,6 +1628,11 @@ private static List<ProjectInfo> DiscoverProjects(string docfxPath, string docfx
                         {
                             resolvedProjects.Add((normalizedPath, ReadProject(normalizedPath)));
                         }
+
+                        if (!group.ProjectPaths.Contains(normalizedPath, StringComparer.OrdinalIgnoreCase))
+                        {
+                            group.ProjectPaths.Add(normalizedPath);
+                        }
                     }
                 }
             }
@@ -1539,6 +1648,13 @@ private static List<ProjectInfo> DiscoverProjects(string docfxPath, string docfx
             return new List<ProjectInfo>();
         }
 
+        foreach (var group in groups)
+        {
+            group.ProjectPaths.Sort((a, b) => string.Compare(NormalizeDocfxPath(a), NormalizeDocfxPath(b), StringComparison.OrdinalIgnoreCase));
+        }
+
+        groups.Sort((a, b) => string.Compare(a.Dest, b.Dest, StringComparison.OrdinalIgnoreCase));
+
         // Sort by normalised path for deterministic, idempotent ordering.
         return resolvedProjects
             .OrderBy(p => NormalizeDocfxPath(p.NormalizedPath), StringComparer.OrdinalIgnoreCase)
@@ -1974,7 +2090,7 @@ private static ApiModel DiscoverApiFromSource(ValidationWorkspace ws, Report rep
                     continue;
                 }
 
-                ScanSourceFile(text, namespaces, staticExtensionContainers, ws, project);
+                ScanSourceFile(text, namespaces, staticExtensionContainers, ws, project, report);
             }
         }
 
@@ -2005,13 +2121,15 @@ private static void ScanSourceFile(
         Dictionary<string, NamespaceInfo> namespaces,
         Dictionary<string, (string Namespace, string DisplayName, int Count)> staticExtensionContainers,
         ValidationWorkspace ws,
-        ProjectInfo project)
+        ProjectInfo project,
+        Report report)
     {
         var lines = text.Replace("\r\n", "\n").Replace("\r", "\n").Split('\n');
         var cleaned = StripCommentsAndStrings(lines);
 
         string? currentNamespace = null;
         var namespaceBodyDepth = 0;
+        var pendingNamespaceBrace = false;
         var depth = 0;
         string? currentTopLevelStaticClass = null;
         var currentTopLevelStaticClassDepth = -1;
@@ -2021,13 +2139,49 @@ private static void ScanSourceFile(
         {
             var clean = cleaned[i];
 
-            var nsMatch = Regex.Match(clean, @"^\s*namespace\s+(?<ns>[\w.]+)\s*(?<brace>\{)?\s*;?\s*$");
+            var nsMatch = Regex.Match(clean, @"^\s*namespace\s+(?<ns>[\w.]+)\s*(?<brace>\{)?\s*(?<semi>;)?\s*$");
             if (nsMatch.Success)
             {
                 currentNamespace = nsMatch.Groups["ns"].Value;
                 RegisterNamespaceProject(ws, currentNamespace, project);
                 GetOrAddNamespace(namespaces, currentNamespace);
-                namespaceBodyDepth = nsMatch.Groups["brace"].Success ? depth + 1 : depth;
+                if (nsMatch.Groups["brace"].Success)
+                {
+                    // Block namespace whose opening brace is on the declaration line.
+                    namespaceBodyDepth = depth + 1;
+                    pendingNamespaceBrace = false;
+                }
+                else if (nsMatch.Groups["semi"].Success)
+                {
+                    // File-scoped namespace: the body shares the current brace depth.
+                    namespaceBodyDepth = depth;
+                    pendingNamespaceBrace = false;
+                }
+                else
+                {
+                    // Block namespace whose opening brace appears on a later line. Defer the
+                    // body-depth decision until that brace is seen so the common Cuemon style
+                    //     namespace Foo
+                    //     {
+                    // is not silently under-reported (the brace pushes real depth past a
+                    // prematurely fixed namespaceBodyDepth, hiding every top-level type).
+                    pendingNamespaceBrace = true;
+                }
+
+                depth += CountChar(clean, '{') - CountChar(clean, '}');
+                continue;
+            }
+
+            if (pendingNamespaceBrace)
+            {
+                // Only trivia (comments, blank lines) is legal between a block namespace
+                // declaration and its opening brace, so the first '{' opens the body.
+                if (clean.IndexOf('{') >= 0)
+                {
+                    namespaceBodyDepth = depth + 1;
+                    pendingNamespaceBrace = false;
+                }
+
                 depth += CountChar(clean, '{') - CountChar(clean, '}');
                 continue;
             }
@@ -2101,6 +2255,14 @@ private static void ScanSourceFile(
                 }
             }
         }
+
+        if (pendingNamespaceBrace && currentNamespace is not null)
+        {
+            // A block namespace declaration was never paired with an opening brace. Surface this
+            // rather than silently under-reporting the file's public types.
+            report.Warnings.Add(new Diagnostic("API_MODEL_SOURCE_SCANNER_INCOMPLETE", null, currentNamespace,
+                $"Source scanner could not pair the block namespace declaration '{currentNamespace}' with an opening brace, so its public types may be under-reported. Confirm the documentation scope with a build-backed audit before authoring."));
+        }
     }
 
     private static IEnumerable<string> EnumerateProjectSourceFiles(ProjectInfo project)
@@ -3218,7 +3380,8 @@ private static string SimpleTypeName(Type type)
     // Namespace page validation
     // ----------------------------------------------------------------------
 
-    private static void ValidateNamespacePage(string repoRoot, string page, string text, NamespaceInfo ns, Report report)
+    private static void ValidateNamespacePage(string repoRoot, string page, string text, NamespaceInfo ns, Report report,
+        List<(string Namespace, string Path, string Fingerprint)>? proseFingerprints = null)
     {
         var rel = Rel(repoRoot, page);
         if (string.IsNullOrEmpty(text))
@@ -3261,6 +3424,7 @@ private static void ValidateNamespacePage(string repoRoot, string page, string t
         else
         {
             var firstParagraph = proseParagraphs[0];
+            var laterParagraphs = proseParagraphs.Skip(1).ToList();
             var prose = string.Join(" ", proseParagraphs.Take(3));
             if (IsInventoryOnlyNamespaceProse(firstParagraph))
             {
@@ -3268,6 +3432,17 @@ private static void ValidateNamespacePage(string repoRoot, string page, string t
                     "The namespace overview only inventories types or extension methods. Rewrite the opening around the developer problem it solves, the outcome it enables, and when a consumer should use it."));
             }
 
+            // Append-only repair: a weak inventory-led opening was left intact while the real usage
+            // or start-here guidance was tacked on in a later paragraph. The opening must be rewritten
+            // around the developer problem rather than patched beneath, even when the lead contains a
+            // generic verb such as "enable" or "provide".
+            if (IsInventoryLedOpening(firstParagraph) && !HasNamespaceProblemFraming(firstParagraph) &&
+                laterParagraphs.Any(p => HasNamespaceUsageGuidance(p) || HasNamespaceStartHereGuidance(p)))
+            {
+                report.Errors.Add(new Diagnostic("NAMESPACE_APPEND_ONLY_REPAIR", rel, ns.Name,
+                    "The opening paragraph still leads with a type inventory while usage or start-here guidance is appended in a later paragraph. Rewrite the opening cohesively around the developer problem and outcome instead of leaving the weak lead intact beneath an appended sentence."));
+            }
+
             if (!HasNamespaceUsageGuidance(prose))
             {
                 report.Errors.Add(new Diagnostic("NAMESPACE_USAGE_GUIDANCE_MISSING", rel, ns.Name,
@@ -3280,6 +3455,17 @@ private static void ValidateNamespacePage(string repoRoot, string page, string t
                 report.Errors.Add(new Diagnostic("NAMESPACE_START_HERE_MISSING", rel, ns.Name,
                     "The namespace exposes multiple public entry points but does not direct a newcomer to a useful starting type or method. Name the API to start with and distinguish the nearby alternatives."));
             }
+
+            var skeleton = NormalizeProseSkeleton(prose);
+            if (proseFingerprints is not null && skeleton.Length >= 40)
+            {
+                proseFingerprints.Add((ns.Name, rel, "lexical:" + skeleton));
+                var rhetoricalSkeleton = NormalizeNamespaceRhetoricalSkeleton(prose);
+                if (rhetoricalSkeleton is not null)
+                {
+                    proseFingerprints.Add((ns.Name, rel, "rhetorical:" + rhetoricalSkeleton));
+                }
+            }
         }
 
         // availability
@@ -3436,6 +3622,110 @@ private static bool IsInventoryOnlyNamespaceProse(string paragraph)
                !HasNamespaceUsageGuidance(paragraph);
     }
 
+    // An inventory-led opening begins by listing what the surface holds ("contains types",
+    // "provides helpers", "the X namespace exposes ..."). This is independent of generic guidance
+    // verbs, so it still matches a lead that ends with "... to enable Y".
+    private static bool IsInventoryLedOpening(string paragraph)
+    {
+        var firstSentence = Regex.Match(paragraph, @"^(.*?[.!?])(?:\s|$)").Groups[1].Value;
+        if (string.IsNullOrEmpty(firstSentence))
+        {
+            firstSentence = paragraph;
+        }
+
+        return Regex.IsMatch(firstSentence,
+            @"(?i)^(?:the\s+)?(?:`?[\w.]+`?\s+)?namespace\s+(?:contains|provides|includes|exposes|groups|collects|offers|defines|holds)\b") ||
+               Regex.IsMatch(firstSentence,
+            @"(?i)\b(?:contains|provides|includes|exposes|groups|collects|offers|defines|holds)\s+(?:a\s+(?:set|collection|number|group)\s+of\s+)?(?:the\s+)?(?:types|classes|helpers?|members?|utilities|extension\s+methods|functionality|apis?|abstractions?)\b");
+    }
+
+    // Problem framing means the opening explains the developer problem or outcome rather than the
+    // surface contents: it leads with the reader's task ("use X when ...", "to ... without ...").
+    private static bool HasNamespaceProblemFraming(string paragraph)
+    {
+        var firstSentence = Regex.Match(paragraph, @"^(.*?[.!?])(?:\s|$)").Groups[1].Value;
+        if (string.IsNullOrEmpty(firstSentence))
+        {
+            firstSentence = paragraph;
+        }
+
+        return !IsInventoryLedOpening(firstSentence) &&
+               Regex.IsMatch(firstSentence,
+                   @"(?i)\b(?:use\b|when\b|need\b|want\b|choose\b|prefer\b|reach for\b|so that\b|without having to\b|without\b|to\s+\w+\s+(?:a|an|the|your))\b");
+    }
+
+    // Collapses namespace prose to a sentence skeleton: inline code, identifiers, namespace names
+    // and numbers become placeholders so two pages that share a mechanical template (only type names
+    // substituted) normalize to the same value.
+    private static string NormalizeProseSkeleton(string prose)
+    {
+        var text = Regex.Replace(prose, @"`[^`]*`", " CODE ");
+        text = Regex.Replace(text, @"\b[A-Z][A-Za-z0-9_]*(?:\.[A-Z][A-Za-z0-9_]*)+\b", " QNAME ");
+        text = Regex.Replace(text, @"\b[A-Z][A-Za-z0-9_]{2,}\b", " NAME ");
+        text = Regex.Replace(text, @"\d+(?:\.\d+)?", " NUM ");
+        text = text.ToLowerInvariant();
+        text = Regex.Replace(text, @"[^a-z ]", " ");
+        text = Regex.Replace(text, @"\s+", " ").Trim();
+        return text;
+    }
+
+    // Detects the specific mass-authoring cadence that survived the broader lexical fingerprint:
+    // "The X namespace helps you ..." followed by "Use it when ..." and "Start with Y ...".
+    // The content words may differ completely, but repeating this three-part rhetorical frame across
+    // even two unrelated namespaces reads as substituted boilerplate. Ordinary shared guidance such
+    // as a standalone "Use X when ..." sentence does not produce this signature.
+    private static string? NormalizeNamespaceRhetoricalSkeleton(string prose)
+    {
+        var text = Regex.Replace(prose, @"`[^`]*`", " CODE ");
+        text = Regex.Replace(text, @"\s+", " ").Trim();
+        var hasStartThen = Regex.IsMatch(text,
+            @"(?i)(?:^|[.!?]\s+)(?:start|begin)\s+with\s+CODE\b[^.!?]{0,220}\bthen\b");
+        if (hasStartThen)
+        {
+            return "start-code-then-navigation";
+        }
+
+        var hasNamespaceHelpsLead = Regex.IsMatch(text,
+            @"(?i)^(?:the\s+)?(?:CODE|[\w.]+)\s+namespace\s+helps\s+you\b");
+        var hasUseItWhen = Regex.IsMatch(text, @"(?i)(?:^|[.!?]\s+)use\s+it\s+when\b");
+        var hasConditionalStart = Regex.IsMatch(text,
+            @"(?i)(?:^|[.!?]\s+)(?:start|begin)\s+with\s+CODE\b|(?:^|[.!?]\s+)if\s+you\b[^.!?]{0,160}\b(?:start|begin)\s+with\s+CODE\b");
+        if (hasNamespaceHelpsLead && hasUseItWhen && hasConditionalStart)
+        {
+            return "namespace-helps-you|use-it-when|conditional-start-code";
+        }
+
+        var hasUseNamespaceWhenLead = Regex.IsMatch(text,
+            @"(?i)^use\s+the\s+CODE\s+namespace\s+when\b");
+        var hasNamespaceOutcomeSentence = Regex.IsMatch(text,
+            @"(?i)[.!?]\s+the\s+namespace\s+(?:helps|keeps|lets|enables|separates|centralizes)\b");
+        var hasChooseNamespaceWhen = Regex.IsMatch(text,
+            @"(?i)(?:^|[.!?]\s+)choose\s+this\s+namespace\s+when\b");
+        return hasUseNamespaceWhenLead && hasNamespaceOutcomeSentence && hasStartThen && hasChooseNamespaceWhen
+            ? "use-namespace-when|namespace-outcome|start-then|choose-namespace-when"
+            : null;
+    }
+
+    private static void ValidateNamespaceProseRepetition(
+        List<(string Namespace, string Path, string Fingerprint)> proseFingerprints, Report report)
+    {
+        foreach (var group in proseFingerprints
+                     .GroupBy(entry => entry.Fingerprint, StringComparer.Ordinal)
+                     .Where(group => group.Select(entry => entry.Namespace).Distinct(StringComparer.Ordinal).Count() >=
+                         (group.Key.StartsWith("rhetorical:", StringComparison.Ordinal) ? 2 : 3)))
+        {
+            var namespaces = group.Select(entry => entry.Namespace)
+                .Distinct(StringComparer.Ordinal)
+                .OrderBy(name => name, StringComparer.Ordinal)
+                .ToList();
+            foreach (var entry in group.GroupBy(e => e.Path, StringComparer.OrdinalIgnoreCase).Select(g => g.First()))
+            {
+                report.Errors.Add(new Diagnostic("NAMESPACE_PROSE_TEMPLATE_REPETITION", entry.Path, entry.Namespace,
+                    $"This namespace overview shares a normalized {(group.Key.StartsWith("rhetorical:", StringComparison.Ordinal) ? "rhetorical frame" : "prose skeleton")} with {namespaces.Count - 1} other namespace page(s) ({string.Join(", ", namespaces.Where(n => !string.Equals(n, entry.Namespace, StringComparison.Ordinal)))}). Write each opening from the namespace's own purpose instead of a substituted template."));
+            }
+        }
+    }
+
     private static bool HasNamespaceUsageGuidance(string prose)
     {
         return Regex.IsMatch(prose,
@@ -3463,7 +3753,7 @@ private static bool HasAvailability(string body)
     // ----------------------------------------------------------------------
 
     private static void ValidateRequiredExamples(string repoRoot, string docfxWorkspace, IReadOnlyList<OverwriteSection> sections, ApiModel api,
-        Options options, HashSet<string>? changedFiles, Report report)
+        Options options, HashSet<string>? changedFiles, ScopePlan scope, Dictionary<string, List<ProjectInfo>> namespaceOwners, Report report)
     {
         foreach (var duplicate in sections
                      .Where(section => section.MappedToExample)
@@ -3481,8 +3771,15 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
                 $"UID `{duplicate.Key}` is mapped to {duplicate.Count()} example sections. Keep one coherent, scenario-led example for a UID; merge or remove the duplicate `example: *content` sections."));
         }
 
+        var exampleFingerprints = new List<(string Uid, string Path, string Fingerprint)>();
+
         foreach (var target in api.RequiredExampleTargets)
         {
+            if (!scope.IncludesNamespace(target.Namespace))
+            {
+                continue;
+            }
+
             if (options.ChangedOnly && changedFiles is not null &&
                 !ShouldValidateRequiredExampleTarget(target, changedFiles))
             {
@@ -3501,9 +3798,19 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
             var qualityResults = candidates
                 .Select(section => ValidateExampleQuality(section, target, relatedExtensionMethods))
                 .ToList();
-            if (qualityResults.Any(result => result.Valid))
+            var validIndex = qualityResults.FindIndex(result => result.Valid);
+            if (validIndex >= 0)
             {
                 report.Summary.RequiredExamples++;
+                var validSection = candidates[validIndex];
+                var fingerprint = NormalizeExampleStructure(validSection.MappedToExample
+                    ? validSection.Body
+                    : ExtractExampleSection(validSection.Body));
+                if (fingerprint.Length >= 40)
+                {
+                    exampleFingerprints.Add((target.Uid, Rel(repoRoot, validSection.File), fingerprint));
+                }
+
                 continue;
             }
 
@@ -3532,12 +3839,113 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
 
             var message = target.Kind == ApiTargetKind.Type
                 ? $"Public non-abstraction type `{target.DisplayName}` requires a type-page DocFX overwrite example. Add an Examples section with a C# code fence to uid `{target.Uid}` in `{expectedPath}` or another overwrite file under `api/types/` that targets this exact type UID. Namespace overview examples do not satisfy this diagnostic. Keep `api/types/**/*.md` under `build.overwrite`, exclude `api/types/**` from `build.content`, and do not use `api/**/*.md` under either section."
-                : $"Public extension method `{target.DisplayName}` requires a DocFX overwrite example. Add an Examples section with a C# code fence to the declaring extension class uid `{expectedUid}` or the namespace page `{target.Namespace}` by default. The example must explicitly call `{target.DisplayName}`. Do not create URL-encoded or hash-like method UID filenames; use a method UID section only when the exact generated UID is verified and can live in a readable overwrite file.";
+                : $"Public extension method `{target.DisplayName}` (declaring type `{target.DeclaringTypeUid ?? "(unknown)"}`, owner {DescribeOwner(target.Namespace, namespaceOwners)}) requires a DocFX overwrite example. Add an Examples section with a C# code fence to the declaring extension class uid `{expectedUid}` or the namespace page `{target.Namespace}` by default. The example must explicitly call `{target.DisplayName}`{(namespaceOwners.TryGetValue(target.Namespace, out var owns) && owns.Count(o => !o.IsTest) > 1 ? " — prefer receiver extension syntax because the container name is shared across assemblies" : string.Empty)}. Candidate overwrite sections inspected: {DescribeExtensionCandidates(candidates, qualityResults, repoRoot)}. Do not create URL-encoded or hash-like method UID filenames; use a method UID section only when the exact generated UID is verified and can live in a readable overwrite file.";
 
             report.Errors.Add(new Diagnostic("EXAMPLE_MISSING", expectedPath, target.Namespace, message));
         }
+
+        // Cross-file template repetition: examples that normalize to the same structural skeleton
+        // across several unrelated targets are mechanical fills, not authored scenarios. A
+        // conservative threshold (three or more distinct UIDs) avoids rejecting a coherent family
+        // or conventional one-line setup that legitimately recurs.
+        foreach (var group in exampleFingerprints
+                     .GroupBy(entry => entry.Fingerprint, StringComparer.Ordinal)
+                     .Where(group => group.Select(entry => entry.Uid).Distinct(StringComparer.Ordinal).Count() >= 3))
+        {
+            var paths = group.Select(entry => entry.Path)
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase)
+                .ToList();
+            var uids = group.Select(entry => entry.Uid)
+                .Distinct(StringComparer.Ordinal)
+                .OrderBy(uid => uid, StringComparer.Ordinal)
+                .ToList();
+            report.Errors.Add(new Diagnostic("EXAMPLE_TEMPLATE_REPETITION", string.Join(", ", paths), NamespaceFromUid(uids[0]),
+                $"{uids.Count} unrelated examples ({string.Join(", ", uids)}) share one normalized code template and differ only by identifiers or literals. Author distinct scenarios that reflect each type's real behavior instead of reusing a single skeleton."));
+        }
+    }
+
+    private static string DescribeOwner(string ns, Dictionary<string, List<ProjectInfo>> namespaceOwners)
+    {
+        if (!namespaceOwners.TryGetValue(ns, out var owners) || owners.Count == 0)
+        {
+            return "(unresolved)";
+        }
+
+        return string.Join(", ", owners.Where(o => !o.IsTest).Select(o => o.AssemblyName)
+            .Distinct(StringComparer.OrdinalIgnoreCase).OrderBy(n => n, StringComparer.OrdinalIgnoreCase));
+    }
+
+    private static string DescribeExtensionCandidates(List<OverwriteSection> candidates, List<ExampleQualityResult> results, string repoRoot)
+    {
+        if (candidates.Count == 0)
+        {
+            return "none found (no overwrite section targets the declaring type UID or namespace page)";
+        }
+
+        var parts = new List<string>();
+        for (var i = 0; i < candidates.Count; i++)
+        {
+            var stage = results[i].Code switch
+            {
+                "EXAMPLE_MISSING" => "no C# fence",
+                "EXTENSION_EXAMPLE_NOT_INVOKED" => "fence present but method never invoked",
+                "EXAMPLE_REFLECTION_ONLY" => "reflection/metadata lookup instead of a call",
+                null => "valid",
+                _ => results[i].Code!
+            };
+            parts.Add($"`{Rel(repoRoot, candidates[i].File)}` ({stage})");
+        }
+
+        return string.Join("; ", parts);
+    }
+
+    // Normalizes example code to a structural skeleton: comments and string contents are removed,
+    // numeric literals and non-keyword identifiers are collapsed to placeholders, and whitespace is
+    // dropped. Two examples that differ only by type or identifier names produce identical skeletons.
+    private static string NormalizeExampleStructure(string body)
+    {
+        var code = string.Join("\n", ExtractCSharpCodeBlocks(body));
+        if (string.IsNullOrWhiteSpace(code))
+        {
+            return string.Empty;
+        }
+
+        code = StripCodeCommentsAndStrings(code);
+        var sb = new StringBuilder(code.Length);
+        foreach (Match token in Regex.Matches(code, @"[A-Za-z_]\w*|\d+(?:\.\d+)?|[^\sA-Za-z0-9_]"))
+        {
+            var value = token.Value;
+            if (Regex.IsMatch(value, @"^[A-Za-z_]\w*$"))
+            {
+                sb.Append(CSharpStructuralKeywords.Contains(value) ? value : "ID");
+            }
+            else if (Regex.IsMatch(value, @"^\d"))
+            {
+                sb.Append('0');
+            }
+            else
+            {
+                sb.Append(value);
+            }
+        }
+
+        return sb.ToString();
     }
 
+    private static readonly HashSet<string> CSharpStructuralKeywords = new(StringComparer.Ordinal)
+    {
+        "abstract", "as", "async", "await", "base", "bool", "break", "byte", "case", "catch", "char",
+        "checked", "class", "const", "continue", "decimal", "default", "delegate", "do", "double",
+        "else", "enum", "event", "explicit", "extern", "false", "finally", "fixed", "float", "for",
+        "foreach", "goto", "if", "implicit", "in", "int", "interface", "internal", "is", "lock", "long",
+        "namespace", "new", "null", "object", "operator", "out", "override", "params", "private",
+        "protected", "public", "readonly", "ref", "return", "sbyte", "sealed", "short", "sizeof",
+        "stackalloc", "static", "string", "struct", "switch", "this", "throw", "true", "try", "typeof",
+        "uint", "ulong", "unchecked", "unsafe", "ushort", "using", "var", "virtual", "void", "volatile",
+        "while", "yield", "record", "init", "nameof", "when", "with", "global",
+    };
+
     private static bool ShouldValidateNamespacePage(string page, HashSet<string> changedFiles)
     {
         return changedFiles.Contains(Path.GetFullPath(page)) || changedFiles.Any(IsChangedDocfxConfig);
@@ -3705,9 +4113,87 @@ private static ExampleQualityResult ValidateExampleQuality(
                 $"The C# example for `{target.DisplayName}` only names the type as metadata. Construct it, call it, configure it, or otherwise demonstrate a consumer-visible operation.", 40);
         }
 
+        // The target is referenced beyond metadata; now reject scaffolds that mention it without
+        // demonstrating a real consumer scenario. These are the dominant Cuemon filler patterns.
+        if (!invokesRelatedExtension)
+        {
+            if (IsDefaultTargetHolder(codeWithoutCommentsOrStrings, target.DisplayName))
+            {
+                return new ExampleQualityResult(false, "EXAMPLE_DEFAULT_PLACEHOLDER",
+                    $"The example for `{target.DisplayName}` only parks the type in a `default!`/`null!` holder property or field instead of constructing and using it. Replace the placeholder with a scenario that builds the type and produces an observable result or next action.", 8);
+            }
+
+            if (IsForwardingScaffold(codeWithoutCommentsOrStrings))
+            {
+                return new ExampleQualityResult(false, "EXAMPLE_FORWARDING_SCAFFOLD",
+                    $"The example for `{target.DisplayName}` is dominated by one-line pass-through members that only re-expose documented API without a scenario. Show a consumer task with an operation and a visible result instead of a mechanical forwarding wrapper.", 12);
+            }
+
+            if (!HasObservableOutcome(codeWithoutCommentsOrStrings))
+            {
+                return new ExampleQualityResult(false, "EXAMPLE_NO_OBSERVABLE_OUTCOME",
+                    $"The example for `{target.DisplayName}` only holds, returns, or constructs the type without an observable outcome. Configure it, invoke a member, pass it to an API, or otherwise produce a result a reader can see.", 14);
+            }
+        }
+
         return ExampleQualityResult.Success;
     }
 
+    // A target-typed property/field whose initializer is `default`, `default!`, or `null!` only
+    // names the type. Treat it as a placeholder unless the example also constructs the type, which
+    // would indicate a legitimate field that a later operation consumes.
+    private static bool IsDefaultTargetHolder(string code, string target)
+    {
+        var holder = Regex.IsMatch(code,
+            $@"(?<![\w.]){Regex.Escape(target)}(?:<[^>]*>)?\s+[A-Za-z_]\w*\s*(?:\{{[^{{}}]*\}}\s*)?=\s*(?:default\s*!?|null\s*!)\s*;");
+        if (!holder)
+        {
+            return false;
+        }
+
+        var constructsTarget = Regex.IsMatch(code, $@"\bnew\s+{Regex.Escape(target)}\b") ||
+                               Regex.IsMatch(code, $@"\bnew\s*\(\s*\)\s*;?\s*$");
+        return !constructsTarget;
+    }
+
+    // Mass forwarding shells re-expose documented members through several one-line, expression-bodied
+    // pass-throughs (`Name(args) => other.Member(args);`) and contain no other behavior. A single
+    // forwarder is the normal shape of an extension example, so this only fires when forwarders
+    // dominate and no statement body, local, initializer, or output demonstrates a scenario.
+    private static bool IsForwardingScaffold(string code)
+    {
+        var forwarders = Regex.Matches(code,
+            @"\b[A-Za-z_]\w*\s*\([^()]*\)\s*=>\s*[^;{}]*\b[A-Za-z_]\w*\s*(?:\.[A-Za-z_]\w*)*\s*(?:\([^;]*\))?\s*;")
+            .Count;
+        if (forwarders < 2)
+        {
+            return false;
+        }
+
+        var hasStatementBody = Regex.IsMatch(code, @"\)\s*\{[^{}]*;[^{}]*\}");
+        var hasLocal = Regex.IsMatch(code, @"(?<![\w.])(?:var|return)\s+") &&
+                       !Regex.IsMatch(code, @"=>\s*[^;{}]*\breturn\b");
+        var hasInitializer = Regex.IsMatch(code, @"\{\s*[@A-Za-z_]\w*\s*=");
+        var hasOutput = Regex.IsMatch(code, @"\b(?:Console|Debug|Trace)\s*\.");
+        if (forwarders >= 3)
+        {
+            return !hasStatementBody && !hasInitializer && !hasOutput;
+        }
+
+        return !hasStatementBody && !hasLocal && !hasInitializer && !hasOutput;
+    }
+
+    // An observable outcome is a member invocation, an object/collection initializer that configures
+    // state, an awaited operation, or visible output. Examples that merely construct, hold, or return
+    // the target without any of these do not teach what the API does.
+    private static bool HasObservableOutcome(string code)
+    {
+        return Regex.IsMatch(code, @"(?<![\w.])(?!new\b)[A-Za-z_]\w*\s*\.\s*[A-Za-z_]\w*\s*\(") ||
+               Regex.IsMatch(code, @"\{\s*[@A-Za-z_]\w*\s*=") ||
+               Regex.IsMatch(code, @"\bawait\b") ||
+               Regex.IsMatch(code, @"\b(?:Console|Debug|Trace)\s*\.");
+    }
+
     private static string StripCodeCommentsAndStrings(string code)
     {
         var lines = code.Replace("\r\n", "\n", StringComparison.Ordinal).Replace('\r', '\n').Split('\n');
@@ -4465,83 +4951,1357 @@ private static bool IsInsufficientSkipReason(string reason)
     }
 
     // ----------------------------------------------------------------------
-    // GitHub example search
+    // Project-scoped discovery: git state, packets, scope selection, families,
+    // symbol ownership, quality risk, manifest, and the safe overwrite writer.
     // ----------------------------------------------------------------------
 
-    private static void SearchGitHubForExamples(List<string> packageIds, Report report)
+    private static GitState GetGitState(string repoRoot)
     {
-        if (packageIds.Count == 0)
-        {
-            return;
-        }
+        var head = RunProcess("git", "rev-parse --verify HEAD", repoRoot, permission: ProcessPermission.Git);
+        var state = new GitState { Available = head.ExitCode == 0 };
 
-        report.ExampleSearchSnippets.Add("## GitHub Search Results");
-        report.ExampleSearchSnippets.Add(string.Empty);
-        report.ExampleSearchSnippets.Add("Results from `gh search code` for documented packages. Prefer usage from repositories other than the target repository.");
-        report.ExampleSearchSnippets.Add(string.Empty);
+        string Abs(string rel) => Path.GetFullPath(Path.Combine(repoRoot, rel.Trim()));
 
-        foreach (var packageId in packageIds)
+        void AddLines(string args, HashSet<string> target)
         {
-            report.ExampleSearchSnippets.Add($"### Package: `{packageId}`");
-            report.ExampleSearchSnippets.Add(string.Empty);
-
-            var result = RunProcess(
-                "gh",
-                $"search code \"{packageId}\" --language C# --limit 5 --json path,repository",
-                Directory.GetCurrentDirectory(),
-                permission: ProcessPermission.GitHubSearch);
-
-            if (result.ExitCode != 0 || string.IsNullOrWhiteSpace(result.StdOut))
+            var r = RunProcess("git", args, repoRoot, permission: ProcessPermission.Git);
+            if (r.ExitCode != 0)
             {
-                report.ExampleSearchSnippets.Add($"Search unavailable (gh exit {result.ExitCode}). Use the URL below.");
-                report.ExampleSearchSnippets.Add(string.Empty);
-                continue;
+                return;
             }
 
-            try
+            foreach (var line in r.StdOut.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
             {
-                using var doc = JsonDocument.Parse(result.StdOut);
-                if (doc.RootElement.ValueKind != JsonValueKind.Array || doc.RootElement.GetArrayLength() == 0)
-                {
-                    report.ExampleSearchSnippets.Add("No results found.");
-                    report.ExampleSearchSnippets.Add(string.Empty);
-                    continue;
-                }
+                target.Add(Abs(line));
+            }
+        }
 
-                foreach (var hit in doc.RootElement.EnumerateArray())
-                {
-                    var path = hit.TryGetProperty("path", out var pathEl) ? pathEl.GetString() ?? string.Empty : string.Empty;
-                    var repoName = string.Empty;
-                    if (hit.TryGetProperty("repository", out var repoEl) && repoEl.ValueKind == JsonValueKind.Object)
-                    {
-                        repoName = repoEl.TryGetProperty("fullName", out var fn) ? fn.GetString() ?? string.Empty : string.Empty;
-                        if (string.IsNullOrEmpty(repoName))
-                        {
-                            repoName = repoEl.TryGetProperty("nameWithOwner", out var nwo) ? nwo.GetString() ?? string.Empty : string.Empty;
-                        }
-                    }
+        if (state.Available)
+        {
+            AddLines("diff --name-only --cached --diff-filter=ACM", state.Staged);
+            AddLines("diff --name-only --diff-filter=ACM", state.Unstaged);
+            AddLines("diff --name-only --cached --diff-filter=D", state.Deleted);
+            AddLines("diff --name-only --diff-filter=D", state.Deleted);
 
-                    if (!string.IsNullOrEmpty(repoName) || !string.IsNullOrEmpty(path))
+            var renames = RunProcess("git", "diff --cached --name-status --diff-filter=R", repoRoot, permission: ProcessPermission.Git);
+            if (renames.ExitCode == 0)
+            {
+                foreach (var line in renames.StdOut.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+                {
+                    var parts = line.Split('\t', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+                    for (var k = 1; k < parts.Length; k++)
                     {
-                        report.ExampleSearchSnippets.Add($"- `{repoName}`: `{path}`");
+                        state.Renamed.Add(Abs(parts[k]));
                     }
                 }
-
-                report.ExampleSearchSnippets.Add(string.Empty);
             }
-            catch
+        }
+
+        // Untracked files are visible even when there is no HEAD yet.
+        var untracked = RunProcess("git", "ls-files --others --exclude-standard", repoRoot, permission: ProcessPermission.Git);
+        if (untracked.ExitCode == 0)
+        {
+            foreach (var line in untracked.StdOut.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
             {
-                report.ExampleSearchSnippets.Add("Unable to parse search results.");
-                report.ExampleSearchSnippets.Add(string.Empty);
+                state.Untracked.Add(Abs(line));
             }
         }
-    }
 
-    // ----------------------------------------------------------------------
-    // YAML / markdown helpers
-    // ----------------------------------------------------------------------
+        return state;
+    }
 
-    private static (string FrontMatter, string Body) SplitFrontMatter(string text)
+    private static List<ProjectPacket> BuildProjectPackets(ValidationWorkspace ws, ApiModel api, GitState gitState,
+        List<MetadataGroupInfo> groups, string repoRoot, string docfxWorkspace,
+        HashSet<string>? protectedDirtyPaths = null)
+    {
+        EnsureNamespaceProjectMap(ws);
+
+        var projectNamespaces = new Dictionary<string, List<string>>(StringComparer.OrdinalIgnoreCase);
+        var sharedNamespaces = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var (ns, owners) in ws.NamespaceProjects)
+        {
+            var libOwners = owners.Where(o => !o.IsTest).ToList();
+            if (libOwners.Count > 1)
+            {
+                sharedNamespaces.Add(ns);
+            }
+
+            foreach (var owner in libOwners)
+            {
+                var key = Path.GetFullPath(owner.Path);
+                if (!projectNamespaces.TryGetValue(key, out var list))
+                {
+                    list = new List<string>();
+                    projectNamespaces[key] = list;
+                }
+
+                if (!list.Contains(ns, StringComparer.Ordinal))
+                {
+                    list.Add(ns);
+                }
+            }
+        }
+
+        var targetsByNs = api.RequiredExampleTargets
+            .GroupBy(t => t.Namespace, StringComparer.Ordinal)
+            .ToDictionary(g => g.Key, g => g.ToList(), StringComparer.Ordinal);
+
+        // A resumed authoring session protects only paths that were dirty when its manifest was
+        // created. Files authored after that baseline must remain selectable for scoped
+        // verification; otherwise the validator would mistake its own dry-run output for
+        // pre-existing user work and make completion impossible.
+        var dirty = protectedDirtyPaths is null
+            ? new HashSet<string>(gitState.AllDirty, StringComparer.OrdinalIgnoreCase)
+            : new HashSet<string>(protectedDirtyPaths, StringComparer.OrdinalIgnoreCase);
+
+        var packets = new List<ProjectPacket>();
+        foreach (var project in ws.LibraryProjects.OrderBy(p => NormalizeDocfxPath(p.Path), StringComparer.OrdinalIgnoreCase))
+        {
+            var key = Path.GetFullPath(project.Path);
+            var packet = new ProjectPacket { Project = project, NormalizedPath = key };
+
+            foreach (var group in groups)
+            {
+                if (group.ProjectPaths.Any(p => PathsEqual(p, key)))
+                {
+                    packet.MetadataGroupIds.Add(group.Id);
+                }
+            }
+
+            var ownedUids = new HashSet<string>(StringComparer.Ordinal);
+            if (projectNamespaces.TryGetValue(key, out var nss))
+            {
+                foreach (var ns in nss.OrderBy(n => n, StringComparer.Ordinal))
+                {
+                    packet.Namespaces.Add(ns);
+                    ownedUids.Add(ns);
+                    if (sharedNamespaces.Contains(ns))
+                    {
+                        packet.SharedNamespaces.Add(ns);
+                    }
+
+                    if (targetsByNs.TryGetValue(ns, out var ts))
+                    {
+                        foreach (var t in ts)
+                        {
+                            packet.Targets.Add(t);
+                            ownedUids.Add(t.Uid);
+                            if (t.DeclaringTypeUid is not null)
+                            {
+                                ownedUids.Add(t.DeclaringTypeUid);
+                            }
+                        }
+                    }
+                }
+            }
+
+            foreach (var section in ws.OverwriteSections)
+            {
+                if (ownedUids.Contains(section.Uid) || packet.Namespaces.Contains(NamespaceFromUid(section.Uid), StringComparer.Ordinal))
+                {
+                    var rel = Rel(repoRoot, section.File);
+                    if (!packet.OverwritePaths.Contains(rel, StringComparer.OrdinalIgnoreCase))
+                    {
+                        packet.OverwritePaths.Add(rel);
+                    }
+                }
+            }
+
+            packet.OverwritePaths.Sort(StringComparer.OrdinalIgnoreCase);
+
+            var related = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var file in EnumerateProjectSourceFiles(project))
+            {
+                related.Add(Path.GetFullPath(file));
+            }
+
+            foreach (var ns in packet.Namespaces)
+            {
+                related.Add(Path.GetFullPath(Path.Combine(docfxWorkspace, "api", "namespaces", ns + ".md")));
+            }
+
+            foreach (var target in packet.Targets.Where(t => t.Kind == ApiTargetKind.Type))
+            {
+                related.Add(Path.GetFullPath(Path.Combine(docfxWorkspace, "api", "types", target.Uid + ".md")));
+            }
+
+            foreach (var rel in packet.OverwritePaths)
+            {
+                related.Add(Path.GetFullPath(Path.Combine(repoRoot, rel)));
+            }
+
+            foreach (var path in related)
+            {
+                if (dirty.Contains(path))
+                {
+                    packet.DirtyRelatedPaths.Add(Rel(repoRoot, path));
+                }
+            }
+
+            packet.DirtyRelatedPaths.Sort(StringComparer.OrdinalIgnoreCase);
+            packets.Add(packet);
+        }
+
+        return packets;
+    }
+
+    private static bool HintMatches(ProjectPacket packet, string hint)
+    {
+        var h = hint.Trim();
+        if (string.IsNullOrEmpty(h))
+        {
+            return false;
+        }
+
+        if (string.Equals(packet.Project.AssemblyName, h, StringComparison.OrdinalIgnoreCase) ||
+            string.Equals(packet.Project.PackageId, h, StringComparison.OrdinalIgnoreCase) ||
+            string.Equals(Path.GetFileNameWithoutExtension(packet.NormalizedPath), h, StringComparison.OrdinalIgnoreCase))
+        {
+            return true;
+        }
+
+        var nh = NormalizeDocfxPath(h);
+        var np = NormalizeDocfxPath(packet.NormalizedPath);
+        return string.Equals(np, nh, StringComparison.OrdinalIgnoreCase) ||
+               np.EndsWith("/" + nh, StringComparison.OrdinalIgnoreCase) ||
+               np.EndsWith(nh, StringComparison.OrdinalIgnoreCase) && nh.Contains('/');
+    }
+
+    private static List<ProjectPacket> SeededShuffle(List<ProjectPacket> source, Random rng)
+    {
+        var list = new List<ProjectPacket>(source);
+        for (var i = list.Count - 1; i > 0; i--)
+        {
+            var j = rng.Next(i + 1);
+            (list[i], list[j]) = (list[j], list[i]);
+        }
+
+        return list;
+    }
+
+    private static long GenerateSeed() => Random.Shared.NextInt64(1, long.MaxValue);
+
+    private static ResumeProjectScope? LoadResumeProjectManifest(string path, string repoRoot, Report report)
+    {
+        string full;
+        try
+        {
+            full = Path.GetFullPath(path, repoRoot);
+        }
+        catch (Exception ex)
+        {
+            report.Errors.Add(new Diagnostic("PROJECT_MANIFEST_INVALID", path, null,
+                $"Unable to resolve the project manifest path: {ex.Message}"));
+            return null;
+        }
+
+        if (!File.Exists(full))
+        {
+            report.Errors.Add(new Diagnostic("PROJECT_MANIFEST_INVALID", Rel(repoRoot, full), null,
+                "The project manifest does not exist."));
+            return null;
+        }
+
+        try
+        {
+            using var doc = JsonDocument.Parse(File.ReadAllText(full), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+            var root = doc.RootElement;
+            if (!root.TryGetProperty("schemaVersion", out var schema) || schema.GetInt32() is not (1 or 2) ||
+                !root.TryGetProperty("packets", out var packets) || packets.ValueKind != JsonValueKind.Array)
+            {
+                report.Errors.Add(new Diagnostic("PROJECT_MANIFEST_INVALID", Rel(repoRoot, full), null,
+                    "The project manifest must use schemaVersion 1 or 2 and contain a packets array."));
+                return null;
+            }
+
+            var result = new ResumeProjectScope();
+            if (root.TryGetProperty("runMode", out var mode) && mode.ValueKind == JsonValueKind.String)
+            {
+                result.Mode = mode.GetString() is "dry-run" ? "dry-run" : "scoped";
+            }
+
+            if (root.TryGetProperty("seed", out var seed) && seed.ValueKind == JsonValueKind.Number && seed.TryGetInt64(out var seedValue))
+            {
+                result.Seed = seedValue;
+            }
+
+            foreach (var packet in packets.EnumerateArray())
+            {
+                if (!packet.TryGetProperty("selected", out var selected) || selected.ValueKind != JsonValueKind.True ||
+                    !packet.TryGetProperty("project", out var project) || project.ValueKind != JsonValueKind.String)
+                {
+                    continue;
+                }
+
+                var projectPath = project.GetString();
+                if (!string.IsNullOrWhiteSpace(projectPath))
+                {
+                    var selectedPath = Path.GetFullPath(projectPath, repoRoot);
+                    if (!IsInsideDirectory(selectedPath, repoRoot))
+                    {
+                        report.Errors.Add(new Diagnostic("PROJECT_MANIFEST_INVALID", Rel(repoRoot, full), null,
+                            $"Selected project path '{projectPath}' resolves outside the repository root."));
+                        return null;
+                    }
+
+                    result.SelectedProjectPaths.Add(selectedPath);
+                }
+            }
+
+            if (root.TryGetProperty("dirty", out var dirty) && dirty.ValueKind == JsonValueKind.Object)
+            {
+                foreach (var propertyName in new[] { "staged", "unstaged", "renamed", "deleted", "untracked" })
+                {
+                    if (!dirty.TryGetProperty(propertyName, out var paths) || paths.ValueKind != JsonValueKind.Array)
+                    {
+                        continue;
+                    }
+
+                    foreach (var item in paths.EnumerateArray())
+                    {
+                        if (item.ValueKind == JsonValueKind.String && !string.IsNullOrWhiteSpace(item.GetString()))
+                        {
+                            var dirtyPath = Path.GetFullPath(item.GetString()!, repoRoot);
+                            if (!IsInsideDirectory(dirtyPath, repoRoot))
+                            {
+                                report.Errors.Add(new Diagnostic("PROJECT_MANIFEST_INVALID", Rel(repoRoot, full), null,
+                                    $"Dirty baseline path '{item.GetString()}' resolves outside the repository root."));
+                                return null;
+                            }
+
+                            result.InitialDirtyPaths.Add(dirtyPath);
+                        }
+                    }
+                }
+            }
+
+            if (result.SelectedProjectPaths.Count == 0)
+            {
+                report.Errors.Add(new Diagnostic("PROJECT_MANIFEST_INVALID", Rel(repoRoot, full), null,
+                    "The project manifest contains no selected project packets to resume."));
+                return null;
+            }
+
+            report.ResumedProjectManifestPath = Rel(repoRoot, full);
+            return result;
+        }
+        catch (Exception ex) when (ex is IOException or JsonException or InvalidOperationException or ArgumentException or NotSupportedException)
+        {
+            report.Errors.Add(new Diagnostic("PROJECT_MANIFEST_INVALID", Rel(repoRoot, full), null,
+                $"Unable to read the project manifest: {ex.Message}"));
+            return null;
+        }
+    }
+
+    private static ScopePlan ResolveScope(Options options, List<ProjectPacket> packets, List<MetadataGroupInfo> groups,
+        ApiModelSource apiSource, string repoRoot, Report report, ResumeProjectScope? resumeScope)
+    {
+        var plan = new ScopePlan();
+        var authoringIntent = options.DryRun || options.ProjectHints.Count > 0 || options.ProjectManifestPath is not null ||
+                              options.ResumeProjectManifestPath is not null;
+        var authoritative = apiSource != ApiModelSource.SourceScan;
+        plan.ScopeState = authoritative ? "authoritative" : "provisional";
+
+        if (authoringIntent && !authoritative)
+        {
+            report.Warnings.Add(new Diagnostic("BUILD_BACKED_SCOPE_REQUIRED", null, null,
+                "Authoring scope was requested but the API model came from the conservative source scanner. Run --build-api-model (or generate DocFX managed-reference YAML) before authoring; the current packet inventory is provisional and may under-report public types."));
+        }
+
+        if (options.ResumeProjectManifestPath is not null && resumeScope is null)
+        {
+            // Loading a requested baseline failed. Keep the scope empty so an invalid or stale
+            // manifest can never silently broaden into a repository-wide authoring run.
+            plan.Mode = "scoped";
+            plan.ScopeRestricted = true;
+        }
+        else if (resumeScope is not null)
+        {
+            plan.Mode = resumeScope.Mode;
+            plan.Seed = resumeScope.Seed;
+            plan.ScopeRestricted = true;
+            foreach (var projectPath in resumeScope.SelectedProjectPaths)
+            {
+                var packet = packets.FirstOrDefault(p => PathsEqual(p.NormalizedPath, projectPath));
+                if (packet is null)
+                {
+                    report.Errors.Add(new Diagnostic("PROJECT_MANIFEST_PROJECT_MISSING", Rel(repoRoot, projectPath), null,
+                        "The resumed project manifest selects a project that is no longer present in the active DocFX metadata graph. Regenerate the manifest before continuing."));
+                    continue;
+                }
+
+                if (packet.Dirty)
+                {
+                    report.Errors.Add(new Diagnostic("PROJECT_MANIFEST_DIRTY_CONFLICT", Rel(repoRoot, packet.NormalizedPath), null,
+                        $"The resumed project was already dirty when the manifest baseline was created and remains protected: {string.Join(", ", packet.DirtyRelatedPaths)}."));
+                    continue;
+                }
+
+                packet.Selected = true;
+                plan.SelectedProjectPaths.Add(packet.NormalizedPath);
+            }
+        }
+        else if (options.ProjectHints.Count > 0)
+        {
+            plan.Mode = options.DryRun ? "dry-run" : "scoped";
+            plan.ScopeRestricted = true;
+            foreach (var hint in options.ProjectHints)
+            {
+                var matches = packets.Where(p => HintMatches(p, hint)).ToList();
+                if (matches.Count == 0)
+                {
+                    report.Errors.Add(new Diagnostic("PROJECT_HINT_NOT_FOUND", null, null,
+                        $"Project hint '{hint}' did not match any documented project. Candidates: {string.Join(", ", packets.Select(p => p.Project.AssemblyName).Distinct(StringComparer.OrdinalIgnoreCase).OrderBy(n => n, StringComparer.OrdinalIgnoreCase))}."));
+                    continue;
+                }
+
+                if (matches.Count > 1)
+                {
+                    report.Errors.Add(new Diagnostic("PROJECT_HINT_AMBIGUOUS", null, null,
+                        $"Project hint '{hint}' matched {matches.Count} projects: {string.Join(", ", matches.Select(m => Rel(repoRoot, m.NormalizedPath)))}. Use a more specific path, assembly name, or package id."));
+                    continue;
+                }
+
+                var packet = matches[0];
+                if (packet.Dirty)
+                {
+                    report.Warnings.Add(new Diagnostic("PROJECT_DIRTY_SKIPPED", Rel(repoRoot, packet.NormalizedPath), null,
+                        $"Explicitly selected project '{packet.Project.AssemblyName}' has pre-existing changes to related files and was not selected for editing: {string.Join(", ", packet.DirtyRelatedPaths)}. Resolve or deliberately continue in a later run."));
+                    continue;
+                }
+
+                packet.Selected = true;
+                plan.SelectedProjectPaths.Add(packet.NormalizedPath);
+            }
+        }
+        else if (options.DryRun)
+        {
+            plan.Mode = "dry-run";
+            plan.ScopeRestricted = true;
+            var seed = options.Seed ?? GenerateSeed();
+            plan.Seed = seed;
+            var rng = new Random(unchecked((int)(seed ^ (seed >> 32))));
+            foreach (var group in groups.OrderBy(g => g.Id, StringComparer.Ordinal))
+            {
+                var candidates = packets
+                    .Where(p => p.MetadataGroupIds.Contains(group.Id, StringComparer.Ordinal))
+                    .OrderBy(p => NormalizeDocfxPath(p.NormalizedPath), StringComparer.OrdinalIgnoreCase)
+                    .ToList();
+                if (candidates.Count == 0)
+                {
+                    continue;
+                }
+
+                var clean = SeededShuffle(candidates, rng).FirstOrDefault(p => !p.Dirty);
+                if (clean is null)
+                {
+                    report.Warnings.Add(new Diagnostic("DRY_RUN_GROUP_UNSELECTED", null, group.Id,
+                        $"Metadata destination group '{group.Id}' has no clean project to sample; every candidate has pre-existing related changes. No documentation was selected for this group."));
+                    continue;
+                }
+
+                clean.Selected = true;
+                plan.SelectedProjectPaths.Add(clean.NormalizedPath);
+            }
+        }
+        else
+        {
+            plan.Mode = "full";
+            foreach (var packet in packets)
+            {
+                packet.Selected = true;
+                plan.SelectedProjectPaths.Add(packet.NormalizedPath);
+            }
+        }
+
+        foreach (var packet in packets.Where(p => p.Selected))
+        {
+            foreach (var ns in packet.Namespaces)
+            {
+                plan.SelectedNamespaces.Add(ns);
+            }
+        }
+
+        return plan;
+    }
+
+    // Family exemptions: an explicit, reviewable manifest under .docfx/family-exemptions.json.
+    private static List<FamilyExemption> LoadAndValidateFamilyExemptions(string repoRoot, string docfxWorkspace,
+        ApiModel api, ValidationWorkspace ws, Dictionary<string, string> namespacePages, Report report)
+    {
+        var path = Path.Combine(docfxWorkspace, "family-exemptions.json");
+        var result = new List<FamilyExemption>();
+        if (!File.Exists(path))
+        {
+            return result;
+        }
+
+        JsonDocument doc;
+        try
+        {
+            doc = JsonDocument.Parse(File.ReadAllText(path), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+        }
+        catch (Exception ex) when (ex is IOException or JsonException)
+        {
+            report.Errors.Add(new Diagnostic("FAMILY_EXEMPTION_INVALID", Rel(repoRoot, path), null,
+                $"Unable to parse the family exemption manifest: {ex.Message}"));
+            return result;
+        }
+
+        var knownTypeUids = new HashSet<string>(
+            api.RequiredExampleTargets.Where(t => t.Kind == ApiTargetKind.Type).Select(t => t.Uid),
+            StringComparer.Ordinal);
+        var validRationales = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+        {
+            "generic-arity", "inherited-specialization", "overload-series", "type-parameter-series"
+        };
+        var coverageSeen = new Dictionary<string, string>(StringComparer.Ordinal);
+        var anchorsSeen = new HashSet<string>(StringComparer.Ordinal);
+
+        using (doc)
+        {
+            if (!doc.RootElement.TryGetProperty("families", out var families) || families.ValueKind != JsonValueKind.Array)
+            {
+                report.Errors.Add(new Diagnostic("FAMILY_EXEMPTION_INVALID", Rel(repoRoot, path), null,
+                    "The family exemption manifest must contain a 'families' array."));
+                return result;
+            }
+
+            foreach (var fam in families.EnumerateArray())
+            {
+                var familyId = ReadJsonString(fam, "familyId");
+                var namespaceUid = ReadJsonString(fam, "namespaceUid");
+                var anchorUid = ReadJsonString(fam, "anchorUid");
+                var rationale = ReadJsonString(fam, "rationale");
+                var anchorExampleFile = ReadJsonString(fam, "anchorExampleFile");
+                var covered = new List<string>();
+                if (fam.TryGetProperty("coveredUids", out var cu) && cu.ValueKind == JsonValueKind.Array)
+                {
+                    covered.AddRange(cu.EnumerateArray().Where(e => e.ValueKind == JsonValueKind.String).Select(e => e.GetString()!));
+                }
+
+                var exemption = new FamilyExemption(familyId ?? string.Empty, namespaceUid ?? string.Empty,
+                    anchorUid ?? string.Empty, covered, rationale ?? string.Empty, anchorExampleFile);
+
+                if (string.IsNullOrWhiteSpace(familyId) || string.IsNullOrWhiteSpace(namespaceUid) ||
+                    string.IsNullOrWhiteSpace(anchorUid) || covered.Count == 0)
+                {
+                    report.Errors.Add(new Diagnostic("FAMILY_EXEMPTION_INVALID", Rel(repoRoot, path), namespaceUid,
+                        $"Family '{familyId}' must declare familyId, namespaceUid, anchorUid, and at least one coveredUid."));
+                    result.Add(exemption);
+                    continue;
+                }
+
+                if (!validRationales.Contains(rationale ?? string.Empty))
+                {
+                    report.Errors.Add(new Diagnostic("FAMILY_EXEMPTION_INVALID", Rel(repoRoot, path), namespaceUid,
+                        $"Family '{familyId}' has rationale '{rationale}'. Use one of: generic-arity, inherited-specialization, overload-series, type-parameter-series. Category alone never exempts unrelated difficult types."));
+                    result.Add(exemption);
+                    continue;
+                }
+
+                var allUids = new List<string> { anchorUid! };
+                allUids.AddRange(covered);
+                var unknown = allUids.Where(u => !knownTypeUids.Contains(u)).ToList();
+                if (unknown.Count > 0)
+                {
+                    report.Errors.Add(new Diagnostic("FAMILY_EXEMPTION_INVALID", Rel(repoRoot, path), namespaceUid,
+                        $"Family '{familyId}' references UIDs that are not public documentation type targets: {string.Join(", ", unknown)}."));
+                    result.Add(exemption);
+                    continue;
+                }
+
+                var outsideNamespace = allUids.Where(u => !string.Equals(NamespaceFromUid(u), namespaceUid, StringComparison.Ordinal)).ToList();
+                if (outsideNamespace.Count > 0)
+                {
+                    report.Errors.Add(new Diagnostic("FAMILY_EXEMPTION_INVALID", Rel(repoRoot, path), namespaceUid,
+                        $"Family '{familyId}' groups UIDs outside the declared namespace '{namespaceUid}': {string.Join(", ", outsideNamespace)}. A family must share one coherent namespace."));
+                    result.Add(exemption);
+                    continue;
+                }
+
+                if (anchorsSeen.Contains(anchorUid!) || covered.Contains(anchorUid!))
+                {
+                    report.Errors.Add(new Diagnostic("FAMILY_EXEMPTION_INVALID", Rel(repoRoot, path), namespaceUid,
+                        $"Family '{familyId}' has an overlapping or circular anchor '{anchorUid}'."));
+                    result.Add(exemption);
+                    continue;
+                }
+
+                var duplicateCoverage = allUids.Where(u => coverageSeen.ContainsKey(u)).ToList();
+                if (duplicateCoverage.Count > 0)
+                {
+                    report.Errors.Add(new Diagnostic("FAMILY_EXEMPTION_INVALID", Rel(repoRoot, path), namespaceUid,
+                        $"Family '{familyId}' duplicates coverage already claimed by another family: {string.Join(", ", duplicateCoverage.Select(u => $"{u} (in {coverageSeen[u]})"))}."));
+                    result.Add(exemption);
+                    continue;
+                }
+
+                // Structurally valid declaration. Now require an anchor example and namespace guidance.
+                var anchorHasExample = AnchorHasValidExample(anchorUid!, ws, api);
+                if (!anchorHasExample)
+                {
+                    report.Errors.Add(new Diagnostic("FAMILY_ANCHOR_EXAMPLE_MISSING", Rel(repoRoot, path), namespaceUid,
+                        $"Family '{familyId}' anchor '{anchorUid}' has no valid, behavioral example. The anchor must demonstrate the shared workflow before siblings can be exempted from standalone examples."));
+                }
+
+                if (!NamespaceExplainsFamily(namespaceUid!, anchorUid!, namespacePages, ws))
+                {
+                    report.Errors.Add(new Diagnostic("FAMILY_NAMESPACE_GUIDANCE_MISSING", Rel(repoRoot, path), namespaceUid,
+                        $"Family '{familyId}' requires the namespace page '{namespaceUid}' to name the anchor '{SimpleNameFromUid(anchorUid!)}' and explain how consumers choose among the siblings."));
+                }
+
+                exemption.Valid = anchorHasExample && NamespaceExplainsFamily(namespaceUid!, anchorUid!, namespacePages, ws);
+                anchorsSeen.Add(anchorUid!);
+                foreach (var u in allUids)
+                {
+                    coverageSeen[u] = familyId!;
+                }
+
+                result.Add(exemption);
+            }
+        }
+
+        return result;
+    }
+
+    private static bool AnchorHasValidExample(string anchorUid, ValidationWorkspace ws, ApiModel api)
+    {
+        var target = api.RequiredExampleTargets.FirstOrDefault(t => string.Equals(t.Uid, anchorUid, StringComparison.Ordinal));
+        if (target is null)
+        {
+            return false;
+        }
+
+        var candidates = ws.OverwriteSections.Where(s => IsExampleCandidate(s, target)).ToList();
+        return candidates.Any(section => ValidateExampleQuality(section, target, new List<string>()).Valid);
+    }
+
+    private static bool NamespaceExplainsFamily(string namespaceUid, string anchorUid,
+        Dictionary<string, string> namespacePages, ValidationWorkspace ws)
+    {
+        if (!namespacePages.TryGetValue(namespaceUid, out var page))
+        {
+            return false;
+        }
+
+        var text = ws.ReadMarkdown(page);
+        var (_, body) = SplitFrontMatter(text);
+        var anchorName = SimpleNameFromUid(anchorUid);
+        var namesAnchor = body.Contains(anchorName, StringComparison.Ordinal);
+        var explainsSelection = Regex.IsMatch(body,
+            @"(?i)\b(?:choose|select|pick|which|differ|arity|overload|type parameter|specialization|when you need|use\s+\w+\s+when)\b");
+        return namesAnchor && explainsSelection;
+    }
+
+    private static void ApplyFamilyExemptions(ApiModel api, List<FamilyExemption> families)
+    {
+        var covered = new HashSet<string>(
+            families.Where(f => f.Valid).SelectMany(f => f.CoveredUids),
+            StringComparer.Ordinal);
+        if (covered.Count == 0)
+        {
+            return;
+        }
+
+        api.RequiredExampleTargets.RemoveAll(t => t.Kind == ApiTargetKind.Type && covered.Contains(t.Uid));
+        foreach (var ns in api.Namespaces)
+        {
+            ns.RequiredExampleTargets.RemoveAll(t => t.Kind == ApiTargetKind.Type && covered.Contains(t.Uid));
+        }
+    }
+
+    private static string? ReadJsonString(JsonElement element, string name)
+        => element.TryGetProperty(name, out var v) && v.ValueKind == JsonValueKind.String ? v.GetString() : null;
+
+    // Symbol ownership: duplicate simple type names across owning projects, type forwarding that
+    // cannot be attributed, and extension containers that cross project boundaries.
+    private static void ValidateSymbolOwnership(ApiModel api, ValidationWorkspace ws, List<ProjectPacket> packets,
+        Report report, out int collisions, out int forwarded, out int extensionAmbiguous)
+    {
+        collisions = 0;
+        forwarded = 0;
+        extensionAmbiguous = 0;
+
+        var ownerByNamespace = ws.NamespaceProjects;
+        string OwnersOf(string ns) => ownerByNamespace.TryGetValue(ns, out var list)
+            ? string.Join(", ", list.Where(o => !o.IsTest).Select(o => o.AssemblyName).Distinct(StringComparer.OrdinalIgnoreCase).OrderBy(n => n, StringComparer.OrdinalIgnoreCase))
+            : "(unknown)";
+
+        // Duplicate simple type names whose owning projects differ.
+        foreach (var group in api.RequiredExampleTargets
+                     .Where(t => t.Kind == ApiTargetKind.Type)
+                     .GroupBy(t => SimpleNameFromUid(t.Uid), StringComparer.Ordinal))
+        {
+            var distinctUids = group.Select(t => t.Uid).Distinct(StringComparer.Ordinal).ToList();
+            if (distinctUids.Count < 2)
+            {
+                continue;
+            }
+
+            var owners = group
+                .SelectMany(t => ownerByNamespace.TryGetValue(t.Namespace, out var l) ? l.Where(o => !o.IsTest) : Enumerable.Empty<ProjectInfo>())
+                .Select(o => Path.GetFullPath(o.Path))
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .ToList();
+            if (owners.Count >= 2)
+            {
+                collisions++;
+                report.Warnings.Add(new Diagnostic("SYMBOL_COLLISION_UNRESOLVED", null, group.First().Namespace,
+                    $"Simple type name '{group.Key}' is documented in multiple assemblies/namespaces ({string.Join("; ", distinctUids.Select(u => $"{u} [{OwnersOf(NamespaceFromUid(u))}]"))}). Qualify examples and overwrite UIDs by owning assembly/project so coverage is not ambiguous."));
+            }
+        }
+
+        // Type forwarding declared in source that cannot be attributed to a documented owner.
+        foreach (var project in ws.LibraryProjects)
+        {
+            foreach (var file in EnumerateProjectSourceFiles(project))
+            {
+                string text;
+                try
+                {
+                    text = File.ReadAllText(file);
+                }
+                catch
+                {
+                    continue;
+                }
+
+                foreach (Match m in Regex.Matches(text, @"\[\s*assembly\s*:\s*TypeForwardedTo\s*\(\s*typeof\s*\(\s*(?<type>[\w.<>, ]+?)\s*\)\s*\)\s*\]"))
+                {
+                    var forwardedType = m.Groups["type"].Value.Trim();
+                    var simple = forwardedType.Contains('.') ? forwardedType[(forwardedType.LastIndexOf('.') + 1)..] : forwardedType;
+                    simple = simple.Split('<')[0];
+                    var documented = api.RequiredExampleTargets.Any(t => string.Equals(SimpleNameFromUid(t.Uid), simple, StringComparison.Ordinal));
+                    if (!documented)
+                    {
+                        forwarded++;
+                        report.Warnings.Add(new Diagnostic("TYPE_FORWARDING_UNRESOLVED", Rel(ws.RepoRoot, file), null,
+                            $"Type '{forwardedType}' is forwarded from '{project.AssemblyName}' but cannot be matched to a documented type target. Resolve which project and UID documents the forwarded family before authoring."));
+                    }
+                }
+            }
+        }
+
+        // Extension containers whose simple name appears in more than one namespace/project.
+        foreach (var group in api.Namespaces
+                     .SelectMany(ns => ns.ExtensionMethods.Select(e => (ns.Name, e.DeclaringClass)))
+                     .GroupBy(x => x.DeclaringClass, StringComparer.Ordinal))
+        {
+            var namespaces = group.Select(x => x.Name).Distinct(StringComparer.Ordinal).ToList();
+            if (namespaces.Count < 2)
+            {
+                continue;
+            }
+
+            var owners = namespaces
+                .SelectMany(ns => ownerByNamespace.TryGetValue(ns, out var l) ? l.Where(o => !o.IsTest) : Enumerable.Empty<ProjectInfo>())
+                .Select(o => Path.GetFullPath(o.Path))
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .ToList();
+            if (owners.Count >= 2)
+            {
+                extensionAmbiguous++;
+                report.Warnings.Add(new Diagnostic("EXTENSION_OWNER_AMBIGUOUS", null, namespaces[0],
+                    $"Extension container '{group.Key}' is declared in multiple namespaces/assemblies ({string.Join(", ", namespaces.Select(ns => $"{ns} [{OwnersOf(ns)}]"))}). Prefer receiver extension syntax and a uniquely owned overwrite UID so the example targets the right declaring type."));
+            }
+        }
+    }
+
+    private static QualityRiskReport EvaluateQualityRisk(Options options, ApiModel api, List<ProjectPacket> packets,
+        int existingValidExamples, int collisions, int forwarded, int extensionAmbiguous, ScopePlan scope, Report report)
+    {
+        var standaloneThreshold = options.RiskStandaloneThreshold ?? 100;
+        var extensionThreshold = options.RiskExtensionThreshold ?? 100;
+        var ratioThreshold = options.RiskMissingRatioThreshold ?? 10.0;
+
+        var standalone = api.RequiredExampleTargets.Count(t => t.Kind == ApiTargetKind.Type);
+        var extension = api.RequiredExampleTargets.Count(t => t.Kind == ApiTargetKind.ExtensionMethod);
+        var missing = Math.Max(0, standalone + extension - existingValidExamples);
+        var ratio = missing / (double)Math.Max(1, existingValidExamples);
+        var shared = packets.SelectMany(p => p.SharedNamespaces).Distinct(StringComparer.Ordinal).Count();
+
+        var risk = new QualityRiskReport
+        {
+            StandaloneTargets = standalone,
+            ExtensionTargets = extension,
+            ExistingValidExamples = existingValidExamples,
+            MissingToExistingRatio = Math.Round(ratio, 2),
+            SymbolCollisions = collisions,
+            TypeForwardedTargets = forwarded,
+            SharedNamespaces = shared,
+            UnresolvedExtensionOwners = extensionAmbiguous,
+            StandaloneThreshold = standaloneThreshold,
+            ExtensionThreshold = extensionThreshold,
+            RatioThreshold = ratioThreshold,
+            PilotTargetCap = 20
+        };
+
+        if (standalone > standaloneThreshold)
+        {
+            risk.TriggeredThresholds.Add($"standalone-targets {standalone} > {standaloneThreshold}");
+        }
+
+        if (extension > extensionThreshold)
+        {
+            risk.TriggeredThresholds.Add($"extension-targets {extension} > {extensionThreshold}");
+        }
+
+        if (ratio > ratioThreshold)
+        {
+            risk.TriggeredThresholds.Add($"missing-to-existing {risk.MissingToExistingRatio} > {ratioThreshold}");
+        }
+
+        if (collisions > 0 || extensionAmbiguous > 0)
+        {
+            risk.TriggeredThresholds.Add($"unresolved symbol ownership ({collisions} collisions, {extensionAmbiguous} extension owners)");
+        }
+
+        risk.HighRisk = risk.TriggeredThresholds.Count > 0;
+        risk.RecommendedScope = packets.Count > 1
+            ? "Run a dry-run pilot (--dry-run) or a single --project packet before authoring the full surface."
+            : "Limit the first authoring pass to a 20-target pilot, then review before continuing.";
+
+        var authoringIntent = options.DryRun || options.ProjectHints.Count > 0 || options.ProjectManifestPath is not null ||
+                              options.ResumeProjectManifestPath is not null || options.BuildApiModel;
+        if (risk.HighRisk && authoringIntent && !options.AllowHighRisk)
+        {
+            report.Warnings.Add(new Diagnostic("QUALITY_RISK_REVIEW_REQUIRED", null, null,
+                $"High-risk authoring queue: {string.Join("; ", risk.TriggeredThresholds)}. Stop after the first project packet or {risk.PilotTargetCap} newly authored targets and obtain explicit review before continuing. {risk.RecommendedScope} Pass --allow-high-risk only as an explicit, reviewed decision."));
+        }
+
+        return risk;
+    }
+
+    private static ScopeReport BuildScopeReport(ScopePlan scope, List<ProjectPacket> packets,
+        List<MetadataGroupInfo> groups, GitState gitState, List<FamilyExemption> families, string repoRoot, Report report)
+    {
+        string RelPath(string abs) => Rel(repoRoot, abs);
+
+        var diagnosticsByNamespace = report.Errors
+            .Where(e => e.Namespace is not null)
+            .GroupBy(e => e.Namespace!, StringComparer.Ordinal)
+            .ToDictionary(g => g.Key, g => g.ToList(), StringComparer.Ordinal);
+
+        var scopeReport = new ScopeReport
+        {
+            Mode = scope.Mode,
+            Seed = scope.Seed,
+            ScopeState = scope.ScopeState,
+            SelectedProjects = packets.Where(p => p.Selected).Select(p => RelPath(p.NormalizedPath)).OrderBy(p => p, StringComparer.OrdinalIgnoreCase).ToList()
+        };
+
+        foreach (var group in groups)
+        {
+            var selected = packets.FirstOrDefault(p => p.Selected && p.MetadataGroupIds.Contains(group.Id, StringComparer.Ordinal));
+            scopeReport.MetadataGroups.Add(new MetadataGroupReport
+            {
+                Id = group.Id,
+                MetadataIndex = group.MetadataIndex,
+                Dest = group.Dest,
+                Projects = group.ProjectPaths.Select(RelPath).OrderBy(p => p, StringComparer.OrdinalIgnoreCase).ToList(),
+                SelectedProject = selected is null ? null : RelPath(selected.NormalizedPath)
+            });
+        }
+
+        foreach (var packet in packets)
+        {
+            var counts = new Dictionary<string, int>(StringComparer.Ordinal);
+            foreach (var ns in packet.Namespaces)
+            {
+                if (diagnosticsByNamespace.TryGetValue(ns, out var diags))
+                {
+                    foreach (var d in diags)
+                    {
+                        counts[d.Code] = counts.GetValueOrDefault(d.Code) + 1;
+                    }
+                }
+            }
+
+            scopeReport.Packets.Add(new PacketReport
+            {
+                Project = RelPath(packet.NormalizedPath),
+                AssemblyName = packet.Project.AssemblyName,
+                PackageId = packet.Project.PackageId,
+                MetadataGroups = packet.MetadataGroupIds.OrderBy(g => g, StringComparer.Ordinal).ToList(),
+                Namespaces = packet.Namespaces.OrderBy(n => n, StringComparer.Ordinal).ToList(),
+                SharedNamespaces = packet.SharedNamespaces.OrderBy(n => n, StringComparer.Ordinal).ToList(),
+                TypeTargets = packet.Targets.Count(t => t.Kind == ApiTargetKind.Type),
+                ExtensionTargets = packet.Targets.Count(t => t.Kind == ApiTargetKind.ExtensionMethod),
+                OverwritePaths = packet.OverwritePaths,
+                ReviewPaths = packet.Namespaces
+                    .Select(ns => RelPath(Path.Combine(Path.GetDirectoryName(report.DocfxPath!)!, "api", "namespaces", ns + ".md")))
+                    .Concat(packet.Targets.Where(t => t.Kind == ApiTargetKind.Type)
+                        .Select(t => RelPath(Path.Combine(Path.GetDirectoryName(report.DocfxPath!)!, "api", "types", t.Uid + ".md"))))
+                    .Concat(packet.OverwritePaths)
+                    .Distinct(StringComparer.OrdinalIgnoreCase)
+                    .OrderBy(path => path, StringComparer.OrdinalIgnoreCase)
+                    .ToList(),
+                DirtyRelatedPaths = packet.DirtyRelatedPaths,
+                Dirty = packet.Dirty,
+                Selected = packet.Selected,
+                DiagnosticCounts = counts
+            });
+        }
+
+        foreach (var skipped in packets.Where(p => !p.Selected))
+        {
+            scopeReport.SkippedProjects.Add(new SkippedProjectReport
+            {
+                Project = RelPath(skipped.NormalizedPath),
+                Reason = skipped.Dirty ? "dirty-related-paths" : (scope.Mode == "full" ? "n/a" : "not-selected"),
+                ConflictingPaths = skipped.DirtyRelatedPaths
+            });
+        }
+
+        foreach (var family in families)
+        {
+            scopeReport.FamilyExemptions.Add(new FamilyExemptionReport
+            {
+                FamilyId = family.FamilyId,
+                NamespaceUid = family.NamespaceUid,
+                AnchorUid = family.AnchorUid,
+                CoveredUids = family.CoveredUids,
+                Rationale = family.Rationale,
+                Valid = family.Valid
+            });
+        }
+
+        scopeReport.Dirty = new GitStateReport
+        {
+            Available = gitState.Available,
+            Staged = gitState.Staged.Select(RelPath).OrderBy(p => p, StringComparer.OrdinalIgnoreCase).ToList(),
+            Unstaged = gitState.Unstaged.Select(RelPath).OrderBy(p => p, StringComparer.OrdinalIgnoreCase).ToList(),
+            Renamed = gitState.Renamed.Select(RelPath).OrderBy(p => p, StringComparer.OrdinalIgnoreCase).ToList(),
+            Deleted = gitState.Deleted.Select(RelPath).OrderBy(p => p, StringComparer.OrdinalIgnoreCase).ToList(),
+            Untracked = gitState.Untracked.Select(RelPath).OrderBy(p => p, StringComparer.OrdinalIgnoreCase).ToList()
+        };
+
+        if (scope.Mode == "dry-run")
+        {
+            var projectArgs = string.Join(" ", scopeReport.SelectedProjects.Select(p => $"--project {p}"));
+            scopeReport.ReproduceCommand = scope.Seed is not null
+                ? $"docfx.cs --repo-root <root> --dry-run --seed {scope.Seed}"
+                : $"docfx.cs --repo-root <root> --dry-run {projectArgs}".TrimEnd();
+        }
+
+        return scopeReport;
+    }
+
+    private static void WriteProjectManifest(string path, string repoRoot, string docfxPath, ScopeReport scope,
+        QualityRiskReport risk, string apiModelSource, Report report)
+    {
+        var manifest = new
+        {
+            schemaVersion = 2,
+            repoRoot = ".",
+            docfxPath = Rel(repoRoot, docfxPath),
+            apiModelSource,
+            runMode = scope.Mode,
+            seed = scope.Seed,
+            scopeState = scope.ScopeState,
+            metadataGroups = scope.MetadataGroups,
+            packets = scope.Packets,
+            dirty = scope.Dirty,
+            familyExemptions = scope.FamilyExemptions,
+            qualityRisk = risk
+        };
+
+        var json = JsonSerializer.Serialize(manifest, JsonOptions);
+        var full = Path.GetFullPath(path, repoRoot);
+        var dir = Path.GetDirectoryName(full);
+        if (!string.IsNullOrEmpty(dir) && !Directory.Exists(dir))
+        {
+            Directory.CreateDirectory(dir);
+        }
+
+        File.WriteAllText(full, json, new UTF8Encoding(false));
+        report.ProjectManifestPath = Rel(repoRoot, full);
+        var reviewFull = Path.Combine(Path.GetDirectoryName(full) ?? repoRoot,
+            Path.GetFileNameWithoutExtension(full) + ".review.json");
+        if (!File.Exists(reviewFull))
+        {
+            var reviewTemplate = new
+            {
+                schemaVersion = 1,
+                pages = scope.Packets
+                    .Where(packet => packet.Selected)
+                    .SelectMany(packet => packet.ReviewPaths)
+                    .Distinct(StringComparer.OrdinalIgnoreCase)
+                    .OrderBy(reviewPath => reviewPath, StringComparer.OrdinalIgnoreCase)
+                    .Select(reviewPath => new
+                    {
+                        path = reviewPath,
+                        evidence = string.Empty,
+                        purpose = string.Empty,
+                        observableOutcome = string.Empty,
+                        patternComparison = string.Empty
+                    })
+            };
+            File.WriteAllText(reviewFull, JsonSerializer.Serialize(reviewTemplate, JsonOptions), new UTF8Encoding(false));
+        }
+
+        report.ReviewReportPath = Rel(repoRoot, reviewFull);
+        scope.ResumeCommand =
+            $"docfx.cs --repo-root <root> --resume-project-manifest \"{full}\" --review-report \"{reviewFull}\" --build-api-model --validate-samples --verify-docfx-build --json";
+    }
+
+    private static void ValidateChangedPageReview(string? path, string repoRoot, List<ProjectPacket> packets,
+        GitState gitState, Report report)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            report.Errors.Add(new Diagnostic("REVIEW_REPORT_MISSING", null, null,
+                "Resumed project authoring requires --review-report <path>. Complete the template emitted beside the project manifest so every changed page is reviewed before scoped completion."));
+            return;
+        }
+
+        var full = Path.GetFullPath(path, repoRoot);
+        if (!File.Exists(full))
+        {
+            report.Errors.Add(new Diagnostic("REVIEW_REPORT_MISSING", Rel(repoRoot, full), null,
+                "The changed-page review report does not exist."));
+            return;
+        }
+
+        var expected = packets.Where(packet => packet.Selected)
+            .SelectMany(packet => packet.Namespaces.Select(ns => Path.Combine(Path.GetDirectoryName(report.DocfxPath!)!, "api", "namespaces", ns + ".md"))
+                .Concat(packet.Targets.Where(t => t.Kind == ApiTargetKind.Type)
+                    .Select(t => Path.Combine(Path.GetDirectoryName(report.DocfxPath!)!, "api", "types", t.Uid + ".md")))
+                .Concat(packet.OverwritePaths.Select(rel => Path.Combine(repoRoot, rel))))
+            .Select(Path.GetFullPath)
+            .Where(candidate => File.Exists(candidate) && gitState.AllDirty.Contains(candidate))
+            .Select(candidate => Rel(repoRoot, candidate))
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .OrderBy(candidate => candidate, StringComparer.OrdinalIgnoreCase)
+            .ToList();
+
+        try
+        {
+            using var doc = JsonDocument.Parse(File.ReadAllText(full), new JsonDocumentOptions
+            {
+                AllowTrailingCommas = true,
+                CommentHandling = JsonCommentHandling.Skip
+            });
+            if (!doc.RootElement.TryGetProperty("schemaVersion", out var schema) || schema.GetInt32() != 1 ||
+                !doc.RootElement.TryGetProperty("pages", out var pages) || pages.ValueKind != JsonValueKind.Array)
+            {
+                report.Errors.Add(new Diagnostic("REVIEW_REPORT_INVALID", Rel(repoRoot, full), null,
+                    "The review report must use schemaVersion 1 and contain a pages array."));
+                return;
+            }
+
+            var reviewed = new Dictionary<string, JsonElement>(StringComparer.OrdinalIgnoreCase);
+            foreach (var page in pages.EnumerateArray())
+            {
+                var reviewPath = ReadJsonString(page, "path");
+                if (!string.IsNullOrWhiteSpace(reviewPath))
+                {
+                    reviewed[NormalizeDocfxPath(reviewPath)] = page;
+                }
+            }
+
+            foreach (var expectedPath in expected)
+            {
+                if (!reviewed.TryGetValue(NormalizeDocfxPath(expectedPath), out var page))
+                {
+                    report.Errors.Add(new Diagnostic("REVIEW_REPORT_INCOMPLETE", expectedPath, null,
+                        "The changed page is missing from the review report."));
+                    continue;
+                }
+
+                var fields = new[]
+                {
+                    (Name: "evidence", Minimum: 5),
+                    (Name: "purpose", Minimum: 20),
+                    (Name: "observableOutcome", Minimum: 10),
+                    (Name: "patternComparison", Minimum: 20)
+                };
+                foreach (var field in fields)
+                {
+                    var value = ReadJsonString(page, field.Name);
+                    if (string.IsNullOrWhiteSpace(value) || value.Trim().Length < field.Minimum ||
+                        Regex.IsMatch(value, @"(?i)^(?:todo|tbd|n/?a|none|same as above|looks good)[.!]?$"))
+                    {
+                        report.Errors.Add(new Diagnostic("REVIEW_REPORT_INCOMPLETE", expectedPath, null,
+                            $"Review field '{field.Name}' must contain page-specific evidence or analysis (minimum {field.Minimum} characters)."));
+                    }
+                }
+            }
+
+            report.ReviewReportPath = Rel(repoRoot, full);
+        }
+        catch (Exception ex) when (ex is IOException or JsonException or InvalidOperationException)
+        {
+            report.Errors.Add(new Diagnostic("REVIEW_REPORT_INVALID", Rel(repoRoot, full), null,
+                $"Unable to read the changed-page review report: {ex.Message}"));
+        }
+    }
+
+    // Safe structured overwrite writer: accepts an authored UID, mapping kind, prose, and C# fence,
+    // validates them, preserves BOM/line-endings, and refuses to clobber dirty paths it does not own.
+    private static int WriteOverwriteCommand(Options options)
+    {
+        var report = new Report { Script = ScriptId };
+        string requestPath;
+        try
+        {
+            requestPath = Path.GetFullPath(options.WriteOverwriteRequestPath!);
+        }
+        catch (Exception ex)
+        {
+            return EmitOverwrite(options, report, ExitCode.InvalidArguments, $"Invalid request path: {ex.Message}");
+        }
+
+        if (!File.Exists(requestPath))
+        {
+            report.Errors.Add(new Diagnostic("OVERWRITE_REQUEST_MISSING", requestPath, null, "The overwrite request JSON file does not exist."));
+            return EmitOverwrite(options, report, ExitCode.InvalidArguments, "Request file missing.");
+        }
+
+        JsonDocument doc;
+        try
+        {
+            doc = JsonDocument.Parse(File.ReadAllText(requestPath), new JsonDocumentOptions { AllowTrailingCommas = true, CommentHandling = JsonCommentHandling.Skip });
+        }
+        catch (Exception ex)
+        {
+            report.Errors.Add(new Diagnostic("OVERWRITE_REQUEST_INVALID", requestPath, null, $"Unable to parse the overwrite request: {ex.Message}"));
+            return EmitOverwrite(options, report, ExitCode.InvalidArguments, "Request invalid.");
+        }
+
+        string? file, uid, mapping, prose, fence;
+        using (doc)
+        {
+            file = ReadJsonString(doc.RootElement, "file");
+            uid = ReadJsonString(doc.RootElement, "uid");
+            mapping = ReadJsonString(doc.RootElement, "mapping") ?? "example";
+            prose = ReadJsonString(doc.RootElement, "prose");
+            fence = ReadJsonString(doc.RootElement, "fence");
+        }
+
+        if (string.IsNullOrWhiteSpace(file) || string.IsNullOrWhiteSpace(uid))
+        {
+            report.Errors.Add(new Diagnostic("OVERWRITE_REQUEST_INVALID", requestPath, null, "The request must specify 'file' and 'uid'."));
+            return EmitOverwrite(options, report, ExitCode.InvalidArguments, "Request invalid.");
+        }
+
+        if (mapping is not ("example" or "summary" or "remarks"))
+        {
+            report.Errors.Add(new Diagnostic("OVERWRITE_REQUEST_INVALID", requestPath, uid, "mapping must be 'example', 'summary', or 'remarks'."));
+            return EmitOverwrite(options, report, ExitCode.InvalidArguments, "Request invalid.");
+        }
+
+        if (!string.IsNullOrEmpty(fence) && CountOccurrences(fence, "```") % 2 != 0)
+        {
+            report.Errors.Add(new Diagnostic("OVERWRITE_FENCE_UNBALANCED", uid, uid, "The supplied C# fence content has unbalanced ``` fences."));
+            return EmitOverwrite(options, report, ExitCode.ValidationFailed, "Unbalanced fence.");
+        }
+
+        var repoRoot = Path.GetFullPath(string.IsNullOrWhiteSpace(options.RepoRoot) ? "." : options.RepoRoot);
+        var fullFile = Path.GetFullPath(file!, repoRoot);
+        var existedBefore = File.Exists(fullFile);
+
+        // Dirty-path protection: refuse to *replace* a file that already had uncommitted changes.
+        // Creating a brand-new overwrite file is always allowed.
+        var gitState = GetGitState(repoRoot);
+        if (existedBefore && gitState.AllDirty.Any(p => PathsEqual(p, fullFile)))
+        {
+            report.Errors.Add(new Diagnostic("OVERWRITE_DIRTY_REFUSED", Rel(repoRoot, fullFile), uid,
+                "Refusing to overwrite a file that has pre-existing uncommitted changes. Resolve or stage it deliberately first."));
+            return EmitOverwrite(options, report, ExitCode.ValidationFailed, "Dirty path refused.");
+        }
+
+        // Duplicate UID guard within the same file.
+        var existing = existedBefore ? File.ReadAllText(fullFile) : string.Empty;
+        if (!string.IsNullOrEmpty(existing) && Regex.Matches(existing, $@"(?m)^\s*uid\s*:\s*{Regex.Escape(uid!)}\s*$").Count > 0)
+        {
+            report.Errors.Add(new Diagnostic("OVERWRITE_UID_DUPLICATE", Rel(repoRoot, fullFile), uid,
+                $"UID '{uid}' already has an overwrite section in this file. Edit it in place instead of appending a duplicate."));
+            return EmitOverwrite(options, report, ExitCode.ValidationFailed, "Duplicate UID.");
+        }
+
+        var hasBom = existing.Length > 0 && File.ReadAllBytes(fullFile).Length >= 3 &&
+                     File.ReadAllBytes(fullFile)[0] == 0xEF;
+        var newline = existing.Contains("\r\n", StringComparison.Ordinal) ? "\r\n" : "\n";
+
+        var sb = new StringBuilder();
+        if (existing.Length > 0 && !existing.EndsWith("\n", StringComparison.Ordinal))
+        {
+            sb.Append(newline);
+        }
+
+        sb.Append("---").Append(newline);
+        sb.Append("uid: ").Append(uid).Append(newline);
+        sb.Append(mapping).Append(": *content").Append(newline);
+        sb.Append("---").Append(newline);
+        if (!string.IsNullOrWhiteSpace(prose))
+        {
+            sb.Append(prose!.Replace("\r\n", "\n", StringComparison.Ordinal).Replace("\n", newline, StringComparison.Ordinal)).Append(newline).Append(newline);
+        }
+
+        if (!string.IsNullOrWhiteSpace(fence))
+        {
+            sb.Append(fence!.Replace("\r\n", "\n", StringComparison.Ordinal).Replace("\n", newline, StringComparison.Ordinal));
+            if (!fence.EndsWith("\n", StringComparison.Ordinal))
+            {
+                sb.Append(newline);
+            }
+        }
+
+        var addition = sb.ToString();
+        var finalText = existing + addition;
+
+        var dir = Path.GetDirectoryName(fullFile);
+        if (!string.IsNullOrEmpty(dir) && !Directory.Exists(dir))
+        {
+            Directory.CreateDirectory(dir);
+        }
+
+        var encoding = new UTF8Encoding(hasBom);
+        File.WriteAllText(fullFile, finalText, encoding);
+
+        report.Status = "passed";
+        report.Summary.CompletionState = "overwrite-written";
+        report.Summary.CanClaimCompletion = false;
+        if (options.Json)
+        {
+            var preview = new
+            {
+                script = ScriptId,
+                status = "passed",
+                file = Rel(repoRoot, fullFile),
+                uid,
+                mapping,
+                bomPreserved = hasBom,
+                lineEnding = newline == "\r\n" ? "crlf" : "lf",
+                bytesWritten = encoding.GetByteCount(finalText),
+                preview = addition
+            };
+            Console.WriteLine(JsonSerializer.Serialize(preview, JsonOptions));
+        }
+        else
+        {
+            Console.WriteLine($"{ScriptId}: wrote {mapping} overwrite for {uid} into {Rel(repoRoot, fullFile)} (bom={hasBom}, eol={(newline == "\r\n" ? "crlf" : "lf")}).");
+        }
+
+        return (int)ExitCode.Success;
+    }
+
+    private static int EmitOverwrite(Options options, Report report, ExitCode code, string message)
+    {
+        report.Status = code == ExitCode.Success ? "passed" : "failed";
+        if (options.Json)
+        {
+            Console.WriteLine(JsonSerializer.Serialize(report, JsonOptions));
+        }
+        else
+        {
+            Console.Error.WriteLine($"{ScriptId}: {message}");
+            foreach (var error in report.Errors)
+            {
+                Console.Error.WriteLine($"  ERROR  [{error.Code}] {error.Message}");
+            }
+        }
+
+        return (int)code;
+    }
+
+    private static int CountOccurrences(string text, string token)
+    {
+        var count = 0;
+        var index = 0;
+        while ((index = text.IndexOf(token, index, StringComparison.Ordinal)) >= 0)
+        {
+            count++;
+            index += token.Length;
+        }
+
+        return count;
+    }
+
+    private static void SearchGitHubForExamples(List<string> packageIds, Report report)
+    {
+        if (packageIds.Count == 0)
+        {
+            return;
+        }
+
+        report.ExampleSearchSnippets.Add("## GitHub Search Results");
+        report.ExampleSearchSnippets.Add(string.Empty);
+        report.ExampleSearchSnippets.Add("Results from `gh search code` for documented packages. Prefer usage from repositories other than the target repository.");
+        report.ExampleSearchSnippets.Add(string.Empty);
+
+        foreach (var packageId in packageIds)
+        {
+            report.ExampleSearchSnippets.Add($"### Package: `{packageId}`");
+            report.ExampleSearchSnippets.Add(string.Empty);
+
+            var result = RunProcess(
+                "gh",
+                $"search code \"{packageId}\" --language C# --limit 5 --json path,repository",
+                Directory.GetCurrentDirectory(),
+                permission: ProcessPermission.GitHubSearch);
+
+            if (result.ExitCode != 0 || string.IsNullOrWhiteSpace(result.StdOut))
+            {
+                report.ExampleSearchSnippets.Add($"Search unavailable (gh exit {result.ExitCode}). Use the URL below.");
+                report.ExampleSearchSnippets.Add(string.Empty);
+                continue;
+            }
+
+            try
+            {
+                using var doc = JsonDocument.Parse(result.StdOut);
+                if (doc.RootElement.ValueKind != JsonValueKind.Array || doc.RootElement.GetArrayLength() == 0)
+                {
+                    report.ExampleSearchSnippets.Add("No results found.");
+                    report.ExampleSearchSnippets.Add(string.Empty);
+                    continue;
+                }
+
+                foreach (var hit in doc.RootElement.EnumerateArray())
+                {
+                    var path = hit.TryGetProperty("path", out var pathEl) ? pathEl.GetString() ?? string.Empty : string.Empty;
+                    var repoName = string.Empty;
+                    if (hit.TryGetProperty("repository", out var repoEl) && repoEl.ValueKind == JsonValueKind.Object)
+                    {
+                        repoName = repoEl.TryGetProperty("fullName", out var fn) ? fn.GetString() ?? string.Empty : string.Empty;
+                        if (string.IsNullOrEmpty(repoName))
+                        {
+                            repoName = repoEl.TryGetProperty("nameWithOwner", out var nwo) ? nwo.GetString() ?? string.Empty : string.Empty;
+                        }
+                    }
+
+                    if (!string.IsNullOrEmpty(repoName) || !string.IsNullOrEmpty(path))
+                    {
+                        report.ExampleSearchSnippets.Add($"- `{repoName}`: `{path}`");
+                    }
+                }
+
+                report.ExampleSearchSnippets.Add(string.Empty);
+            }
+            catch
+            {
+                report.ExampleSearchSnippets.Add("Unable to parse search results.");
+                report.ExampleSearchSnippets.Add(string.Empty);
+            }
+        }
+    }
+
+    // ----------------------------------------------------------------------
+    // YAML / markdown helpers
+    // ----------------------------------------------------------------------
+
+    private static (string FrontMatter, string Body) SplitFrontMatter(string text)
     {
         var normalized = text.Replace("\r\n", "\n").Replace("\r", "\n");
         if (!normalized.StartsWith("---\n", StringComparison.Ordinal))
@@ -4964,6 +6724,20 @@ private static int Emit(Options options, Report report, ExitCode code, string co
         report.Summary.CompletionState = report.Summary.CanClaimCompletion
             ? "complete"
             : report.Errors.Count > 0 ? "incomplete" : "verification-required";
+
+        // A dry run or an explicitly scoped run never claims repository-wide completion; it reports
+        // only the state of the selected scope so a passing subset is not mistaken for a full digest.
+        if (report.Summary.RunMode is "dry-run" or "scoped")
+        {
+            report.Summary.CanClaimCompletion = false;
+            var prefix = report.Summary.RunMode;
+            report.Summary.CompletionState = code == ExitCode.Success &&
+                                             report.Errors.Count == 0 &&
+                                             report.Summary.RemainingGates.Count == 0
+                ? $"{prefix}-passed"
+                : $"{prefix}-failed";
+        }
+
         report.Summary.RemainingWorkItems = report.Errors.Count + report.Summary.RemainingGates.Count;
         report.Summary.RemainingDiagnosticsByCode = report.Errors
             .GroupBy(error => error.Code, StringComparer.Ordinal)
@@ -5261,8 +7035,11 @@ private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerab
             var action = diagnostic.Code switch
             {
                 "EXAMPLE_UID_DUPLICATE" => "Merge the duplicate mappings into one coherent example section for the UID, then rerun validation.",
-                "EXAMPLE_PLACEHOLDER" or "EXAMPLE_REFLECTION_ONLY" or "EXAMPLE_TARGET_NOT_USED" =>
-                    "Inspect exact test, package README, sample, XML-comment, or source evidence; replace the scaffold with a consumer task that uses the target in C# and exposes a result or next action.",
+                "EXAMPLE_PLACEHOLDER" or "EXAMPLE_REFLECTION_ONLY" or "EXAMPLE_TARGET_NOT_USED" or
+                "EXAMPLE_DEFAULT_PLACEHOLDER" or "EXAMPLE_NO_OBSERVABLE_OUTCOME" or "EXAMPLE_FORWARDING_SCAFFOLD" =>
+                    "Inspect exact test, package README, sample, XML-comment, or source evidence; replace the scaffold with a consumer task that constructs or invokes the target in C# and exposes a result or next action.",
+                "EXAMPLE_TEMPLATE_REPETITION" =>
+                    "Rewrite each implicated example around the distinct behavior of its own type; do not reuse one normalized skeleton across unrelated targets.",
                 "EXTENSION_EXAMPLE_NOT_INVOKED" =>
                     "Replace prose-only or metadata-only coverage with a C# scenario that invokes the extension method on a valid receiver.",
                 _ when diagnostic.Message.Contains("Public non-abstraction type", StringComparison.Ordinal) =>
@@ -5278,7 +7055,9 @@ _ when diagnostic.Message.Contains("Public non-abstraction type", StringComparis
     private static bool IsExampleQualityDiagnostic(Diagnostic diagnostic)
     {
         return diagnostic.Code is "EXAMPLE_MISSING" or "EXAMPLE_UID_DUPLICATE" or "EXAMPLE_PLACEHOLDER" or
-            "EXAMPLE_REFLECTION_ONLY" or "EXAMPLE_TARGET_NOT_USED" or "EXTENSION_EXAMPLE_NOT_INVOKED";
+            "EXAMPLE_REFLECTION_ONLY" or "EXAMPLE_TARGET_NOT_USED" or "EXTENSION_EXAMPLE_NOT_INVOKED" or
+            "EXAMPLE_DEFAULT_PLACEHOLDER" or "EXAMPLE_NO_OBSERVABLE_OUTCOME" or "EXAMPLE_FORWARDING_SCAFFOLD" or
+            "EXAMPLE_TEMPLATE_REPETITION";
     }
 
     private static string EscapeTable(string value)
@@ -5376,6 +7155,52 @@ private static bool TryParse(string[] args, out Options options, out string erro
                 case "--no-clean-generated-metadata":
                     options.CleanGeneratedMetadata = false;
                     break;
+                case "--project":
+                    if (!Next(args, ref i, out var ph)) { error = "--project requires a project hint."; return false; }
+                    options.ProjectHints.Add(ph);
+                    break;
+                case "--dry-run":
+                    options.DryRun = true;
+                    break;
+                case "--seed":
+                    if (!Next(args, ref i, out var sd)) { error = "--seed requires an integer."; return false; }
+                    if (!long.TryParse(sd, out var sdv)) { error = "--seed must be an integer."; return false; }
+                    options.Seed = sdv;
+                    break;
+                case "--project-manifest":
+                    if (!Next(args, ref i, out var pm)) { error = "--project-manifest requires a path."; return false; }
+                    options.ProjectManifestPath = pm;
+                    break;
+                case "--resume-project-manifest":
+                    if (!Next(args, ref i, out var rpm)) { error = "--resume-project-manifest requires a path."; return false; }
+                    options.ResumeProjectManifestPath = rpm;
+                    break;
+                case "--review-report":
+                    if (!Next(args, ref i, out var rrp)) { error = "--review-report requires a path."; return false; }
+                    options.ReviewReportPath = rrp;
+                    break;
+                case "--write-overwrite":
+                    if (!Next(args, ref i, out var wo)) { error = "--write-overwrite requires a request JSON path."; return false; }
+                    options.WriteOverwriteRequestPath = wo;
+                    break;
+                case "--allow-high-risk":
+                    options.AllowHighRisk = true;
+                    break;
+                case "--risk-standalone-threshold":
+                    if (!Next(args, ref i, out var rst)) { error = "--risk-standalone-threshold requires a count."; return false; }
+                    if (!int.TryParse(rst, out var rstv) || rstv < 0) { error = "--risk-standalone-threshold must be a non-negative integer."; return false; }
+                    options.RiskStandaloneThreshold = rstv;
+                    break;
+                case "--risk-extension-threshold":
+                    if (!Next(args, ref i, out var ret)) { error = "--risk-extension-threshold requires a count."; return false; }
+                    if (!int.TryParse(ret, out var retv) || retv < 0) { error = "--risk-extension-threshold must be a non-negative integer."; return false; }
+                    options.RiskExtensionThreshold = retv;
+                    break;
+                case "--risk-missing-ratio-threshold":
+                    if (!Next(args, ref i, out var rmr)) { error = "--risk-missing-ratio-threshold requires a number."; return false; }
+                    if (!double.TryParse(rmr, System.Globalization.NumberStyles.Float, System.Globalization.CultureInfo.InvariantCulture, out var rmrv) || rmrv < 0) { error = "--risk-missing-ratio-threshold must be a non-negative number."; return false; }
+                    options.RiskMissingRatioThreshold = rmrv;
+                    break;
                 case "--json":
                     options.Json = true;
                     break;
@@ -5414,6 +7239,52 @@ private static bool TryParse(string[] args, out Options options, out string erro
                         options.ExecutionProfile = v10.ToLowerInvariant();
                         break;
                     }
+                    if (TrySplit(arg, "--project", out var v11) && !string.IsNullOrWhiteSpace(v11))
+                    {
+                        options.ProjectHints.Add(v11);
+                        break;
+                    }
+                    if (TrySplit(arg, "--seed", out var v12) && long.TryParse(v12, out var seedInline))
+                    {
+                        options.Seed = seedInline;
+                        break;
+                    }
+                    if (TrySplit(arg, "--project-manifest", out var v13) && !string.IsNullOrWhiteSpace(v13))
+                    {
+                        options.ProjectManifestPath = v13;
+                        break;
+                    }
+                    if (TrySplit(arg, "--resume-project-manifest", out var v18) && !string.IsNullOrWhiteSpace(v18))
+                    {
+                        options.ResumeProjectManifestPath = v18;
+                        break;
+                    }
+                    if (TrySplit(arg, "--review-report", out var v19) && !string.IsNullOrWhiteSpace(v19))
+                    {
+                        options.ReviewReportPath = v19;
+                        break;
+                    }
+                    if (TrySplit(arg, "--write-overwrite", out var v14) && !string.IsNullOrWhiteSpace(v14))
+                    {
+                        options.WriteOverwriteRequestPath = v14;
+                        break;
+                    }
+                    if (TrySplit(arg, "--risk-standalone-threshold", out var v15) && int.TryParse(v15, out var rstInline) && rstInline >= 0)
+                    {
+                        options.RiskStandaloneThreshold = rstInline;
+                        break;
+                    }
+                    if (TrySplit(arg, "--risk-extension-threshold", out var v16) && int.TryParse(v16, out var retInline) && retInline >= 0)
+                    {
+                        options.RiskExtensionThreshold = retInline;
+                        break;
+                    }
+                    if (TrySplit(arg, "--risk-missing-ratio-threshold", out var v17) &&
+                        double.TryParse(v17, System.Globalization.NumberStyles.Float, System.Globalization.CultureInfo.InvariantCulture, out var rmrInline) && rmrInline >= 0)
+                    {
+                        options.RiskMissingRatioThreshold = rmrInline;
+                        break;
+                    }
 
                     error = $"Unknown argument: {arg}";
                     return false;
@@ -5516,6 +7387,33 @@ repair plan. Requires the gh CLI to be authenticated. Use together with --repair
                                       Runs only after the API model is built, so it never deletes YAML the fast path used.
               --no-clean-generated-metadata
                                       Leave DocFX-generated metadata files untouched (already the default).
+
+            Project-scoped authoring:
+              --project <hint>         Repeatable. Document only the matching project packet(s). A hint
+                                      resolves against project path, file name, assembly name, or package id
+                                      and must match exactly one project. Scoped runs never claim repo completion.
+              --dry-run                Representative run: select one clean project from each metadata
+                                      destination group (or all explicit --project packets). Persist the initial
+                                      baseline with --project-manifest, author the selected packets, then resume it.
+              --seed <integer>         Seed the dry-run selection so it is reproducible. A seed is generated and
+                                      reported when omitted.
+              --project-manifest <path>
+                                      Write a deterministic BOM-less project packet manifest (groups, packets,
+                                      ownership, initial dirty paths, family exemptions, quality risk) and continue.
+              --resume-project-manifest <path>
+                                      Resume the exact selected packets and initial dirty-file baseline from a
+                                      prior manifest. Use this after authoring so newly created dry-run files are
+                                      validated without treating them as pre-existing user work.
+              --review-report <path>  Required with --resume-project-manifest. Complete the generated sibling
+                                      *.review.json file with page-specific evidence, purpose/outcome, observable
+                                      result, and cross-page pattern comparison before scoped completion.
+              --write-overwrite <path> Safe structured overwrite writer. Reads a JSON request with
+                                      file/uid/mapping/prose/fence fields, validates it, preserves BOM/line
+                                      endings, refuses to replace dirty or duplicate-UID files, and exits.
+              --allow-high-risk        Explicitly proceed past the quality-risk pilot stop (a reviewed decision).
+              --risk-standalone-threshold <n>     Standalone-example target threshold (default 100).
+              --risk-extension-threshold <n>      Extension-method target threshold (default 100).
+              --risk-missing-ratio-threshold <x>  Missing-to-existing example ratio threshold (default 10).
               --json                   Emit a machine-readable JSON summary (includes processes + phase timings).
               --help                   Print this usage.
 
@@ -5565,10 +7463,85 @@ private sealed class Options
         public int? ProcessTimeoutMinutes { get; set; }
         public string? ExecutionProfile { get; set; }
         public string SampleReferenceMode { get; set; } = "project";
+        public List<string> ProjectHints { get; } = new();
+        public bool DryRun { get; set; }
+        public long? Seed { get; set; }
+        public string? ProjectManifestPath { get; set; }
+        public string? ResumeProjectManifestPath { get; set; }
+        public string? ReviewReportPath { get; set; }
+        public string? WriteOverwriteRequestPath { get; set; }
+        public bool AllowHighRisk { get; set; }
+        public int? RiskStandaloneThreshold { get; set; }
+        public int? RiskExtensionThreshold { get; set; }
+        public double? RiskMissingRatioThreshold { get; set; }
     }
 
     private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest, string? PackageId = null);
 
+    private sealed record MetadataGroupInfo(string Id, int MetadataIndex, string Dest)
+    {
+        public Dictionary<string, string> Properties { get; } = new(StringComparer.OrdinalIgnoreCase);
+        public List<string> ProjectPaths { get; } = new();
+    }
+
+    private sealed class GitState
+    {
+        public bool Available { get; init; }
+        public HashSet<string> Staged { get; } = new(StringComparer.OrdinalIgnoreCase);
+        public HashSet<string> Unstaged { get; } = new(StringComparer.OrdinalIgnoreCase);
+        public HashSet<string> Renamed { get; } = new(StringComparer.OrdinalIgnoreCase);
+        public HashSet<string> Deleted { get; } = new(StringComparer.OrdinalIgnoreCase);
+        public HashSet<string> Untracked { get; } = new(StringComparer.OrdinalIgnoreCase);
+
+        public IEnumerable<string> AllDirty =>
+            Staged.Concat(Unstaged).Concat(Renamed).Concat(Deleted).Concat(Untracked)
+                .Distinct(StringComparer.OrdinalIgnoreCase);
+    }
+
+    private sealed class ProjectPacket
+    {
+        public required ProjectInfo Project { get; init; }
+        public required string NormalizedPath { get; init; }
+        public List<string> MetadataGroupIds { get; } = new();
+        public List<string> Namespaces { get; } = new();
+        public List<string> SharedNamespaces { get; } = new();
+        public List<ApiTargetInfo> Targets { get; } = new();
+        public List<string> OverwritePaths { get; } = new();
+        public List<string> DirtyRelatedPaths { get; } = new();
+        public bool Selected { get; set; }
+        public bool Dirty => DirtyRelatedPaths.Count > 0;
+    }
+
+    private sealed record FamilyExemption(
+        string FamilyId,
+        string NamespaceUid,
+        string AnchorUid,
+        List<string> CoveredUids,
+        string Rationale,
+        string? AnchorExampleFile)
+    {
+        public bool Valid { get; set; }
+    }
+
+    private sealed class ScopePlan
+    {
+        public string Mode { get; set; } = "full";
+        public long? Seed { get; set; }
+        public string ScopeState { get; set; } = "authoritative";
+        public HashSet<string> SelectedProjectPaths { get; } = new(StringComparer.OrdinalIgnoreCase);
+        public HashSet<string> SelectedNamespaces { get; } = new(StringComparer.Ordinal);
+        public bool ScopeRestricted { get; set; }
+        public bool IncludesNamespace(string ns) => !ScopeRestricted || SelectedNamespaces.Contains(ns);
+    }
+
+    private sealed class ResumeProjectScope
+    {
+        public string Mode { get; set; } = "dry-run";
+        public long? Seed { get; set; }
+        public HashSet<string> SelectedProjectPaths { get; } = new(StringComparer.OrdinalIgnoreCase);
+        public HashSet<string> InitialDirtyPaths { get; } = new(StringComparer.OrdinalIgnoreCase);
+    }
+
     private sealed record ExtensionMethodInfo(string MethodName, string ExtendedType, string DeclaringClass);
 
     private sealed record ApiTargetInfo(string Uid, string Namespace, ApiTargetKind Kind, string DisplayName, string? DeclaringTypeUid = null);
@@ -5752,6 +7725,9 @@ internal sealed class Summary
     public ExecutionSummary Execution { get; set; } = new();
     public string? ValidationMode { get; set; }
     public string? ApiModelSource { get; set; }
+    public string RunMode { get; set; } = "full";
+    public string? ScopeState { get; set; }
+    public long? Seed { get; set; }
     public int PublicNamespaces { get; set; }
     public int NamespacePagesValidated { get; set; }
     public int RequiredExampleTargets { get; set; }
@@ -5799,10 +7775,103 @@ internal sealed class Report
     public string RepoRoot { get; set; } = string.Empty;
     public string? DocfxPath { get; set; }
     public string? RepairPlanPath { get; set; }
+    public string? ProjectManifestPath { get; set; }
+    public string? ResumedProjectManifestPath { get; set; }
+    public string? ReviewReportPath { get; set; }
     public string? Status { get; set; }
     public Summary Summary { get; set; } = new();
+    public ScopeReport? Scope { get; set; }
+    public QualityRiskReport? QualityRisk { get; set; }
     public List<Diagnostic> Errors { get; set; } = new();
     public List<Diagnostic> Warnings { get; set; } = new();
     public List<string> PackageIds { get; set; } = new();
     public List<string> ExampleSearchSnippets { get; set; } = new();
 }
+
+internal sealed class ScopeReport
+{
+    public string Mode { get; set; } = "full";
+    public long? Seed { get; set; }
+    public string? ScopeState { get; set; }
+    public List<MetadataGroupReport> MetadataGroups { get; set; } = new();
+    public List<string> SelectedProjects { get; set; } = new();
+    public List<SkippedProjectReport> SkippedProjects { get; set; } = new();
+    public List<PacketReport> Packets { get; set; } = new();
+    public GitStateReport Dirty { get; set; } = new();
+    public List<FamilyExemptionReport> FamilyExemptions { get; set; } = new();
+    public string? ReproduceCommand { get; set; }
+    public string? ResumeCommand { get; set; }
+}
+
+internal sealed class MetadataGroupReport
+{
+    public string Id { get; set; } = string.Empty;
+    public int MetadataIndex { get; set; }
+    public string Dest { get; set; } = string.Empty;
+    public List<string> Projects { get; set; } = new();
+    public string? SelectedProject { get; set; }
+}
+
+internal sealed class SkippedProjectReport
+{
+    public string Project { get; set; } = string.Empty;
+    public string Reason { get; set; } = string.Empty;
+    public List<string> ConflictingPaths { get; set; } = new();
+}
+
+internal sealed class PacketReport
+{
+    public string Project { get; set; } = string.Empty;
+    public string AssemblyName { get; set; } = string.Empty;
+    public string? PackageId { get; set; }
+    public List<string> MetadataGroups { get; set; } = new();
+    public List<string> Namespaces { get; set; } = new();
+    public List<string> SharedNamespaces { get; set; } = new();
+    public int TypeTargets { get; set; }
+    public int ExtensionTargets { get; set; }
+    public List<string> OverwritePaths { get; set; } = new();
+    public List<string> ReviewPaths { get; set; } = new();
+    public List<string> DirtyRelatedPaths { get; set; } = new();
+    public bool Dirty { get; set; }
+    public bool Selected { get; set; }
+    public Dictionary<string, int> DiagnosticCounts { get; set; } = new();
+}
+
+internal sealed class GitStateReport
+{
+    public bool Available { get; set; }
+    public List<string> Staged { get; set; } = new();
+    public List<string> Unstaged { get; set; } = new();
+    public List<string> Renamed { get; set; } = new();
+    public List<string> Deleted { get; set; } = new();
+    public List<string> Untracked { get; set; } = new();
+}
+
+internal sealed class FamilyExemptionReport
+{
+    public string FamilyId { get; set; } = string.Empty;
+    public string NamespaceUid { get; set; } = string.Empty;
+    public string AnchorUid { get; set; } = string.Empty;
+    public List<string> CoveredUids { get; set; } = new();
+    public string Rationale { get; set; } = string.Empty;
+    public bool Valid { get; set; }
+}
+
+internal sealed class QualityRiskReport
+{
+    public bool HighRisk { get; set; }
+    public int StandaloneTargets { get; set; }
+    public int ExtensionTargets { get; set; }
+    public int ExistingValidExamples { get; set; }
+    public double MissingToExistingRatio { get; set; }
+    public int SymbolCollisions { get; set; }
+    public int TypeForwardedTargets { get; set; }
+    public int SharedNamespaces { get; set; }
+    public int UnresolvedExtensionOwners { get; set; }
+    public List<string> TriggeredThresholds { get; set; } = new();
+    public int StandaloneThreshold { get; set; }
+    public int ExtensionThreshold { get; set; }
+    public double RatioThreshold { get; set; }
+    public int PilotTargetCap { get; set; }
+    public string? RecommendedScope { get; set; }
+}
diff --git a/skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1 b/skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1
new file mode 100644
index 0000000..7600dee
--- /dev/null
+++ b/skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1
@@ -0,0 +1,659 @@
+param(
+    [string]$ValidatorPath = (Join-Path $PSScriptRoot 'docfx.cs')
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+# The validator intentionally exits non-zero for fixtures that contain diagnostics and now writes
+# append-only packet heartbeats to stderr. Opt out of native-command error promotion so a non-zero
+# exit or a stderr heartbeat is not treated as a terminating PowerShell error when this script is
+# invoked from another script (e.g. validate-skill-templates.ps1).
+$PSNativeCommandUseErrorActionPreference = $false
+
+$utf8NoBom = [System.Text.UTF8Encoding]::new($false)
+$csproj = @'
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+  </PropertyGroup>
+</Project>
+'@
+$agents = @'
+<!-- dotnet-docfx-digest:start -->
+Managed DocFX guidance.
+<!-- dotnet-docfx-digest:end -->
+'@
+
+function Write-Utf8File {
+    param([string]$Path, [string]$Content)
+    $dir = Split-Path -Parent $Path
+    if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
+    [System.IO.File]::WriteAllText($Path, $Content, $utf8NoBom)
+}
+
+function New-Workspace {
+    Join-Path ([System.IO.Path]::GetTempPath()) ('dotnet-docfx-scope-' + [guid]::NewGuid().ToString('N'))
+}
+
+function Invoke-ValidatorRaw {
+    param([string[]]$AllArgs)
+    # Relax ErrorActionPreference around the native call so a non-zero exit (diagnostic fixtures)
+    # and stderr packet heartbeats are never promoted to a terminating PowerShell error. Explicit
+    # `throw` statements in scenarios still halt. Returns raw stdout text.
+    $prev = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+        $out = & dotnet run --file $ValidatorPath -- @AllArgs 2>$null
+    } finally {
+        $ErrorActionPreference = $prev
+    }
+    return ($out -join "`n")
+}
+
+function Invoke-Validator {
+    param([string]$Workspace, [string[]]$ExtraArgs = @())
+    $all = @('--repo-root', $Workspace, '--json') + $ExtraArgs
+    return (ConvertFrom-ValidatorJson (Invoke-ValidatorRaw $all))
+}
+
+# The validator prints append-only packet heartbeats to stderr before the single JSON document on
+# stdout. Slice from the first '{' (the start of the JSON object) to parse robustly.
+function ConvertFrom-ValidatorJson {
+    param([string]$Text)
+    if ([string]::IsNullOrWhiteSpace($Text)) { throw 'Validator returned no output.' }
+    $start = $Text.IndexOf('{')
+    if ($start -lt 0) { throw "Validator returned no JSON document. Output: $Text" }
+    return ($Text.Substring($start) | ConvertFrom-Json)
+}
+
+function Assert-Diagnostic {
+    param([object]$Report, [string]$Code, [string]$Where = 'errors')
+    $list = if ($Where -eq 'warnings') { $Report.warnings } else { $Report.errors }
+    if (-not @($list | Where-Object code -eq $Code)) {
+        throw "Expected '$Code' in $Where but it was absent."
+    }
+}
+
+function Assert-NoDiagnostic {
+    param([object]$Report, [string]$Code)
+    if (@($Report.errors | Where-Object code -eq $Code)) { throw "Diagnostic '$Code' was unexpectedly present." }
+}
+
+function Initialize-GitRepo {
+    param([string]$Workspace)
+    Push-Location $Workspace
+    try {
+        & git init -q 2>$null | Out-Null
+        & git -c user.email=t@e.com -c user.name=t add -A 2>$null | Out-Null
+        & git -c user.email=t@e.com -c user.name=t commit -q -m base 2>$null | Out-Null
+    } finally { Pop-Location }
+}
+
+function New-Docfx {
+    param([object[]]$Groups)
+    $entries = ($Groups | ForEach-Object {
+        $files = ($_.Files | ForEach-Object { "`"$_`"" }) -join ', '
+        "{ `"src`": [{ `"src`": `"../`", `"files`": [$files] }], `"dest`": `"$($_.Dest)`" }"
+    }) -join ",`n    "
+    return @"
+{
+  "metadata": [
+    $entries
+  ],
+  "build": {
+    "content": [{ "files": ["*.md"], "exclude": ["api/namespaces/**", "api/types/**"] }],
+    "overwrite": [
+      { "files": ["api/namespaces/**/*.md"] },
+      { "files": ["api/types/**/*.md"] }
+    ],
+    "dest": "_site"
+  }
+}
+"@
+}
+
+$failures = 0
+function Run-Scenario {
+    param([string]$Name, [scriptblock]$Body)
+    $ws = New-Workspace
+    try {
+        & $Body $ws
+        Write-Host "[PASS] $Name"
+    } catch {
+        $script:failures++
+        Write-Host "[FAIL] $Name :: $($_.Exception.Message)"
+    } finally {
+        if (Test-Path $ws) { Remove-Item $ws -Recurse -Force -ErrorAction SilentlyContinue }
+    }
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Dry-run selects one clean project per metadata group; seed reproduces' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Core/Acme.Core.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Net/Acme.Net.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Core/Core.cs') "namespace Acme.Core`n{`n    public sealed class Widget { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws 'src/Net/Net.cs') "namespace Acme.Net`n{`n    public sealed class Client { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(
+        @{ Dest = 'api/core'; Files = @('src/Core/Acme.Core.csproj') },
+        @{ Dest = 'api/net';  Files = @('src/Net/Acme.Net.csproj') }))
+    Initialize-GitRepo $ws
+
+    $r1 = Invoke-Validator $ws @('--dry-run', '--seed', '7')
+    if ($r1.summary.runMode -ne 'dry-run') { throw "runMode=$($r1.summary.runMode)" }
+    if ($r1.summary.seed -ne 7) { throw "seed=$($r1.summary.seed)" }
+    if ($r1.summary.scopeState -ne 'provisional') { throw "scopeState=$($r1.summary.scopeState)" }
+    if ($r1.scope.metadataGroups.Count -ne 2) { throw "groups=$($r1.scope.metadataGroups.Count)" }
+    foreach ($g in $r1.scope.metadataGroups) {
+        if (-not $g.selectedProject) { throw "group $($g.id) had no selection" }
+    }
+    Assert-Diagnostic -Report $r1 -Code 'BUILD_BACKED_SCOPE_REQUIRED' -Where 'warnings'
+    if ($r1.summary.completionState -notlike 'dry-run-*') { throw "completion=$($r1.summary.completionState)" }
+    if ($r1.summary.canClaimCompletion) { throw 'dry-run must not claim completion' }
+
+    $r2 = Invoke-Validator $ws @('--dry-run', '--seed', '7')
+    $s1 = ($r1.scope.selectedProjects | Sort-Object) -join '|'
+    $s2 = ($r2.scope.selectedProjects | Sort-Object) -join '|'
+    if ($s1 -ne $s2) { throw "seed not reproducible: '$s1' vs '$s2'" }
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Explicit hint scopes validation and never claims repo completion' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Core/Acme.Core.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Net/Acme.Net.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Core/Core.cs') "namespace Acme.Core`n{`n    public sealed class Widget { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws 'src/Net/Net.cs') "namespace Acme.Net`n{`n    public sealed class Client { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(
+        @{ Dest = 'api/core'; Files = @('src/Core/Acme.Core.csproj') },
+        @{ Dest = 'api/net';  Files = @('src/Net/Acme.Net.csproj') }))
+    Initialize-GitRepo $ws
+
+    $r = Invoke-Validator $ws @('--project', 'Acme.Core')
+    if ($r.summary.runMode -ne 'scoped') { throw "runMode=$($r.summary.runMode)" }
+    if ($r.summary.canClaimCompletion) { throw 'scoped run must not claim completion' }
+    # Only the Acme.Core namespace should be in scope: Acme.Net diagnostics must be absent.
+    $netErrors = @($r.errors | Where-Object { $_.PSObject.Properties['namespace'] -and $_.namespace -eq 'Acme.Net' })
+    if ($netErrors.Count -gt 0) { throw "out-of-scope Acme.Net diagnostics leaked: $($netErrors.Count)" }
+    $coreErrors = @($r.errors | Where-Object { $_.PSObject.Properties['namespace'] -and $_.namespace -eq 'Acme.Core' })
+    if ($coreErrors.Count -eq 0) { throw 'expected in-scope Acme.Core diagnostics' }
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Unknown and ambiguous project hints fail before editing' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/A/Dup.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/B/Dup.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/A/A.cs') "namespace Dup.A`n{`n    public sealed class One { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws 'src/B/B.cs') "namespace Dup.B`n{`n    public sealed class Two { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(
+        @{ Dest = 'api'; Files = @('src/A/Dup.csproj', 'src/B/Dup.csproj') }))
+    Initialize-GitRepo $ws
+
+    $notFound = Invoke-Validator $ws @('--project', 'DoesNotExist')
+    Assert-Diagnostic -Report $notFound -Code 'PROJECT_HINT_NOT_FOUND'
+
+    $ambiguous = Invoke-Validator $ws @('--project', 'Dup')
+    Assert-Diagnostic -Report $ambiguous -Code 'PROJECT_HINT_AMBIGUOUS'
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Dry-run skips dirty candidate, falls through to clean, and reports unselected group' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/P1/P1.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/P2/P2.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Q1/Q1.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/P1/P1.cs') "namespace Grp.P1`n{`n    public sealed class A { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws 'src/P2/P2.cs') "namespace Grp.P2`n{`n    public sealed class B { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws 'src/Q1/Q1.cs') "namespace Grp.Q1`n{`n    public sealed class C { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(
+        @{ Dest = 'api/grp'; Files = @('src/P1/P1.csproj', 'src/P2/P2.csproj') },
+        @{ Dest = 'api/q';   Files = @('src/Q1/Q1.csproj') }))
+    Initialize-GitRepo $ws
+
+    # Make P1 dirty (modify tracked file) and the entire Q group dirty.
+    [System.IO.File]::WriteAllText((Join-Path $ws 'src/P1/P1.cs'), "namespace Grp.P1`n{`n    public sealed class A { public int N { get; set; } public int M { get; set; } }`n}`n", $utf8NoBom)
+    [System.IO.File]::WriteAllText((Join-Path $ws 'src/Q1/Q1.cs'), "namespace Grp.Q1`n{`n    public sealed class C { public int N { get; set; } public int M { get; set; } }`n}`n", $utf8NoBom)
+
+    $r = Invoke-Validator $ws @('--dry-run', '--seed', '3')
+    $grp = $r.scope.metadataGroups | Where-Object id -eq 'api/grp'
+    if (-not $grp.selectedProject) { throw 'grp group should select the clean P2' }
+    if ($grp.selectedProject -notlike '*P2*') { throw "grp selected dirty project: $($grp.selectedProject)" }
+    Assert-Diagnostic -Report $r -Code 'DRY_RUN_GROUP_UNSELECTED' -Where 'warnings'
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Valid family exemption removes covered siblings; invalid variants are rejected' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Fam/Fam.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Fam/Fam.cs') @'
+namespace Fam.Tuples
+{
+    public sealed class MutableTuple { public int N { get; set; } }
+    public sealed class MutableTupleTwo { public int N { get; set; } }
+    public sealed class MutableTupleThree { public int N { get; set; } }
+    public sealed class Unrelated { public int N { get; set; } }
+}
+'@
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Fam/Fam.csproj') }))
+
+    # Namespace page that names the anchor and explains selection.
+    Write-Utf8File (Join-Path $ws '.docfx/api/namespaces/Fam.Tuples.md') @'
+---
+uid: Fam.Tuples
+summary: *content
+---
+Use `MutableTuple` when you need a small mutable carrier for positional values. Choose the member by arity: the anchor demonstrates the shared workflow and the higher-arity siblings differ only by how many values they carry.
+
+Availability: `Fam.Tuples`
+'@
+    # Anchor has a real example.
+    Write-Utf8File (Join-Path $ws '.docfx/api/types/Fam.Tuples.MutableTuple.md') @'
+---
+uid: Fam.Tuples.MutableTuple
+example: *content
+---
+```csharp
+namespace Samples;
+
+using Fam.Tuples;
+
+public static class TupleUsage
+{
+    public static MutableTuple Build()
+    {
+        var t = new MutableTuple { N = 1 };
+        return t;
+    }
+}
+```
+'@
+    # Unrelated still needs an example.
+    Write-Utf8File (Join-Path $ws '.docfx/family-exemptions.json') @'
+{
+  "families": [
+    {
+      "familyId": "tuple-arity",
+      "namespaceUid": "Fam.Tuples",
+      "anchorUid": "Fam.Tuples.MutableTuple",
+      "rationale": "generic-arity",
+      "coveredUids": ["Fam.Tuples.MutableTupleTwo", "Fam.Tuples.MutableTupleThree"]
+    }
+  ]
+}
+'@
+    Initialize-GitRepo $ws
+
+    $r = Invoke-Validator $ws
+    $fam = $r.scope.familyExemptions | Where-Object familyId -eq 'tuple-arity'
+    if (-not $fam) { throw 'family not reported' }
+    if (-not $fam.valid) { throw 'family should be valid' }
+    # Covered siblings must NOT be required examples anymore.
+    $coveredMissing = @($r.errors | Where-Object { $_.code -eq 'EXAMPLE_MISSING' -and ($_.message -match 'MutableTupleTwo' -or $_.message -match 'MutableTupleThree') })
+    if ($coveredMissing.Count -gt 0) { throw 'covered siblings were still required' }
+    Assert-NoDiagnostic -Report $r -Code 'FAMILY_EXEMPTION_INVALID'
+
+    # Invalid: covers a type outside the namespace / unrelated.
+    Write-Utf8File (Join-Path $ws '.docfx/family-exemptions.json') @'
+{
+  "families": [
+    {
+      "familyId": "bad",
+      "namespaceUid": "Fam.Tuples",
+      "anchorUid": "Fam.Tuples.MutableTuple",
+      "rationale": "generic-arity",
+      "coveredUids": ["Fam.Tuples.DoesNotExist"]
+    }
+  ]
+}
+'@
+    $bad = Invoke-Validator $ws
+    Assert-Diagnostic -Report $bad -Code 'FAMILY_EXEMPTION_INVALID'
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Family without anchor example or namespace guidance is flagged' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Fam/Fam.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Fam/Fam.cs') @'
+namespace Fam.Tuples
+{
+    public sealed class MutableTuple { public int N { get; set; } }
+    public sealed class MutableTupleTwo { public int N { get; set; } }
+}
+'@
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Fam/Fam.csproj') }))
+    # Weak namespace page that neither names the anchor nor explains selection.
+    Write-Utf8File (Join-Path $ws '.docfx/api/namespaces/Fam.Tuples.md') @'
+---
+uid: Fam.Tuples
+summary: *content
+---
+This area is available for general use across the package and helps applications get work done.
+
+Availability: `Fam.Tuples`
+'@
+    Write-Utf8File (Join-Path $ws '.docfx/family-exemptions.json') @'
+{
+  "families": [
+    {
+      "familyId": "tuple-arity",
+      "namespaceUid": "Fam.Tuples",
+      "anchorUid": "Fam.Tuples.MutableTuple",
+      "rationale": "generic-arity",
+      "coveredUids": ["Fam.Tuples.MutableTupleTwo"]
+    }
+  ]
+}
+'@
+    Initialize-GitRepo $ws
+    $r = Invoke-Validator $ws
+    Assert-Diagnostic -Report $r -Code 'FAMILY_ANCHOR_EXAMPLE_MISSING'
+    Assert-Diagnostic -Report $r -Code 'FAMILY_NAMESPACE_GUIDANCE_MISSING'
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Quality-risk thresholds trigger a pilot-review warning' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Risk/Risk.csproj') $csproj
+    $types = (1..6 | ForEach-Object { "    public sealed class T$_ { public int N { get; set; } }" }) -join "`n"
+    Write-Utf8File (Join-Path $ws 'src/Risk/Risk.cs') "namespace Risk.Surface`n{`n$types`n}`n"
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Risk/Risk.csproj') }))
+    Initialize-GitRepo $ws
+
+    $r = Invoke-Validator $ws @('--dry-run', '--seed', '1', '--risk-standalone-threshold', '3')
+    Assert-Diagnostic -Report $r -Code 'QUALITY_RISK_REVIEW_REQUIRED' -Where 'warnings'
+    if (-not $r.qualityRisk.highRisk) { throw 'qualityRisk.highRisk should be true' }
+    if ($r.qualityRisk.standaloneTargets -lt 6) { throw "standaloneTargets=$($r.qualityRisk.standaloneTargets)" }
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Duplicate type names across assemblies and ambiguous extension owners are flagged' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/One/One.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Two/Two.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/One/One.cs') @'
+namespace Pkg.One
+{
+    public sealed class Result { public int N { get; set; } }
+
+    public static class Helpers
+    {
+        public static string Describe(this string value) => value.Trim();
+    }
+}
+'@
+    Write-Utf8File (Join-Path $ws 'src/Two/Two.cs') @'
+namespace Pkg.Two
+{
+    public sealed class Result { public int N { get; set; } }
+
+    public static class Helpers
+    {
+        public static string Summarize(this string value) => value.ToUpperInvariant();
+    }
+}
+'@
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(
+        @{ Dest = 'api/one'; Files = @('src/One/One.csproj') },
+        @{ Dest = 'api/two'; Files = @('src/Two/Two.csproj') }))
+    Initialize-GitRepo $ws
+
+    $r = Invoke-Validator $ws
+    Assert-Diagnostic -Report $r -Code 'SYMBOL_COLLISION_UNRESOLVED' -Where 'warnings'
+    Assert-Diagnostic -Report $r -Code 'EXTENSION_OWNER_AMBIGUOUS' -Where 'warnings'
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Unresolved type forwarding is flagged' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Fwd/Fwd.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Fwd/Fwd.cs') @'
+using System.Runtime.CompilerServices;
+
+[assembly: TypeForwardedTo(typeof(SomeMovedType))]
+
+namespace Fwd.Surface
+{
+    public sealed class Local { public int N { get; set; } }
+}
+
+public sealed class SomeMovedType { }
+'@
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Fwd/Fwd.csproj') }))
+    Initialize-GitRepo $ws
+
+    $r = Invoke-Validator $ws
+    Assert-Diagnostic -Report $r -Code 'TYPE_FORWARDING_UNRESOLVED' -Where 'warnings'
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Project manifest is written deterministically with packets' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Core/Acme.Core.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Core/Core.cs') "namespace Acme.Core`n{`n    public sealed class Widget { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Core/Acme.Core.csproj') }))
+    Initialize-GitRepo $ws
+
+    $manifest = Join-Path $ws 'manifest.json'
+    $r = Invoke-Validator $ws @('--project-manifest', $manifest)
+    if (-not (Test-Path $manifest)) { throw 'manifest not written' }
+    $m = [System.IO.File]::ReadAllText($manifest) | ConvertFrom-Json
+    if ($m.schemaVersion -ne 2) { throw "schemaVersion=$($m.schemaVersion)" }
+    if ($m.packets.Count -lt 1) { throw 'manifest has no packets' }
+    if (-not ($m.packets[0].namespaces -contains 'Acme.Core')) { throw 'packet missing Acme.Core namespace' }
+    $review = Join-Path $ws 'manifest.review.json'
+    if (-not (Test-Path $review)) { throw 'review-report template not written' }
+    $reviewTemplate = [System.IO.File]::ReadAllText($review) | ConvertFrom-Json
+    if (-not @($reviewTemplate.pages | Where-Object path -eq '.docfx/api/namespaces/Acme.Core.md')) { throw 'review template missing namespace page' }
+    if (-not @($reviewTemplate.pages | Where-Object path -eq '.docfx/api/types/Acme.Core.Widget.md')) { throw 'review template missing type page' }
+    # No BOM.
+    $bytes = [System.IO.File]::ReadAllBytes($manifest)
+    if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) { throw 'manifest must be BOM-less' }
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Dry-run manifest resumes authored files through every scoped completion gate' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Core/Acme.Core.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Core/Core.cs') @'
+namespace Acme.Core
+{
+    public sealed class Widget
+    {
+        public int Capacity { get; set; }
+    }
+}
+'@
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Core/Acme.Core.csproj') }))
+    Initialize-GitRepo $ws
+
+    $manifest = Join-Path $ws '.docfx/dry-run-manifest.json'
+    $initial = Invoke-Validator $ws @('--dry-run', '--seed', '17', '--build-api-model', '--project-manifest', $manifest)
+    if (-not (Test-Path $manifest)) { throw 'initial dry-run manifest was not written' }
+    if ($initial.scope.selectedProjects.Count -ne 1) { throw "selected=$($initial.scope.selectedProjects.Count)" }
+    if (-not $initial.scope.resumeCommand) { throw 'resume command was not reported' }
+
+    Write-Utf8File (Join-Path $ws '.docfx/api/namespaces/Acme.Core.md') @'
+---
+uid: Acme.Core
+summary: *content
+---
+Use this namespace to configure small work units with an explicit capacity that callers can inspect before dispatch. `Widget` is the concrete entry point when the capacity belongs to one operation rather than shared application state.
+
+Availability: `Acme.Core`
+'@
+    Write-Utf8File (Join-Path $ws '.docfx/api/types/Acme.Core.Widget.md') @'
+---
+uid: Acme.Core.Widget
+example: *content
+---
+The example creates a bounded work unit and returns the configured capacity so the observable result can feed admission or batching logic.
+
+```csharp
+namespace Samples;
+
+using System;
+using Acme.Core;
+
+public static class WidgetCapacity
+{
+    public static int ConfigureForBatch(int itemCount)
+    {
+        var widget = new Widget { Capacity = Math.Max(1, itemCount) };
+        return widget.Capacity;
+    }
+}
+```
+'@
+
+    $missingReview = Invoke-Validator $ws @('--resume-project-manifest', $manifest)
+    Assert-Diagnostic -Report $missingReview -Code 'REVIEW_REPORT_MISSING'
+
+    $review = Join-Path $ws '.docfx/dry-run-manifest.review.json'
+    $reviewData = [System.IO.File]::ReadAllText($review) | ConvertFrom-Json
+    foreach ($page in $reviewData.pages) {
+        $page.evidence = if ($page.path -like '*namespaces*') { 'src/Core/Core.cs and README.md' } else { 'src/Core/Core.cs public Widget API' }
+        $page.purpose = if ($page.path -like '*namespaces*') { 'Explains when bounded work-unit capacity belongs to one operation.' } else { 'Shows callers how to configure a bounded work unit before dispatch.' }
+        $page.observableOutcome = if ($page.path -like '*namespaces*') { 'namespace guidance' } else { 'Returns the effective capacity used by batching logic.' }
+        $page.patternComparison = 'Compared with every page in this one-packet pilot; wording and code are specific to Widget capacity.'
+    }
+    [System.IO.File]::WriteAllText($review, ($reviewData | ConvertTo-Json -Depth 10), $utf8NoBom)
+
+    $final = Invoke-Validator $ws @(
+        '--resume-project-manifest', $manifest,
+        '--review-report', $review,
+        '--build-api-model',
+        '--validate-samples',
+        '--verify-docfx-build')
+
+    if ($final.summary.runMode -ne 'dry-run') { throw "runMode=$($final.summary.runMode)" }
+    if ($final.summary.completionState -ne 'dry-run-passed') {
+        $codes = (@($final.errors | ForEach-Object code) -join ',')
+        $gates = (@($final.summary.remainingGates) -join ',')
+        throw "completion=$($final.summary.completionState); errors=$codes; gates=$gates"
+    }
+    if ($final.summary.samplesCompiled -ne 1) { throw "samplesCompiled=$($final.summary.samplesCompiled)" }
+    if ($final.summary.docfxBuildsVerified -ne 1) { throw "docfxBuildsVerified=$($final.summary.docfxBuildsVerified)" }
+    if ($final.scope.selectedProjects.Count -ne 1) { throw 'resumed packet was not selected' }
+    Assert-NoDiagnostic -Report $final -Code 'PROJECT_DIRTY_SKIPPED'
+    Assert-NoDiagnostic -Report $final -Code 'PROJECT_MANIFEST_DIRTY_CONFLICT'
+    Assert-NoDiagnostic -Report $final -Code 'REVIEW_REPORT_INCOMPLETE'
+    Assert-NoDiagnostic -Report $final -Code 'EXAMPLE_MISSING'
+    Assert-NoDiagnostic -Report $final -Code 'SAMPLE_COMPILE_FAILED'
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Invalid resume manifest fails closed without selecting the full repository' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Core/Acme.Core.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Core/Core.cs') "namespace Acme.Core; public sealed class Widget { public int N { get; set; } }"
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Core/Acme.Core.csproj') }))
+    Initialize-GitRepo $ws
+
+    $r = Invoke-Validator $ws @('--resume-project-manifest', (Join-Path $ws 'missing.json'))
+    Assert-Diagnostic -Report $r -Code 'PROJECT_MANIFEST_INVALID'
+    if ($r.scope.selectedProjects.Count -ne 0) { throw 'invalid manifest broadened into selected projects' }
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Safe overwrite writer preserves encoding and refuses dirty/duplicate/unbalanced writes' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Core/Acme.Core.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Core/Core.cs') "namespace Acme.Core`n{`n    public sealed class Widget { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Core/Acme.Core.csproj') }))
+    Initialize-GitRepo $ws
+
+    # Write a new overwrite section (LF preserved).
+    $req = Join-Path $ws 'req.json'
+    $target = '.docfx/api/types/Acme.Core.Widget.md'
+    $fence = @'
+```csharp
+var w = new Acme.Core.Widget { N = 1 };
+```
+'@
+    $reqObj = @{ file = $target; uid = 'Acme.Core.Widget'; mapping = 'example'; prose = 'Build a widget.'; fence = $fence }
+    [System.IO.File]::WriteAllText($req, ($reqObj | ConvertTo-Json -Depth 5), $utf8NoBom)
+    $out = & dotnet run --file $ValidatorPath -- --repo-root $ws --write-overwrite $req --json 2>$null | Out-String | ForEach-Object { ConvertFrom-ValidatorJson $_ }
+    if ($out.status -ne 'passed') { throw "writer status=$($out.status)" }
+    $written = Join-Path $ws $target
+    if (-not (Test-Path $written)) { throw 'overwrite file not written' }
+    $content = [System.IO.File]::ReadAllText($written)
+    if ($content -notmatch 'uid: Acme.Core.Widget') { throw 'uid missing' }
+    if ($content -match "`r`n") { throw 'LF was not preserved (found CRLF)' }
+    $bytes = [System.IO.File]::ReadAllBytes($written)
+    if ($bytes[0] -eq 0xEF) { throw 'BOM-less file gained a BOM' }
+
+    # Commit the new file so it is clean, then a duplicate UID write is refused.
+    Push-Location $ws
+    try {
+        & git -c user.email=t@e.com -c user.name=t add -A 2>$null | Out-Null
+        & git -c user.email=t@e.com -c user.name=t commit -q -m overwrite 2>$null | Out-Null
+    } finally { Pop-Location }
+
+    $dup = & dotnet run --file $ValidatorPath -- --repo-root $ws --write-overwrite $req --json 2>$null | Out-String | ForEach-Object { ConvertFrom-ValidatorJson $_ }
+    if (-not @($dup.errors | Where-Object code -eq 'OVERWRITE_UID_DUPLICATE')) { throw 'duplicate UID was not refused' }
+
+    # Unbalanced fence is refused (new file).
+    $badReq = Join-Path $ws 'bad.json'
+    $badFence = @'
+```csharp
+var x = 1;
+'@
+    $badObj = @{ file = '.docfx/api/types/Acme.Core.Other.md'; uid = 'Acme.Core.Other'; mapping = 'example'; fence = $badFence }
+    [System.IO.File]::WriteAllText($badReq, ($badObj | ConvertTo-Json -Depth 5), $utf8NoBom)
+    $bad = & dotnet run --file $ValidatorPath -- --repo-root $ws --write-overwrite $badReq --json 2>$null | Out-String | ForEach-Object { ConvertFrom-ValidatorJson $_ }
+    if (-not @($bad.errors | Where-Object code -eq 'OVERWRITE_FENCE_UNBALANCED')) { throw 'unbalanced fence was not refused' }
+
+    # Dirty-path refusal: modify the committed target then attempt a different UID write to it.
+    [System.IO.File]::AppendAllText($written, "`n<!-- edit -->`n", $utf8NoBom)
+    $req2 = Join-Path $ws 'req2.json'
+    $req2Fence = @'
+```csharp
+var y = 2;
+```
+'@
+    $req2Obj = @{ file = $target; uid = 'Acme.Core.Widget2'; mapping = 'example'; fence = $req2Fence }
+    [System.IO.File]::WriteAllText($req2, ($req2Obj | ConvertTo-Json -Depth 5), $utf8NoBom)
+    $dirty = & dotnet run --file $ValidatorPath -- --repo-root $ws --write-overwrite $req2 --json 2>$null | Out-String | ForEach-Object { ConvertFrom-ValidatorJson $_ }
+    if (-not @($dirty.errors | Where-Object code -eq 'OVERWRITE_DIRTY_REFUSED')) { throw 'dirty path was not refused' }
+}
+
+# ----------------------------------------------------------------------
+Run-Scenario 'Single JSON document on stdout while heartbeats stay on stderr' {
+    param($ws)
+    Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
+    Write-Utf8File (Join-Path $ws 'src/Core/Acme.Core.csproj') $csproj
+    Write-Utf8File (Join-Path $ws 'src/Core/Core.cs') "namespace Acme.Core`n{`n    public sealed class Widget { public int N { get; set; } }`n}`n"
+    Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Core/Acme.Core.csproj') }))
+    Initialize-GitRepo $ws
+
+    # Invoke-ValidatorRaw discards stderr (2>$null); the returned text must therefore be the single
+    # clean JSON document, proving heartbeats stay off stdout.
+    $stdout = Invoke-ValidatorRaw @('--repo-root', $ws, '--json')
+    if ($stdout.TrimStart().Length -eq 0 -or $stdout.TrimStart()[0] -ne '{') {
+        throw "stdout is not a clean single JSON document (starts with '$($stdout.TrimStart().Substring(0, [Math]::Min(40, $stdout.TrimStart().Length)))')"
+    }
+    $parsed = $stdout | ConvertFrom-Json
+    if (-not $parsed.summary) { throw 'stdout did not parse as a single JSON report' }
+}
+
+if ($failures -gt 0) {
+    throw "$failures project-scoped scenario(s) failed."
+}
+
+Write-Host 'DocFX project-scoped regression passed.'
+exit 0
diff --git a/skills/dotnet-docfx-digest/scripts/test-quality.ps1 b/skills/dotnet-docfx-digest/scripts/test-quality.ps1
index cda5771..8367a15 100644
--- a/skills/dotnet-docfx-digest/scripts/test-quality.ps1
+++ b/skills/dotnet-docfx-digest/scripts/test-quality.ps1
@@ -4,6 +4,10 @@ param(
 
 $ErrorActionPreference = 'Stop'
 Set-StrictMode -Version Latest
+# The validator exits non-zero for fixtures that contain diagnostics and writes append-only packet
+# heartbeats to stderr; opt out of native-command error promotion so neither is treated as a
+# terminating error when this script is invoked from validate-skill-templates.ps1.
+$PSNativeCommandUseErrorActionPreference = $false
 
 $utf8NoBom = [System.Text.UTF8Encoding]::new($false)
 $workspace = Join-Path ([System.IO.Path]::GetTempPath()) ('dotnet-docfx-quality-' + [guid]::NewGuid().ToString('N'))
@@ -20,12 +24,28 @@ function Write-Utf8File {
 }
 
 function Invoke-Validator {
-    $output = & dotnet run --file $ValidatorPath -- --repo-root $workspace --json 2>$null
-    if ([string]::IsNullOrWhiteSpace(($output -join "`n"))) {
+    param([string]$Workspace = $workspace)
+
+    # Run the native validator with ErrorActionPreference relaxed so its non-zero exit and stderr
+    # packet heartbeats are never promoted to a terminating PowerShell error (explicit `throw`
+    # statements below still halt the test). This keeps behavior identical whether the script is run
+    # directly or invoked from validate-skill-templates.ps1, which sets [Console]::OutputEncoding.
+    $prev = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+        $output = & dotnet run --file $ValidatorPath -- --repo-root $Workspace --json 2>$null
+    } finally {
+        $ErrorActionPreference = $prev
+    }
+
+    $text = ($output -join "`n")
+    if ([string]::IsNullOrWhiteSpace($text)) {
         throw 'DocFX validator returned no JSON output.'
     }
 
-    return (($output -join "`n") | ConvertFrom-Json)
+    $start = $text.IndexOf('{')
+    if ($start -lt 0) { throw "DocFX validator returned no JSON document. Output: $text" }
+    return ($text.Substring($start) | ConvertFrom-Json)
 }
 
 function Assert-Diagnostic {
@@ -36,6 +56,42 @@ function Assert-Diagnostic {
     }
 }
 
+function Assert-NoDiagnostic {
+    param([object]$Report, [string]$Code)
+
+    if (@($Report.errors | Where-Object code -eq $Code)) {
+        throw "Diagnostic '$Code' was reported but the fixture expected it to be absent."
+    }
+}
+
+function New-DocfxJson {
+    param([string[]]$ProjectFiles)
+
+    $files = ($ProjectFiles | ForEach-Object { "`"$_`"" }) -join ', '
+    return @"
+{
+  "metadata": [{
+    "src": [{ "src": "../", "files": [$files] }],
+    "dest": "api",
+    "properties": { "TargetFramework": "net10.0" }
+  }],
+  "build": {
+    "content": [{ "files": ["*.md"], "exclude": ["api/namespaces/**", "api/types/**"] }],
+    "overwrite": [{ "files": ["api/namespaces/**/*.md", "api/types/**/*.md"] }],
+    "dest": "_site"
+  }
+}
+"@
+}
+
+$projectCsproj = @'
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+  </PropertyGroup>
+</Project>
+'@
+
 try {
     $arrow = "$([char]0x2B07)$([char]0xFE0F)"
     Write-Utf8File (Join-Path $workspace 'AGENTS.md') @'
@@ -228,3 +284,351 @@ public static class IdentifierInput
         Remove-Item -Path $workspace -Recurse -Force
     }
 }
+
+# ----------------------------------------------------------------------
+# Scenario: source discovery for Cuemon-style next-line namespace braces.
+# A block namespace whose opening brace is on the following line must not
+# hide its public types. Before the scanner fix the validator discovered
+# ~0 targets here; the fixture fails if discovery collapses to one target.
+# ----------------------------------------------------------------------
+$discovery = Join-Path ([System.IO.Path]::GetTempPath()) ('dotnet-docfx-discovery-' + [guid]::NewGuid().ToString('N'))
+try {
+    Write-Utf8File (Join-Path $discovery 'AGENTS.md') @'
+<!-- dotnet-docfx-digest:start -->
+Managed DocFX guidance.
+<!-- dotnet-docfx-digest:end -->
+'@
+    Write-Utf8File (Join-Path $discovery 'src/Acme.Widgets.csproj') $projectCsproj
+    Write-Utf8File (Join-Path $discovery 'src/Widgets.cs') @'
+namespace Acme.Widgets
+{
+    public sealed class Gadget
+    {
+        public int Size { get; set; }
+    }
+
+    public sealed class Sprocket
+    {
+        public int Teeth { get; set; }
+    }
+
+    public sealed class Cog
+    {
+        public int Radius { get; set; }
+    }
+
+    public static class WidgetExtensions
+    {
+        public static string Describe(this Gadget gadget) => gadget.Size.ToString();
+    }
+}
+'@
+    Write-Utf8File (Join-Path $discovery '.docfx/docfx.json') (New-DocfxJson -ProjectFiles @('src/Acme.Widgets.csproj'))
+
+    $discoveryReport = Invoke-Validator -Workspace $discovery
+    if ([int]$discoveryReport.summary.requiredExampleTargets -lt 4) {
+        throw "Next-line namespace brace discovery under-reported targets: expected >= 4, got $($discoveryReport.summary.requiredExampleTargets)."
+    }
+    if (-not @($discoveryReport.errors | Where-Object { $_.code -eq 'EXAMPLE_MISSING' -and $_.namespace -eq 'Acme.Widgets' })) {
+        throw 'Discovery fixture did not surface Acme.Widgets targets through the source scanner.'
+    }
+
+    Write-Host 'DocFX next-line namespace discovery passed.'
+} finally {
+    if (Test-Path $discovery) {
+        Remove-Item -Path $discovery -Recurse -Force
+    }
+}
+
+# ----------------------------------------------------------------------
+# Scenario: known-bad example quality patterns observed in the Cuemon run.
+# Each anti-pattern must raise its dedicated diagnostic.
+# ----------------------------------------------------------------------
+$quality = Join-Path ([System.IO.Path]::GetTempPath()) ('dotnet-docfx-examples-' + [guid]::NewGuid().ToString('N'))
+try {
+    Write-Utf8File (Join-Path $quality 'AGENTS.md') @'
+<!-- dotnet-docfx-digest:start -->
+Managed DocFX guidance.
+<!-- dotnet-docfx-digest:end -->
+'@
+    Write-Utf8File (Join-Path $quality 'src/Acme.Demo.csproj') $projectCsproj
+    Write-Utf8File (Join-Path $quality 'src/Demo.cs') @'
+namespace Acme.Demo;
+
+public sealed class Holder { public int Value { get; set; } }
+public sealed class Outcome { public int Value { get; set; } }
+public sealed class Forwarder { public int Value { get; set; } }
+public sealed class RepA { public int Value { get; set; } }
+public sealed class RepB { public int Value { get; set; } }
+public sealed class RepC { public int Value { get; set; } }
+'@
+    Write-Utf8File (Join-Path $quality '.docfx/docfx.json') (New-DocfxJson -ProjectFiles @('src/Acme.Demo.csproj'))
+
+    # Weak inventory lead left intact with appended start-here guidance.
+    Write-Utf8File (Join-Path $quality '.docfx/api/namespaces/Acme.Demo.md') @'
+---
+uid: Acme.Demo
+summary: *content
+---
+The Acme.Demo namespace contains types and helpers that enable common demo work across the package.
+
+Start with `Holder` to keep state together; reach for `Forwarder` when callers need pass-through access.
+
+Availability: `Acme.Demo`
+'@
+
+    # default! holder property.
+    Write-Utf8File (Join-Path $quality '.docfx/api/types/Acme.Demo.Holder.md') @'
+---
+uid: Acme.Demo.Holder
+example: *content
+---
+```csharp
+namespace Samples;
+
+using Acme.Demo;
+
+public static class HolderState
+{
+    public static Holder Current { get; } = default!;
+}
+```
+'@
+
+    # Construction with no observable next action.
+    Write-Utf8File (Join-Path $quality '.docfx/api/types/Acme.Demo.Outcome.md') @'
+---
+uid: Acme.Demo.Outcome
+example: *content
+---
+```csharp
+namespace Samples;
+
+using Acme.Demo;
+
+public static class UseOutcome
+{
+    public static Outcome Build()
+    {
+        var result = new Outcome();
+        return result;
+    }
+}
+```
+'@
+
+    # Mass forwarding shell.
+    Write-Utf8File (Join-Path $quality '.docfx/api/types/Acme.Demo.Forwarder.md') @'
+---
+uid: Acme.Demo.Forwarder
+example: *content
+---
+```csharp
+namespace Samples;
+
+using Acme.Demo;
+
+public static class ForwarderFacade
+{
+    public static int Read(Forwarder source) => source.Read();
+    public static int Peek(Forwarder source) => source.Peek();
+    public static int Count(Forwarder source) => source.Count();
+}
+```
+'@
+
+    # Three structurally identical examples differing only by identifiers.
+    foreach ($name in @('RepA', 'RepB', 'RepC')) {
+        Write-Utf8File (Join-Path $quality ".docfx/api/types/Acme.Demo.$name.md") @"
+---
+uid: Acme.Demo.$name
+example: *content
+---
+``````csharp
+namespace Samples;
+
+using Acme.Demo;
+
+public static class Use$name
+{
+    public static $name Create()
+    {
+        var item = new $name();
+        item.Apply(1);
+        return item;
+    }
+}
+``````
+"@
+    }
+
+    $badQuality = Invoke-Validator -Workspace $quality
+    foreach ($code in @(
+        'EXAMPLE_DEFAULT_PLACEHOLDER',
+        'EXAMPLE_NO_OBSERVABLE_OUTCOME',
+        'EXAMPLE_FORWARDING_SCAFFOLD',
+        'EXAMPLE_TEMPLATE_REPETITION',
+        'NAMESPACE_APPEND_ONLY_REPAIR'
+    )) {
+        Assert-Diagnostic -Report $badQuality -Code $code
+    }
+
+    Write-Host 'DocFX example quality regression passed.'
+} finally {
+    if (Test-Path $quality) {
+        Remove-Item -Path $quality -Recurse -Force
+    }
+}
+
+# ----------------------------------------------------------------------
+# Scenario: mechanical namespace prose repeated across unrelated pages.
+# Three namespaces that share one normalized prose skeleton must fail. Two unrelated pages using
+# the distinctive "namespace helps you / Use it when / Start with" cadence must also fail even
+# when their domain vocabulary is otherwise different.
+# ----------------------------------------------------------------------
+$prose = Join-Path ([System.IO.Path]::GetTempPath()) ('dotnet-docfx-prose-' + [guid]::NewGuid().ToString('N'))
+try {
+    Write-Utf8File (Join-Path $prose 'AGENTS.md') @'
+<!-- dotnet-docfx-digest:start -->
+Managed DocFX guidance.
+<!-- dotnet-docfx-digest:end -->
+'@
+    Write-Utf8File (Join-Path $prose 'src/Acme.Families.csproj') $projectCsproj
+    Write-Utf8File (Join-Path $prose 'src/Families.cs') @'
+namespace Alpha
+{
+    public sealed class AlphaType { public int Value { get; set; } }
+}
+
+namespace Beta
+{
+    public sealed class BetaType { public int Value { get; set; } }
+}
+
+namespace Gamma
+{
+    public sealed class GammaType { public int Value { get; set; } }
+}
+'@
+    Write-Utf8File (Join-Path $prose '.docfx/docfx.json') (New-DocfxJson -ProjectFiles @('src/Acme.Families.csproj'))
+
+    foreach ($pair in @(@('Alpha', 'AlphaType'), @('Beta', 'BetaType'), @('Gamma', 'GammaType'))) {
+        $ns = $pair[0]
+        $type = $pair[1]
+        Write-Utf8File (Join-Path $prose ".docfx/api/namespaces/$ns.md") @"
+---
+uid: $ns
+summary: *content
+---
+Use ``$type`` when callers need a single entry point for the workflow. It keeps configuration explicit and easy to pass across boundaries.
+
+Availability: ``$ns``
+"@
+    }
+
+    $proseReport = Invoke-Validator -Workspace $prose
+    Assert-Diagnostic -Report $proseReport -Code 'NAMESPACE_PROSE_TEMPLATE_REPETITION'
+
+    # Replace the three exact skeletons with two lexically different pages that retain the same
+    # mechanical rhetorical frame. Gamma remains independently written and must not be required
+    # to trigger the diagnostic.
+    Write-Utf8File (Join-Path $prose '.docfx/api/namespaces/Alpha.md') @'
+---
+uid: Alpha
+summary: *content
+---
+The `Alpha` namespace helps you retry transient work without scattering recovery bookkeeping across call sites.
+
+Use it when a caller owns the retry decision and needs a bounded attempt count. If you are defining the recovery policy, begin with `AlphaType` to execute the protected operation.
+
+Availability: `Alpha`
+'@
+    Write-Utf8File (Join-Path $prose '.docfx/api/namespaces/Beta.md') @'
+---
+uid: Beta
+summary: *content
+---
+The `Beta` namespace helps you divide a large import into predictable processing windows.
+
+Use it when workers need bounded ranges instead of hand-maintained indexes. If you are dividing a new workload, start with `BetaType` to plan each assignment.
+
+Availability: `Beta`
+'@
+    Write-Utf8File (Join-Path $prose '.docfx/api/namespaces/Gamma.md') @'
+---
+uid: Gamma
+summary: *content
+---
+Choose `GammaType` when a boundary needs one explicit value that can be inspected before work begins. It keeps the decision local to the caller rather than hiding it in shared state.
+
+Availability: `Gamma`
+'@
+
+    $rhetoricalReport = Invoke-Validator -Workspace $prose
+    Assert-Diagnostic -Report $rhetoricalReport -Code 'NAMESPACE_PROSE_TEMPLATE_REPETITION'
+
+    Write-Utf8File (Join-Path $prose '.docfx/api/namespaces/Alpha.md') @'
+---
+uid: Alpha
+summary: *content
+---
+Use the `Alpha` namespace when operations can fail transiently and callers need bounded retries. The namespace separates recovery policy from the work itself.
+
+Start with `AlphaType` to define the attempt budget, then execute the protected operation. Choose this namespace when retry behavior belongs to application flow.
+
+Availability: `Alpha`
+'@
+    Write-Utf8File (Join-Path $prose '.docfx/api/namespaces/Beta.md') @'
+---
+uid: Beta
+summary: *content
+---
+Use the `Beta` namespace when imports need predictable windows instead of handwritten indexes. The namespace keeps range planning in one place.
+
+Start with `BetaType` to select the window size, then create each assignment. Choose this namespace when the caller controls batching directly.
+
+Availability: `Beta`
+'@
+
+    $imperativeReport = Invoke-Validator -Workspace $prose
+    Assert-Diagnostic -Report $imperativeReport -Code 'NAMESPACE_PROSE_TEMPLATE_REPETITION'
+
+    # Vary the lead paragraphs while retaining the repeated navigation paragraph that escaped
+    # the earlier signatures during the representative forward test.
+    Write-Utf8File (Join-Path $prose '.docfx/api/namespaces/Alpha.md') @'
+---
+uid: Alpha
+summary: *content
+---
+The `Alpha` namespace turns transient failures into bounded recovery attempts without spreading retry bookkeeping across call sites. Use it when application code owns the recovery decision.
+
+Start with `AlphaType` to choose the attempt budget, then pass that policy to the operation that performs the work.
+
+Availability: `Alpha`
+'@
+    Write-Utf8File (Join-Path $prose '.docfx/api/namespaces/Beta.md') @'
+---
+uid: Beta
+summary: *content
+---
+The `Beta` namespace divides large imports into predictable processing windows for workers and queues. It is useful when callers need bounded ranges instead of handwritten indexes.
+
+Start with `BetaType` to select the window size, then use the resulting assignments in the processing loop.
+
+Availability: `Beta`
+'@
+
+    $navigationReport = Invoke-Validator -Workspace $prose
+    Assert-Diagnostic -Report $navigationReport -Code 'NAMESPACE_PROSE_TEMPLATE_REPETITION'
+
+    Write-Host 'DocFX namespace prose repetition regression passed.'
+} finally {
+    if (Test-Path $prose) {
+        Remove-Item -Path $prose -Recurse -Force
+    }
+}
+
+# The validator returns a non-zero exit code for fixtures that intentionally contain
+# diagnostics. Success here is determined by the assertions above not throwing, so reset
+# the process exit code for callers (e.g. validate-skill-templates.ps1) that inspect it.
+exit 0

From 16128c061cc94df021f9f8acd2f72fe6600700ec Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 00:02:35 +0200
Subject: [PATCH 73/88] =?UTF-8?q?=F0=9F=93=9D=20update=20available=20skill?=
 =?UTF-8?q?s=20in=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refreshes the dotnet-docfx-digest skill entry to reflect comprehensive enhancements to documentation structure, implementation capabilities, and testing infrastructure.
---
 README.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 65b1be2..493a67a 100644
--- a/README.md
+++ b/README.md
@@ -545,12 +545,16 @@ API documentation rots the moment code changes. A new public type ships without
 - **DocFX overwrite grounding** — the skill includes a concise `references/docfx-overwrite-files.md` summary of the official overwrite-file and `docfx.json` rules agents need when creating namespace fly-ins, summaries, examples, remarks, and extension-member documentation,
 - **Verification without a build, precision on demand** — by default `scripts/docfx.cs` discovers public API, namespaces, and extension methods without compiling: it reads existing DocFX ManagedReference YAML under `metadata.dest` when present, otherwise runs a conservative source scan over the projects referenced by `docfx.json`, and warns (`API_MODEL_SOURCE_SCANNER_LIMITED`) that the precise path is opt-in. Adding `--build-api-model` (alias `--strict-api-discovery`) builds only the documented project graph through a single scoped `.slnx` graph build and discovers from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution,
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
-- **Decision-useful namespace checks** — uid front matter, availability, and `Extension Members` tables are validated against the actual public surface, while semantic gates reject inventory-only prose and require concrete when-to-use and start-here guidance with diagnostics such as `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING`,
+- **Decision-useful namespace checks** — uid front matter, availability, and `Extension Members` tables are validated against the actual public surface, while semantic gates reject inventory-only prose, weak inventory leads left intact beneath an appended start-here sentence, and mechanical prose templates shared across pages, requiring concrete when-to-use and start-here guidance with diagnostics such as `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
 - **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/types/`, legacy authored `.docfx/api/*.md` overwrite files move into `api/namespaces/` or `api/types/` instead of widening the glob to `api/**/*.md`, both overwrite trees stay excluded from `build.content`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, and agents must rerun the completion repair loop until diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
 - **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
 - **Examples that teach a real workflow** — examples start from package IDs and package-level evidence before falling back to type/member-only searches, prefer README, package docs, tooling, tuning, functional-test, and external GitHub usage when available, and may include multiple related public types when that is what makes the consumer scenario understandable,
-- **Semantic example quality gates** — compilation-valid filler no longer passes: the validator rejects duplicate UID mappings, `Type.GetType`/assembly metadata scaffolds, generic `DocumentedTypeExample`/`Describe()` templates, type examples that never use the target in code, and extension examples that mention a method only in prose instead of invoking it,
+- **Semantic example quality gates** — compilation-valid filler no longer passes: the validator rejects duplicate UID mappings, `Type.GetType`/assembly metadata scaffolds, generic `DocumentedTypeExample`/`Describe()` templates, type examples that never use the target in code, extension examples that mention a method only in prose instead of invoking it, `default!`/`null!` holder properties (`EXAMPLE_DEFAULT_PLACEHOLDER`), classes that only construct or return the target with no observable result (`EXAMPLE_NO_OBSERVABLE_OUTCOME`), mass-forwarding shells of one-line pass-throughs (`EXAMPLE_FORWARDING_SCAFFOLD`), and one normalized code skeleton reused across three or more unrelated targets (`EXAMPLE_TEMPLATE_REPETITION`),
+- **Correct source discovery** — the no-build source scanner correctly handles block namespaces whose opening brace is on the next line, so public types are no longer silently under-reported; when a declaration cannot be paired with its brace it warns (`API_MODEL_SOURCE_SCANNER_INCOMPLETE`) and points to a build-backed audit,
+- **Project-scoped packets and representative dry runs** — documentation is processed in bounded project packets grouped by DocFX `metadata[].dest`, with ownership of namespaces, targets, overwrite files, and git-dirty paths. `--dry-run --build-api-model --project-manifest <path>` selects one **clean** project per destination group and writes both the initial baseline and a sibling changed-page review template; after evidence-based authoring and page-by-page review, `--resume-project-manifest <path> --review-report <path> --build-api-model --validate-samples --verify-docfx-build` verifies the same packets without mistaking new files for pre-existing work. Missing evidence, purpose/outcome, observable-result, or sibling-pattern review entries block completion. Dry runs never edit previously dirty files, fail closed on invalid manifests, and report `dry-run-passed` only after every gate succeeds. `--write-overwrite` preserves BOM/line endings and refuses dirty or duplicate-UID writes,
+- **Build-backed scope and a quality-risk pilot** — authoring scope must be reflection-precise: a `source-scan` model is `provisional` and raises `BUILD_BACKED_SCOPE_REQUIRED` until `--build-api-model` (or DocFX YAML) confirms it. Before editing, a quality-risk gate counts standalone/extension targets, the missing-to-existing ratio, and unresolved symbol ownership; above the thresholds it raises `QUALITY_RISK_REVIEW_REQUIRED` and requires a bounded pilot (one packet or 20 targets) with explicit approval before a full run,
+- **Symbol-aware ownership and narrow family exemptions** — duplicate type names across assemblies (`SYMBOL_COLLISION_UNRESOLVED`), unresolved type forwarding (`TYPE_FORWARDING_UNRESOLVED`), and cross-assembly extension containers (`EXTENSION_OWNER_AMBIGUOUS`) are flagged with owning assembly/project; a heavily generic/inherited/overloaded/arity series can replace redundant per-type examples with one validated anchor example plus deep namespace guidance, declared explicitly in `.docfx/family-exemptions.json`,
 - **Examples that actually compile** — under the opt-in `--validate-samples` path, every `csharp`/`cs` documentation fence is compiled in its own isolated project; all sample projects are batched into one temporary `.slnx` graph build so shared dependencies restore and build once, `--sample-parallelism` bounds MSBuild concurrency, each sample references only the documented project(s) that own its namespace rather than every library project, and failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,
 - **Public API only** — internal and private members, and namespaces with no public API, are deliberately left undocumented,

From 201d91d6d41d427024408700c9e7cfebb7945678 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 15:39:48 +0200
Subject: [PATCH 74/88] =?UTF-8?q?=F0=9F=92=AC=20update=20repo=20documentat?=
 =?UTF-8?q?ion=20and=20guidelines?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refreshes AGENTS.md and README.md to reflect recent enhancements to the dotnet-docfx-digest skill documentation, contract structure, and implementation.
---
 AGENTS.md | 4 +++-
 README.md | 6 ++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 22e4f11..3c8f020 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -85,7 +85,9 @@ If you edit the `~/.agents/skills/<name>/` copy first, mirror it back to the rep
 
 When renaming a skill, update **all four** locations — the repo folder, the local Claude install folder, the local global agent install folder, and the local Gemini Antigravity install folder. The folder name and the `name:` field in the SKILL.md frontmatter must match. A mismatch causes the skill to disappear from tooling or show stale instructions.
 
-A sync mismatch means one side runs a stale version, which leads to confusing eval results and wasted iterations.
+A sync mismatch means one side runs a stale version, which leads to confusing eval results and wasted iterations.
+
+After the source copy passes its deterministic tests, SHA-256 identity across the repo and all three local installs is sufficient installation verification. Do not rerun the same deterministic suites from a hash-identical installed copy; that duplicates time, compute, and token use without adding evidence. Run an installed-copy test only when install-path resolution, loader behavior, permissions, or an actual hash mismatch is the subject of the test.
 
 After changing any repo-managed skill, sync the touched files across the repo copy, `~/.claude/skills/<name>/`, `~/.agents/skills/<name>/`, and `~/.gemini/antigravity/skills/<name>/` before considering the task done.
 
diff --git a/README.md b/README.md
index 493a67a..46279d7 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,8 @@ Repo-level agent guidance also keeps progress updates user-facing: agents should
 
 Completion gates are equally strict: if repository guidance, a loaded skill, or the conversation summary marks a script-backed step as pending, critical, or blocking, agents must treat it as an active checklist item and may not claim completion until that command has run or the exact external blocker has been reported. In the DocFX workflow, that means `scripts/agents.cs` and the build-backed `scripts/docfx.cs --build-api-model --validate-samples --verify-docfx-build` verification are completion gates, not optional cleanup after the documentation files look done. The validator now emits a deterministic completion contract: `summary.canClaimCompletion` must be `true`, `summary.remainingWorkItems` must be `0`, and both `summary.remainingGates` and `summary.remainingDiagnosticsByCode` must be empty. A clean fast run reports `verification-required`, not completion. Pre-existing gaps, large diagnostic counts, sample failures, and documentation-caused DocFX build failures remain repair work; they are not permission to stop after a partial digest. (The plain `scripts/docfx.cs` run is fast and build-free for iteration; the build-backed flags are what make the final gate authoritative.)
 
+Local skill synchronization is verified efficiently: run deterministic tests against the repository source, copy touched files to the three local installs, and compare SHA-256 hashes across all four locations. Hash-identical copies are the same executable content, so agents do not repeat the same suites from an installed path unless install-path or loader behavior is specifically under test.
+
 Resumed DocFX audits preserve every tracked and untracked documentation edit, regenerate the repair plan and example inventory, and process that queue in batches with a fast rerun after each batch. Encoding checks focus on actual damage: valid BOM-less UTF-8 is accepted, `ENCODING_BOM_MISSING` is not emitted, and audits do not create BOM-only or line-ending-only diffs.
 
 Final DocFX verification is machine-adaptive: `auto` selects a high-capacity profile above 8 available logical processors and 32 GiB available memory, overlaps isolated DocFX verification with API/sample work, and scales MSBuild workers up to half the available processors (capped at 16). Smaller machines stay conservative. Child-process timeout defaults to 30 minutes, and callers must allow at least 35 minutes so the validator can return its own timeout diagnostics. Long-running build, sample, and DocFX children also emit 10-second `stderr` heartbeats with phase, workload, runner count, PID, elapsed time, last-output age, and current output while keeping JSON stdout parseable.
@@ -552,8 +554,8 @@ API documentation rots the moment code changes. A new public type ships without
 - **Examples that teach a real workflow** — examples start from package IDs and package-level evidence before falling back to type/member-only searches, prefer README, package docs, tooling, tuning, functional-test, and external GitHub usage when available, and may include multiple related public types when that is what makes the consumer scenario understandable,
 - **Semantic example quality gates** — compilation-valid filler no longer passes: the validator rejects duplicate UID mappings, `Type.GetType`/assembly metadata scaffolds, generic `DocumentedTypeExample`/`Describe()` templates, type examples that never use the target in code, extension examples that mention a method only in prose instead of invoking it, `default!`/`null!` holder properties (`EXAMPLE_DEFAULT_PLACEHOLDER`), classes that only construct or return the target with no observable result (`EXAMPLE_NO_OBSERVABLE_OUTCOME`), mass-forwarding shells of one-line pass-throughs (`EXAMPLE_FORWARDING_SCAFFOLD`), and one normalized code skeleton reused across three or more unrelated targets (`EXAMPLE_TEMPLATE_REPETITION`),
 - **Correct source discovery** — the no-build source scanner correctly handles block namespaces whose opening brace is on the next line, so public types are no longer silently under-reported; when a declaration cannot be paired with its brace it warns (`API_MODEL_SOURCE_SCANNER_INCOMPLETE`) and points to a build-backed audit,
-- **Project-scoped packets and representative dry runs** — documentation is processed in bounded project packets grouped by DocFX `metadata[].dest`, with ownership of namespaces, targets, overwrite files, and git-dirty paths. `--dry-run --build-api-model --project-manifest <path>` selects one **clean** project per destination group and writes both the initial baseline and a sibling changed-page review template; after evidence-based authoring and page-by-page review, `--resume-project-manifest <path> --review-report <path> --build-api-model --validate-samples --verify-docfx-build` verifies the same packets without mistaking new files for pre-existing work. Missing evidence, purpose/outcome, observable-result, or sibling-pattern review entries block completion. Dry runs never edit previously dirty files, fail closed on invalid manifests, and report `dry-run-passed` only after every gate succeeds. `--write-overwrite` preserves BOM/line endings and refuses dirty or duplicate-UID writes,
-- **Build-backed scope and a quality-risk pilot** — authoring scope must be reflection-precise: a `source-scan` model is `provisional` and raises `BUILD_BACKED_SCOPE_REQUIRED` until `--build-api-model` (or DocFX YAML) confirms it. Before editing, a quality-risk gate counts standalone/extension targets, the missing-to-existing ratio, and unresolved symbol ownership; above the thresholds it raises `QUALITY_RISK_REVIEW_REQUIRED` and requires a bounded pilot (one packet or 20 targets) with explicit approval before a full run,
+- **Project-scoped packets and voluntary representative dry runs** — documentation is processed in bounded project packets grouped by DocFX `metadata[].dest`, with ownership of namespaces, targets, overwrite files, and git-dirty paths. A normal run always preserves the user's requested scope and continues packet-by-packet until the global completion contract is clean. Only an explicitly requested `--dry-run --build-api-model --project-manifest <path>` selects one **clean** project per destination group and writes both the initial baseline and a sibling changed-page review template; after evidence-based authoring and page-by-page review, `--resume-project-manifest <path> --review-report <path> --build-api-model --validate-samples --verify-docfx-build` verifies the same packets without mistaking new files for pre-existing work. Missing evidence, purpose/outcome, observable-result, or sibling-pattern review entries block dry-run completion. `--write-overwrite` preserves BOM/line endings and refuses dirty or duplicate-UID writes,
+- **Build-backed scope and output-driven quality** — authoring scope must be reflection-precise: a `source-scan` model is `provisional` and raises `BUILD_BACKED_SCOPE_REQUIRED` until `--build-api-model` (or DocFX YAML) confirms it. Deterministic diagnostics evaluate the authored prose, examples, ownership, compilation, and DocFX build; target volume and diagnostic count never alter scope or select dry-run,
 - **Symbol-aware ownership and narrow family exemptions** — duplicate type names across assemblies (`SYMBOL_COLLISION_UNRESOLVED`), unresolved type forwarding (`TYPE_FORWARDING_UNRESOLVED`), and cross-assembly extension containers (`EXTENSION_OWNER_AMBIGUOUS`) are flagged with owning assembly/project; a heavily generic/inherited/overloaded/arity series can replace redundant per-type examples with one validated anchor example plus deep namespace guidance, declared explicitly in `.docfx/family-exemptions.json`,
 - **Examples that actually compile** — under the opt-in `--validate-samples` path, every `csharp`/`cs` documentation fence is compiled in its own isolated project; all sample projects are batched into one temporary `.slnx` graph build so shared dependencies restore and build once, `--sample-parallelism` bounds MSBuild concurrency, each sample references only the documented project(s) that own its namespace rather than every library project, and failures report the file, fence index, line, exit code, and compiler diagnostics,
 - **Honest opt-outs only** — a sample can skip compilation solely with `// dotnet-docfx-digest:skip-compile - <reason>`; a missing reason is flagged,

From 0e616759c0f844ce0b7fa37dddd97ecaa33db1e6 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 15:40:05 +0200
Subject: [PATCH 75/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20skill=20contract?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refines skill documentation structure, clarifies completion gates and repair workflows, and expands eval test coverage. Improves guidance on encoding safety, adaptive execution, and resuming partial audits.
---
 skills/dotnet-docfx-digest/SKILL.md              |  8 ++++----
 skills/dotnet-docfx-digest/evals/evals.json      | 16 ++++++++--------
 skills/dotnet-docfx-digest/references/scripts.md |  4 ++--
 .../dotnet-docfx-digest/references/workflow.md   |  6 +++---
 4 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 274dbc0..32e6333 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -52,9 +52,9 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 - When reporting adaptive execution, include the selected profile, processor and memory inputs, build/sample worker counts, timeout, concurrent/sequential choice, process counts, and phase timings from JSON. State that sample compilation follows API discovery because scoped references depend on the namespace-to-project map. Name CLI and environment overrides for profile, worker counts, and timeout when the user asks how to tune the run.
 - When reporting heartbeat behavior, state the complete contract: append-only `stderr`, no cursor-rewritten table, start and 10-second heartbeat events, final success/failure marker for all three long phases, latest non-empty child-output line when available, and plain redirected-log markers that do not depend on ANSI color. When reporting encoding safety, explicitly confirm the diff contains neither BOM-only nor line-ending-only changes.
 - Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape.
-- Prefer bounded project packets over one repository-sized authoring context. Discover packets with `docfx.cs --json` (`scope.packets`) or persist them with `--project-manifest <path>`; process one packet at a time and stop the whole run the moment a packet fails its quality gates. Establish reflection-precise scope with `--build-api-model` before authoring — when `summary.scopeState` is `provisional` and `BUILD_BACKED_SCOPE_REQUIRED` fires, the source-scan inventory must not authorize a full authoring run.
-- Honor the high-risk pilot stop. When `qualityRisk.highRisk` is true and `QUALITY_RISK_REVIEW_REQUIRED` is reported (more than 100 standalone or extension targets, a missing-to-existing ratio above 10:1, or any unresolved `SYMBOL_COLLISION_UNRESOLVED`/`EXTENSION_OWNER_AMBIGUOUS`), limit the first pass to one packet or 20 newly authored targets, manually review every changed namespace and type page, and get explicit user approval before continuing. Pass `--allow-high-risk` only as a deliberate, reviewed decision.
-- Dry run is a real run scoped to a representative subset, with identical evidence, authoring, quality, and compilation gates. Start it with `--dry-run --build-api-model --project-manifest <temp-path>`; this also emits a sibling `<name>.review.json` template. Author every selected packet, read every changed page, complete every review entry with evidence, page-specific purpose/outcome, observable result, and sibling prose/code comparison, then finish with `--resume-project-manifest <temp-path> --review-report <review-path> --build-api-model --validate-samples --verify-docfx-build`. The baseline protects pre-existing dirty work while allowing current-run files to verify. No-hint dry runs select one clean project per metadata destination group via a seed; explicit names override selection. Report `dry-run-passed` only after every gate passes, and include the completed `Changed-page review` table in the response; a validator summary is not a manual review. Never claim repository completion. Do not ask for hints when none were supplied. For large repositories, dry run is the mandatory quality pilot.
+- Prefer bounded project packets over one repository-sized authoring context. Discover packets with `docfx.cs --json` (`scope.packets`) or persist them with `--project-manifest <path>`; process one packet at a time while keeping the user's requested scope unchanged. Repair packet-local diagnostics before moving on when practical. If one diagnostic remains difficult after concrete attempts, record it, continue independent packets, and return to it; never turn one repairable packet failure into a reason to stop a full-repository run. Establish reflection-precise scope with `--build-api-model` before authoring — when `summary.scopeState` is `provisional` and `BUILD_BACKED_SCOPE_REQUIRED` fires, the source-scan inventory must not authorize a full authoring run.
+- Repository size, target count, diagnostic volume, context pressure, and model usage limits never change the user's requested scope. An explicit or default repo-wide run continues across every packet until the global completion contract is clean.
+- Dry run is a voluntary mode used only when the user explicitly asks for `dry-run`, a representative sample, or a quality pilot. Never infer it from repository size, diagnostic count, context pressure, or model usage limits. It is a real run scoped to a representative subset, with identical evidence, authoring, quality, and compilation gates. Start it with `--dry-run --build-api-model --project-manifest <temp-path>`; this also emits a sibling `<name>.review.json` template. Author every selected packet, read every changed page, complete every review entry with evidence, page-specific purpose/outcome, observable result, and sibling prose/code comparison, then finish with `--resume-project-manifest <temp-path> --review-report <review-path> --build-api-model --validate-samples --verify-docfx-build`. The baseline protects pre-existing dirty work while allowing current-run files to verify. No-hint dry runs select one clean project per metadata destination group via a seed; explicit names override selection. Report `dry-run-passed` only after every gate passes, and include the completed `Changed-page review` table in the response; a validator summary is not a manual review. Never claim repository completion. Do not ask for hints when none were supplied.
 - Use the safe structured overwrite writer (`docfx.cs --write-overwrite <request.json>`) for repeatable overwrite creation: it preserves BOM/line endings, rejects duplicate UIDs and unbalanced fences, and refuses to replace dirty files. It writes only content you authored — it never generates prose or examples.
 - Declare narrow family exemptions in `.docfx/family-exemptions.json` only for coherent generic-arity, inherited, overload, or type-parameter series. The anchor needs a real example and the namespace page must name it and explain sibling selection; category alone never exempts options, exceptions, delegates, records, or data carriers. See `references/workflow.md`.
 
@@ -67,7 +67,7 @@ Do not stop at namespace pages, extension-member tables, or a first-pass documen
 3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/types/`.
 4. For each missing extension-method example, document it on the declaring extension class page or the namespace page, and explicitly demonstrate the method call.
 5. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too and rerun until the JSON completion contract is clean.
-6. Do not convert repairable diagnostics into a blocker report. Stop incomplete only when the user pauses the task or an external condition still prevents progress after concrete attempts; report the exact blocker without claiming completion.
+6. Do not convert repairable diagnostics into a blocker report. A stubborn diagnostic is a debugging task: inspect the complete implicated UID/path set, validator normalization, source evidence, and related examples; fix either the content or a proven validator defect, then rerun. Continue unrelated packets while investigating when doing so preserves quality. Stop incomplete only when the user pauses the task or a genuine external condition prevents further execution; report the exact command, exit code, and blocker without claiming completion.
 
 Namespace pages and `Extension Members` tables complement type-page examples; they do not replace them. Both namespace pages (`api/namespaces/`) and type pages (`api/types/`) are required deliverables. Generating only one is incomplete work.
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index f7364d8..3bddb73 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -809,12 +809,12 @@
     },
     {
       "id": 66,
-      "prompt": "Run a full DocFX digest across all my project packets, but stop and tell me if a packet produces low-quality output.",
-      "expected_output": "The agent processes packets one at a time, runs the scoped semantic and sample gates per packet, and stops the entire run immediately when a packet fails its quality gates or produces mechanical output (holder/forwarding/repeated templates). It reports which packet failed and why rather than continuing to author later packets.",
+      "prompt": "Run a full DocFX digest across all my project packets. One packet still has a difficult template-repetition diagnostic after the first rewrite.",
+      "expected_output": "The agent processes packets one at a time, debugs the difficult diagnostic using its complete UID/path set and validator normalization, continues independent packets instead of ending the full run, then returns to the failed packet and finishes with global verification. It never substitutes dry-run or a pilot for the requested full scope.",
       "expectations": [
         "Processes packets one at a time with scoped quality gates",
-        "Stops the whole run immediately on the first failing packet",
-        "Does not continue authoring later packets after mechanical output is detected"
+        "Investigates the diagnostic as repair work and continues independent packets rather than stopping the full run",
+        "Returns to every unresolved packet and completes global verification without selecting dry-run"
       ]
     },
     {
@@ -840,11 +840,11 @@
     {
       "id": 69,
       "prompt": "My library has over 400 public types needing examples. Document it with dotnet-docfx-digest.",
-      "expected_output": "The agent sees QUALITY_RISK_REVIEW_REQUIRED (standalone targets above 100) and does not start a bulk authoring pass. It limits the first pass to one project packet or 20 targets, manually reviews those changed pages, and asks for explicit approval before continuing the full run. It treats a dry run as the preferred pilot for the large surface.",
+      "expected_output": "The agent treats the large target count as irrelevant to scope selection, keeps the requested full-repository scope, and processes all packets with bounded packet-local context and validation. It does not select dry-run, impose a target cap, or ask for pilot approval unless the user explicitly requested a dry run.",
       "expectations": [
-        "Detects the high-risk queue and stops for a bounded pilot instead of bulk authoring",
-        "Limits the first pass to one packet or about 20 targets and reviews the actual changed pages",
-        "Requests explicit approval before continuing the full run"
+        "Keeps full-repository scope despite the large queue",
+        "Does not select dry-run or impose a one-packet/20-target pilot cap",
+        "Continues through all packets and runs global completion verification without an approval pause"
       ]
     },
     {
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index 1edb223..d7ffc4b 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -78,7 +78,7 @@ dotnet run --file docfx.cs -- --repo-root . --build-api-model --configuration De
 
 Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only used by build/sample paths), `--framework`, `--validate-samples` / `--no-validate-samples` (default off — opt-in), `--sample-reference-mode <project|package>` (default `project`), `--sample-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_SAMPLE_PARALLELISM`; passed as the maximum node count for the batched sample graph build), `--build-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_BUILD_PARALLELISM`), `--execution-profile <auto|conservative|high-capacity>` (env `DOCFX_DIGEST_EXECUTION_PROFILE`), `--process-timeout-minutes <n>` (1-180, default 30; env `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES`), `--build-api-model` / `--strict-api-discovery` (default off — opt-in), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default off — opt-in), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
-Project-scoped authoring arguments: `--project <hint>` (repeatable; resolves against project path, file name, assembly name, or package id and must match exactly one project), `--dry-run` (select a representative working-tree run), `--seed <integer>` (reproducible dry-run selection; reported when generated), `--project-manifest <path>` (write a deterministic BOM-less packet manifest, initial dirty baseline, and sibling review template), `--resume-project-manifest <path>` (resume exactly those selected packets after authoring), `--review-report <path>` (required on resume; validates page-specific evidence, purpose/outcome, observable result, and pattern comparison), `--write-overwrite <path>` (safe structured overwrite-writer command), `--allow-high-risk` (proceed past the quality-risk pilot stop as an explicit decision), `--risk-standalone-threshold <n>` (default 100), `--risk-extension-threshold <n>` (default 100), and `--risk-missing-ratio-threshold <x>` (default 10). These appear in the report under `scope` and `qualityRisk`.
+Project-scoped authoring arguments: `--project <hint>` (repeatable; resolves against project path, file name, assembly name, or package id and must match exactly one project), `--dry-run` (voluntary representative working-tree run; use only when explicitly requested), `--seed <integer>` (reproducible dry-run selection; reported when generated), `--project-manifest <path>` (write a deterministic BOM-less packet manifest, initial dirty baseline, and sibling review template), `--resume-project-manifest <path>` (resume exactly those selected packets after authoring), `--review-report <path>` (required on resume; validates page-specific evidence, purpose/outcome, observable result, and pattern comparison), and `--write-overwrite <path>` (safe structured overwrite-writer command). Repository size and diagnostic volume never alter scope. Only explicit `--dry-run` selects a representative subset.
 
 ```bash
 dotnet run --file docfx.cs -- --repo-root . --dry-run --build-api-model --project-manifest /tmp/dry-run.json
@@ -128,7 +128,7 @@ Every run records a process tally, per-phase timings, and execution settings. No
 
 Every report also carries a deterministic completion contract. `summary.completionState` is `complete` only when there are no errors and the run enabled `--build-api-model`, `--validate-samples`, and `--verify-docfx-build`. A clean fast run reports `verification-required`. `summary.canClaimCompletion` must be `true`; `summary.remainingWorkItems` must be `0`; and both `summary.remainingGates` and `summary.remainingDiagnosticsByCode` must be empty before an agent can claim a full digest. Any other result is an active repair or verification queue. Diagnostic age, pre-existing status, and volume do not convert repair work into an external blocker.
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, `NAMESPACE_START_HERE_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `EXAMPLE_UID_DUPLICATE`, `EXAMPLE_PLACEHOLDER`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Project-scoped error codes are `PROJECT_HINT_NOT_FOUND` and `PROJECT_HINT_AMBIGUOUS` for `--project` hints, `FAMILY_EXEMPTION_INVALID`, `FAMILY_ANCHOR_EXAMPLE_MISSING`, and `FAMILY_NAMESPACE_GUIDANCE_MISSING` for `.docfx/family-exemptions.json`, and `OVERWRITE_UID_DUPLICATE`, `OVERWRITE_FENCE_UNBALANCED`, `OVERWRITE_DIRTY_REFUSED`, `OVERWRITE_REQUEST_MISSING`, and `OVERWRITE_REQUEST_INVALID` for the `--write-overwrite` writer. The semantic example codes reject the filler patterns that pass a naive token match: `EXAMPLE_DEFAULT_PLACEHOLDER` for a target parked in a `default!`/`null!` holder property or field, `EXAMPLE_NO_OBSERVABLE_OUTCOME` for an example that only holds, returns, or constructs the target with no visible result, `EXAMPLE_FORWARDING_SCAFFOLD` for a shell dominated by one-line pass-through members, and `EXAMPLE_TEMPLATE_REPETITION` for one normalized code skeleton reused across three or more unrelated targets. `NAMESPACE_APPEND_ONLY_REPAIR` flags an inventory-led opening left intact while usage or start-here guidance is appended below it (rewrite the opening cohesively instead), and `NAMESPACE_PROSE_TEMPLATE_REPETITION` flags three or more namespace overviews that share one normalized prose skeleton. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_SOURCE_SCANNER_INCOMPLETE` when the scanner cannot pair a block namespace declaration with its opening brace and may under-report public types, `BUILD_BACKED_SCOPE_REQUIRED` when authoring scope is requested on the provisional source-scan model, `PROJECT_DIRTY_SKIPPED` when an explicitly selected project has pre-existing related changes, `DRY_RUN_GROUP_UNSELECTED` when a metadata group has no clean project to sample, `QUALITY_RISK_REVIEW_REQUIRED` when the queue size or symbol complexity requires a pilot review, `SYMBOL_COLLISION_UNRESOLVED` / `TYPE_FORWARDING_UNRESOLVED` / `EXTENSION_OWNER_AMBIGUOUS` for unresolved symbol ownership, `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, `NAMESPACE_START_HERE_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `EXAMPLE_UID_DUPLICATE`, `EXAMPLE_PLACEHOLDER`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Project-scoped error codes are `PROJECT_HINT_NOT_FOUND` and `PROJECT_HINT_AMBIGUOUS` for `--project` hints, `FAMILY_EXEMPTION_INVALID`, `FAMILY_ANCHOR_EXAMPLE_MISSING`, and `FAMILY_NAMESPACE_GUIDANCE_MISSING` for `.docfx/family-exemptions.json`, and `OVERWRITE_UID_DUPLICATE`, `OVERWRITE_FENCE_UNBALANCED`, `OVERWRITE_DIRTY_REFUSED`, `OVERWRITE_REQUEST_MISSING`, and `OVERWRITE_REQUEST_INVALID` for the `--write-overwrite` writer. The semantic example codes reject the filler patterns that pass a naive token match: `EXAMPLE_DEFAULT_PLACEHOLDER` for a target parked in a `default!`/`null!` holder property or field, `EXAMPLE_NO_OBSERVABLE_OUTCOME` for an example that only holds, returns, or constructs the target with no visible result, `EXAMPLE_FORWARDING_SCAFFOLD` for a shell dominated by one-line pass-through members, and `EXAMPLE_TEMPLATE_REPETITION` for one normalized code skeleton reused across three or more distinct authored sections. One type- or namespace-level section may legitimately satisfy several extension targets and is counted once. `NAMESPACE_APPEND_ONLY_REPAIR` flags an inventory-led opening left intact while usage or start-here guidance is appended below it (rewrite the opening cohesively instead), and `NAMESPACE_PROSE_TEMPLATE_REPETITION` flags three or more namespace overviews that share one normalized prose skeleton. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_SOURCE_SCANNER_INCOMPLETE` when the scanner cannot pair a block namespace declaration with its opening brace and may under-report public types, `BUILD_BACKED_SCOPE_REQUIRED` when authoring scope is requested on the provisional source-scan model, `PROJECT_DIRTY_SKIPPED` when an explicitly selected project has pre-existing related changes, `DRY_RUN_GROUP_UNSELECTED` when an explicitly requested dry run has no clean project to sample, `SYMBOL_COLLISION_UNRESOLVED` / `TYPE_FORWARDING_UNRESOLVED` / `EXTENSION_OWNER_AMBIGUOUS` for unresolved symbol ownership, `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
 
 `ENCODING_CORRUPTION` fires when a documentation file contains the byte sequence `C3 A2 C2 AC` — the UTF-8 re-encoding of the `â¬` pair produced by a Windows-1252 round-trip of `U+2B07` (⬇, the Extension Members table arrow). Restore the affected file with `git checkout HEAD -- <file>` if the committed version was correct, or rewrite the content using the edit tool or byte-level operations. Never use `Get-Content` / `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes(Get-Content)` to rewrite documentation files that contain multi-byte characters.
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 5335f00..14a55c7 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -104,9 +104,9 @@ Full and dry runs use **identical** evidence, authoring instructions, semantic-q
 
 The conservative source scanner is for fast Markdown iteration, not authoritative scope. When `summary.apiModelSource` is `source-scan`, scope is `provisional` and the validator emits `BUILD_BACKED_SCOPE_REQUIRED`. Before authoring a full run or a selected dry-run packet, establish reflection-precise scope with `--build-api-model` (or generate DocFX managed-reference YAML). Treat a material fast/build-backed discrepancy as a blocker, not a rounding error.
 
-### Quality-risk pilot stop
+### Scope stability
 
-Before editing, read `qualityRisk` in the JSON. A run is high-risk when standalone targets exceed 100, extension targets exceed 100, the missing-to-existing example ratio exceeds 10:1, or any symbol-ownership collision remains. In high-risk mode the validator emits `QUALITY_RISK_REVIEW_REQUIRED`: limit the first authoring pass to one project packet or 20 newly authored targets, run the scoped semantic and compilation gates, produce a review inventory of every changed namespace and type page, and obtain explicit user approval before continuing. A dry run is the preferred pilot for very large repositories. Only pass `--allow-high-risk` as an explicit, reviewed decision.
+Target counts, diagnostic volume, ownership complexity, context pressure, and model usage limits never change the requested scope. A full run remains full regardless of queue size. Use project packets to keep authoring context bounded, continue through independent packets when one packet needs more debugging, and return to every unresolved diagnostic before final verification. Use dry-run only when the user explicitly requests a dry run, representative subset, or quality pilot.
 
 ### Working-tree dry run
 
@@ -125,7 +125,7 @@ Use `--dry-run [--seed <n>]` for automatic selection, `--dry-run --project <hint
 
 ### Packet authoring loop
 
-Process one packet at a time so the packet is the active context and write-ownership boundary. When the host supports fresh workers, assign each packet to a fresh worker with only packet-local evidence. For each packet: read the manifest and scoped diagnostics, read related Markdown before editing, read exact source/test/sample/package evidence, build an evidence ledger mapping each decision to a source path, classify targets into standalone-example or family-covered obligations, author namespace prose and overwrites, run the scoped semantic and sample gates, and review the diff. Stop the entire run immediately if a packet fails its quality gates — do not continue to later packets after mechanical output is detected.
+Process one packet at a time so the packet is the active context and write-ownership boundary. When the host supports fresh workers, assign each packet to a fresh worker with only packet-local evidence. For each packet: read the manifest and scoped diagnostics, read related Markdown before editing, read exact source/test/sample/package evidence, build an evidence ledger mapping each decision to a source path, classify targets into standalone-example or family-covered obligations, author namespace prose and overwrites, run the scoped semantic and sample gates, and review the diff. Repair mechanical output immediately. If a packet retains a difficult diagnostic after concrete debugging attempts, record its exact UID/path set and continue independent packets; return to the failed packet before global verification. Do not end a full run while any repairable diagnostic remains.
 
 ### Symbol ownership
 

From c962bfc2a8897e1c4e5e57777f50d626812d71c9 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 15:40:13 +0200
Subject: [PATCH 76/88] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20enhance=20docfx=20sk?=
 =?UTF-8?q?ill=20implementation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refactors docfx.cs for clarity and maintainability. Expands test-quality.ps1 with comprehensive validation. Enhances test-project-scoped.ps1 for focused testing. Adds completion contract support and adaptive execution profiles.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 172 +++---------------
 .../scripts/test-project-scoped.ps1           |  12 +-
 .../scripts/test-quality.ps1                  |  77 ++++++++
 3 files changed, 104 insertions(+), 157 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index ea5e43d..3ef1b58 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -329,7 +329,7 @@ private static int Validate(Options options)
         var families = LoadAndValidateFamilyExemptions(repoRoot, docfxWorkspace, api, workspace, namespacePageIndex, report);
         ApplyFamilyExemptions(api, families);
         report.Summary.RequiredExampleTargets = api.RequiredExampleTargets.Count;
-        ValidateSymbolOwnership(api, workspace, packets, report, out var symbolCollisions, out var typeForwarded, out var extensionAmbiguous);
+        ValidateSymbolOwnership(api, workspace, report);
         var scope = ResolveScope(options, packets, metadataGroups, apiModelSource, repoRoot, report, resumeScope);
         report.Summary.RunMode = scope.Mode;
         report.Summary.Seed = scope.Seed;
@@ -427,15 +427,12 @@ private static int Validate(Options options)
             ValidateChangedPageReview(options.ReviewReportPath, repoRoot, packets, gitState, report);
         }
 
-        var qualityRisk = EvaluateQualityRisk(options, api, packets, report.Summary.RequiredExamples,
-            symbolCollisions, typeForwarded, extensionAmbiguous, scope, report);
-        report.QualityRisk = qualityRisk;
         report.Scope = BuildScopeReport(scope, packets, metadataGroups, gitState, families, repoRoot, report);
         if (options.ProjectManifestPath is not null)
         {
             try
             {
-                WriteProjectManifest(options.ProjectManifestPath, repoRoot, docfxPath, report.Scope, qualityRisk,
+                WriteProjectManifest(options.ProjectManifestPath, repoRoot, docfxPath, report.Scope,
                     report.Summary.ApiModelSource ?? "unknown", report);
             }
             catch (Exception ex)
@@ -3771,7 +3768,7 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
                 $"UID `{duplicate.Key}` is mapped to {duplicate.Count()} example sections. Keep one coherent, scenario-led example for a UID; merge or remove the duplicate `example: *content` sections."));
         }
 
-        var exampleFingerprints = new List<(string Uid, string Path, string Fingerprint)>();
+        var exampleFingerprints = new List<(string SectionUid, string Path, string Fingerprint)>();
 
         foreach (var target in api.RequiredExampleTargets)
         {
@@ -3808,7 +3805,14 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
                     : ExtractExampleSection(validSection.Body));
                 if (fingerprint.Length >= 40)
                 {
-                    exampleFingerprints.Add((target.Uid, Rel(repoRoot, validSection.File), fingerprint));
+                    var path = Rel(repoRoot, validSection.File);
+                    if (!exampleFingerprints.Any(entry =>
+                            string.Equals(entry.SectionUid, validSection.Uid, StringComparison.Ordinal) &&
+                            string.Equals(entry.Path, path, StringComparison.OrdinalIgnoreCase) &&
+                            string.Equals(entry.Fingerprint, fingerprint, StringComparison.Ordinal)))
+                    {
+                        exampleFingerprints.Add((validSection.Uid, path, fingerprint));
+                    }
                 }
 
                 continue;
@@ -3850,13 +3854,16 @@ private static void ValidateRequiredExamples(string repoRoot, string docfxWorksp
         // or conventional one-line setup that legitimately recurs.
         foreach (var group in exampleFingerprints
                      .GroupBy(entry => entry.Fingerprint, StringComparer.Ordinal)
-                     .Where(group => group.Select(entry => entry.Uid).Distinct(StringComparer.Ordinal).Count() >= 3))
+                     .Where(group => group
+                         .Select(entry => (entry.SectionUid, entry.Path))
+                         .Distinct()
+                         .Count() >= 3))
         {
             var paths = group.Select(entry => entry.Path)
                 .Distinct(StringComparer.OrdinalIgnoreCase)
                 .OrderBy(path => path, StringComparer.OrdinalIgnoreCase)
                 .ToList();
-            var uids = group.Select(entry => entry.Uid)
+            var uids = group.Select(entry => entry.SectionUid)
                 .Distinct(StringComparer.Ordinal)
                 .OrderBy(uid => uid, StringComparer.Ordinal)
                 .ToList();
@@ -4952,7 +4959,7 @@ private static bool IsInsufficientSkipReason(string reason)
 
     // ----------------------------------------------------------------------
     // Project-scoped discovery: git state, packets, scope selection, families,
-    // symbol ownership, quality risk, manifest, and the safe overwrite writer.
+    // symbol ownership, manifest, and the safe overwrite writer.
     // ----------------------------------------------------------------------
 
     private static GitState GetGitState(string repoRoot)
@@ -5624,13 +5631,8 @@ private static void ApplyFamilyExemptions(ApiModel api, List<FamilyExemption> fa
 
     // Symbol ownership: duplicate simple type names across owning projects, type forwarding that
     // cannot be attributed, and extension containers that cross project boundaries.
-    private static void ValidateSymbolOwnership(ApiModel api, ValidationWorkspace ws, List<ProjectPacket> packets,
-        Report report, out int collisions, out int forwarded, out int extensionAmbiguous)
+    private static void ValidateSymbolOwnership(ApiModel api, ValidationWorkspace ws, Report report)
     {
-        collisions = 0;
-        forwarded = 0;
-        extensionAmbiguous = 0;
-
         var ownerByNamespace = ws.NamespaceProjects;
         string OwnersOf(string ns) => ownerByNamespace.TryGetValue(ns, out var list)
             ? string.Join(", ", list.Where(o => !o.IsTest).Select(o => o.AssemblyName).Distinct(StringComparer.OrdinalIgnoreCase).OrderBy(n => n, StringComparer.OrdinalIgnoreCase))
@@ -5654,7 +5656,6 @@ string OwnersOf(string ns) => ownerByNamespace.TryGetValue(ns, out var list)
                 .ToList();
             if (owners.Count >= 2)
             {
-                collisions++;
                 report.Warnings.Add(new Diagnostic("SYMBOL_COLLISION_UNRESOLVED", null, group.First().Namespace,
                     $"Simple type name '{group.Key}' is documented in multiple assemblies/namespaces ({string.Join("; ", distinctUids.Select(u => $"{u} [{OwnersOf(NamespaceFromUid(u))}]"))}). Qualify examples and overwrite UIDs by owning assembly/project so coverage is not ambiguous."));
             }
@@ -5683,7 +5684,6 @@ string OwnersOf(string ns) => ownerByNamespace.TryGetValue(ns, out var list)
                     var documented = api.RequiredExampleTargets.Any(t => string.Equals(SimpleNameFromUid(t.Uid), simple, StringComparison.Ordinal));
                     if (!documented)
                     {
-                        forwarded++;
                         report.Warnings.Add(new Diagnostic("TYPE_FORWARDING_UNRESOLVED", Rel(ws.RepoRoot, file), null,
                             $"Type '{forwardedType}' is forwarded from '{project.AssemblyName}' but cannot be matched to a documented type target. Resolve which project and UID documents the forwarded family before authoring."));
                     }
@@ -5709,78 +5709,12 @@ string OwnersOf(string ns) => ownerByNamespace.TryGetValue(ns, out var list)
                 .ToList();
             if (owners.Count >= 2)
             {
-                extensionAmbiguous++;
                 report.Warnings.Add(new Diagnostic("EXTENSION_OWNER_AMBIGUOUS", null, namespaces[0],
                     $"Extension container '{group.Key}' is declared in multiple namespaces/assemblies ({string.Join(", ", namespaces.Select(ns => $"{ns} [{OwnersOf(ns)}]"))}). Prefer receiver extension syntax and a uniquely owned overwrite UID so the example targets the right declaring type."));
             }
         }
     }
 
-    private static QualityRiskReport EvaluateQualityRisk(Options options, ApiModel api, List<ProjectPacket> packets,
-        int existingValidExamples, int collisions, int forwarded, int extensionAmbiguous, ScopePlan scope, Report report)
-    {
-        var standaloneThreshold = options.RiskStandaloneThreshold ?? 100;
-        var extensionThreshold = options.RiskExtensionThreshold ?? 100;
-        var ratioThreshold = options.RiskMissingRatioThreshold ?? 10.0;
-
-        var standalone = api.RequiredExampleTargets.Count(t => t.Kind == ApiTargetKind.Type);
-        var extension = api.RequiredExampleTargets.Count(t => t.Kind == ApiTargetKind.ExtensionMethod);
-        var missing = Math.Max(0, standalone + extension - existingValidExamples);
-        var ratio = missing / (double)Math.Max(1, existingValidExamples);
-        var shared = packets.SelectMany(p => p.SharedNamespaces).Distinct(StringComparer.Ordinal).Count();
-
-        var risk = new QualityRiskReport
-        {
-            StandaloneTargets = standalone,
-            ExtensionTargets = extension,
-            ExistingValidExamples = existingValidExamples,
-            MissingToExistingRatio = Math.Round(ratio, 2),
-            SymbolCollisions = collisions,
-            TypeForwardedTargets = forwarded,
-            SharedNamespaces = shared,
-            UnresolvedExtensionOwners = extensionAmbiguous,
-            StandaloneThreshold = standaloneThreshold,
-            ExtensionThreshold = extensionThreshold,
-            RatioThreshold = ratioThreshold,
-            PilotTargetCap = 20
-        };
-
-        if (standalone > standaloneThreshold)
-        {
-            risk.TriggeredThresholds.Add($"standalone-targets {standalone} > {standaloneThreshold}");
-        }
-
-        if (extension > extensionThreshold)
-        {
-            risk.TriggeredThresholds.Add($"extension-targets {extension} > {extensionThreshold}");
-        }
-
-        if (ratio > ratioThreshold)
-        {
-            risk.TriggeredThresholds.Add($"missing-to-existing {risk.MissingToExistingRatio} > {ratioThreshold}");
-        }
-
-        if (collisions > 0 || extensionAmbiguous > 0)
-        {
-            risk.TriggeredThresholds.Add($"unresolved symbol ownership ({collisions} collisions, {extensionAmbiguous} extension owners)");
-        }
-
-        risk.HighRisk = risk.TriggeredThresholds.Count > 0;
-        risk.RecommendedScope = packets.Count > 1
-            ? "Run a dry-run pilot (--dry-run) or a single --project packet before authoring the full surface."
-            : "Limit the first authoring pass to a 20-target pilot, then review before continuing.";
-
-        var authoringIntent = options.DryRun || options.ProjectHints.Count > 0 || options.ProjectManifestPath is not null ||
-                              options.ResumeProjectManifestPath is not null || options.BuildApiModel;
-        if (risk.HighRisk && authoringIntent && !options.AllowHighRisk)
-        {
-            report.Warnings.Add(new Diagnostic("QUALITY_RISK_REVIEW_REQUIRED", null, null,
-                $"High-risk authoring queue: {string.Join("; ", risk.TriggeredThresholds)}. Stop after the first project packet or {risk.PilotTargetCap} newly authored targets and obtain explicit review before continuing. {risk.RecommendedScope} Pass --allow-high-risk only as an explicit, reviewed decision."));
-        }
-
-        return risk;
-    }
-
     private static ScopeReport BuildScopeReport(ScopePlan scope, List<ProjectPacket> packets,
         List<MetadataGroupInfo> groups, GitState gitState, List<FamilyExemption> families, string repoRoot, Report report)
     {
@@ -5897,7 +5831,7 @@ private static ScopeReport BuildScopeReport(ScopePlan scope, List<ProjectPacket>
     }
 
     private static void WriteProjectManifest(string path, string repoRoot, string docfxPath, ScopeReport scope,
-        QualityRiskReport risk, string apiModelSource, Report report)
+        string apiModelSource, Report report)
     {
         var manifest = new
         {
@@ -5911,8 +5845,7 @@ private static void WriteProjectManifest(string path, string repoRoot, string do
             metadataGroups = scope.MetadataGroups,
             packets = scope.Packets,
             dirty = scope.Dirty,
-            familyExemptions = scope.FamilyExemptions,
-            qualityRisk = risk
+            familyExemptions = scope.FamilyExemptions
         };
 
         var json = JsonSerializer.Serialize(manifest, JsonOptions);
@@ -7183,24 +7116,6 @@ private static bool TryParse(string[] args, out Options options, out string erro
                     if (!Next(args, ref i, out var wo)) { error = "--write-overwrite requires a request JSON path."; return false; }
                     options.WriteOverwriteRequestPath = wo;
                     break;
-                case "--allow-high-risk":
-                    options.AllowHighRisk = true;
-                    break;
-                case "--risk-standalone-threshold":
-                    if (!Next(args, ref i, out var rst)) { error = "--risk-standalone-threshold requires a count."; return false; }
-                    if (!int.TryParse(rst, out var rstv) || rstv < 0) { error = "--risk-standalone-threshold must be a non-negative integer."; return false; }
-                    options.RiskStandaloneThreshold = rstv;
-                    break;
-                case "--risk-extension-threshold":
-                    if (!Next(args, ref i, out var ret)) { error = "--risk-extension-threshold requires a count."; return false; }
-                    if (!int.TryParse(ret, out var retv) || retv < 0) { error = "--risk-extension-threshold must be a non-negative integer."; return false; }
-                    options.RiskExtensionThreshold = retv;
-                    break;
-                case "--risk-missing-ratio-threshold":
-                    if (!Next(args, ref i, out var rmr)) { error = "--risk-missing-ratio-threshold requires a number."; return false; }
-                    if (!double.TryParse(rmr, System.Globalization.NumberStyles.Float, System.Globalization.CultureInfo.InvariantCulture, out var rmrv) || rmrv < 0) { error = "--risk-missing-ratio-threshold must be a non-negative number."; return false; }
-                    options.RiskMissingRatioThreshold = rmrv;
-                    break;
                 case "--json":
                     options.Json = true;
                     break;
@@ -7269,23 +7184,6 @@ private static bool TryParse(string[] args, out Options options, out string erro
                         options.WriteOverwriteRequestPath = v14;
                         break;
                     }
-                    if (TrySplit(arg, "--risk-standalone-threshold", out var v15) && int.TryParse(v15, out var rstInline) && rstInline >= 0)
-                    {
-                        options.RiskStandaloneThreshold = rstInline;
-                        break;
-                    }
-                    if (TrySplit(arg, "--risk-extension-threshold", out var v16) && int.TryParse(v16, out var retInline) && retInline >= 0)
-                    {
-                        options.RiskExtensionThreshold = retInline;
-                        break;
-                    }
-                    if (TrySplit(arg, "--risk-missing-ratio-threshold", out var v17) &&
-                        double.TryParse(v17, System.Globalization.NumberStyles.Float, System.Globalization.CultureInfo.InvariantCulture, out var rmrInline) && rmrInline >= 0)
-                    {
-                        options.RiskMissingRatioThreshold = rmrInline;
-                        break;
-                    }
-
                     error = $"Unknown argument: {arg}";
                     return false;
             }
@@ -7399,7 +7297,7 @@ destination group (or all explicit --project packets). Persist the initial
                                       reported when omitted.
               --project-manifest <path>
                                       Write a deterministic BOM-less project packet manifest (groups, packets,
-                                      ownership, initial dirty paths, family exemptions, quality risk) and continue.
+                                      ownership, initial dirty paths, and family exemptions) and continue.
               --resume-project-manifest <path>
                                       Resume the exact selected packets and initial dirty-file baseline from a
                                       prior manifest. Use this after authoring so newly created dry-run files are
@@ -7410,10 +7308,6 @@ validated without treating them as pre-existing user work.
               --write-overwrite <path> Safe structured overwrite writer. Reads a JSON request with
                                       file/uid/mapping/prose/fence fields, validates it, preserves BOM/line
                                       endings, refuses to replace dirty or duplicate-UID files, and exits.
-              --allow-high-risk        Explicitly proceed past the quality-risk pilot stop (a reviewed decision).
-              --risk-standalone-threshold <n>     Standalone-example target threshold (default 100).
-              --risk-extension-threshold <n>      Extension-method target threshold (default 100).
-              --risk-missing-ratio-threshold <x>  Missing-to-existing example ratio threshold (default 10).
               --json                   Emit a machine-readable JSON summary (includes processes + phase timings).
               --help                   Print this usage.
 
@@ -7470,10 +7364,6 @@ private sealed class Options
         public string? ResumeProjectManifestPath { get; set; }
         public string? ReviewReportPath { get; set; }
         public string? WriteOverwriteRequestPath { get; set; }
-        public bool AllowHighRisk { get; set; }
-        public int? RiskStandaloneThreshold { get; set; }
-        public int? RiskExtensionThreshold { get; set; }
-        public double? RiskMissingRatioThreshold { get; set; }
     }
 
     private sealed record ProjectInfo(string Path, string AssemblyName, List<string> TargetFrameworks, bool IsTest, string? PackageId = null);
@@ -7781,7 +7671,6 @@ internal sealed class Report
     public string? Status { get; set; }
     public Summary Summary { get; set; } = new();
     public ScopeReport? Scope { get; set; }
-    public QualityRiskReport? QualityRisk { get; set; }
     public List<Diagnostic> Errors { get; set; } = new();
     public List<Diagnostic> Warnings { get; set; } = new();
     public List<string> PackageIds { get; set; } = new();
@@ -7856,22 +7745,3 @@ internal sealed class FamilyExemptionReport
     public string Rationale { get; set; } = string.Empty;
     public bool Valid { get; set; }
 }
-
-internal sealed class QualityRiskReport
-{
-    public bool HighRisk { get; set; }
-    public int StandaloneTargets { get; set; }
-    public int ExtensionTargets { get; set; }
-    public int ExistingValidExamples { get; set; }
-    public double MissingToExistingRatio { get; set; }
-    public int SymbolCollisions { get; set; }
-    public int TypeForwardedTargets { get; set; }
-    public int SharedNamespaces { get; set; }
-    public int UnresolvedExtensionOwners { get; set; }
-    public List<string> TriggeredThresholds { get; set; } = new();
-    public int StandaloneThreshold { get; set; }
-    public int ExtensionThreshold { get; set; }
-    public double RatioThreshold { get; set; }
-    public int PilotTargetCap { get; set; }
-    public string? RecommendedScope { get; set; }
-}
diff --git a/skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1 b/skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1
index 7600dee..985819c 100644
--- a/skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1
+++ b/skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1
@@ -359,7 +359,7 @@ Availability: `Fam.Tuples`
 }
 
 # ----------------------------------------------------------------------
-Run-Scenario 'Quality-risk thresholds trigger a pilot-review warning' {
+Run-Scenario 'Normal target volume never changes full-run scope' {
     param($ws)
     Write-Utf8File (Join-Path $ws 'AGENTS.md') $agents
     Write-Utf8File (Join-Path $ws 'src/Risk/Risk.csproj') $csproj
@@ -368,11 +368,11 @@ Run-Scenario 'Quality-risk thresholds trigger a pilot-review warning' {
     Write-Utf8File (Join-Path $ws '.docfx/docfx.json') (New-Docfx @(@{ Dest = 'api'; Files = @('src/Risk/Risk.csproj') }))
     Initialize-GitRepo $ws
 
-    $r = Invoke-Validator $ws @('--dry-run', '--seed', '1', '--risk-standalone-threshold', '3')
-    Assert-Diagnostic -Report $r -Code 'QUALITY_RISK_REVIEW_REQUIRED' -Where 'warnings'
-    if (-not $r.qualityRisk.highRisk) { throw 'qualityRisk.highRisk should be true' }
-    if ($r.qualityRisk.standaloneTargets -lt 6) { throw "standaloneTargets=$($r.qualityRisk.standaloneTargets)" }
-}
+    $r = Invoke-Validator $ws
+    if ($r.PSObject.Properties.Name -contains 'qualityRisk') { throw 'qualityRisk metadata must not be emitted' }
+    if ($r.summary.runMode -ne 'full') { throw "runMode=$($r.summary.runMode); normal execution must remain full" }
+    if (@($r.scope.selectedProjects).Count -ne 1) { throw "selectedProjects=$(@($r.scope.selectedProjects).Count); full scope should include the project" }
+}
 
 # ----------------------------------------------------------------------
 Run-Scenario 'Duplicate type names across assemblies and ambiguous extension owners are flagged' {
diff --git a/skills/dotnet-docfx-digest/scripts/test-quality.ps1 b/skills/dotnet-docfx-digest/scripts/test-quality.ps1
index 8367a15..37e66b0 100644
--- a/skills/dotnet-docfx-digest/scripts/test-quality.ps1
+++ b/skills/dotnet-docfx-digest/scripts/test-quality.ps1
@@ -480,6 +480,83 @@ public static class Use$name
     }
 }
 
+# ----------------------------------------------------------------------
+# Scenario: one authored extension-container example may satisfy several extension targets.
+# The section is one authored scenario and must not be counted once per covered method.
+# ----------------------------------------------------------------------
+$sharedExtension = Join-Path ([System.IO.Path]::GetTempPath()) ('dotnet-docfx-shared-extension-' + [guid]::NewGuid().ToString('N'))
+try {
+    $arrow = "$([char]0x2B07)$([char]0xFE0F)"
+    Write-Utf8File (Join-Path $sharedExtension 'AGENTS.md') @'
+<!-- dotnet-docfx-digest:start -->
+Managed DocFX guidance.
+<!-- dotnet-docfx-digest:end -->
+'@
+    Write-Utf8File (Join-Path $sharedExtension 'src/Acme.Extensions.csproj') $projectCsproj
+    Write-Utf8File (Join-Path $sharedExtension 'src/Extensions.cs') @'
+namespace Acme.Extensions;
+
+public static class TextExtensions
+{
+    public static string Trimmed(this string value) => value.Trim();
+    public static string Uppercase(this string value) => value.ToUpperInvariant();
+    public static int WordCount(this string value) => value.Split(' ', System.StringSplitOptions.RemoveEmptyEntries).Length;
+}
+'@
+    Write-Utf8File (Join-Path $sharedExtension '.docfx/docfx.json') (New-DocfxJson -ProjectFiles @('src/Acme.Extensions.csproj'))
+    Write-Utf8File (Join-Path $sharedExtension '.docfx/api/namespaces/Acme.Extensions.md') @"
+---
+uid: Acme.Extensions
+summary: *content
+---
+Choose these text operations when input needs small, explicit transformations before display or comparison. `TextExtensions` keeps each operation available directly on the source string.
+
+## Extension Members
+
+|Type|Ext|Methods|
+|---|---|---|
+|String|$arrow|``Trimmed``, ``Uppercase``, ``WordCount``|
+
+Availability: ``Acme.Extensions``
+"@
+    Write-Utf8File (Join-Path $sharedExtension '.docfx/api/types/Acme.Extensions.TextExtensions.md') @'
+---
+uid: Acme.Extensions.TextExtensions
+example: *content
+---
+This example prepares a user-entered title and reports the resulting word count.
+
+```csharp
+using System;
+using Acme.Extensions;
+
+namespace Samples;
+
+public static class TextPreparationExample
+{
+    public static void PrintPreparedTitle()
+    {
+        const string input = "  release notes  ";
+        var prepared = input.Trimmed().Uppercase();
+
+        Console.WriteLine(prepared);
+        Console.WriteLine(prepared.WordCount());
+    }
+}
+```
+'@
+
+    $sharedReport = Invoke-Validator -Workspace $sharedExtension
+    Assert-NoDiagnostic -Report $sharedReport -Code 'EXAMPLE_TEMPLATE_REPETITION'
+    Assert-NoDiagnostic -Report $sharedReport -Code 'EXAMPLE_MISSING'
+
+    Write-Host 'DocFX shared extension example fingerprint regression passed.'
+} finally {
+    if (Test-Path $sharedExtension) {
+        Remove-Item -Path $sharedExtension -Recurse -Force
+    }
+}
+
 # ----------------------------------------------------------------------
 # Scenario: mechanical namespace prose repeated across unrelated pages.
 # Three namespaces that share one normalized prose skeleton must fail. Two unrelated pages using

From e702f9f6e61ed28f56e84e4d3988fbb94bbe4e64 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 16:17:58 +0200
Subject: [PATCH 77/88] =?UTF-8?q?=F0=9F=93=9D=20update=20readme=20with=20s?=
 =?UTF-8?q?kill=20enhancements?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refreshes the dotnet-docfx-digest skill entry to reflect recent refinements to documentation structure and implementation improvements.
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 46279d7..8d32830 100644
--- a/README.md
+++ b/README.md
@@ -105,7 +105,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class or namespace pages instead of synthetic method-UID filenames, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class type pages under `.docfx/api/types/` instead of synthetic method-UID filenames or namespace pages that mix extra `uid:` / `example:` blocks into the overview, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -549,7 +549,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Decision-useful namespace checks** — uid front matter, availability, and `Extension Members` tables are validated against the actual public surface, while semantic gates reject inventory-only prose, weak inventory leads left intact beneath an appended start-here sentence, and mechanical prose templates shared across pages, requiring concrete when-to-use and start-here guidance with diagnostics such as `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING`,
 - **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
-- **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/types/`, legacy authored `.docfx/api/*.md` overwrite files move into `api/namespaces/` or `api/types/` instead of widening the glob to `api/**/*.md`, both overwrite trees stay excluded from `build.content`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class or namespace overwrite pages instead of URL-encoded method-UID filenames, and agents must rerun the completion repair loop until diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
+- **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/types/`, legacy authored `.docfx/api/*.md` overwrite files move into `api/namespaces/` or `api/types/` instead of widening the glob to `api/**/*.md`, both overwrite trees stay excluded from `build.content`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class type pages under `.docfx/api/types/` instead of URL-encoded method-UID filenames or namespace pages that mix overview and member UIDs, namespace pages fail validation when they embed secondary `uid:` / `example:` sections, and agents must rerun the completion repair loop until diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
 - **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
 - **Examples that teach a real workflow** — examples start from package IDs and package-level evidence before falling back to type/member-only searches, prefer README, package docs, tooling, tuning, functional-test, and external GitHub usage when available, and may include multiple related public types when that is what makes the consumer scenario understandable,
 - **Semantic example quality gates** — compilation-valid filler no longer passes: the validator rejects duplicate UID mappings, `Type.GetType`/assembly metadata scaffolds, generic `DocumentedTypeExample`/`Describe()` templates, type examples that never use the target in code, extension examples that mention a method only in prose instead of invoking it, `default!`/`null!` holder properties (`EXAMPLE_DEFAULT_PLACEHOLDER`), classes that only construct or return the target with no observable result (`EXAMPLE_NO_OBSERVABLE_OUTCOME`), mass-forwarding shells of one-line pass-throughs (`EXAMPLE_FORWARDING_SCAFFOLD`), and one normalized code skeleton reused across three or more unrelated targets (`EXAMPLE_TEMPLATE_REPETITION`),

From 46123997b2bec3fec6c28c1aea8896fd749a71f9 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 16:18:05 +0200
Subject: [PATCH 78/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20skill=20contract?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refines skill documentation with clarity improvements. Expands eval test cases and enhances reference material for overwrite file layout and workflow patterns.
---
 skills/dotnet-docfx-digest/SKILL.md           |  7 ++--
 skills/dotnet-docfx-digest/evals/evals.json   | 32 +++++++++++++------
 .../references/docfx-overwrite-files.md       |  8 +++--
 .../references/workflow.md                    |  4 ++-
 4 files changed, 35 insertions(+), 16 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 32e6333..7c2cc14 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -43,6 +43,7 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 - Treat validator errors as the repo-wide repair queue, not as evidence that the repository is "blocked." A diagnostic being old, pre-existing, numerous, or outside the first files edited does not remove it from scope. A run with 1,228 `EXAMPLE_MISSING` findings means 1,228 documentation items remain; repairing one type page is a partial result, not a digest.
 - Passing compilation is necessary but not sufficient. `EXAMPLE_PLACEHOLDER`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, and `EXAMPLE_UID_DUPLICATE` are blocking quality failures. Never satisfy the inventory with `Type.GetType`, assembly metadata inspection, `DocumentedTypeExample`, `DocumentedExtensionExample`, generic `Describe()` helpers, repeated UID sections, prose that merely names the target, a `default!`/`null!` holder property that only parks the type, a class that just constructs or returns the target with no observable result, a mass-forwarding shell of one-line pass-through members, or one normalized code skeleton reused across unrelated types.
 - Namespace prose must be decision-useful. `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING` mean the page still needs a problem/outcome opening, a cohesively rewritten lead instead of a weak inventory sentence with guidance appended below it, an opening written from the namespace's own purpose rather than a shared template, concrete "when to use" guidance, and a named starting API when the namespace has multiple entry points.
+- Namespace overview files are single-UID deliverables. `NAMESPACE_EMBEDDED_OVERWRITE_SECTION` means the page mixed namespace guidance with secondary `uid:` / `example:` mappings after the overview, often below `Extension Members`. Move those type/member examples to readable type-targeted files under `.docfx/api/types/`, usually the declaring extension class page, and keep the namespace page limited to the namespace fly-in, availability, related links, and optional `Extension Members` table.
 - Use the JSON completion contract as the final authority: completion requires `summary.canClaimCompletion` to be `true`, `summary.remainingWorkItems` to be `0`, `summary.remainingGates` and `summary.remainingDiagnosticsByCode` to be empty, and the build-backed command to succeed. A clean fast run reports `completionState: verification-required`; it is an iteration checkpoint, not completion. Never describe `status: failed`, `completionState: incomplete`, or `completionState: verification-required` as completed work.
 - Continue documentation repair when `dotnet test` fails for an unrelated environmental dependency such as an unavailable database. Report that test failure separately. It is a blocker only if it prevents the documentation validator, source inspection, or required sample compilation from running.
 - Valid BOM-less UTF-8 is compliant. The validator must not emit `ENCODING_BOM_MISSING` (that diagnostic is intentionally unsupported), and an audit must not add/remove BOMs or normalize line endings solely for consistency. BOM presence has no documentation value; preserve the file's existing state and continue detecting actual `ENCODING_CORRUPTION` and `EXTENSION_TABLE_ENCODING` damage.
@@ -65,7 +66,7 @@ Do not stop at namespace pages, extension-member tables, or a first-pass documen
 1. Run `docfx.cs --json` (fast, no-build) after edits and read the remaining diagnostics.
 2. Treat every missing, placeholder, reflection-only, target-use, extension-invocation, duplicate-UID, namespace-prose, extension-table, availability, and overwrite-layout diagnostic as blocking follow-up work.
 3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/types/`.
-4. For each missing extension-method example, document it on the declaring extension class page or the namespace page, and explicitly demonstrate the method call.
+4. For each missing extension-method example, document it on the declaring extension class page or another readable type-targeted overwrite file under `.docfx/api/types/`, and explicitly demonstrate the method call. Do not append secondary `uid:` / `example:` blocks to the namespace page.
 5. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too and rerun until the JSON completion contract is clean.
 6. Do not convert repairable diagnostics into a blocker report. A stubborn diagnostic is a debugging task: inspect the complete implicated UID/path set, validator normalization, source evidence, and related examples; fix either the content or a proven validator defect, then rerun. Continue unrelated packets while investigating when doing so preserves quality. Stop incomplete only when the user pauses the task or a genuine external condition prevents further execution; report the exact command, exit code, and blocker without claiming completion.
 
@@ -147,7 +148,7 @@ When public API is added or materially changed, update every relevant surface:
 2. Namespace overview pages for namespaces that contain public API, under `.docfx/api/namespaces/`.
 3. `Extension Members` tables for namespaces that expose public extension methods.
 4. Type-targeting overwrite content for public non-abstraction types that require examples or richer guidance, under `.docfx/api/types/`.
-5. Extension-method examples on the declaring extension class page or the namespace page.
+5. Extension-method examples on the declaring extension class page or another readable type-targeted overwrite file under `.docfx/api/types/`.
 6. Availability information.
 7. Verification commands or artifacts that prove the documentation remains accurate and buildable.
 
@@ -187,7 +188,7 @@ Prefer examples derived from existing unit, functional, or integration tests as
 
 For public non-abstraction types, put the example on the generated type page by targeting the type UID in DocFX overwrite content. In Codebelt repositories, keep authored type overwrite Markdown under `.docfx/api/types/`, typically as `.docfx/api/types/{TypeUid}.md`.
 
-For public extension methods, place examples on the declaring extension class page or the namespace page. The example must explicitly call the method.
+For public extension methods, place examples on the declaring extension class page or another readable type-targeted overwrite file under `.docfx/api/types/`. The example must explicitly call the method. Namespace overview files stay single-UID; do not append secondary `uid:` / `example:` blocks after `Extension Members`.
 
 Never mirror synthetic method UIDs that contain hashes, encoding, or generated suffixes in filenames. Keep filenames readable and let the YAML `uid` decide what DocFX model the content targets.
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 3bddb73..4925368 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -28,10 +28,12 @@
     {
       "id": 3,
       "prompt": "Add a usage example to the `Acme.Text` namespace page for the `Greeter` class. Base it on the existing unit test `GreeterTest.Greet_WithName_ReturnsGreeting`.",
-      "expected_output": "Agent converts the Arrange/Act/Assert test into a real-life consumer-oriented, buildable example without raw assertions, and verifies it compiles with scripts/docfx.cs.",
+      "expected_output": "Agent preserves the `Acme.Text` namespace page as a namespace-scoped overview, converts the Arrange/Act/Assert test into a real-life consumer-oriented, buildable example on the `Greeter` type page under `.docfx/api/types/` (or an equivalent type-targeted overwrite file), and verifies it compiles with scripts/docfx.cs.",
       "expectations": [
         "Derives the example from the referenced test rather than inventing behavior",
         "Converts the Arrange/Act/Assert structure into developer-oriented usage instead of pasting raw assertions",
+        "Does not append a secondary `uid:` / `example:` block to the namespace page after `Extension Members` or other namespace guidance",
+        "Places the `Greeter` example on a type-targeted overwrite file under `.docfx/api/types/` rather than on the namespace overview file",
         "Produces a minimal, deterministic, copy/paste-ready C# example with a real using directive for Acme.Text",
         "Avoids pseudo-code, ellipses, and hidden helpers in the sample",
         "Verifies the sample compiles via scripts/docfx.cs or an equivalent build command"
@@ -84,7 +86,7 @@
         "Creates or moves readable type-targeting DocFX overwrite files under `.docfx/api/types/` for public non-abstraction type examples",
         "Keeps `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` only and excludes `api/namespaces/**` and `api/types/**` from `build.content`",
         "Places a public ApplicationHostFactory example on the ApplicationHostFactory type page/overwrite section rather than only on the namespace page",
-        "Creates or updates overwrite content for public extension method examples, or places the example on the extension class or namespace page while explicitly demonstrating the method",
+        "Creates or updates overwrite content for public extension method examples on the declaring extension class page or another readable type-targeted file under `.docfx/api/types/` while explicitly demonstrating the method",
         "Uses generated DocFX UIDs or verified metadata instead of inventing overwrite UIDs",
         "Runs the Completion Repair Loop after edits by rerunning scripts/docfx.cs --json, fixing remaining EXAMPLE_MISSING and overwrite-layout diagnostics, and updating the example inventory before claiming completion",
         "Uses --verify-docfx-build for final DocFX build verification",
@@ -177,10 +179,10 @@
     {
       "id": 14,
       "prompt": "Use dotnet-docfx-digest on a Carter-style repository where `EndpointConventionBuilderExtensions` has generic extension methods whose generated DocFX method UIDs look like `Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.<G>$6D0D8037DBBD61D10816ECA5F93B896F`. The previous run created `.docfx/api/Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.%3CG%3E%246D0D8037DBBD61D10816ECA5F93B896F.md`, added `// dotnet-docfx-digest:skip-compile - Full example requires Cuemon.Extensions.AspNetCore.Text.Yaml package`, and left the namespace page as a thin table. Repair the docs.",
-      "expected_output": "Agent removes or avoids the encoded/hash-like method UID filename, places extension-method examples in a readable declaring-class overwrite file such as `.docfx/api/namespaces/Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.md` or the namespace page, does not use a package-requirement skip marker as a compile escape hatch, either makes the sample compile or reports a precise deterministic blocker, and restores the namespace page as a curated overview with developer-friendly purpose, type-family context, extension-method groups, availability, and pointers to detailed examples.",
+      "expected_output": "Agent removes or avoids the encoded/hash-like method UID filename, places extension-method examples in a readable declaring-class overwrite file such as `.docfx/api/types/Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.md`, does not use a package-requirement skip marker as a compile escape hatch, either makes the sample compile or reports a precise deterministic blocker, and restores the namespace page as a curated overview with developer-friendly purpose, type-family context, extension-method groups, availability, and pointers to detailed examples.",
       "expectations": [
         "Does not create or keep URL-encoded/hash-like method UID filenames for generic extension methods such as `%3CG%3E%24...`",
-        "Uses a readable declaring extension class overwrite file or namespace page for extension-method examples",
+        "Uses a readable declaring extension class overwrite file under `.docfx/api/types/` for extension-method examples",
         "Ensures the example explicitly calls the documented extension method",
         "Does not use `// dotnet-docfx-digest:skip-compile - Full example requires ... package` as the final state",
         "Documents any required package or setup outside the code fence when relevant",
@@ -238,13 +240,13 @@
     {
       "id": 19,
       "prompt": "Run dotnet-docfx-digest with `--changed-only` after I edited a C# 14 extension-block file in the `Codebelt.Extensions.Carter` namespace: `public static class EndpointConventionBuilderExtensions { extension(IEndpointConventionBuilder builder) { public IEndpointConventionBuilder Produces<TResponse>(int statusCode = StatusCodes.Status200OK, params string[] contentTypes) { ... } } }`. The previous run created `.docfx/api/namespaces/EndpointConventionBuilderExtensions.Produces-extensions.md` whose YAML `uid` is `Codebelt.Extensions.Carter.EndpointConventionBuilderExtensions.<G>$6D0D8037DBBD61D10816ECA5F93B896F`, and the namespace page still needs a real extension-method example.",
-      "expected_output": "Agent treats the compiler-generated `<G>$...` container as an implementation artifact of the outer `EndpointConventionBuilderExtensions` type, so the repair path stays on readable declaring-class or namespace overwrite pages. `--changed-only` still notices the edited extension-block source file, surfaces the missing example work, and avoids treating the synthetic nested type as a standalone documented API target.",
+      "expected_output": "Agent treats the compiler-generated `<G>$...` container as an implementation artifact of the outer `EndpointConventionBuilderExtensions` type, so the repair path stays on readable declaring-class overwrite pages under `.docfx/api/types/`. `--changed-only` still notices the edited extension-block source file, surfaces the missing example work, and avoids treating the synthetic nested type as a standalone documented API target.",
       "expectations": [
         "Collapses compiler-generated extension-block containers such as `<G>$...` back to the authored outer static class when choosing extension-method example targets",
         "Does not treat the synthetic nested extension-block type as a required public type example target",
-        "Keeps the required example location on a readable declaring-class overwrite page or the namespace page instead of a synthetic method/type UID file",
+        "Keeps the required example location on a readable declaring-class overwrite page under `.docfx/api/types/` instead of a synthetic method/type UID file",
         "Under `--changed-only`, recognizes the edited extension-block source file as touching the `Produces` extension method even though the method declaration no longer uses `this` syntax",
-        "Still reports missing extension-method examples until a readable declaring-class or namespace overwrite file explicitly calls `Produces`"
+        "Still reports missing extension-method examples until a readable declaring-class overwrite file explicitly calls `Produces`"
       ]
     },
     {
@@ -338,11 +340,11 @@
     {
       "id": 27,
       "prompt": "Run dotnet-docfx-digest on a repository. Confirm that the validator does not depend on DocFX-generated hash filenames like `*.md.G-*` or URL-encoded method UID filenames as source truth.",
-      "expected_output": "Agent discovers required example targets from compiled assembly metadata, not from DocFX-generated hash filenames. It reports `EXAMPLE_MISSING` when no overwrite file under `api/types/` or the namespace page has an example for the required UID. Hash-named files that may exist from a previous run do not satisfy the example requirement.",
+      "expected_output": "Agent discovers required example targets from compiled assembly metadata, not from DocFX-generated hash filenames. It reports `EXAMPLE_MISSING` when no overwrite file under `api/types/` has an example for the required UID. Hash-named files that may exist from a previous run do not satisfy the example requirement.",
       "expectations": [
         "Discovers required example targets from compiled assembly reflection, not from DocFX hash filenames",
         "Does not use `*.md.G-*` files as evidence that an example exists",
-        "Reports `EXAMPLE_MISSING` even if a hash-named file exists but the correct UID is not in an overwrite file under `api/types/` or the namespace page",
+        "Reports `EXAMPLE_MISSING` even if a hash-named file exists but the correct UID is not in an overwrite file under `api/types/`",
         "Does not create hash-named overwrite files as repair actions"
       ]
     },
@@ -887,6 +889,18 @@
         "Checks specifically for repeated sentence and code structures across the pilot",
         "Presents representative output for human review before a full run"
       ]
+    },
+    {
+      "id": 74,
+      "prompt": "A prior dotnet-docfx-digest run put raw `uid:` / `example:` overwrite sections directly after `## Extension Members` inside `.docfx/api/namespaces/Acme.Extensions.Net.md`, so the namespace page now mixes overview content with extension-method examples. Repair the docs and keep the quality bar from the skill instructions.",
+      "expected_output": "Agent treats the namespace page as mixed-ownership documentation, surfaces or repairs the embedded-overwrite defect, keeps the namespace overview single-uid and namespace-scoped, moves the extension-method example mappings into readable type-targeted overwrite files under `.docfx/api/types/` (typically the declaring extension class page), reruns validation, and does not leave secondary `uid:` / `example:` blocks after the namespace overview.",
+      "expectations": [
+        "Recognizes or surfaces the namespace page as invalid mixed namespace/type content rather than accepting the embedded overwrite sections",
+        "Keeps `.docfx/api/namespaces/Acme.Extensions.Net.md` limited to the namespace uid/summary, fly-in prose, availability, related links, and `Extension Members` table",
+        "Moves extension-method examples to readable type-targeted overwrite files under `.docfx/api/types/`, typically the declaring extension class page",
+        "Does not append secondary `uid:` / `example:` sections after `Extension Members` on the namespace page",
+        "Reruns scripts/docfx.cs --json and treats any remaining namespace-ownership or example diagnostic as blocking completion"
+      ]
     }
   ]
 }
diff --git a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
index 3e7c485..282f7c4 100644
--- a/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
+++ b/skills/dotnet-docfx-digest/references/docfx-overwrite-files.md
@@ -25,7 +25,7 @@ The `X.Y.Z` namespace contains types that ...
 
 If `*content` is not used, DocFX assigns the Markdown body to the `conceptual` property. **Do not rely on this default for managed reference (API) pages.** When `conceptual` is set on a managed reference page, some DocFX templates suppress the auto-generated member tables (constructors, methods, properties), leaving only the custom content visible. Always use an explicit property mapping.
 
-For **type-page and extension-method examples**, use the `example` array property instead of `summary`:
+For **type-page and extension-method examples**, use the `example` array property instead of `summary` on a type-targeted overwrite file, usually the declaring extension class page under `.docfx/api/types/`:
 
 ```markdown
 ---
@@ -59,6 +59,8 @@ Do **not** use `summary: *content` for type example files. That replaces only th
 
 DocFX applies overwrite models by `uid`. If the same `uid` appears more than once in one overwrite file, later sections in that same file override earlier sections. Across different overwrite files, ordering is not deterministic, so keep competing sections for the same `uid` together or consolidate them.
 
+Namespace overview files are a deliberate exception to "multiple sections can work." Keep `.docfx/api/namespaces/{Namespace}.md` single-UID and namespace-scoped. Do not append secondary `uid:` / `example:` mappings there, even for extension methods; move those examples to readable type-targeted files under `.docfx/api/types/`, typically the declaring extension class page.
+
 ## Safe structured overwrite writer
 
 For repeatable overwrite creation, prefer `docfx.cs --write-overwrite <request.json>` over hand-assembling fenced Markdown with ad-hoc scripts. The request is JSON with `file`, `uid`, `mapping` (`example`, `summary`, or `remarks`), optional `prose`, and optional `fence`. The writer validates the YAML and balanced fences, refuses duplicate UIDs in the same file (`OVERWRITE_UID_DUPLICATE`), refuses unbalanced fences (`OVERWRITE_FENCE_UNBALANCED`), refuses to replace a file that already had uncommitted changes (`OVERWRITE_DIRTY_REFUSED`), preserves the target file's existing BOM and line endings, and prints a change preview. It writes only structured content you already authored — it never generates prose, selects members, or synthesizes examples. Normal surgical edits may still use your editor; the writer exists for repeatable, encoding-safe overwrite creation.
@@ -91,14 +93,14 @@ The `build.overwrite` entry in `docfx.json` tells DocFX which conceptual Markdow
 
 When a repository has no obvious overwrite location, inspect `docfx.json` first. Look at `build.content`, `build.overwrite`, `metadata.dest`, include paths, and existing Markdown layout before deciding where a new namespace page belongs.
 
-If a public non-abstraction type lacks an example, create a matching type-UID overwrite section in a separate per-type Markdown file by default, and make sure that file is included by `build.overwrite` so the example appears on the generated type API page. In Codebelt repositories, keep type overwrite files under `.docfx/api/types/{TypeUid}.md`, such as `.docfx/api/types/X.Y.Z.Class1.md`, and namespace overview pages under `.docfx/api/namespaces/{Namespace}.md`. File location does not decide whether the page is a namespace page or a type page; the YAML front matter `uid` does. Keep both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite`, exclude both `api/namespaces/**` and `api/types/**` from `build.content`, and do not use `api/**/*.md` under either section. If authored overwrite Markdown already exists directly under `.docfx/api/*.md`, move it into either `api/namespaces/` (for namespace UIDs) or `api/types/` (for type UIDs) without deleting the content. Namespace overview pages and `Extension Members` tables complement examples; they do not replace type-page examples.
+If a public non-abstraction type lacks an example, create a matching type-UID overwrite section in a separate per-type Markdown file by default, and make sure that file is included by `build.overwrite` so the example appears on the generated type API page. Extension-method examples follow the same type-targeted pattern by default: keep them on the declaring extension class page or another readable file under `.docfx/api/types/`, not inside the namespace overview file. In Codebelt repositories, keep type overwrite files under `.docfx/api/types/{TypeUid}.md`, such as `.docfx/api/types/X.Y.Z.Class1.md`, and namespace overview pages under `.docfx/api/namespaces/{Namespace}.md`. File location does not decide whether the page is a namespace page or a type page; the YAML front matter `uid` does. Keep both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite`, exclude both `api/namespaces/**` and `api/types/**` from `build.content`, and do not use `api/**/*.md` under either section. If authored overwrite Markdown already exists directly under `.docfx/api/*.md`, move it into either `api/namespaces/` (for namespace UIDs) or `api/types/` (for type UIDs) without deleting the content. Namespace overview pages and `Extension Members` tables complement examples; they do not replace type-page examples.
 
 ## Practical Rules
 
 - Run `agents.cs` before finishing so root `AGENTS.md` receives persistent DocFX maintenance guidance.
 - Use overwrite files to complement generated API metadata, not to hide incorrect XML documentation.
 - Correct bad XML comments at source when the generated summary is wrong.
-- Use namespace overview pages for namespace fly-ins and extension-member tables.
+- Use namespace overview pages only for namespace fly-ins and extension-member tables; keep type/member overwrite mappings out of them.
 - Keep examples and remarks close to the API item or namespace they explain.
 - Create per-type overwrite files for missing concrete-type examples even when the repository currently has only namespace overview files.
 - Keep namespace overview Markdown under `.docfx/api/namespaces/` and type overwrite Markdown under `.docfx/api/types/`. Move legacy `.docfx/api/*.md` files into the appropriate subdirectory: namespace UIDs go to `api/namespaces/`, type UIDs go to `api/types/`.
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 14a55c7..60d2e1d 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -194,6 +194,8 @@ If you're trying to ..., start with `PrimaryType` or `PrimaryExtensions`.
 
 Remove the `Extension Members` section when the namespace has no public extension methods. Adjust the include path to match the actual file location.
 
+Namespace overview files stay single-UID and stop after the fly-in, availability, related links, and optional `Extension Members` table. Do not append secondary `uid:` / `example:` mappings there; put extension-method examples on the declaring extension class page or another readable type-targeted file under `.docfx/api/types/`.
+
 ## Type example shape
 
 > **DocFX overwrite Markdown only.** This shape is for writing DocFX overwrite content. Do not create tests from it. Tests are evidence, not output — use tests to understand behavior, then transform that knowledge into consumer-facing examples.
@@ -263,7 +265,7 @@ Bad examples:
 - `EndpointConventionBuilderExtensions.-G-6D0D8037DBBD61D10816ECA5F93B896F.md`
 - `EndpointConventionBuilderExtensions.%3CT%3E...md`
 
-Keep the filename readable, place the example in the declaring extension class file or the namespace page, and let the YAML `uid` determine what model receives the content.
+Keep the filename readable, place the example in the declaring extension class file or another readable file under `.docfx/api/types/`, and let the YAML `uid` determine what model receives the content. Do not append member-level overwrite sections to the namespace page.
 
 ## Verification checklist
 

From 4d86303aef517d085f5533d5297204ee3070a014 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 16:18:13 +0200
Subject: [PATCH 79/88] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20enhance=20docfx=20sc?=
 =?UTF-8?q?ript=20with=20targeted=20improvements?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds precision to documentation validation and example handling. Improves diagnostic clarity and completion state reporting for better audit workflows.
---
 skills/dotnet-docfx-digest/scripts/docfx.cs | 38 ++++++++++++++++++---
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 3ef1b58..75709e6 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -3388,6 +3388,7 @@ private static void ValidateNamespacePage(string repoRoot, string page, string t
         }
 
         var (frontMatter, body) = SplitFrontMatter(text);
+        var namespaceBody = TrimNamespaceBody(body);
 
         // uid
         var uid = ReadYamlScalar(frontMatter, "uid");
@@ -3409,10 +3410,12 @@ private static void ValidateNamespacePage(string repoRoot, string page, string t
                 "Namespace page front matter is missing a 'summary' key (expected 'summary: *content')."));
         }
 
+        ValidateNamespacePageOwnership(page, rel, text, ns, report);
+
         // Concept-led namespace prose. A namespace inventory is useful reference material, but it
         // is not a developer-facing overview unless it explains when to use the surface and where
         // a newcomer should begin.
-        var proseParagraphs = ExtractNamespaceProseParagraphs(body);
+        var proseParagraphs = ExtractNamespaceProseParagraphs(namespaceBody);
         if (proseParagraphs.Count == 0)
         {
             report.Errors.Add(new Diagnostic("NAMESPACE_FLYIN_MISSING", rel, ns.Name,
@@ -3466,7 +3469,7 @@ private static void ValidateNamespacePage(string repoRoot, string page, string t
         }
 
         // availability
-        if (!HasAvailability(body))
+        if (!HasAvailability(namespaceBody))
         {
             report.Errors.Add(new Diagnostic("AVAILABILITY_MISSING", rel, ns.Name,
                 "Namespace page has no availability information (expected an availability include or explicit 'Availability:' text)."));
@@ -3475,10 +3478,31 @@ private static void ValidateNamespacePage(string repoRoot, string page, string t
         // extension members
         if (ns.ExtensionMethods.Count > 0)
         {
-            ValidateExtensionSection(rel, body, ns, report);
+            ValidateExtensionSection(rel, namespaceBody, ns, report);
         }
     }
 
+    private static void ValidateNamespacePageOwnership(string page, string rel, string text, NamespaceInfo ns, Report report)
+    {
+        var sections = ExtractOverwriteSections(page, text);
+        if (sections.Count <= 1)
+        {
+            return;
+        }
+
+        var embedded = sections.Skip(1).ToList();
+        var offendingUids = embedded.Select(section => $"`{section.Uid}`")
+            .Distinct(StringComparer.Ordinal)
+            .Take(6)
+            .ToList();
+        var remaining = embedded.Select(section => section.Uid).Distinct(StringComparer.Ordinal).Count() - offendingUids.Count;
+        var suffix = remaining > 0 ? $" and {remaining} more" : string.Empty;
+        report.Errors.Add(new Diagnostic("NAMESPACE_EMBEDDED_OVERWRITE_SECTION", rel, ns.Name,
+            $"Namespace page `{ns.Name}` contains additional overwrite section(s) after the namespace overview ({string.Join(", ", offendingUids)}{suffix}). " +
+            "Keep namespace overview files single-UID and namespace-scoped. Move type/member `uid:` / `example:` mappings to readable files under `api/types/`, " +
+            "typically the declaring extension class page, instead of appending them after `Extension Members`."));
+    }
+
     private static void ValidateExtensionSection(string rel, string body, NamespaceInfo ns, Report report)
     {
         var sectionMatch = Regex.Match(body, @"(?im)^#{2,4}\s+Extension\s+Members\s*$");
@@ -3612,6 +3636,12 @@ void Flush()
         return paragraphs;
     }
 
+    private static string TrimNamespaceBody(string body)
+    {
+        var nextOverwrite = Regex.Match(body, @"(?im)^---\s*$\nuid\s*:");
+        return nextOverwrite.Success ? body[..nextOverwrite.Index] : body;
+    }
+
     private static bool IsInventoryOnlyNamespaceProse(string paragraph)
     {
         return Regex.IsMatch(paragraph,
@@ -6977,7 +7007,7 @@ private static void AppendRequiredExampleDiagnostics(StringBuilder sb, IEnumerab
                     "Replace prose-only or metadata-only coverage with a C# scenario that invokes the extension method on a valid receiver.",
                 _ when diagnostic.Message.Contains("Public non-abstraction type", StringComparison.Ordinal) =>
                     "Search GitHub (see below), verify public API surface, create or update the type-targeting overwrite file under `api/types/`, keep `api/types/**/*.md` under `build.overwrite` only, add a compiling Examples section, then rerun validation.",
-                _ => "Search GitHub (see below), verify public API surface, add a compiling Examples section on the declaring extension class or namespace page that explicitly calls the extension method, then rerun validation."
+                _ => "Search GitHub (see below), verify public API surface, add a compiling Examples section on the declaring extension class page or another readable overwrite file under `api/types/` that explicitly calls the extension method, then rerun validation."
             };
             sb.AppendLine($"| {ns} | `{path}` | `{diagnostic.Code}` | {EscapeTable(action)} {message} |");
         }

From ada4fab6a6806b74d5d53f4647d568a430392486 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 17:03:16 +0200
Subject: [PATCH 80/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refine=20diagnostic?=
 =?UTF-8?q?=20iteration=20guidance=20in=20dotnet-docfx-digest?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clarifies skill behavior for diagnostic family transitions during repair loops. A rerun clearing one diagnostic and revealing another is expected progress, not a blocker. Agents must not stop with decision menus while repairable diagnostics remain. Updated both SKILL.md and references/workflow.md with consistent guidance.
---
 skills/dotnet-docfx-digest/SKILL.md               | 3 +++
 skills/dotnet-docfx-digest/references/workflow.md | 2 ++
 2 files changed, 5 insertions(+)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index 7c2cc14..f272b1b 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -41,6 +41,8 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 - `EXTENSION_TABLE_ENCODING` means the ⬇️ emoji (U+2B07) is missing or corrupted in an Extension Members table data row. Use the literal `⬇️` character, not HTML entities or text substitutes.
 - If either script cannot run, report the exact command, exit code, and failure output. Do not claim repository guidance or documentation was verified unless the scripts actually ran successfully.
 - Treat validator errors as the repo-wide repair queue, not as evidence that the repository is "blocked." A diagnostic being old, pre-existing, numerous, or outside the first files edited does not remove it from scope. A run with 1,228 `EXAMPLE_MISSING` findings means 1,228 documentation items remain; repairing one type page is a partial result, not a digest.
+- A rerun that clears a coarse diagnostic and reveals a more specific one is progress, not a blocker. If `EXTENSION_SECTION_MISSING` drops and `EXTENSION_METHOD_MISSING` appears, or namespace/table repairs expose more `EXAMPLE_MISSING` targets, treat the newly surfaced codes as the next deterministic queue and keep repairing.
+- Do not turn partial progress into a decision menu. While repairable diagnostics remain, never stop to ask whether to continue, focus a subset, or "just run verification." Only ask the user to choose when inspection exposes a real correctness-affecting decision or a genuine external blocker stops further execution.
 - Passing compilation is necessary but not sufficient. `EXAMPLE_PLACEHOLDER`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, and `EXAMPLE_UID_DUPLICATE` are blocking quality failures. Never satisfy the inventory with `Type.GetType`, assembly metadata inspection, `DocumentedTypeExample`, `DocumentedExtensionExample`, generic `Describe()` helpers, repeated UID sections, prose that merely names the target, a `default!`/`null!` holder property that only parks the type, a class that just constructs or returns the target with no observable result, a mass-forwarding shell of one-line pass-through members, or one normalized code skeleton reused across unrelated types.
 - Namespace prose must be decision-useful. `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING` mean the page still needs a problem/outcome opening, a cohesively rewritten lead instead of a weak inventory sentence with guidance appended below it, an opening written from the namespace's own purpose rather than a shared template, concrete "when to use" guidance, and a named starting API when the namespace has multiple entry points.
 - Namespace overview files are single-UID deliverables. `NAMESPACE_EMBEDDED_OVERWRITE_SECTION` means the page mixed namespace guidance with secondary `uid:` / `example:` mappings after the overview, often below `Extension Members`. Move those type/member examples to readable type-targeted files under `.docfx/api/types/`, usually the declaring extension class page, and keep the namespace page limited to the namespace fly-in, availability, related links, and optional `Extension Members` table.
@@ -81,6 +83,7 @@ When continuing after another agent stopped with diagnostics remaining:
 3. Use the repair plan and example inventory as the active queue across all affected namespaces, type pages, extension classes, and extension methods.
 4. Repair manageable batches, then rerun the fast validator after each batch so the queue measurably shrinks; do not stop after a representative subset.
 5. Run the exact final command `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json` and continue until the completion contract is clean.
+6. If a rerun replaces one diagnostic family with a more specific follow-on family, keep going. Do not convert that newly exposed queue into a progress summary or a request for approval to continue.
 
 ## Core Principles
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index 60d2e1d..a99d0e4 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -108,6 +108,8 @@ The conservative source scanner is for fast Markdown iteration, not authoritativ
 
 Target counts, diagnostic volume, ownership complexity, context pressure, and model usage limits never change the requested scope. A full run remains full regardless of queue size. Use project packets to keep authoring context bounded, continue through independent packets when one packet needs more debugging, and return to every unresolved diagnostic before final verification. Use dry-run only when the user explicitly requests a dry run, representative subset, or quality pilot.
 
+Reruns often replace a coarse queue with a more specific one: for example, `EXTENSION_SECTION_MISSING` may shrink only for `EXTENSION_METHOD_MISSING` to appear once the tables exist, or namespace repairs may surface the next layer of `EXAMPLE_MISSING` work. Treat that handoff as expected progress. Do not stop to summarize partial progress, ask whether to continue, or offer a "focus this area vs. just verify" menu while repairable diagnostics remain.
+
 ### Working-tree dry run
 
 Dry run is a limited real run that writes useful documentation directly to the working tree. The validator selects and verifies; the agent performs the evidence-based authoring between those invocations:

From fb9057b543f4ce4df823baf5f98c34e2b69a1b66 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 17:03:23 +0200
Subject: [PATCH 81/88] =?UTF-8?q?=E2=9C=A8=20expand=20eval=20test=20covera?=
 =?UTF-8?q?ge=20for=20diagnostic=20transitions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds eval case 75 to test agent behavior when diagnostic families transition during repair loops. Test validates that agents recognize newly surfaced queues (e.g., EXTENSION_METHOD_MISSING appearing after EXTENSION_SECTION_MISSING is cleared) as expected progress and continue repairs without decision menus or progress summaries. Also updates an existing eval expectation to require that agents do not stop with progress summaries while diagnostics remain.
---
 skills/dotnet-docfx-digest/evals/evals.json | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 4925368..be46944 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -660,6 +660,7 @@
         "Inspects and preserves the 8 untracked namespace pages, 1 untracked type page, and other existing documentation edits instead of discarding or overwriting them wholesale",
         "Explicitly identifies the prior output as partial because 62 extension-section, 1228 example, and 1 DocFX-build diagnostics remain",
         "Does not describe pre-existing diagnostics, diagnostic volume, or the size of the work queue as a blocker",
+        "Does not stop with a progress summary or ask the user whether to continue while repairable diagnostics remain",
         "Uses the deterministic repair plan and complete validator queue to continue repairing every missing extension section and example across the affected documentation surfaces",
         "Reports the SQL Server integration-test failure separately and continues DocFX repair because the failure does not prevent documentation validation or source inspection",
         "Reruns the fast validator after batches of edits instead of stopping after the first namespace or type subset",
@@ -901,6 +902,18 @@
         "Does not append secondary `uid:` / `example:` sections after `Extension Members` on the namespace page",
         "Reruns scripts/docfx.cs --json and treats any remaining namespace-ownership or example diagnostic as blocking completion"
       ]
+    },
+    {
+      "id": 75,
+      "prompt": "Use dotnet-docfx-digest on a Cuemon-style repository. After your first repair batch, fast validation drops `EXTENSION_SECTION_MISSING` from 62 to 16 and clears `NAMESPACE_APPEND_ONLY_REPAIR`, but a deeper queue appears: `EXTENSION_METHOD_MISSING` jumps to 125 because the new `Extension Members` tables are incomplete. `EXAMPLE_MISSING` is still over 1,200.",
+      "expected_output": "The agent treats the newly surfaced `EXTENSION_METHOD_MISSING` findings as the next deterministic queue, keeps the original repo-wide scope, updates extension tables and required examples packet by packet, reruns fast validation between batches, and does not stop with a progress summary or a choice menu. It continues until the build-backed verification succeeds and the JSON completion contract is clean.",
+      "expectations": [
+        "Recognizes the newly surfaced `EXTENSION_METHOD_MISSING` queue as progress rather than as a blocker or a reason to pause",
+        "Does not offer a continue/focus/verify menu or ask the user how to proceed while repairable diagnostics remain",
+        "Keeps the original full-repository scope instead of narrowing to a representative subset or dry run",
+        "Uses packeted batches plus fast reruns to repair incomplete extension tables and the remaining example inventory",
+        "Runs the final build-backed command with `--build-api-model --validate-samples --verify-docfx-build` and does not claim completion until summary.canClaimCompletion is true with no remaining work items, gates, or diagnostics"
+      ]
     }
   ]
 }

From e9f1ba275b97b0eafe1d11a8dc7ce9c812cdd89e Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 17:03:29 +0200
Subject: [PATCH 82/88] =?UTF-8?q?=F0=9F=93=9D=20update=20readme=20for=20di?=
 =?UTF-8?q?agnostic=20iteration=20clarity?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refreshes the dotnet-docfx-digest skill entry to reflect improved guidance on diagnostic family transitions and agent behavior during repair loops.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8d32830..e05e8d7 100644
--- a/README.md
+++ b/README.md
@@ -105,7 +105,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class type pages under `.docfx/api/types/` instead of synthetic method-UID filenames or namespace pages that mix extra `uid:` / `example:` blocks into the overview, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class type pages under `.docfx/api/types/` instead of synthetic method-UID filenames or namespace pages that mix extra `uid:` / `example:` blocks into the overview, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, treats newly surfaced follow-on diagnostics as the next repair queue instead of a stop point, never turns partial progress into a continue/focus/verify menu while repairable work remains, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 

From 79ba0abbd8b212bf46173ccb2e6c9c51bbccd476 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 17:29:58 +0200
Subject: [PATCH 83/88] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20expand=20core=20auth?=
 =?UTF-8?q?oring=20and=20execution=20guidance=20in=20dotnet-docfx-digest?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reinforces critical principles for EXAMPLE_MISSING queue management: it is the core authoring queue, not optional backlog, and must continue until it reaches zero. Clarifies that context limits, queue size, and time estimates are internal concerns, not user-facing stop conditions. Adds guidance on handling diagnostic family transitions, preventing decision menus during repairs, and continuing through verification phases. Also expands Completion Repair Loop with explicit continuation semantics and batch-authoring patterns. Updated both SKILL.md and references/workflow.md with consistent, reinforced guidance.
---
 skills/dotnet-docfx-digest/SKILL.md           | 22 ++++++++++++++-----
 .../references/workflow.md                    | 20 +++++++++++++++++
 2 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index f272b1b..c761f00 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -43,6 +43,8 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 - Treat validator errors as the repo-wide repair queue, not as evidence that the repository is "blocked." A diagnostic being old, pre-existing, numerous, or outside the first files edited does not remove it from scope. A run with 1,228 `EXAMPLE_MISSING` findings means 1,228 documentation items remain; repairing one type page is a partial result, not a digest.
 - A rerun that clears a coarse diagnostic and reveals a more specific one is progress, not a blocker. If `EXTENSION_SECTION_MISSING` drops and `EXTENSION_METHOD_MISSING` appears, or namespace/table repairs expose more `EXAMPLE_MISSING` targets, treat the newly surfaced codes as the next deterministic queue and keep repairing.
 - Do not turn partial progress into a decision menu. While repairable diagnostics remain, never stop to ask whether to continue, focus a subset, or "just run verification." Only ask the user to choose when inspection exposes a real correctness-affecting decision or a genuine external blocker stops further execution.
+- `EXAMPLE_MISSING` is the core authoring queue, not optional backlog. Even when it is the only remaining diagnostic family and the count is in the hundreds or thousands, the digest is still incomplete. Do not stop for a checkpoint, completion report, approval pause, dry-run suggestion, or next-step menu; keep creating compiling examples until `EXAMPLE_MISSING` reaches zero.
+- Treat the next unaddressed `EXAMPLE_MISSING` diagnostic as the only thing that exists. Work it, rerun, then work the next. Counts, percentages, and "remaining work" numbers are progress indicators, not decision points.
 - Passing compilation is necessary but not sufficient. `EXAMPLE_PLACEHOLDER`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, and `EXAMPLE_UID_DUPLICATE` are blocking quality failures. Never satisfy the inventory with `Type.GetType`, assembly metadata inspection, `DocumentedTypeExample`, `DocumentedExtensionExample`, generic `Describe()` helpers, repeated UID sections, prose that merely names the target, a `default!`/`null!` holder property that only parks the type, a class that just constructs or returns the target with no observable result, a mass-forwarding shell of one-line pass-through members, or one normalized code skeleton reused across unrelated types.
 - Namespace prose must be decision-useful. `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING` mean the page still needs a problem/outcome opening, a cohesively rewritten lead instead of a weak inventory sentence with guidance appended below it, an opening written from the namespace's own purpose rather than a shared template, concrete "when to use" guidance, and a named starting API when the namespace has multiple entry points.
 - Namespace overview files are single-UID deliverables. `NAMESPACE_EMBEDDED_OVERWRITE_SECTION` means the page mixed namespace guidance with secondary `uid:` / `example:` mappings after the overview, often below `Extension Members`. Move those type/member examples to readable type-targeted files under `.docfx/api/types/`, usually the declaring extension class page, and keep the namespace page limited to the namespace fly-in, availability, related links, and optional `Extension Members` table.
@@ -56,7 +58,11 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 - When reporting heartbeat behavior, state the complete contract: append-only `stderr`, no cursor-rewritten table, start and 10-second heartbeat events, final success/failure marker for all three long phases, latest non-empty child-output line when available, and plain redirected-log markers that do not depend on ANSI color. When reporting encoding safety, explicitly confirm the diff contains neither BOM-only nor line-ending-only changes.
 - Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape.
 - Prefer bounded project packets over one repository-sized authoring context. Discover packets with `docfx.cs --json` (`scope.packets`) or persist them with `--project-manifest <path>`; process one packet at a time while keeping the user's requested scope unchanged. Repair packet-local diagnostics before moving on when practical. If one diagnostic remains difficult after concrete attempts, record it, continue independent packets, and return to it; never turn one repairable packet failure into a reason to stop a full-repository run. Establish reflection-precise scope with `--build-api-model` before authoring — when `summary.scopeState` is `provisional` and `BUILD_BACKED_SCOPE_REQUIRED` fires, the source-scan inventory must not authorize a full authoring run.
+- If a fast `--project-manifest` or `scope.packets` result contains unnamed packets, zero projects, or `metadataGroup: unknown`, that is a provisional source-scan artifact. Immediately rerun packet discovery with `--build-api-model --project-manifest <temp-path>` (or use generated DocFX YAML) and continue from the reflection-backed packet set. Do not treat weak fast-packet metadata as a blocker or as justification to stop.
+- If build-backed packet discovery still fails or remains unusable, fall back to sequential repair instead of stopping. Use the repair-plan order or sort the remaining `EXAMPLE_MISSING` diagnostics by namespace, clear the first namespace (or the next 3-5 examples in it), rerun the fast validator, then continue to the next namespace.
 - Repository size, target count, diagnostic volume, context pressure, and model usage limits never change the user's requested scope. An explicit or default repo-wide run continues across every packet until the global completion contract is clean.
+- Context limits, queue size, and estimates like "this would take multiple sessions" are internal execution concerns, not user-facing stop conditions. Break the work into packets and keep going until the completion contract is clean unless the user explicitly pauses or a real external blocker prevents further progress.
+- Final build-backed verification (`--build-api-model --validate-samples --verify-docfx-build`) is for claiming completion, not for blocking incremental progress. While `summary.remainingWorkItems` is greater than zero or any diagnostics remain, stay on the fast `docfx.cs --json` loop and keep authoring.
 - Dry run is a voluntary mode used only when the user explicitly asks for `dry-run`, a representative sample, or a quality pilot. Never infer it from repository size, diagnostic count, context pressure, or model usage limits. It is a real run scoped to a representative subset, with identical evidence, authoring, quality, and compilation gates. Start it with `--dry-run --build-api-model --project-manifest <temp-path>`; this also emits a sibling `<name>.review.json` template. Author every selected packet, read every changed page, complete every review entry with evidence, page-specific purpose/outcome, observable result, and sibling prose/code comparison, then finish with `--resume-project-manifest <temp-path> --review-report <review-path> --build-api-model --validate-samples --verify-docfx-build`. The baseline protects pre-existing dirty work while allowing current-run files to verify. No-hint dry runs select one clean project per metadata destination group via a seed; explicit names override selection. Report `dry-run-passed` only after every gate passes, and include the completed `Changed-page review` table in the response; a validator summary is not a manual review. Never claim repository completion. Do not ask for hints when none were supplied.
 - Use the safe structured overwrite writer (`docfx.cs --write-overwrite <request.json>`) for repeatable overwrite creation: it preserves BOM/line endings, rejects duplicate UIDs and unbalanced fences, and refuses to replace dirty files. It writes only content you authored — it never generates prose or examples.
 - Declare narrow family exemptions in `.docfx/family-exemptions.json` only for coherent generic-arity, inherited, overload, or type-parameter series. The anchor needs a real example and the namespace page must name it and explain sibling selection; category alone never exempts options, exceptions, delegates, records, or data carriers. See `references/workflow.md`.
@@ -69,8 +75,12 @@ Do not stop at namespace pages, extension-member tables, or a first-pass documen
 2. Treat every missing, placeholder, reflection-only, target-use, extension-invocation, duplicate-UID, namespace-prose, extension-table, availability, and overwrite-layout diagnostic as blocking follow-up work.
 3. For each missing public concrete-type example, create or update a type-targeting overwrite file under `.docfx/api/types/`.
 4. For each missing extension-method example, document it on the declaring extension class page or another readable type-targeted overwrite file under `.docfx/api/types/`, and explicitly demonstrate the method call. Do not append secondary `uid:` / `example:` blocks to the namespace page.
-5. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too and rerun until the JSON completion contract is clean.
-6. Do not convert repairable diagnostics into a blocker report. A stubborn diagnostic is a debugging task: inspect the complete implicated UID/path set, validator normalization, source evidence, and related examples; fix either the content or a proven validator defect, then rerun. Continue unrelated packets while investigating when doing so preserves quality. Stop incomplete only when the user pauses the task or a genuine external condition prevents further execution; report the exact command, exit code, and blocker without claiming completion.
+5. Treat the next `EXAMPLE_MISSING` diagnostic as the current task. Read the target's public API surface and one relevant test or usage source, write a consumer-facing example to the correct type-targeted overwrite file, rerun the fast validator, then move to the next diagnostic.
+6. A batch can be as small as 3-5 examples, or whatever fits in the current turn. It does not need to be an architecturally complete namespace or packet; completeness emerges from fix → rerun → fix → rerun repetition.
+7. When only `EXAMPLE_MISSING` remains, that is still the main digest work, not a checkpoint. Keep authoring type and extension examples packet by packet; do not replace the queue with a completion summary, progress report, user choice menu, or final verification pass.
+8. If packet discovery from the fast source-scan yields unnamed or zero-project packets, rerun `--build-api-model --project-manifest <temp-path>` before continuing example authoring. If the build-backed packet set is still unusable, fall back to sequential repair in repair-plan or namespace order instead of stopping.
+9. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too and rerun until the JSON completion contract is clean.
+10. Do not convert repairable diagnostics into a blocker report. A stubborn diagnostic is a debugging task: inspect the complete implicated UID/path set, validator normalization, source evidence, and related examples; fix either the content or a proven validator defect, then rerun. Continue unrelated packets while investigating when doing so preserves quality. Stop incomplete only when the user pauses the task or a genuine external condition prevents further execution; report the exact command, exit code, and blocker without claiming completion.
 
 Namespace pages and `Extension Members` tables complement type-page examples; they do not replace them. Both namespace pages (`api/namespaces/`) and type pages (`api/types/`) are required deliverables. Generating only one is incomplete work.
 
@@ -81,9 +91,11 @@ When continuing after another agent stopped with diagnostics remaining:
 1. Inspect `git status --short --untracked-files=all`, enumerate the stated counts and paths, and preserve every existing tracked and untracked documentation edit, not only the newly created namespace/type files. Do not collapse a concrete inventory such as “8 namespace pages and 1 type page” into a generic promise to preserve work.
 2. Rerun the fast validator with `--json --repair-plan <temp-path>` and read the generated plan.
 3. Use the repair plan and example inventory as the active queue across all affected namespaces, type pages, extension classes, and extension methods.
-4. Repair manageable batches, then rerun the fast validator after each batch so the queue measurably shrinks; do not stop after a representative subset.
-5. Run the exact final command `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json` and continue until the completion contract is clean.
-6. If a rerun replaces one diagnostic family with a more specific follow-on family, keep going. Do not convert that newly exposed queue into a progress summary or a request for approval to continue.
+4. If only `EXAMPLE_MISSING` remains, keep going. That queue is not a stopping point. When packet ownership is unclear from the fast run, write a reflection-backed manifest with `--build-api-model --project-manifest <temp-path>` and use that manifest as the example-authoring queue instead of presenting a checkpoint or options.
+5. If the build-backed packet set is still unusable, fall back to sequential example repair in repair-plan or namespace order. Clear the next 3-5 examples, rerun, then continue.
+6. Repair manageable batches, then rerun the fast validator after each batch so the queue measurably shrinks; do not stop after a representative subset.
+7. Run the exact final command `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json` only when you are ready to claim completion, and continue until the completion contract is clean.
+8. If a rerun replaces one diagnostic family with a more specific follow-on family, keep going. Do not convert that newly exposed queue into a progress summary or a request for approval to continue.
 
 ## Core Principles
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index a99d0e4..be7d456 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -104,12 +104,32 @@ Full and dry runs use **identical** evidence, authoring instructions, semantic-q
 
 The conservative source scanner is for fast Markdown iteration, not authoritative scope. When `summary.apiModelSource` is `source-scan`, scope is `provisional` and the validator emits `BUILD_BACKED_SCOPE_REQUIRED`. Before authoring a full run or a selected dry-run packet, establish reflection-precise scope with `--build-api-model` (or generate DocFX managed-reference YAML). Treat a material fast/build-backed discrepancy as a blocker, not a rounding error.
 
+A fast `--project-manifest` result that yields unnamed packets, `projects: []`, or `metadataGroup: unknown` is not a usable plan for large example queues. That is still provisional source-scan scope. Immediately rerun packet discovery with `--build-api-model --project-manifest <temp-path>` (or use generated DocFX YAML) before planning example authoring, then continue from the reflection-backed packet set.
+
 ### Scope stability
 
 Target counts, diagnostic volume, ownership complexity, context pressure, and model usage limits never change the requested scope. A full run remains full regardless of queue size. Use project packets to keep authoring context bounded, continue through independent packets when one packet needs more debugging, and return to every unresolved diagnostic before final verification. Use dry-run only when the user explicitly requests a dry run, representative subset, or quality pilot.
 
 Reruns often replace a coarse queue with a more specific one: for example, `EXTENSION_SECTION_MISSING` may shrink only for `EXTENSION_METHOD_MISSING` to appear once the tables exist, or namespace repairs may surface the next layer of `EXAMPLE_MISSING` work. Treat that handoff as expected progress. Do not stop to summarize partial progress, ask whether to continue, or offer a "focus this area vs. just verify" menu while repairable diagnostics remain.
 
+An example-only queue is still incomplete. When `EXAMPLE_MISSING` is the only remaining diagnostic family — even 1,086 of them — the correct next step is more example authoring, not a completion report, checkpoint, final verification pass, dry-run suggestion, or user choice menu. Internal worries like "this is massive", "this will take multiple sessions", or "this may exceed context limits" are not user-facing stop conditions; solve them with packets and keep going.
+
+### EXAMPLE_MISSING micro-loop
+
+When the queue is dominated by `EXAMPLE_MISSING`, shrink your mental scope to the next concrete target instead of the total count.
+
+1. Take the next `EXAMPLE_MISSING` diagnostic from the repair plan or current fast-validator output.
+2. Read that target's public API surface and one relevant test, sample, or usage source.
+3. Write one consumer-facing example to the correct type-targeted overwrite file.
+4. Rerun the fast validator.
+5. Repeat for the next 3-5 examples, or whatever fits safely in the current turn.
+
+A "batch" does not need to be an architecturally complete namespace, packet, or package. A batch is any set of examples you can finish confidently before rerunning validation. Completeness emerges from iteration.
+
+If packet discovery stays weak even after `--build-api-model`, fall back to sequential repair in repair-plan order or alphabetical namespace order. Clear the next namespace's remaining examples (or the next 3-5 examples in it), rerun, and continue. A tool limitation is not a decision point.
+
+Final verification with `--build-api-model --validate-samples --verify-docfx-build` is reserved for the moment you intend to claim completion. While `remainingWorkItems > 0` or any diagnostics remain, stay on the fast `docfx.cs --json` loop and keep authoring.
+
 ### Working-tree dry run
 
 Dry run is a limited real run that writes useful documentation directly to the working tree. The validator selects and verifies; the agent performs the evidence-based authoring between those invocations:

From 1b6018ffdd65e7f0013994e33dc42375d663140b Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 17:30:06 +0200
Subject: [PATCH 84/88] =?UTF-8?q?=E2=9C=A8=20expand=20eval=20coverage=20fo?=
 =?UTF-8?q?r=20EXAMPLE=5FMISSING=20queue=20and=20execution=20semantics?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds new eval cases testing agent behavior when EXAMPLE_MISSING is the sole remaining diagnostic (test validates agents continue authoring rather than creating completion reports or decision menus) and when large example queues require batched authoring across multiple turns. Tests reinforce that context limits and queue size are internal execution concerns, not user-facing blockers. Ensures agents maintain continuous repair semantics even with diagnostic volume or scope complexity.
---
 skills/dotnet-docfx-digest/evals/evals.json | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index be46944..2ca0483 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -914,6 +914,20 @@
         "Uses packeted batches plus fast reruns to repair incomplete extension tables and the remaining example inventory",
         "Runs the final build-backed command with `--build-api-model --validate-samples --verify-docfx-build` and does not claim completion until summary.canClaimCompletion is true with no remaining work items, gates, or diagnostics"
       ]
+    },
+    {
+      "id": 76,
+      "prompt": "Use dotnet-docfx-digest on a Cuemon-style repository after several repair batches. All non-example diagnostics are gone, but `EXAMPLE_MISSING` is still 1086. A fast `--project-manifest` run returns unnamed packets with `projects: []` and `metadataGroup: unknown` because the scope is still source-scan provisional.",
+      "expected_output": "The agent treats the 1086 `EXAMPLE_MISSING` items as the active core work, not a checkpoint. It does not produce a completion report, next-step menu, or approval pause. Instead it reruns packet discovery with `--build-api-model --project-manifest`, continues authoring type and extension examples packet by packet from that reflection-backed manifest, and if the packet set is still unusable it falls back to sequential repair in repair-plan or namespace order. It works the queue in small fix→rerun batches and delays final verification until the example queue is actually finished.",
+      "expectations": [
+        "Does not treat an example-only queue or its size as a reason to stop, summarize, checkpoint, or ask the user how to proceed",
+        "Does not offer a continue/focus/dry-run/review menu while `EXAMPLE_MISSING` remains non-zero",
+        "Recognizes unnamed or zero-project fast-manifest packets as provisional source-scan output and reruns packet discovery with `--build-api-model --project-manifest`",
+        "If the build-backed packet set is still unusable, falls back to sequential repair in repair-plan or namespace order instead of stopping",
+        "Uses a small fix → rerun micro-loop for examples rather than treating batch size as a planning blocker",
+        "Does not run a final completion report or completion-shaped verification pass while `EXAMPLE_MISSING` still remains",
+        "Continues example authoring and reserves `--build-api-model --validate-samples --verify-docfx-build` for the real end of the queue"
+      ]
     }
   ]
 }

From 4494acfa7d02ef2407082de0b234464eac229256 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 17:30:13 +0200
Subject: [PATCH 85/88] =?UTF-8?q?=F0=9F=93=9D=20update=20readme=20for=20ex?=
 =?UTF-8?q?panded=20authoring=20and=20execution=20guidance?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refreshes the dotnet-docfx-digest skill entry to reflect clarified principles on EXAMPLE_MISSING queue continuity, execution semantics, and batch-authoring patterns. Emphasizes that documentation repair continues until the completion contract is clean, with no user-facing decision menus during diagnostic iteration.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e05e8d7..4877916 100644
--- a/README.md
+++ b/README.md
@@ -105,7 +105,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class type pages under `.docfx/api/types/` instead of synthetic method-UID filenames or namespace pages that mix extra `uid:` / `example:` blocks into the overview, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, treats newly surfaced follow-on diagnostics as the next repair queue instead of a stop point, never turns partial progress into a continue/focus/verify menu while repairable work remains, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed `--build-api-model --validate-samples --verify-docfx-build` verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class type pages under `.docfx/api/types/` instead of synthetic method-UID filenames or namespace pages that mix extra `uid:` / `example:` blocks into the overview, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, treats newly surfaced follow-on diagnostics as the next repair queue instead of a stop point, reruns packet discovery with `--build-api-model --project-manifest` when fast source-scan packets are unnamed or zero-project, falls back to sequential namespace or repair-plan order when packet discovery is still unusable, treats `EXAMPLE_MISSING`-only queues as core work rather than checkpoints, drives large example queues through a concrete fast-path micro-loop (next example or next 3-5 examples → rerun → continue), reserves the final `--build-api-model --validate-samples --verify-docfx-build` verification for the real end of the queue, never turns partial progress into a continue/focus/verify menu or completion report while repairable work remains, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 

From a754e5fb443c198a306aeeb8b5be27e31152f39d Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 18:00:02 +0200
Subject: [PATCH 86/88] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20dotnet-do?=
 =?UTF-8?q?cfx-digest=20with=20assessment-queue=20terminology?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update skill contract and implementation to use 'assessment-queue' terminology instead of 'repair-plan' throughout SKILL.md, eval definitions, reference documentation, and script implementations. This improves clarity around the diagnostic work queue concept used in the skill's documentation repair loop.
---
 skills/dotnet-docfx-digest/SKILL.md           | 18 ++++----
 skills/dotnet-docfx-digest/evals/evals.json   | 16 +++----
 .../dotnet-docfx-digest/references/scripts.md | 14 +++---
 .../references/workflow.md                    | 12 +++---
 skills/dotnet-docfx-digest/scripts/docfx.cs   | 43 ++++++++++---------
 .../scripts/test-quality.ps1                  | 23 +++++++++-
 6 files changed, 73 insertions(+), 53 deletions(-)

diff --git a/skills/dotnet-docfx-digest/SKILL.md b/skills/dotnet-docfx-digest/SKILL.md
index c761f00..d9fdf6c 100644
--- a/skills/dotnet-docfx-digest/SKILL.md
+++ b/skills/dotnet-docfx-digest/SKILL.md
@@ -29,13 +29,13 @@ dotnet run --file <resolved-skill-dir>/scripts/docfx.cs -- --repo-root <repo-roo
 ```
 
 - `--build-api-model` makes API discovery reflection-precise (the fast source-scan path is conservative and may under-report), `--validate-samples` compiles every C# documentation sample through isolated projects in one temporary `.slnx` graph build with bounded MSBuild parallelism, and `--verify-docfx-build` confirms the DocFX build succeeds. Treat `API_MODEL_SOURCE_SCANNER_LIMITED` in a fast run as a reminder to run the build-backed verification before completion, not as a failure.
-- For noisy audits, write and read a deterministic `--repair-plan` (works on the fast path; add `--search-examples` to embed real GitHub usage):
+- For noisy audits, write and read a deterministic assessment work queue with `--assessment-queue`. This works on the fast path; add `--search-examples` to embed real GitHub usage:
 
 ```bash
-dotnet run --file docfx.cs -- --repo-root <repo-root> --json --repair-plan /tmp/docfx-repair-plan.md --search-examples
+dotnet run --file docfx.cs -- --repo-root <repo-root> --json --assessment-queue /tmp/docfx-assessment-queue.md --search-examples
 ```
 
-The repair plan includes a "GitHub Example Sources" section with pre-computed `gh search code` commands and GitHub search URLs for each documented package. Read that section before writing any new example — do not write examples from memory or invention when real source evidence is available. If `--search-examples` is provided and `gh` is authenticated, actual search results are embedded; otherwise, the search commands are ready to run.
+The assessment work queue includes a "GitHub Example Sources" section with pre-computed `gh search code` commands and GitHub search URLs for each documented package. Read that section before writing any new example — do not write examples from memory or invention when real source evidence is available. If `--search-examples` is provided and `gh` is authenticated, actual search results are embedded; otherwise, the search commands are ready to run.
 
 - `ENCODING_CORRUPTION` in the JSON output means a documentation file has double-encoded UTF-8 (mojibake). Restore with `git checkout HEAD -- <file>` if the committed version was correct, or use the edit tool or byte-level operations to rewrite the file safely. Never pipe content through `Get-Content` + `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes()` on documentation files that contain multi-byte characters or emoji.
 - `EXTENSION_TABLE_ENCODING` means the ⬇️ emoji (U+2B07) is missing or corrupted in an Extension Members table data row. Use the literal `⬇️` character, not HTML entities or text substitutes.
@@ -59,7 +59,7 @@ The repair plan includes a "GitHub Example Sources" section with pre-computed `g
 - Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape.
 - Prefer bounded project packets over one repository-sized authoring context. Discover packets with `docfx.cs --json` (`scope.packets`) or persist them with `--project-manifest <path>`; process one packet at a time while keeping the user's requested scope unchanged. Repair packet-local diagnostics before moving on when practical. If one diagnostic remains difficult after concrete attempts, record it, continue independent packets, and return to it; never turn one repairable packet failure into a reason to stop a full-repository run. Establish reflection-precise scope with `--build-api-model` before authoring — when `summary.scopeState` is `provisional` and `BUILD_BACKED_SCOPE_REQUIRED` fires, the source-scan inventory must not authorize a full authoring run.
 - If a fast `--project-manifest` or `scope.packets` result contains unnamed packets, zero projects, or `metadataGroup: unknown`, that is a provisional source-scan artifact. Immediately rerun packet discovery with `--build-api-model --project-manifest <temp-path>` (or use generated DocFX YAML) and continue from the reflection-backed packet set. Do not treat weak fast-packet metadata as a blocker or as justification to stop.
-- If build-backed packet discovery still fails or remains unusable, fall back to sequential repair instead of stopping. Use the repair-plan order or sort the remaining `EXAMPLE_MISSING` diagnostics by namespace, clear the first namespace (or the next 3-5 examples in it), rerun the fast validator, then continue to the next namespace.
+- If build-backed packet discovery still fails or remains unusable, fall back to sequential repair instead of stopping. Use the assessment work queue order or sort the remaining `EXAMPLE_MISSING` diagnostics by namespace, clear the first namespace (or the next 3-5 examples in it), rerun the fast validator, then continue to the next namespace.
 - Repository size, target count, diagnostic volume, context pressure, and model usage limits never change the user's requested scope. An explicit or default repo-wide run continues across every packet until the global completion contract is clean.
 - Context limits, queue size, and estimates like "this would take multiple sessions" are internal execution concerns, not user-facing stop conditions. Break the work into packets and keep going until the completion contract is clean unless the user explicitly pauses or a real external blocker prevents further progress.
 - Final build-backed verification (`--build-api-model --validate-samples --verify-docfx-build`) is for claiming completion, not for blocking incremental progress. While `summary.remainingWorkItems` is greater than zero or any diagnostics remain, stay on the fast `docfx.cs --json` loop and keep authoring.
@@ -78,7 +78,7 @@ Do not stop at namespace pages, extension-member tables, or a first-pass documen
 5. Treat the next `EXAMPLE_MISSING` diagnostic as the current task. Read the target's public API surface and one relevant test or usage source, write a consumer-facing example to the correct type-targeted overwrite file, rerun the fast validator, then move to the next diagnostic.
 6. A batch can be as small as 3-5 examples, or whatever fits in the current turn. It does not need to be an architecturally complete namespace or packet; completeness emerges from fix → rerun → fix → rerun repetition.
 7. When only `EXAMPLE_MISSING` remains, that is still the main digest work, not a checkpoint. Keep authoring type and extension examples packet by packet; do not replace the queue with a completion summary, progress report, user choice menu, or final verification pass.
-8. If packet discovery from the fast source-scan yields unnamed or zero-project packets, rerun `--build-api-model --project-manifest <temp-path>` before continuing example authoring. If the build-backed packet set is still unusable, fall back to sequential repair in repair-plan or namespace order instead of stopping.
+8. If packet discovery from the fast source-scan yields unnamed or zero-project packets, rerun `--build-api-model --project-manifest <temp-path>` before continuing example authoring. If the build-backed packet set is still unusable, fall back to sequential repair in assessment work queue or namespace order instead of stopping.
 9. Rerun the fast validator until the required diagnostics are gone, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`) to surface `SAMPLE_COMPILE_FAILED` and reflection-precise API gaps; resolve those too and rerun until the JSON completion contract is clean.
 10. Do not convert repairable diagnostics into a blocker report. A stubborn diagnostic is a debugging task: inspect the complete implicated UID/path set, validator normalization, source evidence, and related examples; fix either the content or a proven validator defect, then rerun. Continue unrelated packets while investigating when doing so preserves quality. Stop incomplete only when the user pauses the task or a genuine external condition prevents further execution; report the exact command, exit code, and blocker without claiming completion.
 
@@ -89,10 +89,10 @@ Namespace pages and `Extension Members` tables complement type-page examples; th
 When continuing after another agent stopped with diagnostics remaining:
 
 1. Inspect `git status --short --untracked-files=all`, enumerate the stated counts and paths, and preserve every existing tracked and untracked documentation edit, not only the newly created namespace/type files. Do not collapse a concrete inventory such as “8 namespace pages and 1 type page” into a generic promise to preserve work.
-2. Rerun the fast validator with `--json --repair-plan <temp-path>` and read the generated plan.
-3. Use the repair plan and example inventory as the active queue across all affected namespaces, type pages, extension classes, and extension methods.
+2. Rerun the fast validator with `--json --assessment-queue <temp-path>` and read the generated queue.
+3. Use the assessment work queue and example inventory as the active queue across all affected namespaces, type pages, extension classes, and extension methods.
 4. If only `EXAMPLE_MISSING` remains, keep going. That queue is not a stopping point. When packet ownership is unclear from the fast run, write a reflection-backed manifest with `--build-api-model --project-manifest <temp-path>` and use that manifest as the example-authoring queue instead of presenting a checkpoint or options.
-5. If the build-backed packet set is still unusable, fall back to sequential example repair in repair-plan or namespace order. Clear the next 3-5 examples, rerun, then continue.
+5. If the build-backed packet set is still unusable, fall back to sequential example repair in assessment work queue or namespace order. Clear the next 3-5 examples, rerun, then continue.
 6. Repair manageable batches, then rerun the fast validator after each batch so the queue measurably shrinks; do not stop after a representative subset.
 7. Run the exact final command `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json` only when you are ready to claim completion, and continue until the completion contract is clean.
 8. If a rerun replaces one diagnostic family with a more specific follow-on family, keep going. Do not convert that newly exposed queue into a progress summary or a request for approval to continue.
@@ -320,7 +320,7 @@ When the user does not name a specific target:
 1. Run `agents.cs`.
 2. Run the safety gates and inspect repository guidance.
 3. Inspect DocFX configuration, overwrite files, tests, samples, and current documentation state.
-4. Run `docfx.cs --json`, and for multi-diagnostic output rerun with `--repair-plan` and use that plan as the work queue.
+4. Run `docfx.cs --json`, and for multi-diagnostic output rerun with `--assessment-queue` and use that queue as the work queue.
 5. Repair missing namespace pages, extension-member tables, examples, overwrite layout, summaries, and availability notes that can be derived from evidence.
 6. Preserve manual edits, inspect `git diff`, run `dotnet build`, run `dotnet test`, run the Completion Repair Loop, then run the build-backed completion verification (`docfx.cs --build-api-model --validate-samples --verify-docfx-build`).
 
diff --git a/skills/dotnet-docfx-digest/evals/evals.json b/skills/dotnet-docfx-digest/evals/evals.json
index 2ca0483..6879fe8 100644
--- a/skills/dotnet-docfx-digest/evals/evals.json
+++ b/skills/dotnet-docfx-digest/evals/evals.json
@@ -65,13 +65,13 @@
     {
       "id": 6,
       "prompt": "Use dotnet-docfx-digest on this repository.",
-      "expected_output": "Agent treats the request as a repo-wide DocFX documentation audit instead of asking what to document first. It runs scripts/agents.cs, inspects AGENTS.md, docfx.json, source projects, public API, tests, samples, overwrite files, namespace pages, and availability includes, runs scripts/docfx.cs to collect deterministic findings and writes a deterministic --repair-plan for noisy diagnostics, uses that repair plan as the work queue, runs with --verify-docfx-build before completion, repairs missing complementary DocFX documentation that can be derived from source evidence, reads the DocFX overwrite reference when creating or repairing overwrite files, and asks for clarification only if discovery exposes a correctness-affecting choice.",
+      "expected_output": "Agent treats the request as a repo-wide DocFX documentation audit instead of asking what to document first. It runs scripts/agents.cs, inspects AGENTS.md, docfx.json, source projects, public API, tests, samples, overwrite files, namespace pages, and availability includes, runs scripts/docfx.cs to collect deterministic findings and writes a deterministic `--assessment-queue` for noisy diagnostics, uses that assessment work queue as the work queue, runs with --verify-docfx-build before completion, repairs missing complementary DocFX documentation that can be derived from source evidence, reads the DocFX overwrite reference when creating or repairing overwrite files, and asks for clarification only if discovery exposes a correctness-affecting choice.",
       "expectations": [
         "Does not start by asking the user which API or namespace to document",
         "Runs scripts/agents.cs to ensure the repository AGENTS.md contains the managed DocFX maintenance block",
         "Inspects docfx.json and existing DocFX overwrite, namespace, include, source, test, and sample evidence before editing",
         "Runs scripts/docfx.cs, preferably with --json when collecting repo-wide findings, and uses --verify-docfx-build before completion so generated output stays outside the working tree",
-        "For multi-diagnostic output, writes and reads a deterministic --repair-plan and uses it as the work queue before editing",
+        "For multi-diagnostic output, writes and reads a deterministic `--assessment-queue` and uses it as the work queue before editing",
         "Creates or updates missing namespace overview pages, Extension Members tables, examples, and availability notes that can be derived from evidence",
         "Reads references/docfx-overwrite-files.md before creating or repairing DocFX overwrite files",
         "Asks a concise clarifying question only after inspection finds a correctness-affecting unresolved choice"
@@ -123,12 +123,12 @@
     {
       "id": 10,
       "prompt": "Use dotnet-docfx-digest on the Codebelt.Bootstrapper docs after a bad previous run left `Codebelt.Bootstrapper.Console.md`, `Codebelt.Bootstrapper.md`, `Codebelt.Bootstrapper.Web.md`, and `Codebelt.Bootstrapper.Worker.md` checked out. The last agent restored or undid some of those files, only edited `Codebelt.Bootstrapper.md`, and added no required examples.",
-      "expected_output": "Agent does not run broad restore or checkout commands. It captures git status and diffs first, runs scripts/docfx.cs with --json and --repair-plan, reads the repair plan, audits all four Bootstrapper namespace pages as a related family, fixes Extension Members sections consistently, creates or repairs required examples for public non-abstraction types and public extension methods instead of stopping at tables, builds an example inventory mapping each required API to an example file and UID, preserves already checked-out Markdown edits, runs build/test/DocFX verification, and reports any remaining deterministic diagnostics.",
+      "expected_output": "Agent does not run broad restore or checkout commands. It captures git status and diffs first, runs scripts/docfx.cs with --json and --assessment-queue, reads the assessment work queue, audits all four Bootstrapper namespace pages as a related family, fixes Extension Members sections consistently, creates or repairs required examples for public non-abstraction types and public extension methods instead of stopping at tables, builds an example inventory mapping each required API to an example file and UID, preserves already checked-out Markdown edits, runs build/test/DocFX verification, and reports any remaining deterministic diagnostics.",
       "expectations": [
         "Captures git status and diffs before modifying or recovering checked-out Markdown files",
         "Does not use broad git restore, checkout, reset, or whole-directory recovery commands",
         "Stops and reports existing uncommitted documentation changes if they cannot be preserved safely",
-        "Runs scripts/docfx.cs with --json and --repair-plan, then reads the generated repair plan before editing",
+        "Runs scripts/docfx.cs with --json and --assessment-queue, then reads the generated assessment work queue before editing",
         "Audits `Codebelt.Bootstrapper.Console.md`, `Codebelt.Bootstrapper.md`, `Codebelt.Bootstrapper.Web.md`, and `Codebelt.Bootstrapper.Worker.md` together instead of updating only one file",
         "Uses `Extension Members` headings where extension methods are present",
         "Adds required examples for public non-abstraction types and public extension methods, not only namespace fly-ins or extension tables",
@@ -655,13 +655,13 @@
     {
       "id": 53,
       "prompt": "Use dotnet-docfx-digest for a repo-wide audit. The previous agent added 8 missing namespace pages and only 1 type overwrite page, then stopped after the build-backed validator reported 62 EXTENSION_SECTION_MISSING, 1228 EXAMPLE_MISSING, and 1 DOCFX_BUILD_FAILED diagnostic. It called those findings pre-existing documentation gaps. `dotnet build` passes, while `dotnet test` fails only because an integration test cannot connect to SQL Server. Inspect the untracked DocFX work and finish the full digest.",
-      "expected_output": "The agent identifies the existing work as a partial digest, preserves it, and treats all 1291 validator errors as the active repo-wide repair queue rather than as pre-existing blockers. It uses the repair plan and example inventory to continue across every affected namespace, extension section, concrete type, and extension method. The unrelated SQL Server test failure is reported separately and does not end documentation work. The agent reruns fast validation during repair and treats a clean fast result as verification-required, then runs the build-backed command at the end. It does not claim completion until JSON reports summary.canClaimCompletion=true, summary.remainingWorkItems=0, empty summary.remainingGates and summary.remainingDiagnosticsByCode collections, and the build-backed command exits 0.",
+      "expected_output": "The agent identifies the existing work as a partial digest, preserves it, and treats all 1291 validator errors as the active repo-wide repair queue rather than as pre-existing blockers. It uses the assessment work queue and example inventory to continue across every affected namespace, extension section, concrete type, and extension method. The unrelated SQL Server test failure is reported separately and does not end documentation work. The agent reruns fast validation during repair and treats a clean fast result as verification-required, then runs the build-backed command at the end. It does not claim completion until JSON reports summary.canClaimCompletion=true, summary.remainingWorkItems=0, empty summary.remainingGates and summary.remainingDiagnosticsByCode collections, and the build-backed command exits 0.",
       "expectations": [
         "Inspects and preserves the 8 untracked namespace pages, 1 untracked type page, and other existing documentation edits instead of discarding or overwriting them wholesale",
         "Explicitly identifies the prior output as partial because 62 extension-section, 1228 example, and 1 DocFX-build diagnostics remain",
         "Does not describe pre-existing diagnostics, diagnostic volume, or the size of the work queue as a blocker",
         "Does not stop with a progress summary or ask the user whether to continue while repairable diagnostics remain",
-        "Uses the deterministic repair plan and complete validator queue to continue repairing every missing extension section and example across the affected documentation surfaces",
+        "Uses the deterministic assessment work queue and complete validator queue to continue repairing every missing extension section and example across the affected documentation surfaces",
         "Reports the SQL Server integration-test failure separately and continues DocFX repair because the failure does not prevent documentation validation or source inspection",
         "Reruns the fast validator after batches of edits instead of stopping after the first namespace or type subset",
         "Treats fast validation as an iteration checkpoint and still requires the final build-backed command before completion",
@@ -918,12 +918,12 @@
     {
       "id": 76,
       "prompt": "Use dotnet-docfx-digest on a Cuemon-style repository after several repair batches. All non-example diagnostics are gone, but `EXAMPLE_MISSING` is still 1086. A fast `--project-manifest` run returns unnamed packets with `projects: []` and `metadataGroup: unknown` because the scope is still source-scan provisional.",
-      "expected_output": "The agent treats the 1086 `EXAMPLE_MISSING` items as the active core work, not a checkpoint. It does not produce a completion report, next-step menu, or approval pause. Instead it reruns packet discovery with `--build-api-model --project-manifest`, continues authoring type and extension examples packet by packet from that reflection-backed manifest, and if the packet set is still unusable it falls back to sequential repair in repair-plan or namespace order. It works the queue in small fix→rerun batches and delays final verification until the example queue is actually finished.",
+      "expected_output": "The agent treats the 1086 `EXAMPLE_MISSING` items as the active core work, not a checkpoint. It does not produce a completion report, next-step menu, or approval pause. Instead it reruns packet discovery with `--build-api-model --project-manifest`, continues authoring type and extension examples packet by packet from that reflection-backed manifest, and if the packet set is still unusable it falls back to sequential repair in assessment work queue or namespace order. It works the queue in small fix→rerun batches and delays final verification until the example queue is actually finished.",
       "expectations": [
         "Does not treat an example-only queue or its size as a reason to stop, summarize, checkpoint, or ask the user how to proceed",
         "Does not offer a continue/focus/dry-run/review menu while `EXAMPLE_MISSING` remains non-zero",
         "Recognizes unnamed or zero-project fast-manifest packets as provisional source-scan output and reruns packet discovery with `--build-api-model --project-manifest`",
-        "If the build-backed packet set is still unusable, falls back to sequential repair in repair-plan or namespace order instead of stopping",
+        "If the build-backed packet set is still unusable, falls back to sequential repair in assessment work queue or namespace order instead of stopping",
         "Uses a small fix → rerun micro-loop for examples rather than treating batch size as a planning blocker",
         "Does not run a final completion report or completion-shaped verification pass while `EXAMPLE_MISSING` still remains",
         "Continues example authoring and reserves `--build-api-model --validate-samples --verify-docfx-build` for the real end of the queue"
diff --git a/skills/dotnet-docfx-digest/references/scripts.md b/skills/dotnet-docfx-digest/references/scripts.md
index d7ffc4b..faefaab 100644
--- a/skills/dotnet-docfx-digest/references/scripts.md
+++ b/skills/dotnet-docfx-digest/references/scripts.md
@@ -70,13 +70,13 @@ dotnet run --file docfx.cs -- --repo-root . --validate-samples              # co
 dotnet run --file docfx.cs -- --repo-root . --build-api-model               # reflection-backed API discovery (dotnet)
 dotnet run --file docfx.cs -- --repo-root . --changed-only
 dotnet run --file docfx.cs -- --repo-root . --verify-docfx-build            # DocFX build verification (docfx)
-dotnet run --file docfx.cs -- --repo-root . --json --repair-plan /tmp/docfx-repair-plan.md
-dotnet run --file docfx.cs -- --repo-root . --json --repair-plan /tmp/docfx-repair-plan.md --search-examples
+dotnet run --file docfx.cs -- --repo-root . --json --assessment-queue /tmp/docfx-assessment-queue.md
+dotnet run --file docfx.cs -- --repo-root . --json --assessment-queue /tmp/docfx-assessment-queue.md --search-examples
 dotnet run --file docfx.cs -- --repo-root . --validate-samples --sample-reference-mode package
 dotnet run --file docfx.cs -- --repo-root . --build-api-model --configuration Debug --framework net10.0
 ```
 
-Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only used by build/sample paths), `--framework`, `--validate-samples` / `--no-validate-samples` (default off — opt-in), `--sample-reference-mode <project|package>` (default `project`), `--sample-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_SAMPLE_PARALLELISM`; passed as the maximum node count for the batched sample graph build), `--build-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_BUILD_PARALLELISM`), `--execution-profile <auto|conservative|high-capacity>` (env `DOCFX_DIGEST_EXECUTION_PROFILE`), `--process-timeout-minutes <n>` (1-180, default 30; env `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES`), `--build-api-model` / `--strict-api-discovery` (default off — opt-in), `--changed-only`, `--verify-docfx-build`, `--repair-plan <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default off — opt-in), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
+Arguments: `--repo-root`, `--docfx`, `--configuration` (default `Release`, only used by build/sample paths), `--framework`, `--validate-samples` / `--no-validate-samples` (default off — opt-in), `--sample-reference-mode <project|package>` (default `project`), `--sample-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_SAMPLE_PARALLELISM`; passed as the maximum node count for the batched sample graph build), `--build-parallelism <n>` (1-16, adaptive default; env `DOCFX_DIGEST_BUILD_PARALLELISM`), `--execution-profile <auto|conservative|high-capacity>` (env `DOCFX_DIGEST_EXECUTION_PROFILE`), `--process-timeout-minutes <n>` (1-180, default 30; env `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES`), `--build-api-model` / `--strict-api-discovery` (default off — opt-in), `--changed-only`, `--verify-docfx-build`, `--assessment-queue <path>`, `--search-examples`, `--clean-generated-metadata` / `--no-clean-generated-metadata` (default off — opt-in), `--json`, `--help`. When `--framework` is omitted and `docfx.json` declares a single `metadata.properties.TargetFramework`, that framework is used as the validation target.
 
 Project-scoped authoring arguments: `--project <hint>` (repeatable; resolves against project path, file name, assembly name, or package id and must match exactly one project), `--dry-run` (voluntary representative working-tree run; use only when explicitly requested), `--seed <integer>` (reproducible dry-run selection; reported when generated), `--project-manifest <path>` (write a deterministic BOM-less packet manifest, initial dirty baseline, and sibling review template), `--resume-project-manifest <path>` (resume exactly those selected packets after authoring), `--review-report <path>` (required on resume; validates page-specific evidence, purpose/outcome, observable result, and pattern comparison), and `--write-overwrite <path>` (safe structured overwrite-writer command). Repository size and diagnostic volume never alter scope. Only explicit `--dry-run` selects a representative subset.
 
@@ -94,15 +94,15 @@ dotnet run --file docfx.cs -- --repo-root . --write-overwrite /tmp/overwrite-req
 
 The scanner correctly handles block namespaces whose opening brace is on the next line; when it cannot pair a declaration with its brace it warns `API_MODEL_SOURCE_SCANNER_INCOMPLETE`. Project discovery groups projects by their DocFX metadata destination (`metadata[].dest`, default `api`): a group is a sampling unit, and distinct destinations are never collapsed into one ownership-free list. A run is `full`, `scoped` (explicit `--project` hints), or `dry-run` (seeded one-per-group selection). When the API model is `source-scan` and authoring scope is requested, `summary.scopeState` is `provisional` and `BUILD_BACKED_SCOPE_REQUIRED` fires; DocFX YAML or `--build-api-model` make scope `authoritative`. A `dry-run`/`scoped` run never sets `summary.canClaimCompletion`; `*-passed` requires zero diagnostics and all three final gates (`--build-api-model`, `--validate-samples`, `--verify-docfx-build`), otherwise it is `*-failed`. Dirty related paths (staged, unstaged, renamed, deleted, untracked) mark a packet dirty so initial dry-run selection skips it (`DRY_RUN_GROUP_UNSELECTED` when a group has no clean candidate). A resumed manifest reuses only the initial dirty baseline, allowing newly authored files to be verified while continuing to protect pre-existing work; invalid manifests fail closed.
 
-The JSON `scope` object contains `mode`, `seed`, `scopeState`, `metadataGroups` (with the `selectedProject` per group), `selectedProjects`, `skippedProjects`, `packets` (project identity, metadata groups, owned/shared namespaces, target counts, overwrite paths, review paths, dirty related paths, per-packet diagnostic counts), `dirty`, `familyExemptions`, `reproduceCommand`, and, after manifest creation, `resumeCommand`. The top-level report includes `reviewReportPath`. `--project-manifest` writes the packet evidence and initial git baseline as schema version 2 plus a sibling schema-version-1 review template. The resumed run requires every changed selected page to have non-placeholder `evidence`, `purpose`, `observableOutcome`, and `patternComparison` fields before `dry-run-passed` or `scoped-passed` is possible.
+The JSON `scope` object contains `mode`, `seed`, `scopeState`, `metadataGroups` (with the `selectedProject` per group), `selectedProjects`, `skippedProjects`, `packets` (project identity, metadata groups, owned/shared namespaces, target counts, overwrite paths, review paths, dirty related paths, per-packet diagnostic counts), `dirty`, `familyExemptions`, `reproduceCommand`, and, after manifest creation, `resumeCommand`. The top-level report includes `reviewReportPath` and `assessmentQueuePath`. `--project-manifest` writes the packet evidence and initial git baseline as schema version 2 plus a sibling schema-version-1 review template. The resumed run requires every changed selected page to have non-placeholder `evidence`, `purpose`, `observableOutcome`, and `patternComparison` fields before `dry-run-passed` or `scoped-passed` is possible.
 
 `--write-overwrite <path>` reads a JSON request (`file`, `uid`, `mapping` of `example`/`summary`/`remarks`, optional `prose`, optional `fence`), validates the YAML and balanced fences, refuses duplicate UIDs (`OVERWRITE_UID_DUPLICATE`), unbalanced fences (`OVERWRITE_FENCE_UNBALANCED`), and replacing a pre-existing dirty file (`OVERWRITE_DIRTY_REFUSED`), preserves the target's existing BOM and line endings, and prints a change preview. It only writes structured content the agent already authored; it never generates prose, selects members, or synthesizes examples.
 
 `--changed-only` scopes namespace-page, required-example, and sample validation to the changed documentation or source inputs that affect those checks. It still does not build by default: Markdown/overwrite-only changes are validated against the no-build API model, and it uses `git` (read-only) to discover changes. It includes both tracked changes from `git diff` and untracked documentation files from `git ls-files --others --exclude-standard`, so brand-new overwrite Markdown still has its C# samples compiled (under `--validate-samples`) before the file is staged. New or changed public APIs must still surface `EXAMPLE_MISSING` diagnostics when their supporting overwrite examples are absent.
 
-`--repair-plan <path>` writes a deterministic Markdown work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The plan groups repository guidance failures, encoding repairs, namespace and extension-table repairs, a required-example inventory with GitHub search commands, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory includes missing examples and semantic failures such as duplicate UID mappings, placeholders, `default!`/`null!` holders, no-observable-outcome and mass-forwarding scaffolds, repeated code templates across unrelated targets, reflection-only scaffolds, target types that are never used, and extension methods that are never invoked. For public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the plan points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the plan to a temp path unless the user explicitly wants a checked-in artifact. The plan always includes a "GitHub Example Sources" section with `gh search code` commands and GitHub search URLs for each documented package, even when no `EXAMPLE_MISSING` diagnostics are present.
+`--assessment-queue <path>` writes a deterministic Markdown assessment work queue derived from the same diagnostics emitted in JSON/console output. Use it for repo-wide audits or noisy validation runs before editing documentation. The queue groups repository guidance failures, encoding repairs, namespace and extension-table repairs, a required-example inventory with GitHub search commands, sample compilation repairs, other errors, and warnings, then adds completion gates that preserve authored Markdown, require generated-artifact cleanup paths to be listed before deletion, forbid broad restore/checkout recovery, require related namespace pages to be repaired together, and require `git diff` review before final verification. The required-example inventory includes missing examples and semantic failures such as duplicate UID mappings, placeholders, `default!`/`null!` holders, no-observable-outcome and mass-forwarding scaffolds, repeated code templates across unrelated targets, reflection-only scaffolds, target types that are never used, and extension methods that are never invoked. For public non-abstraction types, it names the expected type-targeting overwrite path such as `.docfx/api/types/X.Y.Z.Class1.md`; namespace overview examples and `Extension Members` tables do not complete those items. For extension methods, the queue points agents toward the declaring extension class or namespace page rather than odd URL-encoded method-UID filenames, and config/layout diagnostics require both `api/namespaces/**/*.md` and `api/types/**/*.md` under `build.overwrite` while moving legacy `.docfx/api/*.md` authored overwrite files into the appropriate subdirectory. Write the queue to a temp path unless the user explicitly wants a checked-in artifact. The queue always includes a "GitHub Example Sources" section with `gh search code` commands and GitHub search URLs for each documented package, even when no `EXAMPLE_MISSING` diagnostics are present.
 
-`--search-examples` runs `gh search code` for each discovered package ID and embeds the top matching file paths in the repair plan under "GitHub Search Results". Requires the `gh` CLI to be authenticated. Combine with `--repair-plan` so results are written to a file the agent can read. If `gh` is unavailable or returns no results, the plan still includes the pre-computed search URLs and CLI commands.
+`--search-examples` runs `gh search code` for each discovered package ID and embeds the top matching file paths in the assessment work queue under "GitHub Search Results". Requires the `gh` CLI to be authenticated. Combine with `--assessment-queue` so results are written to a file the agent can read. If `gh` is unavailable or returns no results, the queue still includes the pre-computed search URLs and CLI commands.
 
 `--verify-docfx-build` copies the repository to a temp workspace, resolves the DocFX CLI from `PATH`, runs it against the resolved `docfx.json` there, and removes the temp workspace afterward. Use it instead of running `docfx .docfx/docfx.json` directly from the working tree so generated API YAML, manifest files, and site output such as a configured `build.dest` folder do not flood git status. The temp copy preserves a root `.snk` when the source checkout has one; otherwise the DocFX process receives `SkipSignAssembly=true` in its environment so Codebelt signed projects can still build in keyless workspaces.
 
@@ -128,7 +128,7 @@ Every run records a process tally, per-phase timings, and execution settings. No
 
 Every report also carries a deterministic completion contract. `summary.completionState` is `complete` only when there are no errors and the run enabled `--build-api-model`, `--validate-samples`, and `--verify-docfx-build`. A clean fast run reports `verification-required`. `summary.canClaimCompletion` must be `true`; `summary.remainingWorkItems` must be `0`; and both `summary.remainingGates` and `summary.remainingDiagnosticsByCode` must be empty before an agent can claim a full digest. Any other result is an active repair or verification queue. Diagnostic age, pre-existing status, and volume do not convert repair work into an external blocker.
 
-Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, `NAMESPACE_START_HERE_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `EXAMPLE_UID_DUPLICATE`, `EXAMPLE_PLACEHOLDER`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Project-scoped error codes are `PROJECT_HINT_NOT_FOUND` and `PROJECT_HINT_AMBIGUOUS` for `--project` hints, `FAMILY_EXEMPTION_INVALID`, `FAMILY_ANCHOR_EXAMPLE_MISSING`, and `FAMILY_NAMESPACE_GUIDANCE_MISSING` for `.docfx/family-exemptions.json`, and `OVERWRITE_UID_DUPLICATE`, `OVERWRITE_FENCE_UNBALANCED`, `OVERWRITE_DIRTY_REFUSED`, `OVERWRITE_REQUEST_MISSING`, and `OVERWRITE_REQUEST_INVALID` for the `--write-overwrite` writer. The semantic example codes reject the filler patterns that pass a naive token match: `EXAMPLE_DEFAULT_PLACEHOLDER` for a target parked in a `default!`/`null!` holder property or field, `EXAMPLE_NO_OBSERVABLE_OUTCOME` for an example that only holds, returns, or constructs the target with no visible result, `EXAMPLE_FORWARDING_SCAFFOLD` for a shell dominated by one-line pass-through members, and `EXAMPLE_TEMPLATE_REPETITION` for one normalized code skeleton reused across three or more distinct authored sections. One type- or namespace-level section may legitimately satisfy several extension targets and is counted once. `NAMESPACE_APPEND_ONLY_REPAIR` flags an inventory-led opening left intact while usage or start-here guidance is appended below it (rewrite the opening cohesively instead), and `NAMESPACE_PROSE_TEMPLATE_REPETITION` flags three or more namespace overviews that share one normalized prose skeleton. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_SOURCE_SCANNER_INCOMPLETE` when the scanner cannot pair a block namespace declaration with its opening brace and may under-report public types, `BUILD_BACKED_SCOPE_REQUIRED` when authoring scope is requested on the provisional source-scan model, `PROJECT_DIRTY_SKIPPED` when an explicitly selected project has pre-existing related changes, `DRY_RUN_GROUP_UNSELECTED` when an explicitly requested dry run has no clean project to sample, `SYMBOL_COLLISION_UNRESOLVED` / `TYPE_FORWARDING_UNRESOLVED` / `EXTENSION_OWNER_AMBIGUOUS` for unresolved symbol ownership, `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
+Error codes emitted in JSON include `AGENTS_BLOCK_MISSING`, `DOCFX_CONFIG_MISSING`, `API_OVERWRITE_CONFIG_INVALID`, `API_OVERWRITE_FILE_MISPLACED`, `BUILD_FAILED`, `PUBLIC_API_DISCOVERY_FAILED`, `NAMESPACE_PAGE_MISSING`, `NAMESPACE_UID_MISSING`, `NAMESPACE_UID_MISMATCH`, `NAMESPACE_SUMMARY_MISSING`, `NAMESPACE_FLYIN_MISSING`, `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, `NAMESPACE_START_HERE_MISSING`, `AVAILABILITY_MISSING`, `EXTENSION_SECTION_MISSING`, `EXTENSION_TABLE_MISSING`, `EXTENSION_TABLE_ENCODING`, `EXTENSION_METHOD_MISSING`, `ENCODING_CORRUPTION`, `EXAMPLE_MISSING`, `EXAMPLE_UID_DUPLICATE`, `EXAMPLE_PLACEHOLDER`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `SAMPLE_COMPILE_FAILED`, `SAMPLE_SKIP_REASON_MISSING`, `SAMPLE_SKIP_REASON_INSUFFICIENT`, `DOCFX_BUILD_FAILED`, `ASSESSMENT_QUEUE_WRITE_FAILED`, `GENERATED_METADATA_CLEANUP_FAILED`, `GENERATED_METADATA_CLEANUP_SKIPPED`, `GENERATED_OUTPUT_CLEANUP_FAILED`, and `GENERATED_OUTPUT_CLEANUP_SKIPPED`. Project-scoped error codes are `PROJECT_HINT_NOT_FOUND` and `PROJECT_HINT_AMBIGUOUS` for `--project` hints, `FAMILY_EXEMPTION_INVALID`, `FAMILY_ANCHOR_EXAMPLE_MISSING`, and `FAMILY_NAMESPACE_GUIDANCE_MISSING` for `.docfx/family-exemptions.json`, and `OVERWRITE_UID_DUPLICATE`, `OVERWRITE_FENCE_UNBALANCED`, `OVERWRITE_DIRTY_REFUSED`, `OVERWRITE_REQUEST_MISSING`, and `OVERWRITE_REQUEST_INVALID` for the `--write-overwrite` writer. The semantic example codes reject the filler patterns that pass a naive token match: `EXAMPLE_DEFAULT_PLACEHOLDER` for a target parked in a `default!`/`null!` holder property or field, `EXAMPLE_NO_OBSERVABLE_OUTCOME` for an example that only holds, returns, or constructs the target with no visible result, `EXAMPLE_FORWARDING_SCAFFOLD` for a shell dominated by one-line pass-through members, and `EXAMPLE_TEMPLATE_REPETITION` for one normalized code skeleton reused across three or more distinct authored sections. One type- or namespace-level section may legitimately satisfy several extension targets and is counted once. `NAMESPACE_APPEND_ONLY_REPAIR` flags an inventory-led opening left intact while usage or start-here guidance is appended below it (rewrite the opening cohesively instead), and `NAMESPACE_PROSE_TEMPLATE_REPETITION` flags three or more namespace overviews that share one normalized prose skeleton. Warnings include `API_MODEL_SOURCE_SCANNER_LIMITED` when the no-build source scanner is the API-model source (run `--build-api-model` for reflection-backed precision), `API_MODEL_SOURCE_SCANNER_INCOMPLETE` when the scanner cannot pair a block namespace declaration with its opening brace and may under-report public types, `BUILD_BACKED_SCOPE_REQUIRED` when authoring scope is requested on the provisional source-scan model, `PROJECT_DIRTY_SKIPPED` when an explicitly selected project has pre-existing related changes, `DRY_RUN_GROUP_UNSELECTED` when an explicitly requested dry run has no clean project to sample, `SYMBOL_COLLISION_UNRESOLVED` / `TYPE_FORWARDING_UNRESOLVED` / `EXTENSION_OWNER_AMBIGUOUS` for unresolved symbol ownership, `API_MODEL_EMPTY` when no-build discovery found no public API (Markdown, encoding, and overwrite-layout checks still run; `--build-api-model` is required for namespace and required-example validation), `DOCFX_EXTENSION_BLOCK_UNSUPPORTED` when C# 14 extension blocks are detected in the public API (see DocFX issue #11010), and `API_OVERWRITE_CONFIG_UNREADABLE` when the validator cannot parse the DocFX config well enough to inspect the overwrite layout.
 
 `ENCODING_CORRUPTION` fires when a documentation file contains the byte sequence `C3 A2 C2 AC` — the UTF-8 re-encoding of the `â¬` pair produced by a Windows-1252 round-trip of `U+2B07` (⬇, the Extension Members table arrow). Restore the affected file with `git checkout HEAD -- <file>` if the committed version was correct, or rewrite the content using the edit tool or byte-level operations. Never use `Get-Content` / `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes(Get-Content)` to rewrite documentation files that contain multi-byte characters.
 
diff --git a/skills/dotnet-docfx-digest/references/workflow.md b/skills/dotnet-docfx-digest/references/workflow.md
index be7d456..75bf2bf 100644
--- a/skills/dotnet-docfx-digest/references/workflow.md
+++ b/skills/dotnet-docfx-digest/references/workflow.md
@@ -40,7 +40,7 @@ Use this path when the user names a changed API or namespace.
 4. Determine whether public extension methods are involved.
 5. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
 6. Locate existing overwrite files, namespace pages, availability includes, tests, and samples.
-7. Run `docfx.cs --json --repair-plan /tmp/docfx-repair-plan.md --search-examples` and read the repair plan. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs; use those results as evidence before writing examples.
+7. Run `docfx.cs --json --assessment-queue /tmp/docfx-assessment-queue.md --search-examples` and read the assessment work queue. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs; use those results as evidence before writing examples.
 8. Convert test usage into consumer-oriented examples when relevant.
 9. Update XML documentation comments where purpose-first summaries are needed.
 10. Update or create namespace overview pages whose opening names the developer problem and outcome, followed by concrete when-to-use and start-here guidance.
@@ -66,7 +66,7 @@ Use this path when the user invokes the skill without naming a specific API or n
 3. Read repository guidance, especially root `AGENTS.md`.
 4. Inspect `.docfx/docfx.json` or the repository-specific DocFX config.
 5. Read `references/docfx-overwrite-files.md`.
-6. Run `docfx.cs --json --repair-plan /tmp/docfx-repair-plan.md --search-examples` and read the repair plan. The plan is the authoritative work queue. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs for each documented package — run or open these searches before writing any new example.
+6. Run `docfx.cs --json --assessment-queue /tmp/docfx-assessment-queue.md --search-examples` and read the assessment work queue. That queue is the authoritative work queue. The "GitHub Example Sources" section contains pre-computed `gh search code` commands and URLs for each documented package — run or open these searches before writing any new example.
 7. If the validator fails before producing documentation diagnostics, inspect source projects, DocFX config, existing overwrite files, generated metadata when available, tests, and samples manually.
 8. Check for `ENCODING_CORRUPTION` or `EXTENSION_TABLE_ENCODING` diagnostics first; restore affected files from git before doing any further editing.
 9. Determine every namespace containing public API and whether each namespace exposes public extension methods.
@@ -88,7 +88,7 @@ Use this path when the user invokes the skill without naming a specific API or n
 25. Inspect `git status` and confirm no disposable generated DocFX output remained in the working tree.
 26. Report verification results and any remaining deterministic findings.
 
-When resuming a partial repo-wide audit, begin by inventorying all tracked and untracked documentation changes and preserving them as in-flight work. Regenerate the deterministic repair plan and example inventory, use both as the authoritative queue, and work in batches with a fast validator rerun after every batch. The exact final command is `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json`; descriptive references to those activities do not replace running the flags together.
+When resuming a partial repo-wide audit, begin by inventorying all tracked and untracked documentation changes and preserving them as in-flight work. Regenerate the deterministic assessment work queue and example inventory, use both as the authoritative queue, and work in batches with a fast validator rerun after every batch. The exact final command is `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json`; descriptive references to those activities do not replace running the flags together.
 
 For the final command, let `auto` choose the execution profile unless the user requests a specific resource policy. High-capacity machines run the isolated DocFX verification lane concurrently with API/sample work; conservative machines remain sequential. Give the outer command a timeout at least five minutes above the validator's child-process timeout (35 minutes with the default 30-minute setting) so timeout diagnostics can be returned normally.
 
@@ -118,7 +118,7 @@ An example-only queue is still incomplete. When `EXAMPLE_MISSING` is the only re
 
 When the queue is dominated by `EXAMPLE_MISSING`, shrink your mental scope to the next concrete target instead of the total count.
 
-1. Take the next `EXAMPLE_MISSING` diagnostic from the repair plan or current fast-validator output.
+1. Take the next `EXAMPLE_MISSING` diagnostic from the assessment work queue or current fast-validator output.
 2. Read that target's public API surface and one relevant test, sample, or usage source.
 3. Write one consumer-facing example to the correct type-targeted overwrite file.
 4. Rerun the fast validator.
@@ -126,7 +126,7 @@ When the queue is dominated by `EXAMPLE_MISSING`, shrink your mental scope to th
 
 A "batch" does not need to be an architecturally complete namespace, packet, or package. A batch is any set of examples you can finish confidently before rerunning validation. Completeness emerges from iteration.
 
-If packet discovery stays weak even after `--build-api-model`, fall back to sequential repair in repair-plan order or alphabetical namespace order. Clear the next namespace's remaining examples (or the next 3-5 examples in it), rerun, and continue. A tool limitation is not a decision point.
+If packet discovery stays weak even after `--build-api-model`, fall back to sequential repair in assessment work queue order or alphabetical namespace order. Clear the next namespace's remaining examples (or the next 3-5 examples in it), rerun, and continue. A tool limitation is not a decision point.
 
 Final verification with `--build-api-model --validate-samples --verify-docfx-build` is reserved for the moment you intend to claim completion. While `remainingWorkItems > 0` or any diagnostics remain, stay on the fast `docfx.cs --json` loop and keep authoring.
 
@@ -296,7 +296,7 @@ Before completing documentation work, verify:
 - [ ] `agents.cs` ran successfully.
 - [ ] `AGENTS.md` contains the managed DocFX maintenance block.
 - [ ] Initial `git status --short` was inspected and existing documentation changes were treated as user work.
-- [ ] For multi-diagnostic audits, `docfx.cs --repair-plan` was written, read, and used as the work queue.
+- [ ] For multi-diagnostic audits, `docfx.cs --assessment-queue` was written, read, and used as the work queue.
 - [ ] Only public API is documented.
 - [ ] Every namespace with public API has a namespace overview page.
 - [ ] Related namespace pages in the same public API family were inspected and updated consistently, or intentionally left unchanged with a reason.
diff --git a/skills/dotnet-docfx-digest/scripts/docfx.cs b/skills/dotnet-docfx-digest/scripts/docfx.cs
index 75709e6..73328b5 100644
--- a/skills/dotnet-docfx-digest/scripts/docfx.cs
+++ b/skills/dotnet-docfx-digest/scripts/docfx.cs
@@ -198,7 +198,7 @@ private static int Validate(Options options)
 
         var libraryProjects = projects.Where(p => !p.IsTest).ToList();
 
-        // Store package IDs for use in the repair plan GitHub search section.
+        // Store package IDs for use in the assessment work queue GitHub search section.
         report.PackageIds.AddRange(
             libraryProjects
                 .Select(p => p.PackageId ?? p.AssemblyName)
@@ -404,7 +404,7 @@ private static int Validate(Options options)
             concurrentDocfxCancellation?.Dispose();
         }
 
-        // Optional GitHub example search to embed real usage snippets in the repair plan.
+        // Optional GitHub example search to embed real usage snippets in the assessment work queue.
         if (options.SearchExamples && report.PackageIds.Count > 0)
         {
             phaseTimer.Restart();
@@ -6707,7 +6707,7 @@ private static int Emit(Options options, Report report, ExitCode code, string co
             .OrderBy(group => group.Key, StringComparer.Ordinal)
             .ToDictionary(group => group.Key, group => group.Count(), StringComparer.Ordinal);
 
-        WriteRepairPlanIfRequested(options, report);
+        WriteAssessmentQueueIfRequested(options, report);
 
         // Capture the process tally on every exit path so the result always proves whether the
         // fast path actually shelled out to dotnet/msbuild/docfx/gh.
@@ -6778,9 +6778,9 @@ private static string Describe(Diagnostic d)
         return $"{path}{location}{d.Message}";
     }
 
-    private static void WriteRepairPlanIfRequested(Options options, Report report)
+    private static void WriteAssessmentQueueIfRequested(Options options, Report report)
     {
-        if (string.IsNullOrWhiteSpace(options.RepairPlanPath))
+        if (string.IsNullOrWhiteSpace(options.AssessmentQueuePath))
         {
             return;
         }
@@ -6788,27 +6788,27 @@ private static void WriteRepairPlanIfRequested(Options options, Report report)
         try
         {
             var basePath = Directory.Exists(report.RepoRoot) ? report.RepoRoot : Directory.GetCurrentDirectory();
-            var planPath = Path.GetFullPath(options.RepairPlanPath, basePath);
+            var planPath = Path.GetFullPath(options.AssessmentQueuePath, basePath);
             var directory = Path.GetDirectoryName(planPath);
             if (!string.IsNullOrWhiteSpace(directory))
             {
                 Directory.CreateDirectory(directory);
             }
 
-            File.WriteAllText(planPath, BuildRepairPlan(report), new UTF8Encoding(false));
-            report.RepairPlanPath = planPath;
+            File.WriteAllText(planPath, BuildAssessmentQueue(report), new UTF8Encoding(false));
+            report.AssessmentQueuePath = planPath;
         }
         catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException or NotSupportedException)
         {
-            report.Warnings.Add(new Diagnostic("REPAIR_PLAN_WRITE_FAILED", options.RepairPlanPath, null,
-                $"Unable to write repair plan: {ex.Message}"));
+            report.Warnings.Add(new Diagnostic("ASSESSMENT_QUEUE_WRITE_FAILED", options.AssessmentQueuePath, null,
+                $"Unable to write assessment work queue: {ex.Message}"));
         }
     }
 
-    private static string BuildRepairPlan(Report report)
+    private static string BuildAssessmentQueue(Report report)
     {
         var sb = new StringBuilder();
-        sb.AppendLine("# DocFX Repair Plan");
+        sb.AppendLine("# DocFX Assessment Work Queue");
         sb.AppendLine();
         sb.AppendLine($"Repository: `{report.RepoRoot}`");
         if (!string.IsNullOrWhiteSpace(report.DocfxPath))
@@ -7076,9 +7076,9 @@ private static bool TryParse(string[] args, out Options options, out string erro
                 case "--verify-docfx-build":
                     options.VerifyDocfxBuild = true;
                     break;
-                case "--repair-plan":
-                    if (!Next(args, ref i, out var rp)) { error = "--repair-plan requires a path."; return false; }
-                    options.RepairPlanPath = rp;
+                case "--assessment-queue":
+                    if (!Next(args, ref i, out var rp)) { error = "--assessment-queue requires a path."; return false; }
+                    options.AssessmentQueuePath = rp;
                     break;
                 case "--search-examples":
                     options.SearchExamples = true;
@@ -7154,7 +7154,7 @@ private static bool TryParse(string[] args, out Options options, out string erro
                     if (TrySplit(arg, "--docfx", out var v2)) { options.DocfxPath = v2; break; }
                     if (TrySplit(arg, "--configuration", out var v3)) { options.Configuration = v3; break; }
                     if (TrySplit(arg, "--framework", out var v4)) { options.Framework = v4; break; }
-                    if (TrySplit(arg, "--repair-plan", out var v5)) { options.RepairPlanPath = v5; break; }
+                    if (TrySplit(arg, "--assessment-queue", out var v5a)) { options.AssessmentQueuePath = v5a; break; }
                     if (TrySplit(arg, "--sample-reference-mode", out var v7))
                     {
                         if (!IsValidSampleReferenceMode(v7)) { error = "--sample-reference-mode must be 'project' or 'package'."; return false; }
@@ -7278,7 +7278,7 @@ dotnet run --file docfx.cs -- [options]
               --build-api-model        Reflection-backed API discovery from compiled assemblies. Builds
                                       only the documented project graph (dotnet). Alias: --strict-api-discovery.
               --verify-docfx-build     Run DocFX against a temp copy of the repository (docfx).
-              --search-examples        Run GitHub code search per documented package (gh). Use with --repair-plan.
+              --search-examples        Run GitHub code search per documented package (gh). Use with --assessment-queue.
 
             Options:
               --repo-root <path>       Repository root. Default: current directory.
@@ -7307,9 +7307,10 @@ Override with env var DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES.
               --build-api-model        Reflection-backed API discovery (opt-in). Default: no-build discovery.
               --changed-only           Validate only files changed according to git (git is read-only and allowed).
               --verify-docfx-build     Run DocFX against a temp copy of the repository (opt-in).
-              --repair-plan <path>     Write a deterministic Markdown repair plan from validation diagnostics.
+              --assessment-queue <path>
+                                      Write a deterministic Markdown assessment work queue from validation diagnostics.
               --search-examples        Run GitHub code search for each documented package and embed real usage snippets in the
-                                      repair plan. Requires the gh CLI to be authenticated. Use together with --repair-plan.
+                                      assessment work queue. Requires the gh CLI to be authenticated. Use together with --assessment-queue.
               --clean-generated-metadata
                                       Remove DocFX-generated *.yml and manifest files under metadata.dest (opt-in).
                                       Runs only after the API model is built, so it never deletes YAML the fast path used.
@@ -7373,7 +7374,7 @@ private sealed class Options
         public string? DocfxPath { get; set; }
         public string Configuration { get; set; } = "Release";
         public string? Framework { get; set; }
-        public string? RepairPlanPath { get; set; }
+        public string? AssessmentQueuePath { get; set; }
         public bool ValidateSamples { get; set; }
         public bool ChangedOnly { get; set; }
         public bool VerifyDocfxBuild { get; set; }
@@ -7694,7 +7695,7 @@ internal sealed class Report
     public string Script { get; set; } = string.Empty;
     public string RepoRoot { get; set; } = string.Empty;
     public string? DocfxPath { get; set; }
-    public string? RepairPlanPath { get; set; }
+    public string? AssessmentQueuePath { get; set; }
     public string? ProjectManifestPath { get; set; }
     public string? ResumedProjectManifestPath { get; set; }
     public string? ReviewReportPath { get; set; }
diff --git a/skills/dotnet-docfx-digest/scripts/test-quality.ps1 b/skills/dotnet-docfx-digest/scripts/test-quality.ps1
index 37e66b0..6d759e6 100644
--- a/skills/dotnet-docfx-digest/scripts/test-quality.ps1
+++ b/skills/dotnet-docfx-digest/scripts/test-quality.ps1
@@ -24,7 +24,10 @@ function Write-Utf8File {
 }
 
 function Invoke-Validator {
-    param([string]$Workspace = $workspace)
+    param(
+        [string]$Workspace = $workspace,
+        [string[]]$ExtraArgs = @()
+    )
 
     # Run the native validator with ErrorActionPreference relaxed so its non-zero exit and stderr
     # packet heartbeats are never promoted to a terminating PowerShell error (explicit `throw`
@@ -33,7 +36,7 @@ function Invoke-Validator {
     $prev = $ErrorActionPreference
     $ErrorActionPreference = 'Continue'
     try {
-        $output = & dotnet run --file $ValidatorPath -- --repo-root $Workspace --json 2>$null
+        $output = & dotnet run --file $ValidatorPath -- --repo-root $Workspace --json @ExtraArgs 2>$null
     } finally {
         $ErrorActionPreference = $prev
     }
@@ -260,6 +263,22 @@ public static class IdentifierInput
 ```
 '@
 
+    $assessmentQueue = Join-Path ([System.IO.Path]::GetTempPath()) ('docfx-assessment-queue-' + [guid]::NewGuid().ToString('N') + '.md')
+    try {
+        $assessmentQueueReport = Invoke-Validator -ExtraArgs @('--assessment-queue', $assessmentQueue)
+        if (-not (Test-Path $assessmentQueue)) {
+            throw 'The --assessment-queue flag did not write a Markdown queue file.'
+        }
+        $queueText = [System.IO.File]::ReadAllText($assessmentQueue)
+        if ($queueText -notmatch '^# DocFX Assessment Work Queue') {
+            throw 'The assessment work queue heading was not written as expected.'
+        }
+    } finally {
+        if (Test-Path $assessmentQueue) {
+            Remove-Item -Path $assessmentQueue -Force
+        }
+    }
+
     $good = Invoke-Validator
     $qualityCodes = @(
         'NAMESPACE_FLYIN_MISSING',

From 85e5700436549114f34b711603112c4ba1c06deb Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 18:00:17 +0200
Subject: [PATCH 87/88] =?UTF-8?q?=F0=9F=91=B7=20add=20docfx=20cli=20instal?=
 =?UTF-8?q?l=20to=20skill=20template=20validator?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Install the global DocFX CLI tool before running the skill template validator. This ensures DocFX-related validation checks can run successfully in the CI environment, supporting validation of DocFX configuration and documentation artifacts.
---
 .github/workflows/validate-skill-templates.yml | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/.github/workflows/validate-skill-templates.yml b/.github/workflows/validate-skill-templates.yml
index f214b4f..b6a4931 100644
--- a/.github/workflows/validate-skill-templates.yml
+++ b/.github/workflows/validate-skill-templates.yml
@@ -11,6 +11,17 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Install DocFX CLI
+        shell: pwsh
+        run: |
+          if (Get-Command docfx -ErrorAction SilentlyContinue) {
+            dotnet tool update --global docfx
+          } else {
+            dotnet tool install --global docfx
+          }
+          "$HOME/.dotnet/tools" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+          docfx --version
+
       - name: Run validator
         shell: pwsh
         run: pwsh -NoProfile -File ./scripts/validate-skill-templates.ps1

From fbdee2e32f08f09729f2a86bcdd39086db008e89 Mon Sep 17 00:00:00 2001
From: "aicia[bot]" <bot.mor.u25@gmail.com>
Date: Mon, 15 Jun 2026 18:00:27 +0200
Subject: [PATCH 88/88] =?UTF-8?q?=F0=9F=92=AC=20update=20readme=20for=20as?=
 =?UTF-8?q?sessment-queue=20changes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update repository README to reflect the skill terminology changes from 'repair-plan' to 'assessment-queue' in the dotnet-docfx-digest skill. Ensures documentation accurately describes the current skill capabilities and terminology.
---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 4877916..a32990b 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ Completion gates are equally strict: if repository guidance, a loaded skill, or
 
 Local skill synchronization is verified efficiently: run deterministic tests against the repository source, copy touched files to the three local installs, and compare SHA-256 hashes across all four locations. Hash-identical copies are the same executable content, so agents do not repeat the same suites from an installed path unless install-path or loader behavior is specifically under test.
 
-Resumed DocFX audits preserve every tracked and untracked documentation edit, regenerate the repair plan and example inventory, and process that queue in batches with a fast rerun after each batch. Encoding checks focus on actual damage: valid BOM-less UTF-8 is accepted, `ENCODING_BOM_MISSING` is not emitted, and audits do not create BOM-only or line-ending-only diffs.
+Resumed DocFX audits preserve every tracked and untracked documentation edit, regenerate the assessment work queue and example inventory, and process that queue in batches with a fast rerun after each batch. Encoding checks focus on actual damage: valid BOM-less UTF-8 is accepted, `ENCODING_BOM_MISSING` is not emitted, and audits do not create BOM-only or line-ending-only diffs.
 
 Final DocFX verification is machine-adaptive: `auto` selects a high-capacity profile above 8 available logical processors and 32 GiB available memory, overlaps isolated DocFX verification with API/sample work, and scales MSBuild workers up to half the available processors (capped at 16). Smaller machines stay conservative. Child-process timeout defaults to 30 minutes, and callers must allow at least 35 minutes so the validator can return its own timeout diagnostics. Long-running build, sample, and DocFX children also emit 10-second `stderr` heartbeats with phase, workload, runner count, PID, elapsed time, last-output age, and current output while keeping JSON stdout parseable.
 
@@ -105,7 +105,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-docfx-diges
 | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | Generate a strong name key (`.snk`) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or `sn.exe` required. Works in any terminal. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. |
 | [git-remote-release](skills/git-remote-release/SKILL.md) | Generate GitHub release notes by summarizing all commits and pull requests between two Git tags or branches in a remote GitHub repository. Accepts a compare URL or separate owner/repo, previous ref, and current ref values; falls back to comparing the current branch against the upstream default branch when no input is provided. Produces a human-friendly `## What's Changed` summary with optional GitHub alert blocks, a `Sources:` section preserving PR and commit references, and a full changelog compare link. |
 | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. |
-| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--repair-plan` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class type pages under `.docfx/api/types/` instead of synthetic method-UID filenames or namespace pages that mix extra `uid:` / `example:` blocks into the overview, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, treats newly surfaced follow-on diagnostics as the next repair queue instead of a stop point, reruns packet discovery with `--build-api-model --project-manifest` when fast source-scan packets are unnamed or zero-project, falls back to sequential namespace or repair-plan order when packet discovery is still unusable, treats `EXAMPLE_MISSING`-only queues as core work rather than checkpoints, drives large example queues through a concrete fast-path micro-loop (next example or next 3-5 examples → rerun → continue), reserves the final `--build-api-model --validate-samples --verify-docfx-build` verification for the real end of the queue, never turns partial progress into a continue/focus/verify menu or completion report while repairable work remains, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
+| [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# extension-block compiler containers such as `<G>$...` back to the authored outer static class, validates namespace fly-ins that explain the problem solved/when to use/where to start, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--assessment-queue` Markdown work queues with a type-first required-example inventory, overwrite-layout fixes, package-ID evidence, and scenario choices for noisy audits, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, makes examples start from package-ID usage evidence before type/member-only searches, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class type pages under `.docfx/api/types/` instead of synthetic method-UID filenames or namespace pages that mix extra `uid:` / `example:` blocks into the overview, flags weak skip-compile reasons, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, treats newly surfaced follow-on diagnostics as the next repair queue instead of a stop point, reruns packet discovery with `--build-api-model --project-manifest` when fast source-scan packets are unnamed or zero-project, falls back to sequential namespace or assessment work queue order when packet discovery is still unusable, treats `EXAMPLE_MISSING`-only queues as core work rather than checkpoints, drives large example queues through a concrete fast-path micro-loop (next example or next 3-5 examples → rerun → continue), reserves the final `--build-api-model --validate-samples --verify-docfx-build` verification for the real end of the queue, never turns partial progress into a continue/focus/verify menu or completion report while repairable work remains, exposes `summary.canClaimCompletion`, `summary.remainingWorkItems`, and `summary.remainingDiagnosticsByCode` as a machine-readable final gate, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts and phase timings) so CI can gate on real failures instead of AI claims. |
 
 ### Copyable Install Commands
 
@@ -548,7 +548,7 @@ API documentation rots the moment code changes. A new public type ships without
 - **Verification without a build, precision on demand** — by default `scripts/docfx.cs` discovers public API, namespaces, and extension methods without compiling: it reads existing DocFX ManagedReference YAML under `metadata.dest` when present, otherwise runs a conservative source scan over the projects referenced by `docfx.json`, and warns (`API_MODEL_SOURCE_SCANNER_LIMITED`) that the precise path is opt-in. Adding `--build-api-model` (alias `--strict-api-discovery`) builds only the documented project graph through a single scoped `.slnx` graph build and discovers from compiled metadata via `MetadataLoadContext` with project-asset, deps-file, and framework-pack dependency resolution,
 - **Codebelt signing-key aware** — strong-name signed Codebelt repositories use the root `.snk` file when it is present, while keyless checkouts and temp workspaces verify with `-p:SkipSignAssembly=true` so missing local author keys do not look like documentation drift,
 - **Decision-useful namespace checks** — uid front matter, availability, and `Extension Members` tables are validated against the actual public surface, while semantic gates reject inventory-only prose, weak inventory leads left intact beneath an appended start-here sentence, and mechanical prose templates shared across pages, requiring concrete when-to-use and start-here guidance with diagnostics such as `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING`,
-- **Deterministic repair plans** — `scripts/docfx.cs --repair-plan <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
+- **Deterministic assessment work queues** — `scripts/docfx.cs --assessment-queue <path>` converts noisy validation output into a grouped Markdown work queue with repository guidance, namespace/table repairs, a type-first required-example inventory, sample failures, cleanup gates, no-broad-restore rules, related-namespace coverage, and diff-review completion checks so agents do not update one namespace and forget the rest,
 - **Managed-reference-safe overwrite layout** — public non-abstraction types and public extension methods must have examples in DocFX overwrite content included by `build.overwrite`; the validator discovers Markdown from configured DocFX inputs instead of scanning the whole repository when `docfx.json` is at the root, concrete-type examples are tracked through an explicit inventory and created in readable authored files under `.docfx/api/types/`, legacy authored `.docfx/api/*.md` overwrite files move into `api/namespaces/` or `api/types/` instead of widening the glob to `api/**/*.md`, both overwrite trees stay excluded from `build.content`, C# extension-block compiler containers such as `<G>$...` are collapsed back to the authored outer static class, extension-method examples default to readable declaring-class type pages under `.docfx/api/types/` instead of URL-encoded method-UID filenames or namespace pages that mix overview and member UIDs, namespace pages fail validation when they embed secondary `uid:` / `example:` sections, and agents must rerun the completion repair loop until diagnostics and overwrite-layout failures are fixed or exact blockers are reported,
 - **Concept-led namespace quality** — moving concrete examples to type pages must not hollow out namespace pages; namespace pages still need newcomer-oriented fly-ins that explain the problem solved, when to use the namespace, where to start, type-family context, extension-method group explanations, availability, and pointers to representative type pages, and nearby type/member summaries should stay purpose-first too,
 - **Examples that teach a real workflow** — examples start from package IDs and package-level evidence before falling back to type/member-only searches, prefer README, package docs, tooling, tuning, functional-test, and external GitHub usage when available, and may include multiple related public types when that is what makes the consumer scenario understandable,