feat(docs): streamline component onboarding

[kongche-jbw]

Why

The latest anolisa CLI release changed the recommended AgentSecCore
installation flow, while the AgentSight and Tokenless guides still left key
startup and installation choices implicit. The website documentation also had
two competing language-switch paths that behaved differently.

What changed

• Put Tokenless, Copilot Shell, and AgentSecCore quick starts first in the
  documentation sidebar without changing the existing homepage narrative.
• Keep the website language switch in the top-right navigation by stripping
  inline repository language links during the documentation build, with a link
  check that prevents them from returning.
• Clarify AgentSight package installation, systemd startup, and the two-terminal
  manual trace and serve workflow.
• Document the AgentSecCore anolisa install sec-core flow introduced in CLI
  0.2.16+, while preserving the agent-sec-core RPM package name and adapter
  setup details.
• Keep Tokenless on its supported anolisa install tokenless path, add PATH
  recovery guidance, and make the ANOLISA, RPM, npm, and source-build priority
  explicit.
• Use 30～70% for the Chinese homepage percentage range while retaining the
  existing English copy and scenario framing.

Preview: https://kongche-jbw.github.io/anolisa/

Related issue

no-issue: documentation onboarding and fork preview refinement

User / Agent impact

Users can reach the main component quick starts earlier in the documentation,
follow the current AgentSecCore and AgentSight startup flows, and switch
languages consistently from the website navigation.

Risk and compatibility

• Public CLI, API, configuration, or documented behavior changed

Documentation now reflects the released CLI behavior. No runtime code or
component interfaces changed, so compatibility risk is low.

Validation

• bash scripts/docs-lint.sh
• python3 scripts/docs-link-check.py
• npm run validate:locales --prefix website
• npm run typecheck --prefix website
• SITE_URL=https://kongche-jbw.github.io BASE_URL=/anolisa/ npm run build --prefix website
• SITE_URL=https://kongche-jbw.github.io BASE_URL=/anolisa/ npm run check:links --prefix website
• GitHub Pages deployment and live preview verification:
  https://github.com/kongche-jbw/anolisa/actions/runs/31076892647

Documentation and rollback

Updated the bilingual root quick starts, component READMEs, user guides, and
website documentation build scripts. Reverting the three commits restores the
previous installation guidance and navigation behavior.

[Forrest-ly]

总体评价

Tokenless 组件的文档改动质量良好。重新组织了 Quick Start 章节，将 ANOLISA CLI、RPM、npm 安装路径前置并补充了 adapter 启用示例，中英文版本保持一致。根目录 QUICKSTART.md 中 tokenless 相关内容仅增加了 adapter 示例一行，无破坏性变更。

审查结论

approve

详细意见

🟡 建议修改（不阻塞但推荐）

• [src/tokenless/README.md:108–109] 新增的 Quick Start 代码块中 curl -fsSL https://get.agentic-os.sh | bash 与 export PATH="$HOME/.local/bin:$PATH" 之间建议加一行空行或注释说明 PATH 设置的目的，让读者在复制时不会漏掉第二步。当前两行紧邻，初学者容易只复制第一行。
• [docs/user-guide/en/token-saving/tokenless/QUICKSTART.md:28] "If anolisa is already available, start with anolisa install tokenless." — 建议补充"可用"的判断标准（如 which anolisa 或 anolisa --version），降低歧义。

🟢 值得肯定

• 安装优先级（ANOLISA CLI > RPM > npm > 源码构建）在中英文文档中表述完全一致，层次清晰。
• anolisa adapter scan / enable / status 三步示例为 tokenless 用户提供了完整的 adapter 启用流程，比之前只提"deploy all adapters"更具操作性。
• PATH 恢复指引（export PATH="$HOME/.local/bin:$PATH"）解决了新用户安装后找不到命令的常见问题，中英文 QUICKSTART 均有补充。
• 原 npm Install 独立章节被合并到 Quick Start 中，消除了重复内容，结构更紧凑。
• 中英文文档同步更新，措辞和结构对齐良好。

[Forrest-ly]

总体评价

本轮新 commit 主要调整文档结构、安装入口和 website 构建脚本，tokenless 相关文档（src/tokenless/README*、docs/user-guide/*/token-saving/tokenless/QUICKSTART.md）的内容准确性良好，中英文同步，安装路径和 adapter 示例与上一轮保持一致。

审查结论

approve

详细意见

🟡 建议修改（不阻塞但推荐）

• [website/scripts/prepare-docs.mjs:1186–1190] isUserGuideQuickstart 会把所有 user-guide/*/quickstart.md 都设为 sidebar_position: 1。当前仓库里 user-entrypoint/ 下同时存在 copilot-shell/QUICKSTART.md 和 cosh-ng/QUICKSTART.md，PR 描述却只提到 "Tokenless, Copilot Shell, and AgentSecCore" 三份 quick start。这样会把两份 Copilot Shell 相关的 quick start（可能其中一份并非本意）都提升到首位，且多个条目共享 position 1 容易导致侧边栏排序不确定。建议把谓词收窄到明确的目标路径，或在 front matter 中为不同 quick start 显式指定 1、2、3 等不重复位置。

🟢 值得肯定

• src/tokenless/README* 把 CLI、RPM、npm 三种安装路径前置到 Quick Start，并保留源码构建作为开发者选项，结构更清晰。
• 中英文文档对安装优先级（CLI > RPM > npm > 源码）和 anolisa adapter scan/enable/status 三步流程的表述一致。
• docs/user-guide/*/token-saving/tokenless/QUICKSTART.md 补充了 export PATH 和 "已安装则跳过" 的说明，降低了新用户复制命令时的困惑。
• stripLocaleSwitchLinks() 只处理行首的 [English](...) / [中文版](...)，配合 check-links.mjs 的新规则，能把语言切换统一收敛到导航栏，行为一致。

[Forrest-ly]

Code Review — PR #2258 (commit 0d9f617)

总体结论：LGTM，无阻塞问题。 变更为文档 + 网站构建脚本，我把文档中的关键事实性声明逐条对照了 PR head 的代码，并在本地实际运行了修改过的构建脚本。

已验证（与代码一致）

• sec-core 为 ANOLISA 组件名、RPM 保留 agent-sec-core、契约要求 CLI ≥ 0.2.16、仅 Linux x86_64 system mode —— 与 src/agent-sec-core/.anolisa/component.toml（min_anolisa_version = "0.2.16"、arch = ["x86_64"]、modes = ["system"]、[backends.rpm] package = "agent-sec-core"）一致。
• AgentSight 契约 requires_arch = ["x86_64"]、modes = ["system"]、kernel ≥ 5.8 —— 与 agentsight.md 新需求表一致。
• agentsight.service 通过 Wants=/After=agentsight-enforcer.service 带起 enforcer；agentsight-start.sh 同时启动 trace + serve；安装只放置 unit、不 enable（Makefile 与 spec 的 %post 均无 enable）——与"安装不自启、主服务带起 enforcer"的描述一致。
• make build-all 目标存在且为默认目标；agent-sec-cli --version、anolisa status [COMPONENT]、anolisa adapter status、anolisa update self、serve --host/--port（默认 127.0.0.1:7396）均确认存在。
• sec-core adapter 列表 openclaw/hermes/qwencode/cosh/codex/qoder 与 component.toml 一致；tokenless 的 openclaw adapter 与 component.toml.in 一致；yum install tokenless 对应 spec Name: tokenless。
• 本地运行 node website/scripts/prepare-docs.mjs：73 EN + 73 ZH 文档全部生成成功；146 个生成文件中 [中文版]/[English] 内联切换链接全部被剥离，无残留；4 个 user-guide quickstart 均得到 sidebar_position: 1，installation 仍为 2。
• 正则单测确认：[中文版](...) · [Website](...) · 这类组合行不会被误剥离（根 README.md 不在站点文档集内，不受影响）。

建议（均不阻塞合并）

1. 中文首页范围符号不一致（website/src/pages/index.tsx:186）：hook（line 38）已改为 30～70%，但同页中文 proof 仍是 '30–70% 工具输出压缩*'（en dash）。若目标是中文统一用 ～，建议同时更新 line 186，否则同一页面两种范围符号并存。

2. 失效的 position 配置（website/scripts/prepare-docs.mjs:241）：documentPositions 中 'user-guide/user-entrypoint/cosh-ng/quickstart.md': 2 现在不可达（quickstart 规则恒返回 1）。建议删除，避免后续维护者误以为它还生效。

3. strip 不感知代码围栏（website/scripts/prepare-docs.mjs:117）：stripLocaleSwitchLinks 是行级正则，代码块内行首的 [English](...) 也会被删除（已用样例验证）。当前 docs/ 中此类链接都在第 3 行、无围栏内用例，所以没有实际损坏；但 makeMdxSafe 已有围栏状态跟踪，建议让 strip 复用同样的围栏感知，对未来文档更稳健。

4. CLI 错误文案与实际命令不符（非本 PR 引入，但与本文档流程直接相关）：src/anolisa/crates/anolisa-cli/src/commands/tier1/install/raw.rs:659（另见 145、845）提示 run 'anolisa self-update' and retry，而实际命令是 anolisa update self（本 PR 文档所用即正确命令）。旧 CLI 触发 min-version gate 时用户会看到一个不存在的命令名，建议后续在 CLI 侧修正。

5. systemd 路径的 Dashboard 暴露面（docs/user-guide/{en,zh}/agent-observability/agentsight.md:96-101）：0.0.0.0 暴露警告目前只针对手动 serve 示例，但 agentsight-start.sh 里 systemd 服务用的是 serve --host 0.0.0.0（serve 默认值是 127.0.0.1），即走推荐的 systemctl 路径时 Dashboard 同样监听所有网卡。建议在 systemd 小节补一句"服务自带的 Dashboard 默认监听所有网络接口，暴露到不可信网络前请先做防火墙限制"。这是本次建议中最有安全价值的一条。

6. 小瑕疵：docs/user-guide/zh/agent-observability/agentsight.md:100 "使用这种方式以前，需要先限制网络访问" 读起来略歧义，建议改为"在使用这种方式之前，需要先限制网络访问"；docs/QUICKSTART_zh.md:113 # Web Dashboard http://localhost:7396（双空格）与英文版 # Web Dashboard: http://localhost:7396（冒号）不一致。

[Forrest-ly]

Code review 完成：整体 LGTM，无阻塞问题。

已对照 PR head 代码验证全部关键事实声明（sec-core 组件契约、CLI ≥ 0.2.16 gate、x86_64 system mode、RPM 包名、agentsight systemd 依赖与启动行为、build-all 目标、adapter 列表、update self/status/adapter status 命令），并本地运行 prepare-docs.mjs 确认 146 个文档生成、内联语言链接全部剥离、quickstart sidebar_position 生效。

留有 6 条非阻塞建议（详见 PR 总体评论），其中两条值得跟进：

1. agentsight systemd 服务的 Dashboard 经 agentsight-start.sh 绑定 0.0.0.0，建议在文档 systemd 小节补充暴露面提示；
2. index.tsx 中文 hook 改为 30～70% 后，同页中文 proof（line 186）仍是 30–70%，建议统一。

[Forrest-ly]

总体评价

Tokenless 文档改动的结构更清晰，安装优先级与 adapter 启用示例一致，PATH 恢复指引也覆盖了默认安装目录不在当前 shell PATH 的场景。但 PR 将 npm install 路径提升到 Quick Start 中，而公开 npm registry 上并不存在 anolisa-tokenless 包，这会导致直接复制命令的用户失败。

审查结论

request changes

详细意见

🔴 必须修改（阻塞合并）

• [src/tokenless/README.md:124-129] / [src/tokenless/README_zh.md:81-86]
  Quick Start 将 npm install -g anolisa-tokenless 与 ANOLISA CLI、RPM、源码构建并列为支持路径，但当前仓库的 npm 包并不可用：
  • npm view anolisa-tokenless 返回 404；
  • src/tokenless/npm/package.json 中 "private": true，且 .npmrc 指向 registry.npmjs.org；
  • 可选依赖 @anolisa/tokenless-* 同样未在 npm registry 发布。
    在包未发布到可访问 registry 之前，不应把它作为 Quick Start 的正式安装入口。建议移除该路径，或补充"需发布/配置到可用 registry"的明确说明。

🟡 建议修改（不阻塞但推荐）

• [docs/user-guide/zh/token-saving/tokenless/QUICKSTART.md:31]
  与 Forrest-ly 已指出的英文版问题对应，"如果当前环境已经能运行 anolisa" 建议给出判断标准（如 which anolisa 或 anolisa --version），降低新用户歧义。
• [src/tokenless/README.md:111-116] / [src/tokenless/README_zh.md:69-72]
  与 docs/user-guide 的 QUICKSTART 保持一致，建议在 export PATH 与 anolisa install tokenless 之间加入 anolisa --version 验证步骤；同时 curl | bash 与 export PATH 两行紧邻，初学者容易只复制第一行，可加一行注释或空行说明。

🟢 值得肯定

• 中英文 README 的安装优先级（ANOLISA CLI > RPM > npm > 源码构建）表述一致，去掉了独立的 npm 安装章节后结构更紧凑。
• anolisa adapter scan / enable tokenless openclaw / status tokenless 三步示例完整，adapter 启用路径比旧版更清晰。
• PATH 恢复指引（export PATH="$HOME/.local/bin:$PATH"）同时覆盖了用户指南和 README，解决了默认安装后找不到命令的常见问题。

[yangdao479]

sec-core component.toml中， ANOLISA CLi最小支持版本是0.2.17

[yangdao479]

这里推荐先以普通用户执行 anolisa update self，但同一套安装文档提供的标准 CLI 安装入口是 sudo yum install anolisa。对于 RPM-owned 的 anolisa，run_self_update_with_deps() 在检测到当前用户不是 root 时会直接失败，并明确要求重跑 sudo anolisa update self；因此用户恰在旧 CLI 需要升级时，按这条推荐流程无法继续。

建议区分 CLI 的安装来源：用户目录/脚本安装使用 anolisa update self，RPM 安装使用 sudo anolisa update self（或 sudo yum update anolisa），并同步修正中英文 installation、顶层 QUICKSTART、AgentSecCore QUICKSTART/README 中新增的相同命令。

[yangdao479]

这里不应直接向用户暴露组件内部的 make build-cli。ANOLISA 已维护统一的源码构建与安装入口 ./scripts/build-all.sh --component sec-core，它负责完整构建并安装 sec-core；make build-cli 只处理 CLI wheel，既不是项目对外推荐入口，也不会完成各 Agent 集成资源的安装。

这也导致后文继续引用 ./openclaw-plugin/scripts/deploy.sh、./hermes-plugin/scripts/deploy.sh 和 ./qwen-code-extension/scripts/deploy.sh 等源码树相对路径。用户通过统一脚本完成源码安装后，不应依赖源码仓库或当前工作目录，而应使用安装后的集成入口。建议 QUICKSTART 统一改用 build-all.sh，并将各框架示例调整为安装后的脚本路径或 anolisa adapter enable；仓库内的 Make target 和源码树调试方式放到开发文档中。