docs(design): OpenTUI migration design and architecture notes

[chiga0]

What this PR does

Adds the design and architecture reference document for the batched TUI migration from ink to OpenTUI, under the repo's design-doc directory. It covers the motivation with the measurements behind the decision, the dependency-direction invariant and how CI enforces it, the layering from the framework-neutral streaming model up to renderer dispatch, the seven-batch landing plan with per-batch acceptance criteria, the rollout phases with explicit gates before the default renderer flips, the verification strategy (shared PTY harness, flicker metrics, parity audits), and the tracked deferrals.

Why it's needed

The direction call on the tracking issue approved landing the migration in batches and asked for the design/architecture notes to be published in the repo — seven batches of new infrastructure deserve a reference reviewers can read up front rather than reconstruct from individual PRs. Until now those notes lived outside the repo; this makes them part of it and keeps the batch plan, gates, and deferrals in one place that evolves with the work.

Reviewer Test Plan

Docs-only change; no code paths touched.

How to verify

Read the rendered markdown (single new file under docs/design/). Cross-check points against the tracking issue #8662: batch scope table, parity gaps G-1 through G-3, the Phase-3 flip gates from the maintainer direction comment, and the acceptance criteria per landing PR. The infra batch description matches what landed on main with #10134.

Evidence (Before & After)

N/A — documentation only.

Checklist

• I have read the Contributing Guidelines
• This PR follows the repo conventions (docs placement under docs/design/, dated filename)

---

中文说明：补充 OpenTUI 迁移的设计/架构参考文档（#8662 分批落地的评审前置参考），内容全部来自跟踪 issue、维护者方向意见与已合入的基建批实现，无代码改动。

[qwen-code-ci-bot]

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

[qwen-code-ci-bot]

Thanks for the PR, @chiga0. The change itself is a straightforward docs addition, but the PR body is missing several required sections from the PR template, so it can't pass the gate yet:

• ### Tested on — the OS table under Reviewer Test Plan (N/A entries are fine for a docs-only change)
• ## Risk & Scope — main risk/tradeoff, what's out of scope, breaking changes
• ## Linked Issues — please reference the tracking issue (#8662) here; right now it's only mentioned in prose
• <details><summary>中文说明</summary> — the template asks for a complete per-paragraph Chinese translation inside the details block; the one-line summary at the bottom doesn't cover this

The design doc itself reads well and the dated docs/design/ placement follows the repo convention — this block is purely about the PR description. Once those sections are filled in, a maintainer can re-run with @qwen-code /triage.

中文说明

感谢贡献，@chiga0。改动本身只是一个纯文档新增，但 PR 描述缺少 PR 模板 中的几个必填章节，暂时无法通过门禁：

• ### Tested on —— Reviewer Test Plan 下的操作系统表格（纯文档改动填 N/A 即可）
• ## Risk & Scope —— 主要风险/取舍、未验证/超出范围的部分、破坏性变更说明
• ## Linked Issues —— 请在此关联跟踪 issue（#8662），目前只在正文里提到
• <details><summary>中文说明</summary> —— 模板要求在 details 块中提供逐段完整的中文翻译，底部的一句话摘要不符合要求

设计文档本身内容清晰，带日期的 docs/design/ 命名也符合仓库约定 —— 这里卡住的只是 PR 描述。补齐上述章节后，维护者可以用 @qwen-code /triage 重新触发评审。

— Qwen Code · qwen3.8-max

[qwen-code-ci-bot]

📄 Docs-only change — the automatic review ran at --effort medium (verified findings, no reverse audit; medium posts no inline comments). Outcome:

Review complete: pr-10343 — Comment, not posted (0 Critical, 0 Suggestion)

Reviewed head: 698edf4caf1da5402b51ee3a2983c9240df94a32. Full report in the workflow run. For a full high-effort review with inline comments, comment @qwen-code /review.

中文说明

📄 纯文档变更 —— 自动评审以 --effort medium 运行（发现已验证、无反向审计；medium 不发布行内评论），结果见上方引用行。评审的 head：698edf4caf1da5402b51ee3a2983c9240df94a32。完整报告见 workflow 运行；如需带行内评论的完整高强度（high-effort）评审，请评论 @qwen-code /review。

[yiliang114]

Reviewed the doc against the repo at 7824ef5. The references check out: #10134 merged 2026-08-28, so "landed on main" and the Related PRs table are accurate; #10146 / #9885 / #8677 (draft) / #10005 / #8662 all resolve as described; the dependency-direction section matches the gate as merged (fail-closed symlink handling, AST coverage incl. import-equals/import-type). One small accuracy nit inline on the streaming-model enumeration. The triage gate is separately held on PR-body sections (per the stage-1a comment) — worth filling those in the same pass.

updated

[yiliang114]

LGTM at 698edf4. The one finding from my earlier pass is fixed: the streaming-model enumeration now lists the actual StreamEvent members, and stats is correctly described as an output field derived by the task-end fold (with the explicit note that there is no separate stats input event). The delta since my review is exactly that 4-line doc fix; the rest was already verified — the Related PRs table and "landed on main" claims check out against the merged #10134, #10146/#9885/#8677/#10005/#8662 resolve as described, and the dependency-direction section matches the merged gate.

Note for the gate: the PR body is still missing the template sections the stage-1a triage named (Tested-on table, Risk & Scope, Linked Issues referencing #8662, and the per-paragraph Chinese details block) — worth filling those in before re-running triage.

[qwen-code-dev-bot]

Docs-only change; reviewed the full note and spot-checked its references against live state: the tracking issue #8662 is open, the infra batch #10134 is merged, #10146 (foundation modules) is under review, #10005 and #8677 exist as cited, and scripts/check-tui-dep-direction.mjs is on main — all consistent with what the document claims. CI is green incl. the secret scan, no unresolved review threads, placement/filename follow the docs/design convention. LGTM.

中文：纯文档变更，全文通读并逐一核对了文中引用的 issue/PR/脚本现状，全部吻合；CI 全绿、无未解决线程。LGTM。