From abba2b11f1a8055dbe3ad2b962ca1fb5ab460c93 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=BA=88=E7=BA=BE?= <yushu@srcz.one>
Date: Thu, 22 Oct 2026 16:42:04 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E9=85=8D=E7=BD=AE=E4=B8=8E?=
 =?UTF-8?q?=E7=8A=B6=E6=80=81=E5=BF=AB=E7=85=A7=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md         | 27 +++++++++++++++++++++++++++
 README.zh_hans.md | 25 +++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/README.md b/README.md
index ee611b2..c5e1075 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,33 @@ The RID-first native library probe uses the McMaster fork; check that out as a s
 - **This repository alone** (CI, and any external consumer) → `PackageReference`, pinned to an exact
   version.
 
+## Options and status
+
+The constructor overload accepts `PluginManagerOptions`. `UnloadVerificationTimeout` defaults to
+30 seconds; a finite value must be positive and no more than about 49.7 days, and
+`Timeout.InfiniteTimeSpan` disables the timer. A timeout is a failed unload: the report says so,
+and the slot stays `Detached`, so `Plugins` keeps returning it.
+
+```csharp
+var options = new PluginManagerOptions
+{
+    UnloadVerificationTimeout = TimeSpan.FromSeconds(60),
+};
+
+var manager = new PluginManager(
+    pluginsRoot, dataRoot, configRoot, reportFault,
+    carrierServices, onRemoved, options);
+```
+
+`Plugins` returns a read-only snapshot of every slot, including `Detached` ones;
+`TryGetPlugin(name, out var info)` reads one by name. `PluginInfo` carries `Name`, `Version`,
+`Loader`, `State`, `Enabled`, `IsLoader`, and `Dependencies`.
+
+```csharp
+foreach (var info in manager.Plugins)
+    Console.WriteLine($"{info.Name}: {info.State}, enabled={info.Enabled}");
+```
+
 ## As a lip package
 
 A `v*` tag builds `hosihikari-core-<version>.zip` and publishes it as
diff --git a/README.zh_hans.md b/README.zh_hans.md
index d359154..9bf0fc8 100644
--- a/README.zh_hans.md
+++ b/README.zh_hans.md
@@ -34,6 +34,31 @@ CI 跑的就是这一条命令，走的也是外部插件作者拿到契约的
 
 本机库的 RID 优先解析走 McMaster 的 fork；它也必须作为兄弟目录检出（CI 就是这么摆的）。
 
+## 配置与状态
+
+构造函数重载接受 `PluginManagerOptions`。`UnloadVerificationTimeout` 默认 30 秒；有限值必须为正且
+不超过约 49.7 天，`Timeout.InfiniteTimeSpan` 关闭计时器。超时按卸载失败记录，报告会如实写明；
+槽位保持 `Detached`，因此 `Plugins` 仍会返回它。
+
+```csharp
+var options = new PluginManagerOptions
+{
+    UnloadVerificationTimeout = TimeSpan.FromSeconds(60),
+};
+
+var manager = new PluginManager(
+    pluginsRoot, dataRoot, configRoot, reportFault,
+    carrierServices, onRemoved, options);
+```
+
+`Plugins` 返回所有槽位的只读快照，包含 `Detached`；`TryGetPlugin(name, out var info)` 按名字读取
+一个。`PluginInfo` 带 `Name`、`Version`、`Loader`、`State`、`Enabled`、`IsLoader` 与 `Dependencies`。
+
+```csharp
+foreach (var info in manager.Plugins)
+    Console.WriteLine($"{info.Name}: {info.State}, enabled={info.Enabled}");
+```
+
 ## 作为 lip 包
 
 打 `v*` 标签会构建 `hosihikari-core-<版本>.zip`，发布为