Merge branch 'master' into feat/web-loader-plugin-inventory-settings

.agents/notes/implemented/process/2026-08-12-documentation-site-navigation-and-chrome.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-12-documentation-site-navigation-and-chrome.md
+2026-08-12-documentation-site-navigation-and-chrome.md: 03cd44b94f853725da33800e8c89886b1a657a0b
+2026-08-12-documentation-site-navigation-and-chrome.zh.md: d0972f909e648278cb3cecb7788705b228f4b675

.agents/notes/implemented/process/2026-08-12-documentation-site-navigation-and-chrome.md

@@ -0,0 +1,41 @@
+# Agent Note: Documentation-site navigation and repository chrome
+
+Status: implemented
+
+English | [中文](2026-08-12-documentation-site-navigation-and-chrome.zh.md)
+
+## Problem
+
+The reference sidebar rendered its 43 subsystem pages first, ahead of every other group: `sectionOrder` in the VitePress config listed no position for the subsystem groups, nor for the group holding the Python SDK page, so `indexOf` returned `-1` and sorted them ahead of the ordered sections. Clicking the `参考` navigation item landed on the architecture page whose own sidebar entry was link 44 of 62, 1549px down a 2478px sidebar — outside the viewport. Four subsystem pages carried `order` values already taken by other pages in the same section, resolved only by `Array.prototype.sort` stability and the order the manifest's arrays happened to be concatenated.
+
+The navigation bar named `/guide/` while the manifest published the guide's first page at `guide/quickstart.md`, so that item served a 404: written-down navigation targets drift from the routes the manifest publishes.
+
+Separately, every canonical page carries lines written for its GitHub reader — a language switcher under the heading, and for some, a repository badge — which the site projected verbatim even though its navigation bar already offers both.
+
+## Decision
+
+[website/docs.ts](../../../../website/docs.ts) owns section placement. `sections` declares the groups per locale, and `sectionSpec(locale, label)` returns a group's position and collapse behavior, throwing when a locale declares no placement for a label. A group absent from the declaration now fails the build instead of sorting silently to the top. Placement is per locale because the two sidebars name their groups independently, and a label both use — `SDK` — cannot hold one rank against `入门` and against `Guide` at once.
+
+Subsystem pages are grouped by concern — overview, core and scopes, sessions and persistence, model and context, execution and tools, policy and interaction, platform and access — and the six topical groups render collapsed until one holds the page being read. The groups sort last within the reference sidebar: expanded, they outnumber every other group combined, so anything placed after them is reachable only by scrolling past the whole list. Page `order` derives from array position rather than a hand-written number.
+
+`landingLink(locale, collection)` derives each navigation item's target from `orderedPages`, the same ordering the sidebar renders, so an item always opens its collection's first published page.
+
+`projectedPageContent` in [scripts/project-doc-site.ts](../../../../scripts/project-doc-site.ts) drops the language-switcher line and the repository badge. The switcher match is confined to the first eight lines so a tutorial that shows the convention still renders its example.
+
+The navigation-bar title is the DeepSeek wordmark inlined into `siteTitle`, which VitePress renders as HTML. Inlining is what lets the mark's `currentColor` fills follow the active theme; `themeConfig.logo` renders an `<img>`, which freezes the mark at the colors its file declares and would need one asset per theme. The sidebar scrollbar rests invisible and appears while scrolling, marked by a `data-` attribute rather than a class because Vue rewrites `class` wholesale when it patches the element.
+
+## Alternatives considered
+
+**A search tokenizer for Chinese queries.** Built and reverted. The premise — that MiniSearch leaves Chinese prose as untokenizable whole sentences — was tested against a term (`子代理`) that appears nowhere in the corpus; the Chinese pages write `Subagent` and `子 agent`. Measured against the unmodified index, `插件配置` returns 120 hits, `会话持久化` 85, `工作流` 28, `沙箱` 12, each ranking its own page first: `prefix: true` already reaches Chinese terms through the short tokens punctuation produces. Adjacent-character pairs grew the Chinese index from 1.23MB to 2.12MB for no gain. The attempt also surfaced a trap worth keeping: VitePress ships search-option functions to the browser through `Function.prototype.toString` and rebuilds them with `new Function`, so any such function that closes over a module-level constant throws in an empty scope and silently returns no results.
+
+**Placing the subsystem groups directly after `概念`.** Rejected: it restores the architecture page to the top but leaves generated reference, the Cordis API, and the cookbook below 43 rows.
+
+**Rewriting filename link text during projection.** The subsystem index table writes `[core.md](core.md)`, which reads as a repository file index on the site. `scripts/project-doc-site.spec.ts` asserts that exact row format, so the filenames are a deliberate convention rather than an oversight; changing what the site displays means changing the convention and its gate together, not working around them in the projector.
+
+## Consequences
+
+The reference sidebar measures 1452px with every subsystem group collapsed, against 2478px before, and the architecture page is its first entry. Section placement and collapse are declared in one manifest instead of split between the manifest and the config, and `scripts/project-doc-site.spec.ts` pins three invariants: every sidebar-owning page resolves a placement, an undeclared section is refused, and no two pages share an `order` within a section.
+
+Canonical Markdown is unchanged by the chrome stripping — the switcher and badge still serve GitHub readers. The cost is that the projector now knows two presentation conventions of the source corpus, which a page written with a different switcher wording would not match.
+
+The wordmark is a second copy of a mark that also lives in `apps/web/public/favicon.svg` and `packages/client/ui-primitives/src/FishLogo.tsx`, each carrying its own presentation. A change to the DeepSeek wordmark reaches the documentation site only by updating this copy.

.agents/notes/implemented/process/2026-08-12-documentation-site-navigation-and-chrome.zh.md

@@ -0,0 +1,41 @@
+# Agent Note: 文档站导航与仓库 chrome
+
+Status: implemented
+
+[English](2026-08-12-documentation-site-navigation-and-chrome.md) | 中文
+
+## 问题
+
+参考侧边栏把 43 个子系统页排在了所有其他分组之前：VitePress 配置中的 `sectionOrder` 既没有为子系统分组、也没有为承载 Python SDK 页的分组声明位置，`indexOf` 返回 `-1`，于是它们排到了所有已排序分区的前面。点击 `参考` 导航项落在架构页，而该页自己的侧边栏条目是 62 条中的第 44 条，位于 2478px 侧边栏的 1549px 处——在视口之外。四个子系统页所用的 `order` 值已被同一分区内的其他页占用，只靠 `Array.prototype.sort` 的稳定性和 manifest 数组恰好的拼接顺序才没有错乱。
+
+顶栏把 `入门` 指向 `/guide/`，而 manifest 已把入门首页发布在 `guide/quickstart.md`，该导航项因此返回 404：写死的导航目标会与 manifest 实际发布的路由脱节。
+
+另外，每个规范页面都带有写给 GitHub 读者的行——标题下的语言切换行，部分页面还有仓库徽章——站点原样投影了它们，尽管其导航栏已经提供了这两者。
+
+## 决定
+
+[website/docs.ts](../../../../website/docs.ts) 拥有分区位置。`sections` 按 locale 声明各分组，`sectionSpec(locale, label)` 返回分组的位置与折叠行为，当某 locale 未为该 label 声明位置时抛错。未出现在声明中的分组现在会让构建失败，而不是静默排到最前。位置按 locale 声明，是因为两侧侧边栏各自命名分组，而两侧共用的标签 `SDK` 无法同时相对 `入门` 和相对 `Guide` 取同一位次。
+
+子系统页按关注点分组——总览、内核与作用域、会话与持久化、模型与上下文、执行与工具、策略与交互、平台与接入——其中六个主题组保持折叠，直到某一组包含正在阅读的页面。这些分组排在参考侧边栏的最后：展开时它们的数量超过其余所有分组之和，因此排在它们之后的任何内容都只能靠滚过整个列表才能到达。页面 `order` 由数组位置推导，不再手写数字。
+
+`landingLink(locale, collection)` 依据 `orderedPages`——即侧边栏所用的同一套排序——推导每个导航项的目标，因此导航项始终打开该分区已发布的首个页面。
+
+[scripts/project-doc-site.ts](../../../../scripts/project-doc-site.ts) 中的 `projectedPageContent` 会丢弃语言切换行和仓库徽章。切换行的匹配被限制在前八行内，因此展示该约定的教程仍能渲染出它的示例。
+
+导航栏标题是内联进 `siteTitle` 的 DeepSeek 字标，VitePress 会将其按 HTML 渲染。内联正是让字标的 `currentColor` 填充跟随当前主题的原因；`themeConfig.logo` 渲染为 `<img>`，会把字标固定为文件声明的颜色，并且需要为每套主题各准备一份资源。侧边栏滚动条平时不可见，滚动时出现，通过 `data-` 属性而非 class 标记，因为 Vue 在 patch 该元素时会整体重写 `class`。
+
+## 考虑过的替代方案
+
+**为中文查询定制搜索分词器。** 已实现并撤回。其前提——MiniSearch 会把中文散文留作无法切分的整句——是用一个语料中根本不存在的词（`子代理`）验证的；中文页面写的是 `Subagent` 和 `子 agent`。在未改动的索引上实测，`插件配置` 返回 120 条命中、`会话持久化` 85 条、`工作流` 28 条、`沙箱` 12 条，且各自的页面均排在首位：`prefix: true` 已经能通过标点切出的短 token 命中中文词。相邻字符二元组把中文索引从 1.23MB 增至 2.12MB，却没有带来收益。该尝试还暴露出一个值得保留的陷阱：VitePress 通过 `Function.prototype.toString` 把搜索选项中的函数送到浏览器，再用 `new Function` 重建，因此任何闭包引用了模块级常量的此类函数都会在空作用域中抛错，并静默地返回零结果。
+
+**把子系统分组直接放在 `概念` 之后。** 已否决：这样能让架构页回到顶部，但生成参考、Cordis API 和开发手册仍处在 43 行之下。
+
+**在投影时重写文件名链接文字。** 子系统索引表写的是 `[core.md](core.md)`，在站点上读起来像仓库文件索引。`scripts/project-doc-site.spec.ts` 断言了该行的确切格式，因此这些文件名是刻意的约定而非疏漏；要改变站点显示的内容，就要连同该约定及其门禁一起改，而不是在投影器里绕开它们。
+
+## 影响
+
+在所有子系统分组折叠时，参考侧边栏高度为 1452px，此前为 2478px，且架构页是它的第一个条目。分区位置与折叠行为声明在同一份 manifest 中，不再分散于 manifest 与配置之间；`scripts/project-doc-site.spec.ts` 固定了三条不变式：每个拥有侧边栏的页面都能解析到位置、未声明的分区会被拒绝、同一分区内没有两个页面共用 `order`。
+
+剥离 chrome 不改动规范 Markdown——切换行与徽章仍服务于 GitHub 读者。代价是投影器现在知晓源语料的两项呈现约定，而采用不同切换行措辞的页面将不会被匹配到。
+
+字标是同一图形的第二份副本，另两份位于 `apps/web/public/favicon.svg` 和 `packages/client/ui-primitives/src/FishLogo.tsx`，各自承载自己的呈现方式。DeepSeek 字标的变更只有通过更新这份副本才能到达文档站。

docs/cordis-tutorial/index.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/index.md
-index.md: a10a0f93fde4f710af2ab14f74b854ee07d7c03f
-index.zh.md: fb2c4f0959eab8c7a072c44207943c31b0bed8ea
+index.md: dc9bc13c80885857d42bbc32532f678d8942a40d
+index.zh.md: 4bd3837d7df0c9bcc1d512e1505c0934b56cf0a7

docs/cordis-tutorial/index.md

@@ -8,6 +8,8 @@ The audience is agent developers. You do not need deep TypeScript experience; th
 
 If you want the condensed concept reference instead of a walkthrough, read the [Cordis primer](../cordis-primer.md). The exhaustive API reference lives in the generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) and the [Cordis core API](../cordis-api/context.md) pages.
 
+To write plugins for the harness itself — loaded from a `cordis.yml` and driven from the Web UI rather than the launcher below — start from [your first Harness plugin](../user/develop/basic/index.md).
+
 ## Setup
 
 You need a clone of this repository with dependencies installed; the [development guide](../development.md#setup-tutorial) lists the prerequisites. No API key is needed for this tutorial; every example runs keylessly.

docs/cordis-tutorial/index.zh.md

@@ -8,6 +8,8 @@ Cordis 是 DeepSeek Harness SDK 底层的插件框架：它是一个小型运行
 
 如果你想阅读精简的概念参考，而不是逐步实践，请参阅 [Cordis 入门](../cordis-primer.md)。详尽的 API 参考见[子系统页面](../subsystems/core.md)上生成的 `cordis-surface` 区块，以及 [Cordis 核心 API](../cordis-api/context.md)页面。
 
+如果你要为 harness 本身编写插件——由 `cordis.yml` 加载、在 Web UI 中驱动，而不是下面这个启动器——请从[第一个 Harness 插件](../user/develop/basic/index.md)开始。
+
 ## 准备工作
 
 你需要克隆本仓库并安装依赖；[开发指南](../development.md#setup-tutorial)列出了前置条件。本教程不需要 API 密钥；所有示例均可在无密钥环境中运行。

docs/user/develop/basic/index.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/index.md
-index.md: 71b5bd5ef5d296999420c40d3b8c9cf46c918841
-index.zh.md: 5dafe8bf0938337fa1f38634088acf00a2fcab46
+index.md: 494b7869be6ffdf5767fac260b36b2585305b516
+index.zh.md: 92b5ad4e876b31bc10d57a19d45b1bfdf2fdb9ba

docs/user/develop/basic/index.md

@@ -139,3 +139,4 @@ Function form is sufficient in most cases. Use class form when the plugin provid
 
 - [Build a tool](./tool.md) — learn the tool definition DSL
 - [Plugin configuration](./config.md) — accept user configuration
+- [Cordis tutorial](../../../cordis-tutorial/index.md) — the plugin framework underneath, built from a scratch directory with no API key

docs/user/develop/basic/index.zh.md

@@ -139,3 +139,4 @@ export default class MyService extends Service {
 
 - [开发一个工具](./tool.md) — 详细了解工具定义 DSL
 - [插件配置](./config.md) — 让插件接受用户配置
+- [Cordis 框架教程](../../../cordis-tutorial/index.md) — 底层的插件框架，在临时目录中动手构建，无需 API 密钥

docs/user/develop/framework/index.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/framework/index.md
-index.md: 85701ce281d92da0c805b39291179df73eb65f51
-index.zh.md: 871aa55ef81a7dcbfe3cbde5986244220ee32f98
+index.md: 8cc673148d7fec4f7d9b994907e17293bc3a6a97
+index.zh.md: 1a1f7feb8685e124babb182544bde332b52da42c

docs/user/develop/framework/index.md

@@ -134,3 +134,4 @@ effect cleaned up
 
 - [Services and dependencies](./service.md) — expose a capability to other plugins
 - [Event system](./events.md) — communicate between plugins
+- [Cordis tutorial](../../../cordis-tutorial/index.md) — the same lifecycle, services, and events built step by step against the Cordis runtime

docs/user/develop/framework/index.zh.md

@@ -134,3 +134,4 @@ effect cleaned up
 
 - [服务与依赖](./service.md) — 让插件向其他插件提供能力
 - [事件系统](./events.md) — 在插件之间通信
+- [Cordis 框架教程](../../../cordis-tutorial/index.md) — 在 Cordis 运行时上逐步搭出同一套生命周期、服务与事件

packages/client/ui-primitives/src/icons/index.tsx

@@ -31,6 +31,18 @@ export const IconSearchOutline16 = ({ size = 16, className }: IconProps) => (
   </svg>
 )
 
+/** ic_ds_globe_outline_14 — meridian globe (harness-only figma extract). */
+export const IconGlobeOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M7.00018 0.353516C10.6708 0.353535 13.6468 3.32958 13.6469 7.00018C13.6468 10.6708 10.6708 13.6468 7.00018 13.6469C3.32957 13.6468 0.353535 10.6708 0.353516 7.00018C0.353535 3.32957 3.32957 0.353531 7.00018 0.353516ZM5.44643 7.59661C5.49463 8.97506 5.70762 10.191 6.02136 11.0793C6.20141 11.5891 6.40328 11.9585 6.59898 12.1889C6.79501 12.4196 6.93213 12.454 7.00018 12.454C7.06822 12.454 7.20533 12.4197 7.40138 12.1889C7.59708 11.9585 7.79895 11.589 7.979 11.0793C8.29274 10.191 8.50574 8.97506 8.55394 7.59661H5.44643ZM1.57861 7.59661C1.80785 9.70467 3.2386 11.4509 5.1715 12.1388C5.07135 11.9317 4.97972 11.7098 4.89746 11.477C4.53084 10.4391 4.30224 9.0828 4.25357 7.59661H1.57861ZM9.74679 7.59661C9.69813 9.0828 9.46952 10.4391 9.1029 11.477C9.0206 11.7099 8.92818 11.9316 8.82797 12.1388C10.7613 11.4511 12.1925 9.70496 12.4218 7.59661H9.74679ZM5.1706 1.8616C3.23814 2.54963 1.80876 4.29604 1.5795 6.40376H4.25357C4.30224 4.91756 4.53083 3.56129 4.89746 2.5234C4.97968 2.29066 5.07051 2.0686 5.1706 1.8616ZM7.00018 1.54637C6.93213 1.54638 6.79503 1.5807 6.59898 1.81145C6.40332 2.04177 6.20139 2.41058 6.02136 2.92012C5.70754 3.80851 5.49461 5.02499 5.44643 6.40376H8.55394C8.50575 5.025 8.29282 3.80851 7.979 2.92012C7.79898 2.41059 7.59705 2.04177 7.40138 1.81145C7.20531 1.58067 7.06823 1.54637 7.00018 1.54637ZM8.82887 1.8616C8.92902 2.0687 9.02064 2.29053 9.1029 2.5234C9.46953 3.56129 9.69812 4.91756 9.74679 6.40376H12.4209C12.1916 4.29575 10.7618 2.54943 8.82887 1.8616Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
 /** ic_ds_settings_outline_14 */
 export const IconSettingsOutline14 = ({ size = 14, className }: IconProps) => (
   <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">

packages/client/ui-primitives/tests/icons.client.spec.tsx

@@ -16,8 +16,8 @@ const icons = Object.fromEntries(
 const iconNames = Object.keys(icons)
 
 describe('ic_ds_ icon set', () => {
-  it('exports the full icon set (46 deepsuite + 19 figma extracts + three product glyphs outside those sets)', () => {
-    expect(iconNames.length).toBe(68)
+  it('exports the full icon set (46 deepsuite + 20 figma extracts + three product glyphs outside those sets)', () => {
+    expect(iconNames.length).toBe(69)
   })
 
   it.each(iconNames)('%s renders an svg with currentColor fills and no hardcoded palette', (name) => {

packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx

@@ -23,8 +23,13 @@ import { CONVERSATION_NS as NS } from '../../locale.ts'
 /** Full row props: the toolview runtime share plus the standard locale seat. */
 type SearchRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
+const SEARCH_TITLES: Record<string, string> = {
+  grep: 'Grep',
+  glob: 'Glob',
+}
+
 /**
- * Search row: icon + Search · {summary} in the shared ToolRow chrome, with the
+ * Search row: icon + Grep/Glob · {summary} in the shared ToolRow chrome, with the
  * completed search's card as the row's collapsed-by-default card body (a capped
  * search's recovery footer rides below it, inside ToolRow). Registered under
  * both `grep` and `glob`; the derived model's `kind` decides the card shape. A
@@ -40,7 +45,7 @@ export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {
       variant={model.variant}
       toolName={toolName}
       icon={<IconSearchOutline16 size={14} />}
-      title={model.title}
+      title={SEARCH_TITLES[toolName] ?? model.title}
       // The result view's replacement title outranks the args-derived summary,
       // matching the terminal card's description precedence.
       summary={search?.title ?? model.summary}

packages/client/ui-tool/src/client/tool/toolviews/web-row.tsx

@@ -10,7 +10,7 @@
 // summary line alone.
 
 import type { Context } from '@deepseek-ai/cordis'
-import { IconBrowseOutline16, IconSearchOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconBrowseOutline16, IconGlobeOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ToolCallViewProps } from '../../contract/slots.ts'
 import { webCardModel } from '../models/web-card-model.ts'
@@ -35,7 +35,8 @@ const WEB_TITLES: Record<string, string> = {
 export function WebRow({ toolName, block, inspect, t }: WebRowProps) {
   const model = toolRowModel(toolName, block)
   const web = webCardModel(block)
-  const icon = toolName === 'web_fetch' ? <IconBrowseOutline16 size={14} /> : <IconSearchOutline16 size={14} />
+  // Web search uses a globe; local grep/glob keep the magnifier family.
+  const icon = toolName === 'web_fetch' ? <IconBrowseOutline16 size={14} /> : <IconGlobeOutline14 size={14} />
   return (
     <ToolRow
       t={t}

packages/client/ui-tool/tests/search-card.client.spec.tsx

@@ -246,7 +246,8 @@ describe('SearchRow keyed card', () => {
 
   it('collapses to the summary row; expanding reveals the grep card', () => {
     const view = render(<SearchRow {...rowProps(settledGrep(), 'grep')} />)
-    expect(view.getByText('Search')).toBeTruthy()
+    expect(view.getByText('Grep')).toBeTruthy()
+    expect(view.queryByText('Search')).toBeNull()
     // Collapsed: the card is not in the DOM until the row is expanded.
     expect(searchKindOf(view.container)).toBeNull()
     expect(view.queryByText(/const foo = 1/)).toBeNull()
@@ -259,6 +260,8 @@ describe('SearchRow keyed card', () => {
 
   it('expands to the glob path card', () => {
     const view = render(<SearchRow {...rowProps(settledGlob(), 'glob')} />)
+    expect(view.getByText('Glob')).toBeTruthy()
+    expect(view.queryByText('Search')).toBeNull()
     expect(searchKindOf(view.container)).toBeNull()
     toggleRow(view)
     expect(view.getByText('src/a.ts')).toBeTruthy()

packages/client/ui-tool/tests/web-card.client.spec.tsx

@@ -20,6 +20,7 @@ import type { ToolResultView } from '@deepseek-ai/dsh-api-remotes/client'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ToolCallOwnerProps } from '@deepseek-ai/dsh-client-ui-tool/client'
+import { IconGlobeOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import { webCardModel } from '../src/client/tool/models/web-card-model.ts'
 import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard } from '../src/client/tool/toolviews/GenericToolCard.tsx'
@@ -140,9 +141,11 @@ describe('chat row web body', () => {
   }
 
   it('the WebRow collapses to the summary row, expanding to the full search card', () => {
+    const globe = render(<IconGlobeOutline14 />).container.querySelector('svg')!.outerHTML
     const view = render(<WebRow {...rowProps(settledSearch(), 'web_search')} />)
     // Collapsed: the summary row alone, no card in the DOM.
     expect(view.getByText('Search')).toBeTruthy()
+    expect(view.container.querySelector('svg')?.outerHTML).toBe(globe)
     expect(view.queryByText('Titled')).toBeNull()
     expect(view.container.querySelector('[data-web]')).toBeNull()
     toggleRow(view)

scripts/project-doc-site.spec.ts

@@ -5,7 +5,7 @@ import { existsSync, globSync, mkdirSync, mkdtempSync, readFileSync, realpathSyn
 import { tmpdir } from 'node:os'
 import { basename, join, resolve } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
-import { docsPages, type DocsPage } from '../website/docs.ts'
+import { docsPages, landingLink, routeLink, sectionSpec, type DocsPage } from '../website/docs.ts'
 import {
   addProjectionFrontmatter, projectedPageContent, publishableImage, rewriteMarkdown,
 } from './project-doc-site.ts'
@@ -364,6 +364,63 @@ describe('docsPages locale routes', () => {
   })
 })
 
+describe('sidebar ordering', () => {
+  it('places every section a sidebar collection owns', () => {
+    for (const page of docsPages) {
+      if (page.sidebar === null) continue
+      expect(() => sectionSpec(page.locale, page.section), page.route).not.toThrow()
+    }
+  })
+
+  it('refuses a section with no declared placement', () => {
+    expect(() => sectionSpec('root', '数据结构'))
+      .toThrow('Sidebar section "数据结构" has no placement in the root locale.')
+  })
+
+  it('declares placements per locale rather than in one shared list', () => {
+    // `SDK` labels a group in both locales, so one shared list would have to
+    // rank it against `入门` and against `Guide` at the same position.
+    expect(sectionSpec('root', 'SDK').index).toBeGreaterThan(sectionSpec('root', '入门').index)
+    expect(sectionSpec('en', 'SDK').index).toBeGreaterThan(sectionSpec('en', 'Guide').index)
+    expect(() => sectionSpec('en', '入门')).toThrow()
+    expect(() => sectionSpec('root', 'Guide')).toThrow()
+  })
+
+  it('lands every navigation item on a page the manifest publishes', () => {
+    // The navigation bar named `/guide/` while the manifest published the guide's
+    // first page at `guide/quickstart.md`, so the item served a 404.
+    const collections = [
+      ['root', 'zh-guide'], ['root', 'zh-develop'], ['root', 'zh-reference'],
+      ['en', 'en-guide'], ['en', 'en-develop'], ['en', 'en-reference'],
+    ] as const
+    const published = new Set(docsPages.map(page => routeLink(page.route)))
+    for (const [locale, collection] of collections) {
+      expect(published, `${locale}/${collection}`).toContain(landingLink(locale, collection))
+    }
+  })
+
+  it('collapses the subsystem groups and leaves the smaller ones open', () => {
+    expect(sectionSpec('root', '执行与工具').collapsed).toBe(true)
+    expect(sectionSpec('en', 'Execution and tools').collapsed).toBe(true)
+    expect(sectionSpec('root', '概念').collapsed).toBeUndefined()
+  })
+
+  it('gives each page its own position within a section', () => {
+    // Sidebar entries sort by order alone, so a shared value leaves the two
+    // pages ranked by whichever manifest block happens to be concatenated
+    // first rather than by an intent the manifest states.
+    const taken = new Map<string, string>()
+    const collisions: string[] = []
+    for (const page of docsPages) {
+      const slot = `${page.locale}/${String(page.sidebar)}/${page.section}#${page.order}`
+      const holder = taken.get(slot)
+      if (holder === undefined) taken.set(slot, page.label)
+      else collisions.push(`${slot}: ${holder} / ${page.label}`)
+    }
+    expect(collisions).toEqual([])
+  })
+})
+
 describe('addProjectionFrontmatter', () => {
   it('adds frontmatter to an ordinary Markdown page', () => {
     expect(addProjectionFrontmatter('# Guide\n', { source: 'docs/guide.md' })).toBe(
@@ -411,6 +468,25 @@ describe('projectedPageContent', () => {
     expect(projectedPageContent(markdown, page('zh-guide'))).toBe(markdown)
   })
 
+  it('drops the language switcher the navigation bar already offers', () => {
+    expect(projectedPageContent('# Guide\n\nEnglish | [中文](./en/guide)\n\nBody.\n', page('zh-guide')))
+      .toBe('# Guide\n\nBody.\n')
+    expect(projectedPageContent('# 指南\n\n[English](./en/guide) | 中文\n\n正文。\n', page('zh-guide')))
+      .toBe('# 指南\n\n正文。\n')
+  })
+
+  it('drops the repository badge every page links from its footer', () => {
+    const badge = '[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness)'
+    expect(projectedPageContent(`# Guide\n\nBody.\n\n${badge}\n`, page('zh-guide')))
+      .toBe('# Guide\n\nBody.\n')
+  })
+
+  it('keeps a switcher-shaped line that is not the page header', () => {
+    // A tutorial showing the convention must still render the example.
+    const sample = '# Guide\n\nA\n\nB\n\nC\n\nD\n\nE\n\nEnglish | [中文](./x)\n'
+    expect(projectedPageContent(sample, page('zh-guide'))).toBe(sample)
+  })
+
   it('rejects a locale home source without frontmatter', () => {
     expect(() => projectedPageContent('# Harness\n', page(null)))
       .toThrow('locale home source "docs/index.zh.md" must start with YAML frontmatter')

scripts/project-doc-site.ts

@@ -292,6 +292,37 @@ export function addProjectionFrontmatter(markdown: string, page: Pick<DocsPage,
   return `---\n${fields}\n---\n\n${markdown}`
 }
 
+/** The switcher line a canonical page carries so its GitHub reader can reach the other language. */
+const LANGUAGE_SWITCHER = /^(?:English \| \[中文\]\([^)]*\)|\[English\]\([^)]*\) \| 中文)$/
+
+/** The repository badge a canonical page carries for its GitHub reader. */
+const REPOSITORY_BADGE = /^\[!\[[^\]]*\]\(https:\/\/img\.shields\.io\/[^)]*\)\]\([^)]*\)$/
+
+/**
+ * Drop the lines that address a canonical page's GitHub reader.
+ *
+ * The site carries a locale switcher in its navigation bar and links the
+ * repository from every page, so projecting these lines would repeat both — the
+ * switcher as the first element under each heading.
+ *
+ * @param markdown Rewritten canonical Markdown content.
+ * @returns The content without the switcher line or the repository badge.
+ */
+function withoutRepositoryChrome(markdown: string): string {
+  const lines = markdown.split('\n')
+  const switcher = lines.findIndex(line => LANGUAGE_SWITCHER.test(line))
+  // Only the switcher introducing the page qualifies; further down the same
+  // text is prose or a sample rather than the page's own header.
+  if (switcher !== -1 && switcher < 8) {
+    lines.splice(switcher, lines[switcher + 1] === '' ? 2 : 1)
+  }
+  const badge = lines.findLastIndex(line => REPOSITORY_BADGE.test(line))
+  if (badge !== -1) {
+    lines.splice(lines[badge - 1] === '' ? badge - 1 : badge, lines[badge - 1] === '' ? 2 : 1)
+  }
+  return lines.join('\n')
+}
+
 /**
  * Select the Markdown rendered for one published page.
  *
@@ -300,7 +331,7 @@ export function addProjectionFrontmatter(markdown: string, page: Pick<DocsPage,
  * @returns Full Markdown for ordinary pages or frontmatter-only Markdown for a locale home page.
  */
 export function projectedPageContent(markdown: string, page: DocsPage): string {
-  if (page.sidebar !== null) return markdown
+  if (page.sidebar !== null) return withoutRepositoryChrome(markdown)
   if (!markdown.startsWith('---\n')) {
     throw new Error(`project-doc-site: locale home source ${JSON.stringify(page.source)} must start with YAML frontmatter.`)
   }

website/.vitepress/config.ts

@@ -1,52 +1,34 @@
 /** VitePress configuration for the locally projected documentation site. */
 
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
 import type { DefaultTheme, PageData } from 'vitepress'
 import type { ViteDevServer } from 'vite'
 import { withMermaid } from 'vitepress-plugin-mermaid'
-import { docsPages, type DocsPage } from '../docs.ts'
+import { landingLink, orderedPages, routeLink, sectionSpec, type DocsLocale, type DocsPage } from '../docs.ts'
 import { docsSourceFiles, projectDocs } from '../../scripts/project-doc-site.ts'
 
 projectDocs()
 
-const sectionOrder = [
-  '入门',
-  '基础',
-  '框架能力',
-  '实战',
-  'Cordis 教程',
-  '概念',
-  '生成参考',
-  'Cordis API',
-  '数据结构',
-  '开发手册',
-  'Guide',
-  'Basics',
-  'Framework',
-  'Practice',
-  'Cordis tutorial',
-  'Concepts',
-  'Generated reference',
-  'Cordis Core API',
-  'Data structures',
-  'Cookbook',
-]
-
-function sidebar(collection: DocsPage['sidebar']): DefaultTheme.SidebarItem[] {
-  const pages = docsPages.filter(page => page.sidebar === collection)
-  const sections = new Map<string, DocsPage[]>()
-  for (const page of pages) {
-    const entries = sections.get(page.section) ?? []
+function sidebar(locale: DocsLocale, collection: NonNullable<DocsPage['sidebar']>): DefaultTheme.SidebarItem[] {
+  // `orderedPages` already sorts by section placement, so insertion order
+  // carries the group order and each group keeps its pages in sequence.
+  const groups = new Map<string, DocsPage[]>()
+  for (const page of orderedPages(locale, collection)) {
+    const entries = groups.get(page.section) ?? []
     entries.push(page)
-    sections.set(page.section, entries)
+    groups.set(page.section, entries)
   }
-  return [...sections.entries()]
-    .sort(([left], [right]) => sectionOrder.indexOf(left) - sectionOrder.indexOf(right))
-    .map(([text, entries]) => ({
+  return [...groups.entries()].map(([text, entries]) => {
+    const { collapsed } = sectionSpec(locale, text)
+    return {
       text,
-      items: entries
-        .sort((left, right) => left.order - right.order)
-        .map(page => ({ text: page.label, link: `/${page.route.replace(/(?:index)?\.md$/, '')}` })),
-    }))
+      // A present `collapsed` is what makes the default theme render the
+      // group as collapsible at all, so an open group must omit the key.
+      ...(collapsed === undefined ? {} : { collapsed }),
+      items: entries.map(page => ({ text: page.label, link: routeLink(page.route) })),
+    }
+  })
 }
 
 function watchCanonicalDocs(server: ViteDevServer): void {
@@ -107,10 +89,102 @@ const sharedTheme: Pick<DefaultTheme.Config, 'search' | 'socialLinks' | 'editLin
   },
 }
 
+/** Site base path, carrying the leading and trailing slashes VitePress requires. */
+const base = process.env.DOCS_BASE ?? '/'
+
+/**
+ * The DeepSeek wordmark, inlined so its `currentColor` fills follow the active
+ * theme. An `<img>` would freeze the mark at the colors the file declares.
+ */
+const wordmark = readFileSync(resolve(import.meta.dirname, '../public/wordmark.svg'), 'utf8')
+  .trim()
+  .replace('<svg ', '<svg class="dsh-wordmark" ')
+
+/**
+ * Styles the default theme does not provide, carried inline because the site
+ * runs the stock theme with no theme directory of its own.
+ *
+ * The navigation-bar lockup pairs with `siteTitle`. The scrollbar rules replace
+ * the sidebar's platform bar, which reserves 15px of a 265px column and draws a
+ * track the rest of the navigation has no border for; `scrollbarScript` supplies
+ * the marker that reveals the thumb. Chrome drops `::-webkit-scrollbar` once
+ * `scrollbar-width` is set to anything but `auto`, so the standard properties
+ * stay behind a query only Firefox answers.
+ */
+const siteStyle = `
+.dsh-lockup { display: inline-flex; align-items: center; gap: 8px; min-width: 0; }
+.dsh-wordmark { display: block; height: 22px; width: auto; color: var(--vp-c-text-1); }
+.dsh-tag {
+  display: inline-flex;
+  align-items: center;
+  border: 1px solid var(--vp-c-brand-soft);
+  border-radius: 999px;
+  padding: 1px 9px;
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 18px;
+  white-space: nowrap;
+  color: var(--vp-c-brand-1);
+}
+
+.VPSidebar::-webkit-scrollbar { width: 6px; }
+.VPSidebar::-webkit-scrollbar-track { background: transparent; }
+.VPSidebar::-webkit-scrollbar-thumb {
+  background-color: transparent;
+  border-radius: 3px;
+  transition: background-color 0.3s;
+}
+.VPSidebar[data-scrolling]::-webkit-scrollbar-thumb { background-color: var(--vp-c-text-3); }
+@supports not selector(::-webkit-scrollbar) {
+  .VPSidebar { scrollbar-width: thin; scrollbar-color: transparent transparent; }
+  .VPSidebar[data-scrolling] { scrollbar-color: var(--vp-c-text-3) transparent; }
+}
+`
+
+/**
+ * Mark the sidebar while it scrolls, so its scrollbar rests invisible.
+ *
+ * A sized `::-webkit-scrollbar` opts the element out of the platform's
+ * self-hiding overlay bar, leaving one painted at all times; nothing in CSS
+ * reports that an element is scrolling. The listener captures instead of
+ * bubbling because scroll events do not bubble, and marks a `data-` attribute
+ * rather than a class because Vue rewrites `class` wholesale when it patches
+ * the element.
+ */
+const scrollbarScript = `
+(() => {
+  let idle
+  addEventListener('scroll', (event) => {
+    const target = event.target
+    if (!(target instanceof Element) || !target.classList.contains('VPSidebar')) return
+    target.dataset.scrolling = ''
+    clearTimeout(idle)
+    idle = setTimeout(() => delete target.dataset.scrolling, 800)
+  }, true)
+})()
+`
+
+/**
+ * Navigation-bar title: the DeepSeek wordmark and the release-stage tag.
+ * VitePress renders `siteTitle` as HTML.
+ *
+ * @param previewTag - Localized release-stage label.
+ * @returns Markup placed beside the navigation-bar home link.
+ */
+function siteTitle(previewTag: string): string {
+  return `<span class="dsh-lockup">${wordmark}<span class="dsh-tag">${previewTag}</span></span>`
+}
+
 export default withMermaid({
   title: 'DeepSeek Harness',
   description: '用于构建 Agent Harness 的插件化 SDK',
-  base: process.env.DOCS_BASE ?? '/',
+  base,
+  head: [
+    // VitePress leaves head hrefs untouched, so the base belongs here explicitly.
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: `${base}favicon.svg` }],
+    ['style', {}, siteStyle],
+    ['script', {}, scrollbarScript],
+  ],
   cleanUrls: true,
   srcDir: '.generated',
   cacheDir: '.cache',
@@ -120,15 +194,16 @@ export default withMermaid({
       label: '简体中文',
       lang: 'zh-CN',
       themeConfig: {
+        siteTitle: siteTitle('技术预览'),
         nav: [
-          { text: '入门', link: '/guide/', activeMatch: '^/guide/' },
-          { text: '开发', link: '/develop/basic/', activeMatch: '^/develop/' },
-          { text: '参考', link: '/reference/', activeMatch: '^/reference/' },
+          { text: '入门', link: landingLink('root', 'zh-guide'), activeMatch: '^/guide/' },
+          { text: '开发', link: landingLink('root', 'zh-develop'), activeMatch: '^/develop/' },
+          { text: '参考', link: landingLink('root', 'zh-reference'), activeMatch: '^/reference/' },
         ],
         sidebar: {
-          '/guide/': sidebar('zh-guide'),
-          '/develop/': sidebar('zh-develop'),
-          '/reference/': sidebar('zh-reference'),
+          '/guide/': sidebar('root', 'zh-guide'),
+          '/develop/': sidebar('root', 'zh-develop'),
+          '/reference/': sidebar('root', 'zh-reference'),
         },
         outline: { label: '本页目录' },
         docFooter: { prev: '上一篇', next: '下一篇' },
@@ -146,15 +221,16 @@ export default withMermaid({
       lang: 'en-US',
       link: '/en/',
       themeConfig: {
+        siteTitle: siteTitle('Preview'),
         nav: [
-          { text: 'Guide', link: '/en/guide/', activeMatch: '^/en/guide/' },
-          { text: 'Develop', link: '/en/develop/basic/', activeMatch: '^/en/develop/' },
-          { text: 'Reference', link: '/en/reference/', activeMatch: '^/en/reference/' },
+          { text: 'Guide', link: landingLink('en', 'en-guide'), activeMatch: '^/en/guide/' },
+          { text: 'Develop', link: landingLink('en', 'en-develop'), activeMatch: '^/en/develop/' },
+          { text: 'Reference', link: landingLink('en', 'en-reference'), activeMatch: '^/en/reference/' },
         ],
         sidebar: {
-          '/en/guide/': sidebar('en-guide'),
-          '/en/develop/': sidebar('en-develop'),
-          '/en/reference/': sidebar('en-reference'),
+          '/en/guide/': sidebar('en', 'en-guide'),
+          '/en/develop/': sidebar('en', 'en-develop'),
+          '/en/reference/': sidebar('en', 'en-reference'),
         },
         editLink: {
           pattern: ({ frontmatter }: PageData) => {
@@ -171,6 +247,9 @@ export default withMermaid({
     },
   },
   vite: {
+    // `srcDir` puts the Vite root inside the disposable generated tree, whose
+    // own `public/` no tracked asset can live in.
+    publicDir: resolve(import.meta.dirname, '../public'),
     plugins: [
       {
         name: 'deepseek-harness-doc-projector',

website/docs.ts

@@ -11,7 +11,7 @@
 export type DocsLocale = 'root' | 'en'
 
 /** Sidebar collection rendered for one locale and top-level module. */
-type DocsSidebar =
+export type DocsSidebar =
   | 'zh-guide'
   | 'zh-develop'
   | 'zh-reference'
@@ -133,9 +133,9 @@ const homeAndGuide = pairedPages([
   {
     source: 'docs/user/guide/python-sdk.md',
     route: 'guide/python-sdk.md',
-    label: { root: 'Python SDK', en: 'Python SDK' },
+    label: { root: 'Python', en: 'Python' },
     sidebar: { root: 'zh-guide', en: 'en-guide' },
-    section: { root: '其他接口', en: 'Other interfaces' },
+    section: { root: 'SDK', en: 'SDK' },
     order: 1,
   },
 ])
@@ -144,7 +144,7 @@ const develop = pairedPages([
   {
     source: 'docs/user/develop/basic/index.md',
     route: 'develop/basic/index.md',
-    label: { root: '第一个插件', en: 'First plugin' },
+    label: { root: '第一个 Harness 插件', en: 'Your first Harness plugin' },
     sidebar: { root: 'zh-develop', en: 'en-develop' },
     section: { root: '基础', en: 'Basics' },
     order: 1,
@@ -219,7 +219,7 @@ const develop = pairedPages([
 ])
 
 const cordisTutorial = pairedPages(([
-  ['index.md', 'Cordis 教程', 'Cordis tutorial'],
+  ['index.md', '总览', 'Overview'],
   ['01-first-plugin.md', '1. 第一个插件', '1. Your first plugin'],
   ['02-lifecycle-and-effects.md', '2. 生命周期与副作用', '2. Lifecycle and effects'],
   ['03-services.md', '3. 服务', '3. Services'],
@@ -232,7 +232,7 @@ const cordisTutorial = pairedPages(([
   route: `develop/cordis-tutorial/${file}`,
   label: { root: rootLabel, en: enLabel },
   sidebar: { root: 'zh-develop', en: 'en-develop' },
-  section: { root: 'Cordis 教程', en: 'Cordis tutorial' },
+  section: { root: 'Cordis 框架教程', en: 'Cordis framework tutorial' },
   order,
   ...(file === 'index.md' ? { sourceAliases: ['docs/cordis-tutorial'] } : {}),
 })))
@@ -248,55 +248,84 @@ const cordisPrimerReference = pairedPages([
   },
 ])
 
-const subsystemsReference = pairedPages(([
-  ['README.md', '子系统', 'Subsystems', 0],
-  ['core.md', '核心', 'Core', 1],
-  ['scope.md', '作用域', 'Scopes', 2],
-  ['typert.md', 'TypeRT', 'TypeRT', 39],
-  ['session.md', '会话', 'Sessions', 3],
-  ['session-query.md', '会话查询', 'Session query', 4],
-  ['session-reference.md', '会话引用', 'Session references', 5],
-  ['session-title.md', '会话标题', 'Session titles', 6],
-  ['settings.md', '用户设置', 'User settings', 7],
-  ['credentials.md', '用户凭据', 'User credentials', 8],
-  ['system-prompt.md', '系统提示词', 'System prompts', 9],
-  ['tools.md', '工具', 'Tools', 10],
-  ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 11],
-  ['token-meter.md', 'Token 计量', 'Token metering', 12],
-  ['bash.md', 'Bash 执行', 'Bash execution', 13],
-  ['subprocess.md', '子进程', 'Subprocesses', 14],
-  ['tasks.md', '后台任务', 'Background tasks', 15],
-  ['filesystem.md', '文件系统', 'Filesystem', 16],
-  ['lsp.md', 'LSP 导航', 'LSP navigation', 17],
-  ['code-runtime.md', '代码运行时', 'Code runtime', 18],
-  ['compaction.md', '上下文压缩', 'Compaction', 19],
-  ['subagent.md', '子代理', 'Subagents', 20],
-  ['workflow.md', '工作流', 'Workflows', 21],
-  ['skills.md', '技能', 'Skills', 22],
-  ['approval.md', '审批', 'Approvals', 23],
-  ['permission.md', '权限预设', 'Permission presets', 24],
-  ['plan.md', '计划模式', 'Plan mode', 25],
-  ['user-interaction.md', '用户交互', 'User interaction', 26],
-  ['sandbox.md', '沙箱', 'Sandboxing', 27],
-  ['web.md', 'Web 访问', 'Web access', 28],
-  ['spill.md', 'Spill 存储', 'Spill storage', 29],
-  ['persistence.md', '会话持久化', 'Session persistence', 30],
-  ['storage.md', '存储', 'Storage', 31],
-  ['workspace.md', '工作区', 'Workspaces', 32],
-  ['http-server.md', 'HTTP 服务器', 'HTTP server', 33],
-  ['client-modules.md', '客户端模块', 'Client modules', 34],
-  ['invariants.md', '运行时不变式', 'Runtime invariants', 36],
-  ['session-projection.md', '会话投影', 'Session projections', 37],
-  ['telemetry.md', '遥测', 'Telemetry', 38],
-] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
-  source: `docs/subsystems/${file}`,
-  route: file === 'README.md' ? 'reference/subsystems/index.md' : `reference/subsystems/${file}`,
-  label: { root: rootLabel, en: enLabel },
-  sidebar: { root: 'zh-reference', en: 'en-reference' },
-  section: { root: '子系统', en: 'Subsystems' },
-  order,
-  ...(file === 'README.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
-})))
+/**
+ * Subsystem pages grouped by the concern they document, as `[Chinese section,
+ * English section, pages]`. One flat list of every subsystem pushed the rest of
+ * the reference sidebar below the fold.
+ */
+const subsystemGroups = [
+  ['总览', 'Overview', [
+    ['README.md', '子系统', 'Subsystems'],
+  ]],
+  ['内核与作用域', 'Core and scopes', [
+    ['core.md', '核心', 'Core'],
+    ['scope.md', '作用域', 'Scopes'],
+    ['invariants.md', '运行时不变式', 'Runtime invariants'],
+  ]],
+  ['会话与持久化', 'Sessions and persistence', [
+    ['session.md', '会话', 'Sessions'],
+    ['session-query.md', '会话查询', 'Session query'],
+    ['session-reference.md', '会话引用', 'Session references'],
+    ['session-title.md', '会话标题', 'Session titles'],
+    ['session-projection.md', '会话投影', 'Session projections'],
+    ['persistence.md', '会话持久化', 'Session persistence'],
+    ['spill.md', 'Spill 存储', 'Spill storage'],
+    ['telemetry.md', '遥测', 'Telemetry'],
+  ]],
+  ['模型与上下文', 'Model and context', [
+    ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming'],
+    ['token-meter.md', 'Token 计量', 'Token metering'],
+    ['system-prompt.md', '系统提示词', 'System prompts'],
+    ['compaction.md', '上下文压缩', 'Compaction'],
+  ]],
+  ['执行与工具', 'Execution and tools', [
+    ['tools.md', '工具', 'Tools'],
+    ['bash.md', 'Bash 执行', 'Bash execution'],
+    ['subprocess.md', '子进程', 'Subprocesses'],
+    ['pty.md', 'PTY 会话', 'PTY sessions'],
+    ['tasks.md', '后台任务', 'Background tasks'],
+    ['filesystem.md', '文件系统', 'Filesystem'],
+    ['lsp.md', 'LSP 导航', 'LSP navigation'],
+    ['code-runtime.md', '代码运行时', 'Code runtime'],
+    ['web.md', 'Web 访问', 'Web access'],
+    ['skills.md', '技能', 'Skills'],
+    ['workflow.md', '工作流', 'Workflows'],
+    ['subagent.md', '子代理', 'Subagents'],
+  ]],
+  ['策略与交互', 'Policy and interaction', [
+    ['approval.md', '审批', 'Approvals'],
+    ['permission.md', '权限预设', 'Permission presets'],
+    ['sandbox.md', '沙箱', 'Sandboxing'],
+    ['plan.md', '计划模式', 'Plan mode'],
+    ['user-interaction.md', '用户交互', 'User interaction'],
+    ['commands.md', '命令', 'Human commands'],
+    ['goal.md', '目标', 'Goals'],
+    ['schedule.md', '定时提醒', 'Scheduled reminders'],
+  ]],
+  ['平台与接入', 'Platform and access', [
+    ['http-server.md', 'HTTP 服务器', 'HTTP server'],
+    ['typert.md', 'TypeRT', 'TypeRT'],
+    ['client-modules.md', '客户端模块', 'Client modules'],
+    ['storage.md', '存储', 'Storage'],
+    ['workspace.md', '工作区', 'Workspaces'],
+    ['settings.md', '用户设置', 'User settings'],
+    ['credentials.md', '用户凭据', 'User credentials'],
+  ]],
+] as const
+
+const subsystemsReference = subsystemGroups.flatMap(([rootSection, enSection, files]) => pairedPages(
+  files.map(([file, rootLabel, enLabel], order): PairedPage => ({
+    source: `docs/subsystems/${file}`,
+    route: file === 'README.md' ? 'reference/subsystems/index.md' : `reference/subsystems/${file}`,
+    label: { root: rootLabel, en: enLabel },
+    sidebar: { root: 'zh-reference', en: 'en-reference' },
+    section: { root: rootSection, en: enSection },
+    order,
+    // Subsystem pages carry long third-level sections a two-level outline reaches.
+    outline: [2, 3],
+    ...(file === 'README.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
+  })),
+))
 
 const reference = [
   ...pairedPages(([
@@ -359,19 +388,6 @@ const reference = [
     section: { root: 'Cordis API', en: 'Cordis Core API' },
     order: order + 5,
   }))),
-  ...pairedPages(([
-    ['goal.md', '目标', 'Goals', 14],
-    ['schedule.md', '定时提醒', 'Scheduled reminders', 15],
-    ['pty.md', 'PTY 会话', 'PTY sessions', 26],
-    ['commands.md', '命令', 'Human commands', 38],
-  ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
-    source: `docs/subsystems/${file}`,
-    route: `reference/subsystems/${file}`,
-    label: { root: rootLabel, en: enLabel },
-    sidebar: { root: 'zh-reference', en: 'en-reference' },
-    section: { root: '子系统', en: 'Subsystems' },
-    order,
-  }))),
   ...pairedPages(([
     ['adding-a-package.md', '新增 Package', 'Adding a package'],
     ['adding-a-tool.md', '新增 Tool', 'Adding a tool'],
@@ -395,6 +411,64 @@ const reference = [
   }]),
 ]
 
+/** A sidebar group, matched to pages by `label`. */
+export interface DocsSection {
+  /** Group heading, equal to the `section` field of every page it holds. */
+  label: string
+  /** Render the group collapsed until it holds the page being read. */
+  collapsed?: boolean
+}
+
+/**
+ * Every sidebar group, in the order its locale renders it.
+ *
+ * The subsystem groups collapse because together they outnumber the rest of the
+ * reference sidebar; expanded, they push every other group below the fold.
+ */
+const sections: Record<DocsLocale, readonly DocsSection[]> = {
+  root: [
+    { label: '入门' }, { label: 'SDK' },
+    { label: '基础' }, { label: '框架能力' }, { label: '实战' }, { label: 'Cordis 框架教程' },
+    { label: '概念' }, { label: '生成参考' }, { label: 'Cordis API' }, { label: '开发手册' },
+    { label: '总览' },
+    { label: '内核与作用域', collapsed: true },
+    { label: '会话与持久化', collapsed: true },
+    { label: '模型与上下文', collapsed: true },
+    { label: '执行与工具', collapsed: true },
+    { label: '策略与交互', collapsed: true },
+    { label: '平台与接入', collapsed: true },
+  ],
+  en: [
+    { label: 'Guide' }, { label: 'SDK' },
+    { label: 'Basics' }, { label: 'Framework' }, { label: 'Practice' }, { label: 'Cordis framework tutorial' },
+    { label: 'Concepts' }, { label: 'Generated reference' }, { label: 'Cordis Core API' }, { label: 'Cookbook' },
+    { label: 'Overview' },
+    { label: 'Core and scopes', collapsed: true },
+    { label: 'Sessions and persistence', collapsed: true },
+    { label: 'Model and context', collapsed: true },
+    { label: 'Execution and tools', collapsed: true },
+    { label: 'Policy and interaction', collapsed: true },
+    { label: 'Platform and access', collapsed: true },
+  ],
+}
+
+/**
+ * Placement and collapse behavior of one sidebar group.
+ *
+ * @param locale - Route tree whose sidebar is being built.
+ * @param label - Section label carried by the pages in the group.
+ * @returns The declared group, plus its zero-based position in the locale.
+ * @throws When the locale declares no placement for the label. Ranking by list
+ *   membership alone would sort an undeclared group silently ahead of every
+ *   declared one.
+ */
+export function sectionSpec(locale: DocsLocale, label: string): DocsSection & { index: number } {
+  const declared = sections[locale]
+  const section = declared.find(candidate => candidate.label === label)
+  if (section === undefined) throw new Error(`Sidebar section "${label}" has no placement in the ${locale} locale.`)
+  return { ...section, index: declared.indexOf(section) }
+}
+
 /** Every canonical page published by the documentation website. */
 export const docsPages: DocsPage[] = [
   ...homeAndGuide,
@@ -404,3 +478,47 @@ export const docsPages: DocsPage[] = [
   ...subsystemsReference,
   ...reference,
 ]
+
+/**
+ * Pages of one sidebar collection, in the order the sidebar lists them.
+ *
+ * @param locale - Route tree whose sidebar is being built.
+ * @param collection - Sidebar collection to read.
+ * @returns The collection's pages, ordered by section placement then by `order`.
+ */
+export function orderedPages(locale: DocsLocale, collection: DocsSidebar): DocsPage[] {
+  return docsPages
+    .filter(page => page.locale === locale && page.sidebar === collection)
+    .sort((left, right) => (
+      sectionSpec(locale, left.section).index - sectionSpec(locale, right.section).index
+      || left.order - right.order
+    ))
+}
+
+/**
+ * Site-relative link for a published route.
+ *
+ * @param route - Manifest route, including its `.md` suffix.
+ * @returns The link VitePress serves the route at.
+ */
+export function routeLink(route: string): string {
+  return `/${route.replace(/(?:index)?\.md$/, '')}`
+}
+
+/**
+ * Where a top-level navigation item lands.
+ *
+ * The target is derived rather than written down: a collection whose first page
+ * is renamed or reordered would otherwise leave the navigation bar pointing at
+ * a route the manifest no longer publishes.
+ *
+ * @param locale - Route tree the navigation item belongs to.
+ * @param collection - Sidebar collection the item opens.
+ * @returns Site-relative link of the collection's first page.
+ * @throws When the collection publishes no page.
+ */
+export function landingLink(locale: DocsLocale, collection: DocsSidebar): string {
+  const first = orderedPages(locale, collection)[0]
+  if (first === undefined) throw new Error(`Sidebar collection "${collection}" publishes no page.`)
+  return routeLink(first.route)
+}