docs(site): publish comprehensive agent skill guide

[songoow]

Current integration validation

Head 9d5cd96aee388653238d2585b29f0f6d7906e52e includes main a59aed703374040240f23b2e51ddaf209fcbacc4 and the merged #6431/#6463 shared CI repairs. The PR retains its existing implementation scope. Local validation used Node22.22.3 with SQLite3.51.3 from this source checkout; the 17-case digest guard and real legacy-extension CLI regression pass. New exact-head hosted checks and review remain required.

The two real root/project-base builds and wrong-base/missing-guide negatives pass. Guide/UI behavior is unchanged; earlier approval belongs to the prior head.

Summary

The public website has no agent-readable entry that explains how to adopt LoopX and reach its existing workflows. Publish /loopx/skill.md as a comprehensive guide covering product concepts, installation, host selection, task execution and recovery, seven packaged skills, three optional workflows, common requests, stop/update/uninstall, and authority/privacy/evidence boundaries.

The guide links to canonical skills and defers execution to the installed version and current runtime contract. It ships unchanged through the existing Vite public directory and Frontstage Pages exporter. An English/Chinese footer link makes it discoverable, with wrapping on narrow screens. The SEO check derives its exact guide URL from the built application base, preserving both default root previews and /loopx/ publication. Existing publication and browser smokes check source fidelity, owner/document links, keyboard navigation, raw Markdown readback, and missing-file behavior.

Boundary and design

• Owner: public-site documentation and discovery, supporting roadmap S12 onboarding. No new capability, provider, skill installer, scheduler, or execution authority. This does not close clean-machine onboarding or collaboration qualification.
• Frontend: one footer link; CLI and Lark behavior unchanged. The hero, primary CTA, and opening navigation are unchanged.
• Visual evidence: before/after desktop (1440px) and phone (390px) screenshots inspected locally. The existing footer carries the useful discovery action; links wrap without adding a new panel or competing first-screen content. English and Chinese labels are checked.
• Future-facing pass: reuse canonical skill owners and the existing export/validation chain instead of duplicating workflow bodies or adding a separate publisher. No further refactor needed.

Validation

Current revision validation:

• npm run smoke:seo:bases: two real builds passed (default root and /loopx/). Each also rejects the other base’s guide link and a missing published guide.
• The exact default-root artifact rejected by the original checker passes the revised checker. TypeScript compilation passed with that real build; git diff --check and candidate public/private scans passed.
• Semantic advisory was run; these .mjs validation changes are outside its loopx/ source scope and introduce no shared runtime vocabulary.
• Scope of this revision: SEO validation and a documented local regression command. The guide and UI are unchanged. No further production refactor is needed; deriving the URL from the emitted app script keeps the build base authoritative. New-head hosted checks and independent review remain required.

Previously recorded validation for the unchanged guide and UI:

• Skill frontmatter validation; all contents anchors resolve; documented command forms checked against this checkout's CLI help.
• Real managed-skill install, inspect, and uninstall in an isolated temporary skill root, including generated loopx and loopx-project readback.
• Production frontstage export under /loopx/, including TypeScript checks; strict MkDocs portal and Chinese/English Developer Book builds; case-page restoration.
• Existing seo-smoke.mjs --with-docs: exact Markdown publication, canonical skill/source targets, hosted guide targets, footer discovery, metadata and sitemap checks.
• Standard exporter public-boundary guard and public-site source scan; candidate credential/private-path scan and git diff --check.
• Manual browser navigation from the footer to the guide; desktop/mobile before/after inspection.

Previously passed at the original guide head: full smoke:frontstage-browser against the assembled publication. It covers 1440px/390px layouts, English/Chinese labels, normal/reduced motion, footer keyboard activation, exact Markdown readback, the missing-Markdown 404 case, and 183 published entry links.

Known baseline limits:

• Hosted TypeScript digest-consumer and Windows legacy-extension-history failures are shared baseline issues owned by existing test(digest): pin the direction authority consumer to restore main #6431 and fix(extensions): keep unverified legacy status readable #6463. Both dependencies are merged and included by this integration; new-head hosted qualification remains pending.

• examples/frontstage-pages-workflow-smoke.py fails on its existing ban of GH_TOKEN: ${{ github.token }}, already used by the unchanged Pages workflow. Both files match the base commit.

• Applying the exporter scanner beyond its normal export stage to the entire generated documentation tree reports existing documentation paths/markers. The changed public-site sources and normal exporter guard pass; this PR does not certify unrelated documentation.

• The hosted URL and GitHub Pages response remain unverified until merge and deployment. Local publication evidence does not claim a released or installed product change.

[loopx-agent]

Review exact head: 6479@e3b8c6306eee65c595ddda00bb95c0350d88f53c
Reviewer: model_agent; model=gpt-6.1-sol; provider=OpenAI; declaration_source=runtime_reported; reasoning_effort=xhigh

动机

从公开网站了解LoopX的用户和Agent，需要找到版本明确、可操作且不扩大权限的使用入口。 从现有页脚经键盘进入原始Markdown，按安装版本选择既有workflow；正式/loopx/产物成功，但默认根路径build后的SEO检查被新增硬编码断言拒绝。 真实导出、文档组装及桌面英文/手机中文导航读回一致指南；同一默认构建产物在旧SEO检查通过、当前检查因要求/loopx/skill.md而失败。 不部署网站，不安装或执行用户任务，不认证干净机器首次使用、宿主自动续行、运行中App或真实协作。 需先恢复根路径和/loopx/两种既有构建的检查兼容；托管响应和完整首次使用仍由原有S12验收接续。

指南有实际发现价值：它区分安装、host选择、请求工作、恢复和最终验收，把七项packaged workflow及三项可选流程交还原owner。当前阻塞是新增检查破坏已有构建方式；这份文档无需同时完成整个产品首次使用。

改动思路

公开指南属于现有site/public文档和页脚发现入口；版本、安装、执行和权限仍由既有workflow与runtime负责，文档不创建新的执行owner。 这是一份可独立发布的发现/说明切片；需要修复默认base检查回归，干净机器首次使用与托管部署仍按原S12分别验收。 对照固定基线 site README 的 Root-base local previews and Search publication：支持/loopx/及根路径本地预览，要求local build后运行 npm run smoke:seo，当前为 not_met。roadmap S12 discoverable onboarding boundary 的发现与权限分层已有独立证据，记为implemented；托管响应、clean-machine首次结果仍开放。

最小修复应复用真实build base，保持指南存在及链接正确的断言，并加入两base配对。无需新安装器、publisher、runtime配置或共享协议，也不应把所有本地构建强制改成/loopx/来迁就检查。

具体改动

完整5路径、+380/-2：347行原始Markdown涵盖产品、host、workflow、恢复、stop、升级卸载和权限；SEO扩20行，页脚加一条中英链接，nav加wrap，原browser smoke扩Markdown和404检查。变量 skill 读取发布文件与源字节比较；App 经既有basePath生成链接；.site-footer nav 在需要时换行；footer检查包含本轮新问题。Hero、primary CTA及opening navigation未改。

[P2] SEO断言应跟随实际构建base。 seo-smoke.mjs:39 写死 href=/loopx/skill.md。在site目录执行文档要求的 npm run build，原builder默认base=/，实际页脚正确为/skill.md，随后 npm run smoke:seo 却退出1：homepage footer discovers the skill under the project base。同一份产物交给固定base原SEO脚本退出0；正式/loopx/导出与with-docs检查均通过，故该P2与缺文件、前端导航或旧workflow红灯无关。

请从实际产物或明确base参数取得预期链接，继续检查footer确实指向发布的skill，并覆盖根路径和/loopx/两臂。不要删检查、放宽成任意包含skill.md，或改变已有默认构建来掩盖反例。

对主干的风险

独立当前证据：正常frontstage exporter在/loopx/下通过；portal、中英Developer Book三次strict build分别捕获exit0，标准case恢复后SEO --with-docs通过。指南正文/anchors、10种安全CLI help形式、canonical owner链接和真实隔离目录的managed skills install→inspect→uninstall均核对，未改本人host skills。Ego访问实际组装产物，1440px英文、390px中文页脚键盘进入均读回逐字一致的Markdown，无横向溢出，missing Markdown返回404；两张截图已检查。未把作者183-link/reduced-motion整套结果当成本轮重跑。

默认root build通过，当前SEO失败、同产物旧oracle通过，是新增可重复回归。另一个既有 frontstage-pages-workflow-smoke.py 对GH_TOKEN/github.token的禁止断言在固定base/head同样失败，guard和workflow blob相同；该红灯独立保留。语义advisory后full semantic、risk-based canary和正常export public-boundary通过，仍未覆盖root consumer。未查询、轮询、等待或启动CI。

预览准备曾缺site依赖、一次重试cwd错误及私有静态服务器拒绝根路径；仅修复本地harness，原记录保留，并在同一个Ego TaskSpace内恢复，产品源码和断言未改。指南的main-versus-installed precedence、禁止覆盖generated skill、外部动作授权、stop不等于完成及不保证取消in-flight工作均已读；无新canonical状态或执行权限。官网部署响应、clean-machine首次结果和真实长程收益仍未验收。

我的整体评价

REQUEST_CHANGES，一个P2：修复新SEO断言对既有根路径构建的误拒绝，并补两base回归。 指南与既有publication/footer边界合适、维护成本合理；有界修复后按新精确head复核。前向整理应合并base知识，保留canonical workflow owner；不需要另建publisher或无关重写。当前不授部署或合并权限。

English verdict: REQUEST_CHANGES - e3b8c63. [P2] The new SEO assertion hardcodes /loopx/skill.md and breaks the documented default root-base build→SEO workflow, whose correct footer links to /skill.md. The old checker passes the identical artifact;the /loopx/ export,strict docs and bilingual browser discovery pass. Preserve a discriminating guide check using the built base and cover both modes. Hosted deployment and clean-machine onboarding remain unqualified;CI was not consulted.

[songoow]

Readback on exact head 2c6d5dd208a6d060d54583e89b259b8bcbd3884e (fix(site): validate agent guide links against the built base), addressing the P2 from the review of e3b8c6306.

The SEO smoke no longer assumes /loopx/; it reads the base Vite emitted into the prerendered homepage and requires the footer to point at ${base}skill.md. Validated locally on this head in apps/presentation/site:

• Root base (documented local flow): npm run build → footer href="/skill.md" → npm run smoke:seo exit 0.
• Pages base: LOOPX_SITE_BASE=/loopx/ npm run build → footer href="/loopx/skill.md" → npm run smoke:seo exit 0.
• npm run smoke:seo:bases (node --test scripts/seo-smoke.test.mjs): 2 pass, 0 fail — both bases built and checked, wrong-base guide link and missing guide file rejected.
• Negative probes on the /loopx/ artifact: footer rewritten to /skill.md → exit 1 on the footer assertion; dist/skill.md removed → exit 1 (ENOENT).

Not verified here: --with-docs against an assembled Pages export, and the hosted deployment response. Checks on this head are still running; the typescript-core (2/3) and windows-powershell failures seen on e3b8c6306 reproduce on current main (addressed by #6431 and #6463) and do not come from this PR.

中文：在精确头 2c6d5dd208a6d060d54583e89b259b8bcbd3884e 上复核 P2 修复：根路径与 /loopx/ 两种构建的 smoke:seo 均通过，新增 smoke:seo:bases 2/2 通过，错误 base 链接与缺失指南文件两个负例均正确失败。未验证 --with-docs 与托管部署；该头上的 CI 红灯为当前 main 既有问题（#6431、#6463 修复），不来自本 PR。

[loopx-agent]

Reviewer: model_agent; model=gpt-6.1-sol; provider=OpenAI; declaration_source=runtime_reported; reasoning_effort=xhigh
Review exact head: 6479@2c6d5dd208a6d060d54583e89b259b8bcbd3884e

动机

公开网站的读者和 Agent 需要一个能找到版本对应 workflow、又不会自动取得执行权限的入口。这个提案经现有页脚发布原始 Markdown；之前新增 SEO 检查误把 /loopx/ 写死，导致正确的根路径本地构建被拒绝。本次实际构建证明两种入口都能通过，错误 base 链接和缺失指南仍被拒绝，旧 P2 已在当前头修复。

这次交付是可独立使用的发现与说明切片。官网部署响应、干净机器首次产出、安装中 App、模型执行及真实长期协作继续分别验收；读到指南不等于这些结果成立。

改动思路

复用现有 site/public、Vite BASE_URL、页脚及 Frontstage exporter。指南只解释产品和选择入口，七个 packaged workflow、三个可选流程的操作仍归原文件及安装版本；没有新安装器、provider、状态或调度 owner。

前向整理已落在同一边界：SEO 从已发布的应用 script 路径取得 base，消除第二份固定前缀知识；一组薄回归覆盖两种真实构建及两类坏产物。无需扩大成新的出版流程。收益是发现路径和本地验证恢复一致；长期净收益和模型理解没有被测试数量证明。

具体改动

先对照固定基线 ad863559af7a7cd6e10aa62137bbf69dd877fb3f 的 apps/presentation/site/README.md：Root-base local previews and Search publication 要求根路径及项目路径都支持 build→SEO，当前已满足；S12 discoverable onboarding boundary 的公开发现及权限分层有证据，后续首次使用和部署仍开放。

完整八路径、+434/-2：347 行指南、原页脚一条中英链接和换行、现有 browser/SEO 检查扩展，以及本轮新增的 README 命令、package script、47 行配对测试。关键位置：

• basePath:39 从实际 script URL 推导预期指南 href；仍要求 footer 指向精确地址，没有放宽成任意包含 skill.md。
• seo-smoke.test.mjs:18 分别构建 root 与 /loopx/，改成另一 base 的链接和删除指南后都必须失败；临时产物独立清理。
• App footer:1156 保留现有 locale/BASE_URL 入口。Hero、主要 CTA 和 opening navigation 没有改变。

指南逐段保留安装版本优先、fresh admission、实际 owner、可选功能启用、stop/完成/取消在途工作之间的区别，以及更新/卸载/数据保留边界。公共 frontmatter 是本地发现说明，不是新增共享生命周期；不能覆盖生成的 managed skill。当前仓库经验只用于检验这个普通读者旅程和阶段边界，不继承历史 verdict，也不证明经验有因果收益。

对主干的风险

独立当前验证：npm run build 的 TypeScript 检查与实际构建通过；smoke:seo:bases 2 passed、0 skipped，包括两 base、错误链接和缺失文件。另取同一份真实产物，对照三个不可变 checker：root 在旧 e3b 退出 1、原 ad863 和当前退出 0；/loopx/ 三者均退出 0，指南字节与源一致。这定位的是实际消费者回归修复，未删断言或强制改变默认构建。

语义 advisory 后，当前 native canary 3 direct +19 selected 全部通过，零失败/hold，公开边界通过。advisory 对本次 .mjs 不提供完整语法覆盖，不能把空结果当等价性证明。

复用证据有明确失效边界：guide、App、CSS、browser smoke、build 脚本和依赖 lock 六个 blob 与已完整审过的 e3b 相同，因此保留先前真实 /loopx/ 组装、三次 strict docs、桌面英文/手机中文键盘进入原始 Markdown、404 及隔离 managed-skills 读回结果；本轮没有重跑浏览器或整套文档组装。新 SEO 兼容性单独完成上述实测。不继承作者的 hosted 结果；既有 Pages workflow guard 的 GH_TOKEN 红灯仍属于未改变的 owner，没有据此宣称全站或 CI 全绿。三个贡献提交均有 DCO。未查询、轮询、等待或启动 hosted CI。

我的整体评价

APPROVE，当前完整头未发现阻塞项。 旧 P2 已由真实双 base 和同产物反例证实修复；五段原提案内容也在范围内，不是仅看最后一行。长期方向上改善发现、保留 canonical owner；用户体验上恢复普通本地验证并保留原发现旅程。代码量和维护边界合适，未来整理已应用在 base owner 复用，无需额外抽象。托管部署、干净机器首次结果、模型/安装态及长期效益继续开放；本评审不授合并、部署或安装权限。

English verdict: APPROVE - 2c6d5dd208a6d060d54583e89b259b8bcbd3884e. The root-base SEO regression is fixed without weakening guide discovery. Both real builds and wrong-base/missing-guide negatives pass; the identical root artifact fails the prior checker and passes the original/current ones. Current build/typecheck and3direct/19selected canaries pass. Unchanged-source browser/docs evidence is explicitly reused; hosted and installed onboarding remain unqualified. CI was not consulted.