diff --git a/AGENTS.md b/AGENTS.md
index 9c981ee..540112a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,9 @@
 # Repository Guidelines
 
+Plex Gateway 是独立的 Plex 控制协议适配器。产品与模块边界见 [架构](docs/architecture.md)，阶段目标见 [路线图](docs/roadmap.md) 和 [媒体生命周期设计](docs/media-lifecycle-architecture.md)。Gateway fallback 优先不撤销整体阶段目标；Plex 持久投影仍属下一阶段评估，不能写成已上线或已否决。
+
+恢复工作时，读取当前任务实际引用的记录及必要设计、证据。没有记录时依据当前上下文继续；新的恢复记录可保存到 `.workbench/records/`。
+
 ## 项目结构与模块职责
 
 - `cmd/plex-gateway/` 是生产入口和依赖装配层，`cmd/plex-probe/` 提供只读 Plex 行为探测。
@@ -19,7 +23,7 @@ go build ./cmd/plex-gateway   # 构建二进制
 docker build -t plex-gateway:dev .
 ```
 
-聚焦测试可使用 `go test ./internal/gateway -run TestName`。性能基准与验收条件见 `docs/performance-matrix.md`。
+聚焦测试可使用 `go test ./internal/gateway -run TestName`，构建和容器检查按改动选择。纯文档改动检查内容、相对链接和 `git diff --check`。性能基准与验收条件见 [性能矩阵](docs/performance-matrix.md)。
 
 ## 编码风格与命名
 
@@ -29,6 +33,8 @@ docker build -t plex-gateway:dev .
 
 使用标准库 `testing`。测试命名为 `TestBehavior`，基准命名为 `BenchmarkOperation`。XML/JSON、客户端兼容和配置组合优先使用表驱动测试。协议改动应覆盖成功、异常输入、取消、超时和 fail-open；涉及授权、请求身份、缓存或并发时必须运行 race 测试。性能验收必须区分冷缓存、热缓存、本地媒体、STRM、快速切换和多客户端场景；请求成功不等于性能达标。
 
+播放改动按受影响的真实客户端路径观察：Plex decision、Part/start 授权、302 或 `control-v1`、客户端 CDN Range、首帧与 Seek 后续播，以及相关 timeline、切集和退出。用 [Plex 行为探测](docs/plex-behavior.md) 的方法关联请求顺序，区分控制响应成功、媒体流可用和播放器体验；结论限定到实际样本与环境。
+
 ## 提交与 Pull Request
 
 提交遵循简洁的 Conventional Commits，例如 `feat: support Plex Web direct play`、`fix: trust Plex materialized media info`。在主题分支开发。PR 说明应包含用户可见结果、兼容性边界、验证结果和剩余限制；除非界面变化需要说明，否则不要求截图。
@@ -41,12 +47,14 @@ docker build -t plex-gateway:dev .
 
 `CHANGELOG.md` 是给用户看的中文发版说明，不是代码实现记录。按重要性描述新增能力、体验变化和已知限制，最重要的用户功能必须放在最前。不要堆砌 Stream ID、投影层级、缓存、队列或 ffprobe 等内部细节，除非它们直接影响用户配置或使用边界。
 
-`CHANGELOG.en.md` 必须同步表达相同内容。发版时同时更新 `VERSION` 和两个 changelog 的带日期版本章节；普通开发不要提前修改版本号。发版前比较上一个版本 Tag 到当前 HEAD，确认所有用户可见变化均已覆盖，且没有把 roadmap 或未交付能力写成已发布功能。发布源只使用 `main` 上的 `VERSION`；手工 Release 仅用于按当前版本重建，不接受自定义版本或源码 ref。Push、PR、Tag、镜像和 Release 等外部动作必须遵守当前维护者授权边界。
+`CHANGELOG.en.md` 必须同步表达相同内容。发版时同时更新 `VERSION` 和两个 changelog 的带日期版本章节；普通开发不要提前修改版本号。发版前比较上一个版本 Tag 到当前 HEAD，确认所有用户可见变化均已覆盖，且没有把 roadmap 或未交付能力写成已发布功能。发布源只使用 `main` 上的 `VERSION`；手工 Release 仅用于按当前版本重建，不接受自定义版本或源码 ref。
 
 ## 架构、兼容性与性能边界
 
-Plex 负责媒体库、认证和观看状态；Gateway 只适配控制流和 302，不代理媒体字节；MediaVault 负责 STRM 和直链解析。所有改动必须保持本地媒体透明代理，Part、universal start 和 302 路径不得同步执行 SQLite、ffprobe 或其他分析 I/O。
+Plex 负责媒体库、认证和观看状态；Gateway 适配控制流、302 和可选 `control-v1`，不转运播放媒体字节；MediaVault 负责 STRM 和直链解析。ShimWeave 独立负责浏览器媒体能力与播放，不是 Gateway 的运行依赖。隔离的分析 worker 可进行有界媒体读取。
+
+本地媒体保持透明代理。Part、universal start 和 302 不同步执行 SQLite、ffprobe 或其他分析 I/O；metadata 浏览 miss 只可投递内存任务并立即透传。实际 playback decision 可消耗一次配置内的冷等待预算，超时或失败保留 Plex 路径；L1 命中不因请求同步读 SQLite。
 
-客户端兼容改动应先比较 Plex 对本地媒体与 STRM 的原始响应，并按协议语义适配。只有真实请求证明 Plex 本身存在客户端差异时，才允许增加客户端分支。Gateway 只补缺失的描述性 MediaInfo，不伪造 Plex Stream ID 或播放选择状态；Plex 已返回物化 Stream 行时必须原样透传并跳过重复探测。
+客户端兼容改动应先比较 Plex 对本地媒体与 STRM 的原始响应，并按协议语义适配。只有真实请求证明 Plex 本身存在客户端差异时，才增加客户端分支。到可信 MediaVault 的解析请求保留完整客户端请求头和身份上下文，协议适配只改变明确约定的字段。Gateway 只补缺失的描述性 MediaInfo，不伪造 Plex Stream ID 或播放选择状态；Plex 已返回完整技术字段、真实大小和带正数 ID 的物化 Stream 行时，字节级透传并跳过重复探测。
 
 实验能力必须通过独立开关隔离。关闭时不得创建额外状态、缓存、锁或远程 I/O。未来 Plex MediaInfo 持久投影必须作为隔离组件，具备 PMS/schema 检测、备份、回滚和 API 回读，不能进入 Gateway 热路径。不得提交真实凭据、私有地址、媒体名称或未脱敏抓包。