zszz3 · Oct 8, 2026 · Oct 8, 2026
diff --git a/.release-notes/codex-docs-navigation-cleanup.md b/.release-notes/codex-docs-navigation-cleanup.md
@@ -0,0 +1,6 @@
+# 文档导航与使用说明整理
+<!-- release-target: v2 -->
+
+## Bug 修复
+
+- 按使用、开发和排障整理文档入口，修正 CLI 搜索能力说明，避免旧计划被误当作当前功能状态。
diff --git a/README.md b/README.md
@@ -109,7 +109,7 @@ V2 提供独立的[团队空间](docs/v2/team-workspace.md)，按团队集中管
 
 ## 独立 CLI（源码预览）
 
-`agentrecall-cli` 提供独立的 `agentrecall` 命令，可管理多仓库与团队绑定，主动拉取团队 Skill，预览后安装到项目中的 Codex 或 Claude Code。团队默认关闭，无需启动桌面；当前尚未接入桌面端或 Session 分享。构建安装见 [CLI 包说明](./apps/cli/README.md)，配置见 [CLI 使用指南](./docs/v2/cli.md)，资产流程见 [团队 Skill 指南](./docs/v2/team-assets.md)。
+`agentrecall-cli` 提供独立的 `agentrecall` 命令，可管理多仓库与团队绑定，主动拉取团队 Skill，预览后安装到项目中的 Codex 或 Claude Code。团队默认关闭，配置与资产管理无需启动桌面；会话和资源检索连接正在运行的 V2，分别使用 `session search/get` 和 `resource search/get`。会话上传通过 V2 团队空间操作。构建安装见 [CLI 包说明](./apps/cli/README.md)，配置见 [CLI 使用指南](./docs/v2/cli.md)，资产流程见 [团队 Skill 指南](./docs/v2/team-assets.md)。
 
 ## 隐私与安全
 

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -2,7 +2,7 @@
 
 These instructions apply to documentation under this directory. See the [documentation index](README.md) for reading paths.
 
-- User guides explain operations, prerequisites, visible results and limitations. Specs describe the current checkout's behavior and contracts. ADRs explain decisions and consequences. Plans and handoffs record unfinished work, not current product guarantees.
+- User guides explain operations, prerequisites, visible results and limitations. Specs describe the current checkout's behavior and contracts. ADRs explain decisions and consequences. Keep historical plans and handoffs in `project/archive/` with an explicit archival notice; they are not current product guarantees. Do not recreate `docs/superpowers/`.
 - Before changing a spec, inspect its implementation and owning tests. Link to stable source files and tests rather than copying their code or claiming that a test passed because it exists.
 - Each spec states its product scope, behavior, interfaces/ownership, failure and compatibility boundaries, and verification pointers. Explicitly identify unsupported behavior. Do not label an unmerged feature as released.
 - Update the owning spec in the same change when observable behavior, an interface, durable format, or a failure boundary changes. A behavior-preserving refactor only needs a doc change when its source pointers become stale.

diff --git a/docs/README.md b/docs/README.md
@@ -1,24 +1,44 @@
-# 文档入口
+# AgentRecall 文档
 
-用户使用方式从 [项目 README](../README.md)、[V1 指南](v1/guide.md)和 [V2 指南](v2/guide.md)开始。开发前先读 [AGENTS.md](../AGENTS.md) 和 [贡献指南](../CONTRIBUTING.md)，再按改动范围阅读下列文档。
+先按要完成的事情找入口。V1 是稳定版，V2 是独立的预览版；指南中的能力范围以对应产品为准，是否已发布请查看 [Releases](https://github.com/zszz3/AgentRecall/releases)。
 
-| 层次 | 解决的问题 | 入口 |
-| --- | --- | --- |
-| 功能规格 | 当前行为、接口、数据和失败边界是什么 | [spec](spec/README.md) |
-| 架构决策 | 为什么选择这个边界，改变它有什么代价 | [adr](adr/README.md) |
-| 开发约定 | 修改这个模块时必须遵守什么 | [根 AGENTS](../AGENTS.md)及所属目录的 AGENTS |
-| 用户指南 | 如何操作、配置和排障 | [安装](../Install.md)、[团队空间](v2/team-workspace.md)、[团队资产格式](v2/team-assets.md)、[CLI](v2/cli.md) |
+## 使用与排障
 
-规格描述所在代码版本的行为，不代表相关能力已经发布。发布状态以对应产品的 Release 为准。计划、交接和设计草案不作为当前行为的依据；已有计划见 [CLI 团队计划](v2/agentrecall-cli-team-plan.md)，交接记录见 [CLI 交接](v2/agentrecall-cli-handoff.md)。
+| 我想…… | 阅读 |
+| --- | --- |
+| 安装、更新、回滚或卸载 | [安装指南](../Install.md) |
+| 使用稳定版 | [V1 指南](v1/guide.md) · [English](v1/guide.en.md) |
+| 开始使用 V2，搜索和恢复会话 | [V2 使用指南](v2/guide.md) |
+| 连接团队、Pull/Push、分享会话或管理资源 | [团队空间](v2/team-workspace.md) |
+| 编写团队资产清单，了解安装和恢复规则 | [团队资产参考](v2/team-assets.md) |
+| 用命令行配置团队、查询会话和资源 | [CLI 使用与配置](v2/cli.md) |
+| 处理 Electron 安装失败 | [安装排障](troubleshooting-electron-installation.md) |
 
-文档维护规则见 [docs/AGENTS.md](AGENTS.md)。规格与实现不一致时，检查实现和测试后修正文档或代码，不能仅凭旧文档推断运行行为。
+## 开发与维护
 
-## 按开发任务查阅
+首次参与开发先读[贡献指南](../CONTRIBUTING.md)与[仓库约定](../AGENTS.md)，再看所属模块的规格和源码。规格记录当前代码契约，ADR 记录重要选择的原因，两者均不代替本次验证结果。
 
-- 理解整体进程和数据：先读 [架构总览](spec/architecture.md)。
-- 修改会话加载或流畅度：读 [索引](spec/session-indexing.md)和[桌面生命周期](spec/desktop-lifecycle.md)。
-- 修改执行和结果追踪：读 [Runtime](spec/runtime.md)、[Workflow](spec/workflow.md)及 [Eval](spec/evaluation.md)。
-- 修改客户端能力：读 [MCP](spec/mcp.md)与 [Skills](spec/skills.md)。
-- 修改目录知识：读 [Memory](spec/memory.md)；团队共享另读 [团队资产](spec/team-assets.md)。
+| 要修改的范围 | 入口 |
+| --- | --- |
+| 进程、数据归属与模块边界 | [架构总览](spec/architecture.md) |
+| 会话解析、增量索引与查询 | [会话索引](spec/session-indexing.md) |
+| 启动、刷新或长会话卡顿 | [性能检查](v2/performance.md) · [桌面生命周期](spec/desktop-lifecycle.md) |
+| 团队资产、本地视图与同步冲突 | [团队资产规格](spec/team-assets.md) |
+| Agent 执行、工作流与评估 | [Runtime](spec/runtime.md) · [Workflow](spec/workflow.md) · [Eval](spec/evaluation.md) |
+| MCP、Skills、Memory 或服务商配置 | [全部功能规格](spec/README.md) |
+| 理解决策背景与替代方案 | [ADR 索引](adr/README.md) |
+| macOS 打包和验证 | [打包说明](macos-packaging.md) |
 
-规格中的验收表不是已通过的测试报告；当前覆盖范围和跨模块修改矩阵见 [规格索引](spec/README.md)。
+## 文档分工
+
+| 位置 | 保存什么 |
+| --- | --- |
+| `v1/`、`v2/` | 对应产品的使用指南与专题参考 |
+| `spec/` | 当前行为、接口、数据、失败和兼容边界 |
+| `adr/` | 架构取舍与后果；被替代的决定仍保留 |
+| `designs/` | 有明确适用范围与实现边界的专项设计 |
+| `project/archive/` | 不再维护的计划、交接和排查记录 |
+
+[专项设计](designs/README.md)和[历史记录](project/README.md)单独查阅，不作为新用户的上手流程。旧文档地址保留跳转说明；历史任务状态不能用来判断当前功能是否可用。
+
+维护方式见[文档约定](AGENTS.md)。
diff --git a/docs/adr/0007-team-session-blocks.md b/docs/adr/0007-team-session-blocks.md
@@ -2,7 +2,7 @@
 
 ## 状态
 
-已采用于当前开发分支；不表示已经发布。
+已采用；发布状态以 V2 Release 为准。
 
 ## 背景
 

diff --git a/docs/adr/0008-team-session-local-index.md b/docs/adr/0008-team-session-local-index.md
@@ -1,6 +1,6 @@
 # ADR 0008：团队分享复用本地会话索引
 
-状态：已采用，当前开发分支。范围仅为 V2；V1 没有团队空间。
+状态：已采用。范围仅为 V2；V1 没有团队空间。
 
 ## 背景
 

diff --git a/docs/adr/0009-named-provider-configurations.md b/docs/adr/0009-named-provider-configurations.md
@@ -1,6 +1,6 @@
 # 0009：服务商配置使用独立身份
 
-状态：已采用，当前开发分支。
+状态：已采用。
 
 ## 背景
 

diff --git a/docs/adr/0010-resource-folder-metadata.md b/docs/adr/0010-resource-folder-metadata.md
@@ -1,6 +1,6 @@
 # 0010：资源文件夹独立于安装路径
 
-状态：已采用，当前开发分支。
+状态：已采用。
 
 ## 背景
 

diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -10,11 +10,10 @@ ADR 记录重要边界的背景、取舍和后果，当前行为由 [功能规
 | 0004 | [Runtime 调用与原生会话分开记录](0004-runtime-invocation-ledger.md) | 已采用，补录现有实现 |
 | 0005 | [Workflow 恢复绑定现场证据](0005-workflow-recovery-evidence.md) | 已采用，补录现有实现 |
 | 0006 | [长期记忆按目录明确启用](0006-directory-memory-opt-in.md) | 已采用，补录现有实现 |
-| 0007 | [团队会话内容块与分享归属分离](0007-team-session-blocks.md) | 已采用，当前开发分支 |
-| 0008 | [团队分享复用本地会话索引](0008-team-session-local-index.md) | 已采用，当前开发分支 |
-| 0009 | [服务商配置使用独立身份](0009-named-provider-configurations.md) | 已采用，当前开发分支 |
-| 0010 | [资源文件夹独立于安装路径](0010-resource-folder-metadata.md) | 已采用，当前开发分支 |
+| 0007 | [团队会话内容块与分享归属分离](0007-team-session-blocks.md) | 已采用 |
+| 0008 | [团队分享复用本地会话索引](0008-team-session-local-index.md) | 已采用 |
+| 0009 | [服务商配置使用独立身份](0009-named-provider-configurations.md) | 已采用 |
+| 0010 | [资源文件夹独立于安装路径](0010-resource-folder-metadata.md) | 已采用 |
+| 0011 | [分开会话搜索与资源搜索](0011-separate-agent-search.md) | 已采用 |
 
 新增记录包含：状态、背景、决策、影响、考虑的替代方案、关联规格和实现。编号不复用；废弃决策保留并指向替代记录。只在进程边界、数据归属、持久化兼容或团队冲突策略发生重要变化时新增或修订，不为每次修复创建 ADR。维护规则见 [文档约定](../AGENTS.md)。
-
-- [0011：分开会话搜索与资源搜索](0011-separate-agent-search.md)
diff --git a/docs/designs/README.md b/docs/designs/README.md
@@ -0,0 +1,5 @@
+# 专项设计
+
+这里保留具有独立接口和边界说明的专项设计。阅读时先看每篇的状态；底层接口已经实现并不表示桌面已有操作入口。当前模块总览见[功能规格](../spec/README.md)，旧计划与交接见[历史记录](../project/README.md)。
+
+- [Workflow 克隆与导入导出](2026-07-29-workflow-clone-import-export-design.md)：领域和 IPC 契约，以及尚未接入当前界面的边界。
diff --git a/docs/legacy-update-self-contained-plan.md b/docs/legacy-update-self-contained-plan.md
@@ -1,58 +1,5 @@
 # Legacy Update Self-Containment Implementation Plan
 
-**Goal:** Keep one-click upgrades from legacy AgentRecall releases working while removing the bundled Electron bridge from published tarballs.
+本文已移入[历史记录](project/archive/legacy-update-self-contained-plan.md)，不再作为当前使用或开发状态的入口。
 
-**Architecture:** During `stageUpdate`, npm installs the release archive under a temporary prefix. The package's postinstall detects that staging environment, copies hoisted production dependencies from the prefix into the staged `agent-recall/node_modules`, and skips all user configuration work. The legacy updater can then atomically move only the package directory without losing runtime dependencies.
-
-**Tech Stack:** Node.js CommonJS lifecycle script, npm package lifecycle, Node test runner, Vitest, macOS/Windows CI.
-
-## Global Constraints
-
-- Legacy releases from v0.31.3 onward must be able to update directly to the latest release.
-- Normal npm installs must keep their current Claude statusline behavior.
-- Staging installs must not read or write the user's Claude configuration.
-- Published archives must not bundle Electron; staging must validate self-contained runtime dependencies before reporting success.
-- All installation tests use temporary HOME, npm prefix, cache, and fixtures.
-
-### Task 1: Specify and test staged dependency materialization
-
-**Files:**
-- Create: `scripts/staged-package-dependencies.test.mjs`
-- Modify: `package.json`
-
-- [ ] Write a failing test that creates a synthetic staging `node_modules` with scoped and unscoped dependencies, invokes the lifecycle helper with `AGENT_RECALL_STAGING_INSTALL=1`, and asserts that runtime dependencies exist under `agent-recall/node_modules` while `agent-recall` itself and `.bin` are not recursively copied.
-- [ ] Run `node --test scripts/staged-package-dependencies.test.mjs` and confirm it fails because the lifecycle helper does not exist.
-- [ ] Add an assertion that `package.json` no longer declares bundled dependencies, so the test fails if the archive bridge is restored.
-
-### Task 2: Implement staging-only self-containment
-
-**Files:**
-- Create: `bin/prepare-staged-package-dependencies.cjs`
-- Modify: `bin/install-claude-statusline.cjs`
-- Modify: `package.json`
-
-- [ ] Implement `materializeStagedPackageDependencies({ stageRoot, packageRoot })` to copy all entries from `<stageRoot>/node_modules` into `<packageRoot>/node_modules`, excluding `.bin`, `.package-lock.json`, and `agent-recall`; recurse through scoped packages.
-- [ ] In `postinstall`, detect `AGENT_RECALL_STAGING_INSTALL=1`, run the materialization helper with `AGENT_RECALL_STAGE_ROOT`, and return before statusline configuration.
-- [ ] Remove `bundleDependencies` from the package manifest.
-- [ ] Re-run the focused test until it passes.
-
-### Task 3: Validate the updater boundary
-
-**Files:**
-- Modify: `bin/update-client.cjs`
-- Modify: `scripts/update-client.test.mjs`
-- Modify: `scripts/package-smoke.mjs`
-
-- [ ] Write a failing `stageUpdate` test asserting that staged `electron-store` resolves from the staged package path before update success is returned.
-- [ ] Add the corresponding runtime dependency validation in `stageUpdate`, using Node resolution from `stagedPackagePath` and a readable failure message.
-- [ ] Extend package smoke validation to assert that a built archive does not contain a bundled Electron dependency, while standard isolated npm installation remains launchable.
-- [ ] Run focused script tests and package smoke using only temporary installation paths.
-
-### Task 4: Release and regression verification
-
-**Files:**
-- Create: `.release-notes/self-contained-legacy-update.md`
-
-- [ ] Add a user-facing bug-fix note explaining that older installations can update without requiring a larger download package.
-- [ ] Run `npm run typecheck`, `npm test`, `npm run package:smoke`, `npm run release-note:check`, and `git diff --check`.
-- [ ] Commit the implementation only after all checks pass; if npm 12 blocks an existing unrelated test, record that exact failure separately from this change's focused checks.
+当前行为见[文档导航](README.md)和[功能规格](spec/README.md)。
diff --git a/docs/project/README.md b/docs/project/README.md
@@ -0,0 +1,12 @@
+# 项目历史记录
+
+这里保存曾用于开发的计划、交接和排查背景，不维护当前进度，也不作为功能承诺。当前使用方式见[文档入口](../README.md)，当前契约见[功能规格](../spec/README.md)，发布内容见 [Releases](https://github.com/zszz3/AgentRecall/releases)。
+
+| 记录 | 用途与限制 |
+| --- | --- |
+| [CLI 与团队功能计划](archive/agentrecall-cli-team-plan.md) | 保留早期任务拆分；完成状态与项目模型可能已过时 |
+| [CLI 与团队功能交接](archive/agentrecall-cli-handoff.md) | 保留当时的工作区和验证背景；不再约束当前分支或合并操作 |
+| [Runtime 配置与 Agent 删除排查](archive/runtime-config-agent-delete-integrity.md) | 解释历史数据引用问题；当前规则见 Runtime 规格 |
+| [旧版更新包自包含计划](archive/legacy-update-self-contained-plan.md) | 保留更新兼容方案；不是当前发布操作清单 |
+
+需要推进新工作时，在对应任务或 PR 中记录待办和验证结果。行为定稿后更新所属指南或规格；重要架构取舍进入 ADR，不把一次任务的执行过程追加到使用指南。