[SunSi12138]

Closes #573.

Summary

• Rewrite the root README around the public NuGet consumer path: Contracts → Server → Client.
• Document the current package graph accurately: Contracts use SharpLink.Sdk; client/server add their runtime packages; the SDK carries the Generator analyzer and does not pull SharpLink.Runtime into a contracts-only project.
• Add canonical runnable samples/QuickStart.* projects for the minimum real RPC path.
• Add samples/ProductionTemplate.* projects covering TLS, timeout/resource limits, logging/telemetry, and graceful drain without insecure certificate shortcuts.
• Make copied sample projects NuGet-first by default, while samples/Directory.Build.props supplies the repository-only ProjectReference override.
• Extend the existing package-smoke pipeline so QuickStart and ProductionTemplate are copied to a clean temporary directory and restored/built from freshly packed local .nupkg artifacts with a fresh NuGet cache. Package Source Mapping pins SharpLink.* to the local feed; QuickStart then runs a real Server/Client RPC.
• Auto-run the existing PR Quick/package-smoke path for README/sample/package-graph changes while keeping the full codec compatibility matrix on manual workflow_dispatch; PR metadata edits do not retrigger the heavy validation.

Package-smoke assertions

The package smoke verifies that:

• SharpLink.* resolves from the freshly packed local feed rather than being silently satisfied by nuget.org;
• the contracts project does not resolve SharpLink.Runtime;
• SharpLink.Sdk contains SharpLink.Generator.dll under analyzers/dotnet/cs;
• QuickStart Contracts, Server, and Client restore/build from the freshly packed local version;
• ProductionTemplate Contracts, Server, and Client also build in copied/package mode;
• the QuickStart Server reaches Ready, the Client completes a real unary RPC (Hello, SharpLink!), and the Server performs the sample's explicit graceful shutdown path.

Review follow-ups

Self-review findings are resolved:

• copied QuickStart/ProductionTemplate projects now default to PackageReference instead of repo-relative ../../src references;
• package source mapping prevents published SharpLink packages from masking a broken local pack;
• the ProductionTemplate client's startup timeout is scoped to Connect/Ready, while the sample RPC demonstrates the configured 5 s UseRequestTimeout fallback independently.

Scope

• Base: dev@ba3a16c1c940fa6f516d2d85a631f46408e3f8d9
• Head: c8b8440ac5458531d52e9e40fa42e0b73a1c240f
• Branch is 9 commits ahead / 0 behind dev.
• The PR diff remains 18 README/sample/package-smoke/CI files; production changes from test(runtime): stabilize terminal and reconnect timing flakes #613/test(client): stabilize ready reconciliation observation #615/test(hosting): make cached health task regression deterministic #616/fix(protocol): enforce negotiated inbound frame limit #614 are merge ancestry from dev, not docs: make README NuGet-first with runnable templates #608 diff.

Validation

Exact-head validation is green:

• PR Fast 34294505925 — success on rerun, including formatting, maintainability, Release build, generated-assembly Runtime boundary check, Unit Tests, Generator Tests, Load Test Tests, and allocation gate.
• CodeQL 34294505960 — success.
• PR Quick 34294506090 — success, including Debug/Release build, Unit/Generator/Load tests, Integration Tests, NativeAOT transport/topology smoke, Pack, NuGet package-contract verification, source-mapped local-nupkg QuickStart E2E + ProductionTemplate package build, Demo Oneway, Load Smoke, and Chaos Smoke.

The first PR Fast attempt on this head had one unrelated 30 s timeout in IdempotentUnaryShouldRetryRemoteUnavailableAndExposeResponseObservation (1587/1588 Unit Tests passed). The same exact head's PR Quick Unit Tests passed, and the PR Fast rerun passed the full suite. No #608 code was changed in response.

[SunSi12138]

Correction: #609 was created from my mistaken interpretation of default-branch (main) code-search results as current dev. Direct dev verification shows #287 is already implemented correctly; #609 has been closed as not planned. #573 is not blocked on it. I am auditing current dev directly for any remaining pseudo-parameter/control-surface drift before continuing #573.

[SunSi12138]

Ready-for-review follow-up is also green on the same head a840be31b4bd69f7efb7edb112776ad66d33a0c1:

• PR Fast 34256161412 — success.
• PR Extended 34256179198 — success after rerunning only the extended job.
• Desktop codec produce/verify matrix and summary — success.

The first Extended attempt had one unrelated static-cluster timing failure (StaticClusterShouldExpandWithinGlobalAndPerEndpointBudgets, 450/451 integration tests passed). The same head had already passed Integration in PR Quick, and the Extended rerun passed Integration, NativeAOT, Pack, package-contract verification, local-nupkg package smoke, Demo Oneway, and Load Smoke.

No code changes were made in response to either observed timing flake.

[SunSi12138]

Self-review found three concrete issues to address before merge: two medium-priority acceptance/validation gaps and one lower-priority sample-semantic issue. The README/package map/version, Quick Start lifecycle, production feature coverage, solution compilation coverage, and exact-head CI evidence otherwise look consistent. Note separately that dev has advanced to b02bffebf3c4f0316f4d047f851555d3261046a1, so this PR is currently 1 commit behind and should be synchronized/revalidated after the review fixes.