diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 7353b1fb6..4398f77c8 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -30,6 +30,7 @@
 - **现象**：DeepSeek V4（默认 thinking）对 `tool_choice=required` 或指定函数返回 HTTP 400：`Thinking mode does not support this tool_choice`。
 - **处理**：策划 V2 协议工具固定 `tool_choice=auto`，由 Runtime 校验必须恰好调用 `plan_ask_question` 或 `plan_submit_gdd`。不要按模型名分支，也不要用 required 强行出稿。
 - **验证**：请求体含 `tools` 且 `tool_choice=auto`；无工具调用时走既有非法输出重试。
+
 ## 2026-09-09 常用设置跨文件保存失败
 
 主配置与 local overlay 的单文件原子写入不能保证整体成功；覆盖层写入失败会留下混合配置。保存前先序列化全部变更，多文件保存保留原内容，错误时逆序恢复并报告回滚失败；单文件保持原写入路径，成功后不回读、不触发外部诊断。此回滚仅处理可捕获错误，不承诺进程崩溃下的事务恢复。
@@ -5182,3 +5183,28 @@
 - 不受影响：`image` / `video` / `code` / `publication-material` 的 canonical 分类本身就是 `unclassified`，派生结果等于落盘值，规则不触发（已用断言钉住）。
 - 写入侧已同步 canonical 化：`infer_canvas_export_asset_kind`（`assets.rs`）现在直接产出 canonical kind（`ui → ui-design`、`animation → character-animation`、`asset → image`），不再依赖别名表兜底；`canvas_export_asset_kind_is_always_canonical` 用例逐分支钉死，别名表从此只承担存量兼容。
 - 关联：`packages/shared/src/contracts/gameCreationApp.ts` 的 `gameCreationAppAssetCategory`、`apps/ai-game-creator-shell/src-tauri/src/assets.rs`、`apps/ai-game-creator-shell/tests/resourceCardPreviewRealManifest.test.ts`。
+
+## AGC 资源搜索栏改成「临时叫出」的浮层，工具条带与它的下移逻辑一并撤掉（2026-09-11）
+
+- 现象：资源搜索框与栏目标题栏在真机上仍然重合；分页态标题栏右端的「资源总览」（回到资源总览）按钮**点不动**。
+- 成因（两层，同一处）：常驻工具条带 `.game-resource-book-tools` 是 `position: absolute; top: 0; left/right: 0; z-index: 40` 的**横跨整行**盒子——只有搜索框、筛选条是不透明内容，其余透明区域照样接收点击；它正好盖在栏目标题栏（`z-index: 30`）那条带上，把「资源总览」按钮的命中区域整段吃掉。而管理区 `padding-top: var(--game-resource-book-tools-height)` 与画本场景按同一变量 `inset` 下移，两处都只为"给搜索框腾一条带"存在，带子本身仍与标题栏争同一条水平带。
+- 处理（用户指定方案）：搜索条不常驻。常态只在右下角缩放 Dock 末尾留一颗搜索按钮（`aria-label="搜索资源"`），`Ctrl/Cmd+F`（macOS `Cmd+F`）或点它把浮层叫出来；关闭复用美术画布的 `useImageCanvasFloatingOptionDismiss`（Esc / 点外部，Escape 在 document 上截断，不会连带清画布选中）。随后撤掉工具条带本身：管理区 `padding-top`、场景 `inset` 变量、`resourceBookToolsRef` 与 ResizeObserver 测高 effect、`resourceCanvasSceneSize()`、缩放与滚轮锚点里减掉工具条带的两处算式全部删除，`resourceBookSceneSize` 重新等于管理区盒子（场景盒子 = 可排布盒子，更自洽）。
+- 几何口径（改这些数字前先读）：搜索浮层 `position: absolute; right: 14px; bottom: 58px; width: min(320px, calc(100% - 28px))`——`58px` = Dock 的 `14px` + Dock 高度 `34px` + 10px 间隙，且**刻意不写 `top`**，所以它永远落在管理区底部、不可能压到标题栏那条带；状态提示与附件失败条的浮层容器 `.game-resource-book-notices` 用 `top: 58px`（= 标题栏 `min-height: 42px` + 16px）落在标题栏之下。
+- 浮层必须钉住的两条：① 提示层容器整层 `pointer-events: none`、只有提示条自己 `pointer-events: auto`（横跨整行的透明盒子吃点击正是上面那条 bug）；② 搜索条件不随浮层收起而清除（`searchText` 是画布状态，`type=search` 的原生 Esc 清空已被 `preventDefault` 挡掉），"当前有搜索"由 Dock 按钮的 `.is-active` 高亮表达。
+- 门禁为什么抓不到：jsdom 不做布局命中判定，`getByLabelText` 也不校验可见性；可见性与重叠只能钉声明（`tests/appSurface/project-development.suite.ts` 的 `styleRuleBody` 口径），入口另用真实 DOM 用例覆盖——`tests/appSurface/harness.ts` 的 `openResourceSearch()` 先按产品入口打开浮层，浮层没打开时 `getByLabelText` 直接抛错，堵掉"元素在但点不到"的假绿。
+- 关联：`apps/ai-game-creator-shell/src/styles.css`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/tests/appSurface/harness.ts`、`src/components/image-editor/useImageCanvasFloatingOptionDismiss.ts`。
+
+## AGC 画布侧分类筛选条已按用户要求移除，共享筛选条组件保留（2026-09-11）
+
+- 用户口径：「这个筛选功能有点鸡肋（悬浮文字这几个），给他去掉吧」——指资源画布顶部那排分类 chip（全部 / UI 交互 / 角色与对象 / 场景与环境 / 音频 / 文档 / 待归类）与同一排的画布标签 chip。
+- 处理：只移除画布上的这一处 `PlatformResourceFilterBar` 用法，**共享组件本身保留**（`@` 素材面板 `ImageCanvasProjectAssetPickerDialog` 与参考图弹窗仍在用）。随它一起删掉只为它存在的画布筛选轴：`resourceCanvasCategoryFilters` / `showResourceCategoryFilter` / `resourceCanvasActiveTags` / `resourceTagLibrary`，以及 `visibleResources` 里两个此后恒真的条件——画布可见资源只由搜索框收窄。
+- 不要顺手改分区：栏目大纲、栏目标题栏、`categoryOrder`、`projectResourcesByCategory` 与「资源总览」入口是另一回事，本次一行未动。将来若要恢复分类筛选，应重新设计入口，而不是把这排横跨画布顶部的 chip 行加回来。
+- 关联：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`packages/shared/src/components/PlatformResourceFilterBar.tsx`。
+
+## AGC 项目对话的输入区必须留在对话框内部（2026-09-11）
+
+- 现象：右侧「与陶泥儿的对话」里输入区紧挨着对话框下沿，左右两侧像多出两条竖线，很丑。
+- 成因：`.game-workbench-chat .project-supervisor-surface.is-direct-codex` 下，消息列表与输入区是**两只各自带描边、各自绝对定位的盒子**——列表 `bottom: 104px`、输入区 `bottom: 0; left/right: 0`，两盒上下紧贴：输入区左右描边与列表左右描边接成一条贯穿整栏的线；列表底部内边距只有 24px，最后一条消息还会被不透明的输入区盖住。
+- 处理：消息列表（direct-codex）改为铺满整个会话区（`bottom: 104px → 0`），它自己那只带描边的盒子就是"对话框"；输入区（`.project-supervisor-composer.is-direct-codex`）三边内缩 12px、圆角收到与外框同档 12px，成为框内的一块。**留白必须跟着输入区高度走**：列表 `padding-bottom` / `scroll-padding-bottom` 由 24px 提到 256px（≈ 输入区最高 230px + 12px 内缩 + 约 14px 间距）；改编辑器 `min-height: 96px` / `max-height: 140px` 就要同步改这个数（守卫已把两者钉在一条断言里）。
+- 不改交互语义：输入区仍是同一棵 DOM（编辑器 / `@` 引用 / AI 润色 / 模型选择 / 提交按钮原位），只改落点与留白；边框、底色、阴影全部沿用既有 token。
+- 关联：`apps/ai-game-creator-shell/src/styles.css`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。