diff --git a/crates/design/src/palette/resolve/provenance.rs b/crates/design/src/palette/resolve/provenance.rs
index ee8c63b..c7734f9 100644
--- a/crates/design/src/palette/resolve/provenance.rs
+++ b/crates/design/src/palette/resolve/provenance.rs
@@ -175,9 +175,23 @@ impl Provenance {
 
     /// UI 提示键（`None` = 无需提示）。
     ///
-    /// 形如 `palette.hint.background.low-chroma`，文案映射表见
-    /// `DevDocs/SubAgentsTalk/palette-source-contract.md`。`key` 稳定、可持久化进日志；
-    /// 本 crate 不产出人话文案（文案属于 UI 层，D40 的分层纪律）。
+    /// 形如 `palette.hint.background.low-chroma`，`key` 稳定、可持久化进日志；
+    /// 本 crate 不产出人话文案（文案属于 UI 层，D40 的分层纪律），UI 只做查表：
+    ///
+    /// | 键 | 建议文案（`{card}` = `provenance.card.name()`） |
+    /// |---|---|
+    /// | `palette.hint.background.undecodable` | 背景图读取失败，已改用{card}配色 |
+    /// | `palette.hint.background.too-small` | 背景图太小，无法取色，已改用{card}配色 |
+    /// | `palette.hint.background.bad-dimensions` | 背景图数据异常，已改用{card}配色 |
+    /// | `palette.hint.background.no-opaque-pixels` | 背景图几乎全透明，无法取色，已改用{card}配色 |
+    /// | `palette.hint.background.low-chroma` | 背景图颜色太淡，取不出主题色，已改用{card}配色 |
+    /// | `palette.hint.background.contrast` | 背景图配色达不到可读性要求，已改用{card}配色 |
+    /// | `palette.hint.wallpaper.*` | 同上，把「背景图」换成「桌面壁纸」 |
+    /// | `palette.hint.preset.contrast` | 当前配色可读性不足，已自动微调 |
+    /// | `palette.hint.adjusted` | 为可读性微调了少量颜色（`adjustments` 非空但无失败） |
+    ///
+    /// 完整契约（含可选补充提示、持久化纪律、性能账）见
+    /// `DevDocs/SubAgentsTalk/palette-source-contract.md`（该目录是本地文档，不入库）。
     ///
     /// 优先级：① 先解释「为什么回落」（第一个失败的层级）→ ② 再说「微调过对比度」。
     /// 前者对用户更重要：用户看到的是「我的壁纸怎么没生效」，而不是「颜色被调了 2%」。