@mengyuly/dsh-ponytail 0.3.4 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to `@mengyuly/dsh-ponytail` are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## Unreleased
+
+## [0.4.1] - 2026-10-08
+
+### Changed
+
+- Synchronize bilingual README, settings tooltips, recommendations and skill
+  help with the actual Lite behavior and complete seven-rung ladder.
+- Refresh pinned download links, update instructions, non-model verification,
+  build-source guidance and verified compatibility notes.
+- Add relevant npm search keywords, homepage and issue links. No core rule
+  or mode behavior changes; `latest` remains the default release channel.
+
+## [0.4.0] - 2026-10-08
+
+### Added
+
+- Native Web settings card: default-mode selection, five optional-skill toggles,
+  atomic revision-fenced saves, panel-only reset, retained drafts on failure,
+  read-only guards, and Chinese/English help.
+- Optional native `/ponytail` mode picker; status/reset/help run through the
+  existing command boundary without requesting a model turn.
+- `/ponytail help` and detailed default-source status. DSH Settings persistence
+  is optional; legacy/headless deployments keep their config-file path.
+- Browser interaction tests and downstream build/source hash provenance.
+
+### Fixed
+
+- Normalize repository text line endings to LF so downstream SHA-256 build
+  provenance is reproducible across Windows and Linux checkouts.
+- Mark bundled DSH host-contract peers as optional for package resolution,
+  retaining their version contracts and required host services. Plain npm/pnpm
+  installs now resolve only the two runtime externals instead of following the
+  host's transitive unpublished `dsh-type-meta` peer. Add clean pnpm 11 default
+  installation and runtime-load regression coverage.
+- Restore the complete seven-rung ladder in every active prompt, mandatory
+  Lite alternatives, unnecessary-dependency and fewest-file guards, full-scope
+  acceptance without re-arguing, and upstream minimal-test limits. Full/Ultra
+  enforce the ladder; Lite leaves the scope choice to the user.
+- Downstream builds now compile the instruction fragment from source, avoiding
+  stale rules in the installed bundle.
+- Older DSH Web settings scopes now save through the host's atomic settings RPC,
+  preserving revision conflicts and surfacing write failures instead of calling
+  an unavailable `scope.mutate` method.
+- Restore explicit upstream rules in every active level: all-caller root-cause
+  checks, same-size algorithm edge cases, shortcut ceiling/upgrade annotations,
+  hardware calibration, requested explanations, and coding-only scope.
+- Debt scans now recognize block comments, keep source files under `lib`, and
+  exclude nested dependency/build output in both ripgrep and Git fallbacks.
+
+### Changed
+
+- Review prompt budgets around required semantics instead of enforcing the old
+  compressed sizes. Update bilingual measurements without claiming model savings.
+- Execute debt scan commands against controlled source/vendor/build fixtures;
+  verify exact installed/source prompt and skill parity in the pack smoke test.
+  These checks do not establish model compliance or performance.
 
 ## [0.3.4] - 2026-10-07
 

package/README.md

@@ -15,15 +15,15 @@
 
 - **最新版（latest）**：
   `https://github.com/MengYuil/dsh-ponytail/releases/latest/download/mengyuly-dsh-ponytail.tgz`
-- **固定版本 v0.3.4**（按 Tag 不可变）：
-  `https://github.com/MengYuil/dsh-ponytail/releases/download/v0.3.4/mengyuly-dsh-ponytail.tgz`
+- **固定版本 v0.4.1**（按 Tag 不可变）：
+  `https://github.com/MengYuil/dsh-ponytail/releases/download/v0.4.1/mengyuly-dsh-ponytail.tgz`
 
 说明：
 
 - **latest**：适合快速安装体验，会随最新 Release 更新；固定资产名
   `mengyuly-dsh-ponytail.tgz` 在每个 Release 中保持不变，因此该 URL
   不会因版本号变化而失效，**不适合作为不可变依赖**。
-- **固定版本**：适合可复现安装，URL 中固定 Tag（如 `v0.3.4`），按 Tag
+- **固定版本**：适合可复现安装，URL 中固定 Tag（如 `v0.4.1`），按 Tag
   不可变；资产名同样为 `mengyuly-dsh-ponytail.tgz`。
 - npm 安装仍走 npm Registry 或 `dsh plugin` 命令。
 - 固定资产名由 `scripts/release-assets.mjs` 生成并验证（`node scripts/release-assets.mjs`，仅仓库维护者）。
@@ -32,6 +32,9 @@
 
 装进某个 profile（`web` 可换成 `tui`/自定义名）：
 
+推荐从 npm 安装稳定版：`dsh plugin --profile web add @mengyuly/dsh-ponytail`。
+需要固定本版时使用 `dsh plugin --profile web add @mengyuly/dsh-ponytail@0.4.1`。
+
 ```bash
 # 方式一：本地链接（当前 dsh 核 ≥ 0.1.x）
 dsh plugin --profile web add link:$(pwd)
@@ -47,27 +50,41 @@ dsh plugin --profile web add file:./mengyuly-dsh-ponytail.tgz
 dsh plugin --profile web add @mengyuly/dsh-ponytail
 ```
 
-装完重启 profile 生效（`dsh web` / `dsh tui`）。装载完成后，会话技能目录里会出现 6 个 `ponytail*` 技能，发 `/ponytail-help` 立即验证。
+装完重启 profile 生效（例如 `dsh web`）。发 `/ponytail status` 查看实际模式与来源，
+或 `/ponytail help` 查看命令帮助；两者均不调用模型。默认注册 6 个 `ponytail*` 技能，
+关闭附加技能后目录相应减少。`/ponytail-help` 是会请求模型工作的技能，不是零调用的安装检查。
+
+### 更新已有安装
+
+```bash
+dsh plugin --profile web update @mengyuly/dsh-ponytail
+```
+
+更新后重启对应 profile。GitHub、链接或本地 tgz 安装请重新添加所需来源；
+不要把 npm 更新命令当成改变安装来源的保证。
 
 > `lib/index.js` 是自包含 bundle（已内联 `dsh-llm` / `dsh-skill`——npm 无兼容版本），运行时依赖两个已发布的 peer：`@deepseek-ai/cordis`（4.0.1）与 `@deepseek-ai/schemastery`（3.18.x）。`schemastery` 刻意保持外置而非内联：其 schema DSL 用 `new Function` 编译 `callback` 字符串，外置后**发行产物不含任何动态代码执行**（CI 有专门检查）。GitHub / tgz / npm 三种安装方式都不需要 dsh 源码树。
 
-> 说明：`src/` 是源码、`lib/` 是预构建产物（开箱即可加载，无需编译）。源码主仓在 deepseek-harness 的 `packages/community/ponytail`；改源码后用 `DSH_CHECKOUT=/path/to/deepseek-harness node scripts/sync-dist.mjs` 重建并同步完整 `lib/`（见下「发行维护」）。
+> 说明：当前下游源码以本仓库 `src/` 为准，`lib/` 是随包提供的预构建产物。
+> deepseek-harness 的 `packages/community/ponytail` 是历史内联依赖基线。
+> 下游构建使用 `node scripts/build-ui.mjs`；不要用 `sync:dist` 覆盖尚未同步到宿主的下游修改（详见「发行维护」）。
 
 ## 功能
 
 - **核心模式** `/ponytail` — 每轮注入结构化的懒惰开发者规则集，**三个档位是真实不同的 Prompt 片段**（不只是换一行）：
   - **Common（所有非 off 档共享）**：先把请求转成可观察的完成条件；沿真实调用流取证，但决策阶梯是快速反射、不是研究项目；按“检查 → 修改 → 最窄有效验证 → 检查最终 diff”闭环执行；非平凡逻辑只留一个最小可执行检查，不额外搭测试框架或 fixtures；只汇报已验证结果。
   - **Safety（任何档位都不可删）**：输入校验、防数据丢失的错误处理、安全措施、无障碍、明确验收项、先理解问题、「最小 diff ≠ 正确修复」。
-  - **`lite`**：直接执行、减少仪式；完整交付明确要求；可以一句话指出更简方案，但**不挑战明确需求**。
+  - **`lite`**：完整交付明确要求，**必须用一句话指出更简方案，由用户选择**；没有可行替代时如实说明，不编造方案，也不擅自改变需求范围。
   - **`full`（默认）**：完整七级阶梯（YAGNI → 复用 → 标准库 → 原生 → 已装依赖 → 一行 → 最小实现），默认选最短正确实现，修根因而非症状。
   - **`ultra`**：新增代码前先要证据，优先删除或复用；主动质疑投机性功能/缓存/抽象/配置/新依赖；复杂需求先给最小正确版并说明扩大条件；**不是无脑拒绝**。
   - `off`：完全不注入。
   - 档位**会话级**（会话 A 不影响会话 B，会话结束自动释放）。
-  - 裸 `/ponytail`：已启用时只报告；`off` 时恢复到有效默认档（默认也是 `off` 则回 `full`）。
+  - 裸 `/ponytail`：支持原生命令菜单的 Web 会打开模式选择器；其他宿主中，已启用时只报告，`off` 时恢复到有效默认档（默认也是 `off` 则回 `full`）。
   - `/ponytail status`：只查询、永不修改，并显示当前模式来自会话覆盖还是配置默认值。
   - `/ponytail reset`：清除当前会话覆盖，重新跟随有效配置默认值。
   - `/ponytail lite|full|ultra|off`：显式切换。
-  - `/ponytail default <mode>`：持久化默认值到**用户级配置文件**（env/Profile 仍优先，命令分别提示 saved 与 effective）。
+  - `/ponytail help`：直接显示操作帮助，不调用模型。
+  - `/ponytail default <mode>`：有 DSH Settings 时保存到宿主设置；没有时回退到用户级配置文件（env/Profile 仍优先，命令分别提示 saved 与 effective）。
   - 状态操作立即生效，但不唤醒空闲 Agent；模型通知在下一次真实请求时接收，避免切档位额外触发模型调用。
 - **一次性技能**（用哪个载哪个，不进常驻 prompt）：
   - `/ponytail-review` — 针对最近改动找过度工程；每条包含位置、替代方案和实际调用证据，不猜测精确收益。
@@ -78,7 +95,7 @@ dsh plugin --profile web add @mengyuly/dsh-ponytail
 - **停用**：说 `stop ponytail`、`normal mode`、`停止 ponytail`、`关闭 ponytail`、`普通模式` 或 `正常模式`（兼容中英文句末标点）；随时 `/ponytail` 恢复。
 - **默认值优先级**（代码/测试/文档一致）：
   ```
-  会话 override > PONYTAIL_DEFAULT_MODE > Profile config.defaultMode > 用户 config.json > full
+  会话 override > PONYTAIL_DEFAULT_MODE > Profile config.defaultMode > DSH Settings > 用户 config.json > full
   ```
   - **Profile 级配置**（Cordis 官方插件配置 API，各 profile 可不同）：
     ```yaml
@@ -94,6 +111,36 @@ dsh plugin --profile web add @mengyuly/dsh-ponytail
 - **子代理（如实边界）**：DSH 内置 `subagent` 工具是**隔离派生**，但全局 system-prompt section 默认也会参与子代理的独立组装；这不是父代理 Prompt 或会话状态继承。`PONYTAIL_SUBAGENT_MATCHER`（匹配子代理 `agentPreset` 的正则）只用于筛选能进入本 Prompt 管线的子代理，不是继承开关；无 preset 时不会被 matcher 排除。DSH 当前没有公开的父子 Prompt 继承 API，因此**不宣称父子 Prompt 继承**（有官方 API 后再考虑只读模式快照传播）。非法正则告警一次并 fail-open。
 - **配置错误**：非法 JSON / 非法 `defaultMode` / 读取失败 / 非法正则只告警一次（不刷屏）；配置文件不存在属正常、不告警。
 
+## 图形操作
+
+支持原生 `settingsScope`/`settings.plugin.item` 接口的 DSH Web 中，打开
+**设置 → 插件 → Ponytail**：选择默认模式、分别开关五个附加技能、保存设置，
+或一键恢复面板默认。选择「跟随现有配置」会沿用旧配置，不替用户覆盖环境变量或 Profile。
+面板默认值不是当前会话模式；已有会话覆盖不变，实际模式与来源用 `/ponytail status` 查询。
+附加技能开关不会移除常驻核心规则，只有 `off` 模式关闭规则注入。
+
+原生命令菜单支持时，裸 `/ponytail` 打开模式选择器，并提供状态、会话重置和帮助入口。
+有参数的命令、TUI/CLI 用法保持原样。没有这些界面服务的旧宿主保留命令与文件配置路径。
+保存失败不显示成功，面板保留修改；只读连接禁用写入。面板重置仅清除自身设置，
+不删除旧配置、不清除已有会话覆盖，也不请求模型工作。
+
+已在 WSL Debian 的真实 DSH checkout `b150a551` 上用隔离 profile 联调界面与文件设置。
+旧版仅有 `set/unset` 的 Settings scope 通过宿主原子 RPC 保存，仍保留版本冲突检查。
+DSH 宿主契约 peer 保留版本声明，但标记为包管理器可选，由实际宿主提供；
+`cordis` 与 `schemastery` 仍是必需的运行时 peer。正常安装不需要关闭自动 peer 安装，
+也不会为了安装本插件拉取整套 DSH 和尚未发布的 `dsh-type-meta`。
+「可选」仅指依赖解析：实际运行仍需要 DSH 的 systemPrompt、skills 等宿主服务，不能脱离 DSH 独立运行。
+
+开发者界面验证（工具安装在仓库外，不进入 npm 包）：
+```powershell
+$env:PONYTAIL_TOOL_ROOT = Join-Path $env:TEMP 'ponytail-ui-tools'
+npm install --prefix $env:PONYTAIL_TOOL_ROOT --ignore-scripts typescript@6.0.3 esbuild@0.28.2 react@18.3.1 react-dom@18.3.1 jsdom@26.1.0
+node scripts/build-ui.mjs
+node scripts/test-ui.mjs
+```
+`build-ui` 保留已有内联宿主依赖，编译下游规则片段、插件入口和浏览器界面，**不是权威 monorepo 完整重建**。
+`dist-provenance.json` 中旧 `sourceCommit` 表示基线，`downstreamBuild` 记录当前修改的源码和产物 SHA-256。
+
 ## 效率（条件性收益，非保证）
 
 Ponytail 会给每次模型请求增加一小段固定规则。它的收益是**有条件的**：
@@ -107,14 +154,25 @@ prompt 与推理开销变得更贵。
 
 | 档位 | 字符数 | UTF-8 字节 | 说明 |
 |------|--------|-----------|------|
-| lite | 1915 | 1917 | 实测生成 |
-| full | 3022 | 3038 | 实测生成 |
-| ultra | 2797 | 2813 | 实测生成 |
+| lite | 3911 | 3913 | 实测生成 |
+| full | 4818 | 4834 | 实测生成 |
+| ultra | 5034 | 5050 | 实测生成 |
 | off | 0 | 0 | 不注入 |
 
 这些是 **Prompt 体积测量，不是账单金额，也不是对所有模型成立的节省
 比例**（无统一 tokenizer，`measure:prompt` 输出中 `estimated_tokens` 为
-null；字符数/4 只是粗略估算）。同模式字节级稳定，KV-cache 前缀命中。
+null；字符数/4 只是粗略估算）。同模式字节级稳定，有利于 Prompt 缓存，但不保证宿主或模型缓存命中。
+
+所有启用档位均保留上游边界：修复前检查所有调用方、同等大小方案优先边界正确性、
+有已知局限的捷径留下 `ponytail: <ceiling>, <upgrade path>` 注释、保留硬件校准，
+以及完整回答用户明确要求的解释。规则仅用于编码任务，不改写一般问答或翻译。
+所有启用档位包含完整七阶梯。Lite 必须用一句话指出更简单的替代方案，但由用户选定范围；
+Full 执行阶梯；Ultra 执行阶梯并更积极质疑不必要的复杂度。几行代码足够时不得新增依赖，
+在正确完整的前提下触及最少文件；用户坚持完整版本后直接实现，不反复争辩。
+非平凡逻辑保留一个最小可运行检查，不擅自增加逐函数测试套件；简单一行代码不要求额外测试。
+`ponytail-debt` 支持块注释和 `lib` 源码，两条扫描路径均跳过嵌套依赖与构建目录。
+验证覆盖规则内容、真实搜索命令及安装产物与源码的 Prompt/Skill 一致性；
+这些检查不代表模型遵循率或实际性能已经通过对照评测。
 
 **上游数据不是本 DSH 适配版的保证**：上游 Ponytail 的 single-shot
 （代码 −80~94%、成本 −42~75%、延迟 3.1–5.8×）与 agentic（LOC −54% 等）
@@ -126,17 +184,17 @@ Smoke Benchmark 只提供方向性证据（见 `docs/dsh-smoke-summary.md`）。
 - 档位差异在**规则语义**上（见上），三者 Prompt 体积相近（实测见上表）。
 - 上游 Claude 专属的 statusline 徽标无 DSH 对应物，MCP 服务器因 DSH 有一等 system-prompt 注入点而弃用。
 - 用户 `config.json` 热更新；`PONYTAIL_DEFAULT_MODE` 与 Profile config 需重启生效。
-- 发行 `lib/` 是预编译产物；改源码请回主仓重建后同步。
+- 发行 `lib/` 是预编译产物；下游修改在本仓库构建，并核对安装包与源码的一致性。
 
 ## 兼容矩阵（实测，不虚构）
 
 | 组件 | 已验证环境 | 备注 |
 |---|---|---|
 | Node.js | 22.x / 24.x | CI 矩阵 4 组合全绿 |
-| OS | ubuntu-latest / windows-latest | CI 矩阵 |
+| OS | ubuntu-24.04 / windows-latest | CI 矩阵 |
 | DSH | commit `b150a551`（构建所用 checkout） | 与正式发布版本的精确对应关系**待确认** |
 | Cordis | 4.0.1（构建所用 vendor） | 同上 |
-| web profile | 已验证 | 本机真实 profile 长期运行 + 三路径隔离安装实测（npm / GitHub / tgz） |
+| web profile | 已验证 | WSL Debian 隔离真实 DSH：加载、保存/重启持久化、优先级、技能开关及命令；npm/pnpm 安装验证 |
 | tui profile | 未验证 | 未在 tui profile 中启动测试 |
 | headless profile | 未验证 | 未完整启动；插件单元测试运行于无 UI 环境 |
 | npm tarball | 已验证 | 内容/版本/安装后 smoke/NodeNext consumer |
@@ -146,8 +204,8 @@ Smoke Benchmark 只提供方向性证据（见 `docs/dsh-smoke-summary.md`）。
 
 ## 测试环境与权威关系
 
-- 本机（Linux，Node.js **v24.16.0**，deepseek-harness checkout 构建）与 CI 矩阵（**ubuntu-latest + windows-latest × Node 22/24**）上验证通过。与之精确匹配的已发布 DSH/Cordis 版本**待确认**——checkout 是预发布工作树，非发布 tag。
-- 权威源码在 deepseek-harness monorepo 的 `packages/community/ponytail`（`@deepseek-ai/dsh-ponytail`）；本仓库（`@mengyuly/dsh-ponytail`）是**发行镜像**：随包附构建产物，不是独立真源。
+- 本机 WSL Debian（Node.js **v24.16.0**，DSH checkout CLI 标识 **0.1.1-rc.2**）、Windows Node 24 与 CI（**ubuntu-24.04 + windows-latest × Node 22/24**）上验证。真实宿主 checkout 为 `b150a551`，不是正式发布 tag；不能据此声称所有 DSH 发布版本都兼容。
+- 历史宿主构建基线来自 deepseek-harness monorepo 的 `packages/community/ponytail`；当前 `@mengyuly/dsh-ponytail` 的下游适配修改以本仓库 `src/` 为准，随包附构建产物。
 
 ## 发行维护
 
@@ -157,7 +215,7 @@ Smoke Benchmark 只提供方向性证据（见 `docs/dsh-smoke-summary.md`）。
 > `scripts/` 命令（无维护脚本入口、无安装生命周期钩子），由
 > `node scripts/verify-pack.mjs` 回归检查强制。
 
-- **权威源码**：deepseek-harness monorepo 的 `packages/community/ponytail`（本仓库是发行镜像，只随包发布构建产物）。
+- **构建来源**：monorepo 提供历史内联依赖基线；当前下游适配源码在本仓库。`build-ui` 与完整 `sync:dist` 的证据范围不同，不能混称。
 - **维护者命令**（源码仓库内直接运行 `node scripts/<script>.mjs`；快捷清单见
   `package.dev.json`）：
   ```bash
@@ -167,6 +225,7 @@ Smoke Benchmark 只提供方向性证据（见 `docs/dsh-smoke-summary.md`）。
   node scripts/test-consumer.mjs       # NodeNext + skipLibCheck:false 声明消费测试（对打包产物）
   node scripts/test-regressions.mjs    # 验证工具自身的回归测试
   node scripts/test-core.mjs           # 核心 Prompt 字节、安全边界、模式与 Skill 表面
+  node scripts/test-install.mjs        # pnpm 11 默认 peer 安装，无宿主源码树或规避配置
   node scripts/measure-prompt.mjs      # 各模式 Prompt 段体积（依赖未发布的 src/）
   node scripts/check-release-links.mjs # README/CHANGELOG/docs 无版本化 latest 资产链接
   node scripts/check-release-consistency.mjs --version <v>  # 四方发布一致性（git tag/npm/GitHub/provenance）
@@ -175,8 +234,10 @@ Smoke Benchmark 只提供方向性证据（见 `docs/dsh-smoke-summary.md`）。
   ```bash
   DSH_CHECKOUT=/path/to/deepseek-harness node scripts/sync-dist.mjs
   ```
-  该命令在权威 checkout 中重建（`tsc` 生成声明 + `tsdown` 打包运行时），同步 `lib/index.js`、`lib/invariant.js`、`lib/types/*.d.ts`，生成 `dist-provenance.json`（记录权威 checkout 的真实 commit SHA 与工具链版本），并自动执行一致性校验；产物有变化时会提示提交。**完整构建一致性由本命令在发布流程中完成——发行镜像 CI 不会重新构建权威 monorepo。**
-- **CI 能力边界（如实）**：CI（ubuntu + windows 矩阵）执行上述静态验证与打包/消费测试，但**不重新构建权威 monorepo**；`verify:dist` 是导出表面/签名/运行时导出的一致性检查，**不是**与权威构建的字节级等价证明——后者由 `sync:dist` 在发布流程中保证。
+  该命令重建宿主 checkout 的基线，并覆盖本仓库的源码、JS、声明和 provenance。
+  **仅在下游修改已经同步到该 checkout、且确认需要完整重建时使用**；不应作为日常下游构建命令。
+- **CI 能力边界（如实）**：CI 执行静态验证、源码/下游产物哈希及打包/消费测试，
+  **不重新构建宿主 monorepo**。这些检查不证明当前下游产物等同于宿主基线的全量重新构建，也不证明模型服从率或效率收益。
 - `dist-provenance.json` 随 npm 包发布，便于审计构建来源。
 - 本机验证时若 `npm_execpath` 指向其他包管理器（如 pnpm/yarn shim），脚本会自动回退到 PATH 上的 `npm`；临时目录失败时保留需设 `PONYTAIL_VERIFY_KEEP_TEMP=1`。
 - **安全**：`scripts/**` 仅用于开发/构建/发行验证，**不进入 npm tarball**、无安装生命周期钩子、运行时入口不引用、发布包 `package.json` 不暴露这些维护命令；`child_process` 告警属于可接受的开发工具风险。详见 [SECURITY.md](SECURITY.md)。

package/README_EN.md

@@ -23,8 +23,8 @@ not guarantees)”).
 
 - **Latest release**:
   `https://github.com/MengYuil/dsh-ponytail/releases/latest/download/mengyuly-dsh-ponytail.tgz`
-- **Pinned version v0.3.4** (immutable per tag):
-  `https://github.com/MengYuil/dsh-ponytail/releases/download/v0.3.4/mengyuly-dsh-ponytail.tgz`
+- **Pinned version v0.4.1** (immutable per tag):
+  `https://github.com/MengYuil/dsh-ponytail/releases/download/v0.4.1/mengyuly-dsh-ponytail.tgz`
 
 Notes:
 
@@ -33,7 +33,7 @@ Notes:
   the URL never breaks on a version bump — which also means it is **not
   suitable as an immutable dependency**.
 - **Pinned version**: good for reproducible installs; the URL pins a tag
-  (e.g. `v0.3.4`) that is immutable per tag; the asset name is likewise
+  (e.g. `v0.4.1`) that is immutable per tag; the asset name is likewise
   `mengyuly-dsh-ponytail.tgz`.
 - npm installs still go through the npm Registry or the `dsh plugin` command.
 - The fixed asset name is produced and verified by
@@ -44,6 +44,9 @@ Notes:
 
 Install into a profile (replace `web` with `tui` or a custom name):
 
+Recommended stable npm install: `dsh plugin --profile web add @mengyuly/dsh-ponytail`.
+To pin this release: `dsh plugin --profile web add @mengyuly/dsh-ponytail@0.4.1`.
+
 ```bash
 # Option 1: local link (current dsh cores >= 0.1.x)
 dsh plugin --profile web add link:$(pwd)
@@ -60,9 +63,21 @@ dsh plugin --profile web add file:./mengyuly-dsh-ponytail.tgz
 dsh plugin --profile web add @mengyuly/dsh-ponytail
 ```
 
-Restart the profile after installing (`dsh web` / `dsh tui`) for it to take
-effect. Once loaded, the session skill catalog shows 6 `ponytail*` skills; send
-`/ponytail-help` to verify immediately.
+Restart the profile after installing (for example, `dsh web`). Use
+`/ponytail status` for the effective mode/source or `/ponytail help` for command
+help; neither calls the model. Six `ponytail*` skills are registered by default,
+with disabled optional skills removed from the catalog. `/ponytail-help` is a
+model-backed skill, not a zero-call installation check.
+
+### Updating an existing installation
+
+```bash
+dsh plugin --profile web update @mengyuly/dsh-ponytail
+```
+
+Restart the corresponding profile afterward. For GitHub, linked or local-tgz
+installs, re-add the desired source; the npm update command is not a guarantee
+that the installation source changes.
 
 > `lib/index.js` is a self-contained bundle (`dsh-llm` / `dsh-skill` are
 > already inlined — npm has no compatible versions) with two published
@@ -73,12 +88,10 @@ effect. Once loaded, the session skill catalog shows 6 `ponytail*` skills; send
 > no dynamic code execution** (CI has a dedicated check). None of the three
 > install paths — GitHub, tgz, npm — needs a dsh source tree.
 
-> Note: `src/` is the source, `lib/` is the prebuilt artifact (loadable
-> out of the box, no build step). The authoritative source lives in the
-> deepseek-harness monorepo at `packages/community/ponytail`; after changing
-> source, rebuild and sync the full `lib/` with
-> `DSH_CHECKOUT=/path/to/deepseek-harness node scripts/sync-dist.mjs`
-> (see “Release maintenance” below).
+> This repository's `src/` owns current downstream source; `lib/` ships prebuilt.
+> The monorepo's `packages/community/ponytail` is the historical inlined baseline.
+> Use `node scripts/build-ui.mjs` for downstream builds; do not overwrite local
+> downstream changes with `sync:dist` before they exist in the host checkout.
 
 ## Features
 
@@ -97,8 +110,9 @@ effect. Once loaded, the session skill catalog shows 6 `ponytail*` skills; send
     explicit acceptance criteria, understanding the problem first, and
     “minimal diff ≠ correct fix”.
   - **`lite`**: execute directly, less ceremony; still complete explicit
-    deliverables; you may point out a simpler approach in one sentence, but
-    **do not challenge explicit requirements**.
+    deliverables; **must name a simpler alternative in one line, leaving the
+    choice to the user**. If none works, say so; do not invent an alternative
+    or silently change the requested scope.
   - **`full`** (default): the full seven-rung ladder (YAGNI → reuse → stdlib
     → native → installed dependencies → one line → minimal implementation);
     pick the shortest correct implementation by default; fix root causes, not
@@ -111,16 +125,17 @@ effect. Once loaded, the session skill catalog shows 6 `ponytail*` skills; send
   - `off`: no injection at all.
   - Levels are **session-scoped** (session A does not affect session B;
     released automatically when the session ends).
-  - Bare `/ponytail`: when enabled it only reports; when `off` it restores the
-    effective default level (falling back to `full` if that default is also
-    `off`).
+  - Bare `/ponytail`: opens a picker in Web hosts with native command-menu
+    support. Elsewhere it reports when enabled; from `off` it restores the
+    effective default (falling back to `full` if that default is also `off`).
   - `/ponytail status`: query only, never modifies, and shows whether the
     current mode comes from a session override or the configured default.
   - `/ponytail reset`: clears the current session override and follows the
     effective configured default again.
   - `/ponytail lite|full|ultra|off`: explicit switch.
-  - `/ponytail default <mode>`: persists the default to the **user-level
-    config file** (env/profile still take priority; the command reports both
+  - `/ponytail help`: displays command help without calling the model.
+  - `/ponytail default <mode>`: persists through DSH Settings when available,
+    otherwise the user-level config file (env/profile still take priority; the command reports both
     `saved` and `effective`).
   - Status changes take effect immediately without waking an idle agent.
     Notices reach the model on its next real step, avoiding an extra model
@@ -142,7 +157,7 @@ effect. Once loaded, the session skill catalog shows 6 `ponytail*` skills; send
   punctuation tolerated); `/ponytail` re-enables at any time.
 - **Default priority** (consistent across code/tests/docs):
   ```
-  session override > PONYTAIL_DEFAULT_MODE > Profile config.defaultMode > user config.json > full
+  session override > PONYTAIL_DEFAULT_MODE > Profile config.defaultMode > DSH Settings > user config.json > full
   ```
   - **Profile-level config** (official Cordis plugin config API; each profile
     can differ):
@@ -176,6 +191,43 @@ effect. Once loaded, the session skill catalog shows 6 `ponytail*` skills; send
   invalid regex warn exactly once (no log spam); a missing config file is
   normal and never warns.
 
+## Graphical controls
+
+On DSH Web hosts with the native `settingsScope`/`settings.plugin.item` APIs,
+open **Settings → Plugins → Ponytail** to select a default mode, toggle five
+optional skills, save, or reset panel defaults. “Follow existing configuration”
+preserves legacy configuration. Environment/profile values still take priority;
+existing session overrides stay intact. Use `/ponytail status` for the actual
+session mode and source. Optional-skill toggles never remove the core rules.
+
+When supported, bare `/ponytail` opens a native picker with mode/status/reset/help
+actions. Argued commands and TUI/CLI behavior remain unchanged. Older hosts
+without these services keep the command/config-file paths. Failed saves retain
+drafts; read-only connections cannot write. Panel reset clears only its own
+overrides, not legacy files or session state, and requests no model work.
+
+The native UI and file-backed settings were integration-tested in an isolated
+profile on the real WSL Debian DSH checkout `b150a551`. Older Settings scopes
+with only `set/unset` save through the host's atomic RPC with revision checks.
+DSH contract peers retain their version ranges but are optional for package
+resolution and supplied by the host. Cordis and schemastery remain required
+runtime peers. Normal installation needs no auto-peer workaround and does not
+fetch a second DSH or the unpublished `dsh-type-meta` peer. Optional metadata
+does not make host services optional: runtime still requires DSH systemPrompt,
+skills, and the other services used by the plugin.
+
+Developer UI checks use isolated tools, excluded from the npm tarball:
+```powershell
+$env:PONYTAIL_TOOL_ROOT = Join-Path $env:TEMP 'ponytail-ui-tools'
+npm install --prefix $env:PONYTAIL_TOOL_ROOT --ignore-scripts typescript@6.0.3 esbuild@0.28.2 react@18.3.1 react-dom@18.3.1 jsdom@26.1.0
+node scripts/build-ui.mjs
+node scripts/test-ui.mjs
+```
+`build-ui` retains baseline inlined host dependencies and compiles downstream
+rule fragments and entry/UI code; it is **not an authoritative monorepo rebuild**. Provenance's
+`sourceCommit` identifies the baseline; `downstreamBuild` records current source
+and artifact hashes.
+
 ## Efficiency (conditional gains, not guarantees)
 
 Ponytail adds a small fixed ruleset to every model request. Its benefit is
@@ -192,15 +244,33 @@ scripts/measure-prompt.mjs`, generated from the real
 
 | Level | Characters | UTF-8 bytes | Notes |
 |------|--------|-----------|------|
-| lite | 1915 | 1917 | measured output |
-| full | 3022 | 3038 | measured output |
-| ultra | 2797 | 2813 | measured output |
+| lite | 3911 | 3913 | measured output |
+| full | 4818 | 4834 | measured output |
+| ultra | 5034 | 5050 | measured output |
 | off | 0 | 0 | not injected |
 
 These are **prompt-size measurements, not billing amounts, and not a savings
 ratio that holds for every model** (there is no universal tokenizer;
 `estimated_tokens` in `measure:prompt` output is null; characters/4 is only a
-rough estimate). Same-mode output is byte-stable, so KV-cache prefixes hit.
+rough estimate). Same-mode output is byte-stable, which helps prompt caching,
+but does not guarantee a host or model cache hit.
+
+Every active level preserves upstream boundaries: check all callers before a
+bug fix, prefer edge-case correctness between same-size options, annotate real
+shortcuts with `ponytail: <ceiling>, <upgrade path>`, retain hardware calibration,
+and give explicitly requested explanations in full. Rules apply to coding only,
+not unrelated prose or translation. Debt scans support block comments and `lib`
+sources; both scan paths exclude nested dependency and build directories.
+Checks cover prompt contracts, actual scan commands, and exact installed/source
+prompt and skill parity, not model compliance rates or measured performance.
+
+Every active prompt contains the complete seven-rung ladder. Lite must name a
+simpler alternative in one line while leaving scope to the user; Full enforces
+the ladder; Ultra enforces it and challenges unnecessary complexity more actively.
+Do not add dependencies for work a few lines can do; touch the fewest files that
+deliver a correct complete fix. If the user insists on full scope, build it
+without re-arguing. Non-trivial logic keeps one minimal runnable check, not an
+unrequested per-function suite; trivial one-liners need no extra test.
 
 **Upstream numbers are not a guarantee for this DSH port**: the upstream
 Ponytail single-shot results (code −80–94%, cost −42–75%, latency 3.1–5.8×)
@@ -218,18 +288,18 @@ benchmark provides directional evidence only (see
   point.
 - User `config.json` hot-reloads; `PONYTAIL_DEFAULT_MODE` and profile config
   need a restart.
-- The shipped `lib/` is a prebuilt artifact; to change behavior, rebuild in
-  the main repo and re-sync.
+- The shipped `lib/` is prebuilt; build downstream changes in this repository
+  and verify installed/source parity.
 
 ## Compatibility matrix (measured, not fabricated)
 
 | Component | Verified environment | Notes |
 |---|---|---|
 | Node.js | 22.x / 24.x | CI matrix, 4 combinations green |
-| OS | ubuntu-latest / windows-latest | CI matrix |
+| OS | ubuntu-24.04 / windows-latest | CI matrix |
 | DSH | commit `b150a551` (build checkout) | exact mapping to an official release **TBD** |
 | Cordis | 4.0.1 (build vendor) | same |
-| web profile | verified | long-running on a real local profile + three isolated install-path tests (npm / GitHub / tgz) |
+| web profile | verified | isolated real WSL DSH: loading, save/restart persistence, priorities, skill switches and commands; npm/pnpm install checks |
 | tui profile | not verified | not started inside a tui profile |
 | headless profile | not verified | not fully started; plugin unit tests run in a UI-less environment |
 | npm tarball | verified | contents/version/post-install smoke/NodeNext consumer |
@@ -241,15 +311,13 @@ benchmark provides directional evidence only (see
 
 ## Test environments and source of truth
 
-- Verified locally (Linux, Node.js **v24.16.0**, deepseek-harness checkout
-  build) and in the CI matrix (**ubuntu-latest + windows-latest × Node
-  22/24**). The exact published DSH/Cordis release they correspond to is
-  **TBD** — the checkout is a prerelease working tree, not a release tag.
-- The authoritative source is `packages/community/ponytail`
-  (`@deepseek-ai/dsh-ponytail`) in the deepseek-harness monorepo; this
-  repository (`@mengyuly/dsh-ponytail`) is a **distribution mirror**: it
-  ships build artifacts with the package and is not an independent source of
-  truth.
+- Verified with WSL Debian Node **v24.16.0**, checkout CLI **0.1.1-rc.2**,
+  Windows Node 24 and CI (**ubuntu-24.04 + windows-latest × Node 22/24**).
+  Host checkout `b150a551` is not an official release tag; this does not
+  establish compatibility with every published DSH version.
+- The historical host build baseline is `packages/community/ponytail` in the
+  deepseek-harness monorepo. Current `@mengyuly/dsh-ponytail` downstream changes
+  are maintained in this repository's `src/`, alongside shipped artifacts.
 
 ## Release maintenance
 
@@ -261,9 +329,9 @@ benchmark provides directional evidence only (see
 > commands (no maintenance entry points, no install lifecycle hooks),
 > enforced by a regression check in `node scripts/verify-pack.mjs`.
 
-- **Authoritative source**: `packages/community/ponytail` in the
-  deepseek-harness monorepo (this repository is a distribution mirror that
-  publishes build artifacts only).
+- **Build sources**: the monorepo supplies the historical inlined dependency
+  baseline; this repository owns current downstream source. `build-ui` and a
+  full `sync:dist` provide different evidence and must not be conflated.
 - **Maintainer commands** (run `node scripts/<script>.mjs` inside the source
   repository; see `package.dev.json` for the shortcut list):
   ```bash
@@ -273,6 +341,7 @@ benchmark provides directional evidence only (see
   node scripts/test-consumer.mjs       # NodeNext + skipLibCheck:false declaration consumer test (against the packed artifact)
   node scripts/test-regressions.mjs    # regression tests for the verification tooling itself
   node scripts/test-core.mjs           # core prompt bytes, safety boundaries, modes and skill surface
+  node scripts/test-install.mjs        # pnpm 11 default peer installation, no host tree/workaround
   node scripts/measure-prompt.mjs      # prompt-section size per mode (depends on the unpublished src/)
   node scripts/check-release-links.mjs # README/CHANGELOG/docs contain no versioned latest asset links
   node scripts/check-release-consistency.mjs --version <v>  # four-way release consistency (git tag/npm/GitHub/provenance)
@@ -282,20 +351,14 @@ benchmark provides directional evidence only (see
   ```bash
   DSH_CHECKOUT=/path/to/deepseek-harness node scripts/sync-dist.mjs
   ```
-  This rebuilds inside the authoritative checkout (`tsc` for declarations +
-  `tsdown` for the runtime bundle), syncs `lib/index.js`, `lib/invariant.js`,
-  `lib/types/*.d.ts`, generates `dist-provenance.json` (recording the
-  authoritative checkout's real commit SHA and toolchain versions), and runs
-  the consistency checks automatically; it prompts you to commit when
-  artifacts changed. **Full build consistency is produced by this command in
-  the release process — the mirror repository's CI never rebuilds the
-  authoritative monorepo.**
-- **CI capability boundary (honest)**: CI (ubuntu + windows matrix) runs the
-  static verification and pack/consumer tests above, but **does not rebuild
-  the authoritative monorepo**; `verify:dist` is an export-surface/signature/
-  runtime-export consistency check, **not** a byte-level equivalence proof
-  against the authoritative build — that is guaranteed by `sync:dist` in the
-  release process.
+  This rebuilds the host checkout baseline and overwrites this repository's
+  source, JS, declarations and provenance. **Use only after downstream changes
+  exist in that checkout and a full rebuild is intended**, not as the routine
+  downstream build command.
+- **CI capability boundary (honest)**: CI runs static checks, downstream
+  source/artifact hashes and pack/consumer tests; it **does not rebuild the
+  host monorepo**. These checks establish neither full-rebuild equivalence
+  with the host baseline nor model compliance or efficiency gains.
 - `dist-provenance.json` ships with the npm package for build-source audits.
 - When verifying locally, if `npm_execpath` points at another package manager
   (e.g. a pnpm/yarn shim), the scripts fall back to `npm` on PATH; set

package/dist-provenance.json

@@ -1,11 +1,26 @@
-{
-  "sourceRepository": "https://github.com/deepseek-ai/deepseek-harness.git",
-  "sourceCommit": "b150a551b8d465e31e418e1b2eaf5e79bbb7d28e",
-  "sourcePackage": "packages/community/ponytail",
-  "generatedBy": {
-    "node": "v24.16.0",
-    "typescript": "6.0.3",
-    "tsdown": "0.22.2",
-    "cordis": "4.0.1"
-  }
-}
+{
+  "sourceRepository": "https://github.com/deepseek-ai/deepseek-harness.git",
+  "sourceCommit": "b150a551b8d465e31e418e1b2eaf5e79bbb7d28e",
+  "sourcePackage": "packages/community/ponytail",
+  "generatedBy": {
+    "node": "v24.16.0",
+    "typescript": "6.0.3",
+    "tsdown": "0.22.2",
+    "cordis": "4.0.1"
+  },
+  "downstreamBuild": {
+    "method": "scripts/build-ui.mjs; retains baseline inlined host dependencies",
+    "node": "v24.15.0",
+    "typescript": "6.0.3",
+    "esbuild": "0.28.2",
+    "sha256": {
+      "src/index.ts": "8421733adf8c801c1578b070cf789b5bd77588acbe90403dd69ee5467375c955",
+      "src/client.ts": "faca913a8b0348e89f67853a1e07bd4eefa0236b491f957c71fea3a914c51271",
+      "src/content.ts": "e9f6de036af5233a5ca6ab258be5ba821f8e072065fa43b0c700d2fac42a3095",
+      "src/instructions.ts": "d96deb078f6f633fffb0e3da2750eb9d3afb37bce4cea11145db045c8cceb935",
+      "src/modes.ts": "74b8b885d145759ce17007a054ab6adc295f726f47518f56a3d37de67bd14231",
+      "lib/index.js": "b65a606716bc0e1ab0f8d26262eebd07cefe130373e90fae8324b7101ca9b581",
+      "lib/client.js": "3a57ec216b96944b404d42fc303e3b7681e9c7b0a909bb25cda98820038aba9c"
+    }
+  }
+}