diff --git a/AGENTS.md b/AGENTS.md
index 54fe57c..5111d1c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -113,6 +113,7 @@ users (
   key_check    BYTEA,         -- 派生密钥加密已知常量，用于验证密码短语
   key_params   JSONB,         -- 算法参数，如 {"alg":"pbkdf2-sha256","iterations":600000}
   api_key      TEXT UNIQUE,   -- MCP Bearer token，明文存储（设计决策，见下方说明）
+  key_version  BIGINT       NOT NULL DEFAULT 0,  -- 密码短语变更时递增，用于使其它设备会话失效
   created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   updated_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
 )
@@ -165,10 +166,18 @@ oauth_accounts (
 | `secrets.type` | 密钥类型（调用方提供，默认 `text`） | `text`, `password`, `key` |
 | `secrets.encrypted` | 密文 | AES-GCM |
 
+### Web JSON API 与会话
+
+除页面路由使用的 `require_valid_user`（未登录或 `key_version` 与库不一致时重定向 `/login`）外，JSON API（`/api/...`）使用等价校验：会话中的 `key_version` 须与 `users.key_version` 一致，否则返回 **401** JSON，避免仅校验 `user_id` 时与页面行为不一致。
+
 ### Web 条目页表格列（`/entries`）
 
 列表仅展示非敏感字段；**名称**与**操作**列为固定列（不可在「显示列」中关闭）。**文件夹**（对应 `entries.folder`）、类型、备注、标签、关联、密文等为**可选列**，由用户在「显示列」面板中勾选；可见性保存在浏览器 `localStorage`，键为 **`entries_col_vis`**。新增列会并入默认：若用户曾保存过旧版配置，缺失的列键会按当前默认补齐。**文件夹**列默认**显示**，便于在「全部」等跨 folder 视图下区分条目所属隔离空间。
 
+### 导出 / 导入文件
+
+JSON/TOML/YAML 导出可在每条目上包含 `secret_types`（secret 名 → `text` / `password` / `key` 等），导入时写回 `secrets.type`；**旧版导出无该字段**时导入仍成功，类型按 **`text`** 默认。
+
 ### 共享密钥（N:N 关联）
 
 多个 entry 可共享同一 secret 字段，通过 `entry_secrets` 中间表关联。
diff --git a/README.md b/README.md
index df339bb..d04c7c5 100644
--- a/README.md
+++ b/README.md
@@ -72,9 +72,9 @@ SECRETS_ENV=production
 | `secrets_update` | 是 | 更新条目，支持 `id` 或 `name`+`folder` 定位 |
 | `secrets_delete` | 否 | 删除条目，支持 `id` 或 `name`+`folder` 定位；`dry_run=true` 预览删除 |
 | `secrets_history` | 否 | 查看条目历史，支持 `id` 或 `name`+`folder` 定位 |
-| `secrets_rollback` | 是 | 回滚条目到指定历史版本，支持 `id` 或 `name`+`folder` 定位 |
+| `secrets_rollback` | 否 | 回滚条目到指定历史版本（服务端按历史快照恢复元数据与密文关联），支持 `id`；仅需 **Bearer**，不要求 `X-Encryption-Key` |
 | `secrets_export` | 是 | 导出条目（含解密明文），支持 JSON/TOML/YAML 格式 |
-| `secrets_env_map` | 是 | 将 secrets 转换为环境变量映射（`UPPER(entry)_UPPER(field)` 格式），支持 `prefix` |
+| `secrets_env_map` | 是 | 将 secrets 转为环境变量映射：`PREFIX_ENTRYNAME_FIELDNAME`（字段名中 `.`→`__`、`-`→`_` 再转大写，避免与纯下划线字段名碰撞），支持 `prefix` |
 | `secrets_overview` | 否 | 返回各 folder 和 type 的 entry 计数概览 |
 
 ### 消歧规则