super-dsh 0.3.0-c → 0.3.0-e

package/node_modules/better-dsh/docs/50_test-reports/v0.2.4-ios-focus-zoom-suppression/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -1,158 +0,0 @@
-# v0.2.4 iOS Focus 放大抑制（zoomGuard）实测报告
-
-- **Change**: `openspec/changes/2026-09-03-ios-focus-zoom-suppression`
-- **版本**: better-dsh 0.2.2-a → **0.2.4**（canonical `dashr/package.json`；npm 已发布线 v0.2.3 顺延一档）
-- **日期**: 2026-09-03
-- **范围**: 纯 host 半（boot script 增量 + config 面 + payload 扩键）；client 半零改动，无需 build-client
-- **状态**: 单测/构建层自测完成；4999 实例验证（2.3）与真机观察（3.x）待做
-- **状态**: 4999 实例验证（2.3）✅ 完成（含一轮 blocker 返修 commit `59870fc`）；真机观察（3.x）待 user
----
-
-## 一、实测范围与结果表
-
-| # | 项目 | 层面 | 结果 | 证据 |
-|---|------|------|------|------|
-| 1 | vitest 全量（canonical） | 单测 | ✅ **460/460**（基线 428 + 新增 32；36 files） | `cd dashr && npm test` |
-| 2 | tsc --noEmit（含新 spec） | 类型 | ✅ 0 错 | `npx tsc --noEmit` |
-| 3 | schema：默认值 / off 透传 / font·bogus fail-loud | 单测 | ✅ | `test/zoom-guard.spec.ts` 'config schema' |
-| 4 | 纯函数矩阵（UA × 视口 × config；幂等；还原；bare token；大小写） | 单测 | ✅ 32 tests | 同上 |
-| 5 | 生成脚本形状（ES5、无 `</script`、断点派生 `(max-width:767.98px)`、payload 序列化） | 单测 | ✅ | 同上 'generated zoomGuard section' |
-| 6 | **boot script 评估端到端**（stub DOM 执行真实脚本文本） | 单测 | ✅ 全矩阵 | 同上 'boot script evaluation'（12 场景） |
-| 7 | 构建产物复核（lib/index.js 抽取嵌入函数源重组段 eval） | 构建 | ✅ ES5-ok + provisional/reconcile/还原/风暴全绿 | `.scratch/zg-built-check.ts` |
-| 8 | monorepo 副本 rsync + tsdown（host 半） | 构建 | ✅ 9 files 528.31 kB | `pnpm --filter better-dsh exec tsdown` |
-| 9 | dump-config 覆盖层渲染 `mobile.zoomGuard` | 集成 | ✅ `'off'` 逐字渲染于 dashr-repl 行 | `--patch .scratch/zg-overlay.yml` |
-| 10 | 4999 实例（boot script 注入形状 + CDP 视口矩阵 + off 逃生门 + 桌面 user 复验） | 集成 | ✅ **9/9 矩阵 + 4 冒烟 + off PASS + 桌面 PASS**（经一轮 blocker 返修，见八） | §八；脚本 `.scratch/zg-verify/` |
-| 11 | 真机 iOS PWA 观察（放大抑制/键盘自愈/回弹） | 真机 | ⏳ **待做**（user） | tasks 3.1–3.3 |
-
-## 二、实现要点（含 design.md 偏差说明）
-
-1. **纯函数 = 发布源**：`src/mobile/zoom-guard.ts` 的 `isIOSClassUA` / `mergeViewportTokens` / `shouldApplyZoomGuard` 以 ES5 自包含风格编写，boot script 经 `Function.prototype.toString()` 嵌入这三个函数 —— 单测覆盖的源码与页面执行的源码字节一致（构建后产物已复核该嵌入幸存于 tsdown bundle）。
-2. **schema enum 形式**：本 fork schemastery 无 `choice()`；采用 `z.union(['meta','off']).default('meta')`（字面量 union 即 enum，非法值 config load 即抛）。**'font' 预留值位不进 enum**（决策：未实现值若被 schema 接受则运行期静默 no-op，fail-loud 优于静默；预留以注释标注）。
-3. **⚠ 与 design D4 的重要发现级偏差（已按 D4 精神实现）**：webserver 的 head 注入 splice 点在 `<head>` 开标签**紧后**（`packages/host/webserver/src/injections.ts` `renderIndexInjections`），即 boot script 执行时上游 stock viewport meta（`apps/web/index.html:5`）**尚未解析**——"meta 缺失 → 创建"是常态路径而非边角。若照 D4 字面创建后不管，页面将永久双 meta，依赖引擎未定义的 multi-meta 合并语义，且 spec 的"还原 stock content"场景失义。实现为 **provisional meta + MutationObserver reconcile**：脚本执行时即建 provisional meta（抑制令牌先于一切 bundle 生效，时序要求满足）→ parser 插入 stock meta 时记录真 stock、token merge 改写 **stock meta 本体**、移除 provisional → 单 meta 文档；此后 resize 进出断口均以记录的 stock 为基线改写/还原（字节级还原）。无 MutationObserver 的引擎降级为 provisional 常驻（仍具抑制）。两路径（stock 先在场 = 直接改写；stock 后到 = reconcile）均有单测钉住。
-4. **payload 面**：`zoomGuard` 与 breakpoint 等键同构（配置了才进 payload，schema 默认保证生产必带 'meta'）；`zoomGuard:'off'` 时整段不生成（逃生门 = 零脚本段，非运行期判断）。
-5. **配置生命周期**：zoomGuard 随 mobile 腿（`mobile.enabled=false` 时整个 `__DASHR_MOBILE__` 不注入，zoomGuard 一并不生效）——design D5 "同路径同生命周期" 的字面执行。
-
-## 三、环境事实
-
-- canonical：`/home/u1/workspaces/dashr/dashr`（node_modules 在场，vitest/tsc 直接跑）
-- monorepo 副本：`upstream/deepseek-harness/packages/better-dsh/better-dsh`（rsync + tsdown host 半）
-- Node v22.22.1 / vitest 4.x / tsdown 0.15.x
-- dump-config：`DSH_HOME=.dsh-test npm run dsh -- web --dump-config --patch .scratch/zg-overlay.yml`（dump-config 只渲染 patch 层，schema 默认由单测钉住）
-
-## 四、boot script 评估测试明细（单测第 6 项）
-
-stub DOM（El/Document/MutationObserver/live matchMedia/resize 记录），`new Function` 执行 `buildBootScript` 真实输出：
-
-| 场景 | 断言 |
-|------|------|
-| iPhone ∧ 窄 | 脚本时 provisional meta（`maximum-scale=1, user-scalable=no`）；stock 解析后单 meta、content = `width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no` |
-| 非 viewport 解析插入 | observer 不误触发，继续守望 |
-| 宽↔窄往返 + 5 连 resize 风暴 | 离带 = 字节级还原 stock；回带 = 合并；风暴零叠加 |
-| stock 先在场（worker 形态） | 直接改写，无 provisional |
-| 无 stock 页面 | provisional 常驻；离带移除自建 meta |
-| iPad / iPadOS 桌面 UA+多点 | 改写生效；Mac 桌面（单/零触点）不生效 |
-| Android ∧ 窄 / 桌面任意宽 | stock 原样、零监听器 |
-| iPhone 宽载入后旋转入带 | 后补改写生效 |
-| zoomGuard off | 无脚本段、零改写、零监听 |
-| authorities + mobile 双腿 | `__DSH_TRANSPORT__` 与 zoomGuard 互不干扰 |
-| 断点 900 | matchMedia 收到 `(max-width:899.98px)`，payload 带 `"breakpoint":900` |
-
-## 五、真机观察（user，PWA standalone 主用法）—— TODO
-
-> 以下三章按 design D6 留给 user 真机执行（4999 或真实入口，iOS 版本号请记录）。
-
-### 5.1 放大抑制判定（tasks 3.1）— TODO
-
-- [ ] Safari 态：focus composer / permission select / settings 各 input / 切会话自动聚焦 —— 无 115–120% 放大
-- [ ] PWA standalone 态：同上全过
-- [ ] 双指缩放仍可用（iOS 10+ 应忽略 user-scalable=no 对 pinch 的约束）
-- [ ] `zoomGuard:'off'` 时放大复现（逃生门复验）
-
-### 5.2 键盘遮蔽自愈判定（tasks 3.2）— TODO
-
-- [ ] PWA 态 unzoomed 下 focus composer：键盘弹出后 composer 是否被引擎 resize 抬到键盘上方（innerHeight/100dvh 收缩联动）
-- [ ] 键盘关闭后 viewport 回弹（对照 dev.to 2026-07 记录的 iOS 17/18 standalone 卡死 bug）
-- [ ] Safari 态对照记录
-
-### 5.3 观察结论回填（tasks 3.3）— TODO
-
-- [ ] 研究文档 v2 §6 决策点 3/4 回填
-- [ ] follow-up 取舍：visualViewport shim / display-flip 自愈 / focus gate 讨论输入
-
-## 六、发现的瑕疵与去向
-
-- **发现（非瑕疵）**：head 注入 splice 位于 stock meta 之前 → 促成 provisional+reconcile 设计（见二.3）；已进 upstream-alignment S7 查表第 8 条（viewport 行形状 + splice 次序两查点）。
-- dump-config 只渲染 patch 层、不显 schema 默认 —— zoomGuard 默认值的可观测面在 payload（4999 shell 页）与单测，不在 dump-config；如需 dump 可见需显式配置（本报告第 9 项即此形态）。
-
-## 七、Open items
-- ~~tasks 2.3（4999 实例验证）~~ ✅ 完成（见八；返修 `59870fc` 后 9/9）
-- tasks 3.x 真机观察 —— user
-- 发布/npm publish 与 prod 部署 —— 另按年龄门流程，不在本 change 内
-
----
-
-## 八、4999 实测记录与 blocker 返修轮（lead，2026-09-03 晚）
-
-### 8.1 首轮矩阵与 blocker 发现
-
-- 冒烟四断言全过：A）shell head 内联脚本含 zoomGuard 段；B）boot graph 含 `"id":"better-dsh"` 与 client URL；C）zoomGuard 段（HTML 偏移 25313）早于应用入口 module script（27056）——注：client-modules 的 combo 注册脚本（1286）先于我们执行，但纯工厂注册无 DOM/focus，行为层时序满足 S2；client.js 单包 URL 200 且与 `lib/client/index.js` 前缀字节一致（+84B sourceMappingURL，S7 惯例）。
-- **CDP 视口矩阵首轮 7/9**：两个失败项均为**初始窄载入不 guard**（iOS+390、iPadOS 冒充+390）；跨断口 resize 与事后 synthetic resize 均生效。
-
-### 8.2 根因定位（诊断脚本 `diag.mjs` / `isolate.mjs`）
-
-- 事件时序实测：boot script 执行于 head 解析期，此时布局视口为 viewport-meta 未应用前的默认宽 **980**（`docStart innerWidth=980, mq.matches=false`）→ 首评不 guard；引擎随后应用 `width=device-width` 收窄到 390，但**该转换在载入期间不向页面派发 `resize` 事件**（探针隔离三变体一致；我们的 resize 监听在位且事后手动 dispatch 立即生效）。
-- 关键后果：deferred module script（React 挂载 → unlock effect 自动聚焦）在 DOMContentLoaded 前执行——依赖 resize 事件的补评可能晚于首次 auto-focus。**初始窄载入 = iPhone 用户打开 DSH 的主路径，blocker 级**。
-
-### 8.3 返修（doer 第二轮，commit `59870fc`，tag `v0.2.4` 前移）
-
-- **早期载入重评梯子**：首评未 applied 时启动 ~10ms poll 调 `re()`，三停条件 = applied / readyState complete / 200 tick（~2s）；`apply(true)` 主动取消待发 tick，稳态零 timer。guard 不再依赖任何事件通知——事件缺失只影响"多快"发现，不影响"是否"发现；首次布局必然先于 deferred scripts，抑制仍落在任何输入可聚焦之前。
-- **MQ change 监听兜底**（`mq.addEventListener('change', re)`，老引擎 `addListener` 形态）与 window resize 双通道。
-- 测试 466/466（+6：晚翻无 resize、readyState 停止、非 iOS 零 setTimeout、MQ 通道、legacy addListener、梯子先于 stock 解析落 provisional）；tsc 0。
-
-### 8.4 返修后终验（全绿）
-
-- **CDP 矩阵 9/9**：iOS+390 → guarded（单 meta、两 token 在位）；iOS+1280 → stock；iPadOS 桌面冒充+touch+390 → guarded；Android+390 / 桌面+390 / 桌面+1280 → stock（零改写）；跨断口三段（宽载入 stock → 入带 guard → 出带字节级还原 stock）。
-- **off 逃生门 live PASS**：home 层 `.dsh-test/cordis.patch.yml` 覆盖（注：CLI `web` 子命令不认 `--patch`，该路仅 dump-config 可用）→ shell **整段不发射**、payload `zoomGuard:'off'`、iOS+390 live = stock。验后已删覆盖文件并还原默认态。
-- **默认态恢复复验 + 桌面 user 复验 PASS**：还原后 iOS+390 → guarded；桌面（无 UA 伪装）meta stock 单条、app 完整渲染（root/composer/`[data-composer-card]`/sidebar/slots 在位，标题与占位文案正常）。
-
-### 8.5 遗留观察（非阻塞）
-
-- 真机 iOS Safari 上 8.2 竞态是否同样存在未证（无法本地复现 iOS 引擎）；梯子设计使其无关化——真机观察（五）会给出实证。
-- 探针实验中一次"全探针"运行曾捕捉到 resize 送达（时序非确定论），进一步佐证不能依赖事件通道。
-- CDP 测试脚本存 `.scratch/zg-verify/`（matrix/diag/isolate/off/final 五件），可复跑。
-
-## 九、v0.2.5 standalone 分流（change `2026-09-03-zoomguard-standalone-font-floor`）—— 骨架，4999/真机结论待回填
-
-> 背景：真机首批观察（§五）——浏览器态 meta 改写完美（放大抑制 + pinch 保留），但 **Add to Home Screen PWA standalone 态引擎尊重 `user-scalable=no` → pinch 失效**（Discourse 注释未覆盖的形态；spec v1 的 "pinch remains engine-controlled" 括号在 standalone 不成立）。user 裁决：standalone 态完全不碰 viewport meta，改注入 16px 字号地板 CSS；browser 态维持 v0.2.4。user 主用法即 PWA。
-
-### 9.1 实现摘要（doer，2026-09-03）
-
-- 纯函数（`src/mobile/zoom-guard.ts`，ES5 自包含，toString 嵌入，`var ZD=`/`var ZF=` 与 ZI/ZM/ZS 同款）：`isStandaloneDisplay(mqMatchesStandalone, navStandalone)` = 严格 `=== true` 双源 OR（MQ 主源 + `navigator.standalone` 老 iOS 兜底）；`buildFontFloorCss(bp)` → `@media (max-width:{bp-0.02}px){ input,textarea,select,[contenteditable="true"]{ font-size:16px !important } }`（断口派生与 meta 腿一致：768→767.98、900→899.98）。
-- boot script 分流（D1）：iOS 判定后、任何 meta 逻辑前 —— `var sa=ZD((window.matchMedia&&window.matchMedia('(display-mode: standalone)').matches),(navigator.standalone===true));` standalone → `headEl()` 注入 `<style id="ios-zoom-font-floor" data-plugin="better-dsh" data-plugin-css="better-dsh/zoom-font-floor">`（textContent=ZF(rawBp)）后 **return**：其后 provisional/reconcile/监听/梯子代码字面不可达，meta 字节不动。**style 注入不设宽度门**（宽度由 CSS media query 表达，宽屏 standalone 也注入、规则自然不匹配）。
-- `'off'`：整段不发射（web-trust 门不变、零改动）；`'meta'` 语义升级为自动双形态（enum 不动）。web-trust.ts / client 半零改动。
-
-### 9.2 单测（canonical，doer）
-
-- **478/478 + tsc 0**（v0.2.4 基线 466，+12）：双源判定矩阵（含 undefined 单源兜底）、CSS 文本钉扎（selector 集合 / `!important` / 768→767.98 与 900→899.98）、standalone 矩阵（MQ 源：style 在场 + 三认领属性 + meta 字节不动 + 零 addEventListener/setTimeout/MutationObserver 痕迹 + 零窄带 MQ 探针；宽屏仍注入；navigator.standalone 单源；无 matchMedia 兜底；断口 900；browser 态显式无 style；off 双零）。
-- stub 基建：`runBootScript` 增 `standaloneAtScriptTime`/`navStandalone` 参数，matchMedia 按查询串分流（display-mode 探针不再误读窄带裁定）；browser 全矩阵零回归（mediaQueries 断言更新为含 display-mode 前导探针）。
-
-### 9.3 4999 CDP 双形态（lead，2026-09-03 深夜）—— ✅ 8/8 全绿
-
-**⚠ 测试方法学发现（重要）**：Chrome 的 `Emulation.setEmulatedMedia` **不支持 `display-mode` 特性**（实测 pre-nav/post-nav 设置后页面内 `matchMedia('(display-mode: standalone)').matches)` 恒 false —— Chrome 可仿真特性集不含它，DevTools Rendering 面板亦无此项）。改用 **matchMedia API 边界注入**：`Page.addScriptToEvaluateOnNewDocument` 在一切页面脚本（含 head 注入 boot script）之前包一层 `matchMedia`，仅对含 display-mode+standalone 的查询返回 `{matches:true}`，其余透传 —— boot script 全部分支逻辑照真运行（自检探针 truth=true 证实注入生效）。
-
-| 场景 | 断言 | 结果 |
-|---|---|---|
-| standalone+iOS+390 | meta **字节不动**（`width=device-width, initial-scale=1` 原文）= pinch 恢复前提 | ✅ |
-| standalone+iOS+390 | `#ios-zoom-font-floor` 在场，认领属性齐（data-plugin / data-plugin-css=better-dsh/zoom-font-floor），CSS 文本与 user 提案逐字一致 | ✅ |
-| standalone+iOS+390 | composer computed font-size = **16px**（地板生效） | ✅ |
-| browser+iOS+390 | meta guarded（两 token 在场）、无 font-floor | ✅ |
-| browser+iOS+390 | **client 特性探针**：sidebar computed 首列 0px、认领样式 98 条（v0.2.1f 特性在位） | ✅ |
-| standalone+iOS+1280 | floor 已注入（宽度无关）但 media query 不激活（composer 14px） | ✅ |
-| standalone+Android+390 | iOS 门 → 无 floor、meta stock | ✅ |
-| off | 双形态零发射（单测钉住；'off' 代码路径 v0.2.4 未动） | ✅ |
-
-脚本 `.scratch/zg-verify/dual-mode.mjs`（含 matchMedia 边界注入实现）；重启后 boot graph rev 已随 v0.2.5 变化，tsdown+build-client 双步完成、lib/client 在场（md5 `a88850ec…`）。
-### 9.4 真机复验（user）—— TODO（tasks 3.1）
-
-- [ ] PWA standalone：pinch 恢复 + focus 无放大（输入面 16px）。
-- [ ] 浏览器态：维持 §五 结论（meta 改写 + pinch 保留）。

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/SKILL.md

@@ -1,147 +0,0 @@
----
-name: dsh-dev-skill
-description: "Reference knowledge base distilled from the official DeepSeek Harness (dsh) developer documentation. Use when developing, extending, or debugging dsh plugins, Cordis services/events, LLM adapters, tools, sandbox/approval policy, web UI slots, session/persistence internals, or the Typert API gateway."
----
-
-# DeepSeek Harness (dsh) — Official Docs, Distilled
-
-**Source**: official `deepseek-ai/deepseek-harness` master `docs/` (123 English files, fetched 2026-09-06 into `../src/docs/`) | **Chapters**: 22 | **Generated**: 2026-09-06 | **Depth**: reference (decision-ready lookup)
-
-## How to Use This Skill
-
-- **Without arguments** — load the core mental models below before touching dsh code
-- **With a topic** — ask about `compaction`, `slots`, `sandbox`, `fibers`; I read the matching chapter file first
-- **With a chapter** — ask for `ch15` to load that chapter only
-- **Browse** — ask "what chapters do you have?" for the full index
-
-Chapters are on-demand: only the one you load counts against context.
-
----
-
-## Core Mental Models
-
-**1. Everything is a Cordis plugin; layers compose the app.**
-A running dsh is a plugin tree composed at boot from ordered layers — bundles (listed order) → profile patch → home patch → `--patch` argv — with no privileged core. A patch row targets a plugin id and **replaces its whole config value** (no deep merge): restate every key or lose fields. Ordering between plugins comes from `inject` dependencies, never YAML position. Prefer mounting a plugin or patching a row over forking core, because registrations are reversible effects.
-
-**2. The session log is the single source of truth; history is derived.**
-Every model-visible fact is an append-only `SessionEvent` (`{type, seq, time, data}`). Message history is folded from it (`deriveMessages()`), never stored. Only three surface types produce transcript messages: `user/message`, `assistant/message`, `tool/result` — everything else is audit/state. "Model-visible means logged" is a runtime invariant. State-carrying events carry **whole values, not deltas**. When you need derived per-session state, register a `ProjectionDefinition` — the registry drives, backfolds, and checkpoints it for you.
-
-**3. Capabilities are three-role seams.**
-A swappable capability = abstract Service Definition (`ctx.fs`, `ctx.llm`, `ctx.subagents`) + Provider + thin provider-neutral Consumer tools. Filesystem/subprocess/sandbox form one "execution world" — swap them together. Build a seam only when ≥2 implementations are plausible. Remote controllers project seams onto the wire and own redaction/refusal. Never depend on `ctx.agentLoop`; extension packages use `dsh-agent` events/services.
-
-**4. Tool calls cross a fixed policy pipeline.**
-`tools/pre-execute` (allow/deny/ask decision) → approval (fail-closed: absent asker = deny) → monotonic guards (deny-or-abstain, can never force-allow) → execute → `tools/post-execute` (transform) → `finalizeContent` → snapshotted result (throws become `isError`). Sandbox mode and approval policy are two independent, per-call-resolved knobs. No usable sandbox backend ⇒ `SANDBOX_UNAVAILABLE`, never silent passthrough; escalation is one-shot, strictly wider.
-
-**5. Packages share instances via peer dependencies.**
-The module graph is a peer-dependency graph of shared service instances: an edge means "consume the host's instance" — bundling your own copy breaks identity. Use `ctx.get(name)` for undeclared optional services; `ctx.<name>` throws through foreign fibers. Service visibility is ancestor/isolate only; `provide` throws on duplicates within a scope — sibling shadowing does not exist.
-
-**6. Events have contracts; waterfalls have discipline.**
-Dispatch mode (emit / serial / parallel / bail / waterfall) is part of each event's public contract — call the matching method. In waterfalls, observers must call `next()`; omitting it is a deliberate veto. Policy that must not be reordered belongs in monotonic guards, not pre-execute listeners (which other listeners can reshape).
-
-**7. LLM adapters are thin and provider-neutral at the wire.**
-`LlmAdapter.stream()` emits the closed `StreamChunk` union; the shared `BlockAssembler` reassembles blocks (never per-adapter). One adapter call = one attempt; retries live at agent level (`ResolvedRetryPolicy`). Usage arrives at provider end-of-stream. Credentials are `CredentialRef`s resolved per operation (rotation without restart). Can't honor a `GenerateOptions` field ⇒ throw `LlmError('UNSUPPORTED_OPTION')`.
-
-**8. The web surface is a dumb carrier plus typed slots.**
-`ctx.webServer` owns no TLS/auth/Origin policy — trust is supplied at composition (or a second isolated server for webhooks). The browser app boots from `WebBootGraph` (`window.__DSH_BOOT__`). The only sanctioned UI extension is `ctx.slots.inject` with a fresh list id; single/keyed cells are replacement points. Settings writes are CAS (`SettingsPathOp` + expectedRevision, `redactSecrets` on wire) — never `replace()` from a redacted view. Remote (Typert) methods are strictly unary; streamed responses use Connection Fetch routes; client calls return non-throwing `RemoteResult<T>`.
-
----
-
-## Chapter Index
-
-| # | Title | Key contents |
-|---|---|---|
-| [ch01](chapters/ch01-user-guide.md) | User Guide | providers, credentials, compat blocks, MCP memory, proxy, Python SDK, schedules |
-| [ch02](chapters/ch02-plugin-basics.md) | Plugin Dev Basics | plugin anatomy, Config schema, defineTool, bundles/profiles, layer order, publishing |
-| [ch03](chapters/ch03-plugin-framework-practice.md) | Framework & Practice | fibers, events, service isolation, capability split, LlmAdapter, dynamic Cordis |
-| [ch04](chapters/ch04-cordis-fundamentals.md) | Cordis Fundamentals | plugin shapes, inject, PENDING, dispatch modes, waterfall veto, HMR, `!!js` |
-| [ch05](chapters/ch05-cordis-api.md) | Cordis API | Context scoping (extend/isolate/intercept), fiber API, service store symbols |
-| [ch06](chapters/ch06-architecture.md) | Architecture & Lifecycle | boot layers, profiles, turn/step model, session generations, rescope |
-| [ch07](chapters/ch07-capability-seams.md) | Capability Seams | seam taxonomy, execution world, event-gate companions, selection table |
-| [ch08](chapters/ch08-internals-pipelines.md) | Internals & Pipelines | module graph, event producer–consumer matrix, tool pipeline, defensive patterns |
-| [ch09](chapters/ch09-api-gateway.md) | API Gateway | Typert `@Remote`, `/api` routes, trust fence, DeepSeek wire extensions |
-| [ch10](chapters/ch10-config-catalog.md) | Config Catalog | `config:` blocks, `Requires:` lines, package classes, runtime-only seams |
-| [ch11](chapters/ch11-tool-catalog.md) | Tool Catalog | boot-and-read registry, capability seams, `run_code` transport, aliases |
-| [ch12](chapters/ch12-persistence-catalog.md) | Persistence Catalog | `SessionEventMap`, surface vs log-only, compaction shadow price, migrations |
-| [ch13](chapters/ch13-subsystems-core-session.md) | Subsystems: Core & Session | core spine, event log, inbox, system-prompt assembly, invariants |
-| [ch14](chapters/ch14-subsystems-agent-loop.md) | Subsystems: Agent Loop | subagents, teams, workflows, goals, plan mode, compaction, spill |
-| [ch15](chapters/ch15-subsystems-tool-execution.md) | Subsystems: Tool Execution | ToolRuntime, shell/fs/subprocess, sandbox backends, approval, presets |
-| [ch16](chapters/ch16-subsystems-session-data.md) | Subsystems: Session Data | projections, session-query, storage domains, attachments, jobs |
-| [ch17](chapters/ch17-subsystems-llm-streaming.md) | Subsystems: LLM Streaming | StreamChunk, BlockAssembler, token meter, typert, credentials, client-modules |
-| [ch18](chapters/ch18-subsystems-web-ui.md) | Subsystems: Web & UI | webServer, slots, settings, commands, skills, terminals, webhooks, schedule |
-| [ch19](chapters/ch19-cookbook.md) | Extension Cookbook | recipes: packages, vendoring, tools, settings cards, adapters, PR stacks |
-| [ch20](chapters/ch20-development-testing.md) | Dev & Testing | build faces, test tiers, coverage gates, doc budgets, type-equiv fences |
-| [ch21](chapters/ch21-postmortems.md) | Postmortems | export-default trap, `!!js` scope, GUI feedback loop, Landlock classification |
-| [ch22](chapters/ch22-i18n.md) | i18n & Translation | zh pairing contract, terminology, protected tokens, translation pipeline |
-
-## Topic Index
-
-- **adapters (LLM)** → ch03, ch17, ch19
-- **agent lifecycle / turn model** → ch06, ch13
-- **agent-team** → ch14
-- **approval / escalation** → ch07, ch15
-- **architecture / boot** → ch06, ch08
-- **attachments** → ch16
-- **background jobs** → ch16, ch19
-- **build / DSH_BUILD_FACE** → ch09, ch20
-- **bundles / profiles / layers** → ch02, ch06
-- **client modules / WebBootGraph** → ch17, ch18
-- **compaction** → ch12, ch14
-- **config (cordis.yml, catalog)** → ch02, ch10
-- **cookbook recipes** → ch19
-- **credentials** → ch01, ch17
-- **Cordis (framework, API)** → ch04, ch05
-- **defensive patterns** → ch08
-- **defineTool / tool authoring** → ch02, ch11, ch19
-- **dispatch modes / waterfalls** → ch03, ch04, ch08
-- **dynamic Cordis** → ch03, ch13
-- **events (Cordis vs session)** → ch03, ch12
-- **fibers / registry** → ch04, ch05
-- **filesystem / observation policy** → ch11, ch15
-- **goals** → ch14
-- **HMR** → ch03, ch04
-- **hooks (lefthook)** → ch20
-- **inbox / steering** → ch13
-- **invariants** → ch13
-- **i18n** → ch22
-- **isolate / intercept** → ch05
-- **jobs** → ch16
-- **LlmError / retries** → ch03, ch17
-- **MCP** → ch01
-- **module graph** → ch08
-- **persistence / session log** → ch12, ch16
-- **plan mode** → ch14
-- **postmortems** → ch21
-- **projections** → ch16
-- **providers (user config)** → ch01
-- **Python SDK** → ch01
-- **Remote / Typert gateway** → ch09, ch19
-- **sandbox (modes, backends)** → ch10, ch15
-- **schedules** → ch01, ch18
-- **session-query / title / telemetry** → ch16
-- **settings cards / CAS** → ch18, ch19
-- **skills subsystem** → ch18
-- **slots / UI injection** → ch18
-- **spill** → ch14
-- **StreamChunk / streaming** → ch17
-- **subagents** → ch14
-- **system prompt** → ch13
-- **testing tiers / coverage** → ch20
-- **tools registry / pipeline** → ch08, ch11, ch15
-- **typert (typing)** → ch17
-- **vendoring / packages** → ch19
-- **web server / client / trust** → ch18
-- **webhooks** → ch18
-- **workflows** → ch14
-- **workspace** → ch16
-
-## Supporting Files
-
-- [glossary.md](glossary.md) — ~55 key terms with exact definitions
-- [patterns.md](patterns.md) — 17 techniques: when / how / trade-offs
-- [cheatsheet.md](cheatsheet.md) — seam-selection table, hard rules, defaults, smells
-
----
-
-## Scope & Limits
-
-Distilled exclusively from the **official** `deepseek-ai/deepseek-harness` master docs (English) fetched 2026-09-06; the raw source is preserved at `../src/docs/` (241 files incl. zh pairs) with URL mapping in `../src/site-pages-map.txt` for verbatim lookups. No local research, forks, or third-party analysis was folded in. Generated catalogs (config/tool/module-graph) are summarized, not reproduced — consult the source files for exhaustive per-entry detail. Docs describe the harness at the fetched master revision; verify against your deployed version when behavior matters.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch01-user-guide.md

@@ -1,123 +0,0 @@
-# Chapter 1: User Guide — Providers, MCP Memory, Proxy, SDK, Schedules
-
-## Core Idea
-Every user-facing surface — the Models page, MCP overlays, proxy env vars, the Python SDK, Schedule and GitHub-review overlays — reads or writes the same file-backed composition (`$DSH_HOME/settings.yaml` + Cordis patch layers); model and provider changes take effect on the next request with no server restart.
-
-## Frameworks Introduced
-- **Models page (`Settings → Models`)**: minimal provider form — API key, display name, base URL, API protocol, per-model id/name/context-window/max-output-tokens. Everything else lives in `settings.yaml`.
-  - When to use: DeepSeek, a built-in provider (`anthropic`, `openai`, `moonshotai`/Kimi, `zai`/GLM), or a custom gateway. OAuth providers (Codex) unsupported.
-  - How: enter key → save. Keys are write-only (page receives a redacted descriptor); the secret lands in `$DSH_HOME/.credentials.yaml`, settings keep only a credential reference.
-- **Custom provider form**: lowercase permanent Provider ID + base URL + one API protocol (`openai-completions` | `openai-responses` | `anthropic-messages`) + credential + ≥1 model. One protocol per provider; a dual-protocol gateway needs two providers.
-- **`@deepseek-ai/dsh-mcp-client` row**: generic MCP connector; discovered tools surface as `mcp__<serverName>__<tool>`. Default-off reference configs: Memorix `1.3.0`, MCP Reference Memory `2026.7.4`, Engram `v1.20.0` (all stdio).
-  - When to use: third-party memory or any MCP server.
-  - How: `dsh web --patch <overlay>.cordis.yml`; persist by merging the `insert` row into `$DSH_HOME/profiles/<name>/cordis.patch.yml` (one profile) or `$DSH_HOME/cordis.patch.yml` (all profiles). Never overwrite an existing patch file.
-- **Python SDK (`deepseek-harness-sdk`)**: pip wheel bundling a native runtime + the `dsh` CLI (no system Node); a context manager lazily starts `dsh --profile sdk-minimal` and reuses it until exit.
-- **Schedule overlay**: session-local reminders via `schedule_create` / `schedule_list` / `schedule_delete` (positive `after_seconds`, absolute `at`, or `every_seconds` ≥ 300).
-- **GitHub review overlay**: signed webhook endpoint creating read-only review Sessions on PR `ready_for_review`.
-
-## Key Concepts
-- **Provider ID**: permanent lowercase id — requests, saved sessions, model defaults, and credential references use it; rename = add new + delete old.
-- **`compat` route block**: request-shape corrections pi-ai cannot infer from the URL (`supportsDeveloperRole`, `maxTokensField`, `thinkingFormat`); full switch list = `PiAiCompatProfile` in the generated `dsh-llm-pi-ai` config reference.
-- **`reasoningEfforts`**: per-model map of menu level → wire spelling of `reasoning_effort`; only `off` may be empty (param absence); `compat.thinkingFormat: deepseek` makes `off` send `thinking: {type: disabled}` and other levels `thinking: {type: enabled}` beside the effort.
-- **`input` / `defaultInput` / `modelOverrides`**: modality claims (`text`, `image`) at model level, route fallback (default `[text]`, never strips a catalog model's images), and per-model overrides on built-in providers; unknown modality refused everywhere.
-- **`--patch` overlay**: one-file config layer passed at launch; argv order matters (layer order in Ch 2).
-- **stdio env scrubbing**: the MCP bridge removes credential-named ambient vars and all `DSH_*` vars before spawning a child; per-row `config.env` is the sanctioned secret channel.
-- **Proxy env vars**: `HTTPS_PROXY`/`HTTP_PROXY` read at launch; `NO_PROXY` matches host + subdomains (leading `.`/`*.` equivalent, `*` bypasses all, CIDR never works); loopback always direct; SOCKS reported and skipped; `ALL_PROXY` fallback; `NODE_EXTRA_CA_CERTS` for TLS-intercepting proxies.
-- **`sdk-minimal` profile**: `dsh-sdk-app` JSON-RPC row over an empty root (no `dsh-base`); pins `danger-full-access`; uncompressed JSONL sessions; no compaction, telemetry, or web tools.
-- **Session-local reminder**: owned by the session log; delivered as a queued follow-up turn when the root Agent is fully idle; reopening a cold session restores overdue reminders; forks don't inherit.
-
-## Mental Models
-- Think of the Models page as a deliberate thin editor over `settings.yaml` — same document, re-read per request by the adapters.
-- Treat MCP as a ferry, not a supervisor: DSH parses the overlay, launches/monitors stdio children, re-syncs tools on reconnect — it never installs servers, migrates data, or manages models/embeddings.
-- Proxy reachability is three unrelated mechanisms (OS settings, env vars, TUN mode); CLI tools see only env vars — export them or use TUN.
-- Schedule delivery is "the session talks to itself later": no browser/OS/email channel, just a follow-up turn in the original conversation.
-
-## Anti-patterns
-- **Renaming a Provider ID in place**: every reference (sessions, defaults, credentials) uses it; add a new provider and delete the old one.
-- **Proxy vars in a project `.env`**: DSH refuses to start — a repository must not decide where traffic goes; use a shell profile or `$DSH_HOME/.env` (exported vars win).
-- **CIDR entries in `NO_PROXY`**: no effect; use hostnames/domain suffixes.
-- **Trusting built-in provider discovery against a gateway**: the installed catalog always answers; fetch through a custom provider to see what the gateway really serves.
-- **Reading webhook `202` as "session created"**: it means only signature + JSON accepted and rule calls scheduled in memory.
-- **Expecting notifications from Schedule**: no external notification exists; delivery is only the queued follow-up.
-
-## Code Examples
-Custom provider with the two most common compat fixes:
-```yaml
-llm-pi-ai:
-  providers:
-    my-gateway:
-      apiKeyEnv: GATEWAY_API_KEY
-      api: openai-completions
-      baseURL: https://gateway.example/v1
-      compat:
-        supportsDeveloperRole: false   # gateway rejects role: "developer"
-        maxTokensField: max_tokens     # gateway refuses max_completion_tokens
-      models:
-        - id: vision-preview
-          input: [text, image]
-        - id: my-reasoner
-          reasoningEfforts: { off: , high: high, max: max }
-```
-Generic MCP row (stdio):
-```yaml
-- insert:
-    - id: memory-my-server
-      name: '@deepseek-ai/dsh-mcp-client'
-      config:
-        serverName: my-memory
-        transport: stdio        # remote: streamable-http + url + headers
-        command: my-memory-mcp
-        args: []
-        env: {}
-        cwd: !!js process.cwd()
-```
-SDK entry point:
-```python
-from deepseek_harness import DeepSeekHarness
-with DeepSeekHarness(provider="deepseek-official", model="deepseek-v4-flash",
-                     max_tokens=49_152, cwd=str(ws), dsh_home=str(home),
-                     profile="sdk-minimal") as harness:
-    result = harness.run("Inspect the repository.", session_id="example-001")
-print(result.final_response)
-```
-Proxy:
-```sh
-export HTTPS_PROXY=http://user:pass@proxy.example:8080  # creds in URL, never printed back
-export NO_PROXY=internal.example.com,.corp.example.com
-export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem    # export before process start
-```
-
-## Reference Tables
-| Surface | Activation | Persistence |
-|---|---|---|
-| Custom provider / compat | Models page or `settings.yaml` | `settings.yaml` (re-read per request) |
-| MCP memory server | `--patch examples/mcp-memory/<x>.cordis.yml` | merge row into `cordis.patch.yml` |
-| Schedule | `--patch examples/schedule/cordis.yml` | overlay only (per-process opt-in) |
-| GitHub review | `--patch` + `DSH_GITHUB_WEBHOOK_SECRET` | rows appended to profile patch; `github-ready-review-rule.mjs` beside it |
-| SDK plugins | `dsh plugin --profile sdk-minimal add file:/path` | `$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml` |
-
-| Symptom | Fix |
-|---|---|
-| `MISSING_CREDENTIAL` | store key via Models page or set the referenced env var |
-| `UNKNOWN_MODEL` | select a configured model or add it to the custom provider |
-| model fetch → 401 | bad key; discovery calls `GET /models` — enter models by hand if absent |
-| only reasoning models fail | `compat.supportsDeveloperRole: false` |
-| `off` doesn't stop DeepSeek thinking | `compat.thinkingFormat: deepseek` on model or route |
-| image refused before sending | add `input: [text, image]`; after removing a wrong claim, start a new session (log replays the attachment) |
-
-Schedule `at`: strict RFC 3339 with `Z` or numeric offset, or `{date, time, time_zone}` with explicit `UTC`/IANA Area/Location; DST gaps rejected, overlaps pick the first instant, records keep UTC only. Overdue `every` records: latest occurrence only, same-idle batches combined (one-shots first), no backlog; cron/calendar unsupported.
-
-## Key Takeaways
-1. Model config is two-tier: the form covers what a route needs to exist; reasoning, modality, compat, headers, timeouts, retries live under `llm-pi-ai.providers.<id>` in `settings.yaml` (DeepSeek's own route: `llm-deepseek.reasoningEffort`, e.g. `max`).
-2. Compat switches and modality lists state claims, not checks — they never probe the endpoint; an empty compat key is refused, not ignored.
-3. A crashed MCP child reconnects with backoff and tool re-sync; after the reconnect budget is exhausted, tools unregister until reload/restart. Initial discovery is async — wait for `mcp__...` tools before validating.
-4. Model-authored workflow/code-runtime workers never receive proxy settings; OTLP telemetry is always direct (`DSH_TELEMETRY_MODE=DISABLED` to disable); `web_fetch` to literal private addresses is refused.
-5. The SDK never silently reads `~/.dsh` — pass an explicit `dsh_home`; `web` is a separate CLI application and cannot serve a Python SDK client.
-6. Webhook `run()` is trusted JS: policy-service gates and repo→path maps are ordinary code returning `null` to skip; the secret authenticates inbound data only, granting no outbound GitHub access.
-
-## Connects To
-- **Ch 2**: `--patch` overlays here are the same rows bundles ship; layer order defined there.
-- **Ch 10**: generated config catalog owns every `llm-pi-ai` field incl. `PiAiCompatProfile`.
-- **Ch 17**: compat/reasoning switches map onto the LLM streaming adapter contract.
-- **Ch 7**: MCP rows and provider config are capability seams in the composition.
-- **Ch 18**: Models page, reminder catalog, and sidebar alarms are Web UI surfaces.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch02-plugin-basics.md

@@ -1,127 +0,0 @@
-# Chapter 2: Plugin Development Basics
-
-## Core Idea
-A dsh plugin is a Cordis module — `apply(ctx)` plus declarative `name` / `inject` / `Config` exports — where every `ctx` registration is a lifecycle-managed effect; shipping it means packaging a patch layer (bundle) that a profile composes in a fixed order.
-
-## Frameworks Introduced
-- **Plugin apply contract**: a TypeScript module exporting `name`, optional `inject`, and `apply(ctx)` (or object/class default export). The framework calls `apply` only after every injected service is ready.
-  - When to use: function form covers most cases; class form (`extends Service`, `static inject`, `super(ctx, 'svc')`) when the plugin provides a service to other plugins.
-  - How: dev overlay `- insert: [{id, name: '/absolute/path/src/my-plugin.ts'}]` → `pnpm dsh web --patch ./cordis.yml`.
-- **Schemastery Config schema**: `export interface Config` + `export const Config: Schema<Config> = Schema.object({...})` with `.default()` / `.required()` / `.union()`.
-  - When to use: anything two deployments may want to set differently — Harness requires this as a config field.
-  - How: `apply(ctx, config)` receives validated, default-filled config. Cordis validates while loading; invalid config fails the load with an actionable error. Config values arrive via the plugin row's `config:` key.
-- **`defineTool` DSL** (`@deepseek-ai/dsh-tools`): declarative tool — `parameters` (arg inference/validation), `output.schema` (canonical value type), `output.render` (value → model-facing content), `execute`.
-  - When to use: exposing any model-callable capability.
-  - How: `export const inject = ['tools']`, then `ctx.tools.register(defineTool({...}))`.
-- **Bundle manifest**: npm package declaring `dsh: { bundle: { patch: './cordis.patch.yml' } }`; patch rows reference the package by name so Node resolution finds the installed code. Answers "what does this package contribute?"
-- **Profile manifest**: `$DSH_HOME/profiles/<name>/` — `package.json` with ordered `dsh.profile.bundles` + a user `cordis.patch.yml` layer. Answers "which bundles compose this setup, in what order?" Created and maintained by `dsh plugin`, never written by hand.
-- **App-owned command line**: a provider plugin with `inject = ['cmdlineArgs']` calling `parseCmdline` from `@deepseek-ai/dsh-cmdline` with its own commander program, publishing an app-owned service from the program's action.
-
-## Key Concepts
-- **`ctx.effect(() => disposer)`**: escape hatch for resources `ctx` doesn't track (sockets, intervals); the returned function runs on unload.
-- **Automatic cleanup**: `ctx.on`, `ctx.tools.register`, `ctx.llm.registerAdapter`, `ctx.effect` are all undone at unload — no manual `removeListener`/`clearInterval`.
-- **HMR**: a config or source edit hot-replaces the plugin (unload old → load new → run new `apply`); old registrations never leak.
-- **Layer order**: bundle patches in `dsh.profile.bundles` list order → profile `cordis.patch.yml` → `$DSH_HOME/cordis.patch.yml` → `--patch` overlays in argv order. Later layers win per row.
-- **Row override**: a patch replaces a row's entire `config` value, never deep-merging keys — restate every key the row needs.
-- **In-box bundles** (`@deepseek-ai/dsh-base`): always resolve from the dsh installation itself; pnpm manages only out-of-tree packages.
-- **`prepare` script**: what pnpm runs after a git install; must be self-contained (no sibling-monorepo assumptions). turtle-ui's dedicated tsdown config is the working example.
-- **`allowBuilds`**: pnpm ≥10 gate for a git dependency's build scripts, keyed in the profile's `pnpm-workspace.yaml` (`allowBuilds: { 'dsh-hello-plugin': true }`); granting it = permission to execute the package's code on your machine at install time.
-- **Plain dependency**: a package without `dsh.bundle` installs with a warning and activates no layer — the library format for code that plugin packages import.
-
-## Mental Models
-- Think of a plugin as a block scoped to `apply`: when the block exits (unload, HMR, dependency loss), everything it registered vanishes.
-- Think of a bundle as "one patch layer in an npm package" and a profile as "an ordered list of such layers with user patches on top"; a bundle is authored and distributed, a profile is booted — nothing is both.
-- Use absolute paths in dev overlays because a patch contributes configuration only — it never changes the directory the loader resolves module paths from.
-- Treat `dsh --profile <name> --dump-config` as the no-boot layer inspector: each bundle shows as a `# == <pkg>` section.
-
-## Anti-patterns
-- **Plain-object `Config` export**: doesn't implement the Standard Schema interface Cordis requires.
-- **Hardcoded tunables**: if `cordis.yml` cannot change the value without a code edit, it must become a config field.
-- **Partial row override**: patching only the changed key drops the rest of the row's config (whole-value replacement).
-- **Relative plugin path in an overlay**: loader resolves from the profile directory, not the patch file's location.
-- **Git install without `prepare`**: sources arrive unbuilt — a TS package loads without its `lib/`.
-- **Unpinned git adds with `allowBuilds`**: a later push silently changes what executes at install time; pin `github:you/pkg#<sha>` and only allowlist source you trust.
-
-## Code Examples
-Config + tool in one 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 = 'greet-tool'
-export const inject = ['tools']
-
-export interface Config { greeting: string; maxRetries: number }
-export const Config: Schema<Config> = Schema.object({
-  greeting: Schema.string().default('Hello'),
-  maxRetries: Schema.number().default(3),
-})
-
-export function apply(ctx: Context, config: Config) {
-  ctx.tools.register(defineTool({
-    name: 'greet',
-    description: 'Greet someone by name.',
-    parameters: { name: { type: 'string', required: true, description: 'The name to greet' } },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value }],
-    },
-    async execute(args) { return `${config.greeting}, ${args.name}!` },
-  }))
-}
-```
-Bundle package + patch:
-```json
-{ "name": "dsh-hello-plugin", "version": "0.1.0", "type": "module", "main": "index.js",
-  "files": ["index.js", "cordis.patch.yml"],
-  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } }
-```
-```yaml
-- insert:
-    - id: hello
-      name: dsh-hello-plugin     # package name, not a path
-```
-Surface-bundle flag row (rows stay dormant under `--help` because the provider publishes no service):
-```yaml
-- id: my-app
-  name: '@example/my-app'
-  inject: [myAppStartup]
-  config:
-    port: !!js ctx.myAppStartup.port ?? 8080
-```
-Install / inspect / remove:
-```sh
-dsh plugin --profile demo add ./hello-plugin   # pnpm link + append to dsh.profile.bundles
-dsh --profile demo --dump-config               # shows the "# == dsh-hello-plugin" layer
-dsh plugin --profile demo remove dsh-hello-plugin
-```
-
-## Reference Tables
-| Plugin form | Export | Use when |
-|---|---|---|
-| Function | `export const name` / `inject` + `export function apply` | most cases |
-| Object | `export default { name, inject, apply }` | grouping options |
-| Class | `export default class extends Service` | providing a service to other plugins |
-
-| Distribution | User command | Build happens |
-|---|---|---|
-| npm | `dsh plugin --profile demo add your-package` | at `pnpm publish` (ship built `lib/`) |
-| tarball | `dsh plugin add ./hello-plugin-0.1.0.tgz` | at `pnpm pack` |
-| git | `dsh plugin add github:you/pkg#<sha>` | author's `prepare` + user's `allowBuilds` |
-
-Layer composition (later wins per row): 1. bundle patches in `bundles` list order (`@deepseek-ai/dsh-base` first) → 2. profile `cordis.patch.yml` → 3. home `$DSH_HOME/cordis.patch.yml` → 4. `--patch` overlays in argv order. App arguments are not a patch layer.
-
-## Key Takeaways
-1. `dsh plugin --profile <name> <args...>` just forwards to pnpm in the profile directory — every pnpm verb works; first use initializes the profile with `@deepseek-ai/dsh-base` first in `bundles`.
-2. `execute` returns the canonical value declared by `output.schema`; `output.render` converts that value into model-facing content blocks.
-3. Fail loudly at load: self-contained constraints belong in the schema; constraints referencing live services or registered resources need dependency injection (Ch 3).
-4. Users can override your rows in their profile patch without touching your package — prefer defaults they'll keep and let the schema carry the rest.
-5. A surface bundle needs no launcher change for its own flags: all plugins receive the same immutable post-launcher args snapshot, and multiple plugins may parse it independently.
-6. Loader evaluates a row's `!!js` config only after that row's ordinary injections resolve — config expressions can read injected services with a deployment fallback beside them.
-
-## Connects To
-- **Ch 3**: lifecycle, events, services, and the three-role capability split build directly on `apply` / `inject` / `ctx.effect`.
-- **Ch 4 / Ch 5**: Cordis fundamentals and API own the loader, Fiber, and patch semantics summarized here.
-- **Ch 11**: full tool-authoring reference — nested schemas, canonical values, background work, policy hooks, PTC mode, UI cards.
-- **Ch 10**: the generated config catalog is derived from these `Config` schemas.