dsh-manage-session 0.0.0-stage → 2.0.3

package/CHANGELOG.ja.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 1.0.0
+
+`dsh-session-steward` 0.5.7 から複製・改名した独立パッケージの初版です（旧パッケージの履歴は
+そのリポジトリの CHANGELOG を参照）。本パッケージの位置づけは**セッションマネージャー**：
+アクティブ／アーカイブ済みセッションの統合管理と全文検索。
+
+### 位置づけと命名
+
+- パッケージ名 / プラグイン id：`dsh-session-steward` → `dsh-manage-session`。表示名：セッション管理（9 言語同期）。
+- 設定名前空間：`session-steward` → `manage-session`、`switch-search` → `manage-session-search`。
+- ルート接頭辞：`/session-steward/api` → `/manage-session/api`、`/switch-search/api` → `/manage-session-search/api`。
+- ストレージ：索引・墓碑の既定ディレクトリ `~/.dsh-switch-search` → `~/.dsh-manage-session-index`、
+  お気に入り `session-steward-favorites.json` → `manage-session-favorites.json`（旧パッケージと干渉しません）。
+- スタイル接頭辞 `dss_`/`dsws_` → `dms_`/`dmss_`。スタイルシート id と data 属性も改名。
+
+### 新規：入口の位置（上部ツール枠 / 下部フォールバック）
+
+- ホストが上部ツール行（`sidebar.panellist` パネル行 + `main` ページ枠）を宣言している場合、
+  検索と管理の 2 つの入口を**パネル行**として「プラグイン」行の直後、「その他」ランチャーの手前
+  （order 5 / 6）に配置し、クリックでメイン列に全ページ表示。ページ内「閉じる」で会話に戻ります。
+- その枠が無いホスト（旧ライン／簡易レイアウト）ではサイドバー下部（`sidebar.footer.action`）に
+  フォールバックし、フローティングダイアログを開きます。
+- 判定はロード時（`slots.specDynamic` で両席を確認）。枠が後から現れた場合は下部入口を外して上部へ切替。
+- パネル行／ページは設定スイッチ（`enabled` / `search` / `healthCheck`）に連動し、切替は即時反映。
+
+### 付随変更
+
+- パネルに全ページ形態（`variant: 'page'`）を追加：遮罩と浮動配置を外しメイン列を埋めます。ダイアログ形態は不変。
+- ドキュメント刷新：README / INSTALL を 4 言語で同期（位置づけ・入口・ルート・設定表）。互換節は
+  `scripts/sync-hosts.mjs` の単一ソース生成のまま。
+- 対応ホストのホワイトリストは不変：`engines.dsh` は 0.1.0-rc.2 〜 0.2.1-rc.3 の rc 列挙。

package/CHANGELOG.ko.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 1.0.0
+
+`dsh-session-steward` 0.5.7에서 복제·개명한 독립 패키지의 첫 버전입니다(구 패키지 이력은 해당
+저장소 CHANGELOG 참조). 이 패키지의 정체성은 **세션 매니저**: 활성·보관 세션의 통합 관리와 전문 검색.
+
+### 정체성과 이름
+
+- 패키지명 / 플러그인 id: `dsh-session-steward` → `dsh-manage-session`. 표시 이름: 세션 관리(9개 언어 동기화).
+- 설정 네임스페이스: `session-steward` → `manage-session`, `switch-search` → `manage-session-search`.
+- 라우트 접두사: `/session-steward/api` → `/manage-session/api`, `/switch-search/api` → `/manage-session-search/api`.
+- 저장소: 색인·묘비 기본 디렉터리 `~/.dsh-switch-search` → `~/.dsh-manage-session-index`,
+  즐겨찾기 `session-steward-favorites.json` → `manage-session-favorites.json`(구 패키지와 충돌 없음).
+- 스타일 접두사 `dss_`/`dsws_` → `dms_`/`dmss_`. 스타일시트 id와 data 속성도 개명.
+
+### 신규: 진입점 위치(상단 도구 슬롯 / 하단 대체)
+
+- 호스트가 상단 도구 행(`sidebar.panellist` 패널 행 + `main` 페이지 슬롯)을 선언하면 검색·관리 두
+  진입점이 **패널 행**으로 「플러그인」 행 바로 뒤, 「더 보기」 런처 앞(order 5/6)에 놓이고 클릭 시
+  메인 열에 전체 페이지로 열립니다. 페이지의 「닫기」는 대화로 복귀합니다.
+- 해당 슬롯이 없는 호스트(구버전/간소 레이아웃)는 사이드바 하단(`sidebar.footer.action`)으로 대체되어
+  플로팅 대화상자를 엽니다.
+- 판정은 로드 시점(`slots.specDynamic`로 두 좌석 확인). 슬롯이 늦게 생기면 하단 진입점을 제거하고 상단 전환.
+- 패널 행/페이지는 설정 스위치(`enabled` / `search` / `healthCheck`)와 연동되어 즉시 반영됩니다.
+
+### 부수 변경
+
+- 패널에 전체 페이지 형태(`variant: 'page'`) 추가: 오버레이·부동 배치를 제거하고 메인 열을 채웁니다.
+  대화상자 형태는 그대로입니다.
+- 문서 개편: README / INSTALL 4개 언어 동기화(정체성·진입점·라우트·설정 표). 호환 절은
+  `scripts/sync-hosts.mjs` 단일 소스 생성 유지.
+- 지원 호스트 화이트리스트 불변: `engines.dsh`는 0.1.0-rc.2 ~ 0.2.1-rc.3 rc 열거.

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog / 变更日志
+
+## 2.0.0
+
+**重定位：纯会话管理台。** 搜索/索引子域整体拆回 `dsh-search-index`，本包不再自建索引、
+不再依赖 DRS（`dsh-reference-session-collector`）。
+
+### 破坏性变化
+
+- 删除搜索子域：`/manage-session-search/api` 路由、FTS5 索引引擎/水位同步/重建/快照、
+  DRS 语料源、搜索面板与搜索设置卡、搜索入口与搜索页全部移除。
+- 依赖：移除 `dsh-reference-session-collector`（dependencies + pluginDependencies）与
+  `better-sqlite3`（optional）。
+- 设置：命名空间只剩 `manage-session`；字段删 `search` / `defaultMode` / `autoSync` /
+  `syncIntervalMs` / `archiveKeep` / `indexDir` / `corpusSource` / `drsBaseUrl`。
+- 新方法 `session-catalog`：管理台语料改由宿主 `sessionQuery` + 官方归档集合现场拼装
+  （活跃/归档同表，归档标记 = 归档集合成员）。
+- `session-health-status` 的 switches 增补 `directDelete`（会话菜单删除行的探针面）。
+
+### 入口位次
+
+- 顶栏工具行（`sidebar.panellist` + `main`）→ 单枚面板行 order 6，落在「插件」之后、
+  「更多」之前，点击在主栏整页打开；无该槽位 → 回落底栏对话框。
+- 席位能力用 `inject` 探测（不依赖 `specDynamic`，避免服务面不暴露/装载序问题）。
+
+### 配套
+
+- 字典：`manage-locales.ts` 只保留管理台键集（9 语，含 star.on/star.off）。
+- 文档：README 四语重写；INSTALL 命令不变；兼容句仍由 `scripts/sync-hosts.mjs` 单源生成。
+
+## 1.0.1 / 1.0.0
+
+独立包首发（由 `dsh-session-steward` 0.5.7 复制改名而来），当时仍为合并包（含搜索子域）。

package/INSTALL.ja.md

@@ -0,0 +1,164 @@
+# インストールガイド（公式 DSH CLI）
+
+本ガイドは公式 DSH の `dsh plugin` コマンドのみを使用します。このコマンドは依存関係を profile にインストールし、`dsh.profile.bundles` を同期します。素の `npm install`、profile 内での直接の `pnpm add`、profile マニフェストの手動編集で置き換えないでください。
+
+- [英語インストールガイド](./INSTALL.md)
+- [中国語インストールガイド](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [韓国語インストールガイド](./INSTALL.ko.md)
+- [中国語 README](./README.md)
+- [英語 README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [韓国語 README](./README.ko.md)
+- [変更履歴](./CHANGELOG.md)
+- [日本語の変更履歴](./CHANGELOG.ja.md)
+- [韓国語の変更履歴](./CHANGELOG.ko.md)
+
+本ガイドで使用するプレースホルダは次のとおりです：
+
+- `<profile>`：変更対象の DSH profile。通常は `web`。
+- `dsh-manage-session`：npm パッケージ名かつランタイムプラグイン ID。
+
+> **対応 DSH 範囲：`engines.dsh` の rc 個別ホワイトリスト（`0.1.0-rc.2` 〜 `0.2.1-rc.3`、各版実測）。**
+>
+> これは `package.json` と `dsh.plugin.json` の双方の `engines.dsh` で宣言されている範囲であり、本プラグインが自身の `@deepseek-ai/dsh-client-ui-slots` 依存に対してすでに宣言している `^0.1.0-rc.6` の下限とも一致します。インストール前に `dsh --version` で実行中のバージョンを確認してください。
+
+## 0. 前提条件と profile の確認
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+ls "${DSH_HOME:-$HOME/.dsh}/profiles"
+```
+
+実行中の DSH プロセスが指定している profile を使用してください。`web` が一般的ですが、実際に有効なのは `--profile` 引数です。
+
+## 1. 公式インストール
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session -w
+```
+
+（profile が `web` のように pnpm ワークスペースのルートである場合、`-w` フラグが必要です。）
+
+特定のバージョンを明示的にインストールする場合：
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session@1.0.0 -w
+```
+
+公式 CLI は profile の依存関係、ロックファイル、`dsh.profile.bundles` を自動的に更新します。YAML の行を手動で追加しないでください。
+
+### サプライチェーンのクーリング期間
+
+DSH ランタイムは pnpm 11 を使用しており、その `minimumReleaseAge` ポリシーが公開直後のバージョンを `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` でブロックすることがあります。`~/.dsh/profiles/<profile>/pnpm-workspace.yaml` の `minimumReleaseAgeExclude` にそのバージョンを追加してください：
+
+```yaml
+minimumReleaseAgeExclude:
+  - dsh-manage-session@1.0.0
+```
+
+## 2. ホストの再起動
+
+**インストールまたはアップグレードの後には DSH の再起動が必要です。** ブラウザのページを再読み込みするだけでは不十分です。ホスト側は起動時に `/manage-session/api` ルートと設定名前空間を登録し、またアーカイブの取得元を再読み込みしない限り整理（prune）の結果は反映されません。
+
+## 3. アップグレード
+
+```bash
+dsh plugin --profile <profile> update dsh-manage-session -w
+```
+
+その後 DSH を再起動してください。
+
+## 4. ローカルパス / `link:` による登録（代替手段）
+
+開発やオフラインインストールでは、ローカルのチェックアウトからプラグインを登録します：
+
+```bash
+#    ~/.dsh/profiles/<profile>/package.json dependencies:
+#      "dsh-manage-session": "link:<absolute path to dsh-manage-session>"
+#    ~/.dsh/profiles/<profile>/cordis.patch.yml:
+#      - insert:
+#          - id: dsh-manage-session
+#            name: dsh-manage-session
+cd ~/.dsh/profiles/<profile> && pnpm install && dsh web
+```
+
+または、ローカルパスを指定して公式 CLI を使います（ネットワーク不要）：
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-manage-session -w
+```
+
+ソースチェックアウトからビルドする場合は次のスクリプトを使います：
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/index.d.ts + lib/client.js
+```
+
+`lib/` はコミットされていないため、ソースチェックアウトはパス指定で登録する前にビルドする必要があります。公開時は `prepublishOnly` フックによって自動的にビルドされます。
+
+## 5. インストールの確認
+
+依存関係とインストール済みバージョンを確認します：
+
+```bash
+grep -n "dsh-manage-session" \
+  "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/package.json"
+node -p "require('${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/node_modules/dsh-manage-session/package.json').version"
+```
+
+公式のコンポジションを確認します：
+
+```bash
+dsh --profile <profile> --dump-default-config
+```
+
+次の内容が含まれている必要があります：
+
+```yaml
+- id: dsh-manage-session
+  name: dsh-manage-session
+```
+
+## 6. プラグインの確認
+
+再起動後、サイドバーエントリ `dsh-manage-session` が利用可能になり、設定セクションは `manage-session` 名前空間を使用します。次を確認してください：
+
+1. 両方のフィーチャーゲートがオンのとき、**カルテ室**と**健診**の両タブが描画される。
+2. `historyFiles` をオフにするとカルテ室タブが消え、すべての `session-history-*` 呼び出しが明示的な disabled エラーを返す。
+3. `healthCheck` をオフにすると健診タブが消え、すべての `session-health-*` 呼び出しが明示的な disabled エラーを返す。
+4. `/manage-session/api` 上の未知のメソッドは、黙って成功せず明示的なエラーを返す。
+
+閉じられたドメインは `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }` を返します — プラグインは空の殻を後に残しません。
+
+## 7. トラブルシューティング
+
+| 症状 | 対処 |
+| --- | --- |
+| `dsh` が見つからない | 公式 DSH CLI をインストールするか有効化してください。 |
+| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | profile の `pnpm-workspace.yaml` の `minimumReleaseAgeExclude` にそのバージョンを追加してください。 |
+| インストール後にタブやルートが表示されない | ホストプロセスを再起動してください — ページの再読み込みではルートは再登録されません。 |
+| アーカイブ集合への変更が反映されない | ホストを再起動してください。アーカイブの取得元は起動時に読み込まれます。 |
+| `session-history-*` が disabled エラーを返す | `historyFiles` ゲートがオフです。プラグイン設定で再度有効にしてください。 |
+| `session-health-*` が disabled エラーを返す | `healthCheck` ゲートがオフです。プラグイン設定で再度有効にしてください。 |
+| アップグレード後にクライアントバンドルが古い | ブラウザをスーパーリロードしてください（Ctrl+Shift+R）。 |
+
+## 8. 削除
+
+```bash
+dsh plugin --profile <profile> remove dsh-manage-session
+```
+
+その後 DSH を再起動してください。
+
+## 削除しても修復は元に戻らない
+
+本プラグインはセッションログや履歴データを書き換えることも、フィールドを暗黙に破棄することもありません。一見不可逆に見える唯一の操作 — 破損したプロジェクションキャッシュのレコードを隔離する — も、先にバックアップをコピーし、隔離ディレクトリは復元できるようにディスク上に残します。したがって、プラグインを削除しても、あなたが実行した隔離はそのまま残ります。状態を元に戻したい場合は手動で復元してください。
+
+## ライセンス
+
+MIT

package/INSTALL.ko.md

@@ -0,0 +1,164 @@
+# 설치 가이드(공식 DSH CLI)
+
+이 가이드는 공식 DSH `dsh plugin` 명령만 사용합니다. 이 명령은 의존성을 프로필에 설치하고 `dsh.profile.bundles`를 동기화합니다. 이를 일반 `npm install`, 프로필에서의 직접적인 `pnpm add`, 또는 프로필 매니페스트의 수동 편집으로 대체하지 마세요.
+
+- [영어 설치 가이드](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [中文 README](./README.md)
+- [영어 README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [변경 이력](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+이 가이드의 자리표시자는 다음과 같습니다.
+
+- `<profile>`: 수정할 DSH 프로필이며, 보통 `web`입니다;
+- `dsh-manage-session`: npm 패키지이자 런타임 플러그인 ID입니다.
+
+> **지원 DSH 범위: `engines.dsh`의 rc별 화이트리스트(`0.1.0-rc.2` ~ `0.2.1-rc.3`, 각 버전 실측).**
+>
+> 이는 `package.json`과 `dsh.plugin.json` 양쪽의 `engines.dsh`에 선언된 범위이며, 이 플러그인이 자체 `@deepseek-ai/dsh-client-ui-slots` 의존성에 대해 이미 선언한 `^0.1.0-rc.6` 하한과 일치합니다. 설치 전에 `dsh --version`으로 실행 중인 버전을 확인하세요.
+
+## 0. 사전 요구 사항과 프로필 확인
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+ls "${DSH_HOME:-$HOME/.dsh}/profiles"
+```
+
+실행 중인 DSH 프로세스가 지정한 프로필을 사용하세요. `web`이 일반적이지만, 활성 `--profile` 인자가 기준입니다.
+
+## 1. 공식 설치
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session -w
+```
+
+(프로필이 `web`처럼 pnpm 워크스페이스 루트인 경우 `-w` 플래그가 필요합니다.)
+
+특정 버전을 명시적으로 설치:
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session@1.0.0 -w
+```
+
+공식 CLI는 프로필 의존성, 잠금 파일, `dsh.profile.bundles`를 자동으로 갱신합니다. YAML 행을 수동으로 추가하지 마세요.
+
+### 공급망 쿨다운 기간
+
+DSH 런타임은 pnpm 11을 사용하며, 그 `minimumReleaseAge` 정책이 갓 게시된 버전을 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`과 함께 차단할 수 있습니다. `~/.dsh/profiles/<profile>/pnpm-workspace.yaml`의 `minimumReleaseAgeExclude`에 해당 버전을 추가하세요:
+
+```yaml
+minimumReleaseAgeExclude:
+  - dsh-manage-session@1.0.0
+```
+
+## 2. 호스트 재시작
+
+**설치 또는 업그레이드 후에는 DSH 재시작이 필요합니다.** 브라우저 페이지 새로고침만으로는 부족합니다: 호스트 측은 시작 시 `/manage-session/api` 라우트와 설정 네임스페이스를 등록하며, 정리 결과를 반영하려면 호스트가 아카이브 소스를 다시 로드해야 합니다.
+
+## 3. 업그레이드
+
+```bash
+dsh plugin --profile <profile> update dsh-manage-session -w
+```
+
+이후 DSH를 재시작하세요.
+
+## 4. 로컬 경로 / `link:` 등록(대안)
+
+개발이나 오프라인 설치의 경우 로컬 체크아웃에서 플러그인을 등록합니다:
+
+```bash
+#    ~/.dsh/profiles/<profile>/package.json dependencies:
+#      "dsh-manage-session": "link:<absolute path to dsh-manage-session>"
+#    ~/.dsh/profiles/<profile>/cordis.patch.yml:
+#      - insert:
+#          - id: dsh-manage-session
+#            name: dsh-manage-session
+cd ~/.dsh/profiles/<profile> && pnpm install && dsh web
+```
+
+또는 로컬 경로와 함께 공식 CLI를 사용하세요(네트워크 불필요):
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-manage-session -w
+```
+
+소스 체크아웃에서 빌드할 때는 다음 스크립트를 사용합니다:
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/index.d.ts + lib/client.js
+```
+
+`lib/`는 커밋되지 않으므로, 소스 체크아웃은 경로로 등록하기 전에 빌드해야 합니다. 게시 시에는 `prepublishOnly` 훅을 통해 자동으로 빌드됩니다.
+
+## 5. 설치 검증
+
+의존성과 설치된 버전을 확인합니다:
+
+```bash
+grep -n "dsh-manage-session" \
+  "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/package.json"
+node -p "require('${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/node_modules/dsh-manage-session/package.json').version"
+```
+
+공식 구성을 확인합니다:
+
+```bash
+dsh --profile <profile> --dump-default-config
+```
+
+다음이 포함되어야 합니다:
+
+```yaml
+- id: dsh-manage-session
+  name: dsh-manage-session
+```
+
+## 6. 플러그인 검증
+
+재시작 후 사이드바 항목 `dsh-manage-session`를 사용할 수 있고, 설정 섹션은 `manage-session` 네임스페이스를 사용합니다. 다음을 확인하세요:
+
+1. 두 기능 게이트가 모두 켜져 있을 때 **기록 보관소**와 **점검** 두 탭이 모두 렌더링됩니다.
+2. `historyFiles`를 끄면 기록 보관소 탭이 사라지고 모든 `session-history-*` 호출이 명시적인 disabled 오류를 반환합니다.
+3. `healthCheck`를 끄면 점검 탭이 사라지고 모든 `session-health-*` 호출이 명시적인 disabled 오류를 반환합니다.
+4. `/manage-session/api`의 인식되지 않는 메서드는 조용히 성공하지 않고 명시적인 오류를 반환합니다.
+
+닫힌 도메인은 `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }`를 반환합니다 — 플러그인은 빈 껍데기를 남기지 않습니다.
+
+## 7. 문제 해결
+
+| 증상 | 조치 |
+| --- | --- |
+| `dsh`를 찾을 수 없음 | 공식 DSH CLI를 설치하거나 활성화하세요. |
+| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | 프로필의 `pnpm-workspace.yaml`에 있는 `minimumReleaseAgeExclude`에 해당 버전을 추가하세요. |
+| 설치 후 탭이나 라우트가 없음 | 호스트 프로세스를 재시작하세요 — 페이지 새로고침은 라우트를 다시 등록하지 않습니다. |
+| 아카이브 집합 변경 사항이 보이지 않음 | 호스트를 재시작하세요; 아카이브 소스는 시작 시 읽힙니다. |
+| `session-history-*`가 disabled 오류를 반환함 | `historyFiles` 게이트가 꺼져 있습니다. 플러그인 설정에서 다시 켜세요. |
+| `session-health-*`가 disabled 오류를 반환함 | `healthCheck` 게이트가 꺼져 있습니다. 플러그인 설정에서 다시 켜세요. |
+| 업그레이드 후 클라이언트 번들이 오래됨 | 브라우저를 강력 새로고침하세요(Ctrl+Shift+R). |
+
+## 8. 제거
+
+```bash
+dsh plugin --profile <profile> remove dsh-manage-session
+```
+
+이후 DSH를 재시작하세요.
+
+## 제거해도 복구가 되돌려지지는 않습니다
+
+이 플러그인은 세션 로그나 히스토리 데이터를 재작성하지 않으며, 필드를 조용히 버리지도 않습니다. 되돌릴 수 없어 보이는 유일한 동작 — 손상된 프로젝션 캐시 레코드 격리 — 은 먼저 백업을 복사하며, 격리 디렉터리는 복원에 사용할 수 있도록 디스크에 남겨 둡니다. 따라서 플러그인을 제거해도 요청한 격리 결과는 그대로 남습니다; 상태를 되돌리려면 직접 복원하세요.
+
+## 라이선스
+
+MIT

package/INSTALL.md

@@ -0,0 +1,164 @@
+# Installation Guide (Official DSH CLI)
+
+This guide uses only the official DSH `dsh plugin` command. That command installs the dependency into a profile and synchronizes `dsh.profile.bundles`. Do not replace it with plain `npm install`, a direct `pnpm add` in the profile, or manual edits to the profile manifest.
+
+- [English installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+The placeholders in this guide are:
+
+- `<profile>`: the DSH profile to modify, usually `web`;
+- `dsh-manage-session`: the npm package and runtime plugin ID.
+
+> **Supported DSH range: the enumerated whitelist in `engines.dsh` (`0.1.0-rc.2` … `0.2.1-rc.3`, each rc tested).**
+>
+> This is the range declared in `engines.dsh` of both `package.json` and `dsh.plugin.json`, and it matches the `^0.1.0-rc.6` floor this plugin already declares for its own `@deepseek-ai/dsh-client-ui-slots` dependency. Check the running version with `dsh --version` before installing.
+
+## 0. Prerequisites and profile discovery
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+ls "${DSH_HOME:-$HOME/.dsh}/profiles"
+```
+
+Use the profile named by your running DSH process. `web` is common, but the active `--profile` argument is authoritative.
+
+## 1. Official installation
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session -w
+```
+
+(the `-w` flag is required when the profile is a pnpm workspace root, as `web` is.)
+
+Install a specific version explicitly:
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session@1.0.0 -w
+```
+
+The official CLI updates the profile dependency, the lockfile, and `dsh.profile.bundles` automatically. Do not add a manual YAML row.
+
+### Supply-chain cooling period
+
+The DSH runtime uses pnpm 11, whose `minimumReleaseAge` policy may block a freshly published version with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`. Add the version to `minimumReleaseAgeExclude` in `~/.dsh/profiles/<profile>/pnpm-workspace.yaml`:
+
+```yaml
+minimumReleaseAgeExclude:
+  - dsh-manage-session@1.0.0
+```
+
+## 2. Restart the host
+
+**A DSH restart is required after installing or upgrading.** Refreshing the browser page is not enough: the host half registers the `/manage-session/api` routes and the settings namespace at startup, and the host must reload the archive source before it reflects a prune.
+
+## 3. Upgrade
+
+```bash
+dsh plugin --profile <profile> update dsh-manage-session -w
+```
+
+Restart DSH afterwards.
+
+## 4. Local-path / `link:` registration (alternative)
+
+For development or offline installs, register the plugin from a local checkout:
+
+```bash
+#    ~/.dsh/profiles/<profile>/package.json dependencies:
+#      "dsh-manage-session": "link:<absolute path to dsh-manage-session>"
+#    ~/.dsh/profiles/<profile>/cordis.patch.yml:
+#      - insert:
+#          - id: dsh-manage-session
+#            name: dsh-manage-session
+cd ~/.dsh/profiles/<profile> && pnpm install && dsh web
+```
+
+Or use the official CLI with a local path (no network needed):
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-manage-session -w
+```
+
+Building from a source checkout uses these scripts:
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/index.d.ts + lib/client.js
+```
+
+`lib/` is not committed, so a source checkout must be built before it can be registered by path. Publishing builds it automatically through the `prepublishOnly` hook.
+
+## 5. Verify installation
+
+Check the dependency and the installed version:
+
+```bash
+grep -n "dsh-manage-session" \
+  "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/package.json"
+node -p "require('${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/node_modules/dsh-manage-session/package.json').version"
+```
+
+Check the official composition:
+
+```bash
+dsh --profile <profile> --dump-default-config
+```
+
+It must contain:
+
+```yaml
+- id: dsh-manage-session
+  name: dsh-manage-session
+```
+
+## 6. Verify the plugin
+
+After the restart, the sidebar entry `dsh-manage-session` is available and the settings section uses the `manage-session` namespace. Confirm:
+
+1. Both tabs render — **Retirement Home** and **Checkup** — while both feature gates are on.
+2. Turning `historyFiles` off removes the Retirement Home tab and makes every `session-history-*` call return an explicit disabled error.
+3. Turning `healthCheck` off removes the Checkup tab and makes every `session-health-*` call return an explicit disabled error.
+4. An unrecognized method on `/manage-session/api` returns an explicit error rather than succeeding silently.
+
+Closed domains return `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }` — the plugin does not leave empty shells behind.
+
+## 7. Troubleshooting
+
+| Symptom | Action |
+| --- | --- |
+| `dsh` is not found | Install or enable the official DSH CLI. |
+| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | Add the version to `minimumReleaseAgeExclude` in the profile's `pnpm-workspace.yaml`. |
+| Tabs or routes missing after install | Restart the host process — a page refresh does not re-register routes. |
+| Changes to the archive set are not visible | Restart the host; the archive source is read at startup. |
+| `session-history-*` returns a disabled error | The `historyFiles` gate is off. Re-enable it in the plugin settings. |
+| `session-health-*` returns a disabled error | The `healthCheck` gate is off. Re-enable it in the plugin settings. |
+| Stale client bundle after an upgrade | Hard-refresh the browser (Ctrl+Shift+R). |
+
+## 8. Remove
+
+```bash
+dsh plugin --profile <profile> remove dsh-manage-session
+```
+
+Restart DSH afterwards.
+
+## Removal does not undo repairs
+
+The plugin never rewrites session logs, history data, or silently drops fields. The only irreversible-looking action it takes — quarantining a damaged projection-cache record — copies a backup first, and the quarantine directory is left on disk for you to restore from. Removing the plugin therefore leaves any quarantine you asked for in place; restore it manually if you want the state back.
+
+## License
+
+MIT