@zihanw/pi-forge 0.5.7 → 0.5.9

package/docs/zh-CN/guides/pi-1-compatibility.md

@@ -0,0 +1,102 @@
+# Pi 1.0 兼容说明
+
+[中文文档](../README.md) · [English](../../guides/pi-1-compatibility.md)
+
+## Forge 0.5.9：Pi 1.1 / 1.2 / 1.3
+
+Forge 0.5.9 将开发 SDK 固定为 **1.3.0**，四个可选 SDK peer 范围扩大为：
+
+```text
+>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0
+```
+
+不自动承诺 Pi 1.4 或其他 0.x。历史 CI 保留 1.0.2，并增加 1.0.4 / 1.1.0 / 1.2.0；常规任务使用 1.3.0。兼容任务核对实际解析版本，并明确固定 1.x codemode/MCP/telemetry/chord 为同版本 fixture。这些任务的打包消费者也通过 `PI_TEST_COHERENT_UPSTREAM=1` 使用同样的固定版本；常规打包检查（1.3.0 任务）保持 npm 正常解析。原因是 Pi 1.0.1–1.1.x 的全新无约束安装现在会经上游 caret 拉到更新且不兼容的 codemode/MCP（例如 Pi 1.1.0 + pi-codemode 1.3.0 因缺少 `MCP_TYPESCRIPT_PREAMBLE` 导出而失败），与 Forge 无关。fixture 通过只说明 Forge 在该宿主系列上可用，不代表旧版 Pi 的全新无约束安装可用。
+
+Pi 1.2 的空闲自定义唤醒触发无 `prompt` 的 `before_agent_start`，启动时 `isIdle()` 已为 false。Forge 在编译 System 块之前，通过现有预览投影与历史 helper 一次解析当前分支的 `runtime.lastUserMessage`，直到结算保持工具后续请求的快照。没有符合条件的用户内容则为空；自定义消息不是用户提示。保留 helper 既有渲染（包括图片的 `[image]`）；role=user 不代表经过身份认证的人类。每个实际 start 重置 turn 频率规则；忙碌时 steering 不伪造 start 或用户消息。普通/旧宿主 user 事件仍以展开后的 prompt 为准，包括空文本/仅图片输入。旧宿主不发出 custom-start 时，不伪造该事件。
+
+**Pi 1.1 及更早版本的已知限制：** 这些宿主启动空闲自定义唤醒时（例如 Subagents 完成通知唤醒父会话）不触发任何 `before_agent_start`，Forge 无从得知这一轮开始。该次唤醒请求及其工具后续请求不带预设的 System 块；工具策略照常生效。这一点与 0.5.8 相同，已在 Pi 1.1.0 上实测。普通用户输入和忙碌时的 steering 不受影响。依赖后台完成唤醒的话，请使用 Pi 1.2 或更高版本。
+
+Pi 1.3 保持 custom-start/System 契约，并在默认或修饰符工具选择模式创建会话时恢复 transcript 中的活动工具；显式工具列表仍覆盖恢复。Forge 按预设的 `tools.initial`、allow/deny 与活动能力重新计算有效工具，不能让过期 transcript 越过权限上限或丢失能力工具。停用预设时恢复工具策略所有者保存的启动基线，并协调可区分的外部修改，而不是用经过策略缩减的 transcript 丢弃原基线。真实 SDK 持久化会话测试使用离线 faux 流覆盖这些路径；不引入新的 enabled-membership 执行权限限制。
+
+Pi 1.3 内部 SDK/codemode/MCP/telemetry 改为精确版本依赖，普通消费者无需历史 fixture 覆盖即可解析七个 Pi 包为 1.3.0；这不会修复旧版本 caret 的解析漂移。
+
+下文 0.5.8 一节记录上一版本的策略（peer 至 `<1.1.0`），仅作历史保留，不是当前 peer 范围。
+
+## Forge 0.5.8 与旧版本
+
+本指南介绍 **Forge 0.5.8** 兼容补丁。安装旧版 `@zihanw/pi-forge@0.5.7` 不会获得这些改动；该 artifact 的 Pi peer 范围仍为 `>=0.87.0 <0.88.0`。
+
+Forge 0.5.8 为四个 Pi SDK 包声明的 peer 策略为：
+
+```text
+>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0
+```
+
+最低 Pi 保持 0.87.0。开发依赖固定为 Pi 1.0.2 和 `typebox@1.3.27`。SDK 和 TypeBox 仍为宿主提供的可选 peer，不私装运行时副本；`>=1.0.0 <1.1.0` 覆盖 Pi 1.0 的补丁版本；本次发布实测 1.0.0、1.0.1、1.0.2，CI 定时任务会测试最新 Pi。不自动承诺其他 0.x 中间版本或 Pi 1.1 及以后版本。
+
+本补丁只调整依赖、测试覆盖与文档，**不改变**工具授权、Capability 所有权、用量汇总或个人配置。
+
+## 不受支持宿主的边界
+
+Forge 需要上游 Pi 的 `systemPromptOptions` 与 `context_with_system` 契约。oh-my-pi（OMP）等分支仍不受支持；优雅处理缺失输入不等于支持 OMP，也不认证分支的工具权限实现。
+
+- CLI 应用预设/Profile 会在改变选择或模型前检查命令专用的提示词 API；普通生命周期 context 无需提供命令专用 getter。
+- 全新会话的自动 Profile 模型/思考设置及预设/工具选择仍然提前生效，可能早于首轮提示词兼容性被观察到。不会延后应用，也不会在随后检测到缺失输入时自动回滚。
+- 缺少必要输入时每个会话只警告一次，清除过时的编译捕获，并在该会话内锁定拒绝新的预设/Profile 应用及预设编译/预览，包括已打开 Web 编辑器的 Preview。检测**不会**中止 provider 请求派发，也不会自动清除独立生效的工具策略；Forge 仍继续应用并检查其策略。
+- `/preset use none`（或 `off`）可显式禁用预设。新会话会重置锁定状态与警告次数；tree navigation、compaction 和 agent settlement 不会重置。重试前应先修复宿主契约，再新建会话。
+- 检测不覆盖所有宿主，也不保证在启动时完成。有效的选项与成功的 `pi.on()` 注册不能证明 `context_with_system` 真会被调用；Forge 不以注册成功推断 hook 支持。
+
+## Native MCP：逐项确认精确名称迁移
+
+Pi 0.99.2+ 规范化 native MCP 名称，例如 `mcp__demo-server__ping` 改为 `mcp__demo_server__ping`。同一服务器内 `a-b` 与 `a_b` 等工具名冲突会添加 hash 后缀；服务器名规范化冲突会被拒绝。
+
+请检查 allow/deny、initial、Capability add/remove、脚本和已保存 loadout 中的精确名称：
+
+- 未注册的 Capability **add** 会被拒绝。旧 initial 名称可能被省略，旧精确 allow 项不会放行新名称。
+- **旧的精确 deny/remove 名称可能只是匹配不到更名后的工具。** 不能把所有旧名称都当成 fail-closed；限制项和添加项一样需要检查。
+- 等服务器连接后，查看 Web 编辑器刷新后的工具选择器，或扩展 API `pi.getAllTools()` 返回的注册目录。仅查看 active 列表会漏掉 inactive/deferred 工具。
+- 人工确认每个 old→new 映射，包括碰撞 hash，再更新配置。Forge 不猜测别名，也不全局替换连字符。
+
+这些规则针对 **native MCP**，不是 `pi-mcp-adapter` 2.x 等第三方 adapter。本补丁不迁移 adapter 配置或改写现有资源。
+
+## Discovery 与延迟注册
+
+默认 native MCP 服务器后台连接，不阻塞首个 prompt；`direct` exposure 的启动行为不同。默认工具以 deferred exposure 注册，不列进 codemode description，通过 `searchTools()` / `describeNamespace()` 发现。搜索工具不会授予 Forge Capability，也不会覆盖工具策略。
+
+Pi 1.0 改进了 resume/reload 后的 deferred 工具恢复。Forge 仍要求 Capability add 的工具已注册；服务器未就绪时，应等待注册后重试原操作。单纯 reload 不保证解决问题。显式策略同步可能替换宿主恢复的 loadout，不应假定所有 pending 工具必须自动恢复。完整慢 MCP resume/reload 需要集成验收，不能拿 catalog mock 测试冒充。
+
+Forge 保留 `mcp_servers` 等外来 System section，包括更新和删除。上游 section 更新可能改变后续 prompt，不保证 cache 命中。
+
+## Pi 1.0.1 起的 Anthropic 工具变化
+
+在支持原生中途改工具的 Anthropic 模型上，Pi 1.0.1 起请求级工具列表固定为初始工具加一个保留占位工具，之后的每个工具都直接以完整定义写在 `tool_addition` 块里。因此启用或停用 Capability 不再改写请求级工具列表，同名重定义也不再强制发送完整列表。原生路径仍需要至少一个初始工具：会话开始时没有任何活动工具（例如 `tools.initial: []` 的预设）时，每次工具变化都会在请求级别发送当前完整列表。Forge 不改变这一行为，也没有针对 1.0.1 起重新做真实缓存实测。详见 [Provider 支持](../reference/provider-support.md)。
+
+## Codemode 边界保持原样
+
+Pi 1.0 访问不存在的 `tools` 属性会抛错。检查存在性请用 `"name" in tools`，不要用 `typeof tools.name`。
+
+`tools.initial` 是默认 loadout，**不是按 enabled 集合检查执行的 gate**。在 Preset 许可内、已注册的 deferred/codemode 工具，即使未列入 initial，或添加它的 Capability 已关闭，仍可能经 codemode nested 调用。Preset 的 allow **或** deny 策略和活动 Capability.remove 仍生效；direct 调用还取决于宿主 active loadout。本补丁不改变这些语义，也不让 discovery 自动按授权过滤。
+
+`models.generateImages()`（1.0 新增）和 `models.classify()`（0.99 已有）直接调用会话 model registry，不经过 `ctx.executeTool()` / `tool_call`。关闭生图工具**不等于**关闭模型 API。Pi settings 没有 `models: false` 开关；SDK factory `createCodemodeExtension({ models: false })` 需要明确的编程式插件装配。
+
+Pi 会将 codemode 模型返回的用量计入总账。Forge cache 面板仍分别展示 assistant 用量与显式 `details.forgeNestedUsage`，没有新增任意 native tool/model usage 汇总；不能把两份回执直接重复加总。
+
+## TUI 与配套包
+
+Pi 1.0 默认 fullscreen。要保留普通终端 scrollback，可在 Pi settings 中设置 `"tuiMode": "regular"`，或运行 `pi --tui-mode regular`。这不改变 Forge WebUI。
+
+agent-core 实验 harness 的移除，不等于我们配套 runtime 使用的 coding-agent `AgentSession` 被移除。`pi-durable` 仍明确标为实验性；本补丁不接入它，也不新增跨重启 continue。
+
+已发布的 subagents 0.5.3 不支持 `tools.initial`。尚未发布的新功能版本可以合入 Pi 1.0 适配，但仍需独立完成 runtime artifact/floor、TypeBox peer 整理、bwrap `/tmp` 启动器修复、packed 验收与发布授权。主 Forge 独立发布；main+optional 的 import smoke 不等于待发布 continue/background 功能已验收。见 [host-port 兼容说明](../../reference/subagent-host-port.md#tool-selection-compatibility)。
+
+## 验证
+
+```bash
+# 目标与已安装开发 SDK 不同时，请同时指定这两个版本。
+PI_TEST_VERSION=0.87.0 TYPEBOX_TEST_VERSION=1.3.7 npm run check:packed
+PI_TEST_VERSION=1.3.0 TYPEBOX_TEST_VERSION=1.3.27 npm run check:packed
+```
+
+不指定时，packed 检查读取一致的已安装 SDK family 及其声明的 TypeBox 版本，不再硬编码旧 pin。两个消费者都使用正常 npm peer 解析，并核对实际安装版本。如果存在 optional sibling，使用它声明的 runtime 依赖；不把这当成未发布本地 runtime 的测试。
+
+常规 Linux/macOS/Windows CI 使用固定的 Pi 1.3.0；显式兼容（0.87.0 至 1.2.0，含 1.0.2）与 scheduled latest 探针运行在 Linux。目标 release commit 的 CI 仍是发布门槛；本文不记录其结果，也不代表已完成真实 provider 验收。

package/docs/zh-CN/guides/web-editor.md

@@ -119,7 +119,7 @@ Profile 编辑按 Provider／Model、Thinking／Preset 分组，不可变身份
 
 ### 兼容性说明
 
-使用 `tools.initial` 的预设需要新版 Forge 支持。旧版 Forge 可能忽略 `tools.initial` 并恢复旧选择逻辑（选择性 allow 匹配目录，不限/deny 保留或过滤会话基线）（不支持向下降级兼容）。这些变化需要 Forge 0.5.5；宿主要求保持 Pi `>=0.87.0 <0.88.0` 不变。
+使用 `tools.initial` 的预设需要新版 Forge 支持。旧版 Forge 可能忽略 `tools.initial` 并恢复旧选择逻辑（选择性 allow 匹配目录，不限/deny 保留或过滤会话基线）（不支持向下降级兼容）。这些变化需要 Forge 0.5.5；最低宿主要求保持 Pi 0.87.0 不变（已发布 0.5.7 的 peer 范围为 `>=0.87.0 <0.88.0`；未发布的源码兼容补丁支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；详见 [Pi 1.0 兼容指南](pi-1-compatibility.md)）。
 
 ## Agent profile 工作区
 

package/docs/zh-CN/reference/capabilities.md

@@ -6,7 +6,7 @@ Pi-forge 引入了能力（Capabilities）：会话级动态提示词指令与
 
 ## 环境要求与安装
 
-- **宿主版本：** Pi `>=0.87.0 <0.88.0`（仓库开发 SDK 固定为 `0.87.0`，peer 范围为 `>=0.87.0 <0.88.0`；最低 SDK 0.87 保持不变；不声称对 0.86 的双重运行时支持）。能力功能需要 Forge 0.5.5。
+- **宿主版本：** 最低支持 Pi 0.87.0。已发布的 Forge 0.5.7 声明 peer 范围为 `>=0.87.0 <0.88.0`；Forge 0.5.8 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；Forge 0.5.9 支持联合范围 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0`（开发 SDK 更新至 1.3.0，`typebox@1.3.27`；最低 SDK 0.87 保持不变；不声称对 0.86 的双重运行时支持）。能力功能需要 Forge 0.5.5。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
 - **项目信任：** 激活能力、预设绑定或添加手动指令需要项目处于受信任状态（`isProjectTrusted()`）。
 - **兼容性限制：** 包含 `tools.initial` 的配置需要新版 Forge 支持；旧版 Forge 会忽略 `initial`，因而配置不具备向下降级兼容性。
 
@@ -230,7 +230,7 @@ Forge 在每次发起模型请求时通过两阶段拼装动态投影能力增
 
 ## 兼容性与安全边界
 
-- **要求上游 Pi 0.87：** 必须使用上游 Pi `>=0.87.0 <0.88.0`。不提供对 0.86 的双重运行时支持。之前在 `context` hook 中操作或读取完整 System 消息的第三方扩展必须迁移到 `context_with_system` 完整 hook。
+- **要求上游 Pi 最低版本：** 必须使用上游 Pi 0.87.0 或更高版本（Forge 0.5.9 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0`；Forge 0.5.8 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；已发布 0.5.7 的 peer 元数据保持 `>=0.87.0 <0.88.0` 不变）。不提供对 0.86 的双重运行时支持。之前在 `context` hook 中操作或读取完整 System 消息的第三方扩展必须迁移到 `context_with_system` 完整 hook。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
 - **`before_agent_start` 注入时机：** `before_agent_start` 阶段强制注入的 System 提示词在 Pi 执行流中仍然晚于 `context_with_system` 生效。
 - **前置扩展上下文改写：** Pi 允许 hook 改写消息。当可见元数据锚点或未锚定事件需要定位时，Forge 要求输入与规范会话投影有唯一的有序对应，否则中止而非猜测（fail-closed）。Pi 可能先保存排队的 custom 消息、但暂不放入工具续跑上下文：Forge 仅容许位置能唯一确定的 custom 消息缺省，忽略其重新生成的外层时间戳；保留传入对象，不擅自把缺省对话补回请求。前置改写因而可能与该定位方式冲突；简单后移不保证组合安全。通用插件、warming、自动 overflow 兼容性仍未全面验收。
 - **上游缺陷与协议限制：** 上游 Pi 元数据分块及语义截断缺陷（semantic-cut defect）未被修复，压缩检查点位置保持不变。旧会话和旧投递载体保持原样，不支持继续恢复能力状态；Forge 不会迁移旧 JSONL 或改写历史摘要。不支持也不承诺 OMP（Oh My Pi）。
@@ -253,7 +253,7 @@ Forge 在每次发起模型请求时通过两阶段拼装动态投影能力增
 - Parent 核心防护：源版本一致性保障、外部新增绑定防脏写检测、生命周期与重入安全围栏。
 - 工具补丁仅支持 `add` 与 `remove`；候选的 `only`/allowlist 未实现。
 - 提供保守的 Provider 托管与缓存预警；兼容的 Codex 传输在保留历史没有移除/重复声明时可追加全新工具以保留前缀（不保证缓存命中）；移除/同名重加回退全量当前工具表；不进行自动旧数据迁移，不重写历史摘要；无 Pi split patch；不声称 forceprompt、warming、autooverflow 或远程模型验收保证。
-- 2026-09-24 UI 收口时（提交 `89c6ba2`）本地构建、完整 Node／浏览器／打包验证已通过；这是有日期的本地结果，不是当前 CI 证据、远端提供商验收或 npm 已发布的证明。宿主仍要求 Pi `>=0.87.0 <0.88.0`；可选 runtime／subagent 集成及其生成者接入工作独立测试和发布。
+- 2026-09-24 UI 收口时（提交 `89c6ba2`）本地构建、完整 Node／浏览器／打包验证已通过；这是有日期的本地结果，不是当前 CI 证据、远端提供商验收或 npm 已发布的证明。该历史验收使用 Pi `>=0.87.0 <0.88.0`；当前源码宿主策略见[兼容说明](../guides/pi-1-compatibility.md)。可选 runtime／subagent 集成及其生成者接入工作独立测试和发布。
 
 
 文件路径校验会拒绝检查时已存在的符号链接，但不能隔离另一个本地进程并发替换目录的攻击；源版本比较也不是跨进程锁。不要把资源编辑用于不可信进程可竞争修改的共享目录。

package/docs/zh-CN/reference/provider-support.md

@@ -23,7 +23,7 @@ Pi 和 Forge 在每次请求时都读取当前模型的 `compat` 标记：
 
 | API | 指令正文 | 工具变化 |
 |---|---|---|
-| `anthropic-messages` | 有标记时为 `role: "system"` 消息。Pi 会把它留到下一条 assistant 消息之前再发，因此不会插在 `tool_use` 和对应的 `tool_result` 之间；记录在用户消息之前的更新，实际会发在该用户消息之后。 | 有 `supportsMidConvoToolChanges`、至少一个初始工具且没有同名重定义时：初始工具保持在最前，之后的工具带 `defer_loading` 追加，变化以 `tool_addition` / `tool_removal` 块表示，请求级工具列表只增不减。否则在请求级别发送当前列表。 |
+| `anthropic-messages` | 有标记时为 `role: "system"` 消息。Pi 会把它留到下一条 assistant 消息之前再发，因此不会插在 `tool_use` 和对应的 `tool_result` 之间；记录在用户消息之前的更新，实际会发在该用户消息之后。 | 需要 `supportsMidConvoToolChanges` 且至少一个初始工具。**Pi 1.0.1 起：** 请求级工具列表固定不变（初始工具加一个保留的 deferred 占位工具）；之后的工具直接以完整定义写在 `tool_addition` 块里（同名重定义会替换旧定义），用 `tool_removal` 撤下。**Pi 1.0.0 及更早：** 之后的工具带 `defer_loading` 追加到请求级列表，列表只增不减，同名重定义会退回发送完整列表。其他情况（包括会话开始时没有任何活动工具，例如 `tools.initial: []`）在请求级别发送当前列表。 |
 | `openai-responses`、`openai-codex-responses`、`azure-openai-responses` | 有标记时，在原位置发送 `developer` 消息（支持 developer 角色的推理模型）或 `system` 消息。 | 保留的历史中只有新增时，新工具在原位置加载；历史中任何位置出现过移除或同名重声明，这次请求就改为在请求级别发送完整的当前列表。 |
 | `openai-completions` | 有标记时，在原位置发送 `developer` 或 `system` 消息。 | 有 `supportsMidConvoToolAdditions` 时新增在原位置加载；移除和重声明改为发送完整的当前列表。 |
 | `mistral-conversations` | 有标记时，在原位置发送 `system` 消息。 | 始终在请求级别发送完整的当前列表。 |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zihanw/pi-forge",
-	"version": "0.5.7",
+	"version": "0.5.9",
 	"description": "Pi extension for editable context presets, one-shot agent profiles, tool policy, and request debugging.",
 	"repository": {
 		"type": "git",
@@ -45,10 +45,10 @@
 		]
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-agent-core": ">=0.87.0 <0.88.0",
-		"@earendil-works/pi-ai": ">=0.87.0 <0.88.0",
-		"@earendil-works/pi-coding-agent": ">=0.87.0 <0.88.0",
-		"@earendil-works/pi-tui": ">=0.87.0 <0.88.0",
+		"@earendil-works/pi-agent-core": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0",
+		"@earendil-works/pi-ai": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0",
+		"@earendil-works/pi-coding-agent": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0",
+		"@earendil-works/pi-tui": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
@@ -69,14 +69,14 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-agent-core": "0.87.0",
-		"@earendil-works/pi-ai": "0.87.0",
-		"@earendil-works/pi-coding-agent": "0.87.0",
-		"@earendil-works/pi-tui": "0.87.0",
+		"@earendil-works/pi-agent-core": "1.3.0",
+		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-coding-agent": "1.3.0",
+		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "22.20.1",
 		"@vitejs/plugin-vue": "6.0.8",
 		"playwright-core": "1.61.1",
-		"typebox": "1.3.7",
+		"typebox": "1.3.27",
 		"typescript": "6.0.3",
 		"vite": "8.1.5",
 		"vue": "3.5.40",
@@ -89,7 +89,7 @@
 		"check:docs": "node scripts/check-docs.mjs",
 		"check:dist": "node scripts/check-dist.mjs",
 		"check:package": "node scripts/check-package.mjs",
-		"prepack": "npm run build",
+		"prepack": "npm run build && npm run check:package",
 		"typecheck": "tsc --noEmit && vue-tsc --noEmit -p tsconfig.web.json",
 		"test": "node --test tests/*.test.ts",
 		"test:browser": "node --test --test-concurrency=1 tests-browser/*.test.ts",
@@ -97,11 +97,12 @@
 		"check:packed": "node scripts/check-packed-install.mjs"
 	},
 	"files": [
-		"dist/",
-		"docs/",
-		"examples/",
-		"assets/readme/",
-		"assets/pi-forge-header-concept-1.png",
+		"dist/**/*.js",
+		"dist/**/*.d.ts",
+		"dist/**/*.map",
+		"docs/**/*.md",
+		"examples/**/*.json",
+		"examples/**/*.ts",
 		"README.md",
 		"README.zh-CN.md",
 		"CHANGELOG.md",

package/assets/readme/PROVENANCE.md

@@ -1,95 +0,0 @@
-# README media
-
-## September 26 Capabilities rename
-
-All ten currently embedded WebUI GIFs (five scenes in each language) were re-recorded from the renamed development source based on `9f3bbb4`. They now show Capabilities and Enable/Disable; `capability-tools.gif` replaces the README reference to `mode-tools.gif`. Historical files, including the old mode and TUI clips, are retained rather than silently relabelled.
-
-Context, Draft diff and Capability recordings use the continuous recorder (1440×900, 15fps exports); Tools and Regex use their dedicated recorder (1200×750, 15fps exports). Both use native pointer actions and continuous X11 capture, with only the disclosed pointer halo. The Capability scene checks actual SDK tool selection `read → read,grep,find → read` and locates both the update and removal in projected context. All projects and sessions are disposable fixtures; no real provider inference, personal history, or cache-hit claim is involved. English/Chinese final keyframes were reviewed against the current UI. The legacy TUI clip was not re-recorded and remains unembedded.
-
-```bash
-npm run build
-PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-capability-media LOCALES=en,zh-CN SCENES=context,diff,capability node scripts/record-readme-continuous.ts
-python3 scripts/export-readme-continuous.py /tmp/forge-capability-media
-PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-tools-regex node scripts/record-readme-tools-regex.ts
-```
-
-Current output scene names are `context`, `diff`, and `capability`; copy reviewed outputs to `context-composition.gif`, `edit-draft-diff.gif`, and `capability-tools.gif` respectively. The sections below document earlier captures, not the current embedded footage.
-
-## September 26 README refresh
-
-The concept header `../pi-forge-header-concept-1.png` is restored unchanged. The duplicate overview screenshot is no longer embedded; old image files remain available. Installation precedes all demo GIFs.
-
-Follow-up review: the TUI clip was removed from both READMEs because its command/status flow did not clearly communicate the benefit. The file and recorder are retained as historical material; the five WebUI feature GIFs remain in use. The personal motivation is now a short opening note, with a prominent optional-subagents link before installation.
-
-Recordings produced for this refresh, based on source `6a197e6` plus the local unpublished-alias removal:
-
-- `tui-quickstart.gif` (retained, not embedded in README): real Pi 0.87.1 TUI, 1000×540, about 12.75s. `/preset use project:read-first` → `/instruction use project:write-tools` → `/instruction status`. This uses synthetic read-first resources, not a verbatim copy of the checked-in example. Real Forge operations change selected tools from read/ls/control to also bash/edit. No model response is shown or implied.
-- `<locale>/tool-selection.gif`: real Policy picker, defaults read/ls → read/ls/grep, Save/Activate, compiled Preview tool list. Permission ceiling already includes grep; this is a default-selection edit, not an authorization bypass. About 12.94s.
-- `<locale>/regex-transforms.gif`: enable a preconfigured outgoing system-text rule, then inspect `SAMPLE_TOKEN` → `[REDACTED]` in Preview. About 8.07s. Only synthetic text is used; no general secret-detection guarantee.
-
-Browser captures use the built product editor and production loopback host/compiler, with an inert command harness and synthetic tools (not a live model session). Native X11 pointer interactions are continuous; the blue halo is a recording aid. 1440×900 masters export to 1200×750/15fps GIFs. Semantic before/after assertions check Preview and tool selection; the browser is restricted to its own editor origin. Parent review confirmed no page errors or external browser requests in either locale, and decoded all five GIFs.
-
-The TUI uses a separate temporary home/agent directory, isolated dark colors with brighter dim text, no session persistence, and a local `offline-demo` model definition with an inert placeholder key. That model is not a real provider. Pi runs offline; a Node preload blocks fetch/socket connections and asserts an empty network-attempt log. Keyframes were manually reviewed for actual command results and tool state; capture action logs are not automated OCR assertions. The terminal has no custom Forge UI or replaced output. Earlier captures showing missing-model warnings were discarded from the published asset and retained only in the local evidence report.
-
-### Reproduce the new recordings
-
-Requires the repository dev dependencies, Pi CLI, Google Chrome, Xvfb, xdotool, ffmpeg, ImageMagick `import`, GNOME Terminal and `dbus-run-session`. Private displays `:192` (browser) and `:196` (terminal) must be free. Recorders create disposable resources and clean up only their own processes. Outputs default to the review directory, not the checked-in images.
-
-```bash
-npm run build
-PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-tools-regex node scripts/record-readme-tools-regex.ts
-PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-tui node scripts/record-readme-tui.ts
-```
-
-Review `/tmp/forge-tools-regex/assets/{en,zh-CN}/` and `/tmp/forge-tui/assets/tui-quickstart.gif` before copying to `assets/readme/`. Masters, keyframes and evidence stay in each output directory. Fixture IDs, timing and hashes vary between runs. These clips prove local editing/management behavior, not provider delivery, model compliance, cache reuse, sandbox isolation or autonomous agent decisions.
-
-## September 24 continuous v3
-
-Captured 2026-09-24 EDT from accepted UI commit `89c6ba2` (development package metadata 0.5.4), using isolated synthetic projects, the built production loopback editor/compiler and, for Mode, a real SDK AgentSession with no remote model requests.
-
-The September 24 capture produced these per-locale files:
-- `editor-overview-v3.png` (retained, no longer in README): editor and compiled Preview (1439×899 browser viewport; the continuous videos/GIFs include the 1px X11 border at 1440×900).
-- `context-composition.gif`: native drag reordering plus project-context toggle, about 14.6s.
-- `mode-tools.gif`: Current session Use → locate → Off → locate removal, about 18.3s. Actual SDK tools `read → read,grep,find → read`; projected instructions/stop notices remain distinct from delivery or cache evidence.
-- `edit-draft-diff.gif`: real keyboard edit followed by Draft diff without resizing, about 13–14s.
-
-GIFs are 1440×900/15fps exports of continuous 30fps x11grab MP4, without time acceleration or stitched state screenshots. The native pointer drives the UI; the blue halo/click pulse is a disclosed recording aid, not a Forge feature. Native dragging's light drag image and actual compile loading states are retained. GIF palette conversion is lossy. Complete MP4/GIF decoding and real browser playback/seek were checked for both languages. No personal resources/credentials/history, model inference, provider/cache claims or user-host restart were involved.
-
-## Reproduce September 24 recordings
-
-Requires the checkout's development dependencies, Xvfb, xdotool, ffmpeg, Google Chrome and Python Pillow. Private display `:192` must be unused. The recorder refuses to use an occupied display, creates disposable fixtures and cleans its own processes/resources. Do not copy output over formal assets without reviewing it.
-
-```bash
-npm run build
-PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-readme-v3 LOCALES=en,zh-CN SCENES=context,diff,capability node scripts/record-readme-continuous.ts
-python3 scripts/export-readme-continuous.py /tmp/forge-readme-v3
-```
-
-Output is `media/<locale>/{context,capability,diff}.{mp4,gif}`, proof images and semantic evidence; `manifest.json` records dimensions/durations/hashes. Copy approved GIFs to the corresponding names above and `context-poster.png` to `editor-overview-v3.png`. New recordings have fresh synthetic session IDs; pixel-identical reproduction is not promised.
-
-## Retained legacy media (not referenced by current README)
-
-Captured on 2026-09-23 from the built 0.5.5-development WebUI (package version still 0.5.4), using the production loopback editor server and compiler with an isolated, synthetic code-review project.
-
-Each locale (`en`, `zh-CN`) has:
-
-- `editor-overview.png`: 1440 × 900, selected instructions beside compiled Preview.
-- `context-toggle.gif`: 1440 × 900, two real, settled UI states in a five-second loop. Clicking the project-context toggle removes/restores the owned example `AGENTS.md` paragraph. This is a sampled-state demonstration, not real-time footage or a latency measurement. No zoom, captions, or drawn/replaced UI.
-- `draft-diff.png`: 1440 × 620, one instruction edit compared with the saved Preset. Token deltas are estimates, not provider usage.
-
-No model requests, credentials, personal presets, real conversation history, or user-host restart were needed. `demo-session` and the project contents are examples; `/tmp/pi-forge-readme-*` is a disposable project. Runtime context-file input is supplied through the harness's public prompt-options boundary; no private SDK state is patched. Browser traffic is restricted to that editor origin. These images demonstrate editing/compilation, not provider delivery, model compliance or cache reuse.
-
-## Reproduce from a repository checkout
-
-Requires the repository's Node development dependencies, system Chrome (or `CHROME_PATH`) and Python with Pillow for GIF encoding. Outputs are local; this does not publish them.
-
-```bash
-npm run build
-PI_FORGE_MEDIA_OUT_DIR=/tmp/forge-readme-capture node scripts/record-readme-media.ts
-# Inspect the captured PNGs before replacing the checked-in media.
-python3 scripts/render-readme-media.py /tmp/forge-readme-capture assets/readme
-npm run check:docs
-npm run check:package
-```
-
-The recorder owns its temporary project/global configuration directories and removes them after use. It never copies user auth files. GIFs use one shared palette and two 2.5-second holds; the encoder validates frame count, loop and dimensions.