chore: release 0.1.0-alpha : Trusted Publishing workflow, CHANGELOG, pack dry-run tooling

[Shewart]

Summary

Release plumbing for the first NuGet cut. All code for 0.1.0-alpha is already in main — this branch adds the mechanics to ship it via NuGet Trusted Publishing (OIDC), no long-lived API key.

What's new

.github/workflows/release.yml

Tag-triggered release pipeline: fires on v[0-9]+.[0-9]+.[0-9]+* push. Steps:

1. Restore → build Release → test
2. dotnet pack shelldocs.slnx → 6 .nupkg + 6 .snupkg symbol packages
3. NuGet/login@v1 — exchanges GitHub OIDC token for a 1-hour NuGet API key
4. Push each package to nuget.org with --skip-duplicate (re-runs are safe)
5. Create GitHub Release with auto-generated notes from tag

Includes workflow_dispatch with dry_run: true (default) for pack-and-validate runs that skip the NuGet push.

Trusted Publishing posture — no NUGET_API_KEY secret in the repo. Job declares environment: release + permissions: id-token: write; the NuGet login action verifies GitHub's OIDC token against a policy registered on nuget.org (pinned to owner shellui-dev / repo shelldocs / workflow release.yml / environment release). Blast radius = this specific workflow file in this specific repo. Rotation burden = zero. Verified against Microsoft's live docs.

CHANGELOG.md

Keep-a-Changelog format. Full [0.1.0-alpha] — 2026-07-25 entry lists all six packages and every shipped feature: content primitives, API-reference primitives, chrome, auto-chrome via DocsPageState, search with body-text indexing, consumer DX (assembly-scan registration, aliases, brand logo, package selector), animation polish, CLI commands. Also documents known limitations for the alpha window.

docs/RELEASING.md

Full runbook. One-time setup covers: package-ID availability check, release GitHub environment creation, Trusted Publishing policy registration on nuget.org (with exact field names from the current docs — Repository Owner, Repository, Workflow File filename-only, Environment), NUGET_USER environment secret. Steady-state section reduces subsequent releases to three commands: bump Directory.Build.props, update CHANGELOG, tag + push.

scripts/pack-dry-run.ps1 + scripts/pack-dry-run.sh

Local pack into ./nupkgs-dryrun/, extract each .nupkg, verify README embed, print id + version + size for eyeball check. Fails loud on missing README. Ran successfully during branch prep:

ShellDocs.CLI.0.1.0-alpha.nupkg          964 KB   id=ShellDocs.CLI          version=0.1.0-alpha
ShellDocs.Components.0.1.0-alpha.nupkg    68 KB   id=ShellDocs.Components   version=0.1.0-alpha
ShellDocs.Core.0.1.0-alpha.nupkg          18 KB   id=ShellDocs.Core         version=0.1.0-alpha
ShellDocs.Markdown.0.1.0-alpha.nupkg      15 KB   id=ShellDocs.Markdown     version=0.1.0-alpha
ShellDocs.Templates.0.1.0-alpha.nupkg     11 KB   id=ShellDocs.Templates    version=0.1.0-alpha
ShellDocs.Tokens.0.1.0-alpha.nupkg         9 KB   id=ShellDocs.Tokens       version=0.1.0-alpha

OK — all packages passed validation

Changed

README.md — status line updated to reflect the shipping state, links to CHANGELOG and docs/RELEASING.md.

Pre-merge configuration already done on GitHub + NuGet

• ✅ release environment created in repo Settings → Environments; deployment restricted to v*.*.* tag pushes; NUGET_USER set as environment secret (nuget.org profile name)
• ✅ Package IDs ShellDocs.CLI / .Components / .Core / .Markdown / .Templates / .Tokens all verified free on nuget.org
• ✅ Trusted Publishing policy registered at nuget.org — owner shellui-dev, repo shelldocs, workflow release.yml, environment release

Test plan

• dotnet build shelldocs.slnx — clean, 0 warnings, 0 errors
• dotnet test shelldocs.slnx — 139 / 139 passing
• bash scripts/pack-dry-run.sh — all six packages pack + validate; README embedded in each; correct 0.1.0-alpha version from Directory.Build.props
• Workflow action name (NuGet/login@v1), permissions (id-token: write + contents: write), output name (NUGET_API_KEY), and TP policy field names verified against Microsoft's current live docs

Post-merge — cut the release

git tag v0.1.0-alpha
git push origin v0.1.0-alpha