content(embed): read-only / preview mode section and FAQ on the embed landing pages (en, zh-CN)

Roadmap direction one item 3. Also points the API reference link at the
on-site /help/embed-api page instead of the GitHub markdown.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: chaxus

docs/superpowers/plans/2026-08-15-next-phase-roadmap.md

@@ -83,8 +83,9 @@ Breadcrumb）、页脚互链全齐；robots.txt / sitemap.xml / llms.txt 三件
    修复"。在 convert/csv-to-xlsx 中文页增补一节"为什么别的工具打开中文
    CSV 会乱码、本工具如何检测编码"，FAQ 加对应问答；评估独立页
    `/fix/csv-garbled`（zh 优先，en 后补）。
-3. **只读/预览模式说明**：embed 落地页增补 runtime read-only 一节
-   （含 `document:set-readonly` 示例）；docs/embed-api.md 同步。
+3. ✅ 2026-08-16 **只读/预览模式说明**：embed 落地页（en + zh）增补
+   "Read-only and preview mode" 一节 + FAQ + FAQPage JSON-LD；docs/embed-api.md
+   本就有该节；页面里的 API 参考链接改指站内 /help/embed-api。
 4. **收尾同步**：index.html 页脚补齐缺失的 6 条内链（private、
    edit-without-account、embed、csv-to-xlsx 等）；sitemap 加新页并刷
    lastmod；llms.txt Pages 段加 /open/pdf。

public/embed-document-editor.html

@@ -120,6 +120,14 @@
                   "@type": "Answer",
                   "text": "Add embedOrigin to the iframe URL to lock messaging to a specific origin, and verify event.origin in your own message handler."
                 }
+              },
+              {
+                "@type": "Question",
+                "name": "Can I show a document read-only, or lock it after a while?",
+                "acceptedAnswer": {
+                  "@type": "Answer",
+                  "text": "Yes. Pass readonly: true when opening, or send document:set-readonly at any time. It switches the live editor without reloading, and saves are refused while locked."
+                }
               }
             ]
           },
@@ -258,13 +266,23 @@ <h2>How it works</h2>
         </li>
       </ol>
 
+      <h2>Read-only and preview mode</h2>
+      <p>
+        Open a document read-only (a viewer, a review step, a locked record) by passing <code>readonly: true</code> with
+        the open command, and switch at any time with <code>document:set-readonly</code> — no reload, the document stays
+        where the user was. In read-only mode editing is disabled and <code>document:save</code> answers with
+        <code>document:error</code>; <code>document:get-state</code> reports the current <code>readonly</code> flag.
+      </p>
+      <pre><code>// open locked, unlock later
+send('document:open-url', { url, readonly: true });
+send('document:set-readonly', { readonly: false });</code></pre>
+
       <r-card class="oss"
         ><div class="card-body">
           <strong>Open source &amp; self-hostable.</strong> Under AGPL-3.0 — read the code, run your own copy, and see
           exactly how the boundary works:
           <a href="https://github.com/ranuts/document" rel="noopener">github.com/ranuts/document</a>. Full API
-          reference:
-          <a href="https://github.com/ranuts/document/blob/main/docs/embed-api.md" rel="noopener">docs/embed-api.md</a>.
+          reference: <a href="/help/embed-api">Embed API reference</a>.
         </div></r-card
       >
 
@@ -295,6 +313,11 @@ <h3>How do I restrict which site can talk to the editor?</h3>
           Add <code>embedOrigin</code> to the iframe URL to lock messaging to a specific origin, and verify
           <code>event.origin</code> in your own message handler.
         </p>
+        <h3>Can I show a document read-only, or lock it after a while?</h3>
+        <p>
+          Yes. Pass <code>readonly: true</code> when opening, or send <code>document:set-readonly</code> at any time —
+          it switches the live editor without reloading, and saves are refused while locked.
+        </p>
       </div>
 
       <footer>

public/zh-CN/embed-document-editor.html

@@ -120,6 +120,14 @@
                   "@type": "Answer",
                   "text": "在 iframe URL 上加 embedOrigin 把消息锁定到指定 origin，并在你自己的消息处理里校验 event.origin。"
                 }
+              },
+              {
+                "@type": "Question",
+                "name": "能只读展示文档，或者过一会儿再锁定吗？",
+                "acceptedAnswer": {
+                  "@type": "Answer",
+                  "text": "能。打开时传 readonly: true，或随时发送 document:set-readonly。它直接切换正在运行的编辑器、不重新加载，锁定期间保存会被拒绝。"
+                }
               }
             ]
           },
@@ -251,13 +259,23 @@ <h2>工作原理</h2>
         </li>
       </ol>
 
+      <h2>只读与预览模式</h2>
+      <p>
+        需要"只看不改"（预览器、审阅环节、已归档记录）时，在打开命令里传
+        <code>readonly: true</code>；随时可以用 <code>document:set-readonly</code>
+        切换——不重新加载，文档停在用户原来的位置。只读期间禁止编辑，
+        <code>document:save</code> 返回 <code>document:error</code>；<code>document:get-state</code> 会报告当前的
+        <code>readonly</code> 状态。
+      </p>
+      <pre><code>// 锁定打开，稍后解锁
+send('document:open-url', { url, readonly: true });
+send('document:set-readonly', { readonly: false });</code></pre>
+
       <r-card class="oss"
         ><div class="card-body">
           <strong>开源且可自托管。</strong> 基于 AGPL-3.0——读源码、自托管一份、看清边界是怎么设计的：
           <a href="https://github.com/ranuts/document" rel="noopener">github.com/ranuts/document</a>。完整 API 参考：
-          <a href="https://github.com/ranuts/document/blob/main/docs/embed-api.zh.md" rel="noopener"
-            >docs/embed-api.zh.md</a
-          >。
+          <a href="/zh-CN/help/embed-api">Embed API 参考</a>。
         </div></r-card
       >
 
@@ -285,6 +303,11 @@ <h3>怎么限制哪个站点能和编辑器通信？</h3>
           在 iframe URL 上加 <code>embedOrigin</code> 把消息锁定到指定 origin，并在你自己的消息处理里校验
           <code>event.origin</code>。
         </p>
+        <h3>能只读展示文档，或者过一会儿再锁定吗？</h3>
+        <p>
+          能。打开时传 <code>readonly: true</code>，或随时发送
+          <code>document:set-readonly</code>——它直接切换正在运行的编辑器、不重新加载，锁定期间保存会被拒绝。
+        </p>
       </div>
 
       <footer>