dsh-modern-web-guidance 0.6.0 → 0.7.0

package/README.md

@@ -72,6 +72,10 @@ optional `rules` list of up to 33 rule ids, and `format: 'summary' | 'json'`; it
 and 8 MB per call, and returns at most 200 findings. It carries 33 rules, 30 of them upstream's; the
 [parity note](docs/notes/legacy-scan-parity.md) accounts for what is still missing and for the one real debt.
 
+The same scan is a human command, `/guidance-scan <paths> [--rules ls-01,ls-13] [--format summary|json]`: it reuses the
+tool's scanner, its refusals and its caps, and refuses to run without at least one explicit path. The panel's scan
+button is the same operation with `.` already filled in.
+
 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`.
 
@@ -119,6 +123,7 @@ reach for it. There are three ways to work with it.
 | "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 |
 | "will the code I am about to write or review use a legacy pattern?" | `web_guidance_legacy_scan` | findings for the paths you name explicitly, up to 200 per call |
+| "do it myself, from the terminal" | `/guidance-scan src/` | the same findings as text; `--format json` gives the machine value, `--rules ls-01,ls-13` narrows the table |
 
 ### 1. Just ask for web work (default)
 
@@ -182,17 +187,17 @@ 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: 4 tools, 2 skills, a sidebar panel |
+| Shape | npm package: a CLI plus skills, run as `npx -y modern-web-guidance@latest …` | DSH plugin: 4 tools, 2 skills, 2 human commands, 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 | shipped since 0.5.0: a dependency-free regex scanner over 33 rules, 30 of them upstream's, explicit paths only, report only |
+| Legacy scan | a 4.99 MB `legacy-scan` engine with a four-step scan → verify → report → modernize workflow | shipped since 0.5.0: a dependency-free regex scanner over 33 rules, 30 of them upstream's, explicit paths only, report only — with `/guidance-scan` as its human command since 0.7.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 |
+| Usage insight | none | local counters, the `/guidance-stats` report, the `/guidance-scan` command and a panel that maps both |
 | Languages | English guides | the same guides; docs in EN/RU/ZH, panel in EN/RU/ZH |
-| Size | — | 256 files, 874 kB packed, 2.5 MB unpacked |
+| Size | — | 256 files, 893 kB packed, 2.6 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
@@ -298,7 +303,9 @@ sides are bounded:
 - **The scanner reads only what it is given.** `web_guidance_legacy_scan` has no default target: the caller names 1–16
   paths, each must resolve inside the session workspace, and a symlink that escapes it is skipped rather than followed.
   It refuses absolute paths, paths outside the workspace and missing paths (`path-absolute`, `path-outside`,
-  `path-missing`), caps the read at 200 files, 512 kB per file and 8 MB per call, and never writes a byte.
+  `path-missing`), caps the read at 200 files, 512 kB per file and 8 MB per call, and never writes a byte. The human
+  command `/guidance-scan` goes through the same scanner, so it refuses the same paths and applies the same caps; it
+  also refuses to run with no path at all, so nothing can walk the whole workspace by accident.
 - **The catalog cannot reach outside the package**: entry ids and categories must be slugs, and every resolved path is
   checked to stay inside the data directory. A tampered `guides.json` used to be able to read any `*.md` on disk.
 - **Failures retry and stay opaque**: a transient read error no longer poisons the tool for the session, and tool errors
@@ -329,7 +336,9 @@ The report is a human slash command, not a tool the agent can call:
 counts, per-category hit counts, per-guide retrieve counts, and the last 1000 calls with their query text and returned
 ids. Misses are the point — a count of misses that cannot be reproduced cannot be fixed.
 
-0.5.0 adds a fourth row (`legacy-scan`) and a findings total to the same report.
+0.5.0 adds a fourth row (`legacy-scan`) and a findings total to the same report. 0.7.0 keeps the scan detail with it:
+the rules and guides the findings pointed at, and the last completed scan (when, files read, findings), which the report
+prints as `Most matched rules: …` and `Last scan: …`. That detail is ids and numbers, never a path and never a snippet.
 
 Where it lives: the profile's durable storage, the same trust boundary that already holds session logs. Retention
 defaults to 90 days, and `--reset --yes` erases it.
@@ -341,20 +350,27 @@ Turn it off: set `enabled: false` in the plugin config — no listener is regist
 ## 🖥 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 — four tools plus the finding total — as a view:
+draws the counters `/guidance-stats` prints as a map, and answers four questions in that order:
+
+- **how much, and how well** — total calls, and a hit rate over the calls that could hit (search hits, search misses and
+  unknown ids), with the report's own all-calls rate in the tile's tooltip; a `7 d` / `30 d` switch re-reads the window
+- **when** — calls per day, one bar per day of the window
+- **with what, and how it ended** — calls by tool and by outcome, side by side
+- **what the scanner catches** — the last completed scan, the rules that matched most (up to 10) and the guides those
+  findings point at; the button below scans the session workspace folder and shows that run's result inline
 
-- total calls and hit rate for the last 7 days
-- the most frequent queries, with hit and miss counts
-- category coverage — retrieved guides against the 208 in the corpus
-- the queries that found nothing
-- how many guides were never retrieved
-- the scanner's finding total for the same window
+Below those, the report's lists: the most frequent queries with hit and miss counts, category coverage against the 208
+guides, the queries that found nothing, and the dead guides — listed by id, up to 20.
 
-A single refresh control re-reads the counters; there is nothing else to press.
+Refresh re-reads the counters, and the `7 d` / `30 d` switch sends `/guidance-stats --json --days N` to the host. In a
+conversation, a scan renders as a table — rule, place, confidence, guide — up to 16 rows and an "and N more" count,
+whichever format the call asked for.
 
-The panel is read-only. It never changes a counter, never leaves the machine, and adds no network calls and no new
-tools — the same four tools stay exactly four. `/guidance-stats` remains the text and `--json` version for the
-terminal and for the agent; the panel is that report as a view.
+The panel is read-only apart from the scan button: it changes no counter, never leaves the machine, and adds no network
+calls and no new tools — the same four tools stay exactly four. A scan it starts is counted like any other scan. Paths
+and snippets stay out of the panel by design: the panel shows counters, not evidence, and the chat row is where files
+and lines appear. `/guidance-stats` remains the text and `--json` version for the terminal and the agent, and
+`/guidance-scan` is the text twin of the button.
 
 <a id="configuration"></a>
 
@@ -362,7 +378,8 @@ terminal and for the agent; the panel is that report as a view.
 
 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)).
+counters off, and `/guidance-stats` with them; `/guidance-scan` keeps working, because scanning is not counting (see
+[Usage stats](#usage-stats)).
 
 <a id="updating-the-guide-corpus"></a>
 
@@ -424,7 +441,8 @@ work on their own; the panel additionally needs the host's `slots`, `locale` and
 | 0.4.0 | shipped | the upstream v1.0.0 corpus (208 guides) plus experimental marking |
 | 0.4.1 | shipped | docs: navigation, the comparison, the catalog map |
 | 0.5.0 | shipped | `legacy-scan` as the fourth tool: 30 regex rules, explicit paths only, report only — `web_guidance_legacy_scan`, with a fourth counter and a findings total in the panel. Design and verdict: [docs/notes/legacy-scan-feasibility.md](docs/notes/legacy-scan-feasibility.md) |
-| 0.6.0 | this release | three more rules (`:host-context()`, text balancing, `select:invalid`) take the table to 33 rules, 30 of them upstream's, and a guide-hash guard keeps a rule honest after a corpus refresh |
+| 0.6.0 | shipped | three more rules (`:host-context()`, text balancing, `select:invalid`) take the table to 33 rules, 30 of them upstream's, and a guide-hash guard keeps a rule honest after a corpus refresh |
+| 0.7.0 | shipped | the panel becomes a map rather than a scoreboard — period switch, calls per day, per tool and per outcome, dead guides by id, an honest hit rate, what the scanner catches and a scan button — with `/guidance-scan` as the scanner's human command and a chat table for its findings |
 
 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,
@@ -455,12 +473,14 @@ no network, no code generation" for a gain the lexical index does not show.
 npm test
 ```
 
-`npm test` runs 150 tests across twelve files: `guidance.test.mjs` covers the index, ranking, retrieval and the stemmer;
+`npm test` runs 205 tests across fourteen files: `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;
-`scan-core.test.mjs`, `scan-rules.test.mjs` and `scan-tool.test.mjs` cover the scanner's containment, its rule table and
-the tool contract, and `scan.test.mjs` is the end-to-end scan; `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`).
+`report.test.mjs`, `stats.test.mjs`, `store.test.mjs` and `telemetry.test.mjs` cover the counter pipeline and its 0.7.0
+scan fields; `scan-core.test.mjs`, `scan-rules.test.mjs` and `scan-tool.test.mjs` cover the scanner's containment, its
+rule table and the tool contract, `scan.test.mjs` is the end-to-end scan, and `scan-command.test.mjs` holds
+`/guidance-scan` to the same refusals and the same values; `scan-guides.test.mjs` checks the guide hashes the rule table
+points at, and `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`).
 
 <a id="publishing"></a>
 

package/README.ru.md

@@ -68,11 +68,15 @@ API платформы (нативные `<dialog>`/popover, anchor positioning,
 | Скилл | `chrome-extensions` | Разработка Manifest V3 и требования Chrome Web Store |
 
 Сканер работает только на чтение. `web_guidance_legacy_scan` принимает `paths` (1–16 файлов или каталогов, цели по
-умолчанию нет), необязательный список `rules` до 30 id правил и `format: 'summary' | 'json'`; за вызов он читает не
+умолчанию нет), необязательный список `rules` до 33 id правил и `format: 'summary' | 'json'`; за вызов он читает не
 более 200 файлов, до 512 kB на файл и 8 MB суммарно, и возвращает не более 200 находок. В таблице 33 правила, из них
 30 — правила апстрима; чего до сих пор не хватает и в чём единственный настоящий долг — в
 [заметке о соответствии](docs/notes/legacy-scan-parity.md).
 
+Тот же скан доступен человеку командой `/guidance-scan <paths> [--rules ls-01,ls-13] [--format summary|json]`: она
+ходит через тот же сканер, с теми же отказами и лимитами, и не запускается без хотя бы одного явного пути. Кнопка
+сканирования в панели — та же операция, где `.` уже подставлен.
+
 Каталог покрывает `css`, `ui-atoms`, `ui-components`, `ui-behaviors`, `forms`, `html`, `js`, `accessibility`,
 `visual-design`, `security`, `performance`, `built-in-ai`, `pwa`, `wasm`, `webmcp`, `privacy` и `user-experience`.
 
@@ -119,6 +123,7 @@ dsh plugin --profile desktop add file:E:/path/to/dsh-modern-web-guidance
 | «что там вообще есть?» | `web_guidance_list` | счётчики по категориям или id и заголовки одной категории |
 | «каталог вообще используется?» | `/guidance-stats` | локальный отчёт текстом; `--json` — это то, что читает панель |
 | «код, который я собираюсь написать или проверить, не тянет legacy-паттерн?» | `web_guidance_legacy_scan` | находки по явно перечисленным путям, до 200 за вызов |
+| «хочу прогнать проверку сам, из терминала» | `/guidance-scan src/` | те же находки текстом; `--format json` даёт машинное значение, `--rules ls-01,ls-13` сужает таблицу |
 
 ### 1. Просто попросить сделать веб-задачу (обычный режим)
 
@@ -181,17 +186,17 @@ DeepSeek Harness: инструменты для модели, боковую п
 
 | | Google `modern-web-guidance` | Этот плагин |
 | --- | --- | --- |
-| Форма | npm-пакет: CLI плюс скиллы, запуск как `npx -y modern-web-guidance@latest …` | плагин DSH: 4 инструмента, 2 скилла, боковая панель |
+| Форма | npm-пакет: CLI плюс скиллы, запуск как `npx -y modern-web-guidance@latest …` | плагин DSH: 4 инструмента, 2 скилла, 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: сканер регулярными выражениями без зависимостей, 33 правила, из них 30 — правила апстрима, только явные пути, только отчёт |
+| Сканер legacy | движок `legacy-scan` на 4.99 MB с четырёхшаговым процессом scan → verify → report → modernize | поставляется с 0.5.0: сканер регулярными выражениями без зависимостей, 33 правила, из них 30 — правила апстрима, только явные пути, только отчёт — а с 0.7.0 у него есть человеческая команда `/guidance-scan` |
 | Экспериментальные гайды | закрыты внутри CLI | маркер `[experimental]` в `web_guidance_search`, предупреждающий баннер в `web_guidance_retrieve` |
-| Анализ использования | нет | локальные счётчики, `/guidance-stats` и боковая панель |
+| Анализ использования | нет | локальные счётчики, отчёт `/guidance-stats`, команда `/guidance-scan` и панель, которая показывает и то и другое |
 | Языки | гайды на английском | те же гайды; документация на EN/RU/ZH, панель на EN/RU/ZH |
-| Размер | — | 256 файлов, 874 kB в упаковке, 2.5 MB распакованного |
+| Размер | — | 256 файлов, 893 kB в упаковке, 2.6 MB распакованного |
 
 Что это значит на практике: если вы работаете вне DeepSeek Harness, берите их пакет — это референсная реализация, и
 корпус принадлежит им. Внутри Harness нужны инструменты в списке инструментов модели, установка без сборки и без сети и
@@ -298,6 +303,8 @@ CLI через `npx`, сохраняет заметки про фреймвор
   1–16 путей, каждый обязан разрешаться внутри воркспейса сессии, а симлинк, уводящий наружу, пропускается, а не
   читается. Абсолютные пути, пути за пределами воркспейса и отсутствующие пути он отклоняет (`path-absolute`,
   `path-outside`, `path-missing`), чтение ограничено 200 файлами, 512 kB на файл и 8 MB на вызов, и он не пишет ни байта.
+  Человеческая команда `/guidance-scan` идёт через тот же сканер, поэтому отклоняет те же пути и держит те же лимиты;
+  она ещё и не запускается без пути, так что случайно пройтись по всему воркспейсу нечем.
 - **Каталог не может выйти за пределы пакета**: id и категории записей обязаны быть слагами, и каждый разрешённый путь
   проверяется на принадлежность каталогу данных. Подменённый `guides.json` раньше мог прочитать любой `*.md` на диске.
 - **Сбои повторяются и не раскрывают лишнего**: случайная ошибка чтения больше не отравляет инструмент на всю сессию,
@@ -327,7 +334,10 @@ CLI через `npx`, сохраняет заметки про фреймвор
 счётчики по дням, попадания по категориям, извлечения по гайдам и последние 1000 вызовов с текстом запроса и
 возвращёнными id. Промахи как раз и нужны — промах, который нельзя воспроизвести, нельзя исправить.
 
-0.5.0 добавляет в тот же отчёт четвёртую строку (`legacy-scan`) и итог по находкам.
+0.5.0 добавляет в тот же отчёт четвёртую строку (`legacy-scan`) и итог по находкам. 0.7.0 добавляет к этому
+детализацию: какие правила и гайды дали находки, и последнее завершённое сканирование — когда, сколько файлов
+прочитано, сколько находок; в отчёте это строки `Most matched rules: …` и `Last scan: …`. Только id и числа, ни
+путей, ни сниппетов.
 
 Где лежит: durable-хранилище профиля — та же граница доверия, где уже лежат логи сессий. Срок хранения по умолчанию
 90 дней, `--reset --yes` стирает всё.
@@ -339,22 +349,29 @@ CLI через `npx`, сохраняет заметки про фреймвор
 ## 🖥 Боковая панель
 
 Плагин добавляет клиентскую часть: иконка в левом рейле открывает в центральной области панель
-**Guidance Insights**. Это те же счётчики, что печатает `/guidance-stats` (четыре инструмента и итог по находкам),
-только в виде экрана:
-
-- вызовы и доля попаданий за последние 7 дней
-- самые частые запросы с числом попаданий и промахов
-- покрытие категорий — извлечённые гайды против 208 в корпусе
-- запросы, которые ничего не нашли
-- сколько гайдов не извлекали ни разу
-- итог по находкам сканера за то же окно
-
-Единственный элемент управления — обновление: одна кнопка перечитывает счётчики. Интерфейс панели переведён на
-английский, русский и китайский.
-
-Панель только читает. Она не меняет счётчики, не покидает машину и не добавляет ни сетевых вызовов, ни новых
-инструментов — четыре инструмента остаются ровно четырьмя. `/guidance-stats` остаётся текстовой версией (в том числе
-`--json`) для терминала и агента; панель — тот же отчёт в виде экрана.
+**Guidance Insights**. Это те же счётчики, что печатает `/guidance-stats`, но в виде карты: панель отвечает на
+четыре вопроса по порядку:
+
+- **сколько и насколько удачно** — всего вызовов и доля попаданий, посчитанная по вызовам, которые вообще могли
+  попасть (попадания поиска, промахи поиска, неизвестные id); доля «по всем вызовам», как её считает отчёт, лежит в
+  подсказке плитки. Переключатель `7 дн.` / `30 дн.` перечитывает окно
+- **когда** — вызовы по дням, по столбику на день окна
+- **чем и с каким исходом** — вызовы по инструментам и по исходам, рядом
+- **что находит сканер** — последнее завершённое сканирование, чаще всего сработавшие правила (до 10) и гайды, на
+  которые указывают эти находки; кнопка ниже сканирует рабочую папку сессии и показывает результат этого прогона тут же
+
+Дальше идут списки из отчёта: частые запросы с попаданиями и промахами, покрытие категорий против 208 гайдов,
+запросы без результата и непрочитанные гайды — списком id, до 20.
+
+Обновление перечитывает счётчики, а переключатель `7 дн.` / `30 дн.` отправляет хосту
+`/guidance-stats --json --days N`. В диалоге сканирование показывается таблицей — правило, место, уверенность,
+гайд — до 16 строк и «и ещё N», в каком бы формате его ни запросили.
+
+Панель только читает, кроме кнопки сканирования: она не меняет счётчики и не покидает машину, сетевых вызовов и
+новых инструментов не добавляет — четыре инструмента остаются ровно четырьмя. Запущенное из неё сканирование
+считается как любое другое. Путей и сниппетов в панели нет намеренно: панель показывает счётчики, а не
+доказательства, — файлы и строки видны в строке вызова в диалоге. `/guidance-stats` остаётся текстовой версией (в том
+числе `--json`) для терминала и агента, а `/guidance-scan` — текстовая пара кнопки.
 
 <a id="configuration"></a>
 
@@ -362,7 +379,8 @@ CLI через `npx`, сохраняет заметки про фреймвор
 
 Настройка не нужна, чтобы плагин работал. Он регистрирует инструменты и скиллы на контексте хоста и бездействует,
 если в профиле нет сервисов `tools` или `skills`. Единственная настройка — `enabled` в конфиге плагина: `false`
-выключает локальные счётчики (см. [Статистика использования](#usage-stats)).
+выключает локальные счётчики, а вместе с ними и `/guidance-stats`; `/guidance-scan` продолжает работать, потому что
+сканирование — не подсчёт (см. [Статистика использования](#usage-stats)).
 
 <a id="updating-the-guide-corpus"></a>
 
@@ -424,7 +442,8 @@ CLI через `npx`, сохраняет заметки про фреймвор
 | 0.4.0 | вышел | корпус апстрима v1.0.0 (208 гайдов) плюс пометка экспериментальных |
 | 0.4.1 | вышел | документация: навигация, сравнение, карта каталога |
 | 0.5.0 | вышел | `legacy-scan` четвёртым инструментом: 30 правил-регулярок, только явные пути, только отчёт — `web_guidance_legacy_scan`, с четвёртым счётчиком и итогом по находкам в панели. Дизайн и вердикт: [docs/notes/legacy-scan-feasibility.md](docs/notes/legacy-scan-feasibility.md) |
-| 0.6.0 | этот выпуск | ещё три правила (`:host-context()`, балансировка текста, `select:invalid`) — в таблице 33 правила, 30 из них апстрима, плюс страховка по хешам гайдов: после обновления корпуса правило не устареет молча |
+| 0.6.0 | вышел | ещё три правила (`:host-context()`, балансировка текста, `select:invalid`) — в таблице 33 правила, 30 из них апстрима, плюс страховка по хешам гайдов: после обновления корпуса правило не устареет молча |
+| 0.7.0 | вышел | панель из табло превращается в карту: переключатель окна, вызовы по дням, по инструментам и исходам, непрочитанные гайды списком id, честная доля попаданий, что находит сканер, и кнопка сканирования; плюс `/guidance-scan` — человеческая команда сканера — и таблица находок в диалоге |
 
 Намеренно **не** планируется: поставлять таблицы эмбеддингов апстрима на 9.16 MB или его движок `legacy-scan` на
 4.99 MB со встроенным компилятором TypeScript. И то и другое сломало бы «ноль зависимостей рантайма, никакой сети,
@@ -455,12 +474,14 @@ CLI через `npx`, сохраняет заметки про фреймвор
 npm test
 ```
 
-`npm test` запускает 150 тестов в двенадцати файлах: `guidance.test.mjs` покрывает индекс, ранжирование, извлечение и
-стеммер; `plugin.test.mjs` монтирует плагин на поддельном контексте Cordis; `hardening.test.mjs` защищает инварианты
-безопасности; `report.test.mjs`, `stats.test.mjs`, `store.test.mjs` и `telemetry.test.mjs` покрывают конвейер
-счётчиков; `scan-core.test.mjs`, `scan-rules.test.mjs` и `scan-tool.test.mjs` покрывают изоляцию сканера, его таблицу
-правил и контракт инструмента, а `scan.test.mjs` — сквозной скан; `client-locales.test.mjs` держит синхронными три
-словаря панели. В песочнице, где запрещены дочерние процессы, запускайте файлы напрямую (`node test/hardening.test.mjs`).
+`npm test` запускает 205 тестов в четырнадцати файлах: `guidance.test.mjs` покрывает индекс, ранжирование, извлечение
+и стеммер; `plugin.test.mjs` монтирует плагин на поддельном контексте Cordis; `hardening.test.mjs` защищает инварианты
+безопасности; `report.test.mjs`, `stats.test.mjs`, `store.test.mjs` и `telemetry.test.mjs` покрывают конвейер счётчиков
+и его поля сканера из 0.7.0; `scan-core.test.mjs`, `scan-rules.test.mjs` и `scan-tool.test.mjs` покрывают изоляцию
+сканера, его таблицу правил и контракт инструмента, `scan.test.mjs` — сквозной скан, а `scan-command.test.mjs` держит
+`/guidance-scan` на тех же отказах и тех же значениях; `scan-guides.test.mjs` сверяет хеши гайдов, на которые указывает
+таблица правил; `client-locales.test.mjs` держит синхронными три словаря панели. В песочнице, где запрещены дочерние
+процессы, запускайте файлы напрямую (`node test/hardening.test.mjs`).
 
 <a id="publishing"></a>
 

package/README.zh.md

@@ -67,9 +67,12 @@
 | 技能 | `chrome-extensions` | Manifest V3 开发与 Chrome Web Store 上架要求 |
 
 扫描器只读不写。`web_guidance_legacy_scan` 接受 `paths`（1–16 个文件或目录，没有默认目标）、可选的 `rules`（最多
-30 个规则 id）和 `format: 'summary' | 'json'`；每次调用最多读 200 个文件、单文件 512 kB、合计 8 MB，最多返回
+33 个规则 id）和 `format: 'summary' | 'json'`；每次调用最多读 200 个文件、单文件 512 kB、合计 8 MB，最多返回
 200 条发现。表里一共 33 条规则，覆盖上游 35 条中的 30 条；剩下没覆盖的规则、以及唯一真正的一笔技术债，都记在[对照说明](docs/notes/legacy-scan-parity.md)里。
 
+同一套扫描也给人留了一条命令：`/guidance-scan <paths> [--rules ls-01,ls-13] [--format summary|json]`。它走同一个
+扫描器、同一套拒绝规则和上限，而且不给至少一个显式路径就不跑。面板上的扫描按钮就是这条操作，只是把 `.` 替你填好。
+
 目录覆盖 `css`、`ui-atoms`、`ui-components`、`ui-behaviors`、`forms`、`html`、`js`、`accessibility`、
 `visual-design`、`security`、`performance`、`built-in-ai`、`pwa`、`wasm`、`webmcp`、`privacy` 和
 `user-experience`。
@@ -116,6 +119,7 @@ bundle 只插入一行（`modern-web-guidance`），不需要构建步骤、依
 | “这里到底有什么？” | `web_guidance_list` | 各分类数量，或某个分类下的 id 与标题 |
 | “目录真的有人在用吗？” | `/guidance-stats` | 文本形式的本地报告；`--json` 是面板读取的格式 |
 | “我正要写或要审的代码会不会用上过时写法？” | `web_guidance_legacy_scan` | 对显式列出的路径给出发现，每次最多 200 条 |
+| “想自己在终端里跑一遍” | `/guidance-scan src/` | 同样的发现，文本形式；`--format json` 给出机器可读的原始值，`--rules ls-01,ls-13` 收窄规则表 |
 
 ### 1. 直接提出 Web 开发需求（默认方式）
 
@@ -176,17 +180,17 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 
 | | Google `modern-web-guidance` | 本插件 |
 | --- | --- | --- |
-| 形态 | npm 包：一个 CLI 加技能，用 `npx -y modern-web-guidance@latest …` 运行 | DSH 插件：4 个工具、2 个技能、一个侧边栏面板 |
+| 形态 | npm 包：一个 CLI 加技能，用 `npx -y modern-web-guidance@latest …` 运行 | DSH 插件：4 个工具、2 个技能、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 起内置：零依赖的正则扫描器，33 条规则（其中 30 条对应上游规则），只接受显式路径，只输出报告 |
+| legacy-scan 扫描 | 4.99 MB 的 `legacy-scan` 引擎，带扫描 → 校验 → 报告 → 现代化四步工作流 | 0.5.0 起内置：零依赖的正则扫描器，33 条规则（其中 30 条对应上游规则），只接受显式路径，只输出报告；0.7.0 起还多了一条给人用的命令 `/guidance-scan` |
 | 实验性指南 | 在 CLI 内部做门控 | `web_guidance_search` 结果里的 `[experimental]` 标记，`web_guidance_retrieve` 开头的警告横幅 |
-| 使用情况洞察 | 无 | 本地计数、`/guidance-stats` 和侧边栏面板 |
+| 使用情况洞察 | 无 | 本地计数、`/guidance-stats` 报告、`/guidance-scan` 命令，以及把两者都画出来的侧边栏面板 |
 | 语言 | 英文指南 | 同样的指南；文档 EN/RU/ZH，面板 EN/RU/ZH |
-| 体积 | — | 256 个文件，打包 874 kB，解包 2.5 MB |
+| 体积 | — | 256 个文件，打包 893 kB，解包 2.6 MB |
 
 实际意味着：如果你在 DeepSeek Harness 之外工作，就用他们的包 —— 它是参考实现，语料也归它所有。在 Harness
 里面，你要的是工具出现在模型的工具列表里、安装不需要构建步骤也不联网，以及一个能看出指南到底有没有人在用的
@@ -282,7 +286,8 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 - **扫描器只读它被明确给定的内容。** `web_guidance_legacy_scan` 没有默认目标：调用方要给出 1–16 个路径，每个路径
   都必须落在会话工作区内，指向区外的符号链接会被跳过而不是跟随。绝对路径、工作区外的路径和不存在路径会被拒绝
   （`path-absolute`、`path-outside`、`path-missing`），读取上限为 200 个文件、单文件 512 kB、每次 8 MB，并且它不写
-  任何一个字节。
+  任何一个字节。给人用的 `/guidance-scan` 走同一个扫描器，所以拒绝同样的路径、执行同样的上限；它也不接受空路径，
+  因此没有任何命令会顺手把整个工作区扫一遍。
 - **目录无法越出包外**：条目 id 与分类必须是 slug，每个解析出的路径都会校验是否位于数据目录内。被篡改的
   `guides.json` 此前可以读取磁盘上任意 `*.md`。
 - **失败会重试，且不泄露信息**：一次临时的读取错误不再让工具在本次会话中永久失效，错误信息也不再暴露安装的
@@ -312,7 +317,9 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 命中次数、各指南被取回次数，以及最近 1000 次调用携带的查询文本和返回的 id。未命中的查询才是重点 —— 无法复现的
 未命中就无法修复。
 
-0.5.0 在同一份报告里加了第四行（`legacy-scan`）和一个发现总数。
+0.5.0 在同一份报告里加了第四行（`legacy-scan`）和一个发现总数。0.7.0 把扫描的细节也留在报告里：命中过哪些规则和
+指南，以及最近一次完成的扫描（时间、读了几个文件、多少条发现）—— 报告里就是 `Most matched rules: …` 与
+`Last scan: …` 两行。只有 id 和数字，没有路径，也没有代码片段。
 
 存放位置：profile 的持久存储，也就是本来就存会话日志的那层信任边界。默认保留 90 天，`--reset --yes` 会立即清空。
 
@@ -322,27 +329,33 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 
 ## 🖥 侧边栏面板
 
-插件增加了客户端部分：左侧栏的图标会在中央区域打开 **Guidance Insights** 面板。它展示的就是
-`/guidance-stats` 打印的那些计数（四个工具加发现总数），只是换成了界面：
+插件增加了客户端部分：左侧栏的图标会在中央区域打开 **Guidance Insights** 面板。它把 `/guidance-stats` 打印的计数
+画成一张地图，按顺序回答四个问题：
+
+- **用了多少、准不准** —— 总调用次数，以及按“本来可能命中”的调用算出的命中率（检索命中、检索未命中、未知 id）；
+  报告里那个“按全部调用算”的比例放在图块的提示里。`7 天` / `30 天` 开关重新读取时间窗口
+- **什么时候用的** —— 每日调用，一天一根柱子
+- **用什么、结果如何** —— 按工具和按结果的两列并列
+- **扫描器发现了什么** —— 最近一次完成的扫描、命中最多（最多 10 条）的规则，以及这些发现指向的指南；下面的按钮
+  扫描当前会话的工作区文件夹，并把这一次的结果就地显示出来
 
-- 最近 7 天的调用次数与命中率
-- 最常出现的查询，以及各自的命中与未命中次数
-- 分类覆盖情况 —— 已取回的指南对 208 篇语料
-- 什么都没找到的查询
-- 有多少篇指南从未被取回过
-- 同一时间窗口内扫描器的发现总数
+再往下是报告里的清单：热门查询及其各自的命中与未命中、对 208 篇指南的分类覆盖、没有结果的查询，以及从未被
+检索过的指南 —— 按 id 列出，最多 20 条。
 
-操作只有一个刷新：重新读取一次计数。
+刷新会重新读取计数，`7 天` / `30 天` 开关则把 `/guidance-stats --json --days N` 发给宿主。对话里，扫描结果渲染成
+表格 —— 规则、位置、置信度、指南 —— 最多 16 行，多出来的显示“另有 N 条”，不管调用要的是哪种格式。
 
-面板是只读的。它不改动计数、不离开这台机器，也不新增网络请求和工具 —— 四个工具仍然是四个。
-`/guidance-stats` 仍然是给终端和智能体用的文本版本（含 `--json`）；面板是同一份报告的界面版本。
+面板除了扫描按钮之外只读：它不改计数、不离开这台机器，也不新增网络请求和工具 —— 四个工具仍然是四个。由它发起的
+扫描和别的扫描一样计数。面板里刻意不显示路径和代码片段：面板给的是计数，不是证据；文件和行号在对话的那条工具
+调用里。`/guidance-stats` 仍然是给终端和智能体用的文本版本（含 `--json`），而 `/guidance-scan` 是按钮的文本版本。
 
 <a id="configuration"></a>
 
 ## ⚙️ 配置
 
 插件不需要配置就能工作。它把工具与技能注册到宿主上下文；如果 profile 没有 `tools` 或 `skills` 服务，它就保持
-静默。唯一的设置是插件配置里的 `enabled`：设为 `false` 就关闭本地统计（见[使用统计](#usage-stats)）。
+静默。唯一的设置是插件配置里的 `enabled`：设为 `false` 就关闭本地统计，`/guidance-stats` 也随之消失；`/guidance-scan`
+照常可用，因为扫描不是计数（见[使用统计](#usage-stats)）。
 
 <a id="updating-the-guide-corpus"></a>
 
@@ -397,7 +410,8 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 | 0.4.0 | 已发布 | 上游 v1.0.0 语料（208 篇指南）加实验性标记 |
 | 0.4.1 | 已发布 | 文档：导航、对比表、目录地图 |
 | 0.5.0 | 已发布 | `legacy-scan` 作为第四个工具：30 条正则规则，只接受显式路径，只输出报告 —— `web_guidance_legacy_scan`，面板里多一个计数器和一个发现总数。设计与结论：[docs/notes/legacy-scan-feasibility.md](docs/notes/legacy-scan-feasibility.md) |
-| 0.6.0 | 本次发布 | 再多三条规则（`:host-context()`、文本平衡、`select:invalid`），规则表增至 33 条，其中 30 条对应上游规则；另加指南哈希校验，语料更新后规则不会悄悄过期 |
+| 0.6.0 | 已发布 | 再多三条规则（`:host-context()`、文本平衡、`select:invalid`），规则表增至 33 条，其中 30 条对应上游规则；另加指南哈希校验，语料更新后规则不会悄悄过期 |
+| 0.7.0 | 已发布 | 面板从计分板变成地图：时间窗口开关、每日调用、按工具与按结果、按 id 列出的未读指南、诚实的命中率、扫描器发现了什么，外加一个扫描按钮；同时加入 `/guidance-scan` 这条给人用的扫描命令，以及对话里的发现表格 |
 
 刻意**不**做的：内置上游那 9.16 MB 的 embedding 表，或者它那个附带 TypeScript 编译器的 4.99 MB `legacy-scan`
 引擎。两者都会破坏“零运行时依赖、不联网、不生成代码”，而换来的收益在词法索引上根本看不出来。
@@ -427,11 +441,13 @@ web_guidance_search({"query": "view transition"}) → 取回之前的排序候
 npm test
 ```
 
-`npm test` 会跑 150 个测试，分布在十二个文件里：`guidance.test.mjs` 覆盖索引、排序、取回与词干器；
+`npm test` 会跑 205 个测试，分布在十四个文件里：`guidance.test.mjs` 覆盖索引、排序、取回与词干器；
 `plugin.test.mjs` 用模拟的 Cordis 上下文挂载插件；`hardening.test.mjs` 守住安全不变量；`report.test.mjs`、
-`stats.test.mjs`、`store.test.mjs` 和 `telemetry.test.mjs` 覆盖计数管线；`scan-core.test.mjs`、`scan-rules.test.mjs`
-和 `scan-tool.test.mjs` 覆盖扫描器的隔离、规则表与工具契约，`scan.test.mjs` 是端到端扫描；`client-locales.test.mjs`
-保证面板的三份词典保持同步。在禁止子进程的沙箱里，请直接运行文件（`node test/hardening.test.mjs`）。
+`stats.test.mjs`、`store.test.mjs` 和 `telemetry.test.mjs` 覆盖计数管线及其 0.7.0 的扫描字段；
+`scan-core.test.mjs`、`scan-rules.test.mjs` 和 `scan-tool.test.mjs` 覆盖扫描器的隔离、规则表与工具契约，
+`scan.test.mjs` 是端到端扫描，`scan-command.test.mjs` 则要求 `/guidance-scan` 拒绝同样的路径、返回同样的值；
+`scan-guides.test.mjs` 校验规则表指向的指南哈希；`client-locales.test.mjs` 保证面板的三份词典保持同步。在禁止
+子进程的沙箱里，请直接运行文件（`node test/hardening.test.mjs`）。
 
 <a id="publishing"></a>