Merge branch 'wt/v0.2.0'

Author: ztwzeroo

.github/workflows/ci.yml

@@ -22,6 +22,8 @@ jobs:
         run: pip install -e '.[dev]'
       - name: Test
         run: python -m pytest -v
+      - name: Upstream check selftest
+        run: python scripts/upstream_check.py --selftest
       - name: Review repro audit (all issues must stay fixed)
         shell: bash
         run: python docs/reviews/2026-09-20-repro.py

.github/workflows/release.yml

@@ -71,6 +71,8 @@ jobs:
           "$BIN" install "$SGAME" --kit-dir "$SMK" --arch sm86 --mfg 4x
           test -f "$SGAME/dlssg_sm86.ini" && test -f "$SGAME/version.dll"
           "$BIN" doctor "$SGAME"
+          "$BIN" report "$SGAME"
+          "$BIN" --check-update
           "$BIN" uninstall "$SGAME"
           test ! -e "$SGAME/version.dll" && test ! -e "$SGAME/dlssg_sm86.ini"
           test -f "$SGAME/game.exe"

.github/workflows/upstream-check.yml

@@ -0,0 +1,49 @@
+name: upstream-check
+
+on:
+  schedule:
+    - cron: "17 6 * * *"
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths: ["scripts/upstream_check.py", ".github/workflows/upstream-check.yml"]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Upstream structure smoke
+        id: smoke
+        run: |
+          set +e
+          set -o pipefail
+          python scripts/upstream_check.py | tee upstream-check.log
+          code=$?
+          echo "exit=$code" >> "$GITHUB_OUTPUT"
+          exit $code
+      - name: Manage drift issue
+        if: always()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          EXIT_CODE: ${{ steps.smoke.outputs.exit }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          gh label create upstream-check --color d73a4a --force || true
+          LABEL="upstream-check"
+          TITLE="[upstream-check] upstream structure drift"
+          ISSUE=$(gh issue list --label "$LABEL" --state open --json number --jq '.[0].number')
+          if [ "$EXIT_CODE" != "0" ]; then
+            BODY="Daily upstream smoke failed. Details and run: $RUN_URL"$'\n'$'\n'"$(cat upstream-check.log)"
+            if [ -n "$ISSUE" ]; then gh issue comment "$ISSUE" --body "$BODY"
+            else gh issue create --title "$TITLE" --label "$LABEL" --body "$BODY"; fi
+          elif [ -n "$ISSUE" ]; then
+            gh issue close "$ISSUE" --comment "Upstream smoke green again: $RUN_URL"
+          fi

.gitignore

@@ -7,3 +7,4 @@ __pycache__/
 build/
 dist/
 .worktrees/
+.superpowers/

CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to this project are documented here. The format follows
 [SemVer](https://semver.org/) with a `0.x` experimental prefix. Evidence links
 point to files in this repository (`docs/`) so the trail is auditable offline.
 
+## [0.2.0] — 2026-09-29
+
+### Added
+
+- Daily upstream-structure watch: the scheduled `upstream-check` workflow
+  verifies the upstream shape this toolkit depends on (dlssg_for_sm86 main
+  commit resolves, kit files still exist at that commit, generated INI keys
+  stay accepted, DLSS5-Swapper still publishes a selectable portable asset)
+  and opens/updates an auto-labeled issue on drift, closing it when green
+  again. Evidence: `.github/workflows/upstream-check.yml`,
+  `scripts/upstream_check.py`, selftest `tests/test_upstream_check.py`.
+- `report` command: prints a paste-ready, offline, read-only game-test
+  report (GPU landscape with the selected card, manifest summary, routing
+  verdict, and an explicit "does NOT contain" section) for the game-test
+  issue template. Evidence: `src/dlss_combo/report.py`, `tests/test_report.py`.
+- `--check-update`: non-blocking check for a newer dlss-combo release before
+  any command — prints one line and continues; network failures degrade to a
+  skip notice. Evidence: `src/dlss_combo/update.py`, `tests/test_update.py`.
+- Multi-GPU enumeration: all NVIDIA cards are parsed and the **first card
+  with a supported architecture (RTX 20/30)** is selected; `doctor` lists
+  multi-card rigs and names the primary. `--arch` still overrides.
+  Evidence: `src/dlss_combo/gpu.py`, `tests/test_gpu_multi.py`.
+- Recommended test-games list for RTX 20/30 testers, with native-FG
+  evidence links and a verify-in-game disclaimer. Evidence:
+  `docs/TEST-GAMES.md`.
+
+### Changed
+
+- **CLI is now English-only** — help text, diagnostics and error messages.
+  Internal source comments are unchanged. Guarded by
+  `tests/test_english_cli.py` (CJK scan over user-facing strings).
+- Doctor session diagnostics hardened (see Fixed).
+
+### Fixed
+
+- Unreadable route logs are reported as problems instead of crashing
+  `doctor`; the session verdict is now the **last route event of the newest
+  log** (a later failure is never hidden by an earlier success), and
+  image-layer files count as evidence only, never as layer activation.
+  Evidence: `tests/test_doctor_last_event.py`.
+- Manifest schema/path validation error messages are now English — translated
+  wording only, failure behavior is unchanged — and a bare invocation prints
+  usage again (guarded in `tests/test_english_cli.py`).
+- Proxy fallback order regression-locked to the upstream tool-class order
+  (`version → winmm → dbghelp → dinput8` before `d3d12`/`dxgi`).
+  Evidence: `tests/test_proxy_order.py`.
+
 ## [0.1.3] — 2026-09-20
 
 ### Fixed
@@ -132,6 +179,7 @@ The nine reproduced problem behaviors are pinned by
 `docs/reviews/2026-09-20-repro.py` (all report fixed) and migrated into
 regression tests (`tests/test_review2.py`).
 
+[0.2.0]: https://github.com/ztwzeroo/DLSS5-FrameGen/releases/tag/v0.2.0
 [0.1.3]: https://github.com/ztwzeroo/DLSS5-FrameGen/releases/tag/v0.1.3
 [0.1.2]: https://github.com/ztwzeroo/DLSS5-FrameGen/releases/tag/v0.1.2
 [0.1.1]: https://github.com/ztwzeroo/DLSS5-FrameGen/releases/tag/v0.1.1

README.md

@@ -14,10 +14,11 @@
 [![Target: Windows](https://img.shields.io/badge/target-Windows_10%2F11-334234?style=flat-square)](#will-it-work-with-my-setup)
 [![GPU: RTX 20 / 30](https://img.shields.io/badge/GPU-RTX_20_%2F_30-5b713b?style=flat-square)](#will-it-work-with-my-setup)
 [![License: MIT](https://img.shields.io/badge/license-MIT-334234?style=flat-square)](LICENSE)
+[![upstream-check](https://github.com/ztwzeroo/DLSS5-FrameGen/actions/workflows/upstream-check.yml/badge.svg)](https://github.com/ztwzeroo/DLSS5-FrameGen/actions/workflows/upstream-check.yml)
 
 > **Developer preview.** Best suited to contributors and experienced modders using disposable test copies. The file-safety, rollback and checksum issues from the [2026-09-20 review](docs/reviews/2026-09-20-project-review.md) are fixed and pinned by regression tests (the review's repro script now reports all nine behaviors fixed). No verified in-game benchmarks yet. **Read the [current limitations](docs/STATUS.md) before installing.**
 
-**Have an RTX 20/30 and a single-player D3D12 game with native frame-generation support?** We are looking for early testers. [Download the Windows developer preview](../../releases/latest), try it on a backed-up test copy, and [share a success or failure report](https://github.com/ztwzeroo/DLSS5-FrameGen/issues/new?template=game-test.yml). We have not yet verified the combined setup in a real Windows game; your report helps establish which configurations actually work.
+**Have an RTX 20/30 and a single-player D3D12 game with native frame-generation support?** We are looking for early testers. See the [recommended test games](docs/TEST-GAMES.md), [download the Windows developer preview](../../releases/latest), try it on a backed-up test copy, and [share a success or failure report](https://github.com/ztwzeroo/DLSS5-FrameGen/issues/new?template=game-test.yml). We have not yet verified the combined setup in a real Windows game; your report helps establish which configurations actually work.
 
 <p>
   <a href="../../releases"><img src="https://img.shields.io/badge/Download-Releases_(exe_/_linux)-d3ff6a?style=for-the-badge&amp;labelColor=263021" alt="Download from Releases"></a>
@@ -55,6 +56,10 @@ flowchart LR
 
 *Setup workflow only. This diagram is not a gameplay demonstration or performance result.*
 
+<p align="center"><img src="assets/demo.svg" alt="dlss-combo workflow demo" width="640"></p>
+
+*Animated CLI walkthrough: `fetch` → `install` → `doctor` → `report`. Illustrative output, not measured game results.*
+
 ## Will it work with my setup?
 
 These are the **target requirements**, not a verified compatibility list.
@@ -70,6 +75,8 @@ These are the **target requirements**, not a verified compatibility list.
 
 RTX 40/50, Vulkan games and games without native frame-generation support are outside this project's current target. Other mods may conflict. **Do not use this with anti-cheat or competitive multiplayer games.**
 
+**Multiple NVIDIA GPUs:** when several cards are present, the tool picks the **first card with a supported architecture** (RTX 20/30) and `doctor` lists every card in the rig so you can confirm which one was selected; `install DIR --arch sm75|sm86` overrides the choice. Looking for a suitable game? See [Recommended test games](docs/TEST-GAMES.md).
+
 ## Get started
 
 Use an independently backed-up or disposable game copy. Uninstall validates its manifest, skips externally modified files and restores pre-existing user configs — but no restore is a substitute for a backup. See the [known issues](docs/STATUS.md#known-issues).
@@ -92,6 +99,8 @@ py -m dlss_combo fetch
 
 Prefer Git? Clone `https://github.com/ztwzeroo/DLSS5-FrameGen.git`, open that folder, and run the same commands. The Python package and CLI retain the original names `dlss_combo` and `dlss-combo`.
 
+Add `--check-update` to any command (for example `py -m dlss_combo --check-update doctor DIR`) for a non-blocking check that a newer dlss-combo release exists — it prints one line and never interrupts the run, and it is skipped silently when offline.
+
 ### 2. Configure the image layer
 
 Open the downloaded **DLSS5-Swapper portable EXE** in `~/dlss-combo-kit/swapper/`. Use its interface and upstream instructions to configure your **test copy** of the game. If the asset is a ZIP, follow the upstream extraction instructions first.
@@ -114,7 +123,11 @@ Enable frame generation in the game's graphics settings if available. After a te
 py -m dlss_combo doctor "C:/Games/TestCopy/Binaries/Win64"
 ```
 
-A successful file installation or detected ReShade folder does **not** prove either rendering layer is active. Diagnostics have known limitations; [report your observed result](https://github.com/ztwzeroo/DLSS5-FrameGen/issues/new?template=game-test.yml), including failures.
+A successful file installation or detected ReShade folder does **not** prove either rendering layer is active. Diagnostics have known limitations; [report your observed result](https://github.com/ztwzeroo/DLSS5-FrameGen/issues/new?template=game-test.yml), including failures. To make that easy, `report` generates a paste-ready offline game-test report:
+
+```powershell
+py -m dlss_combo report "C:/Games/TestCopy/Binaries/Win64"
+```
 
 <details>
 <summary><strong>More commands and tuning options</strong></summary>
@@ -131,6 +144,8 @@ Use `py -m dlss_combo --help` or `py -m dlss_combo install --help` for the full
 | `install DIR --arch sm86` | Override the GPU-architecture check; driver checks still run. |
 | `install DIR --proxy winmm.dll` | Pin a specific proxy DLL name (default order follows the upstream tool-class proxies first). |
 | `install DIR --launch-swapper` | Launch the downloaded DLSS5-Swapper portable after installing (checksum-verified). |
+| `report DIR` | Print a paste-ready markdown game-test report (offline, read-only). Add `--out FILE` to save it. |
+| `--check-update` (before any command) | Non-blocking check for a newer dlss-combo release; skipped when offline. |
 | `uninstall DIR` | Remove managed files. Read the file-safety and restoration issues first. |
 
 6X requires a compatible 310.9 build **and** game. Setting 6X with 310.1 does not make that runtime support it. Some optimization tiers are also runtime-dependent. Consult the [upstream INI](https://github.com/sdli1995/dlssg_for_sm86/blob/main/dlssg_sm86.ini) for meanings and constraints.
@@ -162,7 +177,7 @@ WINEDLLOVERRIDES="version=n,b" PROTON_ENABLE_NVAPI=1 PROTON_NVIDIA_NVCUDA=1 %com
 
 | Evidence | Current state |
 |---|---|
-| Offline Python tests | 122 passing at v0.1.3; CI runs the suite on Windows/Linux/macOS on every push |
+| Offline Python tests | 155 passing at v0.2.0; CI runs the suite on Windows/Linux/macOS on every push |
 | Review regression | The 2026-09-20 repro script reports all nine fixed behaviors |
 | Release binaries | Windows EXE + Linux x64 built by GitHub Actions from each tagged commit |
 | Windows game sessions | Not yet validated by this project |
@@ -197,9 +212,9 @@ There are no verified performance results for this combined toolkit yet. GPU, ga
 </details>
 
 <details>
-<summary><strong>Why are some command-line messages in Chinese?</strong></summary>
+<summary><strong>What language is the CLI output in?</strong></summary>
 
-The English documentation covers setup, but the CLI currently includes Chinese messages. English CLI output is on the roadmap. Include the original output when reporting a problem.
+Since v0.2.0 the CLI is English-only — help text, diagnostics and errors (internal source comments remain Chinese). If you see output from an older release that mixes languages, include the original output when reporting a problem, or update to the latest release.
 
 </details>
 
@@ -214,8 +229,8 @@ We will add them when reproducible Windows/NVIDIA tests are available. The banne
 
 - [x] Add regression protection for externally modified files and original configuration recovery.
 - [x] Re-verify cached files and keep the previous kit usable if refresh fails.
+- [x] Make the CLI English-only (help, diagnostics, errors), guarded by a regression test.
 - [ ] Add an installation preview and improve per-session diagnostics with real game evidence.
-- [ ] Add English CLI messages and clearer error guidance.
 - [ ] Validate Windows behavior and publish reproducible RTX 20/30 game results.
 
 See the [English status and known issues](docs/STATUS.md), [detailed audit (Chinese)](docs/reviews/2026-09-20-project-review.md), and [contributor guide](CONTRIBUTING.md).

README.zh-CN.md

@@ -14,6 +14,7 @@
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
 [![Target: Windows](https://img.shields.io/badge/target-Windows-0078D6)](#requirements--运行条件)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![upstream-check](https://github.com/ztwzeroo/DLSS5-FrameGen/actions/workflows/upstream-check.yml/badge.svg)](https://github.com/ztwzeroo/DLSS5-FrameGen/actions/workflows/upstream-check.yml)
 
 **下载 / Download**: [Releases](https://github.com/ztwzeroo/DLSS5-FrameGen/releases) 提供
 Windows EXE 与 Linux x64 二进制（GitHub Actions 从打 tag 的提交构建，未签名），
@@ -73,11 +74,14 @@ Target environment: **Windows 10/11 x64, RTX 20 or RTX 30**, and a D3D12 game wi
 **Single-player testing only. Do not use with anti-cheat or competitive multiplayer games.**
 **仅限单机测试，不要用于带反作弊的游戏或竞技多人游戏。**
 
+**Multiple NVIDIA GPUs / 多张 NVIDIA 显卡：** with several cards present, the tool picks the **first card with a supported architecture** (RTX 20/30) and `doctor` lists every card so you can confirm the selection; `install DIR --arch sm75|sm86` overrides the choice. 不知选哪款游戏？See [Recommended test games / 推荐测试游戏](docs/TEST-GAMES.md)（英文 / English）.
+多卡环境下，工具自动选择**第一张受支持架构**（RTX 20/30）的显卡，`doctor` 会列出全部显卡供确认；可用 `install DIR --arch` 覆盖。
+
 ## Getting started / 开始使用
 
-The commands below are for experimental testing. Read the known issues and keep an independent backup before writing to any game directory.
+The commands below are for experimental testing. Read the known issues and keep an independent backup before writing to any game directory. Not sure which game to start with? See [Recommended test games / 推荐测试游戏](docs/TEST-GAMES.md)（英文 / English）.
 
-以下命令供实验测试使用。向游戏目录写入前，请先阅读已知问题并保留独立备份。
+以下命令供实验测试使用。向游戏目录写入前，请先阅读已知问题并保留独立备份。不知从哪款游戏开始？参考[推荐测试游戏列表](docs/TEST-GAMES.md)（英文）。
 
 ```powershell
 git clone https://github.com/ztwzeroo/DLSS5-FrameGen.git
@@ -96,8 +100,16 @@ dlss-combo install "C:/Games/TestCopy/Binaries/Win64" --mfg 4x
 
 # After playing, inspect logs / 运行游戏后读取诊断
 dlss-combo doctor "C:/Games/TestCopy/Binaries/Win64"
+
+# Generate a paste-ready game-test report / 生成可直接粘贴的测试报告
+dlss-combo report "C:/Games/TestCopy/Binaries/Win64"
 ```
 
+<p align="center"><img src="assets/demo.svg" alt="dlss-combo workflow demo" width="640"></p>
+
+*Animated walkthrough: `fetch` → `install` → `doctor` → `report` — illustrative output, not measured results.*
+*动画演示：下载 → 安装 → 诊断 → 报告（示意输出，非实测结果）。*
+
 The command remains **`dlss-combo`**; the public project name is **DLSS5-FrameGen**. Use `py -m dlss_combo` after installation if the command is not on your PATH.
 
 公开项目名为 **DLSS5-FrameGen**，现有命令保持 **`dlss-combo`**。如果找不到命令，安装后可使用 `py -m dlss_combo`。
@@ -106,15 +118,19 @@ The command remains **`dlss-combo`**; the public project name is **DLSS5-FrameGe
 |---|---|
 | `fetch [--runtime 310.9\|310.1] [--kit-dir DIR] [--refresh]` | Download components; default cache is `~/dlss-combo-kit` / 下载组件 |
 | `install DIR [--mfg 2x\|3x\|4x\|6x] [--tier 0-3] [--runtime 310.9\|310.1] [--kit-dir DIR]` | Install the frame-generation layer / 安装插帧层 |
-| `install DIR --arch sm75\|sm86` | Override GPU detection; currently also bypasses driver detection / 覆盖 GPU 探测，当前也会跳过驱动探测 |
+| `install DIR --arch sm75\|sm86` | Override GPU-architecture detection; driver version checks still run / 覆盖 GPU 架构探测；驱动版本检查仍会执行 |
 | `install DIR --launch-swapper` | Open the cached Swapper asset; launch validation improvements are pending / 打开缓存的 Swapper，启动校验待完善 |
 | `doctor DIR` | Inspect files and available logs / 读取文件与日志状态 |
+| `report DIR [--out FILE]` | Print a paste-ready offline game-test report / 生成可直接粘贴的游戏测试报告（离线、只读） |
+| `--check-update`（加在任意命令前 / prepend to any command） | Non-blocking newer-release check, skipped silently when offline / 非阻塞检查新版本，离线自动跳过 |
 | `uninstall DIR` | Remove managed files; restoration limitations remain / 卸载本工具文件，还原能力存在已知限制 |
 
 ReShade, RenoDX or Feeder file markers alone do not prove DLSS 5 is active. Coexistence with other mods depends on the game and installation route. Measure the base frame rate before raising the frame-generation multiplier.
 
 检测到 ReShade、RenoDX 或 Feeder 文件不代表 DLSS 5 已生效。与其他 mod 是否兼容取决于具体游戏和安装路线；提高插帧倍数前，请先测不插帧时的基础帧率。
 
+`--check-update` 可加在任意命令前（如 `dlss-combo --check-update doctor DIR`），非阻塞检查是否有新版本，只打印一行、离线自动跳过。/ Prepend `--check-update` to any command for a non-blocking newer-release check — it prints one line and is skipped silently when offline.
+
 ## Roadmap / 改善路线
 
 - [ ] Safe file ownership, bounded uninstall paths and original configuration restoration / 文件归属、卸载范围和原始配置还原。