docs: define screenshot provenance and bilingual public-site freshness gates

.github/workflows/public-site-check.yml

@@ -0,0 +1,31 @@
+name: Public site structural check
+
+on:
+  pull_request:
+    paths:
+      - "index.html"
+      - "assets/**"
+      - "README*.md"
+      - "docs/PUBLIC-PRESENTATION*.md"
+      - "scripts/check_public_surface.py"
+      - ".github/workflows/public-site-check.yml"
+  push:
+    branches: [master]
+    paths:
+      - "index.html"
+      - "assets/**"
+      - "README*.md"
+      - "docs/PUBLIC-PRESENTATION*.md"
+      - "scripts/check_public_surface.py"
+      - ".github/workflows/public-site-check.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  structural:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify local homepage structure and content entry points
+        run: python3 scripts/check_public_surface.py

README.md

@@ -112,3 +112,8 @@ Product investment and commercial categories live in [PORTFOLIO.md](PORTFOLIO.md
 Publisher accounts, deferred purchase timing, signing boundaries and every product's initial channel candidate: [distribution policy](docs/DISTRIBUTION.md) · [中文规范](docs/DISTRIBUTION.zh-CN.md). These are maintainer decisions, not a claim of Store availability or verified production signatures.
 
 Documentation languages: [English policy](docs/DOCUMENTATION-LANGUAGES.md) · [中文规范](docs/DOCUMENTATION-LANGUAGES.zh-CN.md). Portfolio: [English](PORTFOLIO.md) · [简体中文](PORTFOLIO.zh-CN.md).
+
+
+## Public presentation and screenshot freshness
+
+Our [public presentation standard](docs/PUBLIC-PRESENTATION.md) explains how to keep product pages, bilingual READMEs, user guides and release claims aligned without screenshot-only tutorials. It also defines screenshot provenance and the release-bound documentation review. [中文规范](docs/PUBLIC-PRESENTATION.zh-CN.md). Progress: [portfolio documentation issue #5](https://github.com/turinglambdaai/turinglambdaai.github.io/issues/5). This is a standard, not a claim that all sites have passed it.

README.zh-CN.md

@@ -110,3 +110,8 @@ turinglambdaai.github.io/
 发行账号、暂缓采购时机、签名边界与每个产品的初始渠道候选见[发行规范](docs/DISTRIBUTION.zh-CN.md) · [English policy](docs/DISTRIBUTION.md)。这是维护决策，不表示已经上架商店或完成生产签名验证。
 
 文档语言：[中文规范](docs/DOCUMENTATION-LANGUAGES.zh-CN.md) · [English policy](docs/DOCUMENTATION-LANGUAGES.md)。组合策略：[简体中文](PORTFOLIO.zh-CN.md) · [English](PORTFOLIO.md)。
+
+
+## 官网、文档与截图保鲜
+
+[公开展示规范](docs/PUBLIC-PRESENTATION.zh-CN.md)定义了产品主页、中英文 README、用户手册与真实发布信息的统一核对方式，避免依赖截图教程，并规定截图来源、版本和随软件更新的复查规则。[English](docs/PUBLIC-PRESENTATION.md)。进度由[全产品文档 Issue #5](https://github.com/turinglambdaai/turinglambdaai.github.io/issues/5)追踪；规范落地不代表全部站点已验收。

docs/PUBLIC-PRESENTATION.md

@@ -0,0 +1,68 @@
+# Public presentation and documentation freshness
+
+**English** · [简体中文](PUBLIC-PRESENTATION.zh-CN.md)
+
+Status: initial review and change-control standard, 2026-10-27. This complements [PRODUCT-STANDARD](PRODUCT-STANDARD.md), [HOME-PAGE-PLAN](HOME-PAGE-PLAN.md) and [DOCUMENTATION-LANGUAGES](DOCUMENTATION-LANGUAGES.md). Product repositories continue to own their own tested functionality, guides, release artifacts and normative contracts. Adopting this standard does **not** certify a product, translate every old page, or prove that a deployed page is fresh.
+
+## Presentation architecture
+
+| Surface | Primary audience and job | Authoritative information |
+| --- | --- | --- |
+| `jrtx.site` | Find the right available product, with clear preview/experimental labels | Curated catalog; each product is the authority for its own capabilities |
+| `<product>.jrtx.site` | Understand what the product solves; find a real first success, platform, privacy and download | Short, outcome-led copy backed by tagged release and user guide |
+| Product `README.md` + `README.zh-CN.md` | Evaluate and start using/building the product | Current scope, tested minimal example, compatibility, guides, license and feedback |
+| Product user guide | Finish a task, recover data, troubleshoot, upgrade safely | Reproducible text and tested commands; optional screenshots |
+| Changelog / release page | Decide whether and how to upgrade | Exact version, platform-specific artifacts, known limitations, checksums/signing and migration |
+
+Never make screenshots the primary explanation of a workflow: readers and agents need searchable instructions, copyable commands, keyboard alternatives, observable expected results and explicit failure/recovery steps. Use a task narrative (input → action → observable result) before a marketing feature list. A product's actual maturity matters more than its visual polish.
+
+## Source-of-truth and editing rules
+
+- **Single owner, many surfaces.** The product's tested source/specification and released artifacts determine actual features, supported OS/CPU, package names, first-run behavior and updater support. The user guide determines data paths and safe backup/recovery instructions. The product's signed-off current commercial terms determine any live offer. Copy only the small public summary needed by each surface; link to the owner for full details.
+- **Separate available, experimental and planned.** A roadmap, CI-green backend or simulator is not proof of a packaged GUI, hardware accuracy, a supported OS, paid checkout or future update. Do not show numeric teaser prices, unverified direct-download links, fake usage/customer quotes or claims of universal privacy.
+- **Separate source from deployment.** Search engines and caches can retain old content after the repository changes. At a content rollout, record the site repo source commit, the deployed content checked at the canonical URL, and the exact product release tag/asset. If the deployment cannot be verified, mark it *unverified*, not fixed.
+- **English and Chinese move together.** Preserve identical current claims, examples, numbers, CTA intent, platform support, limitations, privacy and purchase state across the product page and paired README/guide. Keep API identifiers/commands identical. An untranslated page is a recorded gap, not an assumed translation.
+- **Appropriate scope.** Commercial products need task + trust + install; developer libraries need runnable minimum example + precise API/compatibility references; content/archives need provenance, freshness and corrections. Do not rewrite archived/third-party forks into first-party sales pages.
+
+## Screenshot, animation and demonstration contract
+
+A screenshot is a **versioned piece of evidence**, not the design-system source or an evergreen API contract.
+
+1. **Prefer live text/HTML** for feature summaries, pricing/status, CLI examples, shortcut tables, labels and navigation. Use images for visual composition, spatial steps and real product appearance only. Mark CSS/HTML mockups as **illustrations**, never as packaged-app screenshots.
+2. **Use a real, reproducible state.** Capture from the release candidate or verified tagged build, with synthetic user data and no tokens, credentials, internal file names or private documents. Keep original capture and optional sanitized derivative.
+3. **Record image provenance** next to the asset or in a small checked-in manifest; example (not a claim of an existing asset):
+
+   ```yaml
+   file: images/launcher-search-macos-light.webp
+   product: fulcrum
+   app_version: 0.x.y
+   source_commit: <full-commit-sha>
+   build_artifact: <verified-release-or-acceptance-reference>
+   platform: macOS
+   os_version: <tested-os-version>
+   theme: light
+   state: sample-app-search
+   captured_at: YYYY-MM-DD
+   kind: real-app-screenshot   # or illustration/mockup
+   alt_en: Search results after typing a sample application name
+   alt_zh: 输入示例应用名称后的搜索结果
+   ```
+
+4. **Images are optional and limited.** One strong, real hero image plus at most a few workflow-specific images is usually enough. Use responsive dimensions, compressed WebP/AVIF or appropriately sized PNG, lazy-load below the fold, descriptive alternative text and captions identifying platform/version where relevant. Do not embed full paragraphs, command lists or prices inside images.
+5. **A UI change triggers review, not blind recapture.** On a change to layout, labels, first-run flow or platform host, flag the affected images. Compare them with the current build, either recapture, annotate as a historical version or remove them. Do not overwrite a previously tagged version's evidence with a newer UI.
+6. **Respect independent platform UIs.** Do not imply a macOS screenshot is Windows UI; when behaviors differ, say so in text and show the affected host only where needed. Accessibility, focus state and keyboard route must remain usable without the image.
+
+## A small release-bound checklist
+
+For each affected product release or public-doc PR:
+
+- [ ] Confirm exact base/source SHA, tested release tag and advertised downloadable artifacts; note unsupported targets.
+- [ ] Verify the first useful workflow from a *fresh install or clean profile*; keep copied commands and expected results in text.
+- [ ] Review canonical product site, README EN/ZH, guide EN/ZH, GitHub About and main-site card for factual drift (especially OS/CPU, updater, CLI distribution, data backup/sync, pricing and security).
+- [ ] Check images against the build and record platform/version/source/alt and any intentionally historical content.
+- [ ] Validate links, relative assets, language navigation, mobile/desktop widths, 200% zoom, keyboard focus, reduced motion and relevant alt text. A static check alone cannot validate product facts or visual appearance.
+- [ ] Compare actual deployed URL with expected source SHA, preserve rollback revision, and update the product-specific issue with evidence and unresolved gaps.
+
+## Rollout and ownership
+
+The tracked cross-portfolio implementation is [issue #5](https://github.com/turinglambdaai/turinglambdaai.github.io/issues/5). Existing [homepage issue #2](https://github.com/turinglambdaai/turinglambdaai.github.io/issues/2) retains layout/featured-story ownership. Begin with consumer/professional products; then content sites and core libraries; handle archived/upstream repositories only after provenance review. This document is a repeatable quality contract, **not** a statement that 100 repositories are already upgraded.

docs/PUBLIC-PRESENTATION.zh-CN.md

@@ -0,0 +1,49 @@
+# 公开主页、文档与截图保鲜规范
+
+[English](PUBLIC-PRESENTATION.md) · **简体中文**
+
+状态：2026-10-27 起采用的审查与变更规范。本规范补充[产品交付标准](PRODUCT-STANDARD.md)、[主页规划](HOME-PAGE-PLAN.md)和[文档语言政策](DOCUMENTATION-LANGUAGES.zh-CN.md)。产品真实能力、使用指南、发布产物和协议仍由对应产品仓库负责。采用规范**不代表**产品已验收、历史内容已全部翻译或线上部署已核实。
+
+## 各页面的职责
+
+| 入口 | 用户的任务 | 内容边界 |
+| --- | --- | --- |
+| `jrtx.site` | 快速找到匹配用途、实际可用的产品 | 产品目录及准确的预览/实验状态 |
+| `<product>.jrtx.site` | 理解能解决什么问题，找到安装、第一次成功、隐私和支持 | 以任务结果为中心的简短介绍，依据真实发布和使用手册 |
+| 产品 `README.md` / `README.zh-CN.md` | 判断是否适合、快速运行或开发 | 当前支持范围、最小可验证示例、系统要求、文档、许可证与反馈 |
+| 产品用户手册 | 完成任务、数据恢复、排障与安全升级 | 可搜索的文字和经过验证的命令，截图按需提供 |
+| 更新日志/发布页 | 判断能否以及如何升级 | 版本、系统架构、产物、限制、校验/签名和迁移事项 |
+
+**不要让截图承担主要教程职责。** 应提供可搜索的操作文字、可复制的命令、键盘替代路径、预期结果、失败和恢复方法。先讲真实任务的“输入 → 操作 → 可观察结果”，再介绍功能。产品的真实成熟度比视觉精致更重要。
+
+## 单一事实来源
+
+- **一个权威、多处摘要。** 已测试的产品代码/规格和真实发行产物决定功能、OS/CPU、安装包名称、启动流程和更新能力；使用手册解释存储、备份与恢复；当前已批准且确实开放的商业条款决定价格。其他页面只写必要摘要并链接源头。
+- **分清已交付、实验和规划。** Roadmap、通过 CI 的后端或模拟器不等于原生 GUI、硬件精度、已支持平台、开放收款或已完成更新功能。不要放未验证的直接下载地址、数字预告价格、虚构用户评价或绝对化隐私宣称。
+- **区分源码与线上部署。** 搜索缓存可能在仓库更新后仍展示旧内容。每次改站点都记录网页源码 commit、实际网址的部署核查结果和对应产品发布 tag/产物。查不到线上结果应标记“未验证”，不能声称已经修好。
+- **中英文同步。** 功能状态、示例、数值、下载意图、平台、限制、隐私和交易状态必须一致。技术标识和命令保持原样；未翻译应明确登记。
+- **按类型处理。** 商业产品重在任务/可信度/安装；基础库重在可运行最小示例/API/兼容性；内容归档重在来源、更新与勘误。不要把第三方镜像或归档仓库强行改成销售型模板。
+
+## 截图、动画和演示规范
+
+截图是**有版本范围的产品证据**，不是长期稳定的说明接口。
+
+1. 功能说明、价格与状态、CLI 示例、快捷键、导航文字尽量使用真正的 HTML/文字。只有空间布局和视觉操作才使用图片。CSS/HTML 模拟界面必须标为“示意”，不得冒充打包软件的真实截图。
+2. 从已验证的发行版本或候选构建中截取可复现状态。使用合成示例数据，删除账号密钥、私有文档和本机敏感路径，保留原图和适当处理后的版本。
+3. 在图片旁或受版本管理的 manifest 中记录：文件路径、产品名、应用版本、完整源码 SHA、可验证构建/发布依据、平台及系统版本、主题、界面状态、拍摄日期、真实截图或示意图类型，以及中英文替代文字。字段示例见[英文规范](PUBLIC-PRESENTATION.md#screenshot-animation-and-demonstration-contract)；这不是已经存在某张图片的声明。
+4. 通常一张有价值的真实首页图加少数任务细节图即可。使用尺寸合适的 WebP/AVIF 或 PNG，非首屏图片延迟加载，保留有意义的 alt，必要时标注平台/版本。不要把大段文字、命令和价格做进图片。
+5. UI 布局、标签、首启路径或系统宿主变化时，**触发截图复核，而不是无差别重截**。对照当前软件：更新、标记历史版本或删除旧图。不能用新版本截图覆盖旧版发布的证据。
+6. 各平台遵守自己的原生设计。macOS 的截图不能代表 Windows 界面；差异用文字说明，必要时补充对应平台图片。读者不依赖图片仍须能完成任务。
+
+## 随版本执行的小型检查表
+
+- [ ] 记录源码 SHA、真实发布 tag 和实际支持的下载产物；对未支持的平台直说。
+- [ ] 在干净安装或隔离配置中验证一次有用任务，把可复制命令及预期输出写成文字。
+- [ ] 核对产品站点、README 中英文、手册中英文、GitHub About 和 jrtx.site 目录卡片，尤其是平台/架构、更新、CLI 包装、数据同步与备份、价格、安全声明。
+- [ ] 核对截图与当前构建，保留版本、系统、来源、alt 及历史内容说明。
+- [ ] 检查链接/资源、中英文导航、移动端与桌面端、200% 缩放、键盘焦点、减少动效和图片替代文字；静态脚本不能证明产品功能或视觉正确。
+- [ ] 比对实际线上页面和预计部署 SHA，保留回滚版本，并在产品 Issue 中记录证据和未完成项目。
+
+## 实施跟踪
+
+全产品推进由 [Issue #5](https://github.com/turinglambdaai/turinglambdaai.github.io/issues/5) 跟踪；已有[主页 Issue #2](https://github.com/turinglambdaai/turinglambdaai.github.io/issues/2) 继续负责主站布局和产品推荐位。优先用户产品及专业工具，再到内容站点与基础库；归档/上游代码须先核对来源。**不能因为写完本规范就宣布 100 个仓库已优化。**

scripts/check_public_surface.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Dependency-free structural guard for the portfolio's static front door.
+
+This intentionally does not infer deployed freshness, visual quality,
+cross-repository promises, accessibility conformance, or release readiness.
+"""
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class Page(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.ids = set()
+        self.fragments = []
+        self.assets = []
+        self.errors = []
+
+    def handle_starttag(self, tag, attrs):
+        a = dict(attrs)
+        if "id" in a:
+            if a["id"] in self.ids:
+                self.errors.append(f"duplicate element id: {a['id']}")
+            self.ids.add(a["id"])
+        if tag == "img":
+            if not a.get("alt") and a.get("alt") != "":
+                self.errors.append(f"image missing alt attribute: {a.get('src')}")
+            if not a.get("src"):
+                self.errors.append("image missing src")
+            else:
+                self.assets.append(a["src"])
+        if tag == "a":
+            href = a.get("href", "")
+            if not href:
+                self.errors.append("anchor has no href")
+            elif href.startswith("#") and len(href) > 1:
+                self.fragments.append(href[1:])
+            else:
+                self.assets.append(href)
+        if tag in ("link", "script") and (a.get("href") or a.get("src")):
+            self.assets.append(a.get("href") or a.get("src"))
+
+
+def check():
+    problems = []
+    for rel in ("README.md", "README.zh-CN.md",
+                "docs/PUBLIC-PRESENTATION.md",
+                "docs/PUBLIC-PRESENTATION.zh-CN.md"):
+        if not (ROOT / rel).is_file():
+            problems.append(f"required entry point missing: {rel}")
+    html = (ROOT / "index.html").read_text(encoding="utf-8")
+    page = Page()
+    page.feed(html)
+    page.close()
+    problems.extend(page.errors)
+    if "<html" not in html or not page.ids:
+        problems.append("main page is missing expected semantic structure")
+    for fragment in page.fragments:
+        if unquote(fragment) not in page.ids:
+            problems.append(f"unresolved in-page fragment: #{fragment}")
+    for link in page.assets:
+        parts = urlsplit(link)
+        if parts.scheme or parts.netloc or link.startswith(("mailto:", "tel:", "data:", "/")):
+            continue  # External live URLs need separate deployment/release validation.
+        path = unquote(parts.path)
+        if not path or path.startswith("#"):
+            continue
+        target = (ROOT / path).resolve()
+        if not target.is_relative_to(ROOT) or not target.is_file():
+            problems.append(f"missing or unsafe local asset/link: {link}")
+    for file, needle in (("README.md", "PUBLIC-PRESENTATION.md"),
+                         ("README.zh-CN.md", "PUBLIC-PRESENTATION.zh-CN.md")):
+        if needle not in (ROOT / file).read_text(encoding="utf-8"):
+            problems.append(f"{file} does not link to the public presentation standard")
+    if problems:
+        for p in problems:
+            print("ERROR:", p, file=sys.stderr)
+        return 1
+    print(f"OK: {len(page.ids)} ids, {len(page.fragments)} anchors and {len(page.assets)} link/asset references inspected")
+    print("NOTE: release claims, screenshot provenance, languages and deployed bytes still need manual review")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(check())