dsh-modern-web-guidance 0.4.0 → 0.4.1

package/README.md

@@ -27,8 +27,23 @@
   <a href="https://www.npmjs.com/package/dsh-modern-web-guidance"><img alt="npm" src="https://img.shields.io/npm/v/dsh-modern-web-guidance"></a>
   <img alt="Guides" src="https://img.shields.io/badge/guides-208-2563eb">
   <img alt="DSH plugin" src="https://img.shields.io/badge/DSH-plugin-0d9488">
+  <a href="https://www.npmjs.com/package/dsh-modern-web-guidance"><img alt="npm downloads" src="https://img.shields.io/npm/dm/dsh-modern-web-guidance"></a>
+  <a href="https://github.com/metapeka/dsh-modern-web-guidance/releases"><img alt="release" src="https://img.shields.io/github/v/release/metapeka/dsh-modern-web-guidance?label=release"></a>
 </p>
 
+<details>
+<summary>📑 Contents</summary>
+
+**Start here** · [What you get](#what-you-get) · [Install](#install) · [How to use](#how-to-use) · [Which tool when](#which-tool-when)
+
+**Understand it** · [vs Google's package](#vs-google) · [How search works](#how-search-works) · [Catalog map](#catalog-map) · [Experimental guides](#experimental-guides)
+
+**Operate it** · [Security and limits](#security-and-limits) · [Usage stats](#usage-stats) · [Sidebar panel](#sidebar-panel) · [Configuration](#configuration) · [Updating the corpus](#updating-the-guide-corpus)
+
+**Everything else** · [FAQ](#faq) · [Roadmap](#roadmap) · [Docs map](#docs-map) · [Development](#development) · [Publishing](#publishing) · [License](#attribution-and-license)
+
+</details>
+
 ---
 
 Coding models default to legacy web patterns because that is what their training data contains. This plugin puts 208
@@ -39,7 +54,9 @@ effects, `:has()`, passkeys, `fetchpriority`, …) instead of a JavaScript worka
 Everything runs locally: the guides ship inside the package, search is computed in-process, and there are no network
 calls. Usage counters have existed since 0.2.0, but they never leave the machine — see [Usage stats](#usage-stats).
 
-## What you get
+<a id="what-you-get"></a>
+
+## 🧰 What you get
 
 | Kind | Name | Description |
 |---|---|---|
@@ -52,7 +69,9 @@ calls. Usage counters have existed since 0.2.0, but they never leave the machine
 The catalog covers `css`, `ui-atoms`, `ui-components`, `ui-behaviors`, `forms`, `html`, `js`, `accessibility`,
 `visual-design`, `security`, `performance`, `built-in-ai`, `pwa`, `wasm`, `webmcp`, `privacy`, and `user-experience`.
 
-## Install
+<a id="install"></a>
+
+## 🚀 Install
 
 Published on npm:
 
@@ -76,11 +95,24 @@ From an agent session, `plugin_manager` with `action: "install_bundle"` and the
 does the same thing. The bundle inserts one row (`modern-web-guidance`) and needs no build step, no dependencies, and no
 native modules.
 
-## How to use
+<a id="how-to-use"></a>
+
+## 🧭 How to use
 
 Nothing has to be wired up: the plugin registers itself, and the `modern-web-guidance` skill tells the agent when to
 reach for it. There are three ways to work with it.
 
+<a id="which-tool-when"></a>
+
+### Which tool when
+
+| You want | Call | Comes back |
+| --- | --- | --- |
+| "how is this done today?" | `web_guidance_search` | ranked guide ids for a 2–5 word capability query, optional category filter |
+| "show me the guide" | `web_guidance_retrieve` | full markdown, up to 10 guides or 120 000 characters per call |
+| "what is even in here?" | `web_guidance_list` | counts per category, or ids and titles for one category |
+| "is the catalog actually being used?" | `/guidance-stats` | the local report as text; `--json` is what the panel reads |
+
 ### 1. Just ask for web work (default)
 
 The skill's routing description is "search 208 use-case guides before writing HTML, CSS or client-side JavaScript", so
@@ -132,7 +164,37 @@ ones instead of an empty result.
 | Faster LCP | `prioritize hero image` | `fetchpriority` guides |
 | A Manifest V3 extension | (skill) `chrome-extensions` | extension skill references |
 
-## How search works
+<a id="vs-google"></a>
+
+## 🆚 vs Google's package
+
+This plugin **vendors Google's corpus** — the same 208 guides, byte-identical — and adds the layer
+DeepSeek Harness needs: model-facing tools, a sidebar panel and no runtime dependencies. It does not
+reimplement their agent, and it deliberately drops the engines that would not survive a plugin's size
+and security budget. The honest split:
+
+| | Google `modern-web-guidance` | This plugin |
+| --- | --- | --- |
+| Shape | npm package: a CLI plus skills, run as `npx -y modern-web-guidance@latest …` | DSH plugin: 3 tools, 2 skills, a sidebar panel |
+| Audience | any agent that can run a shell command | DeepSeek Harness sessions |
+| Guide corpus | 208 indexed guides (209 `.md` files, one byte-identical duplicate) | the same 208, byte-identical, snapshot `2026_11_09-5bcc021b` |
+| Lookup | precomputed assets in `gen/` — quantized word vectors (`query-words.i8`, 7.47 MB) and chunk embeddings, 9.16 MB together | BM25 built in-process from `guides.json` and the guide bodies: no assets, no model download (measured 29/30 top-1 on a 30-query probe) |
+| Runtime dependencies | Node plus the CLI engines shipped in the package | none |
+| Network | `npx` fetches the package, then works locally | never — the corpus is inside the package |
+| Legacy scan | a 4.99 MB `legacy-scan` engine with a four-step scan → verify → report → modernize workflow | not shipped; planned as a dependency-free, report-only regex scanner in 0.5.0 |
+| Experimental guides | gated inside the CLI | `[experimental]` marker in `web_guidance_search`, warning banner in `web_guidance_retrieve` |
+| Usage insight | none | local counters, `/guidance-stats`, and the sidebar panel |
+| Languages | English guides | the same guides; docs in EN/RU/ZH, panel in EN/RU/ZH |
+| Size | — | 254 files, 854 kB packed, 2.5 MB unpacked |
+
+What this means in practice: if you work outside DeepSeek Harness, use their package — it is the
+reference implementation and it owns the corpus. Inside Harness you want the tools in the model's tool
+list, an install with no build step and no network, and a panel that says whether the guides are being
+used; that is this plugin.
+
+<a id="how-search-works"></a>
+
+## 🧠 How search works
 
 `lib/guidance.js` builds a BM25 index over the bundled corpus at first use (~1.9 MB of markdown, indexed in a few
 hundred milliseconds and cached): title, id, description, `featuresUsed`, headings and body, with stopword filtering,
@@ -143,14 +205,73 @@ Compared with the upstream semantic search, phrase-like queries (`"light dismiss
 the specific guide first; broad topical queries can differ in ordering. If a search misses, `web_guidance_list` shows
 what the catalog contains.
 
-## Skills
+<a id="catalog-map"></a>
+
+## 🗺 Catalog map
+
+Everything is local, so the catalog is only as useful as the agent's ability to find the right guide.
+`web_guidance_list` prints these counts at runtime; this is what they look like at snapshot
+`2026_11_09-5bcc021b`.
+
+<details>
+<summary>Counts per category (208 guides, 17 categories)</summary>
+
+| Category | Guides | Category | Guides |
+| --- | --- | --- | --- |
+| `ui-behaviors` | 40 | `html` | 8 |
+| `performance` | 26 | `js` | 5 |
+| `ui-components` | 22 | `accessibility` | 4 |
+| `visual-design` | 22 | `built-in-ai` | 4 |
+| `forms` | 19 | `user-experience` | 3 |
+| `css` | 18 | `webmcp` | 3 |
+| `security` | 17 | `pwa` | 2 |
+| `ui-atoms` | 13 | `privacy` · `wasm` | 1 · 1 |
+| | | **total** | **208** |
+
+</details>
+
+<a id="experimental-guides"></a>
+
+## 🧪 Experimental guides
+
+Eighteen of the 208 guides describe platform features that are not safe to assume: eight sit behind an
+Origin Trial in Chrome, and ten are volatile in a single engine. Upstream flags them in its index; this
+plugin surfaces the flag where the agent will actually see it:
+
+- `web_guidance_search` appends `[experimental]` to the hit;
+- `web_guidance_retrieve` opens the guide with a `> [!WARNING]` banner naming the reason;
+- the guide body itself is untouched — byte-identical to upstream — and the banner counts against the
+  120 000-character budget, not against the 10-guide limit.
+
+<details>
+<summary>The 18 flagged guides</summary>
+
+**Origin Trial (8)** — the feature ships behind a trial token: `verify-email-ownership`,
+`apply-webgl-shaders`, `export-html-media-from-canvas`, `expose-canvas-content-to-browser-features`,
+`interactive-content-in-3d-scenes`, `agentic-forms`, `agentic-javascript-tools`, `webmcp`.
+
+**Volatile in one engine (10)** — one engine implements it, or the API is still moving:
+`language-detection`, `language-model`, `summarizer`, `translator`, `out-of-order-html-streaming`,
+`client-side-encryption`, `digital-signatures`, `restrict-outbound-connections`, `2d-panning`,
+`custom-text-decorations`.
+
+</details>
+
+Treat a flagged guide as "the shape of the solution, not a guarantee". Feature-detect what it
+describes, and tell the user which part is behind a flag before shipping it.
+
+<a id="skills"></a>
+
+## 🪄 Skills
 
 The `modern-web-guidance` skill body is adapted from upstream: it tells the agent to call this plugin's tools instead
 of the `npx` CLI, keeps the framework/SSR/DOM notes and the Baseline fallback policy, drops the CLI and telemetry
 sections, and states the trust boundary — retrieved guides are reference material, not instructions. The
 `chrome-extensions` skill is bundled unchanged and loads its `references/` files from the skill directory.
 
-## Security and limits
+<a id="security-and-limits"></a>
+
+## 🛡 Security and limits
 
 The corpus is third-party text that ends up in a model's context, and tool arguments come from that model, so both
 sides are bounded:
@@ -176,7 +297,9 @@ Both properties are covered by `test/hardening.test.mjs`, which fails on the pre
 reports plus runnable repros — lives in [`audit/`](audit/), and the repro scripts under `audit/repro/` exit non-zero
 while a defect is live.
 
-## Usage stats
+<a id="usage-stats"></a>
+
+## 📊 Usage stats
 
 Since 0.2.0 the plugin records what the three tools are actually asked for. The counters are local: no endpoint, no
 analytics service, no third-party SDK, and nothing leaves the machine.
@@ -199,7 +322,9 @@ defaults to 90 days, and `--reset --yes` erases it.
 
 Turn it off: set `enabled: false` in the plugin config — no listener is registered and no file is written.
 
-## Sidebar panel
+<a id="sidebar-panel"></a>
+
+## 🖥 Sidebar panel
 
 The plugin adds a client half: a guidance icon in the left rail opens **Guidance Insights** in the central area. It
 shows the same counters `/guidance-stats` prints, as a view:
@@ -216,13 +341,17 @@ The panel is read-only. It never changes a counter, never leaves the machine, an
 tools — the same three tools stay exactly three. `/guidance-stats` remains the text and `--json` version for the
 terminal and for the agent; the panel is that report as a view.
 
-## Configuration
+<a id="configuration"></a>
+
+## ⚙️ Configuration
 
 The plugin needs no configuration to work. It registers its tools and skills on the host context and is inert when the
 profile has no `tools` or `skills` service. The one setting is `enabled` on the plugin row: `false` turns the local
 counters off (see [Usage stats](#usage-stats)).
 
-## Updating the guide corpus
+<a id="updating-the-guide-corpus"></a>
+
+## 🔄 Updating the guide corpus
 
 The corpus is a pinned snapshot of upstream `modern-web-guidance@1.0.0`
 (skill version `2026_11_09-5bcc021b`). To refresh it:
@@ -238,24 +367,87 @@ The corpus is a pinned snapshot of upstream `modern-web-guidance@1.0.0`
    any served guide tells the agent to run the upstream CLI, so a refreshed corpus needs no manual de-CLI pass — the
    rewrite happens at load time (`lib/guidance.js`, `CLI_REFERENCE`).
 
-## Development
+<a id="faq"></a>
+
+## ❓ FAQ
+
+**The plugin is installed but I see nothing.** The bundle inserts one row (`modern-web-guidance`) and
+needs no build step. Restart DSH after `dsh plugin --profile desktop add …`; the tools appear in the
+next session's tool list, and the panel as an icon in the left rail.
+
+**Search returns nothing useful.** Queries are 2–5 words describing a capability ("light dismiss
+dialog", "view transition", "container query"), not sentences. If a query still misses, call
+`web_guidance_list` for the category overview and retrieve by id from there.
+
+**Why did a result say `[experimental]`?** The guide's platform feature is behind an Origin Trial or
+is volatile in one engine — see [Experimental guides](#experimental-guides). The guide is still the
+right shape; feature-detect it before shipping.
+
+**Does anything leave my machine?** No. The corpus is inside the package, search is computed
+in-process, and there are no network calls. The usage counters are local files and can be switched off
+with `enabled: false` — see [Security and limits](#security-and-limits) and [ADR 0001](docs/adr/0001-local-telemetry.md).
+
+**Google says 203 use cases. Why does this say 208?** Upstream's own count is 203 *use-case* guides;
+the index has 208 entries, the extra five being the discipline overviews (`accessibility`, `forms`,
+`html`, `performance`, `security`). This plugin ships what the index ships.
+
+**Which DSH versions work?** `engines.dsh` is `>=0.2.0-rc.1 <0.3.0-0` and Node `>=22.19.0`. The tools
+work on their own; the panel additionally needs the host's `slots`, `locale` and `remote` services.
+
+<a id="roadmap"></a>
+
+## 🚦 Roadmap
+
+| Release | State | What it is |
+| --- | --- | --- |
+| 0.4.0 | shipped | the upstream v1.0.0 corpus (208 guides) plus experimental marking |
+| 0.4.1 | this pass | docs: navigation, the comparison, the catalog map |
+| 0.5.0 | next | `legacy-scan` as a fourth tool: 30–35 regex rules ported from upstream's engine, explicit paths only, report-only output. Design and verdict: [docs/notes/legacy-scan-feasibility.md](docs/notes/legacy-scan-feasibility.md) |
+
+Deliberately **not** planned: shipping upstream's 9.16 MB embedding tables, or its 4.99 MB
+`legacy-scan` engine with a bundled TypeScript compiler. Both would break "zero runtime dependencies,
+no network, no code generation" for a gain the lexical index does not show.
+
+<a id="docs-map"></a>
+
+## 📚 Docs map
+
+| Document | Read it when |
+| --- | --- |
+| [`docs/README.md`](docs/README.md) | you want the full map of this repository |
+| [`PUBLISHING.md`](PUBLISHING.md) | you are releasing: npm rules, trusted publishing, the release ritual |
+| [`docs/releases/README.md`](docs/releases/README.md) | you are writing release notes — the house style lives here |
+| [`AGENTS.md`](AGENTS.md) | you are an agent working in this repo: CI, client half, conventions |
+| [`GLOSSARY.md`](GLOSSARY.md) | a term in this codebase is unclear |
+| [`NOTICE`](NOTICE) | attribution: what came from upstream and what was left out, and why |
+| [`audit/`](audit) | you want the 0.1.x security, corpus and bug audits as they were written |
+| [`docs/adr/`](docs/adr) | you want the decisions: local telemetry, and what followed |
+| [`docs/notes/`](docs/notes) | you want the research behind a release (upstream diffs, feasibility studies, plans) |
+
+<a id="development"></a>
+
+## 🧑‍💻 Development
 
 ```shell
 npm test
 ```
 
-68 tests across seven files: `guidance.test.mjs` covers the index, ranking, retrieval and the stemmer;
-`plugin.test.mjs` covers tool and skill registration against a mocked Cordis context; `hardening.test.mjs` covers the
-audit findings and fails on the pre-hardening code; `telemetry.test.mjs`, `report.test.mjs`, `store.test.mjs` and
-`stats.test.mjs` cover the usage counters, their report, the durable store and the `/guidance-stats` wiring. In a
+`npm test` runs the suite: `guidance.test.mjs` covers the index, ranking, retrieval and the stemmer;
+`plugin.test.mjs` mounts the plugin against a fake Cordis context; `hardening.test.mjs` guards the
+security invariants; `report.test.mjs`, `stats.test.mjs`, `store.test.mjs` and `telemetry.test.mjs`
+cover the counter pipeline; `client-locales.test.mjs` keeps the panel's three dictionaries in sync. In a
 sandbox that forbids child processes, run the files directly (`node test/hardening.test.mjs`).
 
-## Publishing
+<a id="publishing"></a>
+
+## 📦 Publishing
 
 Marketplace submission and npm steps are documented in [PUBLISHING.md](PUBLISHING.md); the prepared awesome-dsh-plugin
 entry lives in [`market/awesome-dsh-plugin.yml`](market/awesome-dsh-plugin.yml).
 
-## Attribution and license
+<a id="attribution-and-license"></a>
+
+## ⚖️ Attribution and license
 
 Apache-2.0. The guide corpus, the `chrome-extensions` skill, and the source of the adapted `SKILL.md` come from
 [GoogleChrome/modern-web-guidance](https://github.com/GoogleChrome/modern-web-guidance) (Copyright Google LLC,

package/README.ru.md

@@ -22,13 +22,28 @@
 <p align="center">
   <a href="LICENSE"><img alt="Лицензия" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
   <a href="package.json"><img alt="Зависимости" src="https://img.shields.io/badge/dependencies-0-brightgreen"></a>
-  <a href="#безопасность-и-границы"><img alt="Телеметрия" src="https://img.shields.io/badge/telemetry-local--only-brightgreen"></a>
+  <a href="#security-and-limits"><img alt="Телеметрия" src="https://img.shields.io/badge/telemetry-local--only-brightgreen"></a>
   <a href="https://github.com/metapeka/dsh-modern-web-guidance/actions/workflows/test.yml"><img alt="Тесты" src="https://github.com/metapeka/dsh-modern-web-guidance/actions/workflows/test.yml/badge.svg"></a>
   <a href="https://www.npmjs.com/package/dsh-modern-web-guidance"><img alt="npm" src="https://img.shields.io/npm/v/dsh-modern-web-guidance"></a>
   <img alt="Гайды" src="https://img.shields.io/badge/guides-208-2563eb">
   <img alt="Плагин DSH" src="https://img.shields.io/badge/DSH-plugin-0d9488">
+  <a href="https://www.npmjs.com/package/dsh-modern-web-guidance"><img alt="Скачивания npm" src="https://img.shields.io/npm/dm/dsh-modern-web-guidance"></a>
+  <a href="https://github.com/metapeka/dsh-modern-web-guidance/releases"><img alt="Релиз" src="https://img.shields.io/github/v/release/metapeka/dsh-modern-web-guidance?label=release"></a>
 </p>
 
+<details>
+<summary>📑 Содержание</summary>
+
+**Начать здесь** · [Что вы получаете](#what-you-get) · [Установка](#install) · [Как пользоваться](#how-to-use) · [Каким инструментом когда](#which-tool-when)
+
+**Понять, как устроено** · [Против пакета Google](#vs-google) · [Как работает поиск](#how-search-works) · [Карта каталога](#catalog-map) · [Экспериментальные гайды](#experimental-guides)
+
+**Эксплуатация** · [Безопасность и границы](#security-and-limits) · [Статистика использования](#usage-stats) · [Боковая панель](#sidebar-panel) · [Конфигурация](#configuration) · [Обновление корпуса](#updating-the-guide-corpus)
+
+**Остальное** · [Частые вопросы](#faq) · [Дорожная карта](#roadmap) · [Карта документации](#docs-map) · [Разработка](#development) · [Публикация](#publishing) · [Лицензия](#attribution-and-license)
+
+</details>
+
 ---
 
 Модели по умолчанию пишут веб-код по своему обучающему срезу — то есть тянут паттерны пятилетней давности. Этот
@@ -37,9 +52,11 @@ API платформы (нативные `<dialog>`/popover, anchor positioning,
 эффекты, `:has()`, passkeys, `fetchpriority`, …), а не костыль на JavaScript или библиотеку.
 
 Всё работает локально: гайды лежат внутри пакета, поиск считается в процессе, сетевых вызовов нет. Счётчики
-использования есть с 0.2.0, но они не покидают машину — см. [Статистика использования](#статистика-использования).
+использования есть с 0.2.0, но они не покидают машину — см. [Статистика использования](#usage-stats).
+
+<a id="what-you-get"></a>
 
-## Что вы получаете
+## 🧰 Что вы получаете
 
 | Тип | Имя | Описание |
 |---|---|---|
@@ -52,7 +69,9 @@ API платформы (нативные `<dialog>`/popover, anchor positioning,
 Каталог покрывает `css`, `ui-atoms`, `ui-components`, `ui-behaviors`, `forms`, `html`, `js`, `accessibility`,
 `visual-design`, `security`, `performance`, `built-in-ai`, `pwa`, `wasm`, `webmcp`, `privacy` и `user-experience`.
 
-## Установка
+<a id="install"></a>
+
+## 🚀 Установка
 
 Из опубликованного пакета:
 
@@ -75,11 +94,22 @@ dsh plugin --profile desktop add file:E:/path/to/dsh-modern-web-guidance
 Из сессии агента то же самое делает `plugin_manager` с `action: "install_bundle"` и абсолютным путём к пакету в
 `target`. Бандл добавляет одну строку (`modern-web-guidance`) и не требует сборки, зависимостей или нативных модулей.
 
-## Как пользоваться
+<a id="how-to-use"></a>
+
+## 🧭 Как пользоваться
 
 Ничего настраивать не нужно: плагин регистрируется сам, а скилл `modern-web-guidance` подсказывает агенту, когда к
 нему идти. Есть три способа работы.
 
+### <a id="which-tool-when"></a>Каким инструментом когда
+
+| Что нужно | Вызов | Что вернётся |
+| --- | --- | --- |
+| «как это делается сегодня?» | `web_guidance_search` | ранжированные id гайдов по запросу из 2–5 слов, опционально с фильтром по категории |
+| «покажи гайд» | `web_guidance_retrieve` | полный markdown, до 10 гайдов или 120 000 символов за вызов |
+| «что там вообще есть?» | `web_guidance_list` | счётчики по категориям или id и заголовки одной категории |
+| «каталог вообще используется?» | `/guidance-stats` | локальный отчёт текстом; `--json` — это то, что читает панель |
+
 ### 1. Просто попросить сделать веб-задачу (обычный режим)
 
 Описание скилла для роутинга — «искать по 208 гайдам, прежде чем писать HTML, CSS или клиентский JavaScript», так что
@@ -130,7 +160,36 @@ web_guidance_search({"query": "view transition"}) → ранжированный
 | Быстрый LCP | `prioritize hero image` | гайды про `fetchpriority` |
 | Расширение Manifest V3 | (скилл) `chrome-extensions` | материалы скилла про расширения |
 
-## Как работает поиск
+<a id="vs-google"></a>
+
+## 🆚 Против пакета Google
+
+Этот плагин **вендорит корпус Google** — те же 208 гайдов, побайтово идентичных — и добавляет слой, который нужен
+DeepSeek Harness: инструменты для модели, боковую панель и никаких зависимостей рантайма. Он не переписывает их агента
+и сознательно отказывается от движков, которые не выжили бы при бюджете размера и безопасности плагина. Честное
+разделение:
+
+| | Google `modern-web-guidance` | Этот плагин |
+| --- | --- | --- |
+| Форма | npm-пакет: CLI плюс скиллы, запуск как `npx -y modern-web-guidance@latest …` | плагин DSH: 3 инструмента, 2 скилла, боковая панель |
+| Аудитория | любой агент, умеющий запускать команды в оболочке | сессии DeepSeek Harness |
+| Корпус гайдов | 208 проиндексированных гайдов (209 файлов `.md`, один побайтовый дубль) | те же 208, побайтово идентичны, срез `2026_11_09-5bcc021b` |
+| Поиск | предвычисленные ассеты в `gen/` — квантованные векторы слов (`query-words.i8`, 7.47 MB) и эмбеддинги чанков, 9.16 MB вместе | BM25 строится в процессе из `guides.json` и тел гайдов: без ассетов, без скачивания модели (измерено 29/30 top-1 на пробе из 30 запросов) |
+| Зависимости рантайма | Node плюс движки CLI, поставляемые в пакете | нет |
+| Сеть | `npx` скачивает пакет, дальше всё локально | никогда — корпус лежит внутри пакета |
+| Сканер legacy | движок `legacy-scan` на 4.99 MB с четырёхшаговым процессом scan → verify → report → modernize | не поставляется; запланирован на 0.5.0 как сканер регулярными выражениями без зависимостей, только с отчётом |
+| Экспериментальные гайды | закрыты внутри CLI | маркер `[experimental]` в `web_guidance_search`, предупреждающий баннер в `web_guidance_retrieve` |
+| Анализ использования | нет | локальные счётчики, `/guidance-stats` и боковая панель |
+| Языки | гайды на английском | те же гайды; документация на EN/RU/ZH, панель на EN/RU/ZH |
+| Размер | — | 254 файла, 854 kB в упаковке, 2.5 MB распакованного |
+
+Что это значит на практике: если вы работаете вне DeepSeek Harness, берите их пакет — это референсная реализация, и
+корпус принадлежит им. Внутри Harness нужны инструменты в списке инструментов модели, установка без сборки и без сети и
+панель, которая говорит, используются ли гайды; это и есть этот плагин.
+
+<a id="how-search-works"></a>
+
+## 🧠 Как работает поиск
 
 `lib/guidance.js` при первом использовании строит BM25-индекс по встроенному корпусу (~1.9 MB markdown, индексация
 занимает несколько сотен миллисекунд, дальше кэш): заголовок, id, описание, `featuresUsed`, заголовки разделов и
@@ -142,14 +201,72 @@ web_guidance_search({"query": "view transition"}) → ранжированный
 ставят на первое место нужный гайд; на широких тематических запросах порядок может отличаться. Если поиск промахнулся,
 `web_guidance_list` покажет, что в каталоге есть.
 
-## Скиллы
+<a id="catalog-map"></a>
+
+## 🗺 Карта каталога
+
+Всё локально, поэтому каталог полезен ровно настолько, насколько агент умеет найти нужный гайд. `web_guidance_list`
+печатает эти счётчики в рантайме; вот как они выглядят на срезе `2026_11_09-5bcc021b`.
+
+<details>
+<summary>Счётчики по категориям (208 гайдов, 17 категорий)</summary>
+
+| Категория | Гайдов | Категория | Гайдов |
+| --- | --- | --- | --- |
+| `ui-behaviors` | 40 | `html` | 8 |
+| `performance` | 26 | `js` | 5 |
+| `ui-components` | 22 | `accessibility` | 4 |
+| `visual-design` | 22 | `built-in-ai` | 4 |
+| `forms` | 19 | `user-experience` | 3 |
+| `css` | 18 | `webmcp` | 3 |
+| `security` | 17 | `pwa` | 2 |
+| `ui-atoms` | 13 | `privacy` · `wasm` | 1 · 1 |
+| | | **итого** | **208** |
+
+</details>
+
+<a id="experimental-guides"></a>
+
+## 🧪 Экспериментальные гайды
+
+Восемнадцать из 208 гайдов описывают возможности платформы, которые нельзя считать безопасными: восемь закрыты Origin
+Trial в Chrome, а десять изменчивы в пределах одного движка. Апстрим помечает их в своём индексе; этот плагин показывает
+пометку там, где агент её действительно увидит:
+
+- `web_guidance_search` добавляет `[experimental]` к результату;
+- `web_guidance_retrieve` открывает гайд баннером `> [!WARNING]`, называющим причину;
+- тело гайда не тронуто — побайтово идентично апстриму — а баннер считается в бюджет 120 000 символов, а не в лимит
+  в 10 гайдов.
+
+<details>
+<summary>18 помеченных гайдов</summary>
+
+**Origin Trial (8)** — возможность поставляется за токеном триала: `verify-email-ownership`,
+`apply-webgl-shaders`, `export-html-media-from-canvas`, `expose-canvas-content-to-browser-features`,
+`interactive-content-in-3d-scenes`, `agentic-forms`, `agentic-javascript-tools`, `webmcp`.
+
+**Нестабильно в одном движке (10)** — возможность реализована в одном движке, либо API ещё меняется:
+`language-detection`, `language-model`, `summarizer`, `translator`, `out-of-order-html-streaming`,
+`client-side-encryption`, `digital-signatures`, `restrict-outbound-connections`, `2d-panning`,
+`custom-text-decorations`.
+
+</details>
+
+Относитесь к помеченному гайду как к «форме решения, а не гарантии». Проверяйте фича-детектом то, что он описывает, и
+говорите пользователю, какая часть за флагом, прежде чем это отгружать.
+
+<a id="skills"></a>
+
+## 🪄 Скиллы
 
 Тело скилла `modern-web-guidance` адаптировано из апстрима: он велит агенту вызывать инструменты этого плагина вместо
 CLI через `npx`, сохраняет заметки про фреймворки/SSR/DOM и политику Baseline-фолбэков, убирает разделы про CLI и
 телеметрию и проговаривает границу доверия — извлечённые гайды это справочный материал, а не инструкции. Скилл
 `chrome-extensions` вложен без изменений и подгружает свои файлы из `references/` внутри каталога скилла.
 
-## Безопасность и границы
+<a id="security-and-limits"></a>
+
+## 🛡 Безопасность и границы
 
 Корпус — это сторонний текст, который попадает в контекст модели, а аргументы инструментов приходят от самой модели,
 поэтому ограничены обе стороны:
@@ -157,7 +274,7 @@ CLI через `npx`, сохраняет заметки про фреймвор
 - **Ни сети, ни исполнения, одна локальная запись.** Плагин импортирует только локальные `node:fs`, `node:path` и
   `node:url`; у него нет зависимостей и lifecycle-скриптов, поэтому при установке ничего не скачивается и не
   выполняется. Единственный файл, который он пишет, — собственный файл счётчиков (см.
-  [Статистика использования](#статистика-использования)).
+  [Статистика использования](#usage-stats)).
 - **Гайды не могут протащить команды.** В телах гайдов апстрима есть перекрёстные ссылки вида
   `npx -y modern-web-guidance@latest retrieve "…"` (197 вхождений в 64 гайдах). При загрузке индекса они
   переписываются в `web_guidance_retrieve({"ids":["…"]})`, так что ничто прочитанное моделью из каталога не просит
@@ -176,7 +293,9 @@ CLI через `npx`, сохраняет заметки про фреймвор
 и запускаемые репро — лежит в [`audit/`](audit/); скрипты в `audit/repro/` завершаются с ненулевым кодом, пока дефект
 жив.
 
-## Статистика использования
+<a id="usage-stats"></a>
+
+## 📊 Статистика использования
 
 С версии 0.2.0 плагин записывает, что именно спрашивают у трёх инструментов. Счётчики локальные: ни endpoint, ни аналитического
 сервиса, ни стороннего SDK — за пределы машины ничего не уходит.
@@ -199,7 +318,9 @@ CLI через `npx`, сохраняет заметки про фреймвор
 
 Как выключить: `enabled: false` в конфиге плагина — тогда слушатель не регистрируется и файл не пишется.
 
-## Боковая панель
+<a id="sidebar-panel"></a>
+
+## 🖥 Боковая панель
 
 Плагин добавляет клиентскую часть: иконка в левом рейле открывает в центральной области панель
 **Guidance Insights**. Это те же счётчики, что печатает `/guidance-stats`, только в виде экрана:
@@ -210,19 +331,24 @@ CLI через `npx`, сохраняет заметки про фреймвор
 - запросы, которые ничего не нашли
 - сколько гайдов не извлекали ни разу
 
-Единственный элемент управления — обновление: одна кнопка перечитывает счётчики.
+Единственный элемент управления — обновление: одна кнопка перечитывает счётчики. Интерфейс панели переведён на
+английский, русский и китайский.
 
 Панель только читает. Она не меняет счётчики, не покидает машину и не добавляет ни сетевых вызовов, ни новых
 инструментов — три инструмента остаются ровно тремя. `/guidance-stats` остаётся текстовой версией (в том числе
 `--json`) для терминала и агента; панель — тот же отчёт в виде экрана.
 
-## Конфигурация
+<a id="configuration"></a>
+
+## ⚙️ Конфигурация
 
 Настройка не нужна, чтобы плагин работал. Он регистрирует инструменты и скиллы на контексте хоста и бездействует,
 если в профиле нет сервисов `tools` или `skills`. Единственная настройка — `enabled` в конфиге плагина: `false`
-выключает локальные счётчики (см. [Статистика использования](#статистика-использования)).
+выключает локальные счётчики (см. [Статистика использования](#usage-stats)).
 
-## Обновление корпуса гайдов
+<a id="updating-the-guide-corpus"></a>
+
+## 🔄 Обновление корпуса гайдов
 
 Корпус — это закреплённый срез апстрима `modern-web-guidance@1.0.0` (версия скилла `2026_11_09-5bcc021b`). Чтобы
 обновить:
@@ -238,24 +364,87 @@ CLI через `npx`, сохраняет заметки про фреймвор
    Тесты также падают, если какой-то отданный гайд велит агенту запускать CLI апстрима, поэтому после обновления не
    нужен ручной проход «убрать npx» — переписывание происходит при загрузке (`lib/guidance.js`, `CLI_REFERENCE`).
 
-## Разработка
+<a id="faq"></a>
+
+## ❓ Частые вопросы
+
+**Плагин установлен, но я ничего не вижу.** Бандл добавляет одну строку (`modern-web-guidance`) и не требует сборки.
+Перезапустите DSH после `dsh plugin --profile desktop add …`; инструменты появятся в списке инструментов следующей
+сессии, а панель — иконкой в левом рейле.
+
+**Поиск не находит ничего полезного.** Запрос — это 2–5 слов, описывающих возможность («light dismiss dialog»,
+«view transition», «container query»), а не предложение. Если запрос всё равно промахнулся, вызовите
+`web_guidance_list` для обзора по категориям и оттуда извлекайте по id.
+
+**Почему в результате `[experimental]`?** Платформенная возможность гайда закрыта Origin Trial или изменчива в одном
+движке — см. [Экспериментальные гайды](#experimental-guides). Гайд всё равно задаёт правильную форму; проверьте её
+фича-детектом, прежде чем отгружать.
+
+**Что-нибудь уходит с моей машины?** Нет. Корпус лежит внутри пакета, поиск считается в процессе, сетевых вызовов нет.
+Счётчики использования — локальные файлы, их можно выключить через `enabled: false` — см.
+[Безопасность и границы](#security-and-limits) и [ADR 0001](docs/adr/0001-local-telemetry.md).
+
+**Google говорит про 203 use case. Почему здесь 208?** Собственный счёт апстрима — 203 *use-case* гайда; в индексе
+208 записей, лишние пять — обзорные гайды дисциплин (`accessibility`, `forms`, `html`, `performance`, `security`). Этот
+плагин поставляет то, что в индексе.
+
+**Какие версии DSH подходят?** `engines.dsh` — `>=0.2.0-rc.1 <0.3.0-0`, Node `>=22.19.0`. Инструменты работают сами по
+себе; панели дополнительно нужны сервисы хоста `slots`, `locale` и `remote`.
+
+<a id="roadmap"></a>
+
+## 🚦 Дорожная карта
+
+| Выпуск | Состояние | Что это |
+| --- | --- | --- |
+| 0.4.0 | вышел | корпус апстрима v1.0.0 (208 гайдов) плюс пометка экспериментальных |
+| 0.4.1 | этот проход | документация: навигация, сравнение, карта каталога |
+| 0.5.0 | следующий | `legacy-scan` четвёртым инструментом: 30–35 правил-регулярок, перенесённых из движка апстрима, только явные пути, только отчёт. Дизайн и вердикт: [docs/notes/legacy-scan-feasibility.md](docs/notes/legacy-scan-feasibility.md) |
+
+Намеренно **не** планируется: поставлять таблицы эмбеддингов апстрима на 9.16 MB или его движок `legacy-scan` на
+4.99 MB со встроенным компилятором TypeScript. И то и другое сломало бы «ноль зависимостей рантайма, никакой сети,
+никакой генерации кода» ради выигрыша, которого лексический индекс не показывает.
+
+<a id="docs-map"></a>
+
+## 📚 Карта документации
+
+| Документ | Читать, когда |
+| --- | --- |
+| [`docs/README.md`](docs/README.md) | нужна полная карта этого репозитория |
+| [`PUBLISHING.md`](PUBLISHING.md) | вы выпускаете релиз: правила npm, trusted publishing, ритуал релиза |
+| [`docs/releases/README.md`](docs/releases/README.md) | вы пишете release notes — их стиль живёт здесь |
+| [`AGENTS.md`](AGENTS.md) | вы агент, работающий в этом репозитории: CI, клиентская часть, соглашения |
+| [`GLOSSARY.md`](GLOSSARY.md) | непонятен термин в этом коде |
+| [`NOTICE`](NOTICE) | атрибуция: что пришло из апстрима, что осталось за бортом и почему |
+| [`audit/`](audit) | нужны аудиты безопасности, корпуса и багов 0.1.x в том виде, как их писали |
+| [`docs/adr/`](docs/adr) | нужны решения: локальная телеметрия и что за ней последовало |
+| [`docs/notes/`](docs/notes) | нужно исследование, стоящее за релизом (диффы апстрима, feasibility-исследования, планы) |
+
+<a id="development"></a>
+
+## 🧑‍💻 Разработка
 
 ```shell
 npm test
 ```
 
-66 тестов в семи файлах: `guidance.test.mjs` покрывает индекс, ранжирование, извлечение и стеммер; `plugin.test.mjs`
-— регистрацию инструментов и скиллов на замоканном контексте Cordis; `hardening.test.mjs` — находки аудита и падает
-на коде до правок; `telemetry.test.mjs`, `report.test.mjs`, `store.test.mjs` и `stats.test.mjs` — счётчики
-использования, их отчёт, долговременное хранилище и обвязку `/guidance-stats`. В песочнице, где запрещены дочерние
+`npm test` запускает весь набор: `guidance.test.mjs` покрывает индекс, ранжирование, извлечение и стеммер;
+`plugin.test.mjs` монтирует плагин на поддельном контексте Cordis; `hardening.test.mjs` защищает инварианты
+безопасности; `report.test.mjs`, `stats.test.mjs`, `store.test.mjs` и `telemetry.test.mjs` покрывают конвейер
+счётчиков; `client-locales.test.mjs` держит синхронными три словаря панели. В песочнице, где запрещены дочерние
 процессы, запускайте файлы напрямую (`node test/hardening.test.mjs`).
 
-## Публикация
+<a id="publishing"></a>
+
+## 📦 Публикация
 
 Подача в каталог и шаги для npm описаны в [PUBLISHING.md](PUBLISHING.md); подготовленная запись для awesome-dsh-plugin
 лежит в [`market/awesome-dsh-plugin.yml`](market/awesome-dsh-plugin.yml).
 
-## Атрибуция и лицензия
+<a id="attribution-and-license"></a>
+
+## ⚖️ Атрибуция и лицензия
 
 Apache-2.0. Корпус гайдов, скилл `chrome-extensions` и исходный текст адаптированного `SKILL.md` взяты из
 [GoogleChrome/modern-web-guidance](https://github.com/GoogleChrome/modern-web-guidance) (Copyright Google LLC,

package/README.zh.md

@@ -22,13 +22,28 @@
 <p align="center">
   <a href="LICENSE"><img alt="许可证" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
   <a href="package.json"><img alt="依赖" src="https://img.shields.io/badge/dependencies-0-brightgreen"></a>
-  <a href="#安全与边界"><img alt="遥测" src="https://img.shields.io/badge/telemetry-local--only-brightgreen"></a>
+  <a href="#security-and-limits"><img alt="遥测" src="https://img.shields.io/badge/telemetry-local--only-brightgreen"></a>
   <a href="https://github.com/metapeka/dsh-modern-web-guidance/actions/workflows/test.yml"><img alt="测试" src="https://github.com/metapeka/dsh-modern-web-guidance/actions/workflows/test.yml/badge.svg"></a>
   <a href="https://www.npmjs.com/package/dsh-modern-web-guidance"><img alt="npm" src="https://img.shields.io/npm/v/dsh-modern-web-guidance"></a>
   <img alt="指南" src="https://img.shields.io/badge/guides-208-2563eb">
   <img alt="DSH 插件" src="https://img.shields.io/badge/DSH-plugin-0d9488">
+  <a href="https://www.npmjs.com/package/dsh-modern-web-guidance"><img alt="npm 下载量" src="https://img.shields.io/npm/dm/dsh-modern-web-guidance"></a>
+  <a href="https://github.com/metapeka/dsh-modern-web-guidance/releases"><img alt="版本" src="https://img.shields.io/github/v/release/metapeka/dsh-modern-web-guidance?label=release"></a>
 </p>
 
+<details>
+<summary>📑 目录</summary>
+
+**开始使用** · [你得到什么](#what-you-get) · [安装](#install) · [如何使用](#how-to-use) · [何时用哪个工具](#which-tool-when)
+
+**理解原理** · [与 Google 官方包的区别](#vs-google) · [检索如何工作](#how-search-works) · [目录地图](#catalog-map) · [实验性指南](#experimental-guides)
+
+**日常操作** · [安全与边界](#security-and-limits) · [使用统计](#usage-stats) · [侧边栏面板](#sidebar-panel) · [配置](#configuration) · [更新语料](#updating-the-guide-corpus)
+
+**其他** · [常见问题](#faq) · [路线图](#roadmap) · [文档地图](#docs-map) · [开发](#development) · [发布](#publishing) · [许可](#attribution-and-license)
+
+</details>
+
 ---
 
 编程模型默认会写出过时的 Web 代码，因为它们的训练数据里就是这些内容。这个插件把 208 篇经过筛选、节省 token 的
@@ -36,9 +51,11 @@
 过渡、滚动驱动效果、`:has()`、passkey、`fetchpriority` 等），而不是自己写 JavaScript 变通方案或引入库。
 
 一切都本地运行：指南随包分发，检索在进程内计算，没有网络请求。自 0.2.0 起就有使用统计，但它不离开这台机器 ——
-见[使用统计](#使用统计)。
+见[使用统计](#usage-stats)。
 
-## 你得到什么
+<a id="what-you-get"></a>
+
+## 🧰 你得到什么
 
 | 类型 | 名称 | 说明 |
 |---|---|---|
@@ -52,7 +69,9 @@
 `visual-design`、`security`、`performance`、`built-in-ai`、`pwa`、`wasm`、`webmcp`、`privacy` 和
 `user-experience`。
 
-## 安装
+<a id="install"></a>
+
+## 🚀 安装
 
 从已发布的包安装：
 
@@ -75,10 +94,23 @@ dsh plugin --profile desktop add file:E:/path/to/dsh-modern-web-guidance
 在智能体会话里，`plugin_manager` 的 `action: "install_bundle"` 加上包的绝对路径作为 `target`，效果相同。这个
 bundle 只插入一行（`modern-web-guidance`），不需要构建步骤、依赖或原生模块。
 
-## 如何使用
+<a id="how-to-use"></a>
+
+## 🧭 如何使用
 
 不需要任何配置：插件会自行注册，`modern-web-guidance` 技能会告诉智能体什么时候该用它。有三种使用方式。
 
+<a id="which-tool-when"></a>
+
+### 何时用哪个工具
+
+| 你想要 | 调用 | 返回 |
+| --- | --- | --- |
+| “现在该怎么做？” | `web_guidance_search` | 用 2–5 个词描述能力，返回排好序的指南 id，可按分类过滤 |
+| “把指南给我看” | `web_guidance_retrieve` | 完整 markdown，每次最多 10 篇或 120 000 字符 |
+| “这里到底有什么？” | `web_guidance_list` | 各分类数量，或某个分类下的 id 与标题 |
+| “目录真的有人在用吗？” | `/guidance-stats` | 文本形式的本地报告；`--json` 是面板读取的格式 |
+
 ### 1. 直接提出 Web 开发需求（默认方式）
 
 技能的路由描述就是“在写 HTML、CSS 或客户端 JavaScript 之前先检索 208 篇用例指南”，所以一句平常的请求就够了 ——
@@ -128,7 +160,35 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 | 更快的 LCP | `prioritize hero image` | `fetchpriority` 相关指南 |
 | Manifest V3 扩展 | （技能）`chrome-extensions` | 扩展技能的参考文件 |
 
-## 检索如何工作
+<a id="vs-google"></a>
+
+## 🆚 与 Google 官方包的区别
+
+本插件**直接内置 Google 的语料** —— 同样的 208 篇指南，逐字节一致 —— 再补上 DeepSeek Harness 需要的那一层：
+面向模型的工具、一个侧边栏面板，以及零运行时依赖。它没有重新实现上游的智能体，也刻意去掉了那些撑不过插件
+体积与安全预算的引擎。老实说，差别是这样：
+
+| | Google `modern-web-guidance` | 本插件 |
+| --- | --- | --- |
+| 形态 | npm 包：一个 CLI 加技能，用 `npx -y modern-web-guidance@latest …` 运行 | DSH 插件：3 个工具、2 个技能、一个侧边栏面板 |
+| 受众 | 任何能执行 shell 命令的智能体 | DeepSeek Harness 会话 |
+| 指南语料 | 208 篇已索引的指南（209 个 `.md` 文件，其中一个是逐字节副本） | 同样的 208 篇，逐字节一致，快照 `2026_11_09-5bcc021b` |
+| 检索方式 | `gen/` 里预计算好的资源 —— 量化词向量（`query-words.i8`，7.47 MB）与分块 embedding，合计 9.16 MB | 在进程内用 `guides.json` 和指南正文构建 BM25：没有资源文件，不下载模型（在 30 条查询的探针上测得 29/30 的 top-1） |
+| 运行时依赖 | Node 加上包里附带的 CLI 引擎 | 无 |
+| 网络 | `npx` 先取包，之后本地运行 | 从不联网 —— 语料就在包里 |
+| legacy-scan 扫描 | 4.99 MB 的 `legacy-scan` 引擎，带扫描 → 校验 → 报告 → 现代化四步工作流 | 未内置；计划在 0.5.0 里做成零依赖、只输出报告的 regex 扫描器 |
+| 实验性指南 | 在 CLI 内部做门控 | `web_guidance_search` 结果里的 `[experimental]` 标记，`web_guidance_retrieve` 开头的警告横幅 |
+| 使用情况洞察 | 无 | 本地计数、`/guidance-stats` 和侧边栏面板 |
+| 语言 | 英文指南 | 同样的指南；文档 EN/RU/ZH，面板 EN/RU/ZH |
+| 体积 | — | 254 个文件，打包 854 kB，解包 2.5 MB |
+
+实际意味着：如果你在 DeepSeek Harness 之外工作，就用他们的包 —— 它是参考实现，语料也归它所有。在 Harness
+里面，你要的是工具出现在模型的工具列表里、安装不需要构建步骤也不联网，以及一个能看出指南到底有没有人在用的
+面板；那就是本插件。
+
+<a id="how-search-works"></a>
+
+## 🧠 检索如何工作
 
 `lib/guidance.js` 在首次使用时为内置语料建立 BM25 索引（约 1.9 MB markdown，几百毫秒建好并缓存）：标题、id、
 描述、`featuresUsed`、各级标题与正文，配合停用词过滤、小型英文词干器、前缀扩展，以及精确 id/标题命中的加权。
@@ -137,18 +197,73 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 与上游的语义检索相比，短语式查询（`"light dismiss dialog"`、`"anchor positioning"`）会把对应的具体指南排在第一
 位；宽泛的主题查询排序可能不同。如果检索没命中，`web_guidance_list` 会告诉你目录里有什么。
 
-## 技能
+<a id="catalog-map"></a>
+
+## 🗺 目录地图
+
+一切都本地运行，所以目录好不好用，全看智能体能不能找到对的那篇指南。`web_guidance_list` 在运行时打印这些
+数量；下面是快照 `2026_11_09-5bcc021b` 的样子。
+
+<details>
+<summary>各分类数量（208 篇指南，17 个分类）</summary>
+
+| 分类 | 指南数 | 分类 | 指南数 |
+| --- | --- | --- | --- |
+| `ui-behaviors` | 40 | `html` | 8 |
+| `performance` | 26 | `js` | 5 |
+| `ui-components` | 22 | `accessibility` | 4 |
+| `visual-design` | 22 | `built-in-ai` | 4 |
+| `forms` | 19 | `user-experience` | 3 |
+| `css` | 18 | `webmcp` | 3 |
+| `security` | 17 | `pwa` | 2 |
+| `ui-atoms` | 13 | `privacy` · `wasm` | 1 · 1 |
+| | | **合计** | **208** |
+
+</details>
+
+<a id="experimental-guides"></a>
+
+## 🧪 实验性指南
+
+208 篇指南里有 18 篇讲的是不能默认可用的平台特性：其中 8 篇对应的功能在 Chrome 里还挂在 Origin Trial 后面，
+另外 10 篇只在单一引擎里实现、仍不稳定。上游在自己的索引里给它们打了标记；本插件把这个标记放到智能体真正
+看得到的地方：
+
+- `web_guidance_search` 在命中的结果后面追加 `[experimental]`；
+- `web_guidance_retrieve` 在指南开头放一段 `> [!WARNING]` 横幅，写明原因；
+- 指南正文本身没有改动 —— 与上游逐字节一致 —— 横幅计入 120 000 字符的预算，不占 10 篇的次数上限。
+
+<details>
+<summary>被标记的 18 篇指南</summary>
+
+**Origin Trial（8 篇）** —— 功能需要 trial token 才能开启：`verify-email-ownership`、`apply-webgl-shaders`、
+`export-html-media-from-canvas`、`expose-canvas-content-to-browser-features`、`interactive-content-in-3d-scenes`、
+`agentic-forms`、`agentic-javascript-tools`、`webmcp`。
+
+**单一引擎内仍不稳定（10 篇）** —— 只有一个引擎实现了它，或者 API 还在变：`language-detection`、`language-model`、
+`summarizer`、`translator`、`out-of-order-html-streaming`、`client-side-encryption`、`digital-signatures`、
+`restrict-outbound-connections`、`2d-panning`、`custom-text-decorations`。
+
+</details>
+
+把带标记的指南当作“方案的轮廓，而不是保证”。先对它描述的特性做检测，上线前告诉用户哪一部分还挂在开关后面。
+
+<a id="skills"></a>
+
+## 🪄 技能
 
 `modern-web-guidance` 技能正文改编自上游：它让智能体调用本插件的工具，而不是通过 `npx` 调 CLI；保留框架/SSR/DOM
 相关说明与 Baseline 降级策略；删掉 CLI 与遥测章节；并明确信任边界 —— 取回的指南是参考资料，不是指令。
 `chrome-extensions` 技能原样内置，并从技能目录的 `references/` 加载参考文件。
 
-## 安全与边界
+<a id="security-and-limits"></a>
+
+## 🛡 安全与边界
 
 语料是要进入模型上下文的第三方文本，而工具参数又来自该模型，所以两边都设了边界：
 
 - **无网络、无执行，只有一次本地写入。** 插件只导入本地的 `node:fs`、`node:path` 和 `node:url`；没有依赖，也没有
-  lifecycle 脚本，因此安装时不会下载或运行任何东西。它唯一写入的文件是自己的计数文件（见[使用统计](#使用统计)）。
+  lifecycle 脚本，因此安装时不会下载或运行任何东西。它唯一写入的文件是自己的计数文件（见[使用统计](#usage-stats)）。
 - **指南里夹带不了命令。** 上游指南正文之间用
   `npx -y modern-web-guidance@latest retrieve "…"` 互相引用（197 处，分布在 64 篇指南里）。建立索引时这些引用会被
   改写成 `web_guidance_retrieve({"ids":["…"]})`，所以模型从目录里读到的内容不会要求它安装并执行一个未锁定版本的
@@ -165,7 +280,9 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 这两类性质由 `test/hardening.test.mjs` 覆盖，该文件在加固前的代码上会失败。完整审计 —— 三份报告与可运行的复现
 脚本 —— 位于 [`audit/`](audit/)；只要缺陷仍然存在，`audit/repro/` 下的脚本就会以非零码退出。
 
-## 使用统计
+<a id="usage-stats"></a>
+
+## 📊 使用统计
 
 自 0.2.0 起，插件记录三个工具到底被问了什么。计数只在本地：没有上报端点、没有分析服务、没有第三方 SDK，任何东西都不离开这台
 机器。
@@ -187,7 +304,9 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 
 关闭方式：在插件配置里设 `enabled: false` —— 此时不注册监听，也不写文件。
 
-## 侧边栏面板
+<a id="sidebar-panel"></a>
+
+## 🖥 侧边栏面板
 
 插件增加了客户端部分：左侧栏的图标会在中央区域打开 **Guidance Insights** 面板。它展示的就是
 `/guidance-stats` 打印的那些计数，只是换成了界面：
@@ -203,12 +322,16 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 面板是只读的。它不改动计数、不离开这台机器，也不新增网络请求和工具 —— 三个工具仍然是三个。
 `/guidance-stats` 仍然是给终端和智能体用的文本版本（含 `--json`）；面板是同一份报告的界面版本。
 
-## 配置
+<a id="configuration"></a>
+
+## ⚙️ 配置
 
 插件不需要配置就能工作。它把工具与技能注册到宿主上下文；如果 profile 没有 `tools` 或 `skills` 服务，它就保持
-静默。唯一的设置是插件配置里的 `enabled`：设为 `false` 就关闭本地统计（见[使用统计](#使用统计)）。
+静默。唯一的设置是插件配置里的 `enabled`：设为 `false` 就关闭本地统计（见[使用统计](#usage-stats)）。
 
-## 更新指南语料
+<a id="updating-the-guide-corpus"></a>
+
+## 🔄 更新指南语料
 
 语料是上游 `modern-web-guidance@1.0.0` 的锁定快照（技能版本 `2026_11_09-5bcc021b`）。更新步骤：
 
@@ -222,23 +345,81 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
    测试同样会失败，所以刷新语料后不需要手工再清理一遍 npx —— 改写发生在加载时（`lib/guidance.js`，
    `CLI_REFERENCE`）。
 
-## 开发
+<a id="faq"></a>
+
+## ❓ 常见问题
+
+**插件装了却什么也看不到。** bundle 只插入一行（`modern-web-guidance`），不需要构建步骤。执行
+`dsh plugin --profile desktop add …` 之后重启 DSH；工具会出现在下一次会话的工具列表里，面板则以左侧栏图标
+的形式出现。
+
+**检索结果没什么用。** 查询是用 2–5 个词描述一项能力（“light dismiss dialog”、“view transition”、
+“container query”），不是整句。如果还是没命中，先调 `web_guidance_list` 看各分类总览，再按 id 取回。
+
+**为什么结果里写着 `[experimental]`？** 指南讲的平台特性挂在 Origin Trial 后面，或者只在单一引擎里实现、仍
+不稳定 —— 见[实验性指南](#experimental-guides)。指南本身仍然是正确的方向；上线前先做特性检测。
+
+**会有东西离开这台机器吗？** 不会。语料就在包里，检索在进程内计算，没有任何网络请求。使用计数是本地文件，
+可以用 `enabled: false` 关掉 —— 见[安全与边界](#security-and-limits)和 [ADR 0001](docs/adr/0001-local-telemetry.md)。
+
+**Google 说 203 个用例，这里为什么写 208？** 上游自己数的是 203 篇*用例*指南；索引里有 208 条，多出来的 5 篇
+是各领域总览（`accessibility`、`forms`、`html`、`performance`、`security`）。本插件跟着索引走。
+
+**支持哪些 DSH 版本？** `engines.dsh` 是 `>=0.2.0-rc.1 <0.3.0-0`，Node 是 `>=22.19.0`。工具本身可以独立工作；
+面板还需要宿主提供 `slots`、`locale` 和 `remote` 服务。
+
+<a id="roadmap"></a>
+
+## 🚦 路线图
+
+| 版本 | 状态 | 内容 |
+| --- | --- | --- |
+| 0.4.0 | 已发布 | 上游 v1.0.0 语料（208 篇指南）加实验性标记 |
+| 0.4.1 | 本次 | 文档：导航、对比表、目录地图 |
+| 0.5.0 | 下一步 | `legacy-scan` 作为第四个工具：从上游引擎移植的 30–35 条 regex 规则，只接受显式路径，只输出报告。设计与结论：[docs/notes/legacy-scan-feasibility.md](docs/notes/legacy-scan-feasibility.md) |
+
+刻意**不**做的：内置上游那 9.16 MB 的 embedding 表，或者它那个附带 TypeScript 编译器的 4.99 MB `legacy-scan`
+引擎。两者都会破坏“零运行时依赖、不联网、不生成代码”，而换来的收益在词法索引上根本看不出来。
+
+<a id="docs-map"></a>
+
+## 📚 文档地图
+
+| 文档 | 什么时候读 |
+| --- | --- |
+| [`docs/README.md`](docs/README.md) | 想看这个仓库的完整地图 |
+| [`PUBLISHING.md`](PUBLISHING.md) | 你要发版：npm 规则、trusted publishing、发布流程 |
+| [`docs/releases/README.md`](docs/releases/README.md) | 你要写发布说明 —— 团队的行文风格就在这里 |
+| [`AGENTS.md`](AGENTS.md) | 你是要在这个仓库里干活的智能体：CI、客户端部分、各项约定 |
+| [`GLOSSARY.md`](GLOSSARY.md) | 某个术语在这个代码库里说不清楚 |
+| [`NOTICE`](NOTICE) | 署名：哪些来自上游、哪些被去掉，以及为什么 |
+| [`audit/`](audit) | 想看 0.1.x 的安全、语料与缺陷审计原文 |
+| [`docs/adr/`](docs/adr) | 想看决策记录：本地遥测，以及之后的演变 |
+| [`docs/notes/`](docs/notes) | 想看某次发布背后的调研（上游 diff、可行性研究、计划） |
+
+<a id="development"></a>
+
+## 🧑‍💻 开发
 
 ```shell
 npm test
 ```
 
-七个文件共 66 个测试：`guidance.test.mjs` 覆盖索引、排序、取回与词干器；`plugin.test.mjs` 用模拟的 Cordis
-上下文覆盖工具与技能注册；`hardening.test.mjs` 覆盖审计发现，并在加固前的代码上失败；`telemetry.test.mjs`、
-`report.test.mjs`、`store.test.mjs` 和 `stats.test.mjs` 覆盖使用统计、报告渲染、持久存储与
-`/guidance-stats` 接线。在禁止子进程的沙箱里，请直接运行文件（`node test/hardening.test.mjs`）。
+`npm test` 会跑整套测试：`guidance.test.mjs` 覆盖索引、排序、取回与词干器；`plugin.test.mjs` 用模拟的 Cordis
+上下文挂载插件；`hardening.test.mjs` 守住安全不变量；`report.test.mjs`、`stats.test.mjs`、`store.test.mjs` 和
+`telemetry.test.mjs` 覆盖计数管线；`client-locales.test.mjs` 保证面板的三份词典保持同步。在禁止子进程的沙箱
+里，请直接运行文件（`node test/hardening.test.mjs`）。
+
+<a id="publishing"></a>
 
-## 发布
+## 📦 发布
 
 上架目录与 npm 发布步骤见 [PUBLISHING.md](PUBLISHING.md)；已准备好的 awesome-dsh-plugin 条目位于
 [`market/awesome-dsh-plugin.yml`](market/awesome-dsh-plugin.yml)。
 
-## 署名与许可
+<a id="attribution-and-license"></a>
+
+## ⚖️ 署名与许可
 
 Apache-2.0。指南语料、`chrome-extensions` 技能以及改编版 `SKILL.md` 的源文本来自
 [GoogleChrome/modern-web-guidance](https://github.com/GoogleChrome/modern-web-guidance)（Copyright Google LLC，

package/client.js

@@ -111,6 +111,50 @@ window.__ModuleLoader__.load({
       'error.hint': '/guidance-stats печатает тот же отчёт в терминале.',
     }
 
+    /**
+     * Simplified Chinese dictionary. Chinese has no plural inflection, so `call`, `hit` and `miss`
+     * define `.one`, `.few` and `.many` with the same text: `plural()` stays as it is and picks a
+     * form for every language.
+     */
+    const ZH = {
+      'title': '指引使用统计',
+      'subtitle': '本插件在本机记录的计数器，只读。',
+      'refresh': '刷新',
+      'loading': '正在读取计数器...',
+      'updated': '更新于 {time}',
+      'kpi.calls': '总调用次数',
+      'kpi.hitRate': '命中率',
+      'kpi.period': '统计周期',
+      'kpi.periodValue': '最近 {days} 天',
+      'kpi.corpus': '指引数量',
+      'section.queries': '热门查询',
+      'section.queries.empty': '暂无可排序的查询。',
+      'section.coverage': '分类覆盖率',
+      'section.misses': '没有结果的查询',
+      'section.misses.empty': '没有查询返回空结果。',
+      'section.dead': '未被读过的指引',
+      'dead.summary': '{total} 篇指引中有 {count} 篇从未被检索',
+      'dead.none': '每篇指引都至少被检索过一次。',
+      'coverage.value': '{retrieved} / {total}',
+      'call.one': '{count} 次调用',
+      'call.few': '{count} 次调用',
+      'call.many': '{count} 次调用',
+      'hit.one': '{count} 次命中',
+      'hit.few': '{count} 次命中',
+      'hit.many': '{count} 次命中',
+      'miss.one': '{count} 次未命中',
+      'miss.few': '{count} 次未命中',
+      'miss.many': '{count} 次未命中',
+      'empty.title': '最近 {days} 天没有调用',
+      'empty.body': '使用 web_guidance_search 获取指引，然后刷新本面板。/guidance-stats 会以文本形式输出同一份报告。',
+      'error.title': '使用计数器不可用',
+      'error.bridge': '面板桥接不可用',
+      'error.bridgeHint': '当前页面无法访问主机命令桥接。/guidance-stats --json 会输出同一份报告。',
+      'error.session': '没有可运行 /guidance-stats 的会话',
+      'error.sessionHint': '打开或开始一个对话，然后点击刷新。',
+      'error.hint': '/guidance-stats 会在终端输出同一份报告。',
+    }
+
     //#region helpers
 
     /** A finite number, or 0: the report is JSON, so a missing field must read as zero. */
@@ -732,7 +776,7 @@ window.__ModuleLoader__.load({
      */
     function apply(ctx) {
       const t = ctx.locale.bind(NS)
-      ctx.effect(() => ctx.locale.register(NS, { en: EN, ru: RU }), 'modern-web-guidance: client dictionaries')
+      ctx.effect(() => ctx.locale.register(NS, { en: EN, ru: RU, zh: ZH }), 'modern-web-guidance: client dictionaries')
 
       /**
        * The one bridge. `ctx.remote` is the typed Remote service; a page that does not mount it

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "现代 Web 指引",
+    "description": "Google Chrome 的现代 Web 平台指引，支持离线搜索：对话框、CSS 布局、视图过渡、表单、无障碍、性能。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "dsh-modern-web-guidance",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Modern web platform guidance for DeepSeek Harness agents: Google Chrome's 208-guide catalog with offline search and retrieve tools, plus a Chrome extensions (MV3) skill.",
   "type": "module",
   "license": "Apache-2.0",