@nonamelego/dsh-catppuccin 0.5.9 → 0.5.10-beta.1

package/README.en.md

@@ -125,22 +125,29 @@ dsh plugin --profile web add @nonamelego/dsh-catppuccin
 Restart `dsh web` after installing — `dsh plugin` adds it to the profile's bundles.
 Use the profile name of your choice in place of `web` (e.g. `headless`).
 
-**Desktop**: the desktop build's active profile is named `desktop`
-(`$DSH_HOME/profiles/desktop`), so run:
+**Desktop**: the official desktop shell and the community desktop shell both read the **same profile**
+`$DSH_HOME/profiles/desktop`, but **they install/upgrade plugins in completely different, non-interchangeable
+ways** — pick the column that matches your shell:
 
-```sh
-dsh plugin --profile desktop add @nonamelego/dsh-catppuccin
-```
+| | Official desktop shell ([DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) app) | Community shell ([DSH Desktop](https://github.com/anywhere-labs/dsh-desktop)) |
+|---|---|---|
+| **Install** | Its **plugin UI** → add plugin → enter the package name `@nonamelego/dsh-catppuccin` (Git URLs / tarballs / local paths are accepted too) | In the app's own **DSH terminal**:<br>`dsh plugin --profile desktop add @nonamelego/dsh-catppuccin` |
+| **Upgrade** | **Remove the plugin in the plugin UI, then enter the same package name again to reinstall it** (v0.2.0 has no upgrade entry point and no version picker) | The same `update` command as web:<br>`dsh plugin --profile desktop update @nonamelego/dsh-catppuccin` |
+| Runs pnpm | The app's bundled pnpm | The app's bundled pnpm |
+
+Either way, **restart the desktop app** to load the new version.
 
-Run it in the DSH terminal of the desktop app (`dsh plugin` defaults to the active profile),
-then restart the app.
-Installing from the repo works the same way: `dsh plugin --profile desktop add https://github.com/NoNameLeGo/dsh-catppuccin-theme`.
+> ⚠️ **Do not mix the columns**: the official shell's plugin UI does not run commands, and the community
+> shell's `update` command does not apply to the official shell. Also, **the plain `dsh` on your system PATH
+> cannot manage `desktop` in either shell** — upstream reserves that profile name and rejects it with
+> `error: profile "desktop" is managed exclusively by the Electron application`. To use the CLI, use another
+> profile name (`web`, `headless`, `dsh-tui`).
 
 > **Two desktop shells, one profile**: the official
 > [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) monorepo ships
-> `apps/desktop` / `apps/desktop-host` (Electron, still in development), and the community
-> [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) does the same — both boot
-> `$DSH_HOME/profiles/desktop`, so the command above works for either. This plugin's desktop support
+> `apps/desktop` / `apps/desktop-host` (Electron), and the community
+> [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) does the same — both boot
+> `$DSH_HOME/profiles/desktop`, so a plugin installed once works in either. This plugin's desktop support
 > targets the **official web + desktop** builds; the community shell's `desktopProfiles` service probe
 > is kept. The official shell's profile process carries **no** dedicated env marker (its
 > `DSH_DESKTOP_NODE_EXECUTABLE` is injected only into its package-install children), so the plugin
@@ -157,6 +164,10 @@ dsh plugin --profile web add https://github.com/NoNameLeGo/dsh-catppuccin-theme
 When installing from git, pnpm may ask you to allow build scripts — follow pnpm's prompt
 and add the package to the profile's `pnpm-workspace.yaml` `allowBuilds`, then run it again.
 
+On desktop, follow the table above instead: the **official shell** takes the Git URL directly in its
+plugin UI, while the **community shell** runs the same command with
+`dsh plugin --profile desktop add …`.
+
 ### dsh-TUI (terminal) themes
 
 The same package covers the TUI. Install it into the dsh-tui profile:
@@ -202,6 +213,11 @@ installing, launch `dsh --profile dsh-tui` and pick the theme with `/theme` —
 4. Choosing **Follow system** reverts to the official theme — it restores the preference
    you had before enabling Catppuccin (light / dark / follow system) instead of forcing a reset.
 
+> **Second entrance**: open this plugin's own card on the **Plugins** page and the middle of
+> its detail page shows the **same settings** (Catppuccin theme / Glass / Check for updates) —
+> both read and write one set of preferences, so either place works. That area comes from the
+> host's plugin detail page (`0.2.0-rc.2` and later); older versions do not have it.
+
 ### Other options in the Catppuccin row
 
 - **Code highlight style**: default / **italic comments** — affects only the shiki colours used
@@ -246,6 +262,12 @@ In **Settings → General**, right below the **Glass** row:
 - Channel policy: stable builds follow the `latest` tag; prereleases follow both `latest`
   and `beta` (the upgrade command automatically carries `@beta`). Offline or network
   failures show the reason and offer a retry.
+- The upgrade path follows the **host**: the **official desktop build** (DeepSeek Harness
+  client) gets no command line — it has no reachable terminal — so this row shows the
+  **`package@channel`** spec and tells you to delete the plugin on the **Plugins** page and
+  reinstall it (the same path as the desktop section above). The **community desktop shell**
+  and **web** keep the copyable `dsh plugin …` command. The host classifies itself
+  (`web` / `community-desktop` / `official-desktop`); you do not pick.
 
 ## Glassmorphism
 
@@ -269,7 +291,7 @@ What this plugin does:
 - **One-click toggle**: off restores the stock UI exactly; uninstalling the plugin leaves
   nothing behind.
 
-### What Compatibility mode matches
+### When Compatibility mode matches the wrong surface
 
 Compatibility mode frosts host and third-party floating surfaces through **class substrings and
 semantic attributes**, needing no cooperation from other plugins — the price is that a substring
@@ -278,54 +300,19 @@ matches are exactly these:
 
 | Family | Anchor |
 |---|---|
-| Composer card | `[data-composer-card]` (the host's own attribute) |
+| Composer card | `[data-composer-card]` (the material is painted on its `::before`, see issue #19) |
 | Menus | `[role='menu']` |
 | Popovers | `[class*='popover']` / `[class*='dropdown']` (still substrings) |
 | Modal dialogs | `[role='dialog'][aria-modal='true']` |
 | Host right sidebar (open state only) | `[data-sidebar-right-panel][data-sidebar-right-open]` |
 
-`0.5.8` narrowed the three widest families out of the sheet on evidence (the `card` substring, the
-`panel` substring and row-level tooltips — see issue #17), but a **new class name in a third-party
-plugin can still be misread**. Defaults only change with evidence, so when you hit one:
-
-**1. Collect evidence** (read-only — paste into the browser console). Lists every element the glass
-rules match, the matched rule text and its computed values:
-
-```js
-(() => {
-  const rules = []
-  for (const ss of document.styleSheets) {
-    let rs; try { rs = ss.cssRules } catch { continue }
-    for (const r of rs) if (r.selectorText && r.selectorText.includes('dsh-glass')) rules.push(r)
-  }
-  const out = []
-  for (const el of document.querySelectorAll('[class*="card"],[class*="panel"],[role="tooltip"]')) {
-    const hit = rules.filter(r => { try { return el.matches(r.selectorText) } catch { return false } })
-    if (!hit.length) continue
-    const cs = getComputedStyle(el), b = el.getBoundingClientRect()
-    if (b.width < 8 || b.height < 8) continue
-    out.push({ cls: String(el.className).slice(0, 48), w: Math.round(b.width), h: Math.round(b.height),
-               bf: cs.backdropFilter, bg: cs.backgroundColor,
-               rule: hit.map(x => x.style.cssText).join(' | ').slice(0, 60) })
-  }
-  console.table(out.slice(0, 40))
-})()
-```
-
-**2. Stop the bleeding locally.** The plugin has **no** "custom CSS" option (DSH's profile patch
-layer can only write plugin `config` — there is no generic style entry point), so this needs an
-external injector: a browser extension (Stylus / Violentmonkey) or DevTools Overrides with an
-`!important` rule, e.g.
-
-```css
-[class*='yourRow'] { backdrop-filter: none !important; background: none !important; outline: none !important; }
-```
-
-**3. Report it.** Paste step 1's output plus your DSH and plugin versions into
-[issues](https://github.com/NoNameLeGo/dsh-catppuccin-theme/issues). That is how `0.5.8` was built:
-the reporter supplied per-element computed values and we narrowed the **defaults** — which is also
-why there is no "custom CSS" option: the default should be right first, an escape hatch is only a
-supplement.
+**A new class name in a third-party plugin can still be misread.** When you hit one, work through three
+steps: **① collect evidence** (a probe snippet you paste into the console, listing every matched element
+and rule) → **② temporary relief** (inject an `!important` override from outside; this plugin
+deliberately ships **no** "custom CSS" option) → **③ report** (attach the evidence plus your DSH and
+plugin versions to [issues](https://github.com/NoNameLeGo/dsh-catppuccin-theme/issues)).
+The full write-up, the probe snippet and the history (#16 / #17 / #19) live in
+[docs/glass-mis-hits.md](docs/glass-mis-hits.md).
 
 ### Environment limit: glass needs a see-through base from the host
 
@@ -393,53 +380,18 @@ The machine-readable form of the above is `dsh.compatibility` (`dsh` / `dshRelea
 ## Development
 
 ```sh
-pnpm install
-pnpm typecheck       # tsc --noEmit: type check for src
-pnpm typecheck:tests # tsc --noEmit: type check for the specs (vitest transpiles, it never type checks)
-pnpm test            # vitest palette-coverage tests
-pnpm build           # tsdown build -> lib/index.js (host) + lib/client.js (browser)
-```
-
-Palettes are produced by a generator script — after editing
-`scripts/generate-palettes.mjs`, rerun:
-
-```sh
-node scripts/generate-palettes.mjs
-```
-
-The changelog draft is generated from your conventional commits (bilingual `EN:` support
-in commit bodies):
-
-```sh
-pnpm changelog:gen            # print the draft since the last tag
-pnpm changelog:gen -- --write # write it into the [Unreleased] section
-```
-
-TypeDoc docs for the public API (`./client`, `./tui-themes` subpath exports) are generated
-locally on demand into `docs/api/` (that directory is **not** committed — it's in
-`.gitignore`; wire up CI Pages publishing later if an online copy is ever wanted):
-
-```sh
-pnpm docs:api
-```
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guide and
-[docs/state-migrations.md](docs/state-migrations.md) for the state versioning contract.
-
-### Local link debugging
-
-Clone the repo, link it into a profile and add it to the bundles (use your own paths;
-`$DSH_HOME` defaults to `~/.dsh`):
-
-```sh
-pnpm --dir ~/.dsh/profiles/web add link:/path/to/dsh-catppuccin
-# Windows example:
-# pnpm --dir C:\Users\<you>\.dsh\profiles\web add link:D:\dev\dsh-catppuccin
+pnpm install          # install dependencies
+pnpm typecheck        # tsc --noEmit for src
+pnpm typecheck:tests  # tsc --noEmit for tests
+pnpm test             # vitest
+pnpm build            # tsdown -> lib/index.js (host) + lib/client.js (browser)
 ```
 
-Then add `@nonamelego/dsh-catppuccin` to the profile's `package.json`
-`dsh.profile.bundles` and restart `dsh web`. For DSH Desktop use
-`~/.dsh/profiles/desktop` instead.
+The palette table is generated by `scripts/generate-palettes.mjs` — **never hand-edit**
+`src/client/palettes.ts`; CHANGELOG drafts come from `pnpm changelog:gen`.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full command list, the generators, typedoc and local
+link debugging; state-contract migration rules are in
+[docs/state-migrations.md](docs/state-migrations.md).
 
 ## 🙋 FAQ
 
@@ -459,8 +411,25 @@ Then add `@nonamelego/dsh-catppuccin` to the profile's `package.json`
   A: Settings → General → **Check Catppuccin plugin updates** compares against npm in one
   click and gives a copyable upgrade command; or run
   `dsh plugin --profile web update @nonamelego/dsh-catppuccin` manually (re-`add` the
-  latest version works too). In [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop),
-  use `desktop` as the profile name, or just run `dsh plugin update` in the app's DSH terminal.
+  latest version works too). **Desktop depends on which shell you use**: the community
+  [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) runs that same command in the app's own
+  DSH terminal (with `desktop` as the profile name), while the **official shell has no upgrade entry
+  point** — **remove the plugin in its plugin UI, then enter the package name
+  `@nonamelego/dsh-catppuccin` again to reinstall**, and restart the app. The two routes are not
+  interchangeable; see the table under Install → Desktop.
+- **Q: "I ran the upgrade but the version did not change (the desktop app still shows the old one)?"**
+  A: Most likely pnpm 11's built-in **minimum release age** (`minimumReleaseAge`, default **24 hours**)
+  silently filtered the fresh release out: `pnpm add` resolves to the **previous** version inside the
+  window (installing `@beta` on release day lands on the previous beta) while the UI keeps showing the
+  target version. Three ways out, pick one:
+  ① **name the exact version** (easiest) — `@nonamelego/dsh-catppuccin@0.5.10-beta.0`; pnpm then records
+  that version in the profile's `minimumReleaseAgeExclude` automatically;
+  ② give this package a **whole-package exemption** in the profile's `pnpm-workspace.yaml` (configure once,
+  every future beta installs immediately): `minimumReleaseAgeExclude:` then a new line with
+  `  - '@nonamelego/dsh-catppuccin'`; ③ wait until the release is 24 hours old.
+  To confirm: check `version` in the profile's
+  `node_modules/@nonamelego/dsh-catppuccin/package.json` and the `specifier:` for that package in
+  `pnpm-lock.yaml`.
 
 ## 💝 Credits
 

package/README.md

@@ -117,25 +117,27 @@ dsh plugin --profile web add @nonamelego/dsh-catppuccin
 装完重启 `dsh web` 即可，`dsh plugin` 会自动把它加进 profile 的 bundles。
 其他 profile 把命令里的 `web` 换成对应名字即可（如 `headless`）。
 
-**桌面版**：桌面端默认激活的 profile 就叫 `desktop`（`$DSH_HOME/profiles/desktop`），
-把命令里的 `web` 换成 `desktop` 即可：
+**桌面版**：官方桌面壳与社区桌面壳都读**同一个 profile** `$DSH_HOME/profiles/desktop`，但
+**两者装/升插件的方式完全不同、也不通用**——按你用的壳选一列：
 
-```sh
-dsh plugin --profile desktop add @nonamelego/dsh-catppuccin
-```
+| | 官方桌面壳（[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 客户端） | 社区桌面壳（[DSH Desktop](https://github.com/anywhere-labs/dsh-desktop)） |
+|---|---|---|
+| **安装** | 应用内的**插件界面** → 添加插件 → 填包名 `@nonamelego/dsh-catppuccin`（也接受 Git 地址 / 压缩包 / 本地路径） | 在打开的 **终端**里执行命令：<br>`dsh plugin --profile desktop add @nonamelego/dsh-catppuccin` |
+| **升级** | **先在插件界面里把插件删除，再重新填一遍同一个包名安装**（v0.2.0 没有升级入口，也没有版本选择器） | 与 web 类似的更新命令：<br>`dsh plugin --profile desktop update @nonamelego/dsh-catppuccin` |
+| 谁执行 pnpm | 应用自带的 pnpm | 应用自带的 pnpm |
 
-在桌面的 **DSH 终端**里运行即可（`dsh plugin` 默认作用于当前激活的 profile，
-若在托盘里选了别的 profile 就换成那个名字），装完**重启桌面应用**生效。
-从仓库安装的方式同理：`dsh plugin --profile desktop add https://github.com/NoNameLeGo/dsh-catppuccin-theme`。
+两种方式改完都要**重启桌面应用**才会加载新版本。
 
-> **两个桌面壳，同一个 profile**：官方 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
-> 仓库里的 `apps/desktop` / `apps/desktop-host`（Electron，仍在开发中）与社区的
-> [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) 都启动
-> `$DSH_HOME/profiles/desktop`，所以**上面的命令对两者都成立**。本插件的桌面支持以
+> ⚠️ **两列别混用**：官方壳的插件界面不执行命令；社区壳那条 `update` 命令对官方壳也不适用。
+> 另外，**系统 PATH 上那个普通 `dsh` 两个壳都管不了 `desktop`**——上游把 `desktop` 当自己保留的
+> profile，会直接报 `error: profile "desktop" is managed exclusively by the Electron application`。
+> 想用 CLI 管就用别的 profile 名（`web`、`headless`、`dsh-tui`）。
+
+> 本插件的桌面支持以
 > **官方 web + 官方 desktop** 为维护核心；社区壳的 `desktopProfiles` 服务探测也保留。
 > 但官方壳的 profile 进程**没有**专用的环境标记（它的 `DSH_DESKTOP_NODE_EXECUTABLE` 只注入给
 > 包安装子进程），所以本插件改为识别 **Electron-as-node 运行时**（`process.versions.electron`）
-> 来判定官方桌面版——升级提示里的 profile 名与文案因此是对的；设置的读写不受影响。
+> 来判定官方桌面版；设置的读写不受影响。
 
 ### 方式二：从仓库安装
 
@@ -146,6 +148,9 @@ dsh plugin --profile web add https://github.com/NoNameLeGo/dsh-catppuccin-theme
 从 git 安装时 pnpm 可能要求允许构建脚本——按 pnpm 的提示把对应包加进 profile
 `pnpm-workspace.yaml` 的 `allowBuilds` 后重跑一次即可。
 
+桌面版同理，但按上面的表走：**官方壳**在插件界面里直接填 Git 地址；**社区壳**把这条命令的
+`dsh plugin --profile web add …` 换成 `dsh plugin --profile desktop add …`。
+
 ### dsh-TUI（终端版）主题
 
 与 Web GUI 插件同一个包。用标准的插件安装命令装进 dsh-tui profile：
@@ -175,13 +180,17 @@ dsh plugin --profile dsh-tui add https://github.com/NoNameLeGo/dsh-catppuccin-th
 
 ## 使用
 
-1. 打开 Web GUI（默认 `http://127.0.0.1:3080`）；在 [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) 中则直接打开桌面应用即可。
+1. 打开 Web GUI（默认 `http://127.0.0.1:3080`）；在 [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) 中则直接打开桌面应用即可。
 2. 进入 **设置 → 常规**。
 3. 在 **外观** 区域下方找到 **Catppuccin** 行，选择主题：
    **Latte**（浅色）、**Frappé**、**Macchiato** 或 **Mocha**（深色）。
 4. 选择 **跟随系统** 则回退到官方主题——会还原你启用 Catppuccin 之前
    的官方偏好（浅色 / 深色 / 跟随系统），而不是强制重置。
 
+> **另一处入口**：在 **插件页**（Plugins）点开本插件自己的卡片，中间会出现**同一组设置**
+> （Catppuccin 主题 / 玻璃质感 / 检查更新）——两处读写的是同一份偏好，改哪边都一样。
+> 该区域由宿主（≥ `0.2.0-rc.2` 的插件详情页）提供，更旧的版本上没有。
+
 ### Catppuccin 行里的其它选项
 
 - **代码高亮风格**：默认 / **注释斜体**（italic-comments）——只影响代码块与 diff 的 shiki 高亮配色。
@@ -224,6 +233,11 @@ dsh plugin --profile dsh-tui add https://github.com/NoNameLeGo/dsh-catppuccin-th
   命令，会提示改用 `git pull` 或重新构建。
 - 通道策略：正式版只跟随 `latest` 标签；预发布版同时跟随 `beta`（升级命令
   自动带 `@beta`）。离线或网络失败时显示原因并可重试。
+- 升级路径按**宿主**分流：**官方桌面版**（DeepSeek Harness 客户端）不给命令行——
+  它没有可达的终端入口，所以这一行改为给出 **`包名@渠道`** 并提示在
+  **插件界面**里先删除、再重新安装（与上面「桌面版」段的升级路径一致）；
+  **社区桌面壳**与 **web** 仍照常给出可复制的 `dsh plugin …` 命令。
+  判定由宿主完成（`web` / `community-desktop` / `official-desktop`），无需你选。
 
 ## 玻璃拟态（Glassmorphism）
 
@@ -244,65 +258,24 @@ dsh plugin --profile dsh-tui add https://github.com/NoNameLeGo/dsh-catppuccin-th
   变色；页面底色取当前主题纯色，背景亮度旋钮直接往纯色里调和白/黑；
 - **一键开关**：关闭即完全还原原生界面，插件卸载不留任何残留。
 
-### 兼容模式会命中哪些面
+### 兼容模式误命中了别的面？
 
-兼容模式靠**类名子串与语义属性**给宿主与第三方插件的悬浮面加玻璃，不需要任何插件配合——
+兼容模式靠**类名子串与语义属性**给宿主与第三方插件的悬浮面加玻璃，不需要插件配合——
 代价是子串匹配**无法区分「面」与「面里的行级容器」**。自 `0.5.8` 起，明确会被命中的族只剩这些：
 
 | 族 | 锚点 |
 |---|---|
-| 输入框卡片 | `[data-composer-card]`（宿主自己的属性；材质画在它的 `::before` 上，见 issue #19） |
+| 输入框卡片 | `[data-composer-card]`（材质画在它的 `::before` 上，见 issue #19） |
 | 菜单 | `[role='menu']` |
-| 弹出层 | `[class*='popover']` / `[class*='dropdown']`（这两个仍是子串） |
+| 弹出层 | `[class*='popover']` / `[class*='dropdown']`（仍是子串） |
 | 模态框 | `[role='dialog'][aria-modal='true']` |
 | 宿主右侧栏（仅展开态） | `[data-sidebar-right-panel][data-sidebar-right-open]` |
 
-`0.5.8` 按证据把最宽的三族收窄掉了（宽泛的 `card` 子串、`panel` 子串、行级 tooltip，详见
-issue #17），但**第三方插件里新出现的类名仍可能被误命中**。默认收窄要讲证据，遇到时走下面三步。
-
-#### 1. 取证（只读，粘进浏览器控制台）
-
-列出当前所有被玻璃规则命中的元素、命中的规则原文与 computed 值：
-
-```js
-(() => {
-  const rules = []
-  for (const ss of document.styleSheets) {
-    let rs; try { rs = ss.cssRules } catch { continue }
-    for (const r of rs) if (r.selectorText && r.selectorText.includes('dsh-glass')) rules.push(r)
-  }
-  const out = []
-  for (const el of document.querySelectorAll('[class*="card"],[class*="panel"],[role="tooltip"]')) {
-    const hit = rules.filter(r => { try { return el.matches(r.selectorText) } catch { return false } })
-    if (!hit.length) continue
-    const cs = getComputedStyle(el), b = el.getBoundingClientRect()
-    if (b.width < 8 || b.height < 8) continue
-    out.push({ cls: String(el.className).slice(0, 48), w: Math.round(b.width), h: Math.round(b.height),
-               bf: cs.backdropFilter, bg: cs.backgroundColor,
-               rule: hit.map(x => x.style.cssText).join(' | ').slice(0, 60) })
-  }
-  console.table(out.slice(0, 40))
-})()
-```
-
-#### 2. 临时止血
-
-本插件**没有**「自定义 CSS」配置项（DSH 的 profile patch 层只能给插件写 `config`，没有通用样式入口；
-但**个别第三方插件自带样式入口**，例如 `dsh-better-sidebar@0.21.1` 的 `customCss`——它 gate 在自身的
-`titleBarScheme: 'custom'` 上、以 `data-dsh-custom-css` 注入，装了这类插件时也可以直接写在它的 `config` 里），
-所以这一步要用外部注入——浏览器扩展（Stylus / 暴力猴）或 DevTools 的 Overrides——加一条
-`!important` 规则把该族还原，例如：
-
-```css
-[class*='yourRow'] { backdrop-filter: none !important; background: none !important; outline: none !important; }
-```
-
-#### 3. 反馈
-
-把第 1 步的表格输出连同 DSH 与插件版本贴到
-[issues](https://github.com/NoNameLeGo/dsh-catppuccin-theme/issues)。`0.5.8` 就是这么修出来的：
-报告人给了逐元素的 computed 对照，我们据此收窄**默认**规则——这也是为什么没有「自定义 CSS」
-配置项：默认行为应该先是对的，配置项只能当补充。
+**第三方插件里新出现的类名仍可能被误命中**。遇到时走三步：**① 只读取证**（一段粘进控制台的探针脚本，
+列出命中的元素与规则）→ **② 临时止血**（外部注入一条 `!important` 还原；本插件**不**提供
+「自定义 CSS」配置项）→ **③ 反馈**（把取证输出连同 DSH 与插件版本提到
+[issues](https://github.com/NoNameLeGo/dsh-catppuccin-theme/issues)）。
+三步的完整说明、探针脚本与历史（#16 / #17 / #19）见 [docs/glass-mis-hits.md](docs/glass-mis-hits.md)。
 
 ### 环境限制：玻璃需要宿主提供可透出的底色
 
@@ -364,51 +337,17 @@ alias 101 / specific 11 / 非三族 1）全覆盖，含 0.2.0 新增的 17 个 a
 ## 开发
 
 ```sh
-pnpm install
-pnpm typecheck       # tsc --noEmit：src 的类型检查
-pnpm typecheck:tests # tsc --noEmit：tests 的类型检查（vitest 跑 esbuild，不做类型检查）
-pnpm test            # vitest 跑配色表 / 契约 / e2e 覆盖测试
-pnpm build           # tsdown 构建 -> lib/index.js（服务端）+ lib/client.js（浏览器）
-```
-
-配色表由生成器脚本产出——修改 `scripts/generate-palettes.mjs` 后重跑
-（`--pin <sha>` 可把上游 commit SHA 写进 `palettes.ts` 头部，见
-`docs/plugin-improvements.md` 的 L 项）：
-
-```sh
-node scripts/generate-palettes.mjs [--pin <upstream-sha>]
-```
-
-CHANGELOG 草稿由 conventional 提交生成（提交正文里的 `EN:` 行会被渲染成英文摘要）：
-
-```sh
-pnpm changelog:gen            # 打印上一 tag 之后的草稿
-pnpm changelog:gen -- --write # 直接写入 [Unreleased] 节
-```
-
-对外 API（`./client`、`./tui-themes` 子路径导出）的 typedoc 文档**按需本地生成**到
-`docs/api/`（该目录不入库、已进 `.gitignore`；哪天真需要在线版本再接 CI 发布）：
-
-```sh
-pnpm docs:api
-```
-
-贡献指南见 [CONTRIBUTING.md](CONTRIBUTING.md)；状态契约的版本迁移约定见
-[docs/state-migrations.md](docs/state-migrations.md)。
-
-### 本地链接调试
-
-克隆到本地后，把包链接进 profile（把路径换成你自己的；`$DSH_HOME` 默认是 `~/.dsh`）：
-
-```sh
-pnpm --dir ~/.dsh/profiles/web add link:/path/to/dsh-catppuccin
-# Windows 例：
-# pnpm --dir C:\Users\<you>\.dsh\profiles\web add link:D:\dev\dsh-catppuccin
+pnpm install          # 装依赖
+pnpm typecheck        # tsc --noEmit：src 的类型检查
+pnpm typecheck:tests  # tsc --noEmit：tests 的类型检查
+pnpm test             # vitest
+pnpm build            # tsdown -> lib/index.js（服务端）+ lib/client.js（浏览器）
 ```
 
-再把 `@nonamelego/dsh-catppuccin` 加进 profile `package.json` 的
-`dsh.profile.bundles`，重启 `dsh web`。DSH Desktop 用
-`~/.dsh/profiles/desktop` 对应路径。
+配色表由 `scripts/generate-palettes.mjs` 生成，**不要手改** `src/client/palettes.ts`；
+CHANGELOG 草稿由 `pnpm changelog:gen` 从 conventional 提交里产出。
+完整命令清单、生成器与 typedoc、本地 link 调试见 [CONTRIBUTING.md](CONTRIBUTING.md)；
+状态契约的版本迁移约定见 [docs/state-migrations.md](docs/state-migrations.md)。
 
 ## 🙋 常见问题
 
@@ -436,9 +375,21 @@ pnpm --dir ~/.dsh/profiles/web add link:/path/to/dsh-catppuccin
   A: 设置 → 常规 → **检查 Catppuccin 插件更新** 一键检测本插件在 npm 上的最新版本，
   发现新版会给出可复制的升级命令；也可以随时手动执行
   `dsh plugin --profile web update @nonamelego/dsh-catppuccin`
-  （或重新 `add` 最新版）。在 [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) 中，把 `web` 换成 `desktop`
-  （`dsh plugin --profile desktop update @nonamelego/dsh-catppuccin`），
-  或者直接在 DSH 终端里运行 `dsh plugin update`（默认作用于当前 profile）。
+  （或重新 `add` 最新版）。
+  **桌面版要分壳**：社区壳 [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) 在应用内的
+  DSH 终端里用同一条命令（把 `web` 换成 `desktop`）；**官方壳没有升级入口**——要在插件界面里
+  **先删掉本插件，再重新填一遍包名 `@nonamelego/dsh-catppuccin` 安装**，然后重启应用。
+  两种方式不通用，详见上面「安装 → 桌面版」的对照表。
+- Q: **_"升级命令跑了，但版本没变（桌面版重启后也还是旧的）？"_**\
+  A: 大概率是 pnpm 11 内置的**最小发布年龄**（`minimumReleaseAge`，默认 **24 小时**）把刚发布的版本
+  静默过滤掉了：`pnpm add` 会解析到**上一个**符合窗口的版本（例如新 beta 发布当天去装 `@beta`，
+  实际装到的仍是上一个 beta），而界面显示的却是目标版本。三条出路，任选其一：
+  ① **指名精确版本**（最省事）——`@nonamelego/dsh-catppuccin@0.5.10-beta.0`，pnpm 会自动把该版本
+  写进当前 profile 的 `minimumReleaseAgeExclude`；② 在当前 profile 的 `pnpm-workspace.yaml` 里
+  给本包**整包豁免**（一次配置，之后每个新 beta 都能立刻装）：
+  `minimumReleaseAgeExclude:` 换行再加 `  - '@nonamelego/dsh-catppuccin'`；③ 等版本发布满 24 小时。
+  判断方法：看 profile 里 `node_modules/@nonamelego/dsh-catppuccin/package.json` 的 `version`,
+  以及 `pnpm-lock.yaml` 里那个包的 `specifier:`。
 
 ## 💝 致谢