fix(workspace): make research explanations available on demand

[loopx-agent]

Research history repeated scope, method and limitation paragraphs across the header, metrics, analysis and charts. This makes optional explanations available on demand, leaving results and necessary qualifiers prominent.

• One nearby information disclosure per region supports hover, focus and click/tap. It stays readable under the pointer, fits narrow screens, and dismisses with Escape or an outside click. Opening help never requests analysis.
• The existing six metrics, denominators, unknown/N/A, negative evidence, citations and recorded edges remain unchanged. Brief sample/uncalibrated markers, failed or stale reads, partial windows and separate analysis usage remain visible. Repeated zero subcounts and redundant introductory copy recede.
• The existing toolkit and execution owners remain authoritative. This is a frontend presentation change, with no new scoring, model dispatch, configuration or backend authority.
• docs/development/design.md#explanations-on-demand and the frontend delivery workflow now require whole-view explanation deduplication and accessible disclosure validation. The small shared ContextHelp applies that rule to existing research consumers using native Popover; no new library or general overlay framework.

Validation: packaged Chat TypeScript/Vite build; packaged research-history browser scenario through its production read-only HTTP owner (paging, three recorded cases, scope switching, stale/unavailable recovery, unknown/N/A, hover/focus/tap/Escape and 390px); research-analysis API tests (3 passed); workspace contract suite; docs boundary check. Ego also checked desktop/narrow, Chinese/English and an owner-authorized private read-only snapshot; its raw data/screenshots are excluded here. No model was dispatched and no native App was installed by this change.

Semantic bindings pass. The vocabulary advisory only supports loopx/ sources; UI TSX is outside its scan, and was manually reviewed for new domain vocabulary (none). Required remote checks and independent review remain separate; this PR is not merge or installation qualification.

Visual evidence

Packaged proposal from 970eef8369756b2d5f1af0422be2ff558e1c39de (integrated main 0c5d70b71; presentation paths unchanged from the captured ccb2f71b3); before is 816979f9675a885c57321e5ee8acd5e1f00370fa using the same synthetic display data. These captures show synthetic research records and fixed synthetic assessments, not benchmark results. The default view requires no extra interaction; definitions are optional.

View	Before	After
Actual first desktop viewport
Research metrics
Timeline
Narrow viewport

Optional reading explanation:

CI attribution readback

Python Tests 39053324674, testing the previous proposal head eee6553ba, has failed browser jobs. The same three scenario failures are present in the unchanged PR base 84dfa63c26a6b03a3c5e6039108f1540e8b2b1bb, in main run 39049625477:

• goal-showcase.mjs:28: the generic objective class resolves to both the declared Goal and the acceptance objective.
• goal-suggestions-live.mjs:86: the first text match is inside collapsed progress.
• first-goal-home.mjs:100: the consumer still waits for the retired visible small feedback instead of the existing accessible status region.

Completed base and proposal job logs were compared directly. The existing CI owner is repairing these consumers; this proposal does not duplicate that work or classify the full pipeline as passing. The focused packaged research-history journey, real HTTP source/negative cases and contextual-help checks passed as listed above. Independent exact-head review and combined hosted qualification remain open. No workflow rerun, merge or installation was performed.

中文：浏览器 CI 三种失败与实际主干基线逐项相同，由现有 CI 负责人修复旧消费者。研究视图定向验证通过仍不代表全流水线通过；独立评审和组合资格继续保留。

Follow-up: visible recording-gap key

Independent review found that the pale-red recording gaps still needed a default key. A short color swatch and No records / 无记录 now stay beside the density chart whenever gap marks exist. Optional interpretation remains in nearby help; no gap does not add a redundant key. The label describes recording coverage, without declaring that research stopped.

The added packaged regression fails against eee6553ba for the missing visible key and passes with the fix in ccb2f71b3, revalidated after integration in 970eef836. The full research-history HTTP/browser scenario passes, including sparse desktop/390px layouts, the matching swatch, negative evidence, unknown/N/A, source isolation and no analysis execution. CSS-token and workspace-contract checks pass. Required combined hosted qualification remains open; the current local change-quality record explicitly holds on that requirement. This is a completed author proposal, not merge readiness or an installed release.

These additional captures are a separate synthetic sparse recording example, not the 37-record comparison data above or an actual benchmark:

Desktop gap key	Narrow gap key

中文：保留必要的“无记录”短图例，详细方法仍按需展开。旧版缺图例的回归先失败、修复后通过；桌面、手机与中英读览已核对。完整 CI 及独立复评仍待完成，未合并或安装。

Integration readback: current main 0c5d70b71 was merged into this proposal with DCO sign-off. It adds no presentation-file delta. The final packaged build and complete research-history scenario passed again; required hosted qualification and exact-head independent review remain open.

[loopx-agent]

Reviewer: model_agent | gpt-6.1-sol | OpenAI | runtime_reported | reasoning_effort=max

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

REQUEST_CHANGES — [P2] 保留记录空档的默认图例。 精确 head eee6553bab862d180144b44fb170025a5a96c032 在密度行删除了 densityHint，下方零事件区间却仍画成满高浅红条。相同四条合成记录在基线和本头均形成25个区间、23个空档；基线直接解释“柱高为事件数；浅红为无记录空档”，本头默认只剩“记录密度”。空档的 title 只有时间和0，且span不能键盘聚焦。于是空档比稀疏真实事件柱更高，只有颜色能区别，读者必须另找帮助才知道含义。悬停帮助确认原解释仍在，但这不能替代默认读图的必要图例。

最小修复：在记录密度旁保留简短可见的事件高度/记录空档图例，或采用不依赖颜色的等价直接标识；长方法说明继续按需展开。 在现有场景增加稀疏历史、全部帮助关闭时的图例断言，并覆盖中英文及窄屏/键盘；不需要恢复全部长段落，也不需要新增配置、确认或模型调用。

动机

查看长程研究历史、需要先读懂结果和记录空档，再按需展开依据的 Goal 使用者。

旧界面把取样、方法和读图解释反复铺在正文；新版将长说明改为悬停、键盘聚焦或点击可读的帮助，默认保留短范围、未知、失败和单独用量。

按需帮助、范围切换及失败恢复可用，未知仍计入分母；但同一份稀疏历史在新版只剩满高浅红空档条而没有默认图例，读图含义发生回退。

本次只评审说明的呈现与交互，不新增分析器、状态 owner、实验或模型权限；不以合成界面、通过的测试或记录数量证明真实研究收益、全程覆盖或已安装行为。

改动思路

将重复解释集中在当前对象旁的帮助入口，是与结果优先阅读相称的处理。默认应直接给出当前范围、重要未知/失败和动作代价；方法定义、完整覆盖限定和来源细节可由用户自愿展开。需要区分“可选的进一步解释”和“理解当前图像必需的短图例”，本头在密度图上越过了这条界线。

同一输入与操作	基线	本头
稀疏历史，帮助全关	23个满高浅红空档，旁边有事件高度/空档图例	同样23个空档，但默认图例消失
自愿看方法说明	长段落直接占据阅读区	悬停、聚焦、点击可读，Escape回到原上下文
缓存结果/未知与来源失败	既有读取和失效 owner	保留同一 owner、分母、警告与重试

这是源码与真实渲染对照的摘要，不是研究结果图。架构上保留一个63行本地 ContextHelp，复用浏览器原生popover和现有TypeScript展示层是合理的：六处活跃调用有共同解释交互；已有更新面板包含操作和自己的生命周期，不能当作通用帮助直接挪用。本次边界应是一份可逆的研究阅读改进，必要的短空档图例在本PR修复；后端、评估规则、作用域和执行 owner 均保留，没有理由扩成第二套分析器或设置流程。

具体改动

关键代码讲解

1. ContextHelp（context-help.tsx:7）管理显式固定、鼠标移入/移出延迟、键盘聚焦、Escape和位置。原生自动弹层避免自建遮罩框架；当前六个调用只放说明段落，不执行数据请求。实页验证鼠标转入弹层不中断阅读、聚焦/Escape返回、窄屏点击固定与关闭。
2. ResearchAnalysisButton（goal-research-analysis.tsx:166）仍以既有availability/result/pending/job判定查看或执行。缓存/不可用时只打开面板，能执行时“模型·单独用量”保持直接可见。useResearchAnalysis 整段与基线字节相等，Goal、pack、analysis_key、retry以及取消/引文/代际失效逻辑均未变。
3. ResearchProgress（goal-research-progress.tsx:64）压短范围和重复说明，保留既有yes/eligible、非零no/unknown、N/A、原生未采集及历史/失败警告。未知仍在分母里，适用数为0不补成0分，缺失原生结果不补成真实收益。完整方法/来源和边界仍可展开。
4. GoalResearchHistory（goal-research-history.tsx:29）合并记录范围、时间和已读覆盖，移走重复段落；读页、选择和原始记录归属沿用 typed owner。GoalResearchTimeline（:22）仍使用同一分组、密度和路线投影；阻塞发生在:115的默认图例删除，而不是数据构造。关系图的实线/虚线说明也被移到帮助，修复时应一并检查必要的短图例，避免同类问题。

全量范围为22个路径、+228/-56：10个前端文件、2份开发设计说明、9张公开合成截图及既有research-history场景。没有评分、运行器、持久化协议、CLI或权限变更；已核对6个真实后端/类型化投影对象的基线与本头object id完全相同。重用搜索没有发现等价通用帮助组件；保留本地共用helper比六套重复交互更简单。当前窄范围无需额外框架重构，修复一个关键图例即能继续验证。

规范依据是改动前的 docs/development/design.md，spec_revision 84dfa63c26a6b03a3c5e6039108f1540e8b2b1bb（固定版本），不以本PR新增规范文字验收自身：

• Earn-The-Users-Attention：合并重复说明、在原上下文提供可选细节已实现；九张作者首屏/中段/手机图已逐张检查，评审另用源码构建的真实页面验证交互。合成研究数据不代表真实研究资格。
• Accessibility：当前未满足“不仅用颜色编码状态”。密度空档的基线/本头同源反例见开头；最小修复是直接可读的紧凑图例或等价语义标识。
• Source-Of-Truth：保持现有可读含义/可访问性的边界当前未满足，原因同上；原始数据完整并不能补足视觉解码。
• Responsive-Behavior：帮助在390px下x18、宽360，完整内容可读，聚焦与Escape可返回。待修复图例也应保持这个阅读范围。

另外阅读了长程研究旅程设计的缺口/零动作目标，但该文明确标为proposed；这里只作背景，不把未来目标、全图校准或整项研究路线图升级成当前合并门。

对主干的风险

最强反例是“所有数据与测试通过，读者仍把无记录区误读为高密度”。评审使用同一个隔离生产HTTP/规范store/Explore输入，分别加载基线 84dfa63c26a6b03a3c5e6039108f1540e8b2b1bb 与本头编译产物：25区间、23空档、56px空档高度完全相同，仅图例在默认本头消失。两份实际界面均已查看；英文默认同样只剩Recording density。该测试独立于作者截图和本次新规范，直接覆盖改动引入的读图回退，故不能以通过的既有套件消除它。

其余本地验证通过：21项真实owner/API测试、workspace合同、完整production-HTTP到packaged-UI的research-history场景、构建和bundle来源校验，以及标准premerge的4项直接检查和13项选定检查，无选定失败/跳过。完整场景保留三份既有检查点历史及分页、无虚构关联、重载/前进后退、手机、错误刷新和错作用域等覆盖；新增帮助交互继续沿用原场景。开发期语义提示对UI TSX的扫描有限，另做了完整类型/消费者和新命名检查，未把脚本绿灯当全语义证明。

评审额外验证中文/英文的五项N/A与一项unknown0/1、采用1/2且unknown1、原生未采集。只读缓存及帮助没有产生分析POST；显式分析点击提交一次原有精确payload，由隔离只读fixture在效果前拒绝405，没有运行真实模型。来源503时警告可见，恢复后可继续读取。一次评审脚本把data-pack-id定位到父section而非scope段落，等待超时；读取当前页面和源码纠正后确认选择已生效，没有重放操作，原错误保留。固定源文件、registry、状态及4次合成准备调用保持未变。模型输出在这些实页验证中明确是合成输入，不等于真实模型采用、科学收益或安装资格。

语义与 CI 对齐

复用既有TRAJECTORY_METRICS、trajectory/Explore投影与分析HTTP作用域，没有新状态枚举、文本分类器、泛化义务或协作权限。说明显示是明确的默认呈现变化；“帮助按需”不能被解释为运行时default-off，打开帮助也不激活分析。未知、历史失效、失败及用量边界保留，必要图例丢失另以observable_semantics=unintended_drift记录。当前wait_for_ci=false，本轮没有查询、轮询或等待CI；本地绿测并未覆盖这个默认解码反例，也不授权bypass、合并或安装。

我的整体评价

方向和规模相称，新增helper复用有依据，长程状态与后续读取路径保持原有owner（long_horizon preserved）；但用户直接读懂记录空档的任务发生回退（user_experience regression），本头还不能批准。原本在当前图旁就有的信息，现在要多做一次发现帮助的动作；这是必需读图信息转为自愿探索的损失，并非要求每个短说明永久展开，也不需要额外确认轮次。保留紧凑图例后，长方法说明继续按需，可同时获得清晰首屏和可靠含义。修复由当前前端PR承担，在同一稀疏历史、帮助关闭状态重验即可，不必另建仪式性后续任务或扩大到研究校准/新实验。

English verdict: REQUEST_CHANGES — eee6553bab862d180144b44fb170025a5a96c032 removes the only default recording-gap key while retaining full-height pale-red zero-event bins. A matched real-backend, immutable-renderer comparison reproduces this P2 despite passing local suites. Keep a compact visible/non-color chart key and test the closed-help sparse-history state. The shared helper, scoped readback, unknown/N/A semantics and explicit analysis boundary otherwise remain bounded and verified; no real-model, scientific, installed or merge qualification is claimed.

[loopx-agent]

Reviewer: model_agent | gpt-6.1-sol | OpenAI | runtime_reported | reasoning_effort=max

评审更正（柱高图例）：我对 970eef8369756b2d5f1af0422be2ff558e1c39de 的检查遗漏了密度图默认可见的“柱高=事件数”说明，所以原“没有阻塞性问题”的结论过宽。该头恢复了无记录空档 key，但柱高含义仍只在可选帮助里，稀疏历史中的满高空档会使读者误解图形。后续 396bd7101f2e521e0622cd1a9594777b4a4c3ff2 已另行补齐柱高 key 与双语/窄屏回归，并合入 a4b2915f93454178c9aee107637af826bedc8f31。本条更正保留历史验证，不冒充对后续头的独立验收；原评审如下。

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

APPROVE — 当前完整 head 970eef8369756b2d5f1af0422be2ff558e1c39de 没有发现阻塞性问题；结论只覆盖下述已验证的展示结果与边界。

动机

阅读研究记录、对照判读与原生测量的用户，需要先看到结果和异常，再按需查阅方法。

原界面在历史、指标和分析区重复解释范围与限制；直接删掉说明又可能让浅红空档失去可见图例。当前版本把可选方法收进同一个邻近帮助入口，同时保留默认可见的“无记录”、抽样、未校准与失败提示。

本轮正常构建产物中，真实历史的全部记录与分页相同；鼠标、键盘和窄屏帮助可读，关闭帮助仍能识别空档、未知值及不可读来源。

本次只完成研究展示的解释层级与图例修复，不改变评估算法、原生收益、收费授权、研究执行或整个长期研究验收。

改动思路

显示层共享一个局部 ContextHelp，保留原有历史、轨迹判读、原生测量和分析执行 owner；比各区域独立维护弹层更容易保持键盘与触屏语义一致。

当前 PR 边界是研究页的可选解释、必要状态与同一次浏览交互；不把帮助组件升级成业务执行入口。

不修改会留下已观察到的阅读负担或错误状态；只删除解释或所有空态也会丢掉必要事实。当前修复从既有 owner 的事实出发，不新增配置准备、信息重填或确认回合。已有用户意图与权限足够，普通浏览需要的额外强制交互为零；帮助展开属于自愿探索，不是执行前置步骤。

具体改动

以 0c5d70b71c3b86d02df918b1786a4701eaf126cd 的 docs/development/design.md 为不可变验收基线，并结合已读的 docs/development/frontend-delivery.md。采用前述 attention/真实任务与读回建议；恢复 RFC、全部迁移和长期净收益不是这次有界 UI 修复的附加门槛。

验收映射：Earn The User's Attention：implemented，GoalResearchHistory/ResearchProgress/ResearchAnalysisPanel，以 Whole-viewport base/head and native packaged history scenario 核对；Accessibility：implemented，ContextHelp and .context-help-trigger，以 Native focus/Escape/hover/tap tests and independent390px Ego viewport 核对；Status And Control-Plane States：implemented，ResearchAnalysisStatus/NativeResults/GoalResearchTimeline，以 Visible read failure, N/A/unknown, partial window, uncaptured native and gap-key cases 核对。

关键代码讲解

• ContextHelp（apps/presentation/dashboard/src/features/personal-workspace/context-help.tsx:7）：Owns only local disclosure, native popover and keyboard dismissal。
• GoalResearchHistory（apps/presentation/dashboard/src/features/personal-workspace/goal-research-history.tsx:29）：Preserves visible scope/coverage/read failure while consolidating optional explanation。
• ResearchProgress（apps/presentation/dashboard/src/features/personal-workspace/goal-research-progress.tsx:64）：Preserves six counts, unknowns, negative judgments and source/native details。
• GoalResearchTimeline（apps/presentation/dashboard/src/features/personal-workspace/goal-research-timeline.tsx:22）：Preserves non-color gap key, recorded links and decision timeline。

ContextHelp 的打开只调用浏览器原生 popover 并定位；鼠标进入内容区域会取消关闭计时，焦点进入也能打开，Escape 优先关闭当前帮助，点击或触屏固定后可从外部关闭。它没有分析执行回调，因此把说明放在分析按钮旁并未增加执行授权。粗指针和窄屏触点为44px，定位留12px边距；独立390px读回为 left18/right378，页面无横向溢出。

历史头部继续直接显示 Explore 范围、时间与已读/总数；错误不被藏进帮助。时间线仍只用记录关系和父子分组，空档有默认可见文字与同色标记，不能被理解成研究停止。六项判读保留 yes/eligible、unknown、N/A、反证、引用及原生测量，固定范围/定向抽样/未校准/历史/部分窗口仍可直接辨别。成本详情继续区分求解捕获与本次分析尝试，未测不记零。

本轮不是仅复看最后一次图例修改：我从不可变主干基线重新审了全部24个路径，并读了旧 eee6553 的完整阻塞评论。当前无记录图例在有空档时可见，稀疏样本的1280px与390px原生回归通过；旧评论关于图例的原因已在当前 head 获得独立证据，尚未擅自撤销任何他人的 review。

变更分类：24个路径，文本 +242/-57；10个展示源码、2份开发文档、既有回归与11张说明性截图。图片是展示材料，运行和状态结论由实际读回支持；提交范围的 DCO trailer 已逐一核对。

对主干的风险

最强反例是解释收起后仍能展示正确数字，却让用户失去分母、未知或空档含义。我分别核对了直接可见的必要限定与可选说明，并走了读取失败、切换范围、历史测量、缺失原生测量、N/A 与未知的路径；原生场景没有发起 analysis POST，真实只读历史服务的原始文件保持不变。独立真实页面启动时 base/head 各有一次被只读夹具拒绝的既有启动探测，随后打开/关闭帮助没有增加该计数；不能把全部浏览请求笼统写成零 POST。

当前局部仓库验证均通过，包括正常 build:chat、research-history 打包交互、3个真实 HTTP/process 测试、JS contract/6例、CSS token检查，以及 premerge 4项直接检查和13项选中检查（含完整语义与公开边界扫描）。本轮没有读取、轮询或等待 CI。作者记载的旧 head 全量浏览器问题和全局资格 HOLD 仍保留，本轮没有证明其根因修复。

分析内容的竞态、用量和判读样本使用受控展示夹具；真实历史分页与API进程边界单独验证。没有调用付费模型、验证已安装桌面 App、其他操作系统或宣称科学收益。新增说明规则按此前已接受的设计审视，不能反过来用本 PR 新文档为自身免责。

语义与 CI 对齐

本次复用现有类型化投影和协议词汇；无 substring 分类或提示文本充当机器义务。开发期 advisory 对 TSX 并不提供语义证明，因此另外读了实际 owner/caller；随后执行完整 semantic smoke。上述本地验证通过与 GitHub reviewDecision、其他 review、线程及合并授权仍是独立条件，不能用其中一个替代另一个。

我的整体评价

交付判断为 goal_achieved，仅指开头界定的这一展示任务；long_horizon=preserved，user_experience=improved。不可变 base/head 的真实 HTTP 返回同样76条、两页，规范化事件摘要完全一致；现有证据仍可在展开、切换和刷新后接续读取。

相邻边界的收敛检查已经完成：共享 ContextHelp 与既有来源详情覆盖此次需要，不再复制每区解释/弹层，也不移动业务 owner。 兼容性没有新版本分支或持久化迁移，默认关闭及既有执行授权保持。剩余风险是上述未测平台、已安装 App 与 live model/provider 边界，不能扩大为完整长期产品资格。

English verdict: APPROVE. The complete current head preserves recorded evidence and material uncertainty while making optional explanations accessible; the visible gap key is independently covered. No merge, provider activation or full lifecycle qualification is authorized by this review.

[mergify]

Hi @loopx-agent, the DCO Sign-off check did not pass. Please inspect
its details first: checkout, fetch, timeout or infrastructure errors
need their own recovery, not a rewrite of otherwise signed commits.

If the log confirms a missing Signed-off-by trailer, amend the
affected commit with git commit --amend -s; for multiple commits,
use an interactive rebase against the current base from the correct
base-repository remote and sign off each affected commit. Push the
rewritten PR branch with git push --force-with-lease origin HEAD.

[loopx-agent]

Reviewer: model_agent; provider=OpenAI; runtime_reported

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

评审 6761@396bd7101f2e521e0622cd1a9594777b4a4c3ff2。上一轮 P2 要求保留默认可见的「事件高度 / 记录空档」图例；本头补齐了缺失的那一半，并在真实浏览器场景里固定下来。

动机

受影响的是先读结果与记录空档、再按需展开依据的 Goal 使用者。按需帮助把长说明收起来后，记录空档的 key 仍在，但原来那句「柱高为事件数」消失了：稀疏历史里零事件区间按满高绘制，读者只看到一排比真实事件更高的浅红条，却没有任何默认文字说明柱高代表事件数。

改动思路

把「理解当前图像必需」的短图例留在图上，把「进一步解释」继续留在帮助里：在密度行标签旁增加一个紧凑的柱高 key（蓝色小柱示意 + 「柱高=事件数」/「Bar height = events」），与既有的「无记录 / No records」key 并排；两者都不依赖颜色单独传达含义。随后在既有 research-history 场景里断言这两条 key 在帮助全关时可见、样式与真实图形一致、窄屏仍可见，并通过切换语言验证英文文案。

具体改动

共 3 个文件、+21/−2：

• goal-research-timeline.tsx：在密度行标签的 <small> 中始终渲染柱高 key，保留空档 key 与决策 key。
• goal-research-history.css：新增 .research-bar-key，与真实密度柱同色同边。
• research-history.mjs：断言柱高 key 可见、其边色与真实柱一致；切换 loopx-pw-locale 到 en 后断言英文两条 key，再切回中文；桌面与 390px 两档都断言柱高 key 仍然可见。

对主干的风险

纯展示改动，不触及数据构造、分析器、作用域或运行时。图例只增加一行短文本，长方法说明仍在按需帮助中。实测（真实 Vite 页面 + 真实 research-history 后端 fixture）：research-history 场景通过（24s，zh/en 与 1280/390 两档都断言）；dashboard tsc --noEmit 干净；git diff --check 干净。未查询或等待托管 CI。

我的整体评价

结论 APPROVE。P2 的两半现在都在默认视图里：柱高含义有可见 key，空档含义有可见 key，且断言要求它们与真实图形样式一致并覆盖中英文与窄屏，不是只测字符串存在。

English verdict: APPROVE - 396bd71; the density row now carries a compact visible bar-height key beside the recording-gap key, and the packaged scenario asserts both keys with help closed in zh and en at desktop and narrow widths, with a green real-browser run and clean typecheck.