Git Repo Digest

Git Repo Digest

Use this skill to turn a deterministic digest workspace into website-ready or docs-ready Markdown. The bundled scripts/digest.cs runner owns repository access, evidence gathering, package discovery, evidence packing, prompt generation, and generated instructions. The agent owns reading that evidence, writing the digest files, and validating that every claim is grounded.

Critical

• Treat generated output as the source of truth. If manifest.json, instructions.md, prompts/*.prompt.md, or evidence/**/*.xml files disagree with this skill, follow the generated files unless they are internally inconsistent.
• Every authored result/*.md file must start with the YAML frontmatter contract from its generated prompt. Preserve generated static metadata such as package counts, library counts, target framework monikers, external links, family links, internal .md family URLs, and link glyphs unless raw evidence proves the hint wrong.
• For result/Index.md, preserve the generated title hint exactly unless raw evidence proves the product metadata is wrong. The runner resolves that title from a literal root Directory.Build.props <Product> value, then from a literal <Product> on the most-referenced top-level packable .csproj; it fails generation when no product can be resolved instead of falling back to repo-id.
• Preserve generated documentation links as validated static metadata. The runner resolves documentation hosts from PackageProjectUrl first, falls back to exact README.md / .nuget/<PackageName>/README.md documentation links that pass the documentation-host filter when package-specific URLs are not 200 OK, including emoji-prefixed Documentation headings and package-local "More documentation..." blocks before Related Packages, derives normal package API paths from .docfx/**/docfx.json metadata[].dest entries when they name the package, uses namespaces declared under src/<PackageName>/**/*.cs as additional DocFX page candidates, links packages with no DocFX API entry to the same docs root as result/Index.md, and fails before prose is written when no documentation URL returns 200 OK.
• Keep the workflow generic. The runner input is a full repository URL, not an implied owner/slug convention.
• Require the runner input --repo-url. The runner also requires --output-root; if the user omits it, resolve it deterministically to <active-workspace>/.bot/digests and pass that explicit value to the runner.
• Accept curated external usage repositories from the user's natural invocation when present, then pass each one to the runner with a repeated --external-repo-url flag.
• Map repository URLs and optional output paths positionally, regardless of whether the user typed a slash command, pasted bare URLs, or wrote a natural-language request. First URL is always the digest repo-url; a second value is output-root only when it is not a URL; every URL after the first is an external-repo-url.
• A bare list of two or more URLs is not ambiguous: treat it as one digest target plus external usage repositories. Do not reinterpret later URLs as separate digest targets unless the user explicitly says to digest multiple repositories independently, for example "digest both repos", "create separate digests", or "run one digest per URL".
• Do not second-guess URL mapping from repository names, package names, topical similarity, or whether an external repository seems likely to consume the digest repository. The runner is responsible for finding reference-plus-code matches or reporting that no external usage matches were found.
• A bare repository URL means generate a fresh workspace with the runner after output-root is known. Do not search for or reuse the latest existing {output-root}/{repo-id}/{run-id} merely because it exists.
• Reuse an existing digest workspace only when the user explicitly provides a workspace path or asks to reuse, continue, inspect, validate, or repair existing output.
• For fresh generation, treat prior result/*.md files, copied website/docs pages, sibling .bot/digests runs, and any previously authored digest prose as contamination, not evidence. Do not read, summarize, adapt, compare against, or use them as style/source material unless the user explicitly asked to reuse, continue, inspect, validate, or repair that exact existing workspace.
• If the user did not provide an output path, use <active-workspace>/.bot/digests as the output root so the workspace becomes <active-workspace>/.bot/digests/{repo-id}/{run-id}. Do not ask for confirmation just to use this default.
• If the user provides an output path, pass that value as --output-root; the runner still appends {repo-id}/{run-id}.
• Do not make repo-id customizable. It is derived from the final repository URL path segment.
• Do not make run-id customizable. It is always generated in UTC as yyyyMMdd-HHmmssZ.
• Do not make the result directory customizable. It is always result.
• Do not assume GitHub owner, repository host, organization, package prefix, website path, or docs domain from memory.
• Do not call an LLM provider from the runner. The calling agent is the brain that writes prose.
• Process one package evidence set at a time. Do not load all package evidence sets into the same prompt unless the generated manifest explicitly requires it.
• When the runtime supports subagents and the manifest has multiple independent package evidence sets, prefer one subagent per package. Give each subagent only its assigned package prompt, evidence files, instructions.md, the relevant manifest entry, and the complete-read contract. Subagents reduce context pressure; they do not reduce grounding requirements.
• Complete reads are mandatory for the files used in the current phase. For a package digest, read that package's prompt plus its required evidence files before writing. For the overview, read prompts/overview.prompt.md and every completed package result file required by the manifest before writing. The generated evidence indexes and chunks are a safer way to finish reading large evidence files; they are not permission to skip sections.
• Raw package evidence lives under evidence/{PackageName}/ as source.xml, tests.xml, projects.xml, readmes.xml, and external-usage.xml. Markdown prompts are task instructions; indexes are navigation aids only.
• Evidence indexes summarize chunks in a Contents column. They list stable packed-path labels such as Source Code, Test Coverage, NuGet Documentation, or Project Metadata when XML <file path="..."> entries are present.
• If a tool caps, truncates, summarizes, or partially displays a required full evidence file, read its *.index.md file and then read every chunk listed in numeric order. If the chunk reads are also capped or incomplete, continue by ranges or stop and report the blocker instead of writing from a subset.
• Do not use an evidence index as evidence for digest claims. It is a navigation aid; the full evidence file or all ordered chunks are the source evidence.
• Package evidence includes generated api-summary.md and engineering-signals.md reading aids. Use them to focus attention on likely public types, abstractions, extension points, lifecycle contracts, validation guards, factories, callbacks, and package-boundary clues, but verify every claim against raw source, tests, and project evidence.
• Write package result files before the overview result file.
• For the overview, explicitly read every completed package result file listed by the manifest. Reading only project/readme evidence is an incomplete overview workflow because the package digests are the primary editorial source.
• Do not invent APIs, package relationships, examples, dependencies, support statements, performance claims, or architectural claims not supported by the package evidence.
• Treat external usage evidence as curated consumer-usage inspiration, not API authority. It can shape ## Basic usage when current source evidence validates the APIs.
• Do not turn a source-backed structural risk into an unmeasured behavior claim. Phrases such as "most common mistake", "developers often", "users frequently", "popular choice", "widely used", or "typical failure" require explicit evidence such as package analytics, issue history, docs that say so, telemetry, survey data, or examples in the generated evidence. Without that evidence, describe the risk conditionally: "If you install X in a project that only needs Y, it adds Z."
• If required deterministic files are missing, stale, contradictory, or too large to use safely, stop and report the blocking issue instead of guessing.
• Do not copy results into a website or documentation tree unless the user explicitly asks for publication or sync.

Runner Contract

The skill bundles a .NET 10 file-based app:

scripts/digest.cs

Run it with dotnet run --file so it is not confused with a nearby project file:

dotnet run --file "<skill-root>/scripts/digest.cs" -- --repo-url <repo-url> --output-root <output-root>

Required inputs:

--repo-url      Fully qualified git repository URL
--output-root   Directory where the digest workspace will be written

Optional repeated input:

--external-repo-url  Public repository URL to clone and search locally for curated consumer usage

Fixed conventions:

repo-id      Derived from the final repository URL path segment, with .git removed
run-id       Derived from current UTC time
result dir   result

The runner requires the .NET 10 SDK or newer and git. It performs one shallow git clone for the repository under digest, optionally performs one shallow clone per provided external usage repository, discovers packages from the digest clone, and packs evidence with its bundled C# packer. The packer uses git ls-files for deterministic tracked-file membership, applies the runner's evidence classifiers, skips generated or low-signal paths, keeps text files only, and writes stable XML evidence files under evidence/{PackageName}/.

The runner also supports deterministic result validation for authored workspaces:

dotnet run --file "<skill-root>/scripts/digest.cs" -- --validate-results --workspace <workspace>

Use this as a deterministic gate after authoring result files. It reports unsupported package-owned API member access in C# examples, low-signal Basic usage patterns, non-Codebelt-style xUnit snippets, non-PascalCase MethodName_Scenario_ExpectedBehavior test-method names, and Basic usage snippets that do not compile and pass as temporary Codebelt.Extensions.Xunit tests. For executable validation, the runner creates temp test projects with direct package references for the page's NuGet package plus xUnit test packages and Codebelt.Extensions.Xunit, then runs dotnet test with bounded parallelism. The agent must revise from source evidence and rerun until validation passes.

Any result-file edit after a validation pass invalidates that pass. Rerun --validate-results after the final write to result/*.md, including after small copy edits, regenerated Basic usage snippets, or manual repairs.

Packing notes:

• The evidence packer is local-only. It does not call Node/npm, Repomix, browser automation, or a public packing service.
• The evidence packer does not emit third-party token counts, compression summaries, public GitHub search results, or external Secretlint results. Treat source, tests, project files, README files, and curated external usage files as the grounding surface. Treat generated public API summaries and engineering signals as reading aids only.
• External usage evidence is gathered only from user-provided repository URLs. The runner does not search GitHub.
• If any provided external usage repository cannot be cloned or inspected, the runner fails fast before digest prose is written.
• The runner rejects external usage URLs that normalize to the same repository as --repo-url.
• External usage selection uses a reference-plus-code rule: an external project must reference the current package, or a discovered package that transitively references the current package, either in its .csproj or nearest ancestor Directory.Build.props / Directory.Build.targets; selected C# files can come from source or test projects, but must contain a strong current-package marker such as the package id or namespace before public-symbol matches affect ranking.
• The runner does not try to evaluate MSBuild conditions on external package references. It uses references as a broad candidate signal and relies on strong code matches to decide what external source or test files are worth packing.
• The runner filters known low-signal files such as GlobalSuppressions.cs from packed evidence. Do not recreate or infer digest claims from those files.
• The runner follows Codebelt repository conventions for discovery: source projects live under src/, owned tests live under test/, and owned test projects are named after the package plus .Tests for libraries or .FunctionalTests for apps. It does not scan generic tests/ roots or broader suffix variants such as .UnitTests or .IntegrationTests. Within the fixed test/ root, it prefers a dedicated owned test project, then a single unambiguous direct project reference. If only downstream package tests match a shared base package prefix, the runner leaves Test path undiscovered instead of assigning another package's tests.
• Source files are source evidence even when their type or file names end in Test, such as framework abstractions named WebHostTest. Test evidence is limited to files under the discovered owned test/ path.
• If .NET 10 or git is unavailable, stop and report the missing dependency.

Expected Workspace

The digest root is chosen by the caller when an output path is supplied. When the user does not supply an output path, the deterministic default staging root is:

<active-workspace>/.bot/digests

When that default root is used, the generated workspace is:

<active-workspace>/.bot/digests/{repo-id}/{yyyyMMdd-HHmmssZ}

If the user supplies an output path, use that value as the root while keeping the same generated child shape:

{output-root}/{repo-id}/{yyyyMMdd-HHmmssZ}

Generated shape:

{output-root}/{repo-id}/
  manifest.json
  instructions.md
  prompts/
    {PackageName}.prompt.md
    overview.prompt.md
  evidence/
    {PackageName}/
      source.xml
      tests.xml
      projects.xml
      readmes.xml
      external-usage.xml
      api-summary.md
      engineering-signals.md
      source.index.md
      source.chunks/
        0001.xml
  result/
    Index.md
    {PackageName}.md

The manifest is authoritative after generation. Always follow the manifest for concrete package names, prompt paths, evidence paths, evidence index paths, evidence chunk paths, result paths, and phase order. Manifest targets also include frontmatterHints, which are generated metadata values for the YAML frontmatter required in each result file. For the overview target, frontmatterHints.title is repository-owned product metadata, not a URL-derived repository id. Documentation entries in frontmatterHints.links are validated URLs only; the runner does not emit repository #readme documentation fallbacks.

Workflow

Step 1: Resolve Inputs

Collect or infer these runner inputs:

• repo-url: required. Ask for it if the user gives only a slug or a repository nickname.
• output-root: pass this explicitly to the runner. If the user did not provide an output path, use <active-workspace>/.bot/digests.
• external-repo-url: optional and repeatable. Use only public repository URLs the user supplied as curated usage sources.

Apply this positional mapping to slash commands, pasted bare values, and natural-language invocations alike:

<digest-repo-url> <optional-output-folder> <optional-external-url> <optional-external-url>

Map them as follows:

• First URL: repo-url.
• Second value: output-root only when it is not a URL.
• Every URL after the first, including the second value when it is a URL: repeated external-repo-url values.
• If the second value is a URL and no output root was supplied, keep it as external-repo-url and use <active-workspace>/.bot/digests as output-root.
• Do not ask whether later URLs should be independent digest targets. That question is already answered by the positional mapping unless the user explicitly asks for multiple independent digests.
• Do not reject or question an external-repo-url because the repository name or domain seems unrelated. Pass the user-supplied URL to the runner and let deterministic external usage selection decide whether it contributes evidence.

Examples:

• https://github.com/example/library https://github.com/example/consumer maps to --repo-url https://github.com/example/library --output-root <active-workspace>/.bot/digests --external-repo-url https://github.com/example/consumer unless the user supplies an explicit output path.
• /git-repo-digest https://github.com/example/library .bot/digests https://github.com/example/consumer maps to --repo-url https://github.com/example/library --output-root .bot/digests --external-repo-url https://github.com/example/consumer.
• generate a digest for https://github.com/example/library using https://github.com/example/consumer as evidence uses the same mapping: first URL is the digest repo, second URL is external usage evidence.
• digest both https://github.com/example/library and https://github.com/example/other-library separately is different because the user explicitly requested independent digests; handle that as separate digest runs.

Do not ask for repo-id, run-id, or result directory.

Step 2: Generate or Locate the Digest Workspace

Choose the workspace mode from the user's input, not from folders you happen to discover:

• Generate fresh when the user provides a repository URL and does not explicitly ask to reuse existing output.
• Generate fresh even when {output-root}/{repo-id} already contains prior run folders; the runner appends a new UTC {run-id}.
• In fresh mode, do not inspect old result/*.md files, website copies, docs copies, sibling run folders, or other digest prose before writing. The only digest-writing inputs are the newly generated workspace's manifest.json, instructions.md, prompts, evidence files, evidence indexes, evidence chunks, and any result files produced earlier in the same new workspace phase order.
• Locate existing only when the user explicitly provides a digest workspace path such as {output-root}/{repo-id} or {output-root}/{repo-id}/{run-id}, or asks to reuse, continue, inspect, validate, or repair existing output.
• If the user provides {output-root}/{repo-id} as an existing-workspace path and does not name a run-id, inspect the folder and ask before choosing among prior run folders unless the user asked for the latest run.

For a fresh run, execute the bundled runner from this skill:

dotnet run --file "<skill-root>/scripts/digest.cs" -- --repo-url <repo-url> --output-root <output-root> [--external-repo-url <external-url>]...

The runner writes deterministic evidence files, prompt files, and the result folder. It does not call an LLM and does not overwrite existing result/*.md files.

Step 3: Read the Run Contract

Read only these root files first:

manifest.json
instructions.md

From manifest.json, identify:

• repository URL
• repository identifier
• output directory
• package phase entries
• overview phase entry
• each package prompt path
• each evidence file path
• each evidence index path
• each ordered evidence chunk path
• each external usage evidence path, index path, and ordered chunk path
• each result file path
• each target's frontmatterHints values
• dependency order

If there is no manifest, infer the package list only from prompts/*.prompt.md and evidence/*/ folders and stop to tell the user the manifest is missing. Continue only if the user explicitly accepts the degraded workflow.

Step 4: Write Package Digests

For each package in the first phase:

1. Open only that package's prompt, evidence artifacts, and instructions.md if needed.
2. Try to read each required evidence file completely. If a read output is capped or truncated, open the manifest-declared evidence index and then read every manifest-declared chunk in numeric order until the whole evidence file has been inspected.
3. Confirm the package result path is result/{PackageName}.md or the manifest's declared equivalent.
4. Start the result with the generated YAML frontmatter schema, replacing editorial placeholders for title, description, and lede with grounded package-specific prose.
5. Write the exact required sections from the generated package prompt.
6. Ground Key APIs prose and examples in source, tests, project files, README files, external usage files, or metadata found in the evidence.
7. For ## Basic usage, prefer representative external usage when it exists, validates against current source evidence, and gives a clearer consumer scenario than owned tests.
8. Use generated summaries and engineering signals to revisit likely design invariants, lifecycle contracts, callback wiring, factory boundaries, generic type constraints, exception guards, and package-boundary decisions in the raw source.
9. Do not document non-public members as APIs, but do inspect internal implementation when it explains public lifecycle behavior, validation, callback flow, or package boundaries.
10. Keep examples compact and use real namespaces, type names, method names, and constructor signatures from the evidence.
11. If the evidence proves the package is a convenience, aggregate, or metadata-only package with no source of its own, write that honestly instead of inventing APIs.

Do not use another package's evidence to fill gaps unless the current prompt explicitly includes it or the manifest marks that relationship as required.

When editing an existing package result:

• Read the affected file immediately before editing. Do not rely on memory, stale subagent output, or a previously displayed excerpt.
• When replacing a named section such as ## Basic usage, select from the section heading through the complete section body. Do not start the replacement inside the section or inside a fenced code block.
• If replacing a code example, include the opening fence, the entire code block, the closing fence, and any section-specific explanatory prose in the replacement boundary.
• After every result-file edit, re-read the affected section and verify the heading appears exactly once, every fenced code block has a matching closing fence, and no old fragment survived above or below the replacement.
• Rerun --validate-results after the final result-file edit. A previous validation pass is stale after any result-file change.

Optional Subagent Strategy

If the agent runtime can delegate work, use subagents to keep each package evidence set isolated and roomy:

• Spawn at most one subagent per package from the current package phase.
• Give each subagent a narrow task: completely read its assigned prompt and evidence set, using evidence indexes and ordered chunks if a full evidence file is capped, follow instructions.md, write or draft only its assigned result/{PackageName}.md, and report any unreadable or contradictory evidence.
• Do not give one subagent multiple package evidence sets unless the manifest says those packages are dependent.
• Do not ask a subagent to write result/Index.md until all required package result files exist.
• The main agent is the orchestrator and final editor. It gathers each subagent's completed package result file, reported caveats, and validation notes, then authors result/Index.md itself from those completed digests plus prompts/overview.prompt.md and supplementary project/readme evidence as needed.
• The coordinating agent remains responsible for manifest order, final file placement, overview synthesis, validation, and final reporting.

Subagent summaries and caveats are useful handoff material for the orchestrator, but they are not a replacement for the completed package result files required by the overview phase.

Step 5: Write the Overview

Write result/Index.md only after package digests exist.

Open and completely read prompts/overview.prompt.md and every completed package result file listed by the manifest or by the generated required package-digest source section. Treat the completed package result files as the required package-digest source for result/Index.md; treat project/readme evidence as supplementary repository evidence for relationships, project metadata, README framing, and package inventory. Reading only project/readme evidence is not sufficient when package result files exist.

If package digests were produced by subagents, collect their reported caveats and validation notes before drafting the overview. Use those notes to avoid overclaiming, but ground the overview in the completed package result files, prompts/overview.prompt.md, and supplementary project/readme evidence as needed.

The overview should help readers understand the repository's concepts before they open package-specific pages. It should not behave like a package inventory, repeat package-page summaries, or amplify unsupported claims.

Write result/Index.md as a conceptual overview:

• Start with the generated YAML frontmatter schema, preserving the generated title because it comes from repository-owned <Product> metadata, and replacing editorial placeholders for description and lede with grounded repository-level prose.
• Keep NuGet URLs inside links, with the index NuGet link queryable and package-page NuGet links package-exact. Keep generated repository, releases, issues, documentation, NuGet, and familyLinks entries when they are present in frontmatterHints.
• Treat generated documentation links as already validated by the runner. Do not replace them with repository README anchors or invented docs paths.
• Use the generated overview prompt's exact required headings, currently ## Overview, ## Concepts, and ## Usage guidance.
• Start ## Concepts with a short introductory paragraph before the first concept heading.
• Use concept subsection headings for ideas, patterns, boundaries, responsibilities, or trade-offs, not package names.
• Derive concept candidates from every completed package digest's ## Overview, ## Key APIs, ## Basic usage, and ## Usage guidance sections, then connect package responsibilities and APIs across layers where the evidence supports it.
• Build concepts from coverage first, then merge only true duplicates. A concept should survive when ignoring it would hide a substantial package-owned capability, extension model, boundary, or trade-off.
• Preserve distinct capability domains represented by package-owned APIs even when they share the same lower-level pattern, dependency, or factory model.
• Before writing, do a coverage pass against completed package names and Key APIs; any package-owned domain that disappears needs either its own concept or an explicit merge into a named related concept.
• Include as many concept subsections as the completed package digests genuinely support; do not force a fixed concept count.
• Link to package pages only as inline relative Markdown links such as [Package.Name](Package.Name.md).
• For single-package repositories, skip package-selection framing entirely and still explain the real concepts the package introduces.
• For multi-package repositories, explain package coverage inside concept prose instead of creating package tables or one subsection per package.
• Do not repeat Basic usage examples, API inventories, installation commands, or package-specific overview paragraphs from package pages.

For usage guidance, separate evidence from inference:

• It is grounded to say a meta-package brings in referenced packages or framework references when the project files show that relationship.
• It is grounded to recommend the smaller package first when the generated instructions ask for "use less" guidance and the package boundaries support that recommendation.
• It is not grounded to call that situation "the most common mistake" or describe actual developer behavior unless the evidence includes frequency evidence.
• Prefer neutral phrasing such as "Avoid installing the aggregate package when..." or "Choose the aggregate package only when..." over popularity or frequency claims.

If any package digest is missing, decide from the manifest:

• If the overview depends on all package digests, stop and report the missing files.
• If partial overview generation is explicitly allowed, name the missing package digests in the final response.

Step 6: Validate Grounding and Shape

Run the deterministic result validator and require a pass before reporting completion:

dotnet run --file "<skill-root>/scripts/digest.cs" -- --validate-results --workspace <workspace>

This validator catches C# Basic usage member accesses on package-owned receiver types that do not exist in source evidence, non-Codebelt-style xUnit snippets, test methods not named with the exact PascalCase MethodName_Scenario_ExpectedBehavior convention, malformed Basic usage sections, low-signal Basic usage examples, and snippets that fail an executable Codebelt.Extensions.Xunit harness. It intentionally does not guess replacement APIs. If it reports an error, revise the example from source evidence and rerun validation until it passes.

The executable validation path is optimized for large digest workspaces: it writes direct package references into each temporary test project, runs examples with bounded parallelism, and honors GIT_REPO_DIGEST_VALIDATE_PARALLELISM when a host needs to lower or raise concurrency. Do not replace this with manual dotnet add package loops.

Treat validation as a final-state check, not a milestone from earlier in the session. If any result/*.md file changes after --validate-results passes, rerun validation before reporting completion.

Use a tight repair loop when validation fails:

• Treat targeted rg searches as triage only. A search hit is not automatically a defect; decide from context and source evidence, for example HttpStatusCode.OK is not the same as a toy literal response body.
• Create a short repair ledger for each validation diagnostic: result file, exact diagnostic, affected Basic usage block, source evidence needed, and planned edit.
• Inspect the failing snippet and the exact failing line before speculating about framework internals, overload resolution, dependency injection, logger categories, or validator behavior.
• Allow at most one quick hypothesis pass. If the cause is not confirmed from source, tests, or the executable failure line, replace the example from source-backed evidence instead of continuing an open-ended investigation.
• Prefer one focused edit per diagnostic, then rerun --validate-results. Do not treat unrelated preflight search hits as reasons to rewrite passing examples.

Before finishing, verify:

• Every manifest package has a corresponding result file.
• result/Index.md exists when the manifest includes an overview entry.
• Result filenames match manifest paths.
• Evidence index and chunk paths in the manifest exist for every generated evidence file.
• Required headings from the generated package prompt are present verbatim.
• Required headings from the generated overview prompt are present verbatim.
• Every result file begins with YAML frontmatter before the first Markdown heading.
• Frontmatter includes title, description, lede, pageKind, packageCount, libraryCount, targetFrameworks, targetFrameworkMonikers, license, links, and familyLinks; package pages also include packageId.
• The links array contains NuGet entries: package pages point to exact package URLs, while result/Index.md uses the generated queryable NuGet URL.
• The familyLinks array appears on both result/Index.md and package pages, links to every package page with relative PackageName.md URLs, and keeps package-context glyphs unless evidence supports a better glyph.
• Prefer generated family glyphs derived from .nuget/{PackageName}/README.md Related Packages sections when available; otherwise keep the generated package-name heuristic glyph.
• Link entries preserve context-specific glyphs for NuGet, repository, releases, issues, and documentation links when those links are available.
• No frontmatter value still contains placeholder wording such as "Write a source-grounded" or "Write a short lede".
• result/Index.md has an introductory paragraph after ## Concepts and before the first concept subsection.
• result/Index.md uses concept headings instead of package-named subsections.
• result/Index.md concepts synthesize completed package ## Overview, ## Key APIs, ## Basic usage, and ## Usage guidance sections instead of ignoring package-level APIs or scenarios.
• Every completed package digest contributes to at least one concept subsection or is intentionally merged with a named related concept because it makes the same point.
• Distinct package-owned capability domains are not collapsed into a generic umbrella concept when separate subsections would better reveal important work.
• result/Index.md connects related packages in concept prose where package responsibilities, dependencies, or APIs show a relationship.
• result/Index.md does not contain a package-selection table unless a future generated prompt explicitly asks for one.
• Package links in result/Index.md are inline relative Markdown links such as [Package.Name](Package.Name.md).
• No result file contains analysis notes, citations, XML, JSON, confidence scores, or chat commentary unless the generated prompt explicitly asks for them.
• Code examples mention only APIs visible in the relevant evidence.
• Basic usage examples pass API-shape validation: every namespace, type, constructor, method, extension method, override, generic constraint, and property access used in the snippet exists on the declaring type in source evidence or on the framework type shown by the snippet's static type.
• Basic usage examples pass Codebelt xUnit validation: every C# test snippet includes using Codebelt.Extensions.Xunit; and using Xunit;, uses a file-scoped consumer namespace such as namespace MyProject.Tests;, omits using Xunit.Abstractions;, declares a public test class inheriting from Test or a source-backed Codebelt test base class that the evidence shows derives from Test, defines a constructor that accepts ITestOutputHelper output and passes that output helper to the base constructor, names the single [Fact] or [Theory] method with exactly three PascalCase parts in the MethodName_Scenario_ExpectedBehavior shape such as ResolveOptions_MissingName_ThrowsOptionsException, and uses TestOutput.Write, TestOutput.WriteLine, or TestOutput.WriteLines for concise human-friendly scenario output.
• Basic usage examples pass executable validation: the validator writes each Basic usage C# block to a temporary Codebelt.Extensions.Xunit project with direct package references to the page's NuGet package plus xUnit test packages and Codebelt.Extensions.Xunit, runs dotnet test with bounded parallelism, and treats any compile or test failure as blocking.
• Basic usage sections are structurally valid: package pages have one top-level ## Basic usage section, headings inside fenced code blocks do not count as Markdown section boundaries, and every Basic usage section contains at least one complete fenced C# code block.
• If executable validation fails, rewrite the example from source, tests, and source-valid external usage, then rerun --validate-results until the workspace passes.
• Basic usage examples inspired by external usage validate every API call, constructor, namespace, and extension method against current source evidence.
• Basic usage examples for convenience, aggregate, metadata-only, or no-assembly packages validate referenced-package API shape against the referenced package's source evidence, not the aggregate package's empty or metadata-only evidence.
• Property accesses in C# examples are API-shape claims. For any real package-owned type, fixture, base class, builder, options object, context, factory result, or service object, verify that the accessed member is declared by the relevant source evidence or by a known framework type used with the correct static type.
• External usage evidence may shape the consumer scenario, but stale external code does not override current source or test evidence.
• For normal code packages, ## Basic usage contains exactly one C# fenced code block unless the generated prompt explicitly allows more.
• For normal code packages, the Basic usage C# example is a complete Codebelt-style test snippet with explicit using statements, a file-scoped consumer namespace, a public test class inheriting from Test or a source-backed Codebelt test base class that the evidence shows derives from Test, a constructor with ITestOutputHelper output passed to the base constructor, useful TestOutput.Write, TestOutput.WriteLine, or TestOutput.WriteLines output, and exactly one [Fact] or [Theory] method named with exactly three PascalCase parts in the MethodName_Scenario_ExpectedBehavior shape unless the generated prompt explicitly allows more.
• For normal code packages, the Basic usage example demonstrates a realistic consumer task where the package API changes how the code is written, not just a smoke test that calls one method with a literal value.
• For normal code packages, the Basic usage example shows a system under test interacting through the package API when the package supports DI, pipelines, handlers, factories, lifecycle hooks, loggers, collectors, stores, recorders, fixtures, providers, or test hosts.
• For normal code packages, the two-sentence Basic usage explanation describes only what the example actually demonstrates.
• For convenience, aggregate, metadata-only, or no-assembly packages that reference code packages, ## Basic usage contains one C# fenced code block per referenced code package.
• For convenience packages, each Basic usage example is introduced by a third-level heading naming the referenced package, for example ### Codebelt.Extensions.Xunit.
• For convenience packages, each referenced-package example follows the same Codebelt-style xUnit shape and contains exactly one [Fact] or [Theory] method named with the PascalCase MethodName_Scenario_ExpectedBehavior convention.
• For convenience packages, the Basic usage section includes a final paragraph explaining that the convenience package provides the single package reference and that the APIs come from the referenced packages.
• Convenience-package examples must not reuse individual package Basic usage examples verbatim.
• Convenience-package examples must not describe referenced APIs as if they are implemented by the convenience package itself.
• Convenience-package examples should be shorter and use-case-oriented. They should complement, not duplicate, the normal package pages.
• Every C# Basic usage example includes necessary using statements, prefers explicit imports, uses a file-scoped consumer namespace, and includes at least one assertion or observable result plus human-friendly TestOutput context.
• Every C# Basic usage example is small but complete enough to understand without hidden files, hidden helpers, hidden services, or unexplained setup.

…(truncated)