README content contract

README content contract 是面向项目入口文档的可审查规范：README 先让目标读者理解产品、边界和下一步，再提供可复现的 Quick Start、集成 contract、交付语义、文档真相源、许可证入口、有限产品 preview，以及有来源的 Logo 和 Badge 入口。它把 README 当成产品与工程事实的入口，而不是营销素材目录、未经验证的命令抄本、状态装饰或所有文档内容的替代品（projects/oidrune.md、projects/tavily-hikari.md、projects/kaisoumail.md）。

这个 Topic 关注 README 与紧邻的 PRODUCT.md、领域上下文、Spec、Implementation、HTTP contract、ADR、quality gates 和 License 的责任分工。它不要求每个项目拥有独立 docs site，也不替代 System design docs 对系统级长期真相源的判断；若文档站本身是独立构建、预览和发布面，应另用 Project docs site（skills/style-playbook/references/topics/system-design-docs/TOPIC.md、skills/style-playbook/references/topics/project-docs-site/TOPIC.md）。

当 README 是项目的公共入口，且改动会影响产品定位、目标使用者、非目标、Logo/wordmark、Badge、安装/运行命令、跨仓库集成、交付状态、文档导航、许可证或公开资料边界时使用。下列任一信号成立即可命中：README 有双语入口或多个语言版本；包含 Logo、品牌 mark、产品 preview 或状态 Badge；提供 Quick Start 或 demo；提供 GitHub Actions、CLI、API 或 reusable workflow 示例；产品有异步 handoff、preview、公开发布或隐私投影约束；或者维护者需要审查 README 与仓库真实脚本/配置是否一致（projects/oidrune.md、projects/tavily-hikari.md、projects/kaisoumail.md、README.md、package.json）。

若仓库只有个人笔记、内部设计记录、一次性的 changelog，或改动仅是 Markdown 排版而不改变内容 contract，不应命中本 Topic；排版应使用 Markdown style。若主要问题是系统设计文档作为运行时长期真相，则使用 System design docs；若主要问题是独立文档站的构建与发布，则使用 Project docs site（skills/style-playbook/references/topics/markdown-style/TOPIC.md、skills/style-playbook/references/topics/system-design-docs/TOPIC.md、skills/style-playbook/references/topics/project-docs-site/TOPIC.md）。

• 产品优先顺序。 README 先回答产品是什么、谁使用、解决什么问题和明确不做什么，再放有限且有产品识别价值的 preview；目标用户与 non-goals 应与 PRODUCT.md 对齐。preview 不能成为产品边界的替代品（projects/oidrune.md、PRODUCT.md）。
• 双语 parity。 README.md 与本地化 README 在顶部互链，并逐项同步产品边界、Quick Start、交付语义、部署责任、文档真相源地图和 License；只翻译标题或只维护其中一种语言不算 parity。无法同步时要在风险中记录缺口（projects/oidrune.md、README.md、README.zh-CN.md）。
• 真实 Quick Start。 命令必须来自 package.json、配置文件或 checked-in scripts，写清 runtime/package manager 版本、安装命令、deterministic demo command 和 demo 的外部服务边界。公开 playbook 只保留无本机地址的命令与仓库相对证据，不复制 loopback literals、本机绝对路径或私有部署 endpoint（projects/oidrune.md、package.json、vite.demo.config.ts）。
• 安全集成示例。 GitHub Actions 示例应明确 if: always()、needs、最小 id-token: write、受信任发布对应的 full commit SHA、由依赖 job 结果推导的 outcome、完整 caller-provided summary 和成对 gateway override inputs；调用方不传 secrets:，partial pair 在 token 请求前拒绝。示例要与 reusable workflow contract 和 companion example 同步（projects/oidrune.md、docs/notify-example.md、.github/workflows/notify.yml）。
• 异步语义准确。 对 202 Accepted、queued、delivered、retry 和 dead letter 分层描述。202 可以表示 durable handoff 已完成，但不能被写成下游 Telegram、邮件或 webhook 已完成；README 应同时指出后续可观察状态及失败边界（projects/oidrune.md、docs/specs/oidrune-mvp/contracts/http.md）。
• 文档真相源地图。 README 应提供可导航的职责地图：PRODUCT.md 管产品范围、用户和 non-goals；CONTEXT.md 管领域语言；Spec 管长期行为；IMPLEMENTATION.md 管实现覆盖与 rollout；HTTP contract 管请求/响应和状态；ADR 管不可逆取舍；quality gates 管 merge/release policy；specs README 管 spec hierarchy 与各文件角色。README 可以是入口，但不应冒充这些文档的唯一真相源（projects/oidrune.md、docs/specs/README.md）。
• License 入口。 文档地图之后保留可点击、稳定的 License 链接，并指向仓库中的实际许可证文件；双语入口保持同一目标（projects/oidrune.md、LICENSE）。
• 产品定义先于 Logo 与 preview。 README 先说明产品、目标用户和 non-goals，再放 Logo、wordmark 或少量 dark/light product-identifying preview。Logo 是产品识别入口，不是产品边界、功能说明或验收证据；不得用 logo proof、海报或 social card 替代产品定义（projects/oidrune.md）。
• Logo 使用有 canonical source。 README 中的 Logo/mark 必须来自仓库声明的 canonical asset 或稳定公开 URL，提供能说明产品身份的 alt text，并保持明暗主题或语言版本的语义一致；不要复制一张临时 PNG、枚举营销素材目录或把 application icon 的平台外壳预烘焙进 README Logo。安装面需要 favicon、manifest、maskable、Apple touch 或 native bundle 时，资产角色和生成/缓存规则回到 Application icon，不能在本 Topic 复制（projects/kaisoumail.md、projects/blog-26.md、projects/codex-vibe-monitor.md、projects/tuckmark.md、skills/style-playbook/references/topics/application-icon/TOPIC.md）。
• Badge 是可验证状态入口。 每个 README Badge 都必须链接到与它完全对应的权威来源：CI Badge 指向明确 workflow 和 branch/ref，Release Badge 指向真实 Release 列表或具体 Release，语言/工具链 Badge 指向 checked-in toolchain 或维护者可复核的版本来源。Badge 只提供紧凑导航，不替代 README 的产品说明、quality gate、release contract 或真实发布证明（skills/style-playbook/references/data/projects/tavily-hikari.json、projects/oidrune.md、projects/style-playbook-skills.md）。
• Badge 保持少量、稳定和可追溯。 只保留读者会据此做决定的状态；不要使用手工填写、无对应 gate、指向错误 branch、过期 release、私有 endpoint 或无法解释语义的装饰性 Badge。自定义 shields 文案必须有 checked-in source 和维护责任；Badge 图像不可作为唯一可访问文本，链接文本/alt 应能说明它展示的状态（skills/style-playbook/references/data/projects/tavily-hikari.json、projects/oidrune.md）。
• Logo/Badge 与双语 README 同步。 英文和本地化 README 的 Logo、Badge 顺序、链接目标、alt/label 语义和产品边界必须 parity；一侧新增 Badge 或替换 Logo，另一侧不能继续指向旧 release、旧 workflow 或旧资产（projects/oidrune.md、projects/tavily-hikari.md、projects/kaisoumail.md）。
• Preview 与营销边界。 允许少量 dark/light 或等价 product-identifying preview；不要在 README 堆叠或枚举 posters、social cards、logo proof 等素材目录，也不要把营销资产事实提升为产品规则、文档真相源或 Topic 标签（projects/oidrune.md、docs/marketing/）。
• 公开文档隐私扫描。 在提交前对 snapshot、Topic、catalog、search payload、generated group Skill 和公开导出做 privacy scan；阻断 loopback literals、本机绝对路径、private source/endpoint、内部网段、credential-bearing URL 和 secret-like values。若证据只能靠本机路径表达，应改用仓库相对路径、checked-in snapshot 或公开 URL（projects/oidrune.md、docs/solutions/style-playbook/oidrune-reference-intake.md）。

• Product-first：产品、目标用户和 non-goals 位于 preview 之前，并与产品范围文档一致。
• Logo identity：Logo/wordmark 位于产品定义之后，使用 canonical source、可理解的 alt/label 和稳定链接；没有把 logo proof、social card 或 application icon 外壳当作产品说明。
• Badge provenance：每个 Badge 都有匹配的权威链接、明确的 workflow/release/toolchain 来源和 branch/ref 语义；没有 stale、装饰性或无法审计的 Badge。
• Bilingual parity：双语 README 顶部互链，产品边界、Quick Start、交付/部署语义、文档地图和 License 可逐项对照。
• Identity parity：双语 README 的 Logo、Badge、链接目标、alt/label 和顺序保持同一语义，不存在一侧过期或缺失。
• Quick Start：runtime 版本、安装命令、真实 deterministic demo command、外部服务边界和安全的公开投影均已验证。
• Actions contract：if: always()、needs、id-token: write、full SHA、outcome、完整 summary、成对 override inputs 和 no-secrets caller 均可从示例/实现交叉验证。
• Async semantics：202 的 durable handoff、下游 delivery、retry、dead letter 和最终状态没有被混写。
• Truth-source map：产品、领域、Spec、Implementation、HTTP、ADR、quality gates 和 specs hierarchy 各有职责与链接。
• License：文档地图后存在指向实际许可证文件的可点击链接。
• Preview boundary：preview 只承担产品识别，不依赖营销素材目录来解释产品或证明实现。
• Public surface：Markdown、catalog、fingerprint、topic/search index、group Skill 和 public release scan 均通过隐私检查。

• projects/oidrune.md：完整的 concrete evidence。它把产品优先双语入口、真实 Bun Quick Start、无 secrets 的 full-SHA reusable workflow、gateway pair、202 Accepted durable handoff、文档真相源地图、License 和 preview/营销边界整理成 R1–R8 contract；这些是验证本 Topic 的证据，不是把 Oidrune 的 Telegram、Cloudflare 或发布实现推广为通用规则。
• projects/tavily-hikari.md 与 skills/style-playbook/references/data/projects/tavily-hikari.json：README 顶部的 Release、CI Pipeline、Rust badges 分别链接 GitHub Releases、明确的 Actions workflow 和 rust-toolchain.toml，是 Badge provenance 的正向样本；它不证明所有项目都应复制同一组 Badge。
• projects/kaisoumail.md：scripts/generate-brand-assets.py、apps/web/public/site.webmanifest 和 apps/web/public/*.png 证明 canonical brand asset、install metadata、maskable icon 与 Apple touch icon 是相邻但不同的 contract；它用于防止把 README Logo 规则误写成 application icon 规则。
• projects/blog-26.md、projects/codex-vibe-monitor.md、projects/tuckmark.md：分别提供 manifest/install surface 已存在但 contract 完整度不同的边界证据；尤其是 Blog-26 的空 icons 数组只能记录为未收口，不能推断 Logo 或 install identity 已完成。
• docs/solutions/style-playbook/oidrune-reference-intake.md：记录从 source README、配套 workflow 和文档层级抽取 contract 的决策过程，并明确公开投影与源仓库事实的边界。

• 先放海报、social card 或 logo proof，再用几句文案解释产品，会让读者无法判断目标用户和 non-goals；修正为产品定义、用户、非目标、再 preview。
• 把 README Logo 当作 favicon、maskable icon 或 native bundle icon 的同一文件，导致平台裁切、缓存和安装面规则污染 README；修正为保留 canonical mark，但按消费面拆分 README identity 与 Application icon 资产 contract。
• 把 Badge 当成装饰性标题行，复制别的仓库的 workflow、branch 或 release URL，导致“绿色”状态与当前候选无关；修正为逐个绑定权威来源、branch/ref 和可复核的状态语义。
• Badge 只在英文 README 更新，或只替换图像不更新链接、alt 和本地化入口，导致双语读者看到不同的交付事实；修正为 Logo/Badge 的 parity check。
• 使用私有 endpoint、token-bearing URL 或内部部署 Badge 作为公开 README 证据，会把凭据边界和不可验证的部署事实泄露到公开面；修正为公开、稳定、无需凭据的状态来源，并通过 public release scan。
• 只在英文 README 更新 Quick Start 或交付语义，中文入口仍保留旧命令或旧边界，会让双语用户得到不同安全结论；修正为双语逐项 parity check。
• README 复制过期命令、私有部署 endpoint 或本机演示地址，会让外部读者无法复现或把本地环境误认为公共 contract；修正为从 checked-in scripts/config 复核命令，并在公开投影做 privacy scan。
• 示例写了 uses 却省略 full SHA、if: always()、needs、OIDC permission、完整 summary 或 gateway pair，会使通知在失败/取消场景丢失、或把 secret 责任转移给调用方；修正为 example、workflow contract 和 tests 三方校验。
• 把 202 Accepted 写成“消息已发送”，会掩盖 queue retry、dead letter 和 operator recovery；修正为明确 durable handoff 与最终 delivery 的状态机边界。
• 把 README 的文档列表当作所有文档的真相源，或遗漏 Spec、Implementation、HTTP、ADR、quality gates 和 specs hierarchy 的职责，会导致实现与决策漂移；修正为按消费者维护 truth-source map。
• 只放许可证文件而不给 README 可点击入口，或双语入口指向不同 License，会增加合规和复制成本；修正为文档地图后的稳定 License link。
• 把一个项目的 Telegram、Cloudflare、release workflow 或 preview 目录当成通用 README 规则，会让 Topic 失去迁移价值；修正为只提升结构性 contract，把项目集成留在 Reference implementation。
• 只扫描源码、不扫描生成 catalog/search/group Skill 和 public export，会让本机路径、私有 URL 或 secret-like values 从机器索引重新泄露；修正为将 public release scan 纳入 checklist 和交付 gate。

• projects/oidrune.md
• projects/tavily-hikari.md
• projects/kaisoumail.md
• projects/blog-26.md
• projects/codex-vibe-monitor.md
• projects/tuckmark.md
• docs/solutions/style-playbook/oidrune-reference-intake.md
• skills/style-playbook/references/data/projects/tavily-hikari.json
• skills/style-playbook/references/data/topics/readme-content-contract.json
• skills/style-playbook/references/data/topic-candidates.json
• README.md at https://github.com/IvanLi-CN/oidrune/tree/4b5901a8827731ea06a05211dc6edf06e46783bc
• README.zh-CN.md at https://github.com/IvanLi-CN/oidrune/tree/4b5901a8827731ea06a05211dc6edf06e46783bc
• https://github.com/IvanLi-CN/oidrune/releases/tag/v0.1.18