super-dsh 0.1.12 → 0.3.0

package/node_modules/better-dsh/docs/specs/ast-engine-deomp/spec.md

@@ -0,0 +1,170 @@
+# AST 去 OMP 化：内置 WASM 引擎（ast-engine-deomp）
+
+状态：**设计已定（user 裁决 2026-10-03：路线 A + 14 语法全部随包）；spike 已证；待落实现**
+｜ 规格路径：`docs/specs/ast-engine-deomp/spec.md`（仓库根 docs；`better-dsh/docs/` 是 `prebuild` 由 `../docs` 重建的产物，别写那里）
+
+---
+
+## 0. 动机（实证）
+
+`dvc://ast_grep` / `dvc://ast_edit` 是插件里**最后一个还需要 OMP 二进制的组件**。`zero-npm-runtime-deps`（0.2.5-a/b）已把 `@oh-my-pi/pi-natives-<platform>` 从 `dependencies` 摘掉，改为首次使用 lazy 自装——安装不再背它，但**第一次用 AST 仍要付**：
+
+| 项 | 实测 |
+|---|---|
+| 自装下载量 | `@oh-my-pi/pi-natives-linux-x64@18.0.6` = **70.8 MB**（registry `content-range: bytes 0-1/70791219`） |
+| 自装落盘量 | `dist.unpackedSize` **328 MB**（本机 18.2.11 实测 352 MB：`pi_natives.*-modern.node` 183 MB + `-baseline.node` 183 MB） |
+| 前提 | 必须联网 + npm registry 可达（否则 AST 设备整个不可用） |
+
+三点归属澄清（避免误伤）：
+
+1. **better-dsh 声明的 OMP 依赖 = 0 条**（`package.json` 实证）。
+2. prod profile 里那 352 MB `@oh-my-pi/*` **不是我们的**——来自 `super-dsh@0.1.9` → `@oh-my-pi/pi-coding-agent@18.2.11`。
+3. 这条自装路径是 0.2.5-a 的**有意的临时态**（`zero-npm-runtime-deps` 第 2 节表格最后一行），不是终态。
+
+**为什么可以自己实现**：`@oh-my-pi/pi-natives` 的 ast 面（`crates/pi-ast` 4,448 行 + `crates/pi-natives/src/ast.rs` 1,509 行）分两层——
+
+- **引擎**（唯一真 native）：ast-grep 结构匹配/改写 + ~70 个 tree-sitter 语法。**OMP 自己也是抄的**：`Cargo.toml` 里 `ast-grep-core 0.39` + `tree-sitter 0.25`，全 MIT。上游 ast-grep 官方就发布**纯 WASM 构建**。
+- **底盘**（全是胶水，TS 可写）：`.gitignore` 感知遍历（`ignore` crate）、glob 过滤（`globset`）、扩展名→语言推断、`maxFiles`/`maxReplacements`、dryRun、parseError 收集、meta 变量、分页、聚合统计。
+
+**投入上限的负证据**：`docs/60_exploration-and-research/07-omp-usage-telemetry/omp-lsp-ast-device-usage-telemetry.md` —— 3 周、288 个 session、21,666 次 toolCall 的真实 OMP 语料里，`ast_edit` / `lsp` **执行 0 次**（对照 `dsh://browser` 631 次）。所以本 change 的取舍原则是**语义零回归、体积大降、不为性能做过度工程**，而不是把 native 性能复刻出来。
+
+---
+
+## 1. 目标态（硬契约）
+
+   > **2026-10-04 修订（task-12 诊断字段）**：本条的「一字不动」是 **parity swap 期的冻结口径**——它约束的是 native→WASM 替换本身的行为面 A/B。验收后的 0.2.6 起为可诊断性**有意背离**：`ast_grep`/`ast_edit` 结果新增**可选**诊断字段 `patternErrors` / `pathNotFound` / `overlapping`（native 对这三种失败同样静默，见 2026-10-04 实测报告 A1/A3/A6）。这是 spec'd 的契约扩展（ast/dvc spec 新增 Requirement "Diagnostic fields (deliberate divergence from the native predecessor)"），不属于本规格意义上的回归；既有字段名与语义仍一字不动。
+1. **模型面契约一字不动**：`ast_grep` 的 `{patterns, path, offset, limit, includeMeta}`、`ast_edit` 的 `{ops:[{pat,out}], paths, dryRun}`，以及结果里 `changes` / `fileChanges` / `totalReplacements` / `filesTouched` / `filesSearched` / `applied` / `limitReached` / `parseErrors` / `matches` / `totalMatches` / `filesWithMatches` 的字段与语义全部保持。
+2. **零 OMP 痕迹（代码/产物面）**：源码、产物、`.vendor`、运行时网络请求，以及 tarball 里运行时实际装载的面（`lib/`、`package.json`、`scripts/`）都不再出现 `@oh-my-pi` / `pi_natives`。tarball 内 `docs/` 是刻意的发布载荷，对本次迁移的历史性提及属预期、不计入该判据（2026-10-04 终审定界：代码/产物面实测 0 命中；docs prose 提及数量随发布内容浮动，非回归信号）。
+3. **守住 zero-npm-runtime-deps 契约**：`dependencies` / `optionalDependencies` / `postinstall` 维持不存在；引擎与语法是**构建期输入**（devDependencies），产物以**包内资产**形式随 `files` 发布——即该规格认可的"构建期进产物"那条出路，不引入新的运行时自装。
+4. **离线自足**：断网、无 npm、无 `.vendor` 的环境下 `ast_grep`/`ast_edit` 必须真实可用。
+5. **fail-open 保持**：引擎整体或某一种语法加载失败，只降级该设备/该语言，插件加载与其余组件零影响；对外仍是 `DVC_DEVICE_ERROR`，措辞改为指向内置引擎。
+
+---
+
+## 2. 技术选型（spike 已证）
+
+| 角色 | 选定 | 版本 | 体积 | 许可 |
+|---|---|---|---|---|
+| 匹配/改写引擎 | `@ast-grep/wasm`（**官方** ast-grep 的 WASM 构建） | 0.45.3 | 1.73 MB | MIT |
+| WASM 运行时 | `web-tree-sitter` | 0.26.x | 0.20 MB | MIT |
+| 语法（14 个） | `@lumis-sh/wasm-<lang>` | 0.26.x | 12.5 MB | MIT |
+
+**合计 14.4 MB 随包**，对照现状 **70.8 MB 下载 / 328 MB 落盘 / 必须联网**。
+
+语法↔扩展名表（沿用现有 `AST_CODE_EXTENSIONS`，本 change 不缩语言面）：
+
+| 扩展名 | 语法 | 扩展名 | 语法 |
+|---|---|---|---|
+| `.py` `.pyi` | python | `.c` `.h` | c |
+| `.js` `.jsx` `.mjs` `.cjs` | javascript | `.cpp` `.hpp` | cpp |
+| `.ts` `.mts` `.cts` | typescript | `.html` | html |
+| `.tsx` | tsx | `.css` | css |
+| `.rs` | rust | `.json` | json |
+| `.go` | go | `.yaml` `.yml` | yaml |
+| `.sh` | bash | `.rb` | ruby |
+
+### 2.1 spike 结论（丢弃式探针：`.scratch/ast-wasm-spike/`）
+
+**A/B 一致性**：用 `natives-loader.ts` 同款方式 dlopen 本机真实 `pi_natives.linux-x64.node`，与 WASM 栈跑同一组用例——
+
+| 用例 | OMP native | WASM 栈 | |
+|---|---|---|---|
+| `c` `foo($A)` | 0 | 0 | ✅ |
+| `c` `return foo($A)` | 1 | 1 | ✅ |
+| `cpp` `foo($A)` | 1 | 1 | ✅ |
+| `css` `color: $V` / `color: red` | 0 / 0 | 0 / 0 | ✅ |
+| `html` `<div class=$C>$$$K</div>` | 1 | 1 | ✅ |
+| `python` `return $X` | 1 | 1 | ✅ |
+| `js` `foo($$$A)` / `rust` `vec![$$$A]` / `yaml` `b: $V` / `go` `foo($A)` | 1 | 1 | ✅ |
+
+**C / CSS 的"匹配不到"是 ast-grep 上游的 pattern 上下文歧义，不是 WASM 退化**——native 给同样的 0。行为面零回归。
+
+**三个已解的坑**（实现时不得重新踩）：
+
+1. **Node 不吃 ESM wasm import**：`@ast-grep/wasm` 的 `wasm.js` 直接 `import "*.wasm"`，Node 22 需 `--experimental-wasm-modules`。正解是**手动装配**：`WebAssembly.instantiate(bytes, { './wasm_bg.js': bg })` → `bg.__wbg_set_wasm(instance.exports)` → `instance.exports.__wbindgen_start()`（wasm-bindgen 标准手法；wasm 的 import module 名实测为 `./wasm_bg.js`，102 个 import）。
+2. **`expandoChar` 必须显式给 `'µ'`**：默认值 `$` 只在 JS/TS/bash/cpp 下碰巧可用；python / rust / go 会**静默 0 命中**（实测矩阵：`default:0 / "$":0 / "µ":1`）。`µ` 在全部被测语言下可用。
+3. **语法 wasm 必须是新式 `dylink.0`**：最流行的 `tree-sitter-wasms@0.1.13` 是 legacy `dylink`，与 `web-tree-sitter@0.26` 硬不兼容（`getDylinkMetadata` → `need dylink section`）。`@lumis-sh/wasm-*`（`dylink.0` 实测为 1）是正解。
+
+**性能实测（诚实记录，见 §6）**：14 个语言 `registerDynamicLanguage` 冷启 **121 ms**；单文件 17 KB typescript 解析 **26.6 ms**；遍历 `better-dsh/src` 188 文件 / 1.1 MB 源码（解析+匹配）**1,273 ms ≈ 0.9 MB/s**（单线程）。
+
+---
+
+## 3. 模块设计
+
+```
+src/devices/ast/
+  engine/
+    wasm.ts          ← 手动 wasm 装配 + Parser.init + 惰性单例；唯一的 wasm 入口
+    grammars.ts      ← 语言注册表：lang → 资产路径 + expandoChar 'µ'；懒注册、按需
+    language-map.ts  ← 扩展名 → 语言（**单一真相源**）
+    match.ts         ← pattern 编译 + 多根节点记 0 命中 + 命中 → AstFindMatch 映射（字节偏移）
+    edit.ts          ← astEdit 核心：rewrites / dryRun / changes[] / 字节偏移换算
+  walker.ts          ← .gitignore 感知遍历 + glob + 语言推断 + maxFiles 限额
+  ast-device.ts      ← 保持公开契约，改为调 engine + walker（薄适配层）
+  ast-reminder.ts    ← 语言集合改为对齐 engine 的语法表（不再"对 shipped 二进制实测"）
+  natives-loader.ts  ← **删除**
+```
+
+**资产流**：新增 `scripts/copy-ast-assets.mjs`，构建期把 3 件套 wasm 从 `node_modules` 拷进 `lib/ast-assets/`（`files: ["lib", …]` 已覆盖，无需改发布面）。构建链改为：
+
+```
+tsdown && npm run build-client && node scripts/copy-kernel-bridge.mjs && node scripts/copy-ast-assets.mjs
+```
+
+> ⚠ 必须在 `tsdown` **之后**：tsdown 会清空 `lib/`（同 `lib/client/` 的老坑）。
+
+**依赖面**：`@ast-grep/wasm` / `web-tree-sitter` / `@lumis-sh/wasm-*`（14 个）进 `devDependencies`。`src/vendor.ts` 本身保留（`dvc://browser` 的 puppeteer 仍用它），只删掉 pi-natives 的调用点与 `PI_NATIVES_VERSION`。
+
+**需要主动补齐的行为（照 OMP 语义实现，不是搬运）**：
+
+- **多根节点 pattern = 记 0 命中**：`function $N($$$A) { $$$B }`、`"alpha": $V` 这类片段在 wasm 的 `findAll` 会抛 `Multiple AST nodes are detected`。OMP 的 Rust 库虽有 `compile_wrapped_fallback`（`ops.rs`，仅 JSON 有模板），但实测 shipped native 在这条路径上并未用它：`astGrep` 返回 `matches=0` 且 `parseErrors=null`，`astEdit` 返回 `totalReplacements=0` 且结果里没有 `parseErrors` 键。因此 TS 侧对齐的是 **native 的实测行为**：捕获该异常 → 记 0 命中、不写 `parseErrors`、不抛错。
+- **`.gitignore` 感知遍历** + glob 过滤 + `maxFiles` / `maxReplacements`。
+- **UTF-8 字节偏移换算**：`range().index` 是**字符**偏移，OMP 的 `byteStart`/`byteEnd`/`deletedLength` 是**字节**偏移（实测含中文时 17 vs 25）。`changes[]` 生成时换算。
+- **parseError 收集**、分页（`offset`/`limit`）、`includeMeta` 的 meta 变量收集、聚合统计。
+
+**错误处理**：`wasm.ts` 加载失败 → 设备级 `DVC_DEVICE_ERROR`（措辞：内置引擎不可用，不再叫用户去装 npm 包）；单语言语法加载失败 → 该语言文件跳过并计入 `parseErrors`，其余语言照常。
+
+---
+
+## 4. 随本 change 一并改的文档
+
+行为契约里目前写着 `@oh-my-pi/pi-natives`，必须同步改（否则 spec/impl 脱节）：
+
+- `docs/20_specs/ast/spec.md` + `docs/specs/ast/spec.md`（两文件当前**内容相同**，同步改）：`Lazy natives, zero startup cost` 一条的措辞从"natives 懒加载"改为"内置 WASM 引擎按需加载"。
+- `docs/20_specs/dvc/spec.md` + `docs/specs/dvc/spec.md`：`ast devices` 一条删掉 "backed by the published `@oh-my-pi/pi-natives` binding"，改为内置 WASM 引擎。
+- `THIRD_PARTY_NOTICES.md`：增列 ast-grep / tree-sitter / `@lumis-sh/wasm-*`（三件套均 MIT）。
+- `src/NOTICE-OMP.md`：**保留**（已核：该文件覆盖 browser / lsp / ast 三类共 8 个文件，ast 不是唯一来源）。`browser-device.ts`、`lsp-device.ts`/`lsp-client.ts`/`lsp-jsonrpc.ts`/`lsp-language.ts`/`lsp-types.ts`/`lsp-server-registry.ts` 仍显式引用它。正文无需改（通用措辞，未点名 ast）；仅在实现时确认 ast 的 2 个文件删除后**没有**残留 `../NOTICE-OMP.md` 引用。
+
+---
+
+## 5. 验收（对齐"改动点同类"红线）
+
+1. **A/B 一致性矩阵常驻单测**：同一组 pattern 在 native 与 WASM 下逐条结果相同（§2.1 的表落成 `test/`）。
+2. **离线第一人称实测**：断网 + 删掉 `<pkg>/.vendor` 后，4999 rig 上真实 session 走通 `dvc://ast_grep` 与 `dvc://ast_edit`（含 dryRun 与真写盘）。
+3. **零 OMP 实证（代码/产物面）**：`npm pack` 出的 tarball 在 `lib/`、`package.json`、`scripts/` 上 `grep -rc "pi_natives\|@oh-my-pi"` = 0（`docs/` 发布载荷的历史性提及不计入）；运行期无 registry 请求。
+4. **工具面口径同类**：`tsc --noEmit` 0 错；全量单测绿；boot graph 含 better-dsh；`dvc://` roster 仍列出两个 ast 设备。
+5. 实测报告落 `docs/50_test-reports/`；**发布仍需 user 明确放行**（单次授权，见根 AGENTS.md 〇节）。
+
+---
+
+## 6. 已知风险与代价
+
+| 风险 | 说明 | 处置 |
+|---|---|---|
+| **吞吐下降** | WASM 单线程 ≈ 0.9 MB/s；native 是 Rust 并行遍历。大仓全量 codemod 会明显变慢 | 明示接受（该设备 3 周 0 调用）。若日后成为瓶颈，再评估 worker 分片 |
+| **语法 ABI 锁步** | `dylink.0` 要求 `web-tree-sitter` 与语法包**主版本同步**升级 | 两者一起 pin；升级走显式、带 A/B 的变更 |
+| **语言面依赖第三方语法包** | `@lumis-sh/wasm-*` 是社区包（MIT，活跃） | 路径与版本在 `grammars.ts` 单点声明；若某语言其停更，可自行 `tree-sitter build --wasm`（本机有 docker）替换单个资产 |
+| **`expandoChar` 静默失效** | 漏给 `µ` 会导致某语言**静默 0 命中**（不报错） | 每个语言注册后跑一次自检 pattern；单测锁定全语言矩阵 |
+| **per-language pattern 歧义** | C 的 `foo($A)`、CSS 的 `color: $V` 匹配不到 | **与上游 native 行为一致**（已 A/B 证），非本 change 引入，不修 |
+| 字节偏移换算错位 | 含多字节字符时 `changes[]` 坐标会偏 | 单测覆盖 CJK 用例 |
+
+---
+
+## 7. 进展日志
+
+- **2026-10-03 设计轮**：user 裁决路线 A（官方 `@ast-grep/wasm` 引擎 + TS 底盘），14 个语法全部随包。丢弃式 spike 落在 `.scratch/ast-wasm-spike/`（`probe.mjs` / `iso.mjs` / `expando.mjs` / `comboA|B|C.mjs` / `probe3.mjs` / `probe4.mjs` / `ab-native.mjs`）：
+  - 证伪了 `tree-sitter-wasms@0.1.13`（legacy `dylink`）；
+  - 证真了 `@lumis-sh/wasm-*` 0.26.x（`dylink.0`）覆盖全部 14 语言；
+  - 定位并解决 `expandoChar` 与手动 wasm 装配两个坑；
+  - 与真 native 完成 A/B，行为零回归；
+  - 量得 14.4 MB 资产、0.9 MB/s 吞吐、字节偏移差异。

package/node_modules/better-dsh/docs/specs/authentication-only-web-admission/spec.md

@@ -0,0 +1,51 @@
+# Authentication-only Web admission
+
+## Goal
+
+An operator can reach their authenticated DSH deployment through any domain or
+LAN address without maintaining separate server and browser address allowlists.
+The server keeps its current bind address; the existing rig's LAN relay supplies
+LAN reachability. This feature does not change listening interfaces.
+
+## Configuration
+
+Opt in through the existing `dashr-web-trust` row:
+
+```yaml
+- id: dashr-web-trust
+  name: better-dsh/web-trust
+  config:
+    trustAllHosts: true
+```
+
+The default is `false`, retaining existing declared-authority behavior. When
+enabled, `--trusted-host`, `DSH_TRUSTED_HOSTS` and `trustedPageAuthorities` are
+not needed for admission or page management privileges.
+
+## Contract
+
+- Keep the original Connection instance, transport, RPC registrations and token
+  exchange. No upstream source changes, replacement service or private-field
+  access are required.
+- Replace only its `requestRejection` method while this row is active. Delegate
+  cookie verification to public `authorizeIndex`, using the real request headers
+  and a fixed query-free index URL. Discard the index responder's output; the
+  transport remains responsible for the actual HTTP response.
+- Any address, Origin and Fetch-Metadata marker can pass after authentication.
+  Missing, invalid, expired or wrong-authority cookies still return 401. Cookie
+  lifetime and signing remain the native authenticator's responsibility.
+- This API admission delegate never exchanges a URL token: normal index login
+  still performs that exchange. Existing password-login behavior is unchanged.
+- Inject `ownsHost: true` before browser application initialization, regardless
+  of page hostname, without overwriting an existing transport. Management UI
+  consumers continue to use the original Connection's common capability flag.
+- Unloading or disabling this row restores the original admission method;
+  reload the page to update its initialization-time capability flag.
+
+## Acceptance
+
+Use a packaged plugin installed through `dsh plugin add` in the long-lived 4999
+rig, with no trusted-host CLI argument or environment variable. Verify loopback,
+LAN and the actual HTTPS deployment domain; an additional unlisted Host must
+authenticate successfully without bypassing cookie verification. Check settings
+persistence, provider settings and plugin management in the real browser.

package/node_modules/better-dsh/docs/specs/compaction-recall/spec.md

@@ -0,0 +1,46 @@
+# compaction-recall Specification
+
+## Purpose
+TBD - created by archiving change 2026-09-11-url-schemes-recallable-context. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Compaction manifest with nested chain
+The system SHALL expose the compaction manifest of the live session, one entry per successful compaction episode, each carrying: `label` (the `compaction/summary` event seq), `checkpoint_seq` (summary seq + 1), `compactionId`, timestamp, `shadowedRange`, `shadowedItems`, `shadowedTokenCount`, `replaces_checkpoint` (the previous episode's checkpoint seq when absorbed, else null), and an 8-section summary preview (≤100 chars per section).
+
+#### Scenario: Manifest reflects nested compaction
+- **WHEN** a session has two successful compactions where the second absorbed the first's checkpoint
+- **THEN** the manifest lists both episodes and the second entry carries `replaces_checkpoint` equal to the first episode's checkpoint seq
+
+### Requirement: Label resolution precedes ordinal
+For any bracket-addressed collection, the system SHALL match the label (the element's immutable seq coordinate) exactly first, and SHALL fall back to the 0-based ordinal only when no label matches. Compaction episodes SHALL use the `compaction/summary` event seq as label; failed compactions SHALL NOT appear in any collection because they never emit a summary event.
+
+#### Scenario: Failed compaction is not addressable
+- **WHEN** a compaction attempt fails (summary not smaller than shadowed content) and the model reads the compactions manifest
+- **THEN** the failed episode is absent from the manifest and has no addressable label
+
+### Requirement: Canonical and prepared faces for compaction episodes
+For `ctx://session/compactions[<label>]`, the bare URL SHALL return the episode's structured summary (all 8 sections verbatim) as the prepared default face, and `:raw` SHALL return the episode's canonical content — the original shadowed span derived from `shadowedSeqs` (role + content per item). Line windows SHALL always apply to the canonical content, and the composite `:raw:<lines>` form SHALL be valid and equal `:<lines>`. The former `/original` sub-path SHALL be removed — it was identical to `:raw` and is superseded by composing the `:raw` / `:N-M` selectors directly on the episode; a path using it SHALL be rejected with the structured `CTX_BAD_PATH` error echoing the URL. When an unwindowed `:raw` read of the canonical face exceeds 65536 chars, the system SHALL append an actionable note naming `:N-M` line-window paging; windowed reads (`:N-M`, `:raw:N-M`) and the bare prepared face SHALL NOT carry the note.
+
+#### Scenario: Recall of the original span behind a summary
+- **WHEN** the model reads `ctx://session/compactions[221217]:raw` after the episode shadowed 559 items
+- **THEN** the system returns the original message-level content of all shadowed items, including tool results and assistant messages
+
+#### Scenario: Chained recall to pre-previous originals
+- **WHEN** the model reads `ctx://session/compactions[109245]:raw` (the first episode in a nested chain)
+- **THEN** the system returns the first span's original content even though later compactions shadowed its checkpoint
+
+#### Scenario: Unwindowed raw recall of an oversized span pages explicitly
+- **WHEN** the model reads `ctx://session/compactions[221217]:raw` and the span exceeds 65536 chars
+- **THEN** the system returns the full span followed by a note naming `:N-M` line-window paging, while `:raw:N-M` / `:N-M` return the windowed lines without the note
+
+#### Scenario: Removed /original sub-path
+- **WHEN** the model reads `ctx://session/compactions[221217]/original`
+- **THEN** the system rejects the path with `CTX_BAD_PATH`, echoing the URL
+
+### Requirement: Recall is read-only and lazily materialized
+The system SHALL serve all recall resources strictly read-only, SHALL build the episode index lazily from the session log (zstd-decompressed, single-pass seq index) with invalidation on session-file change, and SHALL NOT impose truncation on canonical content beyond the tool layer's own limits, surfacing an actionable truncation note instead.
+
+#### Scenario: Oversized original request
+- **WHEN** the model reads an original span exceeding the tool-layer response cap
+- **THEN** the system returns the truncated head (or the requested line window) with a note naming the `:raw`/line-window addressing for the remainder

package/node_modules/better-dsh/docs/specs/ctx/spec.md

@@ -0,0 +1,179 @@
+# ctx Specification
+
+## Purpose
+
+Let the model read a curated, read-only snapshot of its calling environment via `ctx://` URLs — small, static, agent-derived facts (who am I, what model, what cwd) addressable like any other resource, plus a recallable-context navigation surface over the live session's event log. This replaces the v0.1.8c design that mapped `ctx://` onto persistent-kernel variables; see design.md D4 for why that semantics was wrong (the kernel namespace is the model's own REPL scratchpad, not its environment).
+
+## Requirements
+
+### Requirement: Coordinate invariant
+Every number the system shows the model SHALL be either directly usable as a selector in the same URL family, or explicitly labeled metadata with its unit. The two coordinates are `seq` (event sequence, for `[<label|n>]` addressing) and `line` (transcript line, for `:N-M` windows and `grep` on `ctx://session/transcript`); both SHALL be labeled wherever shown. An unlabeled number that is not an addressable coordinate SHALL NOT appear.
+
+#### Scenario: Labeled coordinates in the manifest
+- **WHEN** the model reads `ctx://session/compactions`
+- **THEN** every episode row carries `seq=<start>..<end>` and `lines=<start>..<end>` (or `lines=<none>` for an empty span), never a bare range that could be misread as the other unit
+
+### Requirement: Curated snapshot keys
+The system SHALL resolve `ctx://session` as the recallable-context statistics snapshot: the prepared default face SHALL carry the session header (absorbing the former identity fields `id`/`status`/`origin`/`delegationDepth`), storage facts, totals using native DSH field names, per-compaction segments plus a `live` tail segment (each with `seq_start`/`seq_end` and `lines`), the inline compactions manifest (label, checkpoint_seq, compactionId, `seq_start`/`seq_end`, `lines`, shadowedItems, shadowedTokenCount, `fidelity`, `replaces_checkpoint`, and an 8-section × ≤100-char summary preview per episode), an `asOf` card (max seq and transcript line at read time, with a note that totals are live values), and a `system_prompt` info card. The canonical face (see `:raw`) SHALL be the full session transcript. The first-level keys `model` and `cwd` SHALL be removed — their information SHALL appear only as info-card fields inside the snapshot. Any other first-level key SHALL return the structured `CTX_UNKNOWN_KEY` error listing the known keys and sub-paths.
+
+#### Scenario: Reading session identity
+- **WHEN** the model reads `ctx://session` from a delegated subagent session
+- **THEN** the snapshot header carries the agent id, status, origin, and delegation depth
+
+#### Scenario: Reading the model configuration
+- **WHEN** the model reads `ctx://session`
+- **THEN** the snapshot info card carries the provider, model, and maxTokens of the calling agent's request options
+
+#### Scenario: Reading the working directory
+- **WHEN** the model reads `ctx://session`
+- **THEN** the session's creation working directory appears as an info-card field, not as a separate key
+
+#### Scenario: Staleness is self-evident
+- **WHEN** the model reads `ctx://session` and caches the snapshot
+- **THEN** the `asOf` card tells it the seq and line the snapshot was taken at, so it cannot mistake a cached snapshot for live totals
+
+#### Scenario: Unknown key
+- **WHEN** the model reads `ctx://<other key>`
+- **THEN** the system returns the structured `CTX_UNKNOWN_KEY` error naming the known keys and sub-paths
+
+### Requirement: Bare listing
+The system SHALL let bare `ctx://` return the roster of available resources and usage entry points (one per line), including the `session` root, the sub-path grammar pointer (naming the composite `:raw:N-M` form), and the `transcript`/`compactions`/`user_prompts`/`tool_calls`/`agent_responses`/`thinking`/`system`/`injections` sub-paths; the static portion SHALL not require a live agent, and the roster SHALL stay within its line budget (its previous size plus the three collection entries).
+
+#### Scenario: Listing keys
+- **WHEN** the model reads bare `ctx://`
+- **THEN** the system returns the roster naming `session`, its sub-paths (including `thinking` and `system`), and the addressing-grammar pointer
+
+### Requirement: Snapshot requires a live agent
+The system SHALL read every snapshot value from the calling agent supplied in the resolver env; an env with no live agent returns the structured `CTX_NO_AGENT` error on any value read.
+
+#### Scenario: No agent in the context
+- **WHEN** a ctx:// value read runs with no live agent in the resolver env
+- **THEN** the system returns the structured `CTX_NO_AGENT` error
+
+### Requirement: ctx is strictly read-only
+The system SHALL reject every write to `ctx://` with the structured `URL_READ_ONLY` error explaining the scheme is a curated read-only snapshot. There is no kernel-variable write channel and no variable mutation of any kind.
+
+#### Scenario: Writing to a snapshot key
+- **WHEN** the model writes to `ctx://<any key>`
+- **THEN** the system returns the structured `URL_READ_ONLY` error and changes nothing
+
+### Requirement: Session sub-path grammar
+The system SHALL resolve `ctx://session/…` sub-paths: `transcript` (full transcript), `compactions` (manifest), `compactions[<label|ordinal>]` (the episode summary), `user_prompts[<n|seq>]`, `tool_calls[<n|seq>]`, `agent_responses[<n|seq>]`, `thinking[<n|seq>]` (reasoning blocks), and `system[<n|seq>]` (system messages). The former `compactions[<label|n>]/original` sub-path SHALL be removed — it was identical to `:raw` and is superseded by composing the `:raw` / `:N-M` selectors directly on the episode; a path using it SHALL be rejected with the structured `CTX_BAD_PATH` error echoing the URL. Bracket resolution SHALL match the label (the element's immutable seq coordinate) exactly first, and SHALL fall back to the 0-based ordinal on miss. The system SHALL support `:raw`, line windows (`:N`, `:N-M`, `:N+K`, `:N-`, comma-separated ranges), `:path/<dot-path>`, and `?q=<query>` on every resolved resource; the composite `:raw:<lines>` form SHALL be valid everywhere and SHALL equal `:<lines>` (the `:raw` prefix is redundant in a line-window context but MUST parse). Line windows on a compaction episode SHALL interpret numbers as transcript line coordinates (identical to the same window on `transcript`), and `:path/`/`?q=` SHALL apply to the bare (prepared) face.
+
+#### Scenario: Drilling into a compaction episode by label
+- **WHEN** the model reads `ctx://session/compactions[221217]`
+- **THEN** the system returns that episode's structured summary (all 8 sections verbatim) or, for the latest episode, the navigation block (see digest residence)
+
+#### Scenario: Ordinal fallback
+- **WHEN** the model reads `ctx://session/compactions[0]` and no episode carries the label `0`
+- **THEN** the system returns the first-recorded episode (0-based)
+
+#### Scenario: Transcript-relative episode window
+- **WHEN** the model reads `ctx://session/compactions[<label>]:5300-5310`
+- **THEN** the system returns transcript lines 5300–5310 — the same bytes as `ctx://session/transcript:5300-5310`
+
+#### Scenario: Composite raw selector
+- **WHEN** the model reads `ctx://session/compactions[221217]:raw:500-560`
+- **THEN** the system returns the same lines as `ctx://session/compactions[221217]:500-560`
+
+#### Scenario: Removed /original sub-path
+- **WHEN** the model reads `ctx://session/compactions[221217]/original`
+- **THEN** the system returns the structured `CTX_BAD_PATH` error echoing the URL and naming the `:raw` / `:N-M` selectors as the replacement
+
+### Requirement: Canonical and prepared content faces
+The system SHALL treat every resource as having one canonical content: `:raw` SHALL return the canonical full content, line windows SHALL always apply to the canonical content, and the bare URL SHALL return the prepared default face when one is prepared (session → statistics snapshot; compaction episodes → digest/navigation block; `thinking`/`system`/`injections` and the element collections → index lists) or the canonical content when none is. `:raw:<lines>` SHALL equal `:<lines>` — the composite form is accepted on every resource. A line window that reaches past a resource's canonical extent SHALL return an explicit boundary note (e.g. `[ctx:// note: … span is transcript lines <s>-<e>]`) rather than silently returning a truncated or empty view.
+
+#### Scenario: Line windows ignore the prepared face
+- **WHEN** the model reads `ctx://session/compactions[221217]:500-560`
+- **THEN** the system returns transcript lines 500–560 of the episode's original shadowed span, not of the summary
+
+#### Scenario: Out-of-span window is explicit
+- **WHEN** the model reads `ctx://session/compactions[221217]:5500` and the episode span ends before transcript line 5500
+- **THEN** the system returns the boundary note naming the episode's span instead of an empty string
+
+#### Scenario: Over-read notes, open tail does not
+- **WHEN** the model reads a window whose upper bound exceeds the canonical extent (e.g. `transcript:1940-2000` on a 1947-line transcript)
+- **THEN** the system returns the available lines plus the boundary note naming the canonical end — a partial over-read is still an over-read, because otherwise the model cannot tell "empty" from "does not exist"
+- **WHEN** the model reads the open-tailed `transcript:1940-`
+- **THEN** the system returns the remaining content to the end with no boundary note, provided the window's start is within the extent
+- **WHEN** the model reads an open tail whose start is already past the extent (e.g. `compactions:2-` when the canonical content is one line)
+- **THEN** the system returns the boundary note alone — there is no content to return, so the over-read must be spoken for
+
+#### Scenario: Upper bound exactly at the extent is not an over-read
+- **WHEN** the model reads `compactions:1-1` where the canonical content is exactly one line
+- **THEN** the system returns that line with no boundary note
+
+### Requirement: Episode digest residence
+The system SHALL render the prepared face of the **latest** compaction episode as a navigation block (NOT the digest text, which is already resident in the model's live context as the compact-checkpoint message): it SHALL name the episode's `lines`/`seq`/items/tokens, its `fidelity`, the transcript lines where the resident digest lives (`digest resident at transcript:<start>-<end> (seq=<checkpointSeq>)`), and the landmark roster. The prepared face of every **older** episode SHALL return that episode's full digest (`summaryText`) followed by the same pointer block. `:raw` on any episode SHALL always return the full shadowed span, so a digest is never lost.
+
+#### Scenario: Latest episode is a pointer, not a dump
+- **WHEN** the model reads the bare URL of the most recent compaction episode
+- **THEN** the system returns the navigation block with the digest's transcript location and landmarks, and does NOT repeat the digest text
+
+#### Scenario: Older episode returns its digest
+- **WHEN** the model reads the bare URL of a non-latest compaction episode
+- **THEN** the system returns that episode's full digest followed by its pointer block
+
+### Requirement: Landmark roster
+The system SHALL include, in each compaction episode's navigation/pointer block, a direction-marker roster computed over that episode's shadowed events, every marker expressed as transcript line coordinates directly usable with `:N-M`: user-turn lines, failure lines (tool results with `message.isError` true or a present error), touched file paths with occurrence counts (best-effort, from tool-call arguments), and the count of prior checkpoints absorbed in the span. Rosters SHALL be capped to a screen and SHALL tail with `… +N more` when capped.
+
+#### Scenario: Locating user turns and failures
+- **WHEN** the model reads a compaction episode's prepared face
+- **THEN** the landmark block lists user-turn lines and failure lines as transcript line numbers
+
+#### Scenario: Locating touched files
+- **WHEN** the model reads a compaction episode whose span contains file tool calls
+- **THEN** the landmark block lists each touched path with its occurrence count
+
+### Requirement: Fidelity signal
+The system SHALL include, per compaction episode, a `fidelity=<user_turns>:<tool_calls>` figure (in the manifest, the snapshot, and the episode pointer block) so the model can judge whether the digest is trustworthy: a tool-heavy span's digest is trustworthy and detail is regenerable, while a user-intent-heavy span must be drilled into.
+
+#### Scenario: Reading fidelity
+- **WHEN** the model reads `ctx://session/compactions` or a compaction episode's prepared face
+- **THEN** each episode carries its `fidelity` ratio
+
+### Requirement: Thinking, system, and injections collections
+The system SHALL expose three index-faced collections under `ctx://session/`, all following the canonical/prepared face model (bare URL = prepared index; `:raw` / `:N-M` = canonical full text):
+
+- `thinking` — the reasoning blocks of `assistant/message` events (`message.content` blocks of `type: "reasoning"`, in event order; a message may carry several). The bare URL SHALL return an index list, one line per block: 0-based ordinal, event seq, turn/step, and a ≤100-char single-line preview. `[<n|seq>]` SHALL return that block's full text (label = the block's event seq, exact match first, 0-based ordinal fallback). `:raw` SHALL return all blocks' full text joined in event order with a blank line between blocks, and line windows SHALL index that canonical text.
+- `system` — the session's `system/message` events (text from `data.text` when present, else the message content blocks; source kind/plugin from `data.source` when present). The bare URL SHALL return an index list, one line per message: event seq, source kind/plugin, and a ≤100-char single-line preview. `[<n|seq>]` SHALL return that message's full text. `:raw` SHALL return all messages' full text joined with a blank line between messages, and line windows SHALL index that canonical text.
+- `injections` — the session's injected `user/message` events, i.e. every `user/message` whose `source.kind` is not `user` (agent instructions, runtime-context snapshots, …; the exact complement of the `user_prompts` collection). The bare URL SHALL return an index list, one line per message: event seq, source kind, and a ≤100-char single-line preview. `[<n|seq>]` SHALL return that message's full text rendered as `[<zero-padded seq>] INJECTED <kind>` followed by the content. `:raw` SHALL return all messages' full text joined with a blank line between messages, and line windows SHALL index that canonical text.
+
+#### Scenario: Index then drill into a reasoning block
+- **WHEN** the model reads `ctx://session/thinking` and then `ctx://session/thinking[2]`
+- **THEN** the index lists one line per reasoning block (ordinal, seq, turn/step, preview) and the drilled read returns the third block's full text
+
+#### Scenario: Canonical window over the joined blocks
+- **WHEN** the model reads `ctx://session/thinking:10-20`
+- **THEN** the system returns lines 10–20 of the reasoning blocks' full text joined with blank lines, ignoring the index face
+
+#### Scenario: System message by seq label
+- **WHEN** the model reads `ctx://session/system[7]` where event seq 7 is a system message
+- **THEN** the system returns that message's full text
+
+#### Scenario: Injections complement user_prompts
+- **WHEN** the model reads `ctx://session/injections` in a session whose `user/message` events carry both `source.kind: "user"` and non-`user` sources (agent instructions, runtime snapshots)
+- **THEN** the index lists only the non-`user` messages (seq, source kind, preview), `ctx://session/injections[<n|seq>]` returns one message's full text, and `ctx://session/user_prompts` continues to list only the real prompts
+
+#### Scenario: Injection message by ordinal or seq
+- **WHEN** the model reads `ctx://session/injections[0]` or `ctx://session/injections[<seq>]`
+- **THEN** the system returns that injected message's full text with its `INJECTED <kind>` header line
+
+### Requirement: Element collections carry index faces
+The system SHALL give `user_prompts`, `tool_calls`, and `agent_responses` the same prepared-index/canonical model: the bare URL SHALL return an index list (one line per element: event seq and a ≤100-char preview; the long `tool_calls`/`agent_responses` collections SHALL cap the bare index at a screen and tail with `… +N more — use :raw for all, ?q= to filter, [n|seq] for one`); `[<n|seq>]` SHALL return that element's full text; `:raw` SHALL return all elements' full text joined; line windows SHALL index that canonical text. The error for an unaddressed or out-of-range element SHALL name the collection and its count and SHALL NOT echo an empty-bracket URL.
+
+#### Scenario: Browsing user prompts
+- **WHEN** the model reads `ctx://session/user_prompts`
+- **THEN** the system returns an index list of the real user prompts (seq + preview)
+
+#### Scenario: Addressing a tool call
+- **WHEN** the model reads `ctx://session/tool_calls[<seq>]`
+- **THEN** the system returns that call's name, arguments, and result — where a present result's text is rendered from either the flat or the nested content-block shape, never silently empty
+
+### Requirement: Unknown key echoes known keys
+The `CTX_UNKNOWN_KEY` error SHALL list the currently known first-level keys and the sub-path pointer, so the model can self-correct without leaving the read tool.
+
+#### Scenario: Unknown key with roster echo
+- **WHEN** the model reads `ctx://bogus`
+- **THEN** the system returns `CTX_UNKNOWN_KEY` naming `session` and the sub-path roster
+

package/node_modules/better-dsh/docs/specs/docs-packaging-trim/spec.md

@@ -0,0 +1,110 @@
+# 发布包瘦身：摘掉与 DSH/本插件无关的 docs（docs-packaging-trim）
+
+状态：**设计已定（user 裁决 2026-10-03：档位 F）；待落实现**
+｜ 规格路径：`docs/specs/docs-packaging-trim/spec.md`（仓库根 docs；`better-dsh/docs/` 是 `prebuild` 由 `../docs` 重建的产物，别写那里）
+
+---
+
+## 0. 动机（审计实证）
+
+`better-dsh` 的 tarball 是 **20.2 MB**，而 `lib/`（真正的代码）只有 **2.5 MB**。差额几乎全在**随包发布的 docs 副本**上：`tar czf docs` = **20.3 MB**（含 tar 开销），即 tarball 基本等于 docs。
+
+`scripts/copy-docs.mjs` 把仓库 `docs/` 拷进 `better-dsh/docs/`（`files: ["docs"]` 发布），已有 EXCLUDE 规则只挡了 `60_exploration-and-research/`、`superd/`、`dsh-sys-prompt_*.md`、`*_artifacts/`。逐目录盘点后，剩下的发布面里混着**与 DSH 和本插件都无关的东西**。
+
+### 0.1 关键澄清：`80_upstream-docs-and-skills/` 不是"纯文档"
+
+user 提问："`api-skills.json` 不是给人读的，那它存在的唯一意义就是作为技能放在 skills 目录让 harness 读取，对吧？既然是纯文档就不需要它？"
+
+**比这更弱**——该目录自己的 `src-README.md` 写明：
+
+> This stage only does the **fetching**; distillation into a skill is a separate follow-up
+
+即 `hermes-dev-skill/` 是"抓取 → 蒸馏成技能"两阶段流水线的**第一阶段**，而**第二阶段从未执行**：整个目录没有 `SKILL.md`、没有 `skill/`。所以这 77 MB 是**没有被任何东西消费的流水线输入**——既不是技能，也不是文档。`api-skills.json` 是 `https://hermes-agent.nousresearch.com/docs/api/skills.json`（59 MB），**Hermes 自己那套技能的机器可读目录**，`grep` 全仓无引用。
+
+### 0.2 归属：这是别人的框架说明书
+
+`hermes-dev-skill` 是 **NousResearch/hermes-agent** 官方文档的完整镜像（`src-README.md` 记着 sparse clone commit `4e9d3c71…` 与抓取日期 2026-09-16），它自己声明的用途是：
+
+> so agents that develop / integrate with **Hermes Agent** can work without hitting the live site
+
+——一个**别的 agent 框架**的说明书。Hermes 有自己的文档站与仓库（该 README 自己就引了）。入库溯源：commit `d13c4a3`，提交信息为 *"rig(test123): remove profiles/node_modules symlink farm"*——一个与文档无关的 rig 提交把它捎带进来。
+
+### 0.3 全树盘点（`copy-docs.mjs` 实际发布范围）
+
+| 路径 | 磁盘 | 是什么 | 判定 |
+|---|---|---|---|
+| `00_adr/` `10_plans/` `20_specs/` `specs/` | 980 K | 本仓 ADR / 计划 / 规格 | ✅ 留 |
+| `50_test-reports/` | 3.5 M | 本仓实测报告（已做 token 脱敏） | ✅ 留 |
+| `superpowers/` | 40 K | 本仓两份 spec/plan | ✅ 留 |
+| `80_.../hermes-dev-skill/` | **77 M** | 别家框架文档镜像；抓取阶段，无 `SKILL.md`，零引用 | ❌ **摘** |
+| `80_.../dsh-dev-skill/pi-and-omp/` | **2.8 M** | OMP / Pi 第三方资料；**技能正文零引用**（`grep -rn "pi-and-omp" skill/` 为空） | ❌ **摘** |
+| `80_.../dsh-dev-skill/src-scripts/` | **3.4 M** | 抓取工具 + `docs-tree.json`（3.5 M 构建清单） | ❌ **摘** |
+| `80_.../dsh-dev-skill/skill/` | 304 K | DSH 开发知识库蒸馏稿（`SKILL.md` + 22 章）——**静态文档**，与技能运行时无关 | ✅ 留（DSH 相关） |
+| `80_.../dsh-dev-skill/src/` | 4.0 M | DSH 官方文档快照——**被 `SKILL.md` 与 4 个章节明确引用** | ✅ 留 |
+| `dsh-docs/`（包根） | 4.1 M | DSH 官方文档（较新），`dsh://docs` 主面 | ✅ 留 |
+| `60_exploration-and-research/` `superd/` | — | 已在既有 EXCLUDE 内 | — |
+
+> **不要整段摘 `80_upstream-docs-and-skills/`**：`dsh-dev-skill/` 的内容是**蒸馏过的官方 DSH 文档**，按本 change 的留置规则属「与 DSH 相关」的静态文档。**与技能运行时无关**：Harness 技能发现只扫四个根（`<project>/.dsh/skills`、`<project>/.agents/skills`、`~/.dsh/skills`、`~/.agents/skills`，见 `packages/skill/skill-filesystem/src`），插件 docs 树从来不在其中。`dsh://docs` 是纯静态资源——装了插件任何人都能读，里面的目录叫不叫 skill，与 Harness 加载什么技能毫无关系。早期版本的本节曾称它是「运行时真正加载的技能、整段摘会打断一个技能」，**那是错误推断**（把「文件存在」当成了「被运行时加载」），已撤回。
+
+> **重复发布（本 change 不处理）**：`dsh-docs/`（249 文件）与 `…/dsh-dev-skill/src/docs/`（241 文件）是同一套官方 DSH 文档的**两个修订版**（后者较旧）。摘后者需同时改写 `SKILL.md` 与 4 个章节里 `../src/docs/` 的指向——那是**文档内部交叉引用**问题（静态库里出现悬空指针），不是技能问题，另开 change 评估。
+
+---
+
+## 1. 目标态（硬契约）
+
+1. **发布副本里不再出现**：`hermes-dev-skill/`、`dsh-dev-skill/pi-and-omp/`、`dsh-dev-skill/src-scripts/`。
+2. **repo 的 `docs/` 一字不动**：`copy-docs.mjs` 只改写发布副本 `better-dsh/docs/`。本仓测试报告、技能源、任何交叉引用与本地技能（如引用 `site-pages-map.txt` 的 `.agents/skills/cordis-dsh-dev`）全不受影响。
+3. **承重面完好**：`dsh-dev-skill/skill/`（含 `SKILL.md`）与其引用的 `src/docs/`、`src/site-pages-map.txt` 必须**全部保留**。
+4. **无新的悬空引用**：发布副本内不得有指向被摘路径的活引用（见 §3 的已知例外）。
+5. **不改语言/行为面**：本 change 纯打包面，不触碰任何源码或技能正文。
+
+---
+
+## 2. 改动
+
+`scripts/copy-docs.mjs` 的 `EXCLUDE` 数组增加 3 条目录规则（沿用既有的"按源路径正则匹配"形式）：
+
+```js
+/(^|\/)hermes-dev-skill($|\/)/,
+/(^|\/)dsh-dev-skill\/pi-and-omp($|\/)/,
+/(^|\/)dsh-dev-skill\/src-scripts($|\/)/,
+```
+
+不删除任何仓库文件，只改变**进包集合**。
+
+---
+
+## 3. 已知例外（明示接受，不做过度工程）
+
+`docs/80_upstream-docs-and-skills/dsh-dev-skill/src-README.md` 在正文里提到 `src-scripts/`（抓取清单的结构说明）。摘掉该目录后，**发布副本**里这份 fetch manifest 会描述一个不在包内的目录。
+
+- 影响面：仅"文档自述"的措辞不一致，无功能影响；该 manifest 的价值在于说明 `src/` 是什么。
+- 处置：**接受**。不改写正文（改写会让发布副本与 repo 副本分叉，违背 §1.2）。若日后要更干净，用发布期的占位替换，另开 change。
+
+---
+
+## 4. 验收
+
+1. **量化**：`npm pack` 出的 tarball 从 **20.2 MB → ≈ 3.7 MB**（docs 贡献 20.3 → 3.7 MB）；安装后磁盘 sizeof(`docs/`) 从 **98 MB → ≈ 15 MB**。
+2. **承重存活**：解包 tarball，`docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/SKILL.md` 与 `src/docs/`、`src/site-pages-map.txt` 均在位；被摘三目录不存在。
+3. **静态文档可读**：rig 上 `read dsh://docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/SKILL.md` 能取回正文——它只是众多静态文档之一。~~会话技能目录仍列出 `dsh-dev-skill`、`skill://dsh-dev-skill` 可读~~ 该判据建立在错误模型上，撤回：技能是否被 Harness 加载取决于 user 本地 / per-workspace 安装，与本插件无关。
+4. **零新增悬空引用**：在解包后的 `docs/` 内 `grep -rn "hermes-dev-skill\|pi-and-omp\|src-scripts"` 只剩 §3 那一处已知例外。
+5. **`dsh://docs` 可读性不变**：`read dsh://docs` 列表与抽查若干路径仍正常。
+6. 实测报告落 `docs/50_test-reports/`；发布仍需 user 明确放行。
+
+---
+
+## 5. 风险
+
+| 风险 | 说明 | 处置 |
+|---|---|---|
+| 误摘承重目录 | `80_upstream-docs-and-skills/` 名字像"纯上游资料"，实则含承重技能 | §1.3 硬契约 + 验收第 2/3 条把关 |
+| 规则误伤同名目录 | EXCLUDE 是正则，若将来别处出现同名目录会被一并摘 | 规则带路径前缀锚定（`dsh-dev-skill/…`），不做裸名匹配 |
+| 与 ast-engine-deomp 同批发布 | 两者都改打包面，回归时互相遮蔽 | 验收分开做：先各自量化，再合并实测一次 |
+
+---
+
+## 6. 进展日志
+
+- **2026-10-03 设计轮**：user 发现 Hermes 材料混入并质疑归属，要求"只要跟 DSH 不相关、跟我们这个插件不相关的，全部摘掉"。完成全树审计（见 §0.3），确认：`hermes-dev-skill` 是别家框架的**未消费抓取产物**（无 `SKILL.md`）；`pi-and-omp` 被技能正文零引用；`dsh-dev-skill/skill` + `src/` 承重不可摘。user 裁决**档位 F**（只摘未引用的外来物与构建机械）。实测数字：tarball 20.3 → **3.7 MB**；磁盘 98 → **15 MB**。
+- 附带澄清（user 提问驱动）：`api-skills.json` 既非技能亦非文档，是未完成流水线的输入；"包内 gzip"被否决——npm tarball 本就是 gzip，包内再压只影响安装后磁盘，且 `dsh://docs` 读纯文本，需为**零引用**文件新增解压读路径，方向错误。

package/node_modules/better-dsh/docs/specs/dsh/spec.md

@@ -0,0 +1,47 @@
+# dsh Specification
+
+## Purpose
+
+Let the model read the harness's own documentation and its effective configuration via `dsh://` URLs — runtime self-description, shipped with the package so it resolves in source, built, and installed layouts alike.
+
+## Requirements
+
+### Requirement: Documentation addressing
+The system SHALL let `dsh://docs` return the sorted recursive listing of readable harness docs as JSON, and `dsh://docs/<doc>` return that document's content. A missing docs tree returns `URL_DOCS_UNAVAILABLE`; a missing document, a path escaping the docs directory, or a non-file target returns `URL_DOC_NOT_FOUND`. Any other root resource returns `URL_UNKNOWN_RESOURCE`.
+
+#### Scenario: Browsing the doc listing
+- **WHEN** the model reads `dsh://docs`
+- **THEN** the system returns the JSON array of doc paths relative to the docs root
+
+#### Scenario: Reading a specific document
+- **WHEN** the model reads `dsh://docs/<doc>`
+- **THEN** the system returns that document's content
+
+#### Scenario: Path traversal is rejected
+- **WHEN** the model reads `dsh://docs/../secrets`
+- **THEN** the system returns the structured `URL_DOC_NOT_FOUND` error (path escapes the docs directory) and reads nothing
+
+### Requirement: Docs tree resolves in every layout
+The system SHALL locate the docs tree by a nearest-first walk-up from the module's own location (`docs-dir.ts`), and the package SHALL ship the docs (`prebuild` copies the repo `docs/` into the package; the `files` array includes it) so source-tree, bundled-lib, and installed-`node_modules` layouts all resolve the package's own docs first.
+
+#### Scenario: Installed package resolves its own docs
+- **WHEN** the plugin runs from `node_modules/<dashr>/lib/index.js`
+- **THEN** `dsh://docs` serves the docs shipped inside that package, not an ancestor directory's
+
+### Requirement: Effective config addressing
+The system SHALL let `dsh://config` return the current resolved settings as JSON keyed by namespace, and `dsh://config/<ns>` return one namespace. A missing settings service returns `URL_SETTINGS_UNAVAILABLE`; an unknown namespace returns `URL_UNKNOWN_SETTINGS_NAMESPACE`.
+
+#### Scenario: Reading the effective config
+- **WHEN** the model reads `dsh://config`
+- **THEN** the system returns the resolved (not documented-default) configuration, namespace by namespace
+
+#### Scenario: Reading one namespace
+- **WHEN** the model reads `dsh://config/<known namespace>`
+- **THEN** the system returns that namespace's resolved value as JSON
+
+### Requirement: Config never leaks secrets
+The system SHALL strip secrets from every config response: schema-declared `role('secret')` redaction plus a defensive key-name denylist matched against normalized key names (credential/env/API-key material), applied recursively.
+
+#### Scenario: Config hides keys
+- **WHEN** the model reads `dsh://config` or `dsh://config/<ns>` and a resolved field is an API key or other secret-named field
+- **THEN** the returned JSON does not contain the secret value