docs: clarify SpacetimeDB root-dir usage

.hermes/shared-memory/pitfalls.md

@@ -118,17 +118,17 @@
 ## 本地 SpacetimeDB replica identity 不匹配
 
 - 现象：本地 standalone 启动时报 `mismatched database identity`。
-- 原因：root-dir / replica 数据残留与当前数据库身份不一致。
+- 原因：本地 SpacetimeDB 数据目录中的 replica 数据残留与当前数据库身份不一致。
 - 处理：按本地 replica identity mismatch 文档进行备份、重建和脚本诊断。
 - 验证：本地 SpacetimeDB 可正常启动并 publish / 访问。
 - 关联：`docs/technical/SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md`。
 
-## 本地 SpacetimeDB publish 403 优先查 CLI root 身份
+## 本地 SpacetimeDB publish 403 优先查 CLI 身份和目标库
 
 - 现象：`spacetime publish` 在 `Pre-publish check` 阶段返回 `403 Forbidden`，提示当前 identity 无权对目标 database identity 执行 `update database`。
-- 原因：裸 `spacetime` 命令使用了全局 CLI 登录态，但本地开发库权限绑定在 `server-rs/.spacetimedb/local` root-dir 的另一个身份上。
-- 处理：对比 `spacetime login show` 和 `spacetime --root-dir server-rs/.spacetimedb/local login show`；本地开发发布必须使用 `npm run dev:rust`，或显式追加 `--root-dir=server-rs/.spacetimedb/local`。
-- 验证：`spacetime --root-dir server-rs/.spacetimedb/local list --server http://127.0.0.1:3101` 能看到目标库；重新发布不再使用无权限的全局 identity。
+- 原因：当前 CLI 登录态不是目标数据库的创建者或授权身份，或 `.env.local` / publish 命令指向了另一个数据库或 SpacetimeDB 服务。
+- 处理：除 CI/CD 脚本内部受控用法外，不再使用 `spacetime --root-dir` 排障或发布。先执行 `spacetime login show`、`spacetime server list`，再用 `spacetime list --server http://127.0.0.1:3101` 或实际 `--server-url` 确认当前身份是否能看到目标库；本地开发发布优先使用 `npm run dev:rust` 或从 `server-rs` 目录执行显式 `--server` 的 `spacetime publish`。如果身份不对，重新登录正确身份、使用项目脚本重新生成本地库，或在 SpacetimeDB 侧补授权。
+- 验证：`spacetime 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 身份
@@ -150,9 +150,9 @@
 ## 本地 SpacetimeDB publish 401 可清本地库重发
 
 - 现象：本地 `spacetime publish` 显示 `401` 无权限，或重新发布仍像是在更新旧库。
-- 原因：本地开发 root-dir 中保留的数据库、控制库身份或发布身份与当前目标不一致。
-- 处理：确认本地开发数据可以丢弃后，执行 `spacetime --root-dir=server-rs/.spacetimedb/local server clear`，再重新运行 `npm run dev` 或本地 publish。
-- 验证：重新发布日志应显示创建新的数据库，而不是更新旧数据库；若仍显示更新或继续 `401`，继续检查 root-dir、库名和 CLI 身份。
+- 原因：本地开发数据目录中保留的数据库、控制库身份或发布身份与当前目标不一致。
+- 处理：确认本地开发数据可以丢弃后，停止本地 SpacetimeDB，备份或删除 `server-rs/.spacetimedb/local/data`，再重新运行 `npm run dev` 或本地 publish；不要用 `--root-dir` 手工清库。
+- 验证：重新发布日志应显示创建新的数据库，而不是更新旧数据库；若仍显示更新或继续 `401`，继续检查数据目录、库名和 CLI 身份。
 - 关联：`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`、`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`。
 
 ## Vite SPA fallback 吞掉 API 请求