docs: apply hierarchy across the corpus

packages/credentials/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/credentials/README.md
-README.md: 1d450cbeef84750fa57ca0151563c496aed0ce12
-README.zh.md: 843230c3cebf35f234d3ad812165b16ea734678b
+README.md: c08831c90333f8515bf86a5af717c38c50b50817
+README.zh.md: c9756c010af5d2db0fc41f3108eabdc7f1161293

packages/credentials/README.md

@@ -1,14 +1,12 @@
-# credentials/
+# credentials/ — credential references
 
 English | [中文](README.zh.md)
 
-The credential capability seam, as three-package shape dictates (interface / implementation / consumers):
+The credential capability family separates reference resolution from its provider:
 
-| Package | Role |
-|---|---|
-| [`credentials/`](credentials/README.md) | Abstract `ctx.credentials`: branded `CredentialRef` references, per-operation `resolve`, UI-safe `describe`, fail-loud `set`/`unset`, the `credentials/updated` commit event |
-| [`credentials-local/`](credentials-local/README.md) | File/environment provider: the live process environment (read-only, wins) layered over `$DSH_HOME/.env` (writable, byte-preserving line edits, hot-reloaded) |
+| Package | Role | ctx key |
+|---|---|---|
+| [`credentials/`](credentials/README.md) | Credential-reference seam | `ctx.credentials` |
+| [`credentials-local/`](credentials-local/README.md) | Environment and local-file provider | registers `ctx.credentials` |
 
-Configuration files carry *references* to secrets (`apiKeyEnv: DEEPSEEK_API_KEY`), never the secrets: the settings document stays safe to sync and render, and rotating a value touches no configuration. The LLM adapters are the first consumers — they resolve their reference once per model request, which is what makes a key stored moments ago reach the very next request without restarting anything.
-
-The seam shape leaves room for keyring-, helper-command-, and KMS-backed providers.
+Configuration carries references, not secret values. Consumers resolve those references at their operation boundary; the child READMEs own mutation, precedence, and storage semantics.

packages/credentials/README.zh.md

@@ -1,14 +1,12 @@
-# credentials/
+# credentials/：凭据引用
 
 [English](README.md) | 中文
 
-凭据能力 seam，按三包形态的要求组织（接口／实现／消费方）：
+凭据能力家族将引用解析与提供方分离：
 
-| 包 | 角色 |
-|---|---|
-| [`credentials/`](credentials/README.md) | 抽象 `ctx.credentials`：品牌化 `CredentialRef` 引用、按操作 `resolve`、对 UI 安全的 `describe`、响亮失败的 `set`/`unset`，以及 `credentials/updated` 提交事件 |
-| [`credentials-local/`](credentials-local/README.md) | 文件／环境 provider：活跃进程环境（只读、优先）叠加在 `$DSH_HOME/.env`（可写、保字节行级编辑、热重载）之上 |
+| 包 | 角色 | ctx 键 |
+|---|---|---|
+| [`credentials/`](credentials/README.md) | 凭据引用 seam | `ctx.credentials` |
+| [`credentials-local/`](credentials-local/README.md) | 环境与本地文件提供方 | 注册 `ctx.credentials` |
 
-配置文件携带的是对机密的*引用*（`apiKeyEnv: DEEPSEEK_API_KEY`），绝不携带机密本身：设置文档可以放心同步与渲染，轮换值不触碰任何配置。LLM 适配器是第一批消费方——它们每次模型请求解析一次引用，正因如此，片刻前存入的密钥无需重启任何组件即可作用于紧随其后的下一次请求。
-
-seam 形状为 keyring、辅助命令与 KMS 后端的 provider 留有余地。
+配置携带引用而非机密值。消费方在其操作边界解析这些引用；变更、优先级与存储语义由子级 README 负责。