personal-bot 0.2.8 → 0.2.9

package/CONTEXT.md

@@ -1,100 +1,81 @@
 # Personal Bot 领域术语
 
-用于学习与知识积累、任务与项目推进、研究与决策支持。投资是专业应用领域，相关术语保留其投资含义。
+## 资料与接入
 
-## 研究与接入
+**项目**：围绕明确任务保存的目标、资料、结论与交付物。研究项目还包括假设和实验。
 
-**项目**：围绕有明确完成条件的任务保存的目标、过程、证据和结论。研究项目还保存相关假设和实验。
+**长期事务**：持续维护的目标、约束、决策依据与复盘，可关联多个项目；投资事务保留相应市场与持仓约定。
 
-**长期事务**：持续维护的目标、已确认约束、决策依据和复盘，可以引用多个项目。
+**专业方法**：按任务选择的研究、计算、分析或复核方法，包含适用条件与判断依据。
 
-**长期投资事务**：持续维护的投资目标、已确认约束、决策依据和复盘，可以引用多个研究项目。
+**工作区**：组织资料和开展工作的目录范围。两种宿主共享业务资料与历史归档，各自管理原生会话、配置和运行状态。
 
-**回测实验**：在明确历史数据、策略规则与交易假设下进行的一次检验。结果只适用于记录的条件。
+**工作区记忆**：跨会话查找、使用与修正资料的能力，同一主题维护一份当前正文。
 
-**交易机会分析**：结合目标、市场与持仓约束比较候选行动。等待与证据不足也是有效结论。
+**历史消息树（history）**：问答原文、分层摘要、父子关系和来源引用组成的检索资料。完整工具日志、图片与会话恢复由原生存储负责。
 
-**专业方法**：开展学习、任务、研究或复核时使用的方法、判断依据和适用条件，不是所有任务必须经过的固定阶段。
+**资料维护**：根据任务进展更新相关说明，归集成果，提炼可复用的方法与口径。
 
-**投资偏好**：用户对风险、仓位、收益、持有期限等事项的个人要求。它补充和约束专业判断，不是助手开展分析或提出方案的前置条件。
+**能力提供方（provider）**：通过 CLI 或 MCP 提供查询、计算或业务操作的外部系统；代码中的 `src/services/` 则是插件自身的业务服务。
 
-**工作区记忆**：跨会话查找、使用和修正所属资料的能力。正文只维护一份；保留的知识不证明当前事实、软件可用性或操作授权。
+**原生接入**：使用 CLI 的命令与认证，或宿主的 MCP 配置、工具发现与调用。
 
-**历史消息树（history）**：由问答原文、分层摘要、父子关系及来源引用组成的历史资料，供两个宿主共同检索。各宿主维护自己来源的历史；它不包含完整工具日志、推理或图片二进制，也不用于恢复另一宿主的会话。
+**提供方手册**：外部系统的使用入口，记录接口用途、数据口径、配置位置、限制与来源。
 
-**项目资料维护**：根据已有工作结果与证据，整理和更新当前任务、直接关联资料及进行中任务的资料，由助手判断相关内容是否更新完整。可由用户主动发起，或由助手在正常交互中识别更新需要。
+**调用约定**：当前工具版本的输入、结果与执行要求。
 
-**能力提供方（provider）**：通过 CLI 或 MCP 提供数据查询、计算或业务操作的外部系统。它不同于 `src/services/` 中的业务服务。
+**Personal Bot 启用**：宿主按原生配置加载扩展。资料准备使用可选的 `/pbot init`。
 
-**原生接入**：复用 CLI 的命令与认证，或使用当前宿主原生的 MCP 配置、工具发现与调用。Personal Bot 不保存另一套操作目录或逐工具权限。
+**配套插件**：独立安装的附加能力。所需外部服务按该插件的流程准备。
 
-**受控变更**：经精确准备、必要复核和用户授权后执行的业务状态改变。交易是其中一类，不代表全部变更。
+**配套插件清单**：安装器展示的候选集合；用户选择本次安装项，未选中的已有插件保留。
 
-**接入知识**：对具体能力提供方的接口、调用方法、数据含义、限制及已验证事实的理解。知识不证明当前可用性，也不授予操作权限。
+## 专家与团队
 
-**能力提供方使用手册**：汇集一个能力提供方的接入知识、资料依据和验证记录的文档。
+**协调者**：主会话助手，负责分析、任务组织、专家协作和结果跟踪。
 
-**调用约定**：原生操作的输入、结果与执行要求，按当前版本的帮助或协议定义核对。
+**通用专家（general-purpose）**：具有独立上下文和任务归属的子会话，在委派范围内完成研究、实现、计算或复核。工作区可在 `agents/general-purpose.md` 补充职责，协调者对应 `agents/coordinator.md`。
 
-**工作区**：组织学习资料、长期事务、项目、能力接入与执行记录的工作范围，用途可以组合，投资任务可覆盖多个市场。业务约定、用户资料和历史消息树可以跨宿主使用，原生会话与运行状态独立保存。
-_避免_：用工作区表示单个会话或真实账户。
+**子会话（agent）**：由 start 创建，以 agentId 标识，绑定所属宿主、父会话和分支。存活时可 send，停止后用 resume 携新要求恢复。
 
-**Personal Bot 启用**：当前宿主按原生配置加载 Personal Bot 扩展。没有独立的工作区就绪状态；资料和外部服务是否准备好不影响加载，也不证明某项能力可用或已获执行许可。
+**团队（team）**：同一父会话中的固定成员、共同目标与公共记录，以 teamId 标识。关闭团队保留成员与历史。
 
-**配套插件**：与 Personal Bot 配合提供附加能力、可独立安装的组件。其依赖的外部服务不属于插件本体，安装插件不代表服务已准备好。
+**团队批次（team run）**：以 runId 标识的有限轮次。roundRobin 按成员顺序执行；parallel 同轮并行，完成后进入下一轮。继续讨论使用新批次。
 
-**配套插件清单**：维护者为 Personal Bot 安装提供的候选插件集合，用户从中选择本次需要的插件。清单不等同于工作区实际安装内容；移出清单不表示卸载已有插件。
+**工作周期（cycle）**：子会话一次受管工作，以 cycleId 标识，可处理多条消息。结果通过对应周期报告查看。
 
-## 任务管理
+**消息请求（request）**：以 requestId 标识的一条输入，按接纳、消费和完成记录状态。
 
-**Task Conductor**：主会话通过原生 MCP 使用的独立任务系统，拥有周期、重复流程、DAG 和持久执行状态，不经 pbot 专家转发。taskId 标识任务定义，runId 标识一次执行，节点 ID 标识 DAG 节点，三者不能互换，也不与 pbot 子会话的 agentId 或工作周期 cycleId 混用。
+**专家交付**：本次任务的报告、产物与来源引用；要求修改文件时包含约定范围内的修改。
 
-**定时任务**：由 Task Conductor 按获授权的频率和时区触发的任务。每轮明确数据来源、期间与时点；文档记录周期不代表已经设置调度，任务本身不授予交易执行许可。取消当前执行与停止未来周期是不同操作。
+**独立复核**：由新专家会话或独立 Task Conductor 节点，根据原始资料核验具体方案。复核者沿用通用专家类型，复核要求由任务决定。
 
-## 角色与执行
+## 外部任务与操作
 
-**协调者**：协助用户学习和积累知识、推进任务与项目、开展研究并支持决策的主助手，负责方案建议、专家协作和已授权操作的结果跟踪。
+**Task Conductor**：通过原生 MCP 使用的独立任务系统，管理周期、重复流程、DAG 与持久执行状态。taskId 对应任务定义，runId 对应一次执行，节点 ID 对应 DAG 节点；与 pbot 的标识分别使用。
 
-**通用专家（general-purpose）**：pbot 唯一可委派类型，在具有独立上下文和任务归属的子会话中完成研究、分析、计算或独立复核，按任务选择专业方法。start 使用新上下文，send 可继续既有上下文；独立复核须新建会话，通用职责不扩大委派范围或用户授权。
+**定时任务**：由服务按约定频率和时区触发，每轮明确数据期间与执行范围。当前执行与未来周期分别停止。
 
-**独立复核者**：在新会话或独立任务节点中核验具体方案的事实与约束，给出通过、拒绝或无法确认结论的助手，不是另一个可委派的 pbot 角色类型。
+**用户授权**：用户请求或明确确认的操作范围与条件。交易、转账和账本修改需在相应授权范围内执行。
 
-**专家协作**：保留独立委派与团队工作。协调者组织和验收，团队成员可直接交换原文；轮流讨论或并行轮次由代码安排，不依赖协调者模型逐条转述。它不规定固定研究流程，不替代用户授权，也不承载 Task Conductor 的持久调度。
+**受控变更**：按任务完成准备、必要复核与用户授权后执行的业务状态改变。
 
-**团队（team）**：同一父会话中的固定成员和公共记录，以 teamId 标识。成员仍有各自的私人会话上下文；团队关闭不销毁成员或清除记忆。
+**执行意图、尝试与回执**：分别指操作准备、进入执行阶段和外部工具返回的结果。
 
-**团队批次（team run）**：以 runId 标识的一批有限轮次，采用 roundRobin 或 parallel。后者同轮并行、轮间汇合；结束不代表业务完成，暂停或恢复不自动重跑旧请求。该 runId 与 Task Conductor 的 runId 分属不同系统。
+**未知结果**：操作可能已经生效而结果尚不清楚的状态。先按原业务标识查询，再决定后续动作，避免重复执行。
 
-**专家职责**：通用专家 general-purpose 的工作范围与交付责任，不是子会话实例标识。工作区仅 coordinator.md 和 general-purpose.md 的职责补充会被加载。
+**人工结案**：用户核对外部事实后保存处理结论，结束待核对事项。
 
-**子会话（agent）**：由 start 创建、以 agentId 标识的独立专家会话，绑定父会话与创建分支，归属创建它的宿主。工作结束后可用 send 继续对话；停止后用 resume 携新要求显式恢复，不重放旧工作，也不跨宿主接管。
+## 投资研究
 
-**工作周期（cycle）**：子会话从开始处理到本轮结束的一次活动，以 cycleId 标识。一个周期可处理多条消息；空闲状态不代表上轮工作成功。
+**投资偏好**：用户对风险、仓位、收益、持有期限等事项的要求。
 
-**消息请求（request）**：父侧提交的一条子会话消息，以 requestId 标识。入队或接收不证明模型已阅读或任务已完成。
+**回测实验**：使用记录的数据、策略规则、市场约束与交易假设检验策略。
 
-**专家交付**：专家为本次委派提供的报告、证据与产物引用；用户指令明确要求修改资料时，也可包含相应的资料修改。
+**交易机会分析**：结合目标、市场与持仓约束比较候选行动，可得出继续研究或等待的结论。
 
-**独立复核**：由新通用专家会话或独立 Task Conductor 节点，根据原始依据核验具体方案，可覆盖多个操作。不能用 send 或 steer 把原分析会话改称独立复核。它属于方案层面的工作约定，不是单次工具调用的程序门槛，也不替代用户授权；任务协调器验收不等于专业复核。
+**候选合约**：参与当前分析与比较的具体期权合约。
 
-**候选合约**：参与本次比较的具体期权合约，尚不表示可交易。
+**交易方案**：包含对象、方向、数量、价格条件及约束的行动建议。
 
-**交易方案**：包含对象、方向、数量、价格条件及约束的具体行动建议。
-
-**交易复核**：对具体方案的规则、数据、持仓、计算和订单约束进行独立核验。复核通过不代表用户授权。
-_避免_：将批准与授权混用。
-
-**复核证据**：本次核验的规则、数据、计算和订单依据，包含来源与时间。
-
-**用户授权**：用户请求或明确确认的业务范围与条件。工具可用、研究请求和复核通过不自动授权业务变更。
-
-**执行意图**：包含目标、参数和约束的具体操作准备，不表示已获许可或已发送。
-_避免_：用订单指尚未发送的意图。
-
-**执行尝试**：一次操作进入执行阶段的事实，不证明外部能力提供方已收到或执行。
-
-**执行回执**：外部工具返回的结果，不必然证明成功或成交。
-
-**未知执行义务**：调用可能已生效但结果无法确定的待核对事项，不自动阻塞其他调用，也不授予重发许可。后续操作仍须符合当前任务授权；不能从未知结果推断没有副作用。
-
-**人工结案**：用户核对外部事实后记录处理结论，结束该未知义务的核对事项，不授权重发操作。
+**交易复核**：核验方案的规则、数据、持仓、计算与订单约束，保留所用依据和时间。执行仍遵循用户授权。

package/README.md

@@ -4,13 +4,13 @@ English | [简体中文](README.zh-CN.md)
 
 **A personal assistant connecting knowledge, research, and action.**
 
-Personal Bot provides a workspace-scoped [Pi](https://pi.dev) extension and a native dsh Web integration. It supports learning, project work, research, decision support, investment analysis, and explicitly authorized operations. See the [dsh guide](docs/dsh.en.md) for installation, commands, and acceptance limits.
-
-The model handles analysis, coordination, and native tools. Personal Bot adds workspace materials, specialist collaboration, and Python environment preparation. It does not create a second main agent or start tasks or trades automatically.
+Personal Bot provides a workspace-scoped [Pi](https://pi.dev) extension and a native dsh Web integration for organizing materials, project work, research, specialist collaboration, and authorized operations. The model handles analysis and coordination; the plugin adds workspace materials, specialist sessions, history search, and a shared Python environment.
 
 ## Install
 
-The Pi installer supports Linux and macOS. It requires Node.js 22.19+, npm, and Python 3.11+ with venv/ensurepip. Run in an interactive terminal:
+### Pi setup wizard
+
+Linux and macOS require Node.js 22.19+, npm, and Python 3.11+ with venv/ensurepip. Run in an interactive terminal:
 
 ```bash
 npx personal-bot@latest setup
@@ -18,191 +18,131 @@ npx personal-bot@latest setup
 npx personal-bot@latest setup --workspace ~/pbot-workspace
 ```
 
-The wizard selects an existing or new directory, installs or updates the shared Pi executable, and installs pbot in that workspace. It offers `task-conductor-plugin` and `pi-web-access`, both selected by default on the first installation. Later runs preselect existing packages. Each normal npm package updates to its latest stable version. Local sources, Git sources, and pinned versions are kept unless you choose to switch. Deselecting a plugin or removing it from the maintained catalog does not uninstall it.
+The wizard selects or creates a directory, installs or updates Pi, and installs Personal Bot for that workspace. Task Conductor and Pi Web Access are selected by default on the first installation; later runs preselect installed plugins. Ordinary npm sources update to the latest stable version. Local, Git, and pinned sources are kept by default, with an option to switch. Deselecting a plugin preserves its installation.
 
-Missing tmux is installed through an existing Homebrew or supported Linux package manager. Missing Python prerequisites produce repair instructions. pbot prepares its shared Python venv on startup. After installation, the wizard offers to start Pi and run `/pbot init`; the existing command owns workspace material creation. Pi handles project trust, login, and model selection. Installation does not call a model.
+Missing tmux is installed through an existing Homebrew or supported Linux package manager. Missing Python prerequisites produce repair instructions. After installation, the wizard can start Pi and run `/pbot init`. Follow Pi's prompts for project trust, login, and model selection.
 
-For a persistent short command, install the package separately:
+For a persistent short command, install the CLI globally:
 
 ```bash
 npm install -g personal-bot@latest
 pbot setup
 ```
 
-This global npm installation provides the command; it does not register a global Pi extension. `pbot setup` uses the globally installed installer version. Update it with npm, or use `npx personal-bot@latest setup` for the latest installer. The npx command does not install itself globally.
-
-A core failure stops startup. If a configured Git or local directory source is missing or has no identifiable package name, setup stops and asks you to repair the source through Pi; it preserves the declaration. Existing standalone extension files remain supported. An optional plugin failure allows the other plugins to proceed and is reported before you choose whether to start Pi. Completed steps remain in place; fix the cause and rerun setup. There is no automatic rollback across package managers. See the [installation design](docs/installation-design.md) for scope and recovery rules.
+Update this command through npm; Pi manages the workspace extension. If installation fails, fix the cause and rerun setup. Completed steps and existing materials are preserved. An optional plugin failure still allows you to start Pi.
 
-### Install directly with Pi
+### Existing Pi installation
 
-If Pi is already installed, run from your workspace root:
+Run from the workspace root:
 
 ```bash
 pi install --local npm:personal-bot
 pi
 ```
 
-`--local` saves the package declaration in the project's `.pi/settings.json`. Review and grant project trust when Pi prompts you, and start Pi from the workspace root. Loading Personal Bot enables its roles, skills, tools, and shared Python environment preparation. There is no separate activation switch.
-
-Use `pi install` without `--local` only when you want the extension in every Pi session. Use Pi package management or `pi config` to adjust an existing installation's scope. Do not load both the npm and source installations. The development and test baseline is Pi 1.5.0; installer acceptance limits are recorded in [validation](docs/validation.md).
-
-### Install from source
-
-To try the installer from source:
-
-```bash
-git clone https://github.com/realqiyan/personal-bot.git
-cd personal-bot
-npm ci --ignore-scripts
-npm run build:cli
-node bin/pbot.mjs setup
-```
-
-To load only the source extension:
-
-```bash
-cd /path/to/workspace
-pi install --local /absolute/path/to/personal-bot
-pi
-```
-
-Replace the example paths with your actual paths. A local installation loads the source directory directly, so keep that directory and its dependencies available.
+`--local` saves the declaration in the project's `.pi/settings.json`. Start Pi from that workspace root. Loading the package enables roles, skills, tools, and Python preparation. Use a global extension installation only when you want it in every Pi session. Manage existing sources with `pi list` or `pi config`, keeping one active source per package.
 
-### Use with dsh
+### dsh
 
-Use the latest dsh release with Node.js 24.9+ (or the newer minimum declared by that release), npm, pnpm, and Python 3.11+. `pbot setup` installs for Pi; dsh uses its native profiles and plugin manager. Run in a terminal:
+You need Node.js 24.9+, npm, pnpm, and Python 3.11+. Follow the installed dsh release's `engines` if it requires a newer runtime. Use its native profiles and plugin manager:
 
 ```bash
 npm install -g @deepseek-ai/dsh@latest pnpm@latest
-dsh --version
-pnpm --version
-# First creation only: this replaces an existing profile of the same name.
+# First creation only; this replaces an existing profile of the same name.
 dsh --profile pbot --from-default-profile web --dump-config
 dsh plugin --profile pbot add personal-bot@latest
 dsh --profile pbot
 ```
 
-The last command starts the Web server and normally opens a browser. Select your workspace and main session there, then configure models and authentication in dsh's native settings. In the chat input, use `/pbot` to open the workspace, specialist, team, and history tabs; `/pbot status` checks the workspace and Python environment; `/pbot init` optionally creates missing material directories. Loading the plugin and these checks do not call a model.
+In the browser, select a workspace and main session, then configure models and authentication. Enter `/pbot` in chat to open management, `/pbot status` to inspect state, or `/pbot init` to prepare materials.
 
-For subsequent starts, run `dsh --profile pbot`. After stopping active specialists and the server, update the host and plugin separately:
+For later starts, run `dsh --profile pbot`. Stop active specialists and the server before updating the plugin:
 
 ```bash
-npm install -g @deepseek-ai/dsh@latest
 dsh plugin --profile pbot update personal-bot --latest
-dsh plugin --profile pbot list personal-bot --depth 0
-dsh --profile pbot
-```
-
-Do not repeat `--from-default-profile` during updates. For the desktop application, install and manage `personal-bot@latest` through its native Plugins page; the npm CLI's `pbot` profile and the application's `desktop` profile are separate.
-
-The [full English guide](docs/dsh.en.md) ([中文](docs/dsh.md)) covers launcher options, plugin inspection and removal, source tarballs, every `/pbot` subcommand, JSON parameters, and examples. Specialists use native Agent/Session instances in the server process; refreshing a page does not stop accepted work. Pi and dsh query shared history archives while owning their own sessions, models, authentication, and MCP configuration. The tested dsh baseline is `0.2.2-rc.1`; `latest` can change and does not imply that future releases have passed acceptance. See the [validation record](docs/validation.md).
-
-### Optional: Task Conductor
-
-For scheduled tasks, recurring workflows, or DAGs, use the optional `task-conductor-plugin` and its shared `using-task-conductor` skill. The plugin and the `task-conductor` service are installed separately. Follow the [upstream integration guide](https://github.com/realqiyan/task-conductor/blob/master/docs/host-integrations.md) for service setup, connection settings, and updates.
-
-**Pi:** Check `pi list` for an existing installation and its resource settings. For the published Pi integration, run from the workspace root:
-
-```bash
-pi install --local npm:task-conductor-plugin
 ```
 
-For unreleased plugin changes, use `pi install --local /absolute/path/to/task-conductor/plugin` instead. Keep one source enabled. Run `/reload` in Pi, then `/skill:using-task-conductor`. The skill covers service installation, `task-conductor setup`, and Pi's native MCP registration. `--local` limits plugin loading; choose MCP scope separately and reuse existing connections.
+The desktop application installs `personal-bot@latest` through its native Plugins page and uses a separate desktop profile. See the [dsh guide](docs/dsh.en.md) ([中文](docs/dsh.md)) for launcher options, updates, and chat commands.
 
-**dsh:** The native Host integration is included in the unpublished Task Conductor `0.1.6` release candidate. Until publication, build the plugin and matching service from that source, then install the plugin tarball into your existing Web profile:
+### Use from source
 
 ```bash
-cd /absolute/path/to/task-conductor
-npm run pack:plugin
-dsh plugin --profile pbot add /absolute/path/to/task-conductor/task-conductor-plugin-<version>.tgz
-dsh plugin --profile pbot list task-conductor-plugin --depth 0
+git clone https://github.com/realqiyan/personal-bot.git
+cd personal-bot
+npm ci --ignore-scripts
+npm run build:cli
+node bin/pbot.mjs setup
 ```
 
-Use the actual tarball path printed by the packaging command. Restart `dsh --profile pbot`, open the main session, and invoke `/using-task-conductor`. The plugin provides the shared skill through native filesystem discovery and creates a native MCP connection for each root main session, using that session's working directory. Tools retain names such as `mcp__task-conductor__executor_list`; avoid adding a duplicate manual connection. The desktop application's native Plugins page accepts the same local tarball; its profile is separate. See the [dsh Task Conductor guide](docs/dsh.md#task-conductor) for the matching local service build and setup.
-
-The service keeps its own coordinator model configuration and `pi-durable` runtime. Using dsh as the host does not require the interactive Pi CLI. To also run task nodes with dsh, register the canonical absolute dsh executable through Task Conductor's admin CLI or Web interface as custom executor `dsh-acp`, with arguments `["--profile", "acp"]`. Follow the upstream skill's [custom ACP instructions](https://github.com/realqiyan/task-conductor/blob/master/plugin/skills/using-task-conductor/references/custom-acp.md); `dsh` is not a built-in executor ID. Nodes use their own dsh profile, authentication, tools, and environment.
+To load only the Pi source extension, run `pi install --local /absolute/path/to/personal-bot` from the workspace and keep that source directory and its dependencies available. For dsh, follow the [source installation steps](docs/dsh.en.md#installing-from-source).
 
-Notifications return to the originating persistent host session; resume that session to receive pending events. Closing Pi or dsh does not stop service tasks. Update the plugin and service separately, following upstream instructions to check active work, stop the service, and back up its data. Keep credentials in your terminal or private files. Use the skill's native tool discovery and read-only connection checks; these do not establish successful model execution or task delivery.
+### Optional: Task Conductor
 
-## Optional workspace preparation
+Use `task-conductor-plugin` for schedules, recurring workflows, DAGs, and tasks that continue after the host exits. Install the plugin and its service separately, following the [upstream integration guide](https://github.com/realqiyan/task-conductor/blob/master/docs/host-integrations.md).
 
-Personal Bot works without initialization. Run `/pbot init` only if you want the standard material layout. It creates missing material directories and a missing root `AGENTS.md`; it does not overwrite files or start model tasks. In Pi, the new `AGENTS.md` enters native context after `/reload` or the next startup. The bundled directory guide is available from the first task.
+Pi users run `pi install --local npm:task-conductor-plugin` from the workspace, reload, then read `/skill:using-task-conductor`. dsh users follow the [Task Conductor setup](docs/dsh.en.md#task-conductor) and read `/using-task-conductor` in the main session.
 
-Keep goals, markets, preferences, and working agreements in ordinary documents. Ask the assistant to organize them as needed. For external tools, provide the CLI/MCP name, purpose, official documentation, or configuration location—not credential values.
+Notifications return to the session that submitted the task. Service tasks continue after Pi or dsh closes. Query and stop the current run and future recurrences separately.
 
 ## Daily use
 
-Describe the task directly: organize project materials, compare research findings, delegate an independent review, or run calculations. No fixed workflow is required. The command table and process details below describe Pi; see the [dsh guide](docs/dsh.en.md) for its Web interface and commands.
+Describe the task directly: organize materials, compare findings, delegate a review, or run calculations. These commands are for Pi; dsh commands are in its guide.
 
 | Command | Purpose |
 | --- | --- |
 | `/pbot` | Open the workspace menu |
 | `/pbot init` | Create missing material directories and root `AGENTS.md` |
-| `/pbot status` | Show workspace path, Personal Bot version, and Python environment status |
-| `/pbot history [text]` | Search historical exchanges and summaries; read originals and navigate their parents and children |
-| `/pbot agents` | Inspect specialists; enter sessions, send instructions, rename, or stop tasks |
-| `/pbot teams` | Inspect teams and public messages; start rounds, pause, close, or open members |
-| `/pbot python setup` | Retry shared venv preparation and activation; no path argument needed |
+| `/pbot status` | Inspect workspace, version, and Python state |
+| `/pbot history [text]` | Search exchanges and summaries, then read originals |
+| `/pbot agents` | Inspect, enter, rename, stop, or send instructions to specialists |
+| `/pbot teams` | Inspect teams and public messages; start rounds, pause, or close |
+| `/pbot python setup` | Retry shared Python preparation |
 | `/reload` | Pi's native command to reload extensions and resources |
 
-- **Native tools:** Use CLI commands through Bash with their current help. Keep concise provider guides and evidence references. Configure MCP for the current project by default: run `pi mcp add --local <server> ...` from the workspace root to write `.pi/mcp.json`, then inspect the configuration source with `/mcp`. Change user-level configuration only when cross-project use is explicitly requested. No Personal Bot registration, parameter binding, or permission table is needed. See the [connection skill](resources/skills/provider-connections/SKILL.md).
-- **History:** No session naming is required. Browse with `/pbot history`, or ask the assistant to look something up. `pbot_history` searches originals and summaries and follows parent/child references. Groups of four consecutive exchanges form a summary tree. Originals are searchable first; after a main interaction ends, the current Pi model builds pending summaries one at a time, including older discovered sessions. This makes extra model calls. New input cancels this work; a later idle period resumes it. Loading and searching make no model calls. Exchanges and summaries are stored in the workspace at `.pi/pbot/history/` and remain searchable when copied to another machine. Existing user-level indexes are copied into the workspace, keeping the old copies. See [history](docs/history.md).
-- **Research and analysis:** Ask the assistant to synthesize evidence, explain conflicts, check calculations and definitions, or identify assumptions to validate first.
-- **Independent sub-sessions:** Personal Bot supports tmux and independent Pi sessions; install tmux on the system to use them. `pbot_agent start` returns immediately; without a message, prompts, or files it creates an idle process without calling a model. Task completion produces a notification. Options cover models, directories, files, tools, and resources. Operations include send, follow-up, rename, status, read, stop, and explicit resume; there is no foreground/background flag or wait operation. `/pbot agents` shows active agents and can open their TUI. Main-session reload preserves running agents; exit or session switching stops them and retains history. Sub-sessions use native CLI/MCP within their delegated scope. See [specialist collaboration](docs/agent-collaboration.md).
-- **Teams:** `pbot_team` groups existing agents for `roundRobin` discussion or `parallel` rounds. Members exchange original messages through `pbot_team_message`; ordinary posts do not wake models. A running team reserves its members. Pause and drain in-flight work before private messages; reload pauses teams without replaying requests. The first release uses fixed membership and bounded rounds, not dynamic ask/reply wake-ups. See [specialist collaboration](docs/agent-collaboration.md).
-- **Scheduled and durable tasks:** The main session uses optional Task Conductor directly through native MCP, its `using-task-conductor` skill, and actual tool contracts. Without it, ordinary Personal Bot features still work, but scheduling is unavailable. Personal Bot adds no durable task scheduler or forwarding layer. Query and stop external tasks separately from sub-sessions. Cancelling the current run does not stop future recurrences, and closing Pi or dsh does not imply that external tasks stopped.
-- **Python:** All workspaces share one dedicated venv for the current user. Loading Personal Bot creates or updates it with locked dependencies and activates it in the current Pi process. Main and specialist sessions use `python` or `python3` through Bash. Failures are reported; fix the cause and retry with `/pbot python setup`. System Python, external terminals, existing scripts, and historical results are not changed. Shared dependency updates affect other workspaces, so stop relevant scripts before changing plugin versions or retrying setup. See the [Python guide](python/README.md) and [computation reference](resources/references/compute.md).
-- **Material maintenance:** Ask to organize project materials, reproduce a report using its previous definitions, or review delivery and close a task. The [project maintenance skill](resources/skills/project-maintenance/SKILL.md) updates the current task and affected materials within your requested scope. Current guidance is consolidated by topic, with reusable methods and analysis definitions extracted from project conclusions. Sources and important decisions remain traceable. Cleanup removes unnecessary temporary outputs within scope, not formal materials, history, or backups.
-
-Main and child transcripts use Pi's native session storage. Use `pi --resume` to select a chat explicitly; `pi --continue` may select the most recently active child. Enter managed children through `/pbot agents`; stopped children reopen their saved session idle, without calling a model. Use `pbot_agent resume` to restart with a new instruction. Never open a second writer for a running child's session file. Do not resend a potentially side-effecting operation merely because a session resumed.
+- **Material preparation:** `/pbot init` is optional. It creates missing items and preserves existing files. In Pi, a new root AGENTS file loads after `/reload` or the next startup.
+- **Native tools:** Use CLI tools through Bash and MCP through the host's configuration. Add Pi project connections with `pi mcp add --local <server> ...` and inspect their source with `/mcp`. See the [connection skill](resources/skills/provider-connections/SKILL.md).
+- **History:** Pi and dsh query shared workspace archives. Originals are searchable first; after a main interaction, the current model fills pending summaries through additional model calls. New input cancels that work first. See [history](docs/history.md).
+- **Specialists and teams:** Delegate independent work, continue a conversation, or organize ordered discussions and parallel rounds. Pi specialists require tmux; dsh uses native sessions. A running team reserves its members. Pause and drain in-flight work before private tasks. See [specialist collaboration](docs/agent-collaboration.md).
+- **Python:** All workspaces share one venv for the current user. Loading the plugin prepares it and activates it in the host process. Use `python` or `python3` through Bash. Stop scripts using the environment before dependency updates. See the [Python guide](python/README.md) for paths, troubleshooting, and licenses.
+- **Material maintenance:** Ask the assistant to organize a project, repeat an analysis with its existing definitions, or check a delivery. The [maintenance skill](resources/skills/project-maintenance/SKILL.md) updates current guidance and extracts reusable methods while preserving formal materials, history, and backups.
 
-Personal Bot maintains no separate provider-call ledger or result wrapper. Native tools own their results and large-output handling; project conclusions cite relevant sources and results. If an outcome is unclear, query native status first. Complete result retention is not guaranteed after a process crash.
+Use `pi --resume` to select the main session explicitly; `pi --continue` can select the most recently active child. Enter managed specialists through `/pbot agents`. Opening a stopped specialist's saved session leaves it idle; use resume with a new instruction to continue work. Keep one writer per running session.
 
 ## Workspace materials
 
 | Location | Purpose |
 | --- | --- |
-| `AGENTS.md` | Material navigation and working agreements |
-| `areas/`, `projects/` | Long-term goals, task definitions, conclusions, and deliverables |
+| `AGENTS.md` | Navigation and working agreements |
+| `areas/`, `projects/` | Long-term goals, tasks, conclusions, and deliverables |
 | `knowledge/` | Reusable concepts, methods, and analysis definitions |
-| `.pi/pbot/history/`, `.dsh/pbot/history/` | Saved exchanges, summaries, and node links, maintained by source and queried together |
-| `providers/` | Provider guides, coverage gaps, and validation evidence |
-| `scratch/` | Temporary scripts, query and calculation data, downloads, and runtime environments |
-| `agents/`, `.agents/skills/` | Workspace additions to coordinator/general-purpose roles and workspace skills |
-
-Fetch data that can be queried again when needed, using the recorded definitions.
+| `.pi/pbot/history/`, `.dsh/pbot/history/` | Exchanges, summaries, and node links |
+| `providers/` | External tool guidance, data definitions, and sources |
+| `scratch/` | Temporary scripts, calculation data, downloads, and environments |
+| `agents/`, `.agents/skills/` | Role additions and workspace skills |
 
-Personal Bot stores no private activation state in the workspace. Pi owns its configuration; reload when required by Pi. Stop the old instance before copying a workspace. Concurrent writes from multiple machines to a synchronized directory are not supported. See [file storage](docs/file-storage.md) for storage and copying boundaries.
+Existing layouts and agreements take precedence. Fetch queryable data when needed using the recorded definitions. Stop writes in the old instance before copying a workspace; concurrent writes from multiple machines to a synchronized directory are unsupported. See [file storage](docs/file-storage.md).
 
-## Updates and historical data
+## Updates and operating scope
 
-Current release: **0.2.8**. Personal Bot maintains no workspace format, initialization state, or workspace upgrade mechanism. Update the plugin through its native host package manager. For a local Pi installation, update the source, run `npm ci --ignore-scripts` if dependencies changed, then reload or restart Pi.
+Current release: **0.2.9**. Update through the host's native package manager. For a local Pi source, update the checkout, run `npm ci --ignore-scripts` when dependencies change, then reload or restart. Stop active specialists before changing versions. Recreate specialists across compatibility lines; existing materials, history, and backups are preserved.
 
-Stop active sub-sessions before changing versions. Sub-session compatibility follows the minor version before 1.0 and the major version from 1.0 onward. Sessions from another compatibility line cannot be resumed directly.
+Operations follow the user's request, existing agreements, and required confirmations. Bash, Python, MCP, and extensions use the actual account and credential permissions. Enforce hard limits through read-only credentials, service controls, or restricted environments. Trades, transfers, and ledger changes require authorization for those operations. After cancellation, timeout, or disconnection, query native status before retrying to avoid duplicate execution.
 
-Pi stores child JSONL transcripts in its native session directory or the location selected by native configuration. In the current Pi agent directory, `pbot/subagents/` holds only control records and session references; `pbot/teams/` holds public team records. Version 0.2.0 does not support the old session location. It does not migrate or delete 0.1.x history, and excludes old records from current lists and background scheduling. Stop active children with the old version before updating, then create new agents. The shared Python environment uses the user-level `pbot/python/.venv`; see the [Python guide](python/README.md) for exact system paths. Personal Bot does not import other applications' sessions, configuration, or environments, or modify their data. Configure MCP and CLI environments explicitly through native mechanisms. Preserve user materials, historical evidence, and backups.
-
-## Trust and risks
-
-- Personal Bot provides no per-tool permission system or unified approval gate. CLI, MCP, Bash, Python, and extensions have the permissions of their actual accounts and credentials. They are not sandboxed. Use read-only credentials, service-side controls, or a restricted environment for hard limits.
-- Tool availability is not user authorization. Research, connection setup, and validation do not authorize trades, transfers, or ledger changes.
-- Protocol success does not prove business completion. Cancellation, timeout, and session recovery do not undo external side effects. Check native status before retrying an operation that may have been sent.
-- Task Conductor nodes do not automatically inherit the main session's tools, environment, or skills. Do not schedule unattended operations without user authorization or when the native service requires human confirmation.
-
-See [native tools and execution boundaries](docs/capability-design.md). Real models, external services, and full TUI/RPC interactions still require an approved acceptance environment. Local tests do not prove readiness for live trading.
+Task Conductor nodes need their own tools, environment, skills, and authentication. Preserve human interaction for operations that require confirmation. See [tools and execution](docs/capability-design.md).
 
 ## Development and documentation
 
+Development for both hosts uses Linux and Node.js 24.9+. After installing locked dependencies, run:
+
 ```bash
 npm run check
 npm test
 git diff --check
+npm pack --dry-run
 ```
 
-Full development and acceptance for both hosts require Linux and Node.js 24.9+. `npm test` includes smoke and E2E tests and generates `dist/` for tests and `lib/` for the CLI and dsh Host/Web entries. Pi still loads the extension source directly. Inspect package contents with `npm pack --dry-run`. See [validation](docs/validation.md) for test groups and limits.
-
-The README is available in English and Simplified Chinese. Detailed design documents and bundled guides are currently primarily in Chinese.
+`npm test` includes smoke and E2E tests and generates `dist/` for tests and `lib/` for distribution. Pi loads source at runtime.
 
-- [Development documentation](docs/README.md): architecture, tools, collaboration, storage, and validation.
-- [npm releases](docs/release.md): configuration, authorization, publishing, and installation acceptance.
-- [Domain terminology](CONTEXT.md) · [Python environment, native libraries, and licenses](python/README.md).
+- [Documentation index](docs/README.md): current architecture, usage, and development guidance.
+- [npm release](docs/release.md): candidate checks, configuration, and publication.
+- [Domain terms](CONTEXT.md).