[Decision] qtx 作为推荐入口与免安装试用在 README 的呈现

[Drswith]

Decision space

围绕本仓库 README.md 的呈现策略需要做三个决定：

1. 是否把 qtx 作为 README 中推荐的主入口？当前 quantex 在文案、Quick Start、命令表、Agent 表里全面占据主导，qtx 仅在文末以 footnote 出现，这与"项目实际更推荐 qtx"的倾向不一致。
2. 是否把 npx / bunx / pnpm dlx 的免安装试用作为 README 一等公民推荐路径？当前 package.json#bin 同时声明了 quantex 与 qtx，技术上 npx -p quantex-cli qtx ... 已可直接使用，但 README 仅在"Agent 快速接入"一节出现过一次类似命令，普通终端用户会误以为必须先全局安装。
3. （邻接议题，可拆出独立 ADR/issue）二进制安装在 Windows 上以 Copy-Item 复制 quantex.exe -> qtx.exe（POSIX 是 symlink）。这影响 self upgrade 时是否同步替换 qtx.exe、卸载时是否同步删除、以及 process.argv[0] 行为的一致性。

讨论上下文还包含对 README 与 Drswith/vanilla-jsx README 的对比评审，得出的可借鉴点（Features 块、可跑的 Quick Start、每个能力配示例、Contributing 独立成节、TOC）会随本决定一并落到 README 改造中，但不是本决定本身要拍板的内容。

Constraints

• 项目定位（AGENTS.md）：human-friendly + agent-friendly 的 agent lifecycle CLI，不扩张为 workflow orchestration platform。
• 既有契约：package.json#bin 两个名字 (quantex / qtx) 不能轻易移除，npm/Bun 用户当前命令习惯不能破坏。
• 现有安装通道必须继续等价支持 quantex 与 qtx：
  • npm i -g quantex-cli / bun add -g quantex-cli：包管理器 shim。
  • install.sh：qtx 是 quantex 的 symlink。
  • install.ps1：qtx.exe 是 quantex.exe 的 Copy-Item 副本。
  • npx -p quantex-cli ... / bunx quantex-cli ...：临时 shim 路径。
• 工作网关（AGENTS.md "Work Intake Gate"）：改"用户如何理解安装与命令"属于 product-facing documentation that changes how users understand installation, commands, release, or agent-facing usage，原则上要走 OpenSpec change。
• 状态与自升级保证：~/.quantex/state.json 中 self.installSource 在二进制脚本里只在 quantex 端落盘；npx 路径不写状态，需要在文档里诚实标注。
• 文档对称：任何对中文 README 的措辞调整需同步 README.en.md 与 skills/quantex-cli/SKILL.md，避免 surface 漂移。

Tradeoffs

决定 1：qtx 是否成为推荐主入口

• 方案 A：保持现状（quantex 主，qtx footnote）
  • 优点：文档可读性高（命令名表意清楚）；脚本/CI 中长名更易 grep。
  • 缺点：与项目实际推荐相违背；新用户复制走的命令永远是长名。
• 方案 B：彻底切换为 qtx 主（命令表、Quick Start、Agent 表全部改 qtx）
  • 优点：实际倾向显式化；onboarding 命令更短、体感更好。
  • 缺点：脚本类示例里 qtx 不如 quantex 自我解释；存量用户文档/笔记里仍是 quantex，认知漂移。
• 方案 C：双名共陈，qtx 优先（推荐）
  • Quick Start 与 Agent 表使用 qtx，常用命令表用 "qtx i / quantex install" 双列共陈，文档其它处段保留 quantex 增加可搜索性。
  • 在 hero 段落显式声明"推荐 qtx，等价于 quantex"。
  • 优点：兼顾扫读体感与可搜索性，最低破坏成本表达倾向。
  • 缺点：表格略宽；翻译需同步两份 README。

决定 2：免安装试用是否成为一等公民

• 方案 A：保持现状（仅 agent 集成段出现 npm exec）
  • 优点：避免读者误用 npx 路径执行写状态命令。
  • 缺点：放弃 CLI 管理器最契合的"零承诺试用"场景；quantex doctor / list / info / inspect / capabilities 这些只读命令本就适合 npx。
• 方案 B：新增"免安装试用"独立小节（推荐）
  • 范围：仅 promote 只读命令（list / info / doctor / inspect / capabilities），明确建议安装、更新、卸载等会写状态的命令仍走全局安装。
  • 同时给出 npx -p quantex-cli qtx ...、bunx quantex-cli ...、pnpm dlx quantex-cli ... 等价命令。
  • 风险点：用户用 npx 跑 install/update --all 后，下一次本地执行时 state.json 里 self.installSource 可能与实际不一致——文档需要明确标注。
• 方案 C：把所有命令都推荐 npx
  • 优点：最低门槛。
  • 缺点：与 state.json / self upgrade 设计冲突，违背 AGENTS.md 中"记住真实安装来源"的能力承诺。

决定 3（邻接）：Windows 二进制双副本的一致性

• 方案 A：保持现状（Copy-Item 复制 qtx.exe）
  • 优点：不依赖管理员权限或开发者模式。
  • 缺点：磁盘 2× 占用；self upgrade 必须显式同时替换两份；卸载文档需要列出两个文件。
• 方案 B：尝试 symlink，回退到复制
  • 优点：与 POSIX 体验对齐。
  • 缺点：Windows symlink 权限要求复杂，回退路径仍要保留复制方案，等价复杂度增加。
• 方案 C：保留复制，但要求 self upgrade 与卸载文档显式覆盖 qtx.exe（推荐方向）
  • 需要在 src/self/binary.ts 与 Windows delayed replacement 流程中确认：升级时同步替换 qtx.exe，并在 README/runbook 中列出双文件清理步骤。
  • 这条进入"observable CLI behavior / self upgrade"范畴，应单独走 OpenSpec change，不与 README 决定捆绑。

Proposed ADR title

• Adopt qtx as the recommended primary CLI entry point in user-facing documentation
• （拆分项）Promote no-install try-it-out via npx -p quantex-cli qtx ... for read-only commands
• （邻接拆分项，独立 ADR/OpenSpec）Ensure Windows binary install keeps qtx.exe consistent with quantex.exe across self upgrade and uninstall

Next step

按 AGENTS.md "Work Intake Gate"：

• 决定 1、2 拍板后，开一个 OpenSpec change 同步落地 README.md / README.en.md / skills/quantex-cli/SKILL.md。
• 决定 3 单独走 OpenSpec change（属于 self upgrade / install behavior 域），不与 README 改动合并。

[Drswith]

This decision has been promoted into durable repo-native and GitHub delivery artifacts:

• Issue Promote qtx and read-only no-install usage in product-facing docs #75 tracks the README / skill / OpenSpec documentation work
• PR docs: promote qtx README entrypoint #77 is the active implementation PR
• OpenSpec change: openspec/changes/promote-qtx-readme-surface/
• Issue Keep Windows qtx.exe consistent with quantex.exe across self-upgrade and uninstall #76 tracks the separately scoped Windows qtx.exe / quantex.exe consistency follow-up

I'm closing this discussion now that the actionable work and the split follow-up are both captured in the repository workflow.