diff --git a/docs/开发环境册.md b/docs/开发环境册.md
index 30a05c2..2c6126c 100644
--- a/docs/开发环境册.md
+++ b/docs/开发环境册.md
@@ -50,7 +50,8 @@ NATS 不可达 → SSE 推送停摆、`/health` 照实报 fail，但代理/上
 `requireService(['api-gateway'])`——只认网关。`src/shared/service-token.ts` 用
 `config.keycloak.clientId` ＋ `KEYCLOAK_CLIENT_SECRET` 换 `client_credentials` token，
 两者必须是**同一个 client** 的。相关的 realm 角色与 audience mapper 配置记录见
-`docs/keycloak-setup-log.md`（该文只记对象名与操作结果，同样不含密钥值）。
+`docs/keycloak-setup-log.md`——**该文不含任何密钥值**（它自己在开头也声明"不含任何 secret、
+密码或完整 token"），**但记有 Keycloak 站点地址与 realm 名**，引用或外发时注意范围。
 
 `.env` / `.env.*` 已在 `.gitignore`（`!.env.example` 例外）。收尾核验里
 `git log --all --oneline --diff-filter=A -- .env | wc -l` 必须为 `0`。
@@ -59,8 +60,12 @@ NATS 不可达 → SSE 推送停摆、`/health` 照实报 fail，但代理/上
 
 ## 3. 端口与运行
 
+**新人第一步**：本仓 `package.json` 的 `engines` 声明 **Node ≥ 22**；包管理器用 **pnpm**
+（仓内有 `pnpm-lock.yaml` 与 `pnpm-workspace.yaml`，别用 npm/yarn 装）。
+
 ```bash
 pnpm i               # 装依赖
+cp .env.example .env # 照 §2.2 逐项填；真值向共享设施的凭证发放渠道索取，不要向别人的 .env 复制
 pnpm dev             # tsx watch，读 .env，起在 :8800
 pnpm gates           # typecheck + lint + test
 ```
@@ -91,7 +96,7 @@ fake-agent 桩 8901（在 Task 仓 `tools/fake-agent.ts`，Activity 仓交付真
 ## 5. 测试纪律
 
 本仓无库，共享库那套 `zz_test_` 前缀 / `afterAll` 谓词清理 / LIKE 下划线转义 / 生产扫描排除
-的纪律**在本仓无直接落点**，但两条相关的仍适用：
+的纪律**在本仓无直接落点**，但三条相关的仍适用：
 
 1. **集成用例打的是共享 Keycloak 与共享 NATS**，不许起本地替身；不可达就如实跳过或失败。
 2. **`test/support/token.ts` 是三仓同一性文件**（逐字节相同）——改它要同步三仓并重跑同一性脚本。