turinglambdaai · Oct 25, 2026 · Oct 23, 2026
diff --git a/README.md b/README.md
@@ -8,6 +8,12 @@ Build first-party native desktop apps with [Racket](https://racket-lang.org/). U
 
 **English** · [中文](README.zh-CN.md)
 
+## Start here
+
+Choose Rivet when first-party native interaction is worth maintaining separate SwiftUI, WinUI 3 and GTK4 UIs. Racket owns shared domain logic; native hosts own rendering and OS interaction. For a shared HTML/CSS interface, evaluate Glaze instead.
+
+[Fit, maturity, upgrades and support](docs/USING.md) · [简体中文](docs/USING.zh-CN.md)
+
 ## Quick Start
 
 Install Rivet from the Racket Package Catalog with the `raco` from the Racket CS installation you want to embed:

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -8,6 +8,12 @@
 
 [English](README.md) · **中文**
 
+## 使用入口
+
+当第一方原生交互值得维护 SwiftUI、WinUI 3、GTK4 三份界面时，选择 Rivet。共享领域逻辑归 Racket，渲染与系统交互归原生宿主。需要共享 HTML/CSS 界面时可评估 Glaze。
+
+[使用选择、成熟度、升级与支持](docs/USING.zh-CN.md) · [English](docs/USING.md)
+
 ## 快速开始
 
 请使用你希望 Rivet 最终嵌入的那套 Racket CS 自带的 `raco`，从 Racket Package Catalog 安装：

diff --git a/docs/README.md b/docs/README.md
@@ -53,3 +53,7 @@ and operating instructions into the canonical guides above, record the release
 result in `CHANGELOG.md`, and delete the plan instead of preserving a second
 history of the same feature. Durable protocol and security rationale stays in
 its owning guide until the implementation supersedes it.
+
+## Adoption and support
+
+[English guide](USING.md) · [简体中文](USING.zh-CN.md): fit, maturity, upgrade boundaries and support. This user path links to the existing canonical technical owners above.
diff --git a/docs/USING.md b/docs/USING.md
@@ -0,0 +1,35 @@
+# Rivet adoption and support
+
+**English** · [简体中文](USING.zh-CN.md)
+
+## When to use it
+
+Choose Rivet when first-party native interaction is worth maintaining separate SwiftUI, WinUI 3 and GTK4 UIs. Racket owns shared domain logic; native hosts own rendering and OS interaction. For a shared HTML/CSS interface, evaluate Glaze instead.
+
+## Requirements and maturity
+
+Racket CS 9.0+ and the target platform’s native toolchain. Desktop delivery has explicit capability/acceptance classes; mobile runtime or companion foundations are not a generated, signed and packaged app workflow.
+
+## One useful verification
+
+Run inspect and doctor in the generated project, complete one backend mutation and observe its persisted result in the packaged native app. Keep one product interaction contract across hosts and adapt shortcuts, focus and window behavior to each OS. A unit test or screenshot alone does not establish product parity.
+
+## Reading path
+
+1. [First application](getting-started.md)
+2. [Documentation map](README.md)
+3. [API stability](api-stability.md)
+4. [Product acceptance](product-acceptance.md)
+5. [Release and updates](release-and-updates.md)
+
+Technical references retain one normative meaning. Chinese onboarding explains and links to that reference rather than creating a second protocol.
+
+## Upgrades, data and support
+
+Record the package versions and platforms your application actually tests. Read CHANGELOG and compatibility contracts before upgrading, test user-data migration on copies and retain a recoverable version. A library does not supply your product’s database backup, publisher identity, refunds, account recovery or privacy policy. Example customer/offer identifiers and amounts are fixtures, not live offers.
+
+Use [Issues](https://github.com/turinglambdaai/rivet/issues) in English or Chinese. Include package/commit, Racket version, OS/architecture, a minimal reproduction and the first redacted error. Never attach real keys, customer credentials, raw payment data or private documents. Community support has no guaranteed response time.
+
+[Private vulnerability reporting](../SECURITY.md).
+
+[Current licence](../LICENSE) · [CHANGELOG](../CHANGELOG.md)
diff --git a/docs/USING.zh-CN.md b/docs/USING.zh-CN.md
@@ -0,0 +1,35 @@
+# Rivet 使用与支持
+
+[English](USING.md) · **简体中文**
+
+## 何时使用
+
+当第一方原生交互值得维护 SwiftUI、WinUI 3、GTK4 三份界面时，选择 Rivet。共享领域逻辑归 Racket，渲染与系统交互归原生宿主。需要共享 HTML/CSS 界面时可评估 Glaze。
+
+## 要求与成熟度
+
+需要 Racket CS 9.0+ 和目标平台原生工具链。桌面交付有明确能力与验收分级；移动运行时或伴随端基础不等于已生成、签名和打包的应用工作流。
+
+## 一次有效验证
+
+在生成项目内运行 inspect 和 doctor，完成一个后端修改，并在打包原生应用中观察持久化结果。跨宿主保持一个产品交互契约，快捷键、焦点和窗口行为遵循各系统习惯。单元测试或截图本身不能证明产品一致性。
+
+## 推荐阅读路径
+
+1. [第一个应用](getting-started.zh-CN.md)
+2. [文档地图](README.md)
+3. [API 稳定性](api-stability.zh-CN.md)
+4. [产品验收](product-acceptance.md)
+5. [发行与更新](release-and-updates.md)
+
+技术规范保持一个权威版本；链接目标为英文时，它仍是对应行为的定义，不是第二份中文协议。
+
+## 升级、数据与支持
+
+固定并记录应用实际测试的包版本和平台。升级前阅读 CHANGELOG 与兼容契约，在副本上测试用户数据迁移，并保留可恢复版本。框架或库不替产品提供数据库备份、发布证书、退款、账号恢复或隐私政策。不要把示例夹具中的客户、商品和金额当成真实 offer。
+
+在 [Issues](https://github.com/turinglambdaai/rivet/issues) 反馈，中文或英文均可。包含包版本/提交、Racket 版本、系统架构、最小复现和已脱敏的首条错误。不要附带真实密钥、客户凭据、支付原始数据或私密文档。社区支持不承诺响应时限。
+
+[敏感漏洞报告流程](../SECURITY.md)。
+
+[现行许可证](../LICENSE) · [CHANGELOG](../CHANGELOG.md)
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,5 +1,7 @@
 # Getting Started with Rivet
 
+**English** · [简体中文](getting-started.zh-CN.md)
+
 This guide takes a fresh machine from “Rivet is installed” to a running native application and a distributable build. The starter project is intentionally small: a Racket backend plus native WinUI 3, SwiftUI, and GTK4 hosts.
 
 ## 1. Install Rivet
@@ -228,3 +230,5 @@ for the boundary you are changing.
 ## Troubleshooting rule of thumb
 
 Start with `raco rivet doctor`. If the toolchain is healthy but `dev`, `build`, or `package` fails, keep the first `rivet: error:` message and the native compiler output immediately around it. Rivet aims to fail at the earliest actionable boundary rather than hide native build failures behind generic errors.
+
+[Upgrades, maturity and support](USING.md).
diff --git a/docs/getting-started.zh-CN.md b/docs/getting-started.zh-CN.md
@@ -1,5 +1,7 @@
 # Rivet 快速上手
 
+[English](getting-started.md) · **简体中文**
+
 这份教程的目标很明确：从一台刚装好开发环境的电脑开始，尽快跑起第一个 Rivet 原生应用，并最终得到可以分发的构建结果。脚手架保持最小化：共享的 Racket 后端 + Windows 的 WinUI 3 宿主 + macOS 的 SwiftUI 宿主 + Linux 的 GTK4 宿主。
 
 ## 1. 安装 Rivet
@@ -226,3 +228,5 @@ raco rivet release    # 生成完整签名发布物
 ## 排查问题的第一原则
 
 先运行 `raco rivet doctor`。如果工具链正常但 `dev`、`build` 或 `package` 失败，优先保留第一条 `rivet: error:` 以及它附近的 native compiler 输出。Rivet 的目标是尽可能在最早、最可操作的边界失败，而不是把原生构建错误隐藏成模糊提示。
+
+[升级、成熟度与支持](USING.zh-CN.md)。
diff --git a/docs/index.html b/docs/index.html
@@ -19,6 +19,12 @@
             --accent-bright: #67E8F9;
         }
     </style>
+<style id="product-start-style">
+.product-start{max-width:1120px;margin:64px auto;padding:32px 24px;border-top:1px solid var(--border,#aaa);font:inherit;line-height:1.65}
+.product-start h2{font-size:clamp(1.7rem,3vw,2.4rem);letter-spacing:-.025em;margin:0 0 16px}.product-start h3{font-size:1.05rem;margin:0 0 10px}.product-start p{margin:0 0 16px;max-width:74ch}.product-start-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:28px;margin:28px 0}.product-start a{text-decoration:underline;text-underline-offset:4px;overflow-wrap:anywhere}.product-start a:focus-visible{outline:2px solid currentColor;outline-offset:5px}.product-start .start-links{display:flex;gap:16px 24px;flex-wrap:wrap}.product-start .start-status{font-weight:600}.product-start .start-limits{font-size:.95em}
+html:lang(en) .reader-zh,html:lang(zh) .reader-en{display:none!important}@media(max-width:700px){.product-start{margin:40px auto;padding:24px 20px}.product-start-grid{grid-template-columns:1fr;gap:18px}}
+</style>
+<style>.lang-menu li.lang-choice{padding:0}.lang-menu .lang-choice button{display:block;width:100%;padding:8px 12px;border:0;background:transparent;color:inherit;font:inherit;text-align:left;cursor:pointer}.lang-menu .lang-choice button:focus-visible{outline:2px solid currentColor;outline-offset:-2px;border-radius:4px}</style>
 </head>
 
 <body>
@@ -53,8 +59,8 @@
                         <span id="current-lang-label" data-en="English" data-zh="简体中文">English</span>
                     </button>
                     <ul class="lang-menu">
-                        <li onclick="setLanguage('en')">English</li>
-                        <li onclick="setLanguage('zh')">简体中文</li>
+                        <li class="lang-choice"><button type="button" onclick="setLanguage('en')">English</button></li>
+                        <li class="lang-choice"><button type="button" onclick="setLanguage('zh')">简体中文</button></li>
                     </ul>
                 </li>
             </ul>
@@ -274,7 +280,8 @@ <h2 class="section-title animate-on-scroll">
     </section>
 
     <!-- Footer -->
-    <footer>
+    <section id="adoption" class="product-start"><h2 class="reader-en " lang="en">Build one verifiable result.</h2><h2 class="reader-zh " lang="zh">先完成一个可验证的结果。</h2><p class="reader-en " lang="en">Choose Rivet when first-party native interaction is worth maintaining separate SwiftUI, WinUI 3 and GTK4 UIs. Racket owns shared domain logic; native hosts own rendering and OS interaction. For a shared HTML/CSS interface, evaluate Glaze instead.</p><p class="reader-zh " lang="zh">当第一方原生交互值得维护 SwiftUI、WinUI 3、GTK4 三份界面时，选择 Rivet。共享领域逻辑归 Racket，渲染与系统交互归原生宿主。需要共享 HTML/CSS 界面时可评估 Glaze。</p><p class="reader-en " lang="en">Racket CS 9.0+ and the target platform’s native toolchain. Desktop delivery has explicit capability/acceptance classes; mobile runtime or companion foundations are not a generated, signed and packaged app workflow.</p><p class="reader-zh " lang="zh">需要 Racket CS 9.0+ 和目标平台原生工具链。桌面交付有明确能力与验收分级；移动运行时或伴随端基础不等于已生成、签名和打包的应用工作流。</p><p class="reader-en " lang="en">Run inspect and doctor in the generated project, complete one backend mutation and observe its persisted result in the packaged native app. Keep one product interaction contract across hosts and adapt shortcuts, focus and window behavior to each OS. A unit test or screenshot alone does not establish product parity.</p><p class="reader-zh " lang="zh">在生成项目内运行 inspect 和 doctor，完成一个后端修改，并在打包原生应用中观察持久化结果。跨宿主保持一个产品交互契约，快捷键、焦点和窗口行为遵循各系统习惯。单元测试或截图本身不能证明产品一致性。</p><div class="start-links"><a class="reader-en" lang="en" href="https://github.com/turinglambdaai/rivet/blob/main/docs/USING.md">Getting started, compatibility &amp; support</a><a class="reader-zh" lang="zh" href="https://github.com/turinglambdaai/rivet/blob/main/docs/USING.zh-CN.md">入门、兼容与支持</a></div></section>
+<footer>
         <div class="footer-content">
             <div class="footer-brand">
                 <svg width="22" height="22" viewBox="0 0 512 512" fill="none">