dsh-plugin-guide 0.3.30 → 0.3.31

package/README-es.md

@@ -1,12 +1,15 @@
 <div align="center">
 
 # 🐳 dsh-plugin-guide
-- **Canal 1024 store**: `npm i -g dsh1024` una vez, luego `dsh1024 plugin --profile web add dsh-plugin-guide` (cuenta para el ranking de instalaciones de [deepseek1024.com](https://deepseek1024.com)).
 
 **Todo lo que necesitas para construir plugins de [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).**
 
 *Archivo de documentación oficial · primer de Cordis · deep-dives de la comunidad · trampas probadas en batalla · agent skill · toolchain CLI*
 
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -27,6 +30,22 @@
 
 **📖 ¿Prefieres leerlo como sitio web?** [perrylink.github.io/dsh-plugin-guide](https://perrylink.github.io/dsh-plugin-guide/) — cada capítulo en su propia página, más un [llms.txt](https://perrylink.github.io/dsh-plugin-guide/llms.txt) legible por máquina para asistentes.
 
+## Why not just read the official docs?
+
+Porque está escrita para quien ya sabe qué página abrir, y DSH publica **una versión preliminar cada 1,7–2,8 días** con cambios que rompen compatibilidad. Este plugin cubre las tres brechas que más tiempo cuestan:
+
+| Brecha | Qué añade este plugin |
+|---|---|
+| **"¿Contra qué versión estoy desarrollando?"** | Una [matriz de versiones](guide/version-matrix.md): los cuatro valores que se llaman "latest", las etiquetas `latest` congeladas de los subpaquetes, las fallas de compatibilidad y cómo elegir un rango en `peerDependencies`. **No existe una línea estable** — toda versión publicada es preliminar. |
+| **"¿Qué rompe esta versión?"** | Una [guía de migración](guide/migration-0.2.md) que expone `0.1.6-alpha.2` → `0.2.1-alpha.2` como **seams citables**, cada uno con síntoma *y* arreglo y su fuente oficial — incluida una pérdida de datos y un cambio que hace fallar los prompts antes de construir la petición al modelo. |
+| **"¿Mi plugin es realmente correcto?"** | Una [CLI sin dependencias](SKILL.md) (`dsh-plugin-dev new / check / verify`) y un [espejo literal y sin conexión](references/official-docs/) de la documentación oficial, para que el agente cite la página exacta. |
+
+**Compruébalo en 60 segundos:**
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -72,6 +91,10 @@ content counts as stated in the README (What you get)
 - **Deep-dives de la comunidad** — 114 repositorios de la comunidad archivados (15 con deep-dive), más un índice fuente completo donde cada hecho enlaza a su origen.
 - **Toolchain CLI** — `dsh-plugin-dev new / check / verify`: genera, verifica estáticamente y valida el empaquetado de plugins DSH; cada check enlaza a la sección de la skill que aplica.
 
+- **Adaptabilidad de versión** — [guide/version-matrix.md](guide/version-matrix.md): los cuatro valores "latest", las etiquetas `latest` congeladas, las fallas de compatibilidad, cómo elegir el rango de peers y los 19 cambios de `0.2.1-alpha.2`.
+- **Enrutador de la cadena de herramientas** — [guide/family-toolchain.md](guide/family-toolchain.md): qué herramienta responde a cada pregunta, el catálogo completo de 33 comprobaciones de `dsh-plugin-doctor` y su cruce con las 16 de este repositorio.
+- **Decisión sobre el alcance del espejo** — [references/mirror-scope-decision.md](references/mirror-scope-decision.md): por qué "eliminar lo no referenciado para ahorrar un 80%" **no se sostiene** al volver a medirlo.
+- **Destilado de la skill oficial** — [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md): prohibiciones, metadatos de presentación y reglas de UI/rendimiento de la skill oficial `cordis-plugin-development`.
 ## Knowledge base
 
 | Path | Qué es |
@@ -89,6 +112,10 @@ content counts as stated in the README (What you get)
 | `bin/` · `src/cli/` · `dist/` | El CLI `dsh-plugin-dev`: scaffolder, checker, verifier (TypeScript, empaquetado con tsdown) |
 | `templates/` | Esqueletos TS + JS: plantilla de contrato, Config, tests, cordis.patch.yml, READMEs en cinco idiomas |
 | `downloads/` | Instantáneas crudas — generadas por `scripts/`, no confirmadas |
+| `guide/version-matrix.md` | **Matriz de adaptabilidad de versión**: los cuatro valores "latest", etiquetas congeladas, fallas de compatibilidad, selección de rango de peers, linaje del formato de sesión y los 19 cambios de `0.2.1-alpha.2` |
+| `guide/family-toolchain.md` | **Enrutador de la cadena de herramientas**: pregunta → propietario → artefacto citable; catálogo completo de 33 comprobaciones de `dsh-plugin-doctor` y cruce con las 16 de este repositorio |
+| `guide/migration-0.2.md` | Guía de cambios que rompen compatibilidad de la generación 0.2 (§0–§12 hasta `0.2.1-alpha.1`; **§13 cubre los 19 seams de `0.2.1-alpha.2`**) |
+| `references/mirror-scope-decision.md` | Registro de decisión sobre el alcance del espejo: por qué no se recorta por "cero referencias", con el script de medición reproducible |
 
 ## CLI toolchain
 

package/README-hi.md

@@ -1,12 +1,15 @@
 <div align="center">
 
 # 🐳 dsh-plugin-guide
-- **1024 स्टोर चैनल**: एक बार `npm i -g dsh1024`, फिर `dsh1024 plugin --profile web add dsh-plugin-guide` ([deepseek1024.com](https://deepseek1024.com) इंस्टॉल रैंकिंग में गिना जाता है)।
 
 **[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) प्लगइन बनाने के लिए आपकी ज़रूरत की हर चीज़।**
 
 *आधिकारिक दस्तावेज़ संग्रह · Cordis प्राइमर · सामुदायिक गहन-विश्लेषण · युद्ध-परीक्षित नुकसान · agent skill · CLI टूलचेन*
 
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -27,6 +30,22 @@
 
 **📖 इसे वेबसाइट के रूप में पढ़ना चाहें?** [perrylink.github.io/dsh-plugin-guide](https://perrylink.github.io/dsh-plugin-guide/) — हर अध्याय अपने पृष्ठ पर, साथ ही असिस्टेंट के लिए मशीन-पठनीय [llms.txt](https://perrylink.github.io/dsh-plugin-guide/llms.txt)।
 
+## Why not just read the official docs?
+
+क्योंकि वे उसके लिए लिखे गए हैं जिसे पहले से पता है कौन-सा पृष्ठ खोलना है, और DSH **हर 1.7–2.8 दिन में एक प्रीरिलीज़** जारी करता है जिसमें संगतता तोड़ने वाले बदलाव होते हैं। यह प्लगइन वही तीन अंतराल भरता है जो सबसे अधिक समय लेते हैं:
+
+| अंतराल | यह प्लगइन क्या जोड़ता है |
+|---|---|
+| **"मैं किस संस्करण के लिए विकसित कर रहा हूँ?"** | एक [संस्करण मैट्रिक्स](guide/version-matrix.md): चार भिन्न मान जो स्वयं को "latest" कहते हैं, उप-पैकेजों के जमे हुए `latest` टैग, संगतता-भंग बिंदु, और `peerDependencies` रेंज कैसे चुनें। **कोई स्थिर पंक्ति नहीं है** — हर प्रकाशित संस्करण प्रीरिलीज़ है। |
+| **"यह संस्करण क्या तोड़ता है?"** | एक [माइग्रेशन गाइड](guide/migration-0.2.md) जो `0.1.6-alpha.2` → `0.2.1-alpha.2` को **उद्धरण-योग्य seams** के रूप में देता है, प्रत्येक में लक्षण *और* समाधान तथा आधिकारिक स्रोत — जिसमें एक डेटा-हानि जोखिम भी शामिल है। |
+| **"मेरा प्लगइन वास्तव में सही है?"** | एक [शून्य-निर्भरता CLI](SKILL.md) (`dsh-plugin-dev new / check / verify`) और आधिकारिक दस्तावेज़ों का [शब्दशः ऑफ़लाइन प्रतिबिंब](references/official-docs/), ताकि एजेंट अनुमान के बजाय सटीक पृष्ठ उद्धृत करे। |
+
+**60 सेकंड में सत्यापित करें:**
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -72,6 +91,10 @@ content counts as stated in the README (What you get)
 - **सामुदायिक गहन-विश्लेषण** — 114 सामुदायिक रिपॉज़िटरी संग्रहीत (15 गहन-विश्लेषित), साथ ही पूर्ण स्रोत सूची जहाँ हर तथ्य अपने मूल से जुड़ा है।
 - **CLI टूलचेन** — `dsh-plugin-dev new / check / verify`: DSH प्लगइन स्कैफ़ोल्ड करना, स्थैतिक जाँच और पैक-सत्यापन; हर जाँच उस skill अनुभाग से जुड़ती है जिसे वह लागू करती है।
 
+- **संस्करण अनुकूलनशीलता** — [guide/version-matrix.md](guide/version-matrix.md): चार "latest" मान, जमे हुए उप-पैकेज टैग, संगतता-भंग बिंदु, peer रेंज का चयन और `0.2.1-alpha.2` के 19 बदलाव।
+- **टूलचेन राउटर** — [guide/family-toolchain.md](guide/family-toolchain.md): कौन-सा प्रश्न किस टूल का है, `dsh-plugin-doctor` की पूरी 33-जाँच सूची, और इस रिपॉज़िटरी की 16 जाँचों से तुलना।
+- **मिरर स्कोप निर्णय** — [references/mirror-scope-decision.md](references/mirror-scope-decision.md): "संदर्भ-रहित सामग्री हटाकर 80% बचाने" का सुझाव दोबारा मापने पर **टिकता नहीं**।
+- **आधिकारिक skill का सार** — [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md): आधिकारिक `cordis-plugin-development` skill के निषेध, प्रदर्शन मेटाडेटा और UI/प्रदर्शन नियम।
 ## Knowledge base
 
 | Path | यह क्या है |
@@ -89,6 +112,10 @@ content counts as stated in the README (What you get)
 | `bin/` · `src/cli/` · `dist/` | `dsh-plugin-dev` CLI: स्कैफ़ोल्डर, जाँचकर्ता, सत्यापक (TypeScript, tsdown-बंडल) |
 | `templates/` | TS + JS स्कैफ़ोल्ड कंकाल: अनुबंध टेम्प्लेट, Config, टेस्ट, cordis.patch.yml, पाँच-भाषा README |
 | `downloads/` | कच्चे स्नैपशॉट — `scripts/` से उत्पन्न, कमिट नहीं |
+| `guide/version-matrix.md` | **संस्करण अनुकूलनशीलता मैट्रिक्स**: चार "latest" मान, जमे हुए टैग, संगतता-भंग बिंदु, peer रेंज चयन, सत्र-प्रारूप वंशावली और `0.2.1-alpha.2` के 19 बदलाव |
+| `guide/family-toolchain.md` | **टूलचेन राउटर**: प्रश्न → स्वामी → उद्धरण-योग्य कलाकृति; `dsh-plugin-doctor` की 33-जाँच सूची और इस रिपॉज़िटरी की 16 जाँचों से तुलना |
+| `guide/migration-0.2.md` | 0.2 पीढ़ी के संगतता-भंग बदलावों की माइग्रेशन गाइड (§0–§12 `0.2.1-alpha.1` तक; **§13 `0.2.1-alpha.2` के 19 seams**) |
+| `references/mirror-scope-decision.md` | मिरर स्कोप निर्णय रिकॉर्ड: "शून्य संदर्भ" के आधार पर कटौती क्यों नहीं, साथ में पुनरुत्पाद्य मापन स्क्रिप्ट |
 
 ## CLI toolchain
 

package/README-pt.md

@@ -1,12 +1,15 @@
 <div align="center">
 
 # 🐳 dsh-plugin-guide
-- **Canal 1024 store**: `npm i -g dsh1024` uma vez, depois `dsh1024 plugin --profile web add dsh-plugin-guide` (conta para o ranking de instalações do [deepseek1024.com](https://deepseek1024.com)).
 
 **Tudo o que você precisa para construir plugins do [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).**
 
 *Arquivo de documentação oficial · primer de Cordis · deep-dives da comunidade · armadilhas testadas em batalha · agent skill · toolchain CLI*
 
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -27,6 +30,22 @@
 
 **📖 Prefere ler como site?** [perrylink.github.io/dsh-plugin-guide](https://perrylink.github.io/dsh-plugin-guide/) — cada capítulo em sua própria página, além de um [llms.txt](https://perrylink.github.io/dsh-plugin-guide/llms.txt) legível por máquina para assistentes.
 
+## Why not just read the official docs?
+
+Porque ela é escrita para quem já sabe qual página abrir, e o DSH publica **uma versão preliminar a cada 1,7–2,8 dias** com mudanças que quebram compatibilidade. Este plugin cobre as três lacunas que mais custam tempo:
+
+| Lacuna | O que este plugin acrescenta |
+|---|---|
+| **"Contra qual versão estou desenvolvendo?"** | Uma [matriz de versões](guide/version-matrix.md): os quatro valores que se chamam "latest", as tags `latest` congeladas dos subpacotes, as falhas de compatibilidade e como escolher um intervalo em `peerDependencies`. **Não existe linha estável** — toda versão publicada é preliminar. |
+| **"O que esta versão quebra?"** | Um [guia de migração](guide/migration-0.2.md) que expõe `0.1.6-alpha.2` → `0.2.1-alpha.2` como **seams citáveis**, cada um com sintoma *e* correção e sua fonte oficial — incluindo uma perda de dados e uma mudança que faz os prompts falharem antes de montar a requisição ao modelo. |
+| **"Meu plugin está realmente correto?"** | Uma [CLI sem dependências](SKILL.md) (`dsh-plugin-dev new / check / verify`) e um [espelho literal e offline](references/official-docs/) da documentação oficial, para o agente citar a página exata. |
+
+**Comprove em 60 segundos:**
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -72,6 +91,10 @@ O `dsh-plugin-guide` é a base de conhecimento de desenvolvimento de plugins DSH
 - **Deep-dives da comunidade** — 114 repositórios da comunidade arquivados (15 com deep-dive), mais um índice fonte completo onde cada fato aponta para sua origem.
 - **Toolchain CLI** — `dsh-plugin-dev new / check / verify`: gerar, verificar estaticamente e validar o empacotamento de plugins DSH; cada check aponta para a seção da skill que ele aplica.
 
+- **Adaptabilidade de versão** — [guide/version-matrix.md](guide/version-matrix.md): os quatro valores "latest", tags `latest` congeladas, falhas de compatibilidade, escolha do intervalo de peers e as 19 mudanças de `0.2.1-alpha.2`.
+- **Roteador da cadeia de ferramentas** — [guide/family-toolchain.md](guide/family-toolchain.md): qual ferramenta responde a cada pergunta, o catálogo completo de 33 verificações do `dsh-plugin-doctor` e o cruzamento com as 16 deste repositório.
+- **Decisão sobre o escopo do espelho** — [references/mirror-scope-decision.md](references/mirror-scope-decision.md): por que "remover o não referenciado para economizar 80%" **não se sustenta** ao medir de novo.
+- **Destilado da skill oficial** — [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md): proibições, metadados de apresentação e regras de UI/desempenho da skill oficial `cordis-plugin-development`.
 ## Knowledge base
 
 | Path | O que é |
@@ -89,6 +112,10 @@ O `dsh-plugin-guide` é a base de conhecimento de desenvolvimento de plugins DSH
 | `bin/` · `src/cli/` · `dist/` | O CLI `dsh-plugin-dev`: scaffolder, checker, verifier (TypeScript, empacotado com tsdown) |
 | `templates/` | Esqueletos TS + JS: modelo de contrato, Config, tests, cordis.patch.yml, READMEs em cinco idiomas |
 | `downloads/` | Instantâneas cruas — geradas por `scripts/`, não commitadas |
+| `guide/version-matrix.md` | **Matriz de adaptabilidade de versão**: os quatro valores "latest", tags congeladas, falhas de compatibilidade, seleção de intervalo de peers, linhagem do formato de sessão e as 19 mudanças de `0.2.1-alpha.2` |
+| `guide/family-toolchain.md` | **Roteador da cadeia de ferramentas**: pergunta → responsável → artefato citável; catálogo completo de 33 verificações do `dsh-plugin-doctor` e cruzamento com as 16 deste repositório |
+| `guide/migration-0.2.md` | Guia de mudanças que quebram compatibilidade da geração 0.2 (§0–§12 até `0.2.1-alpha.1`; **§13 cobre os 19 seams de `0.2.1-alpha.2`**) |
+| `references/mirror-scope-decision.md` | Registro de decisão sobre o escopo do espelho: por que não se recorta por "zero referências", com o script de medição reproduzível |
 
 ## CLI toolchain
 

package/README-zh.md

@@ -1,7 +1,6 @@
 <div align="center">
 
 # 🐳 dsh-plugin-guide
-- **1024 商店渠道**：先 `npm i -g dsh1024`，再 `dsh1024 plugin --profile web add dsh-plugin-guide`（计入 [deepseek1024.com](https://deepseek1024.com) 安装排行）。
 
 **构建 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件所需的一切。**
 
@@ -9,6 +8,10 @@
 
 > **官方仓库。** 本仓库是 dsh-plugin-guide 的唯一官方仓库，由 PerryLink 维护。其他账号下的同名仓库与本项目无关。
 
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
@@ -29,6 +32,22 @@
 
 **📖 想在网页上读？** [perrylink.github.io/dsh-plugin-guide](https://perrylink.github.io/dsh-plugin-guide/) —— 每章独立成页，另有给助手用的机器可读 [llms.txt](https://perrylink.github.io/dsh-plugin-guide/llms.txt)。
 
+## Why not just read the official docs?
+
+因为官方文档是写给"已经知道该翻哪一页"的人的，而 DSH **每 1.7–2.8 天发一个 prerelease**，且带破坏性变更。本插件补的正是最耗时间的三处缺口：
+
+| 缺口 | 本插件补什么 |
+|---|---|
+| **"我到底在对着哪一版开发？"** | [版本矩阵](guide/version-matrix.md)：四个都自称"最新"的值、子包 `latest` 冻结陷阱、破坏性变更断层，以及 `peerDependencies` 区间怎么选。**不存在稳定版**——所有已发布版本都是 prerelease。 |
+| **"这一版破坏了什么？"** | [迁移指南](guide/migration-0.2.md)：把 `0.1.6-alpha.2` → `0.2.1-alpha.2` 整理成**可引用的 seam**，每条含症状*与*修法并附官方出处——其中包括一处数据丢失风险和一处"模型请求还没发出就失败"的变更。 |
+| **"我的插件真的对吗？"** | [零依赖 CLI](SKILL.md)（`dsh-plugin-dev new / check / verify`）+ [官方文档逐字离线镜像](references/official-docs/)，让 agent 能引确切页面而不是靠猜。 |
+
+**60 秒自证：**
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -75,6 +94,9 @@ content counts as stated in the README (What you get)
 - **社区深读** —— 归档 114 个社区仓库（15 个深读），外加每条事实都链回出处的完整来源索引。
 - **CLI 工具链** —— `dsh-plugin-dev new / check / verify`：脚手架、静态检查、打包验证 DSH 插件；每个检查项都链回它强制执行的技能章节。
 
+- **家族工具链路由** —— [guide/family-toolchain.md](guide/family-toolchain.md)：哪个工具负责哪个问题、`dsh-plugin-doctor` 33 项检查全表，以及与本库 16 项检查的交叉对照。
+- **镜像范围决策** —— [references/mirror-scope-decision.md](references/mirror-scope-decision.md)：为什么"删掉零引用内容以省 80% 体积"经复测**不成立**（它们被本库自己声明的宽 glob 覆盖）。
+- **官方自带技能要点** —— [references/official-plugin-dev-skill.md](references/official-plugin-dev-skill.md)：官方 `cordis-plugin-development` 技能的禁则、展示元数据清单与 UI/性能规则。
 ## Knowledge base
 
 | Path | 是什么 |
@@ -93,6 +115,9 @@ content counts as stated in the README (What you get)
 | `bin/` · `src/cli/` · `dist/` | `dsh-plugin-dev` CLI：脚手架、检查器、验证器（TypeScript，tsdown 打包） |
 | `templates/` | TS + JS 脚手架骨架：契约模板、Config、tests、cordis.patch.yml、五语 README |
 | `downloads/` | 原始快照 —— 由 `scripts/` 生成、不入库 |
+| `guide/family-toolchain.md` | **家族工具链路由**：问题→所有者→可引用产物；`dsh-plugin-doctor` 33 项检查全表与裁定语义；本库 16 项检查的交叉对照 |
+| `guide/migration-0.2.md` | 0.2 世代破坏性变更迁移指南（§0–§12 覆盖到 `0.2.1-alpha.1`，**§13 覆盖 `0.2.1-alpha.2` 的 19 个 seam**） |
+| `references/mirror-scope-decision.md` | 镜像范围决策记录：为什么不按"零引用"裁剪（附可复跑的测量脚本） |
 
 ## CLI toolchain
 

package/README.md

@@ -1,15 +1,21 @@
 <div align="center">
 
 # 🐳 dsh-plugin-guide
-- **1024 store channel**: `npm i -g dsh1024` once, then `dsh1024 plugin --profile web add dsh-plugin-guide` (counts toward the [deepseek1024.com](https://deepseek1024.com) install ranking).
+
+**Your agent stops inventing DSH plugin APIs.**
+
+The DeepSeek Harness plugin-development knowledge base, installed *as an agent skill* — official docs, a version-compatibility matrix, migration seams and battle-tested pitfalls, plus a scaffolder/checker CLI.
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+```
+
+Then just ask: *"Use the dsh-plugin-guide skill to build me a … plugin."*
+
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
 [![dshfind](https://dshfind.com/api/badge/PerryLink/dsh-plugin-guide?metric=downloads)](https://dshfind.com/plugins/PerryLink/dsh-plugin-guide?ref=badge)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-plugin-guide/badge)](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-plugin-guide)
 
-**Everything you need to build [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugins.**
-
-*Official docs archive · Cordis primer · community deep-dives · battle-tested pitfalls · agent skill · CLI toolchain*
-
 > **Official repository.** This is the only official repository of dsh-plugin-guide, maintained by PerryLink. Same-name repositories under other accounts are not affiliated.
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
@@ -28,8 +34,28 @@
 
 ---
 
+## Why not just read the official docs?
+
+Because the official docs are written for someone who already knows which page to open, and DSH ships a **prerelease every 1.7–2.8 days** with breaking changes. This plugin closes the three gaps that costs authors the most time:
+
+| Gap | What this plugin adds |
+|---|---|
+| **"Which DSH am I even targeting?"** | A [version matrix](guide/version-matrix.md): the four different values that all call themselves "latest", the frozen sub-package `latest` tags, the breaking-change seams, and how to pick a `peerDependencies` range. **There is no stable line** — every published version is a prerelease. |
+| **"What does this break?"** | A [migration guide](guide/migration-0.2.md) covering `0.1.6-alpha.2` → `0.2.1-alpha.2` as **citable seams** with symptom *and* fix, each with its official source — including a data-loss hazard and a change that makes prompts fail before a model request is built. |
+| **"Is my plugin actually correct?"** | A [zero-dependency CLI](SKILL.md) (`dsh-plugin-dev new / check / verify`) plus an [offline verbatim mirror](references/official-docs/) of the official docs, so your agent can cite the exact page instead of guessing. |
+
+**Prove it works in 60 seconds:**
+
+```sh
+dsh plugin --profile web add dsh-plugin-guide
+npx dsh-plugin-guide new hello-plugin      # scaffold a plugin
+cd hello-plugin && npx dsh-plugin-guide check --json   # 16 static checks
+```
+
 **📖 Prefer reading it as a site?** [perrylink.github.io/dsh-plugin-guide](https://perrylink.github.io/dsh-plugin-guide/) — every chapter as its own page, plus a machine-readable [llms.txt](https://perrylink.github.io/dsh-plugin-guide/llms.txt) for assistants.
 
+**Also on the 1024 store channel:** `npm i -g dsh1024`, then `dsh1024 plugin --profile web add dsh-plugin-guide` (counts toward the [deepseek1024.com](https://deepseek1024.com) install ranking).
+
 <!-- star-cta -->
 ## ⭐ 如果它帮到了你
 
@@ -44,6 +70,7 @@ Everything you need to build [DeepSeek Harness](https://github.com/deepseek-ai/d
 
 Official docs archive · Cordis primer · community deep-dives · battle-tested pitfalls · agent skill · CLI toolchain
 
+
 ![Terminal demo of dsh-plugin-guide: dsh-plugin-guide — install the bundle, then run the checker](https://raw.githubusercontent.com/PerryLink/dsh-plugin-guide/main/docs/assets/dsh-plugin-guide-demo.png)
 
 ![Animated terminal demo of dsh-plugin-guide](https://raw.githubusercontent.com/PerryLink/dsh-plugin-guide/main/docs/assets/dsh-plugin-guide-demo.gif)
@@ -137,16 +164,19 @@ The CLI has no hardcoded tunables — each is a flag or an environment variable.
 ## Quick start
 
 ```sh
-# 1. install the bundle into your profile
-dsh plugin --profile web add github:PerryLink/dsh-plugin-guide
-
-# or from npm (published releases)
+# 1. install the bundle into your profile — npm first
 dsh plugin --profile web add dsh-plugin-guide
 
 # 2. restart and verify the row
 dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-guide'
 ```
 
+⚠️ **Use the npm channel, not the git channel, for a first install.** The git channel pulls source, and
+`dist/` is not committed, so pnpm has to run this package's `prepare` build script — which pnpm 10+ blocks
+until you explicitly allowlist it (`allowBuilds`). That is a documented pitfall of git installs, not a
+defect, but it makes the git channel a poor first experience. See [Install & uninstall](#install--uninstall)
+for the git and tarball channels when you specifically want an unreleased commit.
+
 Then just ask your agent: *"Use the dsh-plugin-guide skill to build me a … plugin."*
 
 Or drive the CLI directly:
@@ -159,8 +189,8 @@ npx dsh-plugin-guide verify                      # pack + clean-profile smoke
 
 ## Install & uninstall
 
-- **git channel** (latest `main`): `dsh plugin --profile web add github:PerryLink/dsh-plugin-guide#<sha>` — pin a commit for reproducibility; the entry point is plain ESM JS, no build step.
-- **npm channel** (published releases): `dsh plugin --profile web add dsh-plugin-guide`.
+- **npm channel** (published releases — **the default; start here**): `dsh plugin --profile web add dsh-plugin-guide`. The published tarball already contains `dist/`, so no build step runs.
+- **git channel** (latest `main`, or an unreleased commit): `dsh plugin --profile web add github:PerryLink/dsh-plugin-guide#<sha>` — pin a commit for reproducibility. ⚠️ `dist/` is not committed, so pnpm must run this package's `prepare` and will refuse until the build is allowlisted; add it to the profile's `allowBuilds` (see [publish.md](references/official-docs/docs/user/develop/basic/publish.md)).
 - **tarball channel**: `pnpm pack` in this repo, then `dsh plugin --profile web add ./dsh-plugin-guide-<version>.tgz`.
 - **uninstall**: `dsh plugin --profile web remove dsh-plugin-guide`.
 

package/SKILL.md

@@ -64,6 +64,9 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - **新 LLM 提供商**：`docs/user/develop/practice/llm-adapter.md`（StreamChunk 协议）。
 - **UI 插件（Web）**：`references/official-plugin-dev-skill.md` §3.2 + `docs/subsystems/slots.md`、`sidebar-right.md`、`client-modules.md`、`web-client.md`、**`docs/ui-radius.md`**（注意 `ui-radius` 在 `docs/` 顶层，**不在** `docs/subsystems/` 下）；Chat 行业务节点用 `ctx.uiConversation.events.register()` + `conversation.chat.node` slot。
 - **插件配置表单**：`docs/subsystems/settings.md`（已改名 "Plugin Configuration Forms"）+ `docs/cookbook/adding-a-settings-card.md`（已重写）。
+- **斜杠命令**：`docs/subsystems/commands.md`——命令是**面向人**的入口，与工具（面向模型）是两套注册面；只加工具而想让用户能敲 `/x` 时要另注册命令。
+- **权限 / 审批 / 沙箱**：`docs/subsystems/approval.md`（审批流与 `ask` 决策）+ `docs/subsystems/permission-presets.md`（预设档位）+ `docs/subsystems/sandbox.md`（进程约束及其已知边界：Windows ACL 部分强制）。需要拦截工具调用时读 `docs/cookbook/extension-cookbook.md` 的 permission-gate 范例。
+- **上下文 / 压缩 / 性能**：`docs/subsystems/compaction.md`（压缩缝与阈值语义）+ `docs/subsystems/spill.md`（溢出存储：只负责存储，无保留策略、无检索 API）；`ctx` 自身的 API 面见 `docs/cordis-api/context.md`（**没有** subsystems 版的 context 页）。per-session 派生状态用 `ctx.sessionProjections`（见 §4.8 第 5 条）。
 - **打包/发布**：`docs/user/develop/basic/publish.md`（bundle/profile、层顺序、多 patch 数组、peer 解析、git 安装坑）。
 - **升级/迁移**：`guide/version-matrix.md`（**版本适配矩阵：先读这个**——五个"最新"、子包 `latest` 冻结、破坏性变更断层、peer 区间选择、会话格式 V0→V4）→ `guide/migration-0.2.md`（本库综述，0.1.6→0.2.1-alpha.1）→ `docs/upgrade-guide/**`（官方逐版本迁移指南）+ `docs/persistence-changes/**`（持久化类型变更记录）+ `docs/session-format-status.md`（会话格式版本权威）。⚠️ **目标宿主是 `0.2.1-alpha.2` 或更新时**：`version-matrix.md` §3 列了该版落的 **19 条破坏性变更**（`webRuntime`→`webStartup`、`mode: both` 被拒、`backgroundMode`/`run_in_background` 移除、`{{cwd}}` 移除、`BundleInfo` 新增必填字段、`dsh plugin --profile` 位置强制等），`migration-0.2.md` **尚未并入**。
 - **查服务/事件精确签名**：**优先用会话内 inspection**（`cordis_inspect_list` / `cordis_inspect_query`：Service / Event / Config / Tool / Slots / Theme），其次 `docs/subsystems/*.md` 生成式 Cordis API 区 + `docs/cordis-api/*`；**不要自造第二份静态清单**。站点 URL ↔ 本地副本对照见 `guide/links.md`，社区链接完整清单见 `references/community-ecosystem.md`。

package/dist/dsh-plugin-dev.js

@@ -277,82 +277,82 @@ const SKILL_SECTIONS = {
 	"patch-valid": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§2.2",
-		heading: "两个概念、两种清单（bundle manifest）"
+		heading: "三个概念、三种清单（package.json 的 `dsh` 键）"
 	},
 	"patch-ids-unique": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§2.3",
-		heading: "配置分层顺序（按 id 整行覆盖）"
+		heading: "配置分层顺序（后层覆盖前层，逐行按 `id` 整段替换 config）"
 	},
 	"manifest-bundle-patch": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§2.2",
-		heading: "bundle 最小结构（dsh.bundle.patch）"
+		heading: "三个概念、三种清单（package.json 的 `dsh` 键）"
 	},
 	"manifest-main": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§7.3",
-		heading: "main/types 指向 lib 产物"
+		heading: "常见坑清单"
 	},
 	"manifest-peers": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§7.3",
-		heading: "cordis 双副本与 peer 对齐宿主"
+		heading: "常见坑清单"
 	},
 	"manifest-engines": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§8",
-		heading: "规范与质量门禁（Node 版本）"
+		heading: "规范与质量门禁（对插件作者的实际影响）"
 	},
 	"manifest-files": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§7.1",
-		heading: "files 白名单与构建产物"
+		heading: "从 GitHub 安装的 build-script 坑"
 	},
 	"manifest-package-manager": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§8",
-		heading: "packageManager 固定 pnpm"
+		heading: "规范与质量门禁（对插件作者的实际影响）"
 	},
 	"display-meta": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§7.0.1",
-		heading: "展示元数据与图标（locale meta + 导出 icon）"
+		heading: "展示元数据与图标（0.2 世代新增的硬性交付项）"
 	},
 	"readme-five-langs": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§8",
-		heading: "文档双语/多语成对"
+		heading: "规范与质量门禁（对插件作者的实际影响）"
 	},
 	"readme-consistency": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§8",
-		heading: "五语 README 同步"
+		heading: "规范与质量门禁（对插件作者的实际影响）"
 	},
 	"redline-persona-role": {
-		file: "SKILL.md",
-		section: "§边界",
-		heading: "注入提示词段落以角色句开头、保持短小"
+		file: "guide/plugin-dev-guide.md",
+		section: "§3.7",
+		heading: "仓库级红线（写进 AGENTS.md，违反会挂门禁）"
 	},
 	"redline-waterfall-next": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§3.5",
-		heading: "waterfall 铁律：必须调用 next()"
+		heading: "事件（Events）"
 	},
 	"redline-no-hardcoded-tunables": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§3.6",
-		heading: "配置 Schema 化、不硬编码可调参数"
+		heading: "配置（Config）"
 	},
 	"redline-effect-registration": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§3.3",
-		heading: "注册即 effect（disposer 可逆）"
+		heading: "注册即 effect"
 	},
 	"redline-async-apply-registration": {
 		file: "guide/plugin-dev-guide.md",
-		section: "§3.3",
-		heading: "async apply 首个 await 之后不得注册（卸载窗口竞态）"
+		section: "§3.3.1",
+		heading: "async `apply()` 的注册顺序（最容易写成静默缺陷的一条）"
 	}
 };
 /** Fallback citation for any check id not in the table. */

package/guide/plugin-dev-guide.md

@@ -148,6 +148,37 @@ ctx.effect(() => { const t = setInterval(...); return () => clearInterval(t) })
 
 框架代管：`ctx.on` / 服务 `register()` / `ctx.effect()`。`HMR`（`@deepseek-ai/cordis-plugin-hmr`）正因注册全部可逆而成立。
 
+#### 3.3.1 ⚠️ async `apply()` 的注册顺序（最容易写成静默缺陷的一条）
+
+`apply` **可以是 async**，但**第一个 `await` 之后再做注册是错的**：从 `await` 返回到注册完成之间存在一个
+卸载窗口——插件已开始 `UNLOADING`、effect 却还没建立，于是那次注册**既不会被记入 fiber 的 disposer 集合，
+也不会报错**。表现为"插件装了、日志全绿、能力却时有时无"（高负载下才复现）。
+
+**规则：注册必须在第一个 `await` 之前完成。** 需要异步数据才能决定注册内容时，先取数据再注册：
+
+```ts
+// ✅ 正确：await 只用于取数据，注册全部落在 await 之前的同步段之后、但不再 await
+export async function apply(ctx) {
+  const cfg = await loadRemoteConfig()        // 允许 await
+  if (!cfg.enabled) return                    // 允许提前返回
+  ctx.effect(() => ctx.tools.register(buildTool(cfg)))   // 注册紧随其后，不再 await
+}
+```
+
+```ts
+// ❌ 错误：await 之后才注册，卸载窗口内注册会丢
+export async function apply(ctx) {
+  ctx.on('a', handlerA)
+  await something()
+  ctx.tools.register(toolB)                  // ← 这次注册可能永远不会被撤销
+}
+```
+
+**自查**：`dsh-plugin-dev check` 的 `redline-async-apply-registration` 就是本条的机械检测
+（家族内唯一检测器，见 [`family-toolchain.md`](family-toolchain.md) §3.2）。
+**官方契约**：`apply` 返回 disposer 函数 / `null` / `undefined` / `Promise<disposer>` / （异步）可迭代——
+async `apply` 合法，但**必须返回 `Promise<disposer>`**，不能靠"await 之后再注册"来隐式注册。
+
 ### 3.4 服务（Service）
 
 - **消费**：`export const inject = ['tools']` → `apply` 里 `ctx.tools` 已就绪。可选依赖：不写 inject，用 `ctx.get('metrics')?.method()`。
@@ -200,9 +231,10 @@ export function apply(ctx: Context, config: Config) { /* config 已校验+补默
 
 1. **注册即 effect**：所有贡献走 `ctx.effect()` / `ctx.on()`；registry 的 `register()` 返回 disposer。
 2. **waterfall 监听器必须调 `next()`**。
-3. **模型可见 ⟺ 已记录**（Model-visible ⟺ logged）：任何进入模型请求的内容必须能从会话日志重建；新增模型可见输入必须新增会话事件。运行时不变式会断言这一点。
+3. **模型可见 ⟺ 已记录**（Model-visible ⟺ logged）：任何进入模型请求的内容必须能从会话日志重建；新增模型可见输入必须新增会话事件。~~运行时不变式会断言这一点~~ —— ⚠️ **该强制手段已于 `0.2.1-alpha.1` 随运行时 invariants 整体移除**（`upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants`），所以这条**现在完全靠评审与自觉**，没有任何机械兜底。见 §3.6 与 [`migration-0.2.md`](migration-0.2.md) §4。
 4. **跨边界 opaque id 用 branded**：`Branded<B>`（`dsh-brand`，纯类型、零运行时依赖），从不裸 `string`；构造走 per-type factory（`SessionId` / `CallId` / `JobId` / `GoalId` 等），防止不同 id 在类型层互换。
 5. **会话事件版本规则**：`SessionEventMap` 成员默认 required-on-read——不认识该事件类型的 build 一律拒绝整份日志，除非该事件带信封的 `ignorable: true`。**插件不得新增事件类型**（见 §3.5 红线）：`Session.append()` 写不了信封标记。只有结构格式变更才 bump `SESSION_FORMAT_VERSION`（当前 **4**；V3→V4 把 results 提升为 tool-role 消息、把消息 source 改为生产者自有的 `source.kind`，V3 读方拒绝 V4 日志）。新增**模型可见输入**由宿主侧事件承担（红线 3），插件只消费。
+6. **注入的提示词段落要短、且以角色句开头**：插件写进系统提示词的段落（`systemPrompt.section()` 的正文）**第一句应当是说明"你是谁/做什么"的短句**，整段保持精简。原因有二：它是每轮请求都付费的固定前缀；而且段落开头若不是完整句子，模型会把后续内容当作它的延续来读。**自查**：`dsh-plugin-dev check` 的 `redline-persona-role`（段落首句需以 `。.?!` 收尾、首句 ≤200 字符、整段 ≤600 字符）。**这条是"工程卫生"而非官方硬门禁**——官方文档没有对应条款，别在 README 里把它说成官方要求。
 
 ---
 
@@ -306,6 +338,70 @@ declare module '@deepseek-ai/dsh-llm' {
 
 **工具的 `parameters` 是 DSH 自己的方言，不是 JSON Schema**；Remote 服务调用是**位置参数**而不是对象参数（`get()` 能用，最有欺骗性）；往 `ctx` 上写**未声明**的属性会抛错并可能静默杀掉整个插件的激活——可选服务一律 `ctx.get(name)`，**`ctx.<service>` 只对自己 `inject` 里声明过的服务合法**。
 
+### 4.9 插件内如何发布一个 skill（本仓库就是参考实现）
+
+一个插件可以**自己携带一份 agent 技能**——这是把"知识/流程"交付给宿主的标准做法，也是本仓库
+（`dsh-plugin-guide`）唯一在做的事。机制曾经在社区资料里被写错成"systemPrompt section + 工具注册"，
+**那不是这条路**。
+
+**契约**（官方 `docs/subsystems/skills.md`）：
+
+- `ctx.skills` 是 **provider 注册表**，注册是**同步**的，必须在 `apply()` 内完成。
+- 插件走的是**运行时贡献**入口 `ctx.skills.register(definition)`，其类型为
+  `SkillRegistration = Omit<SkillDefinition, 'invocation' | 'provider'> & { invocation?; provider? }`
+  ——`invocation` 省略即模型与用户两侧都可见，`provider` 省略即落到注册表自有的 runtime provider。
+- **返回的是 Cordis effect disposer**：撤销该贡献并使发现缓存失效。所以照例写成
+  `ctx.effect(() => ctx.skills.register({...}))`。
+- 要携带随包资料，给 **`resourceBase: { kind: 'directory', path: <包目录> }`**；技能正文里的
+  `./guide/...`、`./references/...` 相对路径就按该目录解析。**这是"渐进披露"得以成立的关键**：
+  技能正文只放路由，重资料留在包里按需读，不必一次塞进模型上下文。
+
+**最小可用实现**（取自本仓库 `index.js`，可直接抄）：
+
+```js
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'my-skill-plugin'
+export const inject = ['skills']
+
+const packageRoot = dirname(fileURLToPath(import.meta.url))
+
+export function apply(ctx) {
+  const { description, body } = splitFrontmatter(readFileSync(join(packageRoot, 'SKILL.md'), 'utf8'))
+  ctx.effect(() =>
+    ctx.skills.register({
+      name: 'my-skill-plugin',
+      source: 'bundled',
+      description,                                     // 决定"何时被加载"
+      content: body,                                   // 技能正文
+      resourceBase: { kind: 'directory', path: packageRoot },
+    }),
+  )
+}
+```
+
+**四个实测要点**（每一条都踩过）：
+
+1. **`description` 就是触发器，要写"何时使用"而不是"这是什么"。** 宿主只把 name + description 放进目录给模型挑，
+   所以写 `Use when developing, reviewing, packaging, debugging, or answering questions about …`
+   这类带场景动词的句子，而不是名词短语。
+2. **解析 frontmatter 要容忍 CRLF。** 用精确的 `startsWith('---\n')` 会在 Windows 检出（`core.autocrlf=true`）
+   上失配，后果是**静默退化**：描述掉回兜底字符串（技能变得不易被选中），且**整份文件连同 frontmatter 被当成技能正文**注入。
+   本仓库为此加了 `.gitattributes`（`* text=auto eol=lf`），并把解析改成行尾无关。
+3. **截断 frontmatter 与裁掉正文前导空行是两件事。** 只做前者，正文会以换行开头；宿主的 filesystem provider
+   自己会裁，但**不是所有 provider 都裁**，自己裁更稳。
+4. **单测要真的加载入口模块。** `index.js` 长期零测试，缺陷因此活到发布之后；测试只需一个
+   `{ effect, skills: { register } }` 桩，就能断言"注册的 name、用的是 frontmatter 描述还是兜底、
+   `resourceBase` 是否指向包目录"。本仓库 `tests/entry.test.ts` 就是这 8 条断言。
+
+**与"工具"的区别**：注册工具（`ctx.tools.register`）会让**每一次请求**都付该工具定义的 token；
+注册技能只在模型**按描述选中**它时才加载正文。给 agent 交付"资料/流程"用技能，交付"可执行动作"才用工具。
+
+**相关**：`references/official-plugin-dev-skill.md`（官方自带开发技能的要点）、
+`references/official-docs/docs/subsystems/skills.md`（完整契约与 ranked local discovery 表）。
+
 ---
 
 ## 5. 能力分层：Service Definition / Provider / Consumer
@@ -356,7 +452,7 @@ LLM 适配器同理：继承 `LlmAdapter` 实现 `stream(options)`，`ctx.llm.re
 | 子代理委派 | `ctx.subagents` provider 注册表 + `dsh-tool-subagent`（现有多家 provider：in-process spawn / fork / `dsh-subagent-acp` / `-codex` / `-claude-code` / `-dsh-sdk`） |
 | 多代理编排 | `ctx.workflowEngine` 缝（Definition/Provider/Consumer）+ PTC workflow engine + `workflow`/`ralph` 工具 Consumer |
 | MCP | 每服务器一个插件：发现工具 → `ctx.tools.register()` |
-| Skills | section + 工具注册；调用时 `inject()` 技能内容 |
+| Skills | ⚠️ **不是** section + 工具注册：插件用 **`ctx.skills.register()`** 注册一个运行时技能（`SkillRegistration` = `SkillDefinition` 去掉 `invocation`/`provider`，两者可省略走默认），**在同一 `apply()` 内同步注册**，返回的 disposer 撤销贡献并使发现缓存失效。随包携带资料时给 **`resourceBase: { kind: 'directory', path: <包目录> }`**，技能正文里的 `./...` 相对路径即按该目录解析。官方参考实现是 `dsh-skill-badge`（注册一个不可变的 `bundled` 候选 + 暴露打包资源目录）。**本仓库 `index.js` 是第二个可跑的例子**——见下方 §"插件内如何发布 skill" |
 | 定时任务 | 注册模型可调的调度工具；定时器 → 空闲 `followup(source:{kind:'cron'})` / 忙碌 `inject()` |
 | 遥测/回放 | `session/event` → JSONL；回放 = `sessions.create(id, {seed})` |
 | 上报通道（0.2 新增） | `ctx.otel`：`createEventReporter(options)` / `createSessionLogReporter(options)`——自带传输与批处理，未用时**不分配** provider/transport；**消费者必须在自己 fiber 释放时 drain 通道** |

package/guide/quick-reference.es.md

@@ -181,3 +181,5 @@ Documentación comunitaria de desarrollo — plantillas/tutoriales/errores, list
 - Investigación del repo: `references/harness-repo.md`
 - Comunidad/ecosistema: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
 - Todas las URLs de fuentes: `references/sources.md`
+- [Matriz de versiones](version-matrix.md) — los cuatro valores «latest», etiquetas `latest` congeladas, fallas de compatibilidad y selección de rango de peers.
+- [Lista de migración](migration-0.2.md) — §0–§12 cubren los cambios que rompen compatibilidad, **§13 los 19 seams de `0.2.1-alpha.2`**.

package/guide/quick-reference.hi.md

@@ -181,3 +181,5 @@ Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(
 - रिपो शोध: `references/harness-repo.md`
 - समुदाय/पारिस्थितिकी: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
 - सभी स्रोत URL: `references/sources.md`
+- [संस्करण मैट्रिक्स](version-matrix.md) — चार "latest" मान, जमे हुए `latest` टैग, संगतता-भंग बिंदु और peer रेंज का चयन।
+- [माइग्रेशन सूची](migration-0.2.md) — §0–§12 संगतता-भंग बदलाव, **§13 में `0.2.1-alpha.2` के 19 seams**।

package/guide/quick-reference.pt.md

@@ -181,3 +181,5 @@ Documentação comunitária de desenvolvimento — modelos/tutoriais/armadilhas,
 - Pesquisa do repo: `references/harness-repo.md`
 - Comunidade/ecossistema: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
 - Todas as URLs de fontes: `references/sources.md`
+- [Matriz de versões](version-matrix.md) — os quatro valores "latest", tags `latest` congeladas, falhas de compatibilidade e seleção de intervalo de peers.
+- [Lista de migração](migration-0.2.md) — §0–§12 cobrem as mudanças que quebram compatibilidade, **§13 os 19 seams de `0.2.1-alpha.2`**.