diff --git a/.hermes/shared-memory/pitfalls.md b/.hermes/shared-memory/pitfalls.md
index ebeba2a0..5fb1bce5 100644
--- a/.hermes/shared-memory/pitfalls.md
+++ b/.hermes/shared-memory/pitfalls.md
@@ -83,6 +83,14 @@
 - 验证：`spacetime --root-dir server-rs/.spacetimedb/local list --server http://127.0.0.1:3101` 能看到目标库；重新发布不再使用无权限的全局 identity。
 - 关联：`scripts/dev-rust-stack.sh`、`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`。
 
+## `npm run dev` 本地 SpacetimeDB 401 / 403 可重置默认 local 身份
+
+- 现象：`npm run dev` 启动本地开发栈时，SpacetimeDB 在登录、发布或预检查阶段返回 `401` / `403`，清理后仍像在使用旧 token 或旧本地库。
+- 原因：本机 `spacetime` CLI 保存的旧 token、默认 server、正在运行的 standalone 进程或默认 local 数据库与当前发布身份不一致。
+- 处理：确认只是本地测试库且数据可丢弃后，先查看并停止本地 `spacetimedb-standalone`，执行 `spacetime logout`，确认并设置 `spacetime server set-default local`，停 server 后用 `spacetime server clear -y` 清空默认本地库，再 `spacetime start`，另开终端执行 `spacetime login --server-issued-login local`，最后用 `spacetime publish --server local A` 或项目脚本重新发布。
+- 验证：`spacetime server list` 默认目标为 local；重新登录后发布不再返回 `401` / `403`；`npm run dev` 可以完成 SpacetimeDB publish 并继续启动 `api-server`。
+- 关联：`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`、`scripts/dev-rust-stack.sh`。
+
 ## 本地 SpacetimeDB 联调可按阶段跳过宿主或发布
 
 - 现象：本地 `npm run dev` 因 `3101` 已占用、重复发布 SpacetimeDB wasm 编译太慢，或只想检查 `spacetime-module` 语法而被完整联调链路拖慢。
diff --git a/docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md b/docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md
index 785c6ace..3eb2419e 100644
--- a/docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md
+++ b/docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md
@@ -60,6 +60,39 @@ spacetime --root-dir server-rs/.spacetimedb/local list --server http://127.0.0.1
 
 如果裸 `spacetime login show` 的身份与 `--root-dir server-rs/.spacetimedb/local login show` 不一致，而目标库只出现在本地 root 的 `list` 结果中，说明不能使用裸 `spacetime publish`。应通过 `npm run dev:rust` 或显式追加 `--root-dir=server-rs/.spacetimedb/local` 重新发布。
 
+### 4.1 `npm run dev` 本地 401 / 403 快速恢复
+
+如果 `npm run dev` 启动本地开发栈时，SpacetimeDB 在登录、发布或预检查阶段返回 `401` / `403`，且确认本地测试库可以丢弃，可以按下面顺序重置本机默认 local server、旧 CLI token 和本地数据库：
+
+```powershell
+# 1. 先停掉正在跑的本地 server
+Get-Process spacetimedb-standalone, spacetime -ErrorAction SilentlyContinue
+
+# 如确认只是本地测试 server，可结束它
+Stop-Process -Name spacetimedb-standalone -ErrorAction SilentlyContinue
+
+# 2. 清掉 CLI 保存的旧 token
+spacetime logout
+
+# 3. 确认默认目标是本地，或发布时显式指定 local
+spacetime server list
+spacetime server set-default local
+
+# 4. 如要彻底清空默认本地库，停 server 后再清
+spacetime server clear -y
+
+# 5. 重新启动默认本地 server
+spacetime start
+
+# 6. 另开一个终端，向当前 local server 重新拿本地 token
+spacetime login --server-issued-login local
+
+# 7. 再发布
+spacetime publish --server local A
+```
+
+这条流程适合“本地 `npm run dev` 因旧 token、旧本地库或 CLI 默认 server 混乱导致无法继续”的场景。若当前目标库需要保留数据，不要执行 `spacetime server clear -y`，先按上一段对比 `login show`、`--root-dir` 和数据库所有者身份。
+
 如果目标是本地部署库，且允许清空本地数据：
 
 ```bash