@chestnut23/dsh-conversation-outline 0.1.0

package/docs/publishing-guide.md

@@ -0,0 +1,384 @@
+# dsh-conversation-outline 发布指南（Publishing Guide）
+
+本指南面向维护者，覆盖把 `dsh-conversation-outline` 从本地仓库发布到**npm registry**与
+**GitHub** 两条分发通道的完整流程：许可证选择、发布前检查、GitHub 仓库创建、版本与
+Release 工作流、npm 发布（含命名冲突时的 scoped 兜底）、**GitHub-only 分发**（本仓库的
+默认形态）、发布后推广与 FAQ。
+
+权威依据：DSH 插件开发 Skill（`/tmp/dsh-plugin-skill.md` §7「分发、安装与生效边界」、
+§8.4「从零安装与 Git 分发」）与本仓库 `docs/implementation-spec.md` §3/§4。
+
+---
+
+## 1. 许可证选择：为什么推荐 MIT
+
+### 1.1 常见许可证对比
+
+| 许可证 | 类型 | 对用户的要求 | 对商业/闭源使用 | 备注 |
+|---|---|---|---|---|
+| **MIT** | 宽松（permissive） | 保留版权声明即可 | ✅ 完全允许 | 生态默认，单文件、无附加义务 |
+| Apache-2.0 | 宽松 | 保留声明 + 标注修改文件 | ✅ 允许 | 含专利授权条款，篇幅较长 |
+| BSD-3-Clause | 宽松 | 保留声明 | ✅ 允许 | 与 MIT 类似，多一条禁止用作者名义背书 |
+| GPL-3.0 | 强 Copyleft | 衍生作品必须同协议开源 | ⚠️ 传染 | 会吓退不想开源的集成方 |
+| Unlicense | 公有领域 | 无 | ✅ 允许 | 放弃一切权利；部分司法辖区有争议 |
+
+### 1.2 推荐：MIT
+
+理由：
+
+1. **生态一致性**：DSH 官方及第三方插件事实标准（参考样例 `@nanmicoder/dsh-agent-teams`
+   即 MIT）；用户对 MIT 的心理预期最低。
+2. **零义务**：只要求保留版权与许可声明，不限制 DSH 商业部署场景。
+3. **可维护**：单文件 `LICENSE` + `package.json` 的 `"license": "MIT"` 字段即可，无专利
+   附录等额外内容。
+4. **已就位**：仓库根目录已有 `LICENSE`（MIT 全文），`package.json` 已声明 `"license": "MIT"`。
+
+### 1.3 发布前必须修掉的两处占位
+
+- `LICENSE` 第 3 行：`Copyright (c) 2026 your name` → 替换成真实版权人
+  （`Copyright (c) 2026 <你的名字或组织>`）。
+- `package.json` 的 `repository.url`：`git+https://github.com/<owner>/dsh-conversation-outline.git`
+  → 替换为真实仓库地址（创建仓库后回填）。
+
+> 许可证选择一旦公开就极难更改（改协议需要所有贡献者同意），发布前定稿。
+
+---
+
+## 2. 发布前检查清单（Pre-publish Checklist）
+
+逐项确认，全部满足再发版：
+
+- [ ] **包名可用**：`npm view dsh-conversation-outline` 返回 404（`npm error code E404`）
+      表示名字未被占用；被占用则走 scoped 兜底（见 §5.3）。
+- [ ] **`package.json` 完整**：`name` / `version` / `description` / `keywords` /
+      `license` / `engines`（`^22.19.0 || >=24`）/ `files` 白名单 / `repository`（已回填）。
+- [ ] **`files` 白名单正确**：`["lib", "assets", "docs", "cordis.patch.yml", "README.md", "README.zh.md", "LICENSE"]`——
+      `lib/` 是唯一产物目录，`cordis.patch.yml` 是 bundle patch，二者缺一不可；
+      横幅图（assets）、导航文档（docs）与中英两份 README 一并随包发布。
+- [ ] **构建与校验全绿**：
+
+      ```sh
+      pnpm typecheck   # host + client 双 tsc program
+      pnpm build       # tsc × 2 → tsdown 打 lib/client.js
+      pnpm verify      # 离线冒烟（manifest/exports/patch/产物形状 + 纯逻辑）
+      ```
+
+- [ ] **README 与实际分发形态一致**（skill §9）：README.md（英文）+ README.zh.md（中文）
+      互相链接、内容一致；安装命令与即将发布的方式匹配——若先走 GitHub 分发，
+      README 的推荐命令应为 `github:<owner>/dsh-conversation-outline`；
+      npm 发布后再把推荐命令换成 npm 包名（两份 README 同步改）。
+- [ ] **`lib/` 产物是最新且已提交**（本仓库策略，见 §6.2）——GitHub 安装拿到的就是
+      仓库里的 `lib/`，发 tag 前必须确认与源码同步。
+- [ ] **LICENSE 版权人已替换**（§1.3）。
+- [ ] **`prepublishOnly` 存在**：`pnpm build && pnpm verify`——保证无论谁发布，
+      发出去的必然是「构建 + 校验通过」的产物。
+- [ ] **peer 依赖范围用 rc 通道**：`@deepseek-ai/*` 为 `^0.1.0-rc.6` 这类 rc 范围
+      （普通 `^0.0.1` 不匹配 `0.0.1-rc.x`，安装会解析失败）。
+- [ ] **敏感信息零残留**：`lib/` 内无本机绝对路径（`scripts/verify.mjs` 已自动检查
+      `/Users/`），`.gitignore` 排除 `node_modules/`（开发期类型符号链接绝不入库）。
+
+---
+
+## 3. 创建 GitHub 仓库（Create the Repo）
+
+本仓库目前**尚未 `git init`**，首次发布从这里开始。
+
+### 3.1 命令行（gh CLI）
+
+```sh
+gh auth login                    # 首次：浏览器授权
+git init
+git add -A
+git commit -m "chore: initial commit"
+gh repo create <owner>/dsh-conversation-outline --public --source . --remote origin --push
+```
+
+`gh repo create` 文档：<https://cli.github.com/manual/gh_repo_create>。
+
+### 3.2 Web 界面
+
+打开 <https://github.com/new>：
+
+- Repository name：`dsh-conversation-outline`（与包名一致，便于 `github:owner/repo` 记忆）。
+- Visibility：**Public**（私有仓库无法被 `dsh plugin add github:...` 直接安装）。
+- Description：`Codex-style conversation outline plugin for DeepSeek Harness (bilingual zh-CN/en)`。
+- 不要勾选自动初始化（README/LICENSE/.gitignore）——仓库里已有，避免冲突；
+  若误勾，用 `git pull --rebase` 合并。
+
+参考：<https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository>
+
+### 3.3 初始化建议（可选但推荐）
+
+- **Topics**：`dsh`、`dsh-plugin`、`deepseek-harness`、`conversation-outline`——便于被发现。
+- **默认分支保护**：Settings → Branches → main：要求 PR 通过（typecheck/build/verify）才能合并。
+- **ISSUE_TEMPLATE / PR template**（可选）：`.github/ISSUE_TEMPLATE/bug_report.yml`、
+  `.github/pull_request_template.md`。
+- **SECURITY.md**（可选）：说明漏洞上报渠道（GitHub private advisory 即可）。
+
+---
+
+## 4. 版本与 Release 工作流（Versioning & Releases）
+
+### 4.1 语义化版本（SemVer）
+
+起步 `0.1.0`。规则：
+
+- `patch`：修复、文案、样式微调（`0.1.1`）；
+- `minor`：新功能、向后兼容增强（`0.2.0`；`0.x` 阶段 minor 可以是任何功能）；
+- `major`：破坏性变更（`1.0.0` 之后才严格适用，`0.x` 阶段破坏性变更 bump minor 即可）。
+
+### 4.2 CHANGELOG
+
+推荐 `CHANGELOG.md` 手写（项目小，避免引入 Changesets 的复杂度）：
+
+```markdown
+## [0.1.0] - 2026-01-xx
+
+### Added
+- 浮动徽章 + 会话大纲面板（shell.overlay）
+- 点击跳转（切 Chat 视图 → 滚动 → 高亮闪烁）
+- 搜索 / 加载更早 / 复制 / 追问标签
+- zh-CN / en 双语
+```
+
+### 4.3 发版动作
+
+```sh
+pnpm typecheck && pnpm build && pnpm verify   # 全绿
+# 更新 version（npm version 0.1.1 或手改 package.json）
+git add -A && git commit -m "release: v0.1.1"  # lib/ 变更一并提交（§6.2）
+git tag v0.1.1
+git push origin main --tags
+gh release create v0.1.1 --generate-notes     # GitHub Release + 自动生成变更说明
+```
+
+`gh release create` 文档：<https://cli.github.com/manual/gh_release_create>；
+GitHub Releases 说明：<https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository>
+
+### 4.4 可选：CI（GitHub Actions）
+
+`.github/workflows/ci.yml` —— PR 自动检查：
+
+```yaml
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: pnpm }
+      - run: pnpm install
+      - run: pnpm typecheck
+      - run: pnpm build
+      - run: pnpm verify
+```
+
+> 注意：CI 里 `pnpm install` 需要能解析 `@deepseek-ai/*` peer（本仓库通过
+> `pnpm dev:types` 符号链接本地类型，见 implementation-spec §1.7）——若 CI 无 DSH
+> checkout，可让 CI 先执行 `pnpm dev:types` 对应的链接脚本，或在 CI 里跳过类型检查、
+> 仅跑 `pnpm build && pnpm verify`。以实际 CI 环境为准。
+
+发布自动化的可选进阶：`on: push: tags: ['v*']` 触发 `pnpm publish`，配合
+[npm trusted publishing（OIDC）](https://docs.npmjs.com/generating-provenance-statements)
+可免存 token、自动生成 provenance 签名。
+
+---
+
+## 5. npm 发布（npm Publish）
+
+### 5.1 账号与安全前置
+
+- 在 <https://www.npmjs.com> 注册账号，**必须开启 2FA**（npm 已强制：发布包的账号必须有
+  2FA；GitHub 也在把 npm 账号的 2FA 与短时令牌作为安全基线推行）。
+  参考：[npm Docs — Requiring 2FA for package publishing](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/)
+  与 [GitHub Mandates 2FA and Short-Lived Tokens for npm](https://thehackernews.com/2025/09/github-mandates-2fa-and-short-lived.html)。
+- 本地登录：`npm login`（或 `pnpm login`，二者共享 npm 凭证）。
+
+### 5.2 发布命令
+
+```sh
+npm pack --dry-run   # 先看 files 白名单实际会打进哪些文件（应只有 lib/、assets、docs、patch、README、LICENSE）
+pnpm publish         # 触发 prepublishOnly: pnpm build && pnpm verify
+```
+
+- `prepublishOnly` 保证发布前自动重构建 + 校验，防止手滑发布旧产物。
+- 发布后验证：`npm view dsh-conversation-outline`（版本、文件、peerDependencies）。
+- 钉版本安装（用户侧）：`dsh plugin --profile web add dsh-conversation-outline@0.1.0`。
+
+参考：<https://docs.npmjs.com/cli/v10/commands/npm-publish>
+
+### 5.3 命名冲突与 scoped 兜底（Fallback）
+
+若 `dsh-conversation-outline` 已被占用（`npm view` 返回包信息而非 404）：
+
+1. 改用 scoped 名：`@<你的npm用户名>/dsh-conversation-outline`（scope 名可以是用户名或组织名；
+   npm 每个账号默认拥有同名 scope）。
+2. **scoped 包发布默认是 `restricted`（私有）**，必须显式声明公开：
+
+   ```jsonc
+   // package.json
+   {
+     "name": "@<your-username>/dsh-conversation-outline",
+     "publishConfig": { "access": "public" }
+   }
+   ```
+
+   （`access: public` 只对首次发布生效；`npm publish --access public` 是等价的一次性参数。）
+3. 同步更新：README 安装命令、`exports` 不变（包名不影响内部路径）、`cordis.patch.yml`
+   的 `id`/`name` 改为新包名（verify 脚本会检查 patch 首行 id/name 与 `package.json.name`
+   一致，改名后必须重跑 `pnpm verify`）。
+4. 重新走一遍 §2 清单后发布。
+
+> **不要用 `@deepseek-ai` scope**：那是 DSH 官方 registry 的私有 scope（需要官方只读
+> token），个人无法发布。scoped 兜底只建议用你自己的用户名/组织 scope。
+
+---
+
+## 6. GitHub-only 分发（本仓库默认形态）
+
+### 6.1 关键决策：`lib/` 提交进 Git
+
+skill §7.1 给出 Git 分发的两种构建策略，本仓库选的是**备选（无交互安装）**：
+
+> 把 exports 指向的完整、最新 `lib/` 提交进 Git；用户无需执行依赖脚本。
+
+- `.gitignore` **故意不忽略 `lib/`**（当前只忽略 `node_modules/`、`*.tsbuildinfo`、
+  `.DS_Store`、`*.log`、`.tmp/`）。
+- 因此 `dsh plugin --profile web add github:<owner>/dsh-conversation-outline` 拿到的是
+  **已构建产物**，直接可加载：
+  - 不需要 `prepare` 构建脚本；
+  - 不需要在用户 profile 的 `pnpm-workspace.yaml` 里配 `allowBuilds`；
+  - 不需要执行任何第三方代码 → 安装零交互、零安全门禁。
+- 代价：每次发版必须**把最新的 `lib/` 一起提交**（见 §4.3），否则 GitHub 安装拿到的是
+  过期产物。`scripts/verify.mjs` 会在本地兜底检查产物一致性，但「提交时产物最新」是
+  发布纪律，无法自动保证。
+
+### 6.2 维护者纪律（GitHub 分发专属）
+
+每次发版动作固定为：
+
+```sh
+pnpm build && pnpm verify   # 产物重建 + 校验
+git add -A && git commit -m "release: v0.1.1 (rebuild lib)"  # lib/ 变更必须入库
+git push origin main --tags
+```
+
+永远不要在 `lib/` 过期时打 tag。
+
+### 6.3 备选路径（官方主推，供完整性参考）
+
+如果将来想**不提交 lib/**（仓库更干净、产物不漂移），就走官方主推的 `prepare` 路线：
+
+1. `package.json` 加：
+
+   ```jsonc
+   "scripts": { "prepare": "pnpm build" }
+   ```
+
+2. pnpm ≥10 默认**拦截 Git 依赖的构建脚本**（安全默认，见
+   [pnpm/pnpm#10288](https://github.com/pnpm/pnpm/pull/10288) 与
+   [pnpm 10.26 发布说明](https://pnpm.io/zh/blog/releases/10.26)），用户必须在**自己 profile
+   的 `pnpm-workspace.yaml`** 里显式放行再重跑 `add`：
+
+   ```yaml
+   # <DSH_HOME>/<profile>/pnpm-workspace.yaml
+   allowBuilds:
+     dsh-conversation-outline: true   # 或按 pnpm 版本用 onlyBuiltDependencies
+   ```
+
+3. 安全注意：`prepare` 会在安装时执行第三方代码，用户侧务必**固定 commit**
+   （`github:owner/repo#<sha>`）且只信任已审查的仓库。
+
+### 6.4 两种策略对比
+
+| 维度 | lib 入库（本仓库现状） | prepare + allowBuilds |
+|---|---|---|
+| 用户安装复杂度 | 零（装完即用） | 需手改 profile 配置后重装 |
+| 仓库整洁度 | lib/ 与源码并存 | 仓库只有源码 |
+| 产物漂移风险 | 需发布纪律（§6.2） | 安装时现构建，无漂移 |
+| 第三方代码执行 | 无 | 有（需 allowBuilds 门禁） |
+| 推荐度 | 本项目采用 | 官方主推，大型/多人项目适用 |
+
+---
+
+## 7. 发布后推广（Post-publish Promotion）
+
+1. **README badges 换回动态**：npm 发布前徽章用静态形式（`badge/npm-v0.1.0` /
+   `badge/license-MIT`，避免 "package not found"）。**发布成功后**，把两份 README 顶部
+   换回动态徽章，自动显示真实版本与下载量：
+
+   ```markdown
+   [![npm](https://img.shields.io/npm/v/dsh-conversation-outline.svg)](https://www.npmjs.com/package/dsh-conversation-outline)
+   [![npm downloads](https://img.shields.io/npm/dm/dsh-conversation-outline.svg)](https://www.npmjs.com/package/dsh-conversation-outline)
+   [![license](https://img.shields.io/npm/l/dsh-conversation-outline.svg)](LICENSE)
+   ```
+
+   （每次升版本后静态 `npm-vX.Y.Z` 徽章也要同步更新，动态徽章则不用管。）
+2. **README 安装命令切换**：把推荐安装方式从 `github:<owner>/...`（或 `link:`）换成
+   `dsh plugin --profile web add dsh-conversation-outline`（npm 形态），GitHub 方式保留为
+   「用最新提交」的备选。
+3. **截图**：补上 `assets/ui.png` 面板截图（README 预览区已留占位）。
+4. **对外渠道**（可选）：DSH 生态列表 / 社区帖 / 博客介绍。
+
+---
+
+## 8. FAQ
+
+**Q1：npm 包名被占了怎么办？**
+→ 见 §5.3：改 scoped 名 `@<你的用户名>/dsh-conversation-outline` + `publishConfig.access:
+public`，同步改 `cordis.patch.yml` 的 id/name 并重跑 `pnpm verify`。
+
+**Q2：GitHub 安装会不会执行构建脚本 / 需要 allowBuilds 吗？**
+→ 当前不会：`lib/` 已入库，无需 `prepare`。**只有**改走 §6.3 的 prepare 路线后，用户才需要
+在 profile 的 `pnpm-workspace.yaml` 配 `allowBuilds` 并重跑 `add`。
+
+**Q3：用户怎么升级？**
+→ 同一条 add 命令重跑即可：`dsh plugin --profile web add dsh-conversation-outline`（npm）
+或 `...@0.1.1` 钉版本；GitHub 方式 `add github:<owner>/dsh-conversation-outline` 拉最新
+main。升级后重启 DSH 服务。
+
+**Q4：怎么卸载？**
+→ `dsh plugin --profile web remove dsh-conversation-outline`（以 `dsh plugin --help`
+确认子命令名；skill 明确给出的是 `add`/`list`）。
+
+**Q5：发错了版本能撤回吗？**
+→ npm 只允许在发布后 **72 小时内** unpublish（`npm unpublish`），之后只能
+`npm deprecate`。所以小版本宁可多发 patch，也不要轻易撤包；GitHub tag 可随时删除重建。
+
+**Q6：用户装的是最新版，但国内镜像没同步？**
+→ 镜像缓存 `latest` 有延迟，用户钉版本安装（§5.2）即可绕开。
+
+**Q7：用户报 `waiting for service: xxx` 或 peer 解析失败？**
+→ 版本通道不匹配：`@deepseek-ai/*` 的 peer 范围必须是 rc 通道（本项目 `^0.1.0-rc.6`），
+且用户侧 `dsh` CLI 与 bundle 版本要同通道。见 implementation-spec §1.6 与开发指南 §4.3。
+
+**Q8：GitHub-only 分发还需要 npm 账号吗？**
+→ 不需要。GitHub 分发对发布者和用户都无需 npm 登录；npm 发布仅在你选择走 §5 时才有前置要求
+（2FA 等）。
+
+**Q9：`lib/` 能不能加回 `.gitignore`？**
+→ 可以，但那就等于切到 §6.3 的 prepare 路线：必须同步加 `prepare` 脚本、更新 README
+（告诉用户配 `allowBuilds`）。改之前想清楚——当前「lib 入库」是 GitHub 零交互安装的前提。
+
+---
+
+## 9. 参考
+
+- DSH 插件开发 Skill §7/§8（本机权威）：`/tmp/dsh-plugin-skill.md`
+- 开发长文指南 §4（构建与安装）：`/tmp/developing-dsh-plugins.md`
+- 官方参考插件（MIT，已发布 npm）：`@nanmicoder/dsh-agent-teams`
+- [npm Docs — npm-publish](https://docs.npmjs.com/cli/v10/commands/npm-publish)
+- [npm Docs — Requiring 2FA for package publishing](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/)
+- [GitHub Mandates 2FA and Short-Lived Tokens for npm (The Hacker News, 2025-09)](https://thehackernews.com/2025/09/github-mandates-2fa-and-short-lived.html)
+- [pnpm/pnpm#10288 — block git dependencies from running prepare scripts unless allowed](https://github.com/pnpm/pnpm/pull/10288)
+- [pnpm 10.26 release notes](https://pnpm.io/zh/blog/releases/10.26)
+- [GitHub Docs — Creating a new repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository)
+- [GitHub Docs — Managing releases in a repository](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)
+- [gh CLI — gh repo create](https://cli.github.com/manual/gh_repo_create)
+- [npm Docs — Generating provenance statements](https://docs.npmjs.com/generating-provenance-statements)

package/docs/security.md

@@ -0,0 +1,47 @@
+# Security
+
+`dsh-conversation-outline` is a **client-only** UI plugin. This page states what it can
+and cannot do, and how to verify it.
+
+## What it runs
+
+- **Host half**: a minimal, empty plugin body (`src/index.ts`) that exists only so the
+  plugin appears in the profile composition and the browser roster. It registers no
+  tools, no HTTP routes, no prompt sections, and reads no files.
+- **Client half**: the browser bundle renders the outline rail + hover panel. It
+  subscribes to the session snapshot and to the sessions list, and touches the DOM only
+  to scroll to and highlight a message row.
+
+## What it does NOT do
+
+- No telemetry, analytics, or tracking. No `fetch`/`XMLHttpRequest`/`WebSocket` calls of
+  its own — all data comes from the DSH runtime's existing connections.
+- No data leaves your browser or machine. Question text is only used to render the
+  panel, to filter, and to copy to your clipboard when you click Copy.
+- No writes to disk, no environment access (the host half has no code), no spawned
+  processes, no native modules.
+
+## Dependencies
+
+- Runtime platform modules only: `react` (peer), plus DSH platform services resolved
+  through the profile's own installation. The bundled client requires exactly
+  `react` and `react/jsx-runtime` — enforced by the build's purity gate and re-checked
+  by `pnpm verify` (require-purity scan).
+- `scripts/link-types.mjs` symlinks local `@deepseek-ai/*` type packages for
+  type-checking only; they are dev-time links, never shipped.
+
+## Verifying
+
+```sh
+pnpm verify
+```
+
+Checks include: exports/files/patch consistency, the loader-wrapper shape of
+`lib/client.js`, absence of absolute machine paths in `lib/`, and that every
+`require(...)` in the bundle is a platform module.
+
+## Reporting
+
+If you find a security issue, please report it privately to the maintainer first
+(open a normal issue if it is not sensitive). See the [publishing guide](publishing-guide.md)
+for release policy.

package/docs/troubleshooting.md

@@ -0,0 +1,65 @@
+# Troubleshooting
+
+## I installed but see nothing
+
+1. **Restart the DSH Web service** — the plugin roster is cached at boot. Installing
+   only writes the profile; the running process keeps its old roster until restart.
+2. Refresh the page afterwards.
+3. **Open a session that already has messages** — the rail intentionally renders
+   nothing on the blank new-session screen (there is nothing to outline yet).
+4. Confirm the plugin is in the profile: `dsh plugin --profile web list`.
+
+## I see the old capsule badge instead of the rail
+
+Your page is still running an old bundle. Refresh the page (Ctrl/Cmd+R). If a stale
+version persists, restart the DSH Web service and refresh again.
+
+## Jumping does nothing / logs "jump failed"
+
+- The target message must be in the **loaded history window** (the panel only lists
+  loaded questions). Click `Load older` first for deeper history, then jump again.
+- Extremely long sessions: if the row does not render within 1.5 s after switching
+  views, the jump is abandoned (a console warning is logged). Retrying usually works.
+
+## The rail overlaps another floating panel
+
+The rail sits on the right edge, vertically centered; the hover panel is an overlay on
+the right side too. If another plugin (e.g. an activity panel) occupies the same area,
+the panel may overlap it while open — close one of them, or open an issue describing
+the conflict so the panel anchor can be tuned.
+
+## `dsh plugin add dsh-conversation-outline` reports "package not found"
+
+The npm path only works **after the package is published to the npm registry**. Until
+then, install from GitHub instead:
+
+```sh
+dsh plugin --profile web add github:lzbaclz/dsh-conversation-outline
+```
+
+## `dsh plugin add` fails on the GitHub path
+
+- The repo **commits `lib/`** — make sure you are not pointing at a fork that deleted
+  the built output (then the exports would not resolve).
+- pnpm version: use pnpm 10+.
+
+## Scratch-profile web boot hangs forever
+
+A fresh scratch profile bundles only `@deepseek-ai/dsh-base`. Add the official
+`@deepseek-ai/dsh-web-app` bundle **by path** from your dsh installation before
+booting (see README → Development). Do NOT add it by package name: the public
+registry only carries the old `0.0.1-rc.1` channel, which mismatches a `0.1.0-rc.x`
+CLI and fails at boot.
+
+## Type errors when building from source
+
+Run `pnpm dev:types` once — it symlinks the `@deepseek-ai` type packages from the
+local dsh profile into `node_modules` (the packages are not re-installable from the
+public registry at their rc channels).
+
+## Hot reload does not trigger
+
+Client-bundle HMR needs the `tsdown --watch` builder rewriting `lib/client.js`, and the
+browser reload chain is always mounted. If it still does not update, refresh the page —
+a plain rebuild plus refresh is the supported fallback. Host-side / manifest changes
+always require a service restart.

package/docs/usage.md

@@ -0,0 +1,62 @@
+# Usage
+
+A full walkthrough of the outline rail and its hover panel.
+
+## The rail
+
+After installing and restarting DSH, open any session that already has user messages.
+A thin vertical strip appears on the right edge, vertically centered:
+
+- **One bar per question**, chronological top→bottom (a conversation minimap).
+- **`+N` marker** at the top when the session has more than 60 questions — older
+  questions fold into it; open the panel and use search / `Load older` to reach them.
+- The rail hides itself on the blank new-session screen (nothing to outline yet).
+
+## Hover preview
+
+- Move the pointer onto the rail: the preview panel slides out to its left, listing
+  every question's opening words (single-line truncated), its `#turn` badge and `HH:MM`
+  time. Mid-turn steering messages carry a `追问` / `steer` tag.
+- Move the pointer away: the panel collapses after a 240 ms grace period (the grace
+  lets the pointer travel from the rail into the panel without flicker).
+- **Touch devices**: tap the strip (between bars) to pin/unpin the panel; `Esc` or the
+  × button closes it.
+
+## Jump to a message
+
+Click a bar on the rail — or a row in the panel:
+
+1. If another view (e.g. Trajectory) is active, the plugin switches back to the Chat
+   view first.
+2. The chat scrolls so the target message sits ~96px below the top.
+3. The message flashes for 1.8 s.
+
+Notes:
+
+- Jumping works only for messages already inside the loaded history window (the panel
+  only lists loaded questions — use `Load older` first for deeper history).
+- `prefers-reduced-motion` disables the smooth scroll and the flash animation.
+
+## Search
+
+Type in the panel's search box: the list filters instantly, case-insensitively, over
+the flattened question text (image attachments count as `[image]`).
+
+## Load older
+
+The `Load older` button appears when older history exists outside the window. It pages
+one history window up via the session's `loadOlder()`; the button greys out while
+loading, and the rail + panel re-derive from the expanded snapshot.
+
+## Copy
+
+Hover a row and click its copy button to copy the full question text (clipboard API,
+with a `document.execCommand` fallback).
+
+## Behavior rules
+
+- The rail follows the **current session**; switching sessions collapses the panel and
+  rebuilds the rail for the new session.
+- New questions appear **live** while the agent runs (the UI subscribes to the session
+  snapshot — no polling).
+- The panel is a pure overlay: the conversation layout never shifts while it is open.