dsh-wsl-workspace 0.4.2 → 0.4.3

package/TESTING.md

@@ -1,109 +1,109 @@
-# Testing
-
-This document describes how to verify `dsh-wsl-workspace` after a change or before a release. The suite covers unit tests, the preset-materialization integration test, a real-WSL smoke test, and a post-build lib verification gate.
-
-## Prerequisites
-
-- Windows host with WSL2 and at least one distribution installed (`wsl.exe` on `PATH`).
-- Node.js 24+ (the tests run with Node's built-in TypeScript support; `tsx` is not required).
-- The DeepSeek Harness checkout (for `tsc`/`tsdown` and the `@deepseek-ai/*` type declarations the `tsconfig.json` paths point at).
-
-## Unit tests
-
-Run the unit tests from the plugin directory:
-
-```powershell
-node --experimental-strip-types --test tests/variants.test.ts tests/fs-execution-context.test.ts tests/shell.test.ts tests/paths.test.ts tests/wsl-skills.test.ts
-```
-
-Coverage:
-
-| File | What it verifies |
-|---|---|
-| `tests/variants.test.ts` | The WSL preset-variant transform: world rows are dropped, the WSL realm is injected, `str-replace-editor` is re-injected exactly once (and only when the source references it), prefab-family rows (`custom-bash`, `bootstrap-filesystem`) are removed, unknown rows are preserved verbatim. |
-| `tests/fs-execution-context.test.ts` | `WslFileSystem` inherits the calling session's cwd through `AsyncLocalStorage` on `tools/execute`; agentless calls fall back to the configured distro. |
-| `tests/shell.test.ts` | The login-shell `cd` prefix preserves the resolved workdir (including single-quote escaping); non-login shells leave the command unchanged. |
-| `tests/paths.test.ts` | UNC ↔ Linux path translation, `/mnt/<drive>` mapping, canonical Windows path keys, WSL username validation. |
-| `tests/wsl-skills.test.ts` | The WSL skill provider (issue #10): non-WSL lookups return nothing, nested `.dsh/skills` / `.agents/skills` discovery with host ranks/sources, `get()` body loading, pruning of `node_modules` / dot-directories, frontmatter validation **including block scalars**, depth and skill-root budgets, the nearest-`.git`-ancestor rule (a cwd deeper than the project root still sees the project's skills, and skills above that ancestor do not leak), the skill-root cap, the **10-second per-scan-root lookup cache** (copy semantics, TTL expiry, `get()` staying live), **directory-symlink following** (linked projects discovered, aliasing deduplicated, dangling symlinks pruned, hops bounded by depth). |
-
-## Provider parity and compatibility checks
-
-- `node scripts/check-rank-parity.mjs` — the provider's project ranks are copied from `@deepseek-ai/dsh-skill-filesystem` (the host does not export them). This script parses the host's built lib when the package is resolvable on this machine and fails on drift. Run it before every release on a machine with the harness installed.
-- `scripts/verify-dsh-compat.sh <version>...` — disposable-Profile install/start/uninstall evidence against specific `@deepseek-ai/dsh` releases: fully isolated (`DSH_HOME` redirected to a temp tree, own port), boots the published harness version with the plugin added by name, probes `POST /wsl-workspace/api`, then removes the plugin and verifies the route disappears. Emits per-version verdict lines used for the `dsh.compatibility.dshReleases` manifest records.
-
-## Preset materialization integration test
-
-Boots the host plugin's `apply()` against a fake context with `DSH_HOME` pointed at a temp directory, then asserts the generated variant rows reference real built lib files and the composition carries the WSL execution-world realm:
-
-```powershell
-node tests/host-materialize.mjs
-```
-
-This covers variant generation, opaque source-directory mirroring (third-party assets travel with the variant), atomic publication (a failed regeneration preserves the previous complete variant), stale-variant cleanup, and legacy `wsl` preset removal.
-
-## Real-WSL smoke test
-
-Requires a running WSL distribution (the first listed distro is used; infrastructure distros such as `docker-desktop` are skipped):
-
-```powershell
-node --experimental-strip-types tests/smoke.ts
-```
-
-This exercises the filesystem round-trip (resolve/write/read/edit/stat/version/listDir/contains/fileUrl), bash execution inside WSL (cwd translation, WSLENV pass-through, stdin, background jobs), Linux-workdir resolution through the session distro fact, `/mnt/<drive>` dual access, and the no-config default-distro fallback.
-
-## Post-build lib verification
-
-`scripts/verify-lib.mjs` parses every `lib/*.js` entry and fails the build when a bare call to a Node builtin export has no matching `node:*` import. This catches the class of bug where a symbol is used but never imported (for example `statSync` in 0.2.3, which made the Add-WSL-Workspace dialog report every path as non-existent at runtime):
-
-```powershell
-node scripts/verify-lib.mjs
-```
-
-The `build` script chains it after `tsdown`:
-
-```powershell
-pnpm build   # tsdown && node scripts/verify-lib.mjs
-```
-
-## Nested skill-catalog regression (issue #10)
-
-The WSL skill provider publishes `.dsh/skills` / `.agents/skills` from nested projects below a WSL workspace (and from the cwd's nearest `.git` ancestor). Regression-test it on the real 9P share:
-
-1. Rebuild the repro tree inside the distribution (`scripts/repro-setup.sh` creates `~/repro-ws-root` with nested projects, pruned traps, and an over-budget deep skill):
-
-   ```powershell
-   cp scripts/repro-setup.sh //wsl.localhost/<distro>/tmp/
-   wsl -d <distro> -- bash -c "bash /tmp/repro-setup.sh"
-   ```
-
-2. Drive the provider against the real `\\wsl.localhost` share — four assertions print (workspace-root cwd finds root + nested skills; nested-project cwd finds only that project; `get()` loads a body; non-WSL cwd returns nothing). Override the target with `WSL_COMPAT_DISTRO` / `WSL_COMPAT_USER` / `WSL_COMPAT_ROOT`:
-
-   ```powershell
-   node scripts/repro-e2e.mjs
-   ```
-
-   The script hardcodes `\\wsl.localhost\Ubuntu\home\mille\repro-ws-root`; adjust the two paths at the top when running as another user or distro.
-3. In the running harness, open a session on the repro workspace and ask the agent to load the nested skills (`brainstorming`, `systematic-debugging`, `writing-plans`) through its skill tool — each must load with the `wsl-workspace` provider attribution, and no duplicate entries may appear. In a non-WSL workspace session the same skills must be "unknown".
-4. Clean-install check (simulates another user): `npm pack`, `npm install <tarball>` in an empty temp project (peers must resolve), then `dsh plugin --profile web add <extracted tarball dir>`, restart `dsh web`, and repeat the end-to-end checks below plus the nested-skill probe above.
-
-## End-to-end verification in the running harness
-
-After installing the plugin into a profile and restarting `dsh web`:
-
-1. The **W** button appears beside Settings at the sidebar foot.
-2. Open "Add WSL workspace…", browse to a directory (e.g. `/home`), and click "Create & open" — the workspace must be created without a "path does not exist" error.
-3. In the new session, the mode picker shows the WSL variant (e.g. `WSL · Standard mode（标准模式）`); the bash tool runs inside the distribution (`pwd` returns a Linux path, `uname -s` returns `Linux`).
-4. `read`/`write`/`edit` operate on WSL files; Windows files stay reachable under `/mnt/<drive>`.
-5. Switch modes (Standard / PTC / Minimal / Creative) — each lands on its WSL variant and the tool catalog matches the mode.
-6. The plugin API responds correctly: `POST /wsl-workspace/api` with `{"method":"check","params":{"distro":"<distro>","path":"/home"}}` returns `{"ok":true,"value":{"exists":true,"isDirectory":true}}`.
-
-## Release checklist
-
-1. `pnpm build` — rebuilds `lib/` and runs the verification gate.
-2. `node --experimental-strip-types --test tests/variants.test.ts tests/fs-execution-context.test.ts tests/shell.test.ts tests/paths.test.ts tests/wsl-skills.test.ts` — all green.
-3. `node tests/host-materialize.mjs` — all assertions pass.
-4. `node --experimental-strip-types tests/smoke.ts` — real-WSL round-trip passes.
-5. `node scripts/check-rank-parity.mjs` — host rank constants still match our copies.
-6. `node scripts/repro-e2e.mjs` (after `scripts/repro-setup.sh`) — nested skill-catalog assertions pass.
-7. `npm pack --dry-run` — confirm the tarball carries only live `lib/` chunks, `src/`, `cordis.patch.yml`, READMEs, `LICENSE`, and `NOTICE` (tsdown uses `clean: false`, so remove stale chunks from `lib/` before packing).
+# Testing
+
+This document describes how to verify `dsh-wsl-workspace` after a change or before a release. The suite covers unit tests, the preset-materialization integration test, a real-WSL smoke test, and a post-build lib verification gate.
+
+## Prerequisites
+
+- Windows host with WSL2 and at least one distribution installed (`wsl.exe` on `PATH`).
+- Node.js 24+ (the tests run with Node's built-in TypeScript support; `tsx` is not required).
+- The DeepSeek Harness checkout (for `tsc`/`tsdown` and the `@deepseek-ai/*` type declarations the `tsconfig.json` paths point at).
+
+## Unit tests
+
+Run the unit tests from the plugin directory:
+
+```powershell
+node --experimental-strip-types --test tests/variants.test.ts tests/fs-execution-context.test.ts tests/shell.test.ts tests/paths.test.ts tests/wsl-skills.test.ts
+```
+
+Coverage:
+
+| File | What it verifies |
+|---|---|
+| `tests/variants.test.ts` | The WSL preset-variant transform: world rows are dropped, the WSL realm is injected, `str-replace-editor` is re-injected exactly once (and only when the source references it), prefab-family rows (`custom-bash`, `bootstrap-filesystem`) are removed, unknown rows are preserved verbatim. |
+| `tests/fs-execution-context.test.ts` | `WslFileSystem` inherits the calling session's cwd through `AsyncLocalStorage` on `tools/execute`; agentless calls fall back to the configured distro. |
+| `tests/shell.test.ts` | The login-shell `cd` prefix preserves the resolved workdir (including single-quote escaping); non-login shells leave the command unchanged. |
+| `tests/paths.test.ts` | UNC ↔ Linux path translation, `/mnt/<drive>` mapping, canonical Windows path keys, WSL username validation. |
+| `tests/wsl-skills.test.ts` | The WSL skill provider (issue #10): non-WSL lookups return nothing, nested `.dsh/skills` / `.agents/skills` discovery with host ranks/sources, `get()` body loading, pruning of `node_modules` / dot-directories, frontmatter validation **including block scalars**, depth and skill-root budgets, the nearest-`.git`-ancestor rule (a cwd deeper than the project root still sees the project's skills, and skills above that ancestor do not leak), the skill-root cap, the **10-second per-scan-root lookup cache** (copy semantics, TTL expiry, `get()` staying live), **directory-symlink following** (linked projects discovered, aliasing deduplicated, dangling symlinks pruned, hops bounded by depth). |
+
+## Provider parity and compatibility checks
+
+- `node scripts/check-rank-parity.mjs` — the provider's project ranks are copied from `@deepseek-ai/dsh-skill-filesystem` (the host does not export them). This script parses the host's built lib when the package is resolvable on this machine and fails on drift. Run it before every release on a machine with the harness installed.
+- `scripts/verify-dsh-compat.sh <version>...` — disposable-Profile install/start/uninstall evidence against specific `@deepseek-ai/dsh` releases: fully isolated (`DSH_HOME` redirected to a temp tree, own port), boots the published harness version with the plugin added by name, probes `POST /wsl-workspace/api`, then removes the plugin and verifies the route disappears. Emits per-version verdict lines used for the `dsh.compatibility.dshReleases` manifest records.
+
+## Preset materialization integration test
+
+Boots the host plugin's `apply()` against a fake context with `DSH_HOME` pointed at a temp directory, then asserts the generated variant rows reference real built lib files and the composition carries the WSL execution-world realm:
+
+```powershell
+node tests/host-materialize.mjs
+```
+
+This covers variant generation, opaque source-directory mirroring (third-party assets travel with the variant), atomic publication (a failed regeneration preserves the previous complete variant), stale-variant cleanup, and legacy `wsl` preset removal.
+
+## Real-WSL smoke test
+
+Requires a running WSL distribution (the first listed distro is used; infrastructure distros such as `docker-desktop` are skipped):
+
+```powershell
+node --experimental-strip-types tests/smoke.ts
+```
+
+This exercises the filesystem round-trip (resolve/write/read/edit/stat/version/listDir/contains/fileUrl), bash execution inside WSL (cwd translation, WSLENV pass-through, stdin, background jobs), Linux-workdir resolution through the session distro fact, `/mnt/<drive>` dual access, and the no-config default-distro fallback.
+
+## Post-build lib verification
+
+`scripts/verify-lib.mjs` parses every `lib/*.js` entry and fails the build when a bare call to a Node builtin export has no matching `node:*` import. This catches the class of bug where a symbol is used but never imported (for example `statSync` in 0.2.3, which made the Add-WSL-Workspace dialog report every path as non-existent at runtime):
+
+```powershell
+node scripts/verify-lib.mjs
+```
+
+The `build` script chains it after `tsdown`:
+
+```powershell
+pnpm build   # tsdown && node scripts/verify-lib.mjs
+```
+
+## Nested skill-catalog regression (issue #10)
+
+The WSL skill provider publishes `.dsh/skills` / `.agents/skills` from nested projects below a WSL workspace (and from the cwd's nearest `.git` ancestor). Regression-test it on the real 9P share:
+
+1. Rebuild the repro tree inside the distribution (`scripts/repro-setup.sh` creates `~/repro-ws-root` with nested projects, pruned traps, and an over-budget deep skill):
+
+   ```powershell
+   cp scripts/repro-setup.sh //wsl.localhost/<distro>/tmp/
+   wsl -d <distro> -- bash -c "bash /tmp/repro-setup.sh"
+   ```
+
+2. Drive the provider against the real `\\wsl.localhost` share — four assertions print (workspace-root cwd finds root + nested skills; nested-project cwd finds only that project; `get()` loads a body; non-WSL cwd returns nothing). Override the target with `WSL_COMPAT_DISTRO` / `WSL_COMPAT_USER` / `WSL_COMPAT_ROOT`:
+
+   ```powershell
+   node scripts/repro-e2e.mjs
+   ```
+
+   The script hardcodes `\\wsl.localhost\Ubuntu\home\mille\repro-ws-root`; adjust the two paths at the top when running as another user or distro.
+3. In the running harness, open a session on the repro workspace and ask the agent to load the nested skills (`brainstorming`, `systematic-debugging`, `writing-plans`) through its skill tool — each must load with the `wsl-workspace` provider attribution, and no duplicate entries may appear. In a non-WSL workspace session the same skills must be "unknown".
+4. Clean-install check (simulates another user): `npm pack`, `npm install <tarball>` in an empty temp project (peers must resolve), then `dsh plugin --profile web add <extracted tarball dir>`, restart `dsh web`, and repeat the end-to-end checks below plus the nested-skill probe above.
+
+## End-to-end verification in the running harness
+
+After installing the plugin into a profile and restarting `dsh web`:
+
+1. The **W** button appears beside Settings at the sidebar foot.
+2. Open "Add WSL workspace…", browse to a directory (e.g. `/home`), and click "Create & open" — the workspace must be created without a "path does not exist" error.
+3. In the new session, the mode picker shows the WSL variant (e.g. `WSL · Standard mode（标准模式）`); the bash tool runs inside the distribution (`pwd` returns a Linux path, `uname -s` returns `Linux`).
+4. `read`/`write`/`edit` operate on WSL files; Windows files stay reachable under `/mnt/<drive>`.
+5. Switch modes (Standard / PTC / Minimal / Creative) — each lands on its WSL variant and the tool catalog matches the mode.
+6. The plugin API responds correctly: `POST /wsl-workspace/api` with `{"method":"check","params":{"distro":"<distro>","path":"/home"}}` returns `{"ok":true,"value":{"exists":true,"isDirectory":true}}`.
+
+## Release checklist
+
+1. `pnpm build` — rebuilds `lib/` and runs the verification gate.
+2. `node --experimental-strip-types --test tests/variants.test.ts tests/fs-execution-context.test.ts tests/shell.test.ts tests/paths.test.ts tests/wsl-skills.test.ts` — all green.
+3. `node tests/host-materialize.mjs` — all assertions pass.
+4. `node --experimental-strip-types tests/smoke.ts` — real-WSL round-trip passes.
+5. `node scripts/check-rank-parity.mjs` — host rank constants still match our copies.
+6. `node scripts/repro-e2e.mjs` (after `scripts/repro-setup.sh`) — nested skill-catalog assertions pass.
+7. `npm pack --dry-run` — confirm the tarball carries only live `lib/` chunks, `src/`, `cordis.patch.yml`, READMEs, `LICENSE`, and `NOTICE` (tsdown uses `clean: false`, so remove stale chunks from `lib/` before packing).
 8. Install the tarball into a clean profile (`dsh plugin --profile web add <tarball>`), restart `dsh web`, and run the end-to-end checks above plus the nested-skill probe. When the compatibility manifest changes, also run `scripts/verify-dsh-compat.sh` for every declared release.

package/lib/client.js

@@ -131,6 +131,14 @@ async function registerWindows(linuxPath, distro, username) {
 async function listWorkspaces() {
 	return call("listWorkspaces", {});
 }
+/**
+* Read the plugin build version and its declared DSH compatibility matrix,
+* for the dialog help panel.
+* @returns the self-description reported by the host plugin.
+*/
+async function describe() {
+	return call("describe", {});
+}
 
 //#endregion
 //#region src/shared/paths.ts
@@ -246,6 +254,92 @@ function isValidWslUsername(value) {
 	return WSL_USERNAME_PATTERN.test(value);
 }
 
+//#endregion
+//#region src/client/help.tsx
+/**
+* Split one dictionary entry into its bullet lines.
+* @param value - the multi-line dictionary string.
+* @returns the non-empty lines, trimmed.
+*/
+function bullets(value) {
+	return value.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+}
+/** One titled section of the panel. */
+function Section({ title, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
+		className: "dww-help-section",
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
+			className: "dww-help-title",
+			children: title
+		}), children]
+	});
+}
+/**
+* Render the help panel shown behind the dialog's "?" button.
+* @param props - translate function plus the host's self-description.
+*/
+function WslHelp({ t, description }) {
+	const releases = description?.releases ?? [];
+	const version = description === null ? t("help.compat.unknown") : `${t("help.compat.versionLabel")} v${description.version}`;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: "dww-help",
+		role: "region",
+		"aria-label": t("help.button"),
+		children: [
+			/* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Section, {
+				title: t("help.compat.title"),
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "dww-help-meta",
+						children: version
+					}),
+					releases.length > 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "dww-help-chips",
+						children: releases.map((entry) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "dww-help-chip",
+							children: entry.id
+						}, entry.id))
+					}) : null,
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+						className: "dww-help-list",
+						children: bullets(t("help.compat.body")).map((line) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: line }, line))
+					})
+				]
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Section, {
+				title: t("help.usage.title"),
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+					className: "dww-help-list",
+					children: bullets(t("help.usage.body")).map((line) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: line }, line))
+				})
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Section, {
+				title: t("help.known.title"),
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+					className: "dww-help-list dww-help-list--known",
+					children: bullets(t("help.known.body")).map((line) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: line }, line))
+				})
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "dww-help-footer",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+					className: "dww-help-link",
+					href: "https://www.npmjs.com/package/dsh-wsl-workspace",
+					target: "_blank",
+					rel: "noreferrer",
+					children: t("help.footer.npm")
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+					className: "dww-help-link",
+					href: "https://github.com/6Mikao9/dsh-wsl-workspace",
+					target: "_blank",
+					rel: "noreferrer",
+					children: t("help.footer.repo")
+				})]
+			})
+		]
+	});
+}
+
 //#endregion
 //#region src/client/AddWslWorkspace.tsx
 /**
@@ -296,7 +390,7 @@ function WslGlyph({ size = 16 }) {
 * The "Add WSL workspace…" footer action and its dialog.
 * @param props - owner share + injected face.
 */
-function AddWslWorkspace({ wide, t, checkPreset, listDistros: listDistros$1, listDir: listDir$1, check: check$1, createWorkspace }) {
+function AddWslWorkspace({ wide, t, describe: describe$1, checkPreset, listDistros: listDistros$1, listDir: listDir$1, check: check$1, createWorkspace }) {
 	const [open, setOpen] = (0, react.useState)(false);
 	const [opening, setOpening] = (0, react.useState)(false);
 	const [distros, setDistros] = (0, react.useState)([]);
@@ -308,6 +402,8 @@ function AddWslWorkspace({ wide, t, checkPreset, listDistros: listDistros$1, lis
 	const [browsing, setBrowsing] = (0, react.useState)(false);
 	const [error, setError] = (0, react.useState)(null);
 	const [busy, setBusy] = (0, react.useState)(false);
+	const [helpOpen, setHelpOpen] = (0, react.useState)(false);
+	const [selfDescription, setSelfDescription] = (0, react.useState)(null);
 	const browseSeq = (0, react.useRef)(0);
 	const refreshBrowse = async (root, targetDistro) => {
 		const seq = ++browseSeq.current;
@@ -329,6 +425,11 @@ function AddWslWorkspace({ wide, t, checkPreset, listDistros: listDistros$1, lis
 		if (!open) return;
 		let cancelled = false;
 		setError(null);
+		describe$1().then((value) => {
+			if (!cancelled) setSelfDescription(value);
+		}).catch(() => {
+			if (!cancelled) setSelfDescription(null);
+		});
 		setOpening(true);
 		(async () => {
 			let presetIssue;
@@ -467,20 +568,35 @@ function AddWslWorkspace({ wide, t, checkPreset, listDistros: listDistros$1, lis
 			children: [
 				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 					className: "dww-header",
-					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h2", {
-						className: "dww-title",
-						children: t("dialog.title")
-					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-						type: "button",
-						className: "dww-close",
-						"aria-label": t("dialog.cancel"),
-						onClick: maskClick,
-						children: "✕"
-					})]
+					children: [
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h2", {
+							className: "dww-title",
+							children: t("dialog.title")
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							className: "dww-help-btn",
+							title: t("help.button"),
+							"aria-label": t("help.button"),
+							"aria-pressed": helpOpen,
+							onClick: () => setHelpOpen((value) => !value),
+							children: "?"
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							className: "dww-close",
+							"aria-label": t("dialog.cancel"),
+							onClick: maskClick,
+							children: "✕"
+						})
+					]
 				}),
-				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 					className: "dww-body",
-					children: [
+					children: helpOpen ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(WslHelp, {
+						t,
+						description: selfDescription
+					}) : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
 						error !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 							className: "dww-error",
 							children: [error, /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
@@ -579,7 +695,7 @@ function AddWslWorkspace({ wide, t, checkPreset, listDistros: listDistros$1, lis
 								}, name))]
 							})]
 						})
-					]
+					] })
 				}),
 				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 					className: "dww-actions",
@@ -870,6 +986,71 @@ const STYLES = `
 }
 .dww-btn--primary:hover:not(:disabled) { background: var(--dsw-alias-button-primary-hover); }
 .dww-btn:disabled { cursor: default; opacity: 0.6; }
+/* Help panel behind the dialog's "?" button. */
+.dww-help-btn {
+  flex: none;
+  margin-left: auto;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 50%;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+  font-size: 13px;
+  line-height: 1;
+}
+.dww-help-btn:hover { background: var(--dsw-alias-interactive-bg-hover); }
+.dww-help-btn[aria-pressed='true'] {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-primary);
+}
+.dww-help {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  max-height: 52vh;
+  overflow-y: auto;
+  padding-right: 4px;
+}
+.dww-help-section { display: flex; flex-direction: column; gap: 6px; }
+.dww-help-title {
+  margin: 0;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary);
+}
+.dww-help-meta { font-size: 12px; color: var(--dsw-alias-label-tertiary); }
+.dww-help-chips { display: flex; flex-wrap: wrap; gap: 6px; }
+.dww-help-chip {
+  padding: 2px 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 999px;
+  font-size: 12px;
+  color: var(--dsw-alias-label-secondary);
+}
+.dww-help-list {
+  margin: 0;
+  padding-left: 18px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--dsw-alias-label-secondary);
+}
+.dww-help-list--known { color: var(--dsw-alias-label-primary); }
+.dww-help-footer {
+  display: flex;
+  gap: 14px;
+  padding-top: 8px;
+  border-top: 1px solid var(--dsw-alias-border-l2);
+}
+.dww-help-link { font-size: 12px; color: var(--dsw-alias-label-tertiary); text-decoration: underline; }
+.dww-help-link:hover { color: var(--dsw-alias-label-primary); }
 `;
 /**
 * Idempotently inject the plugin stylesheet. No-op when a tag with the
@@ -917,7 +1098,18 @@ const zh = {
 	"error.invalidPath": "请输入以 / 开头的 Linux 绝对路径",
 	"error.invalidUsername": "用户名无效：需以字母或下划线开头，仅含字母、数字、_、.、-",
 	"error.pathNotFound": "该路径不存在或是文件，请选择一个文件夹",
-	"error.createFailed": "创建工作区失败"
+	"error.createFailed": "创建工作区失败",
+	"help.button": "插件说明",
+	"help.compat.title": "兼容性",
+	"help.compat.versionLabel": "插件版本",
+	"help.compat.unknown": "未能读取版本与兼容声明（宿主端没有响应）",
+	"help.compat.body": "上方是这份构建声明兼容的 DSH 版本，每一条都在隔离实例上实测过（独立 DSH_HOME、依赖固定到该版本、跑满十项门禁）。\n插件在运行时会识别 DSH 版本：0.1.2 线用 uiWorkspace + remote.agentPresets，更早的版本用 workspaces.startSession + connection.api；两边都没有时会明确报错，而不是留下一个空工作区。\n版本不在列表里通常仍然可用，但未经验证。",
+	"help.usage.title": "用法与特性",
+	"help.usage.body": "点击侧边栏底部的 W 按钮 → 选发行版 → 输入或浏览 Linux 路径 → 检查 → 创建并打开。\n创建出的会话里，bash 与文件工具都落在该发行版内，模型看到的路径全是 Linux 路径；Windows 盘可从会话内通过 /mnt/<盘符> 访问。\n四种模式（标准 / PTC / 极简 / 创造）各有 WSL 变体，在模式选择器里直接选即可，名字形如 WSL · Standard mode（标准模式）。\n用户名可选，等价于 wsl.exe -u <用户名>，只改变 bash 的运行身份；文件工具走 Windows 侧共享，不受它影响。\n技能目录从会话 cwd 最近的 .git 祖先开始向下扫描 .dsh/skills 与 .agents/skills（含嵌套项目），上限 4 层目录 / 64 个技能目录 / 4096 个已访问目录，并按扫描根缓存 10 秒。\n为了让 UNC 工作区也能拿到目录，插件生成预设时会把技能行的 watch 关掉，目录改由会话启动时扫描一次：会话中途新加入的技能要等下一个会话才出现，而技能内容（get）始终是实时读取的。\nbash 在发行版内运行，不受 DSH 文件策略约束；文件工具（read/write/edit）受策略约束，工作区内修改模式下只能写工作区内。",
+	"help.known.title": "已知问题",
+	"help.known.body": "Windows 侧共享无法解析 Linux 符号链接：用 ln -s 链进工作区的项目发现不了（扫描会跳过、不报错），请把工作区注册在真实项目目录所在的层级。\n会话运行中途新加入的技能不会即时出现在目录里（因为对 UNC 关闭了文件监视，见「用法与特性」）；重开一个会话即可看到。技能内容本身始终实时读取。\n只有经本插件注册的 WSL 工作区才会默认用 WSL 变体；在其它工作区里手动新建的会话用宿主默认预设，bash/文件工具就是 Windows 侧的。\n0.4.3 已修复：UNC 工作区下模型收不到技能目录（宿主 fs.watch 在 \\\\wsl.localhost\\… 上失败导致整条目录消息被丢弃），现在生成预设时会关闭该监视，目录照常注入。",
+	"help.footer.npm": "npm 包",
+	"help.footer.repo": "GitHub 仓库"
 };
 /**
 * The `wslWorkspace` translations (English).
@@ -946,7 +1138,18 @@ const en = {
 	"error.invalidPath": "Enter an absolute Linux path starting with /",
 	"error.invalidUsername": "Invalid username: start with a letter or underscore; only letters, digits, _ . -",
 	"error.pathNotFound": "The path does not exist or is a file; choose a folder",
-	"error.createFailed": "Failed to create the workspace"
+	"error.createFailed": "Failed to create the workspace",
+	"help.button": "About this plugin",
+	"help.compat.title": "Compatibility",
+	"help.compat.versionLabel": "Plugin version",
+	"help.compat.unknown": "Version and compatibility declaration unavailable (the host side did not answer)",
+	"help.compat.body": "The chips above are the DSH releases this build declares, each verified on an isolated instance (own DSH_HOME, dependencies pinned to that release, full check suite).\nThe plugin detects the DSH generation at runtime: the 0.1.2 line uses uiWorkspace + remote.agentPresets, older releases use workspaces.startSession + connection.api, and a release exposing neither fails loudly instead of leaving an empty workspace.\nA release outside the list usually still works, but is unverified.",
+	"help.usage.title": "Usage and features",
+	"help.usage.body": "Click the W button at the sidebar foot, pick a distribution, type or browse to a Linux path, press Check, then Create & open.\nIn that session the bash tool and the file tools run inside the distribution, so every path the model sees is a Linux path; Windows drives stay reachable as /mnt/<drive>.\nEach mode (Standard / PTC / Minimal / Creator) has a WSL variant in the mode picker, named like WSL · Standard mode.\nThe optional username behaves like wsl.exe -u <user> for the bash tool only; the file tools go through the Windows-side share and are unaffected.\nThe skill catalog is discovered from the nearest .git ancestor of the session cwd downwards (.dsh/skills and .agents/skills, nested projects included), bounded to 4 levels / 64 skill directories / 4096 visited directories, and cached per scan root for 10 seconds.\nSo that a UNC workspace still receives a catalog, the generated preset turns that row's `watch` off and the catalog is scanned once at session start: a skill added mid-session appears in the next session, while skill bodies are always read live.\nbash runs inside the distribution and is not wrapped by the DSH file policy; read/write/edit are, and workspace-write only writes inside the workspace.",
+	"help.known.title": "Known issues",
+	"help.known.body": "The Windows-side share cannot resolve Linux symlinks, so a project linked in with ln -s is not discoverable (the scan skips it without failing); register the workspace at a level that holds the real project directories.\nA skill added while a session is running does not show up in that session's catalog (file watching is off for UNC workspaces, see Usage and features); start a new session to pick it up. Skill bodies are always read live.\nOnly workspaces registered through this plugin default to a WSL variant; a session started by hand in another workspace keeps the host default preset, so its bash and file tools run on the Windows side.\nFixed in 0.4.3: on a UNC workspace the model did not receive the skill catalog at all (the host fs.watch call fails on \\\\wsl.localhost\\... and the whole catalog message was dropped). The generated preset now disables that watcher, and the catalog is injected as usual.",
+	"help.footer.npm": "npm package",
+	"help.footer.repo": "GitHub repository"
 };
 
 //#endregion
@@ -1075,6 +1278,7 @@ function apply(ctx) {
 			return void 0;
 		},
 		listDistros: () => listDistros(),
+		describe: () => describe(),
 		listDir: (distro, path) => listDir(distro, path),
 		check: (distro, path) => check(distro, path),
 		createWorkspace: async (linuxPath, username, distro) => {