Publish opt-in AgentDocs guidance and upgrade Trellis to alpha.539

[xavierjohn]

Summary

• Publish opt-in schema-v1 AgentDocs guidance through the private Trellis.AgentDocs.Packaging 0.1.0-preview.20 helper in all three NuGet packages. Remove the legacy restore/build-time instruction-copy targets; normal consumer restore and build no longer write repository instructions.
• Keep four unique Microservices guides: Abstractions owns the shared contract and cookbook, Yarp owns gateway guidance, and AspNetCore owns consumer guidance. Cross-package references link to companion guides and Core-owned trellis/ documents through upstream/ aliases, replacing moving GitHub-main links in package copies without duplicating upstream guides. Canonical source guides retain navigable GitHub links; pack-time projection stages the virtual-reference form without changing source files.
• Upgrade the seven upstream Trellis package pins from 3.0.0-alpha.532 to 3.0.0-alpha.539, consuming Core's newly migrated complete first-party guidance bundle. Keep FluentAssertions at 7.2.2 because v8's licensing terms are not approved.
• Document explicit tool installation, publisher approval and synchronization in the package READMEs. Wire real-package and combined gateway/service consumer conformance into build and publishing workflows.

Guidance is installed only with the independently versioned Trellis.AgentDocs tool and explicit approval of trusted publishers. References neither add NuGet dependencies nor bypass approval. JWT contracts and runtime authorization APIs are unchanged.

Depends on the already merged and published Core publisher migration in xavierjohn/Trellis#800. The Copilot instructions also update the review-model preference from gpt-5.5 to gpt-5.6-sol.

Validation

• Windows and isolated Linux Release builds: zero warnings or errors; all 352 Microsoft.Testing.Platform tests passed on each platform, including the end-to-end harness.
• All three actual nupkgs passed published AgentDocs preview.20 strict validation; no helper dependency or consumer build-target leakage.
• Combined gateway/service consumer covered unapproved-reference notices, approval isolation, strict cross-package and fragment resolution, exact target versions and hashes, four unique Microservices guides, and byte-stable repeated sync/check.
• Consumer restore/build preserved consumer-owned instructions and installed no guidance. All 12 restored project graphs aligned to alpha.539; the published Core manifest contained all 27 first-party guides.
• Canonical-source targets and exact projected package text, API-reference lint, stale-doc audit, UTF-8 BOM and diff checks passed; independent code review found no significant issues.

[github-actions]

Test Results

352 tests  ±0   352 ✅ ±0   1m 4s ⏱️ +4s
  4 suites ±0     0 💤 ±0 
  4 files   ±0     0 ❌ ±0 

Results for commit be4ec85. ± Comparison against base commit 8b13e06.

♻️ This comment has been updated with latest results.

[Copilot]

Copilot review overview

🟡 Changes recommended

The new virtual upstream links break canonical API-reference navigation outside AgentDocs installations.

Review effort: Balanced
Findings: 3

Open (3)

• Missing upstream files break canonical API reference links · New
• Upstream documentation links resolve only after AgentDocs synchronization · New
• YARP API reference contains broken upstream links · New

What changed in this PR

Migrates all three packages to opt-in AgentDocs guidance and upgrades the aligned Trellis dependencies to alpha.539.

Changes:

• Adds AgentDocs manifests, cross-package references, and consumer guidance.
• Removes legacy build-time documentation copying.
• Adds package conformance checks to CI and publishing workflows.

File	Description
Trellis.Yarp/​src/​Trellis.Yarp.csproj	Registers YARP guidance.
Trellis.Yarp/​README.md	Documents AgentDocs setup.
Trellis.Yarp/​NUGET_README.md	Adds consumer instructions.
Trellis.Microservices.AspNetCore/​src/​Trellis.Microservices.AspNetCore.csproj	Registers consumer guidance.
Trellis.Microservices.AspNetCore/​README.md	Documents AgentDocs setup.
Trellis.Microservices.AspNetCore/​NUGET_README.md	Adds consumer instructions.
Trellis.Microservices.Abstractions/​src/​Trellis.Microservices.Abstractions.csproj	Registers contract and cookbook guidance.
Trellis.Microservices.Abstractions/​src/​README.md	Documents AgentDocs setup.
Trellis.Microservices.Abstractions/​src/​NUGET_README.md	Adds consumer instructions.
README.md	Describes guidance ownership and approval.
docs/​docfx_project/​api_reference/​trellis-api-yarp.md	Replaces upstream links with virtual references.
docs/​docfx_project/​api_reference/​trellis-api-microservices-cookbook.md	Documents virtual upstream guidance.
docs/​docfx_project/​api_reference/​trellis-api-internal-jwt.md	Replaces upstream links with virtual references.
Directory.Packages.props	Upgrades Trellis and pins AgentDocs helper.
Directory.Build.targets	Defines packaged guidance and references.
CHANGELOG.md	Records migration and dependency upgrade.
build/​Trellis.ApiReference.targets	Removes legacy copy logic.
build/​Trellis.ApiReference.Payload.targets	Removes legacy payload targets.
build/​test-package-layout.ps1	Removes obsolete layout checks.
build/​test-guidance-packages.ps1	Adds package and consumer conformance testing.
.github/​workflows/​publish-nuget-org.yml	Validates guidance before publishing.
.github/​workflows/​publish-github-packages.yml	Validates guidance before publishing.
.github/​workflows/​build.yml	Packs and validates guidance on PRs.
.gitattributes	Stabilizes API-reference line endings.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.