docs(readme): lead the first screen with the Agent team, decisions and evidence

[huangruiteng]

Goal

The README first screen should show what is distinctive about LoopX, which the previous board screenshot did not.

Change

• The first screen leads with an Agent team instead of a task board: delegated members with their states, an owner decision made in place in the conversation, and an accepted result with its evidence. The live Codex turn appears only as context. Steering is not a headline capability.
• English and Chinese variants: docs/assets/personal-workspace/workspace-hero.webp and workspace-hero.zh-CN.webp, about 115 KB and 99 KB at 1920 px, with transparent rounded corners for both GitHub themes. They replace workspace-1.0.webp; no remaining file references it.
• The image moves above the fold, directly under the navigation line. The duplicate image block in the Workspace section is removed.
• A two-step Codex App start sits under the hero in both languages. Install once with python3 -m pip install --upgrade loopx && loopx workflow-skills --install, restart Codex App, then type $loopx <task> in a project thread. One line says what the guided start does (connects the project, plans Todos, sets up the heartbeat), names Claude Code's /loopx <task>, and links to the existing table of other Agent hosts. The example task comes from the newcomer guide. This part does not depend on the other PRs.
• "Try LoopX" is reduced to one install line and a three-host quick table: $loopx <complex task> for Codex App and Codex CLI, /loopx <complex task> for Claude Code, and the loopx skill for DeepSeek Harness. The guided start already connects the project, plans the work and sets up the loop, so the manual connect, status and start-goal --guided steps and the success checklist are gone from the main path. The full host table (still including the Kiro /goal row), the custom-runner tick and the contributor clone are kept in a collapsed section. Windows, pipx, upgrade and uninstall detail now lives only in Installing LoopX. On a desktop render the section shrinks from about 3,380 px to about 660 px.
• A reproducible recipe lives in demo/workspace/readme-hero/: render.mjs plus the hero.html template, documented in demo/workspace/README.md. Intermediate frames stay in ignored output/playwright/.

Honest-capture boundary

Goals, Todos and owner decisions are real Workspace-stories demo state, served by the real backend. The demo starts no Agent, so the Codex conversation and the team delegation records are simulated through browser route mocks. The README caption says so in both languages: "Agent turns and team records are simulated" and "Agent 对话与团队记录为模拟数据". The member-state tag says "at a glance", not "observed", for the same reason.

Dependency

The captured UI includes the inline decision card from #5415, the team execution view from #5420, and the "This machine" source label from #5421. Merge this PR after those three, so the README never shows UI that main does not ship.

Validation

• The README-reading checks (36 smokes plus the documentation pytest files) give the same results before and after this change. The two failures predate it and are unrelated: core-control-plane-diagrams-smoke (a heading missing from state-definitions.md) and codex-cli-no-clone-release-verification-smoke (temp-directory cleanup). codex-cli-tui-bootstrap-smoke-bundle-smoke once failed in the same temp-directory cleanup step with every assertion passed, then passed on three straight reruns.
• examples/public_entry/readme-demo-surface-smoke.py passes; it now checks both hero assets.
• render.mjs was run with the documented command against a demo server built from main plus feat(app): decide User gates in the drawer with one confirmation #5415, feat(app): show team execution as a pulse strip and member cards #5420 and fix(workspace): localize the local source and status-only route labels #5421. Its output matches the owner-approved preview to within anti-aliasing (0.2–0.5% of pixels differ).
• The first-screen preview was reviewed by the owner before commit: GitHub-rendered light, dark, mobile and Chinese views.
• Boundary scan: no local paths, private context or credentials in the changed files.

Future-facing refactor pass: none needed. The recipe is a self-contained demo script with no product code touched.

[huangruiteng]

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

Exact head: 02b26b0099c4db1da0b6cb3c2a261036eaf8fa5c; immutable baseline: 8fdc1616fc84ef158775e322cf3660cfe18a5be0. Independent whole-PR review of all nine changed files. The later README simplification is included; the superseded 23e0acdef head is not the publication target.

[P2] 复现流程缺少创建决策预览的步骤，成功生成的 hero 会丢失批准卡片。 capture 的截图步骤 只滚动对话并截图。用全新 demo 目录运行文档命令，中英文都成功退出，但没有提交图片里的“待你确认 / 确认批准”卡片；决策标注下方是空白。即使本地集成 #5415、#5420、#5421 的指定 heads，结果仍相同，真实 /api/actions?goal_id=community-day 返回空 proposals。仅在隔离 demo 中通过既有 gate.resolve 创建预览后，同一脚本才显示卡片：英文和中文各一个确认入口，未执行 apply，场地 gate 仍开放、依赖任务仍受阻。请把这个前置步骤纳入复现流程，并在截图前断言真实待确认卡片已出现；不要依赖作者机器上已有的预览记录。

动机

普通新读者需要先理解 LoopX 如何把团队责任、用户决策和验收证据连接起来，再从自己的 Agent 开始工作。基线首段主要介绍控制面和结果，工作区图在后文；当前版本把三种能力放到导航之后，并把重复的手动连接流程压缩为安装加宿主入口。这是有价值的文档改进。不过“可复现的首屏呈现”尚未完整成立：新目录生成的图少了关键决策入口，因此本轮不能认定这个交付切片已经完成。

改动思路

README 消费静态中英文资产；渲染脚本先从真实 Chat 后端读取隔离的 Workspace stories，再用浏览器 route mocks 补充对话和委派记录，最后由本地 HTML 模板排版。Goal、Todo 和决策状态继续归既有 backend，模板没有生产状态或授权权力。两种语言的说明明确承认 Agent 对话和团队记录为模拟数据，这个边界应保留，不能把页面里的 accepted 标签当成真实 Agent 验收凭据。

安装说明复用 newcomer guide、workflow-skills 和现有宿主接入文档，没有新增安装器或控制面决策源。新版本的 Try LoopX 保留完整宿主表、Kiro、runner 与源码贡献入口，但折叠了高级路径，并继续链接 Windows、升级和卸载说明。DSH 的原生插件前提仍在展开表中；建议让快捷表的 DSH 行也直接链接它，避免新读者把通用 CLI 安装当成原生 Driver 安装。

具体改动

本次共九个文件、426 行新增和 128 行删除：两个 README 调整首段图片、两步启动和安装阅读路径，demo 文档补充渲染命令，新增 HTML 模板与渲染脚本，替换三个图片文件，并更新已有 README smoke。没有更改产品运行代码、CLI 参数、安装器、持久格式、Lark 或配额调度；这些入口无需产品 companion 变更。当前安装表的语义需按已有宿主接入前提理解，文档精简没有创建任何新的执行权限。

关键内容讲解

1. capture：使用既有 demo 的真实 Goal/Todo，模拟 session、SSE 和四条团队记录。它依次截取成果、对话与成员卡，未启动 Agent。当前遗漏的是真实 typed-action 预览，而非更多模拟对话；应复用现有预览 owner，让新目录也得到同一待确认状态。
2. compose：填充双语文案与三张截图，等待字体、图片解码后导出透明 WebP。提交的两张图分别为 113,880 和 98,842 字节，带 alpha；旧资产没有剩余引用。布局使用单一 hero 色彩区，三处标签对应成员、成果和决策，符合营销页的展示边界。
3. Try LoopX：复用安装与明确宿主调用，保留状态和安装诊断的解释，高级路径默认折叠。它压缩了阅读步骤，没有证明已安装宿主或真实长程执行已验收；首屏图也没有替代这类资格验证。

对主干的风险

主要风险是维护者更新截图时得到一个看似成功、实际缺少核心内容的资产。现有 README smoke 检查引用和文案，无法捕捉这个缺口。独立验证在全新真实 demo 后端复现了空 proposals；补一项“必须有待确认批准入口”的浏览器断言后，原流程因计数为零而失败，隔离预览准备完成后中英文计数均为一。这个对照没有批准场地、启动模型或改变用户的活动 Goal。

本地 README smoke、docs governance、两项 workspace demo 测试及两种来源的 Chat 构建通过；原生 renderer 在原 checkout 与声明依赖集成中均完成双语输出。后者是组合来源验证，不是 bare head 已经包含三个 UI 功能的证明。渲染代码、demo producer、模板、测试和相关设计/安装 owner 在新 commit 中逐一核对了 blob，均未变；新 README 全量差异、GitHub GFM 输出和文档检查重新验证。整屏检查使用 GitHub GFM 与本地近似样式，覆盖英文桌面明暗和中文窄屏明暗；没有水平溢出，模拟说明可见，手机细节主要依赖 caption 与正文。它不是安装后的 App 或 GitHub 页面 chrome 验收。

依当前 capability 契约，没有查询或等待 GitHub CI。作者列出的其他 smokes 和两个历史失败未逐项独立重跑，不据此宣称它们通过或完成归因。#5415、#5420、#5421 仍是明确的合并前提；#5420 的现有记录归属问题 也需要先修复，当前 renderer 的四个不同 Agent 不覆盖那个配置。首屏批准由作者在 PR 中记录；本轮没有更改该呈现，也不把批准声明当成复现证据。

我的整体评价

REQUEST_CHANGES，阻塞点是复现流程缺少决策预览，不是否定 hero 或安装说明的方向。持续推进的生产效果边界保持原状，文档中的普通用户阅读路径更短；但最关键的展示复现仍不完整。修复可留在当前 demo owner：复用真实 typed preview，只准备、不 apply，并等待和检查卡片，保持隔离与双语模拟说明。面向下一次变更的整理也应集中在这个准备/捕获边界，无需引入新能力、第二套状态机或宽泛截图框架。

新 mock 字段复用既有 API 词汇，营销模板属于本地展示，没有新共享协议、default-off 功能或机器强制义务。新 head 应补全新目录的耐久复现断言，再跑 renderer、README 检查，并重新评审全量 PR。原本的真实多 Agent、安装及父目标验收缺口不由这份文档关闭。最终合并仍由维护者处理。

English verdict: REQUEST_CHANGES - A fresh documented demo renders both heroes successfully without the owner approval card shown in the committed assets, including after integrating the three declared UI dependencies. Prepare the real typed decision preview in the isolated demo without applying it, and require the pending control before capture. A preview-only diagnostic restores one control in each language; it is not a delivered repair. Re-review the new exact head and retain the dependency merge hold. No merge was performed.

[huangruiteng]

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

Reviewed head: ea674696434dfba5a6fea7ec8fd9e36dd6d49b22; immutable diff baseline: b5c220d3d76dcf1fa2d0a85f19fe5e6629974fdd.

动机

发现两个 P2 阻塞：当前公开复现命令会拒绝合法的目录身份，以及必需依赖产生的当前 demo 版本。README 首屏本身已更清楚，但“可复现的打包 App 示例”也是这份交付的承诺，文档 smoke 通过不足以关闭它。

目标是让新用户先看到团队、就地决策和附带证据的结果，再从已有 Agent 开始。相比基线的任务板截图和 doctor/connect/manual fallback，双语新入口减少重复设置；已有状态复用、权限和实际续跑仍由既有入口负责。该 PR 不宣称完成真实 Agent 协作或已安装桌面版验收。

改动思路

复用现有 Workspace stories、打包前端和 typed gate.resolve preview，先准备真实 pending proposal，再截图、合成静态 WebP。Goal/Todo 和 owner decision 来自真实隔离后端；对话、SSE 和团队记录通过浏览器 mock，双语图片下方明确披露。渲染器不 apply，最后比较 Todo 状态。这一归属合理，没有新 capability、权限 owner 或持久化分类。

安装入口复用现有 workflow installer 和 guided $loopx，高级宿主折叠到 details，并保留安装恢复指南；旧板图删除，避免相同内容在首屏和工作区段落重复。相关未来修改只需收敛 demo 身份/version 的读取，不需要新增框架或通用兼容层。

具体改动

九个文件均已检查：中英文 README 的首屏、两步入口、试用段落和折叠宿主；demo README 的公开复现命令；92 行合成模板、284 行 capture 脚本；两张新 WebP、旧板图删除；现有 public-entry smoke 的双语资产引用。hero.html 只负责合成与透明圆角，capture 负责语言/截图，prepareDecision 走现有 preview，最后 decisionState 比较全量该 Goal 的 Todo。没有修改自动安装的技能内容或产品运行时。

• [P2] render.mjs 第 45 行：目录身份使用了不同规范化规则。 按 demo README，serve 和 render 都传 /tmp/workspace-hero。macOS 上 Python Path.resolve() 把 manifest.root 写成 /private/tmp/workspace-hero，Node path.resolve() 仍是 /tmp/workspace-hero。因此全新的匹配 demo 在 preview/截图之前就 AssertionError；我在当前 head 独立复现。应按真实文件系统身份规范化后继续核对 manifest，保留对其他目录的拒绝；不要放松所有权检查。验收应包含原样 /tmp 命令及 foreign manifest 负例。
• [P2] render.mjs 第 44 行：与必需依赖的 demo producer 不兼容。 PR 要求先合入 #5415；其当前 producer 已写 workspace_story_demo_v3，这里却只接受 v2。固定 #5415 ab6b22974ece02abde567cedd90bde5e57a70154、#5421 24f64eaf145ce3f7376a641e6808f497d677129b，加上基线已合入的 #5420，重新构建实际 App、创建新 demo，传 canonical root 后仍在此处退出。随后读回 #5415 d0f9b51c16fdc4c0ec44f87d3b524c1242e1c528，该 producer 字节未变。请对齐 demo 现有 owner 的版本契约，再跑原生脚本的完整双语 capture；合并依赖本身不会消除这个拒绝。

对主干的风险

独立通过：README public-entry smoke、2 项 demo 测试、docs asset integrity（7 项）、docs governance、star-history 和 diff 检查。实际 GitHub 固定 head 上检查了中英文图片加载、桌面明暗主题、390px 中文首屏、开始使用 anchor、展开宿主和可复制安装命令。窄屏图片作为概览，mock 披露和下一步文字可见；没有把截图当作持久化或实时执行证据。

相同安装命令在基线/head 的独立空 skills 目录执行，35 个安装内容文件完全一致；只有按目录与时间产生的安装 receipt/lock 不同。实际 entry 保留既有 Goal binding 或进入 canonical guided start，说明 README 的短路径复用已有实现，而不是改变宿主默认权限。安装仍不授予合并、网络或项目权限；高级宿主的 advisory 与 enforced 区分保留。新增 JS 只用既有 gate.resolve 和本地 fixture 词汇，未创建共享状态分类；语义 advisory 对此 JS 不覆盖，已另行手工检查。

以前“没有准备审批卡片”的问题已获得诊断性进展：在私有诊断脚本中仅接受当前 v3、使用 canonical root，保留其余 capture 和状态断言，中英文真实审批按钮均可见、两图生成且 Todo 前后相等，单独读回 preview receipt 为 null、gate 仍 open、依赖工作仍 blocked。随后通过 demo 自身 advance 改变隔离测试决策，fresh-gate 断言正确拒绝。这证明核心卡片准备有用，不算当前原生脚本通过。裸 head 用 canonical root 仍等待审批控件超时，这是明确声明的尚未合入 UI 依赖，未另列为缺陷。

最强回归就是通用 smoke 都绿、贡献者原样运行公开 recipe 却在浏览器之前退出。修复仅需协调目录 identity 与当前 demo schema，保留可见性、fresh gate 和 no-apply 保护。未资格化真实模型、生产协作、已安装桌面或最新依赖的完整 UI 验收；作者更宽泛的 smoke/历史失败归因没有继承。按当前 review policy 不查询或等待远端 CI。

我的整体评价

REQUEST_CHANGES。首屏设计、明确模拟边界和短入口是有价值的增量，结构与用途相称；但两处独立的 false rejection 让当前承诺的复现路径不能交付。修复上述两个 P2 后，按当前依赖在新目录原样运行 EN/ZH 脚本，保留未批准状态和负例证据，再审当前 head。#5415/#5421 的依赖合入与维护者合并决定继续单独处理；本评审没有合并授权。

English verdict: REQUEST_CHANGES - ea67469; two P2 reproducibility blockers: lexical root comparison rejects macOS /tmp aliases, and the renderer rejects the required dependency's current v3 demo manifest. Public/docs smokes and isolated installed-skill parity passed. A bounded private diagnostic produced both languages without applying approval; the unchanged native renderer still fails.

[mergify]

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @huangruiteng.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork