From 2c47636a85b2ac4dc38c399a58b2923456913ce3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 12:45:18 +0800
Subject: [PATCH] docs(environment): state the snapshot's name-matching
 contract

The Windows case-folding in the lookup was implemented without a
user-facing contract. Name matching follows the platform, and the
reason it must is the layer ranking it would otherwise invert.
---
 packages/util/environment/README.i18n.yaml | 4 ++--
 packages/util/environment/README.md        | 2 ++
 packages/util/environment/README.zh.md     | 2 ++
 3 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index c7ad354478..ea1e025257 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/environment/README.md
-README.md: 526c7263106962cdbc19ec58c00b06e58849a258
-README.zh.md: 203b8252d2e96235ec083481ccafda129902cd38
+README.md: 1bb444bc217ce1a01fb98f954d6e1c2bbc3db957
+README.zh.md: a46adf0beeb0fb2069e198c99e4c00c2e8c09c6c
diff --git a/packages/util/environment/README.md b/packages/util/environment/README.md
index 526c726310..1bb444bc21 100644
--- a/packages/util/environment/README.md
+++ b/packages/util/environment/README.md
@@ -18,6 +18,8 @@ Values do also reach `process.env` — a user's `--config` tree and third-party
 
 **Omitting a layer is a refusal, not a demotion** — a caller that must never accept a layer leaves it out of the list, so no future reordering can let it back in. The provider adapters name all three, because the product trusts the project it runs in; the mechanism exists for the decisions where that is not true.
 
+Names match the way the platform matches them: exactly on POSIX, case-insensitively on Windows. A case-sensitive lookup there would rank the wrong layer — a shell's `deepseek_api_key` and a project `.env`'s `DEEPSEEK_API_KEY` are one variable to the OS, and treating them as two would let the project win.
+
 ```ts
 import type { Context } from 'cordis'
 import { environmentOf } from '@deepseek-ai/dsh-environment'
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index 203b8252d2..a46adf0bee 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -18,6 +18,8 @@
 
 **省略某一层是拒绝，不是降级**——绝不能接受某一层的调用方直接不把它列进去，后续任何重新排序都无法让它回来。provider 适配器三层全列，因为产品信任它所运行的项目；该机制是为那些「并非如此」的决策准备的。
 
+变量名按平台自身的规则匹配：POSIX 上精确匹配，Windows 上不区分大小写。在 Windows 上做大小写敏感的查找会选错层——shell 里的 `deepseek_api_key` 与项目 `.env` 里的 `DEEPSEEK_API_KEY` 对操作系统而言是同一个变量，把它们当成两个就会让项目胜出。
+
 ```ts
 import type { Context } from 'cordis'
 import { environmentOf } from '@deepseek-ai/dsh-environment'