diff --git a/AGENTS.md b/AGENTS.md
index bf7646f..b82e930 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,13 +13,12 @@ Go 二进制同时提供 REST API 服务和已构建的前端(SPA)静态资源
 
 ## 常用命令
 
-### 启动后端前的必备环境变量
-后端在缺少以下变量时会 **拒绝启动**(由 `backend/config/config.go` 通过 `log.Fatal` 强制)。
-`./run.sh` 会自动注入开发用默认值;直接 `go run` 或 Docker 则不会。
+### 启动密钥(JWT_SECRET / ENCRYPTION_KEY)
+显式设置优先;**未设置时自动生成随机密钥并持久化**到 `$DATA_DIR/.secrets.env`(0600,重启不变),无法持久化才拒绝启动(`backend/config/config.go` resolveSecrets)。`./run.sh` 仍会注入开发默认值。
 
 ```bash
-export JWT_SECRET=$(openssl rand -hex 32)        # >= 32 字符
-export ENCRYPTION_KEY=$(openssl rand -hex 32)    # >= 32 字节(不是 16,详见「安全」一节)
+export JWT_SECRET=$(openssl rand -hex 32)        # 可选:需要固定密钥时显式设置
+export ENCRYPTION_KEY=$(openssl rand -hex 32)    # 可选:>= 32 字节(不是 16,详见「安全」一节)
 ```
 
 ### 开发模式(两个终端,热重载)
diff --git a/CLAUDE.md b/CLAUDE.md
index 5b564e4..bc055c3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,13 +12,12 @@ Go 二进制同时提供 REST API 服务和已构建的前端(SPA)静态资源
 
 ## 常用命令
 
-### 启动后端前的必备环境变量
-后端在缺少以下变量时会 **拒绝启动**(由 `backend/config/config.go` 通过 `log.Fatal` 强制)。
-`./run.sh` 会自动注入开发用默认值;直接 `go run` 或 Docker 则不会。
+### 启动密钥(JWT_SECRET / ENCRYPTION_KEY)
+显式设置优先;**未设置时自动生成随机密钥并持久化**到 `$DATA_DIR/.secrets.env`(0600,重启不变),无法持久化才拒绝启动(`backend/config/config.go` resolveSecrets)。`./run.sh` 仍会注入开发默认值。
 
 ```bash
-export JWT_SECRET=$(openssl rand -hex 32)        # >= 32 字符
-export ENCRYPTION_KEY=$(openssl rand -hex 32)    # >= 32 字节(不是 16,详见「安全」一节)
+export JWT_SECRET=$(openssl rand -hex 32)        # 可选:需要固定密钥时显式设置
+export ENCRYPTION_KEY=$(openssl rand -hex 32)    # 可选:>= 32 字节(不是 16,详见「安全」一节)
 ```
 
 ### 开发模式(两个终端,热重载)