dsh-plugin-guide 0.3.42 → 0.4.0

package/guide/quick-reference.pt.md

@@ -1,185 +0,0 @@
-# Folha de consulta de plugins do DeepSeek Harness
-
-> Referência rápida de uma página. Detalhes: [plugin-dev-guide.md](plugin-dev-guide.md) (chinês) e [references](../references/).
-> Outros idiomas: [English](quick-reference.md) · [中文](quick-reference.zh-CN.md) · [Español](quick-reference.es.md) · [हिन्दी](quick-reference.hi.md)
-
-## Esqueleto do plugin
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = 'my-plugin'          // obrigatório
-export const inject = ['tools']          // serviços necessários; omita se não houver
-
-export interface Config { limit: number }
-export const Config: Schema<Config> = Schema.object({
-  limit: Schema.number().default(10),    // schema Schemastery, não um objeto simples
-})
-
-export function apply(ctx: Context, config: Config) {
-  ctx.effect(() => {                     // registro = efeito, desfeito ao descarregar
-    const timer = setInterval(() => {}, 1000)
-    return () => clearInterval(timer)
-  })
-  ctx.on('tools/result', (exec, result) => { /* ... */ })
-  ctx.tools.register(defineTool({
-    name: 'my_tool',
-    description: '…',
-    parameters: { x: { type: 'string', required: true } },
-    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
-    async execute(args, exec) { return `hi ${args.x}` },  // respeite exec.signal
-  }))
-}
-```
-
-Outras formas: objeto `export default { name, inject, apply }`; classe `class X extends Service { static inject=[...]; constructor(ctx){ super(ctx,'key') } }` (use ao fornecer um serviço).
-
-## API principal do ctx (Cordis)
-
-| Finalidade | API |
-|---|---|
-| Registrar recurso + limpeza | `ctx.effect(() => disposer)` |
-| Ouvir eventos | `ctx.on(name, handler)` (limpeza automática) |
-| Transmissão / sem retorno | `ctx.emit(name, payload)` |
-| Valor com curto-circuito | `ctx.bail(name, input)` (o primeiro não-null/false/undefined vence) |
-| Valor ordenado | `await ctx.serial(name, input)` |
-| Pipeline | `await ctx.waterfall(name, input, init)`; listeners **devem chamar `next()`** |
-| Contextos filhos | `ctx.extend(meta)` / `ctx.isolate(name, label?)` / `ctx.intercept(name, config)` |
-| Montar plugin filho | `ctx.plugin(plugin)` → Fiber; `await fiber.dispose()` |
-| Consulta de serviço opcional | `ctx.get('metrics')?.x()` |
-| Logging | `ctx.logger(name)` |
-
-Ciclo de vida: `PENDING → LOADING → ACTIVE` (apply lança erro → FAILED); `ACTIVE → UNLOADING → DISPOSED`. Se um serviço necessário desaparece, o plugin descarrega; recarrega quando o serviço volta.
-
-## Modos de despacho de eventos (cinco, incluindo bail)
-
-| Modo | await | Ordem | Valor de retorno |
-|---|---|---|---|
-| emit | não | ordem de registro | nenhum |
-| waterfall | não | ordem de registro | sim (**não chamar `next()` causa curto-circuito**) |
-| parallel | sim | paralelo | nenhum |
-| serial | sim | ordem de registro | sim (o primeiro não vazio para) |
-| bail | não | ordem de registro | sim (o primeiro não null/false/undefined curto-circuita e PARA o resto) |
-
-Eventos tipados (declaration merging):
-
-```ts
-declare module '@deepseek-ai/cordis' {
-  interface Events { 'my/event': (p: { id: string }) => void }
-  interface Context { myService: MyService }   // ao fornecer um serviço
-}
-```
-
-## cordis.yml / camadas
-
-```yaml
-# scratch-plugin/cordis.yml (overlay --patch)
-- insert:
-    - id: hello
-      name: '/absolute/path/to/scratch-plugin/src/my-plugin.ts'
-      config: { greeting: 'Hi' }
-
-# bundle: "dsh": {"bundle":{"patch":"./cordis.patch.yml"}} no package.json
-# profile: "dsh": {"profile":{"bundles":["@deepseek-ai/dsh-base","my-bundle"]}}
-# ordem efetiva: bundles → cordis.patch.yml do profile → $DSH_HOME/cordis.patch.yml → --patch
-# sobrescrita por id; a linha config inteira é substituída (sem deep merge) — repita todas as chaves
-# !!js avalia após os serviços injetados ativarem; disabled é avaliado em cada montagem
-```
-
-Comandos: `dsh --profile web` · `dsh --profile headless "task"` · `dsh --profile X --dump-config` · `dsh plugin --profile X add/remove <pkg>` · `pnpm dsh web --patch ./scratch-plugin/cordis.yml`
-
-Canais de instalação (repository-plugin removido em 0811 — restam apenas dois):
-- **plugin bundle** (`"dsh":{"bundle":{"patch":"..."}}`) → `dsh plugin add <pkg>` entra na pilha `dsh.profile.bundles`; efeito após reiniciar.
-- **plugin cordis simples** (sem `dsh.bundle`) → `dsh plugin add <pkg>` instala a dependência + uma linha insert no `cordis.patch.yml` do profile; **HMR de configuração ao vivo**.
-- fonte git: `dsh plugin add "github:owner/repo#<sha>&path:<subdir>"` (fixe o commit; build `prepare` autocontido + `allowBuilds` no `pnpm-workspace.yaml` do profile; npm/tarball dispensa permissão de build).
-
-## Serviços internos comuns (chaves do ctx)
-
-`sessions` registro de sessão · `systemPrompt` montagem de prompts · `tools` registro de ferramentas + pipeline protegido · `agents` registro de agentes · `agentLoop` driver do loop · `llm` registro de adaptadores · `skills` registro de skills · `commands` comandos slash · `approval` aprovação única · `jobs` trabalhos em segundo plano · `fs` seam de sistema de arquivos · `shell` seam de execução bash · `subprocess` seam de subprocessos · `terminals` PTY · `sandbox` seam de confinamento · `codeRuntime` execução de código · `sessionPersistence` persistência · `settings` / `credentials` / `workspaceRegistry` / `goals` / `planMode` / `subagents` / `workflowEngine` / `storage`.
-Lista completa e assinaturas exatas → `references/official-docs/docs/capability-seams.md` + `docs/subsystems/*.md` (regiões Cordis API geradas).
-
-## Pipeline de políticas de ferramentas (ordem de execução)
-
-```
-tools/pre-execute (waterfall, allow|deny|ask) → ctx.tools.guard() (negação monótona)
-→ tools/execute (wrapper; apenas exec.signal substituível) → execute(args, exec)
-→ tools/post-execute (substituir content/value, bloquear, anexar contexto) → finalizeContent
-→ tools/result (somente observação) → tool/result durável (evento de sessão)
-```
-
-Seleção: portões de política → pre-execute; negação irreversível → guard; timeout/retentativas/métricas → execute; transformar resultados → post-execute; auditoria/coleta → result.
-Code Mode: `await tools.<name>(args)` vem de graça; sucesso = valor JSON canônico final; falha = `ToolCallError(name, toolName, message)`.
-
-## Cartões de UI (funções puras! apenas args(+result) — sem I/O/relógio/aleatório)
-
-- `presentCall(args)` → `{card:'generic',title,kind?,rawInput?,content?,locations?}` | `{card:'terminal',title,description?,cwd?}` | `{card:'diff',title,diffs,locations?}`
-- `presentResult(args,{content,isError,meta?})` → generic / terminal / diff / search(`shape:'matches'|'paths'`) / read / web(`kind:'search'|'fetch'`)
-- Metadados de replay: `output.presentationMeta(args, value)` → persistido em `tool/result.meta`
-
-## Modelo de seam de capacidade de três papéis
-
-Definition (`dsh-my-cap`): `export abstract class MyCapService extends Service { constructor(ctx){super(ctx,'myCap')} abstract execute(req): Promise<res> }` + declaration merging de Context.
-Provider (`dsh-my-cap-local`): `export function apply(ctx){ ctx.plugin(class MyCapLocal extends MyCapService {...}) }`.
-Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(defineTool({... execute: args => ctx.myCap.execute(...)}))`.
-Regras: não divida prematuramente; Provider e Consumer nunca dependem um do outro; padrões resolvem explicitamente em `resolve(request): Spec`.
-
-## Essenciais do adaptador LLM
-
-`class MyAdapter extends LlmAdapter { async *stream(options): AsyncIterable<StreamChunk> }` → `ctx.llm.registerAdapter(['provider'], adapter)`.
-Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloco completo) → … → `usage` (antes de finish) → `finish` (último; `reason: {kind:'stop'|'tool-calls'}`). Lance `LlmError` com código estável para campos que você não puder atender.
-
-## Regras rígidas (violações = falhas de gate / comportamento errado)
-
-1. Todo registro passa por `ctx.effect()` / `ctx.on()` / o `register()` de um serviço (retorna disposer). Um registro em outro contexto (ex.: `agent.ctx`) tem **dois donos**: guarde o disposer também no seu próprio effect.
-2. Listeners de waterfall devem chamar `next()`; não chamar causa curto-circuito por design. Ao reescrever uma decisão de `agent/pre-step`, **propague com spread** (`{ ...decision, messages }`) para não perder campos como `startsRequestSeries`.
-3. **O mecanismo mais fraco que basta**: `ctx.tools.restrict()` (só remove) < `ctx.tools.guard()` (só nega) < reescrita por waterfall (depende da ordem) < `system-prompt/assemble` (substitui tudo). Observe resultados finais em `tools/result`; use `tools/post-execute` só para transformar.
-4. Visível-para-o-modelo ⇔ registrado: nova entrada visível exige novo evento de sessão (`SessionEventMap`) — **adicionado pelo host**, não por você (ver regra 10).
-5. Nunca codifique valores ajustáveis (teste: o cordis.yml consegue mudá-los?); má configuração falha em voz alta. Campos editáveis ao vivo usam `Volatile<T>` + `loader/volatile-update` (o namespace do formulário é o id da entrada do perfil).
-6. Pacotes de plugin independentes: cordis é peerDependency com a mesma identidade do host (misturar scoped `@deepseek-ai/cordis` e unscoped divide identidades); ESM; manifesto `dsh.bundle` (`patch` pode ser uma lista ordenada); instalações git precisam de `prepare` + `allowBuilds`; publique `lib/` ou um tarball. Pacotes dsh de instância compartilhada ficam **só em peerDependencies + devDependencies**, nunca em `dependencies` (uma cópia no perfil sombreia o runtime em silêncio). ⚠️ Corrigido: **faixas de peer SÃO aplicadas na instalação** — `dsh plugin add` compara a versão do runtime com a faixa declarada de `@deepseek-ai/dsh-*` e recusa a instalação; apenas `engines.dsh` é declarativo e não aplicado. Uma faixa diz "dá para instalar", não "esta API existe": mantenha a sondagem em runtime (escolha de faixa: `version-matrix.md` §4).
-7. Publique metadados de exibição: `locale/*.json` com `meta.title`/`meta.description` e um `./icon` exportado (SVG/PNG/JPEG/WebP, ≤256 KiB, dentro do pacote). Plugins de subcaminho **nunca** leem o próprio `package.json`.
-8. Documentação bilíngue em pares; descrições/prompts são comportamento; mudanças não triviais levam Agent Note; rode o conjunto mínimo de verificações antes de empurrar (dsh-pre-push-checks).
-9. IDs opacos entre limites são branded (`Branded<B>` de `dsh-brand`), nunca `string` crua.
-10. **Nunca acrescente um evento de sessão com um `type` novo**: membros de `SessionEventMap` são required-on-read — um build que não conhece um tipo recusa todo o log, a menos que o evento carregue a marca `ignorable: true` do envelope, e o `Session.append()` em execução não consegue gravar essa marca (seu terceiro argumento é um `SurfaceIntent` apenas para eventos de superfície). Derive o estado de eventos existentes ou guarde dados do plugin num serviço de storage localizado por inspection. Apenas mudanças de formato estrutural bumpam `SESSION_FORMAT_VERSION` (hoje `4`; a migração V3→V4 eleva resultados de tool a mensagens com papel tool e move os `source` de mensagem para o `source.kind` do produtor). O switch sobre `SessionEvent` continua caindo num `default` documentado — sem `assertNever` (união merge-extensible).
-11. O `source` de `agent.inject()` **não aceita mais** o wrapper retirado `{ kind: 'plugin', plugin: '<name>' }`: declare seu próprio kind via `MessageSourceMap` primeiro. `inject` não acorda o agente (`followup()`/`steer()` acordam).
-12. **Nunca escreva o `cordis.patch.yml` do perfil com sessões rodando** (o HMR recarrega: tools somem das sessões vivas, turnos em andamento morrem e reconstruir o `session-controller` pode deixá-lo morto até reiniciar o processo). Nunca escreva à mão o `package.json` do perfil nem rode pnpm dentro do diretório do perfil.
-13. Plugins de UI: renderize React num slot (nunca uma página servida em iframe); estilize **só** com tokens de tema `--dsw-alias-*`; nunca faça `require` de um pacote Client do Harness (um componente que lança deixa o slot em branco); `dsh.client.inject` deve ser um **array estático**.
-14. Desempenho: guarde o estado por sessão em `ctx.sessionProjections` (`apply` puro e síncrono, mesma referência quando ignora, JSON puro + `stateVersion`); espere eventos duráveis (`turn/end`, `assistant/message`, `tool/result`) e renderize tokens ao vivo de `agent/assistant-stream`; nunca faça polling de `agent/status`.
-
-## Lista rápida de armadilhas da comunidade (detalhes: guia §7.3 / community-repo-deep-dive.md)
-
-- Trio do tsconfig: `moduleResolution: bundler` + `allowImportingTsExtensions` + `rewriteRelativeImportExtensions` (+ `lib:["ES2024"]`, `types:["node"]` explícito).
-- `tsc` emite apesar de erros → `tsc || exit 1` / `--noEmitOnError`; procure imports `.ts` residuais no build antes de publicar.
-- Junctions do Windows via PowerShell `New-Item -ItemType Junction`; letra de unidade do vitest em maiúscula `C:/`.
-- `DSH_PERMISSION_MODE=danger-full-access` é de alto risco (sem backend de sandbox no Windows, aprovações desativadas); `DSH_*` em `~/.dsh/.env` quebra a inicialização.
-- Arquivos de sessão são zstd multiframe: use `scanZstdFrames`/`createZstdFrameDecoder` (`@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts`).
-- npm: o `dsh` sem escopo é o projeto alheio node-dsh (um shell) — instale `@deepseek-ai/dsh` (`latest`=`next`=0.2.0-rc.2, `alpha`=0.2.1-alpha.2); `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-headless` e `@deepseek-ai/dsh-session-persistence-jsonl` ainda publicam um `latest` obsoleto (0.0.1-rc.1), fixe `next` (0.2.0-rc.2) ou `alpha` (0.2.1-alpha.1); `create-dsh-plugin` latest=0.2.3; `@deepseek-ai/cordis` latest=4.0.4 com a nova tag `dsh-0-2-1-alpha-1` em 4.0.5-alpha.1; dsh-core/dsh-sdk seguem não publicados (verificado em 2026-10-06).
-- Aplique `resolve()` nos dois lados antes de comparar caminhos (armadilha da barra invertida do Windows).
-
-## Links de documentação
-
-Documentação oficial de desenvolvimento — base do site <https://deepseek-harness.github.io/deepseek-harness> (a raiz é chinês, `en/` é inglês; cópias locais textuais em `references/official-docs/docs/`):
-
-- Básico: [develop/basic/](https://deepseek-harness.github.io/deepseek-harness/develop/basic/) → [tool](https://deepseek-harness.github.io/deepseek-harness/develop/basic/tool) · [config](https://deepseek-harness.github.io/deepseek-harness/develop/basic/config) · [publish](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish)
-- Framework: [develop/framework/](https://deepseek-harness.github.io/deepseek-harness/develop/framework/) ([service](https://deepseek-harness.github.io/deepseek-harness/develop/framework/service), [events](https://deepseek-harness.github.io/deepseek-harness/develop/framework/events)) · Prática: [develop/practice/](https://deepseek-harness.github.io/deepseek-harness/develop/practice/) ([LLM adapter](https://deepseek-harness.github.io/deepseek-harness/develop/practice/llm-adapter))
-- Guias: [quickstart](https://deepseek-harness.github.io/deepseek-harness/guide/quickstart) · [providers](https://deepseek-harness.github.io/deepseek-harness/guide/providers) · [python-sdk](https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk)
-- Cordis: [primer](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer) · [tutorial](https://deepseek-harness.github.io/deepseek-harness/develop/cordis-tutorial/) · [core API](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/context)
-- Referência: [architecture](https://deepseek-harness.github.io/deepseek-harness/reference/) · [cookbook/adding-a-tool](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-tool) · [cookbook/extension-cookbook](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook) · [subsystems](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/)
-- Índice completo URL ↔ cópia local: [guide/links.md](links.md)
-
-Documentação comunitária de desenvolvimento — modelos/tutoriais/armadilhas, lista completa em [references/community-ecosystem.md](../references/community-ecosystem.md): [plugin-template](https://github.com/omdsh-dev/plugin-template) · [dsh-plugin-dev pitfalls](https://github.com/omdsh-dev/dsh-plugin-dev) · [from-scratch tutorial](https://github.com/Opr4Mp3r/deepseek-harness-plugin-from-scratch) · [dsh-plugin-check](https://github.com/omdsh-dev/dsh-plugin-check)
-
-## Índice de fontes principais
-
-- Documentação oficial textual: `references/official-docs/docs/**` (215 páginas, inclui pares `.zh.md`)
-- Restrições da raiz do repo: `references/official-docs/AGENTS.md`, `references/official-docs/packages/AGENTS.md`, `references/official-docs/vendor/README.md`; estado de sincronização em `references/official-docs/SNAPSHOT.md`
-- HTML do site: `downloads/web/site/**` (site completo EN+ZH) + `downloads/manifest.tsv`
-- Cordis upstream: `downloads/github/cordis/**` + pesquisa `references/upstream-cordis.md`
-- Paper do Cordis: `downloads/github/paper/**` + pesquisa `references/cordis-paper-and-community.md`
-- Pesquisa do site: `references/website-pages.md`
-- 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`**.

package/guide/quick-reference.zh-CN.md

@@ -1,184 +0,0 @@
-# DeepSeek Harness 插件开发速查表
-
-> 一页式速查。细节回到 [plugin-dev-guide.md](plugin-dev-guide.md) 与 [references](../references/)。
-
-## 插件骨架
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = 'my-plugin'          // 必须
-export const inject = ['tools']          // 依赖的服务; 无依赖可省略
-
-export interface Config { limit: number }
-export const Config: Schema<Config> = Schema.object({
-  limit: Schema.number().default(10),    // Schemastery schema, 不是普通对象
-})
-
-export function apply(ctx: Context, config: Config) {
-  ctx.effect(() => {                     // 注册=effect, 卸载自动撤销
-    const timer = setInterval(() => {}, 1000)
-    return () => clearInterval(timer)
-  })
-  ctx.on('tools/result', (exec, result) => { /* ... */ })
-  ctx.tools.register(defineTool({
-    name: 'my_tool',
-    description: '…',
-    parameters: { x: { type: 'string', required: true } },
-    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
-    async execute(args, exec) { return `hi ${args.x}` },  // 尊重 exec.signal
-  }))
-}
-```
-
-其他形态：对象 `export default { name, inject, apply }`；类 `class X extends Service { static inject=[...]; constructor(ctx){ super(ctx,'key') } }`（提供服务时用）。
-
-## ctx 核心 API（Cordis）
-
-| 用途 | API |
-|---|---|
-| 注册自定义资源+清理 | `ctx.effect(() => disposer)` |
-| 监听事件 | `ctx.on(name, handler)`（自动清理） |
-| 广播 / 无返回值 | `ctx.emit(name, payload)` |
-| 短路取值 | `ctx.bail(name, input)`（首个非 null/false/undefined 即止） |
-| 顺序取值 | `await ctx.serial(name, input)` |
-| 管线 | `await ctx.waterfall(name, input, init)`；监听器**必须 `next()`** |
-| 子上下文 | `ctx.extend(meta)` / `ctx.isolate(name, label?)` / `ctx.intercept(name, config)` |
-| 挂子插件 | `ctx.plugin(plugin)` → Fiber；`await fiber.dispose()` |
-| 可选服务查询 | `ctx.get('metrics')?.x()` |
-| 日志 | `ctx.logger(name)` |
-
-生命周期：`PENDING → LOADING → ACTIVE`（apply 抛错 → FAILED）；`ACTIVE → UNLOADING → DISPOSED`。依赖服务消失 → 自动卸载，恢复 → 自动重载。
-
-## 事件派发五模式（含 bail）
-
-| 模式 | await | 顺序 | 返回值 |
-|---|---|---|---|
-| emit | 否 | 注册序 | 无 |
-| waterfall | 否 | 注册序 | 有（**不调 next() 即短路**） |
-| parallel | 是 | 并行 | 无 |
-| serial | 是 | 注册序 | 有（首个非空即止） |
-| bail | 否 | 注册序 | 有（首个非 null/false/undefined 即短路，**并停止后续监听器**） |
-
-类型声明（declaration merging）：
-
-```ts
-declare module '@deepseek-ai/cordis' {
-  interface Events { 'my/event': (p: { id: string }) => void }
-  interface Context { myService: MyService }   // 提供服务时
-}
-```
-
-## cordis.yml / 分层
-
-```yaml
-# scratch-plugin/cordis.yml (--patch 覆盖层)
-- insert:
-    - id: hello
-      name: '/absolute/path/to/scratch-plugin/src/my-plugin.ts'
-      config: { greeting: 'Hi' }
-
-# bundle: package.json 的 "dsh": {"bundle":{"patch":"./cordis.patch.yml"}}
-# profile: "dsh": {"profile":{"bundles":["@deepseek-ai/dsh-base","my-bundle"]}}
-# 生效顺序: bundles → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch
-# 按 id 覆盖, 整行 config 替换(非深合并); 覆盖方必须重述全部键
-# !!js 表达式(双感叹号)在注入服务就绪后求值; disabled 每次挂载时求值
-```
-
-命令：`dsh --profile web` · `dsh --profile headless "task"` · `dsh --profile X --dump-config` · `dsh plugin --profile X add/remove <pkg>` · `pnpm dsh web --patch ./scratch-plugin/cordis.yml`
-
-安装形态（0811 起 repository-plugin 机制已移除，只剩两条通道）：
-- **bundle 插件**（`"dsh":{"bundle":{"patch":"..."}}`）→ `dsh plugin add <pkg>` 进 `dsh.profile.bundles` 层栈，重启生效。
-- **纯 cordis 插件**（无 `dsh.bundle`）→ `dsh plugin add <pkg>` 装依赖 + profile `cordis.patch.yml` 加 insert 行，**配置 HMR 实时生效**。
-- git 源：`dsh plugin add "github:owner/repo#<sha>&path:<subdir>"`（pin commit；`prepare` 自包含构建 + profile `pnpm-workspace.yaml` allowBuilds；npm/tarball 免构建许可）。
-
-## 常用内建服务（ctx 键）
-
-`sessions` 会话日志/内存库 · `systemPrompt` 提示词组装 · `tools` 工具注册与受控执行管线 · `agents` Agent 注册表 · `agentLoop` 循环驱动器 · `llm` 模型适配器注册表 · `skills` 技能注册表 · `commands` 人类斜杠命令 · `approval` 一次性审批 · `jobs` 后台任务 · `fs` 文件系统缝 · `shell` bash 执行缝 · `subprocess` 子进程缝 · `terminals` PTY · `sandbox` 进程限制缝 · `codeRuntime` 代码执行 · `sessionPersistence` 持久化 · `settings` / `credentials` / `workspaceRegistry` / `goals` / `planMode` / `subagents` / `workflowEngine` / `storage`。
-完整清单与每个方法的精确签名 → `references/official-docs/docs/capability-seams.md` + `docs/subsystems/*.md`（生成式 Cordis API 区）。
-
-## 工具策略管线（执行顺序）
-
-```
-tools/pre-execute (waterfall, allow|deny|ask) → ctx.tools.guard() (单调 deny)
-→ tools/execute (包裹, 仅可换 exec.signal) → execute(args, exec)
-→ tools/post-execute (换 content/value/阻断/附上下文) → finalizeContent
-→ tools/result (只读观察) → 持久化 tool/result (会话事件)
-```
-
-选择规则：策略门用 pre-execute；不可翻案的 deny 用 guard；超时/重试/指标用 execute；改结果用 post-execute；审计/采集用 result。
-Code Mode：`await tools.<name>(args)` 免费获得；成功=最终规范 JSON 值；失败=`ToolCallError(name, toolName, message)`。
-
-## UI 卡片（纯函数！只依赖 args(+result)，禁止 I/O/时钟/随机）
-
-- `presentCall(args)` → `{card:'generic',title,kind?,rawInput?,content?,locations?}` | `{card:'terminal',title,description?,cwd?}` | `{card:'diff',title,diffs,locations?}`
-- `presentResult(args,{content,isError,meta?})` → generic / terminal / diff / search(`shape:'matches'|'paths'`) / read / web(`kind:'search'|'fetch'`)
-- 回放元数据：`output.presentationMeta(args, value)` → 持久化 `tool/result.meta`
-
-## 三层能力缝（seam）模板
-
-Definition（`dsh-my-cap`）：`export abstract class MyCapService extends Service { constructor(ctx){super(ctx,'myCap')} abstract execute(req): Promise<res> }` + Context 声明合并。
-Provider（`dsh-my-cap-local`）：`export function apply(ctx){ ctx.plugin(class MyCapLocal extends MyCapService {...}) }`。
-Consumer（`dsh-tool-my-cap`）：`inject = ['tools','myCap']`，`ctx.tools.register(defineTool({... execute: args => ctx.myCap.execute(...)}))`。
-规则：不提前拆；Provider 与 Consumer 互不依赖；默认值走显式 `resolve(request): Spec`。
-
-## LLM 适配器要点
-
-`class MyAdapter extends LlmAdapter { async *stream(options): AsyncIterable<StreamChunk> }` → `ctx.llm.registerAdapter(['provider'], adapter)`。
-Chunk 协议：`block-start` → `text-delta*` → `block-end`（完整块）→ … → `usage`（在 finish 前）→ `finish`（最后；`reason: {kind:'stop'|'tool-calls'}`）。无法满足的字段抛带稳定 code 的 `LlmError`。
-
-## 红线（违反=挂门禁/错误行为）
-
-1. 注册必须走 `ctx.effect()`/`ctx.on()`/服务 `register()`（返回 disposer）。注册在别的 ctx（如 `agent.ctx`）上的有**两个拥有者**——disposer 也要留在自己插件的 effect 里。
-2. waterfall 监听器必须调 `next()`；不调=故意短路。改写 `agent/pre-step` 决策要**展开**（`{ ...decision, messages }`），否则 `startsRequestSeries` 之类字段会丢。
-3. **用最弱的够用机制**：`ctx.tools.restrict()`（只移除）< `ctx.tools.guard()`（只拒绝）< waterfall 改写（依赖顺序）< `system-prompt/assemble`（整段替换）。最终结果只看 `tools/result`；只有要变换结果才用 `tools/post-execute`。
-4. 模型可见 ⟺ 已记录：新模型可见输入必须新增会话事件（`SessionEventMap`）——**由宿主侧新增**，不是插件自己写（见第 10 条）。
-5. 不得硬编码可调参数（判断：cordis.yml 能否改）；misconfig fail loud。要暴露给用户的实时字段用 `Volatile<T>` + `loader/volatile-update`（表单命名空间=profile 条目 id）。
-6. 独立插件包：cordis 是 peerDependency（与宿主同身份：scoped `@deepseek-ai/cordis` 与 unscoped 混用会"双 Cordis 分裂"）；ESM；`dsh.bundle` 清单（`patch` **可为有序数组**）；git 安装配 `prepare` + `allowBuilds`；发布带 `lib/` 或 tarball。**共享实例的 dsh 包只放 peer + dev，绝不放 dependencies**（profile 内副本会静默遮蔽运行时）。⚠️ **已更正：peer 范围会被安装期强制**——`dsh plugin add` 拿运行时版本比对声明的 `@deepseek-ai/dsh-*` 范围，不匹配即**拒绝安装**；只有 `engines.dsh` 是纯声明、零强制。范围只能表达"能不能装"，**表达不了某个 API 在不在**——仍要配运行时探测（区间选择见 `version-matrix.md` §4）。
-7. 必须交展示元数据：`locale/*.json` 的 `meta.title`/`meta.description` + 导出的 `./icon`（SVG/PNG/JPEG/WebP，≤256 KiB，必须在包内）。子路径插件**不读**自己的 `package.json`。
-8. 文档双语成对；工具描述/提示词即行为；非平凡变更加 Agent Note；提交前跑最小检查集（dsh-pre-push-checks）。
-9. 跨边界 opaque id 用 branded（`Branded<B>` from `dsh-brand`），从不裸 `string`。
-10. **绝不要用新的 `type` 追加会话事件**：`SessionEventMap` 成员默认 required-on-read——不认识该事件类型的 build 会拒绝整份日志，除非该事件带上信封的 `ignorable: true` 标记；而运行时 `Session.append()` **无法**写这个标记（其第三参仅为 surface 事件的 `SurfaceIntent`）。插件状态要从既有事件推导，或用 inspection 找到的 storage 服务自持。只有结构格式变更才 bump `SESSION_FORMAT_VERSION`（当前 `4`；V3→V4 迁移把 tool 结果提升为 tool-role 消息、把消息 source 换成生产者自有的 `source.kind`）。对 `SessionEvent` 的 switch 仍落入文档化 `default`——**禁用 `assertNever`**（merge-extensible union）。
-11. `agent.inject()` 的 `source` **不再接受**退役的 `{ kind: 'plugin', plugin: '<name>' }` 包装——先用 `MessageSourceMap` 声明合并自己的 kind。`inject` 不唤醒 agent（要唤醒用 `followup()`/`steer()`）。
-12. **绝不在会话运行期间写 profile 的 `cordis.patch.yml`**（HMR 会重载：会话内工具会消失、在途 turn 被杀、最坏重建 `session-controller` 失败并永久失效，只能整进程重启）。不要手写 profile 的 `package.json`，不要在 profile 目录里跑 pnpm。
-13. UI 插件：只渲染 slot 里的 React 组件（禁止 iframe 托管页面）；样式只用 `--dsw-alias-*` 主题 token；不 `require` 任何 Harness Client 包（抛错组件会把 slot 搞白）；`dsh.client.inject` **必须是静态数组**。
-14. 性能：per-session 状态放 `ctx.sessionProjections`（纯同步 `apply`、忽略即同引用、纯 JSON + `stateVersion`）；等持久事件（`turn/end`/`assistant/message`/`tool/result`），实时 token 读 `agent/assistant-stream`；**不轮询 `agent/status`**。
-
-## 社区实测坑速查（详见 guide §7.3 / community-repo-deep-dive.md）
-
-- tsconfig 三件套：`moduleResolution: bundler` + `allowImportingTsExtensions` + `rewriteRelativeImportExtensions`（+ `lib:["ES2024"]`、显式 `types:["node"]`）。
-- `tsc` 报错仍 emit → `tsc || exit 1` / `--noEmitOnError`；发布前 grep 产物无 `.ts` 残留。
-- Windows junction 用 PowerShell `New-Item -ItemType Junction`；vitest 盘符大写 `C:/`。
-- `DSH_PERMISSION_MODE=danger-full-access` 高风险（Windows 无沙箱后端、禁用审批）；`DSH_*` 放 `~/.dsh/.env` 会报错。
-- 会话文件多帧 zstd：用 `scanZstdFrames`/`createZstdFrameDecoder`（`@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts`）。
-- npm：无作用域 `dsh` 是无关项目 node-dsh（shell）——官方包是 `@deepseek-ai/dsh`（`latest`=`next`=0.2.0-rc.2、`alpha`=0.2.1-alpha.2）；`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-headless`、`@deepseek-ai/dsh-session-persistence-jsonl` 的 `latest` 仍是过期版本（0.0.1-rc.1），要钉 `next`（0.2.0-rc.2）或 `alpha`（0.2.1-alpha.1）；`create-dsh-plugin` latest=0.2.3；`@deepseek-ai/cordis` latest=4.0.4，另有新标签 `dsh-0-2-1-alpha-1`=4.0.5-alpha.1；dsh-core/dsh-sdk 仍未发布（2026-10-06 复核）。
-- 路径比较前两侧都 `resolve()`（Windows 反斜杠陷阱）。
-
-## 文档链接
-
-官方开发文档——站点基址 <https://deepseek-harness.github.io/deepseek-harness>（根路由中文，`en/` 前缀英文；逐字副本在 `references/official-docs/docs/`）：
-
-- 入门：[develop/basic/](https://deepseek-harness.github.io/deepseek-harness/develop/basic/) → [tool](https://deepseek-harness.github.io/deepseek-harness/develop/basic/tool) · [config](https://deepseek-harness.github.io/deepseek-harness/develop/basic/config) · [publish](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish)
-- 框架与实践：[develop/framework/](https://deepseek-harness.github.io/deepseek-harness/develop/framework/)（[service](https://deepseek-harness.github.io/deepseek-harness/develop/framework/service)、[events](https://deepseek-harness.github.io/deepseek-harness/develop/framework/events)）· [develop/practice/](https://deepseek-harness.github.io/deepseek-harness/develop/practice/)（[LLM adapter](https://deepseek-harness.github.io/deepseek-harness/develop/practice/llm-adapter)）
-- 用户指南：[quickstart](https://deepseek-harness.github.io/deepseek-harness/guide/quickstart) · [providers](https://deepseek-harness.github.io/deepseek-harness/guide/providers) · [python-sdk](https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk)
-- Cordis：[primer](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer) · [tutorial](https://deepseek-harness.github.io/deepseek-harness/develop/cordis-tutorial/) · [core API](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/context)
-- 参考：[architecture](https://deepseek-harness.github.io/deepseek-harness/reference/) · [cookbook/adding-a-tool](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-tool) · [cookbook/extension-cookbook](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook) · [subsystems](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/)
-- 完整 URL ↔ 本地副本对照：[guide/links.md](links.md)
-
-社区开发文档——模板/教程/踩坑，完整清单见 [references/community-ecosystem.md](../references/community-ecosystem.md)：[plugin-template](https://github.com/omdsh-dev/plugin-template) · [dsh-plugin-dev pitfalls](https://github.com/omdsh-dev/dsh-plugin-dev) · [from-scratch tutorial](https://github.com/Opr4Mp3r/deepseek-harness-plugin-from-scratch) · [dsh-plugin-check](https://github.com/omdsh-dev/dsh-plugin-check)
-
-## 关键源索引
-
-- 本地官方文档全文：`references/official-docs/docs/**`（429 篇，含全部 212 个 `.zh.md`；镜像基线 `dsh-v0.2.1-alpha.2`）；**没上文档站**的那些页（session-format-status、`upgrade-guide/**`、`persistence-changes/**`、ui-radius、web-styling、module-graph）见 [links.md](links.md) §2.1
-- 迁移清单：[migration-0.2.md](migration-0.2.md) —— §0–§12 覆盖 `0.1.6-alpha.2` → `0.2.1-alpha.1` 的全部破坏性变更，**§13 把 `0.2.1-alpha.1` → `0.2.1-alpha.2` 整理成 19 个可引用 seam（`L1`–`L19`）**；每条都附官方 upgrade-guide 出处
-- 官方自带插件开发技能：[references/official-plugin-dev-skill.md](../references/official-plugin-dev-skill.md)
-- 仓库根约束：`references/official-docs/AGENTS.md`、`references/official-docs/packages/AGENTS.md`、`references/official-docs/vendor/README.md`；同步状态见 `references/official-docs/SNAPSHOT.md`
-- 站点爬取 HTML：`downloads/web/site/**`（中英双语全站）+ `downloads/manifest.tsv`（下载清单）
-- 上游 Cordis：`downloads/github/cordis/**` + 调研 `references/upstream-cordis.md`
-- Cordis 论文：`downloads/github/paper/**` + 调研 `references/cordis-paper-and-community.md`
-- 网站/官网调研：`references/website-pages.md`
-- 仓库调研：`references/harness-repo.md`
-- 社区/生态：`references/community-ecosystem.md` + 工作区 `dsh-plugin-topic-2026-08-13/`
-- 全部 URL 清单：`references/sources.md`

package/guide/release-engineering.md

@@ -1,198 +0,0 @@
-# Release Engineering for a DSH Plugin Portfolio
-
-> Chinese: [release-engineering.zh-CN.md](release-engineering.zh-CN.md)
-
-The official documentation teaches you how to build **one** plugin. It does not cover how to keep **dozens** of them installable, publishable, and upgradeable across a harness that ships compatibility-breaking changes by design. This chapter is that missing part, written from a live portfolio of 38 bundle plugins, 39 npm packages and 500+ published versions.
-
----
-
-## 0. The contract you are actually maintaining
-
-A plugin is not "a TypeScript package". It is four contracts, and a portfolio breaks whenever one of them drifts:
-
-| Contract | Where it lives | Breaks when |
-|---|---|---|
-| Bundle manifest | `package.json` -> `dsh.bundle.patch` | the patch file is renamed or the key is dropped |
-| Install surface | npm package name + `dist-tags` | a publish lands on the wrong tag, or never happens |
-| Compatibility window | `peerDependencies` on `@deepseek-ai/*` | the harness moves an alpha/rc line and the range no longer admits it |
-| Discoverability | GitHub topic `dsh-plugin` + package `keywords` | the repo is renamed, or a fork is created without topics |
-
-Everything below is about keeping those four in sync at portfolio scale, cheaply.
-
----
-
-## 1. Layout and naming that scale
-
-Two habits separate 5 plugins from 50:
-
-1. **One repository per plugin**, each independently releasable. A monorepo makes one failing gate block every plugin's release.
-2. **A predictable name**: `dsh-<capability>` for the package, the repository named identically. Scoped names (`@you/dsh-x`) are fine; keep the repository name stable, because the discovery mechanism is a GitHub topic and a rename silently drops you out of search.
-
-Keep a per-repo `AGENTS.md` stating that repository's own rules. As a portfolio grows, the repository file becomes the authority for that repo, and cross-repo conventions live in one shared document (this one).
-
----
-
-## 2. The version-line matrix
-
-During developer preview the harness publishes several lines at once, for example `0.1.2-rc.1`, `0.1.5-alpha.1`, `0.1.5-rc.1`, `0.1.6-alpha.2`, `0.1.7-alpha.2`. A portfolio pinned to one line breaks the moment a user installs from another.
-
-The pattern that admits all windows (one clause per prerelease tuple; each `-0` floor covers every prerelease of its tuple, never the bare `>=0.1.7` form):
-
-```jsonc
-{
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2"
-  }
-}
-```
-
-⚠️ **Do not write the open form `>=0.1.2-rc.1 <0.3.0`.** It looks like the widest safe range and is the opposite: it spans an entire breaking-change generation, so the gate admits a `0.2.x` host while your plugin still calls `0.1.x` APIs — an install-time pass followed by a runtime break. **Upper bounds must be cut per generation** (`<0.2.0` / `<0.3.0`), and the six-clause shape above is the canonical range recorded in `dsh-plugin-kit`'s `data/peer-range.json` (`canonicalRange`, updated 2026-09-26). `dsh-plugin-doctor`'s R8 flags the open form.
-
-A range is only as wide as its newest clause, and semver makes this easy to get wrong in a way that looks right: **a range admits a prerelease only if some comparator carries that same `[major, minor, patch]` tuple AND a prerelease.** So a band ending at `>=0.1.6-0 <0.2.0` admits `0.1.6-alpha.2` but *not* `0.1.7-alpha.2` — it reads as "everything up to 0.2" and behaves as "nothing after the 0.1.6 tuple". Adding the line's own clause is the whole fix; check it with `semver.satisfies('0.1.7-alpha.2', range)`, never by eye.
-
-Rules that follow:
-
-- **`devDependencies` pin the newest published line.** Your typecheck must fail before your users do.
-- **`dependencies` pin the stable/rc line; `peerDependencies` admit both windows.** Never narrow a peer range just to make your own CI green - you will silently uninstall yourself from users on the other line.
-- **Never re-pin 30 repositories by hand.** A scripted wave (patch bump, pin update, gate, publish) is the only sustainable path; run it as one atomic batch with a rollback note.
-
----
-
-## 3. The release pipeline
-
-Per repository the release is a tag push that triggers a workflow:
-
-```yaml
-on:
-  push:
-    tags: ['v*']
-jobs:
-  publish:
-    steps:
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm run build
-      - run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-Five things that cost real time to learn:
-
-1. **`--frozen-lockfile` is a gate, and it is right.** A release commit that forgets `pnpm-lock.yaml` fails here. Never release from a dirty lockfile state.
-2. **Publish with `--provenance`.** One flag produces a signed supply-chain attestation - the cheapest trust signal you can give a reviewer.
-3. **Secrets are per repository.** `NPM_TOKEN` must exist in every repository that publishes. When a token is rotated, reseed all of them, or the failure appears much later, one repo at a time.
-4. **A pushed tag cannot be re-published.** If the artifact was wrong: fix the commit, force-move the tag, re-run, and accept that the first attempt is public history.
-5. **Know the registry replication delay.** A verification job running immediately after a publish can still resolve the previous version ("The latest release is X"). Re-run after `latest` settles instead of "fixing" a package that was never broken.
-
----
-
-## 4. One version, three surfaces
-
-Publish once, mirror everywhere, make the mirror idempotent:
-
-| Surface | Mechanism | Failure mode to watch |
-|---|---|---|
-| npm | tag-triggered workflow | dist-tag lands on the wrong line |
-| GitHub Release | the same tag-triggered workflow (idempotent) | release notes drift from CHANGELOG |
-| Gitee (mirror) | scheduled sync workflow | mirror HEAD behind upstream after a force-move |
-
-Verify all three before calling a release done. A release that exists on npm but not in the mirror is a half release, and mirror users will report a bug you already fixed.
-
-The GitHub Release is created by the **same tag workflow** that publishes to npm - never by hand. Manual creation is exactly how release notes drift from `CHANGELOG.md`, and the gap is invisible from the registry: a version that exists on npm but has no Release page looks complete to `npm view` and incomplete to anyone reading the repository. Keep the step idempotent, so a re-run, a backfilled tag, or an already-existing Release page cannot fail the job:
-
-```sh
-if gh release view "$TAG" >/dev/null 2>&1; then
-  echo "release $TAG already exists; skipping"
-  exit 0
-fi
-node scripts/changelog-section.mjs "$VERSION" > release-notes.md || true
-if [ -s release-notes.md ]; then
-  gh release create "$TAG" --title "$TAG" --notes-file release-notes.md
-else
-  gh release create "$TAG" --generate-notes
-fi
-```
-
-Three details carry the weight. The job needs `permissions: contents: write` (the publish job's `contents: read` is not enough, and job-level permissions override the workflow's). It belongs in a **separate job that `needs:` the publish job**, so a tag whose `CHANGELOG.md` lacks that section cannot turn a successful npm publish into a red release. And the `|| true` plus the `-s` test is what makes the missing-section case degrade to generated notes instead of failing - a release page with generated notes beats no release page at all.
-
----
-
-## 5. README parity is part of the build
-
-If the portfolio ships READMEs in several languages, treat them as build artifacts:
-
-- The language set is fixed and checked. Adding a section to one language and not the others must fail CI.
-- Enforce encoding discipline before tagging: UTF-8 without BOM, no mojibake, no replacement characters. A published README cannot be repaired - npm metadata is immutable, and the registry may not even display your corrected file.
-- When scripting anchors, remember word boundaries do not behave as expected after CJK characters.
-
----
-
-## 6. Migration waves when the harness breaks compatibility
-
-The harness states plainly that compatibility-breaking changes will happen. Plan for waves, not for stability:
-
-1. **Detect.** Run a typecheck matrix against the newest published line before users hit it. A removed event type or a changed signature surfaces as a compile error in one repository, which tells you the blast radius for all of them.
-2. **Triage.** Separate pin updates, mechanical code changes, and semantic redesigns. Only the first two belong in a wave; the third gets its own release and its own changelog entry.
-3. **Execute atomically.** One batch of patch bumps, one gate run, one publish wave, and a rollback note per repository (previous tag plus the exact pin to restore).
-4. **Record the incident.** Two examples worth writing down, because both were self-inflicted and both cost a release cycle:
-   - A release commit without the lockfile turned CI red; fixed by amending the commit and force-moving the tag.
-   - A lockfile generated by a different package manager contained workspace-link entries that a clean install could not reproduce; fixed by deleting it, reinstalling in isolation, and regenerating.
-
-**Rule of thumb**: if a wave touches more than about four repositories at once, the CI queue saturates and runs settle out of order. Batch accordingly.
-
----
-
-## 7. The pre-tag gate
-
-Before every tag push:
-
-- [ ] `pnpm install --frozen-lockfile` clean
-- [ ] typecheck against the newest published line, not the one you developed on
-- [ ] unit tests green
-- [ ] package invariants: the `files` whitelist contains the built entry, and the entry exists
-- [ ] README language parity plus encoding audit (no BOM, no mojibake, no replacement characters)
-- [ ] `CHANGELOG.md` has a section for the version you are about to tag
-- [ ] the tag workflow creates the GitHub Release itself, idempotently, from that section (section 4)
-- [ ] the version bump matches intent (patch = wave, minor = feature, major = breaking)
-- [ ] the tag does not already exist on the remote
-
-After the tag:
-
-- [ ] npm `dist-tags.latest` equals the new version
-- [ ] the GitHub Release exists with notes
-- [ ] the mirror is synced
-- [ ] every consumer repository that vendor-pins this package was bumped in the same batch
-
----
-
-## 8. Registry behaviours that look like your bug but are not
-
-Document these once so nobody debugs them twice:
-
-- **`versions[].readme` can be empty** for every published version of a package even though the tarball README is byte-identical to your repository. The package page then shows a stale README. It is a registry-side presentation behaviour, reproducible through both the CLI and CI channels - do not "fix" it by re-publishing.
-- **`description` is truncated** at roughly 255 characters in package metadata. Compare a truncated form, not the full string, when verifying a publish.
-- **Scoped packages** may return placeholder values on some download-count endpoints. Use the range endpoint rather than the point endpoint.
-- **Published does not mean visible.** See item 5 in section 3.
-
----
-
-## 9. Local tooling that fakes a result
-
-Each of these returns a confident wrong answer rather than an error, and each one cost a real debugging cycle. Written down so the next person recognises the shape:
-
-- **`npm view <pkg>@<ver> A B --json` invents absences.** Asking for two fields at once can report a field that exists as empty, which reads as "the published package lost its `peerDependencies`". Query one field per call; when it matters, unpack the published tarball and read its `package.json` - that is the ground truth. An audit that flagged eight packages this way was wrong about all eight.
-- **A content search that honours `.gitignore` returns false negatives.** Where the workspace root ignores everything (`*` plus a single negation), a search across it finds nothing, and "nothing" reads as proof of absence. Before concluding a pattern is absent, confirm it with a scan that does not consult ignore rules.
-- **Windows PowerShell 5.1's `Set-Content -Encoding utf8` writes a BOM.** A JSON request body beginning `EF BB BF` fails to parse, and the error blames the payload's contents rather than its encoding. Write machine-read files through an explicit encoder: `[System.IO.File]::WriteAllText($path, $text, (New-Object System.Text.UTF8Encoding($false)))`.
-- **On Windows, `rd /s /q` cannot remove a tree containing a reserved device name** (`NUL`, `CON`, `AUX`, `PRN`, `COM1`-`COM9`, `LPT1`-`LPT9`). It reports success and leaves the entire ancestor chain in place. Delete that entry through a `\\?\`-prefixed long path, then assert the directory is actually gone - a zero exit code is not evidence that the tree disappeared.
-
----
-
-## 10. What this buys you
-
-A portfolio maintained this way behaves like a product: users on any harness line can install any plugin, every version is attested, mirrors agree, and a breaking upstream change costs one wave instead of an outage. It is also the strongest form of ecosystem contribution - the official project asks for exactly this, and explicitly does not rank official packages above community ones.
-
-Corrections and additions are welcome; the practical entry points are listed in [links.md](links.md).