目标

在发布前从 NuGet 用户首次接入 的视角做一次易用性收口：让用户不需要先理解仓库构建、RuntimeContext、Manifest、Assembly Catalog 等内部/高级概念，就能完成安装、定义契约、启动 Server、发起 Client 调用、正确释放，并能快速理解关键语义和导出可用于提 issue 的脱敏诊断信息。

创建基线：

dev@81207868a24050da7933aac87090143555f268bd

执行时仍应重新记录实际 dev HEAD，并以当时真实 package graph / public API 为准。

Related: #86（public API/package baseline、migration docs、release gate）。本 tracker 不重复 #86 的 API freeze/migration 工作，而聚焦 新用户 onboarding + semantic clarity + supportability。

子 issue

• [docs][release] README 改为 NuGet-first Contracts → Server → Client 入门与生产模板 #573 — README 改为 NuGet-first Contracts -> Server -> Client 入门，并提供独立 production-shaped template；README 示例以会编译/运行的 canonical sample 为事实源。
• [docs][release] 增加调用超时、readiness、OneWay、替换与 retry 语义速查 #574 — 在 Quick Start 附近增加 timeout/deadline、readiness、OneWay、replacement、retry 的 Semantic Quick Reference。
• [diagnostics][release] 提供可导出的脱敏 Client/connection support snapshot #575 — 提供按需生成、schema-versioned、默认可安全附到公开 issue 的脱敏 Client/connection support snapshot。

如果实施中发现某个语义本身错误或 public API 缺口，不扩大这些文档/诊断 PR；应另开 correctness/API issue 并关联回来。

为什么需要单独收口

当前 README 的快速开始更偏仓库贡献者路径：构建仓库、运行测试、运行 demo；而 NuGet 用户真正需要尽早知道的内容包括：

• Contracts / Server / Client 各自安装什么 package；
• Generator 如何随 package/analyzer 分发；
• 契约项目不需要为了定义 contract 引入完整 Runtime；
• 最小可运行 contract / service / call / dispose；
• 生产接入时 timeout、TLS、resource limits、graceful shutdown、logging 如何组合；
• ConnectAsync、OneWay、retry、deadline、dynamic replacement 等边界到底意味着什么；
• “连不上 / 经常超时 / pending 满”时如何一次导出足够但不泄密的诊断快照。

这些内容分散在后续章节或架构文档中会显著提高首次接入成本。

总体设计原则

1. 第一屏服务 NuGet consumer

README 首屏应优先回答：

装什么包？
契约怎么写？
Server 怎么起？
Client 怎么调？
怎么正确停？

而不是先要求 clone/build/test repository。

2. Hello World 与生产模板分开

Hello World 只展示最小成功路径。

第二份 production-shaped template 在同一份可运行配置中展示：

timeout / deadline
TLS
resource limits
logging / telemetry baseline
graceful shutdown / drain

不要让用户从十个 demo 拼生产配置，也不要把所有高级 feature 塞进第一屏。

3. 文档代码必须可执行验证

Quick Start / production template 应来自仓库中真正会被编译/运行的 canonical source。Release validation 应至少能使用本地 .nupkg 从空项目完成一次 Contracts -> Server -> Client smoke，而不是只依赖 repository ProjectReference。

4. 关键语义集中回答

Quick Start 附近必须直接回答：

5. 排障优先一次 support snapshot

不增加默认每 RPC verbose logging。优先提供按需快照，汇总：

effective non-secret config
runtime/package/protocol summary
endpoint readiness/state
connection state
negotiated protocol/compression
pending / queue usage + limits
retry/admission/breaker summary where applicable
last connection failure stage + safe classification

默认输出不得包含：

authentication credentials/tokens
private keys/certificate secret material
arbitrary metadata
request/response payload
high-cardinality business identifiers
raw application object values

Endpoint 地址、certificate identity、exception message 等灰区必须有显式 redaction policy；默认 JSON 应适合公开 issue。

Release-level 验收标准

• [docs][release] README 改为 NuGet-first Contracts → Server → Client 入门与生产模板 #573 完成：README 第一屏是 NuGet consumer path。
• 一个新用户只按 Quick Start 即可完成 Contracts -> Server -> Client 的最小调用。
• package/Generator/Contracts dependency 说明与实际 pack artifact 一致。
• 有一份独立、可运行的 production-shaped template，覆盖 timeout、TLS、resource limits、logging、graceful shutdown。
• README/sample 代码来自 CI 中会编译/运行的 canonical source，避免文档漂移。
• [docs][release] 增加调用超时、readiness、OneWay、替换与 retry 语义速查 #574 完成：Quick Start 附近有 Semantic Quick Reference。
• 自动 retry 明确限定到当前真实支持的 unary/idempotency policy，不使用“任何失败都能安全重试”式表述。
• OneWay、readiness、replacement、deadline budget 边界与实现/测试一致。
• [diagnostics][release] 提供可导出的脱敏 Client/connection support snapshot #575 完成：可以按需导出脱敏诊断 JSON。
• Snapshot 覆盖配置、endpoint/connection、negotiation、pending/queue、最后连接失败阶段。
• Redaction tests 证明认证信息、任意 metadata、payload、业务高基数值不会出现在默认 JSON。
• Snapshot 不给 per-RPC hot path 增加可测固定 allocation/锁成本。
• 与 [Runtime Architecture][Phase 18] 完成 public API/package 审计、发布门禁与迁移文档 #86 的 package/API/migration release gate 交叉核对后再关闭。

非目标

本 tracker 不直接：

• 重做 RuntimeContext / Manifest / Assembly Catalog 架构；
• 改写 retry/deadline/readiness/OneWay 的已有语义；
• 因文档方便新增 legacy compatibility API；
• 把所有高级功能塞进 Hello World；
• 为排障默认记录 payload/metadata 或开启高频 debug logging；
• 重复 [Runtime Architecture][Phase 18] 完成 public API/package 审计、发布门禁与迁移文档 #86 的 public API/package baseline 与 migration audit。

发现现有语义本身存在问题时，应单独创建 correctness/API issue；本 tracker 只负责把已确定的边界变得 可发现、可运行、可诊断。