dsh-connect 0.8.0 → 0.9.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record with:
 #   git hash-object README.md README.zh.md
-README.md: 60d7d023edd88b0a136a308c90c33967b7a6bb9f
-README.zh.md: 0258195b0c6d92a2bcee8958830a41e9ed4e8bbc
+README.md: 66b5e97ca9fcfabb7c9d9a63d9f7d6c610185c39
+README.zh.md: c3d1f3118d2c4e45c4cea67436df869c1a3f87ac

package/README.md

@@ -11,7 +11,7 @@ The **all-in-one plugin** for connecting [DeepSeek Harness](https://github.com/d
 `dsh-connect` binds a chat conversation to a DSH agent session and drives it end to end:
 
 - **Session binding & routing** — one chat ⇄ one agent session, persisted in a `bindings.json` route store; sessions can be created, resumed, switched, cleared and mirrored to the DSH Web GUI.
-- **Streaming replies** — DSH `assistant/chunk` events are bridged into the channel's native streaming (Feishu typewriter cards): the thinking hint opens the reasoning phase, reasoning streams live with readable paragraph breaks, tool calls appear as `🔧` progress lines, and a liveness heartbeat keeps the card moving even through long silent stretches (long first-token waits, heavy tool runs) so it never sits frozen on "Thinking…".
+- **Streaming replies** — the model's live deltas are bridged into the channel's native streaming (Feishu typewriter cards): the thinking hint opens the reasoning phase, reasoning streams live with readable paragraph breaks, tool calls appear as `🔧` progress lines, and a liveness heartbeat keeps the card moving even through long silent stretches (long first-token waits, heavy tool runs) so it never sits frozen on "Thinking…". The runner keeps two subscriptions, because `0.1.5-rc.2` split what used to be one: the durable `session/event` stream carries turns, tools and settlement, while the transient `agent/assistant-stream` frames carry the deltas — the `assistant/chunk` session event that used to carry both is gone.
 - **Notification levels** — per-chat control over how much of the process is streamed: `尽量输出过程` (full process) / `输出重要节点` (key milestones) / `只输出结果` (result only). Switch any time via the settings menu or `/notify`; the choice is persisted per chat and applies immediately.
 - **Task-end stats** — after every task a compact card reports the model used, input/output tokens, elapsed time and context-window usage, and suggests `/compact` when the context is getting full.
 - **Interactive menus** — button cards for status, tasks, history, goals, schedule, model/effort switching, workspace picking, language, and more (see the in-chat `/` commands).
@@ -25,10 +25,24 @@ The **all-in-one plugin** for connecting [DeepSeek Harness](https://github.com/d
 
 | Aspect | Value |
 |---|---|
-| DSH version | `^0.1.0-rc.6` (peer `@deepseek-ai/dsh-agent`, `dsh-llm`, `dsh-session`) |
+| DSH version | `^0.2.0-rc.2` (peer `@deepseek-ai/dsh-agent`, `dsh-llm`, `dsh-session`) |
 | Cordis | `^4.0.1` |
 | Node.js | ≥ 20 (ESM, `NodeNext`) |
-| Last verified | **2026-08-16** against DSH `0.1.0-rc.6` on Windows (Feishu WebSocket transport) |
+| Last verified | **2026-10-02** against DSH `0.2.0-rc.2` on Windows (host load, Feishu WebSocket transport, web-settings pane) |
+
+**Keep the peer range in step with the host.** Upstream ships no changelog or
+migration guide, so a stale range is the only thing standing between this plugin
+and silent breakage: DSH `0.1.5-rc.2` deleted the `Session.events` accessor and
+the `assistant/chunk` event type outright, and every `dsh-*` package is versioned
+on the same line. When you upgrade DSH, bump `peerDependencies` (and
+`devDependencies`) for `dsh-agent`, `dsh-llm` and `dsh-session` together, re-run
+`tsc`, and re-run the test suite — a range that no longer overlaps the host
+version is the signal that the bridge needs another migration.
+
+DSH refuses to load a plugin whose range does not cover it, so a stale range is
+at least loud: installing `0.9.0` on `0.2.0-rc.2` is rejected with *"may cause
+crashes or data loss"* before anything runs. `0.9.2` is the version that covers
+`0.2.0-rc.2`; see [Upgrading from 0.9.0](#upgrading-from-090).
 
 The plugin runs on the DSH **Host plane** (process-level singleton services), not inside an agent preset.
 
@@ -67,7 +81,7 @@ rm -f ~/.dsh/.dsh-connect/feishu-credentials.json
 ## Quick start
 
 1. **Install the plugins** (see above).
-2. **Add the minimal config** to `~/.dsh/profiles/<profile>/cordis.patch.yml` (also see [`examples/profile-cordis.patch.yml`](../../examples/profile-cordis.patch.yml)). The plugin registers itself via its bundle manifest, so only override its config — do **not** `insert` it again (a duplicate id crashes dsh at boot):
+2. **Add the minimal config** to `~/.dsh/profiles/<profile>/cordis.patch.yml` — the shape is also in [`examples/minimal.config.json`](examples/minimal.config.json), and the fully commented version is [`examples/profile-cordis.patch.yml`](https://github.com/IvanWu2015/dsh-connect/blob/main/examples/profile-cordis.patch.yml) in the repository (that path is outside the published tarball, hence the absolute link). The plugin registers itself via its bundle manifest, so only override its config — do **not** `insert` it again (a duplicate id crashes dsh at boot):
 
    ```yaml
    - id: connect
@@ -87,7 +101,19 @@ rm -f ~/.dsh/.dsh-connect/feishu-credentials.json
 3. **Start the host** — `dsh web` (or `dsh run`). With no credentials configured, the `feishu` channel enters **one-click onboarding**: scan the QR / open the link from the log to authorize the bot.
 4. **Send a message** to the bot in Feishu. The bot replies with a streaming card; `/help` lists all commands; the conversation also appears in the DSH Web GUI automatically (auto-mirror).
 
-A fully reproducible example is the `examples/` folder plus `docs/feishu-setup.md` (Feishu app creation, event subscriptions, publishing).
+A fully reproducible example is the [`examples/`](examples/) folder plus the repository's [Feishu setup manual](https://github.com/IvanWu2015/dsh-connect/blob/main/docs/feishu-setup.md) (Feishu app creation, event subscriptions, publishing).
+
+## Questions and approvals in a conversation
+
+When the agent needs a decision from you it stops and asks, and the asking happens in the chat — no switching to the Web GUI:
+
+- **A question with options** renders as a card with one button per option. One tap answers it and the card immediately moves on to the next question.
+- **A question without options** has no buttons to offer: the bot sends the question as a prompt and you **reply in the chat**. That message is the answer.
+- **A tool approval** (an action that needs your go-ahead) is a card too, with **Allow once** / **Reject** buttons. This one accepts **only a tap** — a plain chat message sent while an approval is waiting is not recorded as its result.
+
+One chat holds one pending card at a time. A second request is handed back to the host's own path (the Web GUI) rather than fighting the first card for the same message — and so is a card that could not be delivered, or a request cancelled before you answered; in each case the chat is **released**, because a leaked pending entry would silently swallow your next message.
+
+"This action is no longer active" means the card has expired — it auto-closes after 60 s idle, so ask again. A double tap, or a tap landing right after the previous question was answered, falls inside the card's redraw window and is ignored silently rather than misreported as expired.
 
 ## Configuration
 
@@ -97,7 +123,7 @@ Configuration lives in the DSH profile patch (`cordis.patch.yml`) under the plug
 
 | Key | Default | Description |
 |---|---|---|
-| `agentPreset` | roster default | Agent preset id composed into each bound session |
+| `agentPreset` | roster default | Agent preset id composed into each bound session. Resolution is best-effort: the configured id is tried, then `standard` (or the roster's first mountable row), and if neither composes the agent is built without a preset so the turn still runs. A stale id therefore degrades instead of failing every message — it is logged, not thrown. |
 | `workDir` | process cwd | Absolute working directory for each bound agent |
 | `workspaces` | `[]` | Extra workspaces offered by the `/dir` picker |
 | `visionModel` | auto-detected | `{ provider, model }` used to describe images when the main model can't see them |
@@ -107,7 +133,7 @@ Configuration lives in the DSH profile patch (`cordis.patch.yml`) under the plug
 | `stateDir` | `.dsh-connect` | Directory holding the `bindings.json` route store (env `DSH_CONNECT_STATE_DIR` overrides) |
 | `autoMirror` | `true` | Automatically create a Web GUI mirror for every new session |
 | `streamHeartbeatMs` | `60000` | Liveness heartbeat interval (ms) for the streaming card; `0` disables it |
-| `notifyLevel` | `important` | Default notification level: `full` (stream everything) / `important` (key milestones) / `result` (answer only); per-chat override via settings menu or `/notify` |
+| `notifyLevel` | `result` | Default notification level: `full` (stream everything) / `important` (key milestones) / `result` (answer only, the default); per-chat override via settings menu or `/notify` |
 | `progressTimeoutMs` | `300000` | Proactive progress-notice interval (ms): when a turn has sent no standalone card/text for this long, a status card reports the latest milestone; `0` disables; per-chat override via settings menu or `/progress` |
 
 ### Shared (all channels)
@@ -116,7 +142,7 @@ Configuration lives in the DSH profile patch (`cordis.patch.yml`) under the plug
 |---|---|---|
 | `channels` | all built-in | Which channels to activate: `feishu` / `telegram` / `dingtalk` / `web`. Omit to activate all built-in channels. |
 | `channelDefaults` | `{}` | Keys applied to every channel that doesn't set its own (e.g. `{ language: "zh" }`). |
-| `settingsStatePath` | — | Optional path for the web-settings pane to persist non-secret config (e.g. `.dsh-connect/settings.json`). |
+| `settingsStatePath` | `<stateDir>/dsh-connect-settings.json` | Where the web-settings pane mirrors non-secret config. Defaults to `dsh-connect-settings.json` *inside* `stateDir`, so it lands beside `bindings.json` and can never disagree with the stores; set it to override. The pane's authoritative store is this plugin's entry in the active profile patch (see [User settings](#user-settings)); this file is only the compatibility mirror the legacy `/dsh-connect` RPC reads and writes, and a pre-0.2 install's copy of it is read back once by the upgrade (see [Upgrading from 0.9.0](#upgrading-from-090)). |
 
 ### `feishu` (Feishu / Lark channel)
 
@@ -176,7 +202,10 @@ Environment variables (`FEISHU_*`, `TELEGRAM_*`, `DINGTALK_*`, `DSH_CONNECT_STAT
 
 - **Files written**
   - `<stateDir>/bindings.json` (default `.dsh-connect/`) — the chat ⇄ session route store (chat keys, session ids, mirror and lock state).
-  - `~/.dsh/.dsh-connect/feishu-credentials.json` — Feishu credentials saved by one-click onboarding.
+  - `<stateDir>/dsh-connect-settings.json` (default `.dsh-connect/`) — the non-secret compatibility mirror, see `settingsStatePath`.
+  - `<profile dir>/.dsh-connect-legacy-imported` — a marker recording that the one-shot upgrade import ran. It sits beside the profile entry the import writes to (see [Upgrading from 0.9.0](#upgrading-from-090)), and its contents are a sentence saying where the settings came from; nothing is stored in it.
+  - this plugin's entry in the active **profile patch** (`profileContext.patchPath`, `cordis.patch.yml`) — written through DSH's first-party `settings` service (atomic, file-locked, comment-preserving).
+  - `~/.dsh/.dsh-connect/feishu-credentials.json` — **legacy**, read-only. One-click onboarding used to save Feishu credentials here instead of the credential store, so a user who had just scanned the QR code still saw `未配置凭据` forever. Onboarding now writes to the credential store, and an existing install is backfilled from this file once on boot; after that it is never read or written again.
   - `<workDir>/.dsh-connect-images/` — user images/attachments staged for the agent's tools.
   - DSH's own session logs and settings under `~/.dsh/` (sessions, settings, etc.).
 - **Network**
@@ -184,20 +213,205 @@ Environment variables (`FEISHU_*`, `TELEGRAM_*`, `DINGTALK_*`, `DSH_CONNECT_STAT
   - LLM provider APIs used by DSH for the agent's model (e.g. DeepSeek), plus the optional vision model.
 - **User data** — message text and attachments flow through the bot to the agent session; they are stored in the DSH session log like any DSH conversation. The allowlists (`allowUsers` / `allowChats`) limit who can drive the bot.
 
+## The settings pane
+
+`dsh-connect` adds its own page under **Settings → dsh-connect**. It is a channel
+tab strip over collapsible cards: each card is headed by a button, its
+low-frequency fields sit behind a second-level **Advanced** fold, and
+Save/status stay pinned to the bottom of the scroll region.
+
+| Channels & credentials | Advanced fields opened |
+|---|---|
+| ![dsh-connect settings pane: the channel tab strip, the Feishu card expanded with its credential fields, and three folded channel cards each showing a credentials badge](docs/images/settings-overview-zh.png) | ![the same pane with a channel's Advanced fold opened, revealing the callback port and path fields](docs/images/settings-advanced-zh.png) |
+
+![the common-defaults card and the pinned save bar at the bottom of the pane](docs/images/settings-defaults-zh.png)
+
+English captures: [overview](docs/images/settings-overview-en.png) · [advanced](docs/images/settings-advanced-en.png) · [defaults](docs/images/settings-defaults-en.png).
+
+> Captured from a throwaway profile whose credentials are all placeholders. Nothing
+> above contains a real secret — and it could not, because the host masks every
+> stored value before it reaches the browser (see [below](#seeing-and-masking-stored-values)).
+
+Cards default to the channels you have enabled (the first one, if none are), and
+clicking a tab opens that card and scrolls it into view *without* closing the
+others — several open at once is a legitimate state. Collapsing a card unmounts
+its body rather than hiding it, which is safe because an unsaved secret you typed
+lives in the pane's own state, not in the card. Ticking a channel's enable box
+opens it too.
+
+## User settings
+
+The web settings pane (`dsh-connect` under **Settings**) edits **this plugin's
+entry in the active profile patch** — the same
+`~/.dsh/profiles/<profile>/cordis.patch.yml` you would edit by hand — through
+DSH's own first-party `settings` service. That service writes atomically under a
+file lock and preserves your comments, and the loader hot-reloads the result, so
+a save takes effect without a restart.
+
+The fields the pane owns are declared `volatile` in the plugin's config schema.
+That declaration is what makes a save *reconcile* instead of remounting: the
+loader hands the plugin a live reference for each declared field, and a settings
+write commits them in place, so the running adapters pick the values up on their
+next message. Fields the pane does not own are simply not declared — which is
+the mechanism that keeps it from writing them.
+
+Values resolve in three layers, most specific last:
+
+1. the schema defaults shipped with the plugin;
+2. the config the plugin is composed with (its inherited entry);
+3. this plugin's entry in the active profile patch — both what you hand-write
+   there and what the pane saves.
+
+A save is projected onto the declared fields only, so an undeclared key — a
+credential, `settingsStatePath`, something you added yourself — cannot reach the
+document even if a caller sends it. The converse is load-bearing too: the host
+resets a declared field that an update *omits* to its inherited value, so a save
+always writes the complete declared section. Undeclared keys you hand-wrote in
+that entry are preserved across a pane save, untouched.
+
+**The pane never writes credentials.** A profile patch is a plain document users
+are invited to paste into bug reports, so a secret you type into the pane goes to
+the DSH credential store (`ctx.credentials`) instead — which is also where
+one-click onboarding and the `FEISHU_*`-style environment variables put them. A
+secret you hand-wrote in the entry yourself is left where it is.
+
+The legacy `/dsh-connect` HTTP RPC is retained for panel compatibility; it now
+reads and writes the same namespace, and mirrors non-secret config to
+`settingsStatePath` (see [Shared](#shared-all-channels)) for older panels.
+
+### Seeing and masking stored values
+
+The pane shows each stored credential as a read-only *current value* line under
+its input (`not configured` when nothing is stored), so you can confirm what you
+configured without retyping it. **The masking happens on the host**, in one shared table
+(`src/settings/secret-disclosure.ts`) that both the host and the pane read — the
+pane only decides whether to render the input as a `password` or a `text` field,
+so the display and the policy cannot drift apart.
+
+| Field | How it is shown |
+|---|---|
+| `appId`, `clientId` | **In full.** These are identifiers, not authenticators: they appear in every outbound API call and in the vendor console, so hiding them protects nothing. |
+| `appSecret`, `clientSecret`, `botToken`, `secret` | Head and tail only — `a1b2…z9y8`. Values too short to survive partial disclosure show a fixed `••••••` instead. |
+| `webhookUrl` (DingTalk) | URL-aware. Origin, path and parameter *names* are kept and only the token's middle is masked, because DingTalk puts the token in the query string — masking the whole URL (`https…bcde`) would confirm nothing. |
+| any other key | Masked by default. |
+
+Two properties hold regardless:
+
+- **No usable secret crosses the wire.** The value is masked before it leaves the
+  host, so a browser tab — or a screenshot of one — never holds one.
+- **A mask can never be written back.** The preview is text *beside* the input,
+  never the input's value. Inputs always start blank; blank means "leave the
+  stored value alone", so saving the config alone writes no credential at all.
+
+The pane's own strings (channel names, field labels, option text, status) all
+come from `client/locale.mjs`, which ships `zh` and `en`. A test asserts both
+languages cover exactly the same key set — the host resolves a missing key by
+silently falling back to the other language, so an untranslated string shows up
+as mixed-language text rather than as an error.
+
+### Credential groups
+
+A channel counts as *configured* when **any one** of its credential groups is
+fully satisfied, and each group is satisfied only when **all** of its refs are
+set — all-of within a group, any-of across groups. A channel with no groups
+(`web`) is configured by definition and never shows a warning badge.
+
+The grouping exists because a channel can have more than one mutually exclusive
+way to authenticate, and requiring all of them would wrongly report a working
+bot as unconfigured:
+
+| Channel | Groups |
+|---|---|
+| `feishu` | app id + app secret |
+| `telegram` | bot token |
+| `dingtalk` | webhook URL + sign secret — *or* — stream client id + client secret |
+| `web` | none |
+
+So a DingTalk bot using only webhook push (no stream credentials) is correctly
+reported as configured, as is one using only stream mode.
+
+## Upgrading from 0.9.0
+
+Applies to the in-repo `0.9.1` as well — it was committed but never published
+to npm, so `0.9.0` is the version users are actually upgrading from.
+
+DSH 0.2 keeps per-plugin settings in the **profile patch**, not in
+`$DSH_HOME/settings.yaml`, and it does not know the old document's `dsh-connect:`
+section — its own migration renames that file and imports the sections it
+recognises, leaving ours to be dropped with a warning. Without help, an
+upgrading user's channels keep working (their config is in the patch) but every
+pane-only choice silently reverts to its default the first time the pane opens.
+
+So **0.9.2 imports it once, on the first boot after the upgrade**:
+
+- It looks for the `dsh-connect:` section in `$DSH_HOME/settings.yaml` first,
+  then in `settings.yaml.imported` (where the host's own migration renames the
+  document, and which may have happened before or after this ran), and finally in
+  this plugin's own `dsh-connect-settings.json` — the fallback store a user who
+  never had a live settings peer would be carrying all their choices in.
+- The section is projected onto the fields the pane owns, so **credentials cannot
+  travel**: they are in the credential store, and anything else in that file
+  stays where it is.
+- It **merges, it does not replace.** The values in force are the base and the
+  legacy values are layered on top, because the host resets a declared field that
+  an update omits — an import carrying only per-channel keys would otherwise
+  clear `channels` and switch every adapter off.
+- It writes through the same path a pane save uses, so the running adapters
+  reconcile immediately — no restart.
+- **Nothing is deleted or renamed.** Unlike the host's own import, ours never
+  writes to `settings.yaml`.
+- The outcome is recorded once in a marker named after the profile entry itself
+  (`profileContext.patchPath`), so it lives at
+  `<profile dir>/.dsh-connect-legacy-imported` — including the benign "there was
+  nothing to import" case, so a later boot cannot re-apply the old values over
+  edits you have made since. The anchor is the entry, not the state file it used
+  to sit beside: the state path is yours to move (`stateDir`,
+  `DSH_CONNECT_STATE_DIR`, `settingsStatePath`) and to delete, and either would
+  have made the next boot believe the import had never run. A profile directory
+  moves only if the profile itself does, which is the one case where re-importing
+  is right.
+
+The retry rule is narrower than "any failure is retried", and deliberately so.
+Three outcomes are final and get the marker: a document that is not there, a
+document with no `dsh-connect:` section, and a successful import. Everything else
+— a document that will not parse, one that is **there but cannot be read**
+(a permission, or a `settings.yaml` that is really a directory), a refused write,
+a host with no settings service — imports nothing, **leaves both files alone, and
+writes no marker**, so the next boot simply tries again once you have fixed the
+cause. That last one is why "not there" and "could not be read" are told apart:
+until `0.9.2` they were the same outcome, so a single unreadable document ended
+the migration for good, silently.
+
+Each of those failures is one `connect: …` line naming the file and the reason;
+the troubleshooting table below lists them. A marker that cannot be **written** is
+reported too — without it every boot would re-run the migration and layer the
+legacy values back over your newer edits. If you never used the pane, none of
+this is visible.
+
 ## Troubleshooting
 
 Logs come from the DSH host logger (run `dsh web` in a terminal); plugin messages are prefixed `connect:` / `connect-feishu:`.
 
 | Symptom | Likely cause / fix |
 |---|---|
+| Installing `dsh-connect@0.9.0` on DSH `0.2.0-rc.2` is refused: *"`dsh-connect@0.9.0` 与 DSH `0.2.0-rc.2` 不兼容 … 运行它可能导致崩溃或数据丢失"* | Not a bug and not a warning to click past: DSH's compatibility gate rejects any plugin whose declared peer range does not cover the running host, and `0.9.0` predates the `0.2.0` line. Install **`0.9.2`** (or newer), whose peers require `^0.2.0-rc.2`. |
 | `connect-feishu: adapter init failed` / `start failed` | Bad credentials, app not published, or network blocked. Check `appId`/`appSecret`, re-run onboarding, verify the bot is online in the Feishu console. |
 | `connect: resume of <id> failed, creating fresh session` | The persisted session could not be resumed (missing workdir, persistence issue). Check `workDir` and `~/.dsh/sessions`. |
+| The bot answers every message with a raw `agent-presets: preset "…" not found` line, and nothing reaches the agent | A stale `agent-presets.default` in `$DSH_HOME/settings.yaml` names an id no installed build ships. Fixed in **0.9.0**, which retries `standard` and logs the decision rather than failing the turn; on an older build, set the key to a shipped id (`standard`). |
 | Session-locked notices | Another client (Feishu or Web) holds the write lock. Use `/unlock` or wait for the lock timeout. |
-| Model switch in the Web GUI appears ignored | Fixed in the current main: the plugin no longer pins a static default model over the Web GUI's session selection. Restart `dsh web` so the rebuilt plugin is loaded. |
+| Model switch in the Web GUI appears ignored | Fixed in **0.9.0**: the plugin no longer pins a static default model over the Web GUI's session selection. Upgrade, then restart `dsh web`. |
 | `[用户发送了图片，但下载失败…]` | Feishu `im:resource` permission is missing on the app; grant it and re-approve. |
-| Streaming reply is one unbroken blob | Fixed in the current main: block boundaries and the reasoning/answer split now insert blank lines (and reasoning soft breaks are expanded for Feishu cards). Restart `dsh web`. |
-| Card frozen on "Thinking…" with no progress on a long task | Fixed in the current main: reasoning now streams live, tool calls show as `🔧` progress lines, and a liveness heartbeat updates the card during silent stretches. Restart `dsh web`. |
-| Menu cards don't update / expire | Cards auto-close after 60 s idle by design; re-open the menu. |
+| Streaming reply is one unbroken blob | Fixed in **0.9.0**: block boundaries and the reasoning/answer split now insert blank lines (and reasoning soft breaks are expanded for Feishu cards). Upgrade, then restart `dsh web`. |
+| Card frozen on "Thinking…" with no progress on a long task | Fixed in **0.9.0**: reasoning now streams live, tool calls show as `🔧` progress lines, and a liveness heartbeat updates the card during silent stretches. Upgrade, then restart `dsh web`. |
+| The agent offers options / asks for tool approval and nothing appears in Feishu | Fixed in **0.9.2** (the in-repo `0.9.1` was never published): the bridge subscribed to a host service that does not exist, so every question fell silently back to the host. Upgrade, then restart `dsh web`. |
+| Tapping a card button says it is no longer active, on a card that was just posted | Fixed in **0.9.2** (the in-repo `0.9.1` was never published): a tap landing while the card was being redrawn (a double tap, or one right after the previous question was answered) was misread as a stale action. Upgrade, then restart `dsh web`. |
+| `connect: the legacy settings at <path> could not be parsed …` | The pre-0.2 document has a YAML error, so the one-shot migration ([Upgrading from 0.9.0](#upgrading-from-090)) skipped it and left it in place. Fix the YAML and restart; nothing is imported until then, and no marker is written, so the retry is automatic. |
+| `connect: could not import the legacy dsh-connect settings from <path> …` | The migration found the section but DSH refused the write (usually a value that fails validation). The section is still in the file — fix the named field and restart. |
+| `connect: could not read the legacy settings candidate at <path> …` | The candidate is *there* but could not be read: a permission, a path that is really a directory, or a `~` in `$DSH_HOME` that was not expanded. This is the one failure that does **not** mark the migration done — nothing is imported, nothing is marked, and the next start retries on its own, so fixing the cause is all that is needed. The distinction from "not there" is the point: the two were the same outcome until 0.9.2, so **a single `EACCES` ended the entire migration silently and permanently**. |
+| `connect: could not write the one-shot import marker at <path> …` | The import itself succeeded; the marker that records it could not be written (usually a read-only home). Not harmless: with no marker every start re-runs the whole migration and layers the legacy values back over whatever you changed in the pane after upgrading — which shows up as settings reverting on their own. Fix the profile directory's write permission, or create the marker file by hand. |
+| `connect: the import marker at <path> could not be read …` | A marker exists but cannot be read. It is treated as **already imported** and reported: better to skip an import than to re-apply old values over your newer settings. Delete the marker and restart to trigger the import again. |
+| Saving the pane fails with *`Configuration for "connect" is overridden by a home patch or command-line overlay`* | The pane writes the profile patch, but resolution layers `bundle → profile → $DSH_HOME/cordis.patch.yml → --patch`, so a value set in one of the last two wins over anything the pane saves and DSH refuses the write rather than let a save that could never take effect look successful. Edit the home patch (or drop the overlay) if you want the pane to own these settings. |
+| Menu cards don't update / expire | Cards auto-close after 60 s idle by design; re-open the menu. Question and approval cards behave the same — see [Questions and approvals in a conversation](#questions-and-approvals-in-a-conversation). |
 
 **Rollback** — reinstall a previous release (`dsh plugin --profile web add dsh-connect@<version>` after removing the current one), or `git checkout` the pinned commit in a source install.
 
@@ -208,11 +422,13 @@ This is a pnpm workspace; `dsh-connect` is the single package under `packages/`:
 ```
 packages/
   connect/          # this package — the all-in-one plugin
-    src/            # core: runner, service, binding, commands, i18n, menus …
+    src/            # core: runner, service, binding, commands, menus, chat keys …
     src/channels/   # channel adapters: feishu / telegram / dingtalk / web
-    src/settings/   # web-settings stack: host RPC, credential store, settings service/pane
+    src/settings/   # web-settings stack: host RPC, credential store, disclosure policy
+    client/         # web-settings frontend plugin + its pure, testable modules
     test/           # node:test suites (run-all.mjs imports every suite)
-    client/         # web-settings frontend plugin
+    docs/images/    # screenshots used by this README
+    examples/       # minimal.config.json
 ```
 
 ```sh
@@ -228,9 +444,11 @@ pnpm test
 node packages/connect/test/unit.test.mjs
 ```
 
-**Structure** — `src/runner.ts` owns the per-chat agent driver and the streaming bridge (`applyStreamChunk` is the pure, unit-tested chunk assembler); `src/service.ts` owns the adapter registry and routing; `src/channels/` holds the feishu / telegram / dingtalk / web channel adapters; `src/settings/` holds the web-settings stack (host RPC, credential store, settings service); `src/i18n.ts` holds the `zh`/`en` dictionaries (keep keys in sync across both); `src/binding.ts` is the route store.
+**Structure** — `src/runner.ts` owns the per-chat agent driver and the streaming bridge (`applyStreamChunk` is the pure, unit-tested chunk assembler); `src/service.ts` owns the adapter registry and routing; `src/channels/` holds the feishu / telegram / dingtalk / web channel adapters; `src/settings/` holds the web-settings stack (host RPC, credential store, disclosure policy); `src/binding.ts` is the route store.
+
+Two things that used to live in `src/` moved to `client/` so they could be unit-tested without React: **`client/locale.mjs`** holds every user-visible pane string in `zh` and `en` (keep the key sets identical — the host resolves a missing key by silently rendering the *other* language, so an untranslated string shows up as half-English text, not as an error), and **`client/panel-state.mjs`** holds the card open/advanced rules. Both are plain ESM with no dependencies and are asserted directly in `test/locale.test.mjs` / `test/panel-state.test.mjs`.
 
-**Contributing** — PRs welcome at [github.com/IvanWu2015/dsh-connect](https://github.com/IvanWu2015/dsh-connect). For user-facing strings, add the key to both `zh` and `en` in `src/i18n.ts`. Release notes live in `CHANGELOG.md`; see `docs/PUBLISHING.md` for the release flow.
+**Contributing** — PRs welcome at [github.com/IvanWu2015/dsh-connect](https://github.com/IvanWu2015/dsh-connect). For user-facing pane strings, add the key to both `zh` and `en` in `client/locale.mjs`, then rebuild the bundle (`node scripts/build-client.mjs`) — `test/client-bundle.test.mjs` runs the **built** artifact and fails if it is stale. Release notes live in `CHANGELOG.md`; see [`docs/PUBLISHING.md`](https://github.com/IvanWu2015/dsh-connect/blob/main/docs/PUBLISHING.md) for the release flow.
 
 ## License & security