diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index caa92d8a..30989b63 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -296,11 +296,14 @@ jobs:
       - name: Build debug
         run: cargo build --all-features
 
-      - name: Verify embedded script help matches docs
+      - name: Verify embedded help matches docs
         run: |
           tmpfile="$(mktemp)"
+          trap 'rm -f "$tmpfile"' EXIT
           target/debug/ghostscope --script-help > "$tmpfile"
           diff -u docs/scripting.md "$tmpfile"
+          target/debug/ghostscope --value-diagnostics-help > "$tmpfile"
+          diff -u docs/value-diagnostics.md "$tmpfile"
 
       - name: Build release
         run: cargo build --release --all-features
diff --git a/README-zh.md b/README-zh.md
index 9885a298..45a86e6d 100644
--- a/README-zh.md
+++ b/README-zh.md
@@ -221,6 +221,10 @@ GhostScope 把编译后的二进制重新变成“可观测系统”。在 TUI 
 - [**使用限制**](docs/zh/limitations.md)
   已知的限制和约束
 
+- [**值诊断**](docs/zh/value-diagnostics.md)
+  理解值不可用、内存读取失败、展示降级和采集限制；
+  使用 `ghostscope --value-diagnostics-help` 离线查看
+
 </td>
 <td width="33%" valign="top">
 
@@ -237,7 +241,7 @@ GhostScope 把编译后的二进制重新变成“可观测系统”。在 TUI 
   输入模式所有可用命令
 
 - [**脚本语言**](docs/zh/scripting.md)
-  编写强大的追踪脚本
+  编写追踪脚本；使用 `ghostscope --script-help` 离线查看
 
 </td>
 <td width="33%" valign="top">
diff --git a/README.md b/README.md
index 4cc37796..b90dcd4a 100644
--- a/README.md
+++ b/README.md
@@ -226,6 +226,10 @@ See [Limitations](docs/limitations.md) for unsupported and explicitly degraded s
 - [**Limitations**](docs/limitations.md)
   Known limitations and constraints
 
+- [**Value Diagnostics**](docs/value-diagnostics.md)
+  Understand unavailable values, read failures, display fallbacks, and capture limits;
+  read offline with `ghostscope --value-diagnostics-help`
+
 </td>
 <td width="33%" valign="top">
 
@@ -242,7 +246,7 @@ See [Limitations](docs/limitations.md) for unsupported and explicitly degraded s
   All available commands for Input Mode
 
 - [**Script Language**](docs/scripting.md)
-  Write powerful trace scripts
+  Write trace scripts; read offline with `ghostscope --script-help`
 
 </td>
 <td width="33%" valign="top">
diff --git a/docs/architecture.md b/docs/architecture.md
index d220fb97..498efb20 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -39,6 +39,36 @@ validated protocol record or explicit failure state
 | Event transport | `LOSS-1` | RingBuf or PerfEventArray carries events; output-helper failures increment per-trace loss counters. |
 | Protocol and rendering | `IDENT-1`, `FAIL-1` | Trace/PID/TID metadata and structured unavailable, expression-error, and backtrace states remain visible to consumers. |
 
+## Value Display Diagnostics
+
+Static display limits and runtime read statuses travel separately. The DWARF
+layer resolves a `ValueReadPlanResolution` containing an optional capture plan,
+path-qualified static notes, and any rejected root adapter report. Notes survive
+even when no semantic capture is selected; ordinary DWARF reads retain their
+runtime address checks. The compiler adds limits discovered during bounded
+capture lowering and finalizes notes for both memory-backed and register-backed
+arguments, binding them to expression/type indices in `TraceContext`. Setup messages deduplicate
+resolved expressions, types, and reasons even when internal indices differ.
+
+CLI, TUI creation results, and trace snapshots consume the same structured
+notes. Snapshots retain them for `info trace`, independently of logs and loader
+actor ownership. Runtime read failures retain `VariableStatus` and individual
+nested-child statuses; the formatter never parses logs to infer failures.
+Diagnostic metadata adds no eBPF memory reads and does not change the binary
+status layout. Optional sequence-width metadata identifies proven element-limit
+truncation; legacy metadata retains a general capture-limit explanation.
+
+At semantic depth boundaries, bounded type-only lookahead avoids diagnosing
+plain field-only structs as failed adapters. It does not traverse runtime
+pointer graphs. Static enum-path notes describe possible branches, not observed
+read failures. User-facing explanations and next steps are in
+[value diagnostics](value-diagnostics.md).
+
+The CLI embeds that same Markdown file for `--value-diagnostics-help`, using the same
+early-exit path as `--script-help`. CI compares both outputs with their source
+documents. Skills route to the installed binary's reference instead of
+maintaining a separate copy of the guide.
+
 ## System Overview
 
 ```
diff --git a/docs/configuration.md b/docs/configuration.md
index 4bb344ea..52ca4f93 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -68,6 +68,9 @@ ghostscope --script-file trace.gs
 # Print the embedded script language reference and exit
 ghostscope --script-help
 
+# Explain value failures, display fallbacks, and capture limits offline
+ghostscope --value-diagnostics-help
+
 # Choose script-mode event stdout rendering
 ghostscope --script-output pretty   # default: formatted stdout
 ghostscope --script-output plain    # payload-only stdout
@@ -290,6 +293,7 @@ index is reported in CLI/TUI startup status before falling back.
 | `--script <SCRIPT>` | `-s` | Inline script to execute | None |
 | `--script-file <PATH>` | | Script file to execute | None |
 | `--script-help` | | Print the embedded script language reference and exit | Off |
+| `--value-diagnostics-help` | | Print the embedded value diagnostics guide and exit | Off |
 | `--script-output <MODE>` | | Script event stdout mode: pretty, plain | pretty |
 | `--backtrace-depth <N>` | | Max DWARF-unwound frames captured by each `bt`/`backtrace` instruction (`1..=128`) | 128 |
 | `--no-backtrace-runtime-modules` | | Disable compact-CFI loading for newly mapped `bt`/`backtrace` modules; events still render with available symbols, module offsets, or raw addresses | Off |
diff --git a/docs/input-commands.md b/docs/input-commands.md
index 49aaea17..9584d570 100644
--- a/docs/input-commands.md
+++ b/docs/input-commands.md
@@ -307,6 +307,8 @@ Displays list of available info subcommands.
 
 ### info trace - View Trace Status
 
+Individual trace details also retain static value-display limits, affected paths, reasons, and documentation links. See [value diagnostics](value-diagnostics.md).
+
 **Syntax:**
 ```
 info trace [id]
diff --git a/docs/limitations.md b/docs/limitations.md
index 540bf60f..b9ee9632 100644
--- a/docs/limitations.md
+++ b/docs/limitations.md
@@ -1,5 +1,7 @@
 # Limitations
 
+For value failure and fallback messages and next steps, see [value diagnostics](value-diagnostics.md).
+
 This document describes conditions outside the supported operating envelope or
 cases that degrade explicitly. The guarantees that remain mandatory inside the
 supported envelope are defined in the
diff --git a/docs/scripting.md b/docs/scripting.md
index fac17688..3769ecb2 100644
--- a/docs/scripting.md
+++ b/docs/scripting.md
@@ -134,6 +134,8 @@ Practical guidance:
 
 ### Rust Value Presentation
 
+For unavailable values, read failures, display fallbacks, and capture limits, see [value diagnostics](value-diagnostics.md), also available offline with `ghostscope --value-diagnostics-help`. CLI prints static display notes by default; TUI retains them in `info trace <id>`.
+
 Rust value support does not add Rust-specific syntax to the DSL. After the DSL
 resolves an expression, the DWARF layer may select a bounded semantic read plan
 for its root type. If the concrete type identity or layout does not validate,
@@ -220,13 +222,14 @@ trace do_stuff {
   explicit memory-read behavior.
 - `ebpf.mem_dump_cap` bounds each indirect argument and defaults to 256 bytes.
   A semantic value whose logical length exceeds the captured prefix is marked
-  `<truncated>`.
+  `<truncated: byte limit>`, `<truncated: element limit>`, or the more general
+  `<truncated: capture limit>`, depending on the available evidence.
 
 For example, with `mem_dump_cap = 3`, an `&str` containing
 `"hello from rust"` is rendered as:
 
 ```text
-"hel" <truncated>
+"hel" <truncated: byte limit>
 ```
 
 The value can also be read explicitly when its target DWARF exposes known
@@ -376,7 +379,7 @@ DWARF variables include locals, parameters, and globals from the traced program.
 | Enum | `enum E` | Enum (via base int) | Printed as `Type::Variant`; arithmetic/compare uses base integer |
 | Bitfield | `int flags:3` | Bitfield → integer view | Extracted integer; mixes with script ints/bools |
 | Typedef/Qualified | `typedef`, `const`, `volatile` | Typedef/QualifiedType | Treated as underlying type |
-| Optimized‑out | variable optimized away | OptimizedOut | Read fails; renders `<OPTIMIZED_OUT>`; operations follow failure semantics |
+| Optimized‑out | variable optimized away | OptimizedOut | No recoverable value at this location; renders `<unavailable: optimized out>`; operations follow failure semantics |
 | Unknown | unsupported/unknown | Unknown | Renders `<UNKNOWN_TYPE_N_BYTES>` |
 
 #### Supported Complex Access
@@ -532,7 +535,7 @@ Notes:
 - Reads are type-sensitive. For `{:x}`, the DWARF/script type controls the captured value size and how the value is materialized. For `{:x.N}`/`{:s.N}`, pointers use the pointer value as the read address, arrays/aggregates use their base address, and addressable scalar DWARF variables use their storage address. A pure script integer is not addressable and will be rejected unless you explicitly cast it to a pointer type.
 - Kernel performs bounded reads for memory-dump forms; user space renders hex/ASCII. For `{:s}` ASCII, rendering stops at first NUL; non‑printables show as `\xNN`.
 - Per‑argument read cap is controlled by `ebpf.mem_dump_cap` (default 256 bytes). Requests beyond cap are truncated; if event payload is exceeded, output may also truncate with `…`.
-- On read failure (e.g., null deref, offsets unavailable, permission), extended specifiers print `<MISSING_ARG>`.
+- Extended specifiers preserve runtime read-failure messages (such as null dereference or unavailable offsets). `<MISSING_ARG>` means a formatting argument is missing. See [value diagnostics](value-diagnostics.md).
 
 Example:
 
diff --git a/docs/value-diagnostics.md b/docs/value-diagnostics.md
new file mode 100644
index 00000000..6498b9bd
--- /dev/null
+++ b/docs/value-diagnostics.md
@@ -0,0 +1,175 @@
+# Understanding value diagnostics
+
+GhostScope distinguishes an unavailable value, a failed memory read, a display
+fallback, and a partial capture. A display note does not mean the trace failed
+to attach. Successfully captured fields remain available.
+
+| Output | Meaning | Next step |
+| --- | --- | --- |
+| `<unavailable: optimized out>` | No recoverable value at this probe location | [Choose another location](#optimized-out) |
+| `<unreadable: memory read failed; errno=…; address=…>` | This read failed; possible causes include a page that cannot be faulted in or an invalid address | [Check memory reads; consider sleepable uprobes](#memory-read-failed) |
+| `<internal fields: layout unsupported>` | The type's contents could not be interpreted; physical fields are shown | [Check supported layouts](#layout-unsupported) |
+| `<internal fields: read plan unsupported>` | Debug information could not describe the required reads | [Inspect the debug information](#read-plan-unsupported) |
+| `<truncated: byte limit>` | Only a prefix of the bytes was captured | [Check the byte budget](#byte-limit) |
+| `<truncated: element limit>` | The nested sequence reached the configured width | [Check the element limit](#element-limit) |
+| `<truncated: capture limit>` | Capture was incomplete; the status alone does not identify which limit | [Check capture limits](#capture-limit) |
+| `<not expanded: capture budget>` | Nested capture did not fit; the root display is retained | [Check the nested budget](#capture-budget) |
+| `<nested display limits: depth limit; see trace details>` | Some nested types have static display limits | Read the trace's display notes |
+
+## Finding the reason
+
+Read this guide offline from the installed binary:
+
+```bash
+ghostscope --value-diagnostics-help
+```
+
+Like `--script-help`, this prints the embedded English reference to stdout and
+exits without loading configuration, inspecting a target, or requiring eBPF
+privileges. The content ships with the binary, so it is also available to LLM
+tools without a source checkout or network access.
+
+CLI mode prints static display notes to stderr once per expression/type/reason
+in each compiled trace, even with `--no-log` and `--no-status`. TUI mode shows
+them in trace creation results and retains them in `info trace <id>`. This also
+applies to traces loaded from a saved file. Dry runs report the same static
+notes; runtime reads cannot be checked until a probe runs.
+
+A note names the expression and affected path, the type, a stable reason, the
+technical detail, and a link to this page. `[]` denotes collection elements;
+`::Some.__0` denotes a possible enum payload (field names follow DWARF).
+These are **capture-plan limits**:
+they do not claim that a collection is nonempty or that a variant is active.
+Runtime read errors belong to the actual captured value or child slot.
+
+Normal structs do not need a special adapter. Their ordinary field display is
+not itself a failure. Debug logs and `dwarf-tool rust-adapter` remain useful for
+deeper investigation, but are not required to see a display fallback.
+
+## optimized-out
+
+`<unavailable: optimized out>` means the selected location has no recoverable
+value for that variable. Direct printing can emit this placeholder; using the
+variable in arithmetic or taking its address fails during script compilation.
+
+Try a source location where the value is still live. If rebuilding the target
+is possible, retain debug information and consider reducing optimization.
+Increasing capture limits or enabling sleepable uprobes cannot recover a value
+that the compiler removed.
+
+## memory-read-failed
+
+`<unreadable: memory read failed>` means a target-memory read failed on this
+event. **The errno alone, including `-EFAULT`, cannot distinguish a page that
+cannot be faulted in from an invalid address.** Other possibilities include
+inaccessible memory, a value observed during mutation, mismatched debug
+information, or incorrect address calculation by GhostScope. This is a runtime
+read failure; a static depth-limit note does not explain its cause. Other
+successfully captured fields remain useful; the event is not a process-wide
+atomic snapshot.
+
+First confirm that the binary and separate debug information match, and that
+the probe location and object's lifetime are appropriate. A target pointer may
+itself be null, dangling, or changing concurrently even with matching debug
+information. **If GhostScope computes an invalid address for an object known
+to be valid and live, with matching debug information, that is a GhostScope
+bug.** Report the expression, source/probe location, exact output (including
+errno and address), binary/debug-file identity, GhostScope version, and a
+minimal reproducer when possible. A failed read alone does not establish which
+component is responsible.
+
+If the memory is valid but may not be resident, retry the existing command
+with **`--sleepable-uprobe`**, or use:
+
+```toml
+[ebpf]
+sleepable_uprobe = true
+```
+
+Sleepable uprobes allow supported reads to fault in pages. They require Linux
+5.18+ and RingBuf output. Fixed-length reads use a fault-capable helper;
+NUL-terminated reads that use `bpf_probe_read_user_str()` still cannot fault in
+pages. This option cannot fix an invalid address, missing DWARF, or an
+unsupported type layout.
+
+Enabling it can add probe latency, especially when a read actually faults or
+blocks on I/O. The impact may be small for a particular workload, but is not
+guaranteed to be small; measure the target's latency and probe frequency.
+See [Sleepable Uprobe](configuration.md#sleepable-uprobe) for kernel checks,
+output compatibility, and backtrace behavior.
+
+Null-pointer dereference, address-computation failure, and unavailable process
+offsets have their own messages. Do not assume that enabling sleepable uprobes
+resolves those conditions.
+
+## layout-unsupported
+
+The type matched a known adapter, but its target DWARF layout did not satisfy
+the adapter's checks. GhostScope retains the ordinary field representation.
+These are implementation fields, not the semantic contents of a string or
+collection. Increasing a capture budget will not make this layout supported.
+
+Check [Rust value rendering](scripting.md#rust-value-presentation). For a report,
+include the type, rejection detail, target rustc version, matching debug
+information, and a minimal reproducer. If ordinary DWARF capture also fails,
+the compilation error includes the adapter's rejection report.
+
+## read-plan-unsupported
+
+The required dependent type, pointer target, projection, width, or alignment
+could not be resolved from the target debug information. The note includes the
+available technical reason. Check that the target's matching, full debug
+information is available; report a reproducible unsupported case. Raising
+memory limits or enabling sleepable uprobes does not supply missing DWARF.
+
+## byte-limit
+
+A string or byte-string capture returned only a prefix. Check
+`[ebpf].mem_dump_cap` (default 256 bytes per indirect argument). Nested values
+share this budget with their root, metadata, and sibling values, so a child
+can receive fewer bytes than that setting. An omitted payload instead reports
+the broader `capture limit`, because it could also reflect the event budget.
+
+## element-limit
+
+The captured nested sequence reached `value_adapters.max_sequence_elements`.
+Only the displayed elements were captured. Print a specific element or increase
+that setting if more elements are needed; the shared byte budget still applies.
+
+## capture-limit
+
+The result is partial. The available runtime status does not always distinguish
+byte, element, sparse-bucket, tree-node, and total-event limits. GhostScope does
+not invent a more specific cause when the capture metadata cannot prove it.
+
+Check `[ebpf].mem_dump_cap`, `[ebpf].max_trace_event_size`, and
+`[value_adapters].max_sequence_elements` (default 4). The last setting limits
+nested sequence elements or hash buckets; sparse buckets may contain fewer
+actual entries. See [Value Adapter limits](configuration.md#value-adapter-limits).
+Increase only the relevant limit: larger captures can increase eBPF program
+size, event size, and probe overhead.
+
+## depth-limit
+
+The semantic planner stopped expanding nested contents at
+`[value_adapters].max_nesting_depth` (default 4). The note identifies the path
+beyond the limit. A plain struct or enum payload also consumes a semantic edge.
+This is not a memory-read error and does not imply that the root value is
+missing. Inspect a shallower expression or increase the limit deliberately.
+The separate native DWARF formatting limit reports `<MAX_DEPTH_EXCEEDED>`.
+
+## recursive-type
+
+The planner encountered a repeated DWARF type on the current expansion path.
+It keeps the existing representation rather than following the type
+indefinitely. This concerns the type graph; it does not prove that runtime
+objects form a cycle. Raising the nesting limit does not disable this guard.
+Inspect a specific field or explicitly dereference a known pointer instead.
+
+## capture-budget
+
+The compiled nested capture could not fit within the shared byte budget.
+The root display or other captured fields remain, and the note identifies the
+affected path when available. Print the field separately, reduce requested
+nesting or collection width, or increase `ebpf.mem_dump_cap` deliberately.
+This limitation is determined before the probe runs.
diff --git a/docs/zh/architecture.md b/docs/zh/architecture.md
index 46338f5c..66c68451 100644
--- a/docs/zh/architecture.md
+++ b/docs/zh/architecture.md
@@ -36,6 +36,30 @@ GhostScope 的源码语义并不来自某一个独立组件。最终展示的值
 | 事件传输 | `LOSS-1` | RingBuf 或 PerfEventArray 传输事件；输出 helper 失败会增加按 trace 维护的丢失计数。 |
 | 协议与展示 | `IDENT-1`、`FAIL-1` | Trace/PID/TID 元数据以及结构化的不可用、表达式错误和 backtrace 状态会保留给消费方。 |
 
+## 值展示诊断
+
+静态展示限制与运行时读取状态分开传递。DWARF 层返回 `ValueReadPlanResolution`，
+分别保存可选的采集计划、带路径的静态提示和根 adapter 拒绝报告。没有语义采集
+计划时仍保留提示，普通 DWARF 读取继续使用原有运行时地址检查。编译器补充
+实际嵌套采集预算造成的降级，对内存值和寄存器值统一完成诊断关联，绑定到
+`TraceContext` 内的表达式和类型索引。多个内部索引对应同一用户
+表达式时，设置提示按解析后的表达式、类型和原因去重。
+
+CLI、TUI 创建结果和 trace 快照消费相同的结构化诊断。快照保留原因，因此
+`info trace` 不依赖日志或 loader actor 的生命周期。运行时读取失败继续使用
+`VariableStatus` 和每个嵌套子值自己的状态；格式化器不解析日志来推断失败。
+诊断元数据不增加 eBPF 内存读取，也不改变事件的二进制状态布局。新增的
+序列宽度元数据用于区分确实达到元素上限的截断，旧元数据缺失时保留通用原因。
+
+语义深度边界上的说明使用有界的类型信息检查，避免把纯字段 struct 错报为
+语义展示失败；它不展开目标的运行时指针图。枚举路径的静态提示只说明可能
+分支的展示限制，不能用于断言该分支发生过读取错误。用户提示与处理建议见
+[值诊断](value-diagnostics.md)。
+
+CLI 将同一份英文 Markdown 嵌入 `--value-diagnostics-help`，沿用 `--script-help` 的
+提前退出路径。CI 检查两个命令的输出与源文档一致。Skill 引导模型读取
+已安装二进制中的说明，不单独维护诊断指南副本。
+
 ## 系统概览
 
 ```
diff --git a/docs/zh/configuration.md b/docs/zh/configuration.md
index 79087f08..2f2327a9 100644
--- a/docs/zh/configuration.md
+++ b/docs/zh/configuration.md
@@ -69,6 +69,9 @@ ghostscope --script-file trace.gs
 # 输出内嵌的脚本语言参考并退出
 ghostscope --script-help
 
+# 离线查看值读取失败、展示降级和采集限制的解释
+ghostscope --value-diagnostics-help
+
 # 选择脚本模式的事件 stdout 输出方式
 ghostscope --script-output pretty   # 默认：格式化 stdout
 ghostscope --script-output plain    # 仅保留 payload stdout
@@ -284,6 +287,7 @@ ghostscope bpffs prune --dry-run --json
 | `--script <SCRIPT>` | `-s` | 要执行的内联脚本 | 无 |
 | `--script-file <PATH>` | | 要执行的脚本文件 | 无 |
 | `--script-help` | | 输出内嵌的脚本语言参考并退出 | 关 |
+| `--value-diagnostics-help` | | 输出内嵌的值诊断指南并退出 | 关 |
 | `--script-output <MODE>` | | 脚本事件 stdout 模式：pretty, plain | pretty |
 | `--backtrace-depth <N>` | | 每条 `bt`/`backtrace` 指令最多采集的 DWARF unwind 栈帧数（`1..=128`） | 128 |
 | `--no-backtrace-runtime-modules` | | 禁止为 `bt`/`backtrace` 新映射模块加载 compact CFI；事件仍使用已有符号、模块偏移或裸地址输出 | 关 |
diff --git a/docs/zh/input-commands.md b/docs/zh/input-commands.md
index 1cc1dc94..bdbffe2a 100644
--- a/docs/zh/input-commands.md
+++ b/docs/zh/input-commands.md
@@ -303,6 +303,8 @@ i                   # 缩写形式
 
 ### info trace - 查看追踪状态
 
+单个 trace 的详情也会显示静态值展示限制，包括受影响路径、原因和文档入口，详见[值诊断](value-diagnostics.md)。
+
 **语法：**
 ```
 info trace [id]
diff --git a/docs/zh/limitations.md b/docs/zh/limitations.md
index 5e2dfca4..ac47a372 100644
--- a/docs/zh/limitations.md
+++ b/docs/zh/limitations.md
@@ -1,5 +1,7 @@
 # GhostScope 的限制
 
+值输出中的失败和降级提示，以及下一步排查建议，见[值诊断](value-diagnostics.md)。
+
 本文档描述支持范围之外的条件，以及会显式降级的场景。在支持范围内仍然必须成立的保证，统一定义在[设计保证与可信性模型](design-contract.md)中。
 
 ## 硬性限制
diff --git a/docs/zh/scripting.md b/docs/zh/scripting.md
index 3d5d8eff..8c0f5a50 100644
--- a/docs/zh/scripting.md
+++ b/docs/zh/scripting.md
@@ -127,6 +127,8 @@ GhostScope 的脚本语法本身与源语言无关，但实际效果取决于被
 
 ### Rust 值展示
 
+值不可用、读取失败、展示降级和采集限制的提示见[值诊断](value-diagnostics.md)，也可用 `ghostscope --value-diagnostics-help` 离线查看。CLI 默认会输出静态展示提示；TUI 可用 `info trace <id>` 再次查看。
+
 Rust 值支持不会给 DSL 增加 Rust 专用语法。DSL 解析表达式后，DWARF 层
 可以为根类型选择一个有界的语义读取计划。如果具体类型的身份或布局未通过
 验证，GhostScope 会保留原生 DWARF 展示，而不会猜测 Rust ABI。
@@ -200,13 +202,14 @@ trace do_stuff {
 - `{:s.16}`、`{:x.*}` 和 `{:s.n$}` 等带长度形式仍保留通用的显式内存
   读取语义。
 - `ebpf.mem_dump_cap` 限制每个间接参数，默认值为 256 字节。若语义值的
-  逻辑长度超过已采集的前缀，输出会标记 `<truncated>`。
+  逻辑长度超过已采集的前缀，输出会根据已知原因标记 `<truncated: byte limit>`、
+  `<truncated: element limit>`，或更宽泛的 `<truncated: capture limit>`。
 
 例如，当 `mem_dump_cap = 3` 时，内容为 `"hello from rust"` 的 `&str`
 会显示为：
 
 ```text
-"hel" <truncated>
+"hel" <truncated: byte limit>
 ```
 
 如果目标 DWARF 暴露了已知成员，也可以显式读取：
@@ -348,7 +351,7 @@ DWARF 变量其实就是被跟踪的程序里面定义的**局部变量、参数
 | 枚举 | `enum E` | Enum（按底层整型） | 打印为枚举名；在运算/比较时按底层整数处理 |
 | 位域 | `int flags:3` | Bitfield → 整数视图 | 抽取为整数；可与“脚本变量”的整数/布尔混用比较与算术 |
 | 类型别名/限定 | `typedef`/`const`/`volatile` | Typedef/QualifiedType | 按底层类型处理（行为与底层类型一致） |
-| 优化移除 | 变量被优化掉 | OptimizedOut | 读取失败；打印为 `<OPTIMIZED_OUT>`；运算/比较按失败语义处理 |
+| 优化移除 | 变量被优化掉 | OptimizedOut | 当前追踪位置没有可恢复值；打印为 `<unavailable: optimized out>`；运算/比较按失败语义处理 |
 | 未知 | 不支持或未知 | Unknown | 打印为 `<UNKNOWN_TYPE_N_BYTES>` |
 
 #### GhostScope 支持对复杂的 DWARF 变量访问：
@@ -509,7 +512,7 @@ print "tail={:s.n$}", p;          // 长度来自变量 n
 - 读取方式会受类型影响。对于 `{:x}`，DWARF/脚本类型决定捕获值的大小，以及这个值如何被 materialize。对于 `{:x.N}`/`{:s.N}`，指针使用指针值作为读取地址，数组/聚合使用基地址，可取地址的 DWARF 标量变量使用自己的存储地址。纯脚本整数不是地址，除非显式 cast 成指针类型，否则会被拒绝。
 - 内核侧会为内存转储形式做有界读取；用户态负责十六进制/ASCII 渲染。`{:s}` 的 ASCII 渲染遇到首个 NUL 字节即停止；不可打印字节显示为 `\xNN`。
 - 内存转储的单参数上限由配置项 `ebpf.mem_dump_cap` 控制（默认 256 字节）。若请求长度超过该上限，将被截断；若超过事件负载上限，输出也可能被截断并以 `…` 表示。
-- 读取失败（如空指针、偏移不可用、权限等）时，扩展占位符会输出 `<MISSING_ARG>`。
+- 扩展占位符会保留运行时读取失败的提示，例如空指针或进程偏移缺失。`<MISSING_ARG>` 表示格式化实参缺失。详见[值诊断](value-diagnostics.md)。
 
 示例：
 
diff --git a/docs/zh/value-diagnostics.md b/docs/zh/value-diagnostics.md
new file mode 100644
index 00000000..af490443
--- /dev/null
+++ b/docs/zh/value-diagnostics.md
@@ -0,0 +1,145 @@
+# 理解值诊断
+
+GhostScope 区分“值不可用”“内存读取失败”“展示降级”和“只采集了部分内容”。
+展示提示不代表 trace 创建失败；其他成功采集的字段仍可查看。
+
+| 输出 | 含义 | 下一步 |
+| --- | --- | --- |
+| `<unavailable: optimized out>` | 当前追踪位置没有可恢复的值 | [换一个追踪位置](#optimized-out) |
+| `<unreadable: memory read failed; errno=…; address=…>` | 本次读取失败；可能涉及无法处理的缺页或无效地址 | [检查读取条件，考虑 sleepable](#memory-read-failed) |
+| `<internal fields: layout unsupported>` | 无法解释语义内容，保留内部字段 | [检查布局支持](#layout-unsupported) |
+| `<internal fields: read plan unsupported>` | 调试信息不足以描述所需读取 | [检查调试信息](#read-plan-unsupported) |
+| `<truncated: byte limit>` | 只采集了字节前缀 | [检查字节预算](#byte-limit) |
+| `<truncated: element limit>` | 嵌套序列达到配置的元素上限 | [检查元素上限](#element-limit) |
+| `<truncated: capture limit>` | 结果不完整，现有状态不能确定具体限制 | [检查采集限制](#capture-limit) |
+| `<not expanded: capture budget>` | 嵌套采集放不下，保留根值展示 | [检查嵌套预算](#capture-budget) |
+| `<nested display limits: depth limit; see trace details>` | 部分嵌套类型存在静态展示限制 | 查看 trace 的展示提示 |
+
+## 去哪里看原因
+
+可以直接从已安装的二进制离线查看本文档：
+
+```bash
+ghostscope --value-diagnostics-help
+```
+
+与 `--script-help` 一样，这会向 stdout 输出内嵌的英文参考文档并退出，
+不加载配置、不检查目标，也不需要 eBPF 权限。内容随二进制发布，LLM 工具
+也可以在没有源码仓库或网络的环境中读取。
+
+CLI 在编译 trace 时向 stderr 输出展示提示，即使使用 `--no-log` 和
+`--no-status` 也能看到；同一 trace 内相同表达式、类型和原因只提示一次。
+TUI 在 trace 创建结果中展示提示，之后可通过 `info trace <id>` 再次查看。
+从文件加载的 trace 也会保留这些提示。Dry run 能报告相同的静态限制，但实际
+内存能否读出，要等探针运行才能确定。
+
+每条提示包含表达式与受影响路径、类型、稳定原因名、技术详情和本文档入口。
+`[]` 表示集合元素，`::Some.__0` 表示某个可能的枚举 payload（字段名沿用 DWARF）。
+这些是**采集计划的限制**，不表示集合一定非空或该 variant 已经激活。
+运行时读取错误则对应实际读取的值或子值。
+
+普通 struct 本来就可以按字段展示，没有专用 adapter 并不代表出错。
+调试日志和 `dwarf-tool rust-adapter` 仍可用于深入调查，但查看降级原因不再需要
+先开启日志。
+
+## optimized-out
+
+`<unavailable: optimized out>` 表示当前 probe 位置没有可恢复的变量值。
+直接打印可以显示这个占位符；将它用于运算或取地址，会在脚本编译时失败。
+
+可以换到值仍然存活的源码位置。如果能够重建目标，保留调试信息，并考虑降低
+优化级别。增大采集预算或开启 sleepable 不能恢复已经被编译器移除的值。
+
+## memory-read-failed
+
+`<unreadable: memory read failed>` 表示这次事件读取目标内存失败。
+**仅凭 errno（包括 `-EFAULT`），无法区分无法处理的缺页和无效地址。**
+其他可能原因还包括内存不可访问、观测期间发生修改、调试信息不匹配，或
+GhostScope 计算地址有误。这是运行时读取失败，静态的深度限制提示不能解释
+它的原因。其他成功采集的字段仍有参考价值；一次事件不是整个进程的原子快照。
+
+先确认二进制与独立调试信息匹配，追踪位置和对象生命周期也正确。即使调试
+信息匹配，目标指针本身仍可能为空、悬垂，或正在被并发修改。
+**如果对象已确认有效且存活，调试信息也匹配，但 GhostScope 为它计算出了
+无效地址，那就是 GhostScope 的 bug。** 报告时请保留表达式、源码/探针位置、
+完整输出（含 errno 和地址）、二进制及调试文件标识、GhostScope 版本，并尽量
+提供最小复现。单凭一次读取失败，还不能确定问题属于哪一方。
+
+如果内存有效，但相关页面可能尚未驻留，建议在原命令上增加
+**`--sleepable-uprobe`** 重试，或配置：
+
+```toml
+[ebpf]
+sleepable_uprobe = true
+```
+
+sleepable uprobe 允许支持的内存读取处理缺页，要求 Linux 5.18+ 和 RingBuf
+输出。固定长度读取会使用可处理缺页的 helper；需要 NUL 终止语义、仍使用
+`bpf_probe_read_user_str()` 的读取不能因此处理缺页。它不能修复无效地址、
+缺失的 DWARF 或不支持的类型布局。
+
+开启后可能增加探针延迟，尤其是实际发生缺页或等待 I/O 时。特定负载下影响
+可能较轻，但不能保证总是轻微；应结合命中频率观察目标延迟。
+内核检查、输出兼容性和 backtrace 行为见
+[Sleepable Uprobe](configuration.md#sleepable-uprobe)。
+
+空指针、地址计算失败和进程偏移缺失有各自的提示，不能默认通过 sleepable 解决。
+
+## layout-unsupported
+
+类型匹配了已知 adapter，但目标 DWARF 中的布局没有通过验证。GhostScope
+保留普通字段展示；这些字段是实现细节，不是字符串或集合的语义内容。
+增大预算不能解决布局不支持。
+
+检查 [Rust 值展示支持范围](scripting.md#rust-值展示)。报告问题时，提供类型名、
+拒绝详情、目标 rustc 版本、匹配的调试信息和最小复现。如果普通 DWARF 采集也
+无法编译，编译错误会附带 adapter 拒绝报告。
+
+## read-plan-unsupported
+
+目标调试信息无法解析所需的依赖类型、指针目标、字段投影、宽度或对齐。
+提示会保留已知技术原因。检查目标对应的完整调试信息；对于可复现的不支持
+场景，提交最小复现。增大内存预算或开启 sleepable 不能补全缺失的 DWARF。
+
+## byte-limit
+
+字符串或字节串只采集了前缀。检查 `[ebpf].mem_dump_cap`，默认每个间接参数
+256 字节。嵌套值与根值、协议元数据、兄弟字段共享该预算，所以某个字段
+实际能使用的字节可能更少。如果整个 payload 被省略，会使用更宽泛的
+`capture limit`，因为这也可能由事件预算造成。
+
+## element-limit
+
+嵌套序列已经达到 `value_adapters.max_sequence_elements`。只采集了已显示的
+元素；可以单独打印所需元素，或提高该设置。共享字节预算仍然有效。
+
+## capture-limit
+
+结果不完整。现有运行时状态并不总能区分字节、元素、稀疏 bucket、树节点
+以及总事件大小限制；没有充分证据时，GhostScope 不会猜测具体原因。
+
+检查 `[ebpf].mem_dump_cap`、`[ebpf].max_trace_event_size` 和
+`[value_adapters].max_sequence_elements`（默认 4）。最后一项限制嵌套序列
+元素或 Hash 表 bucket，稀疏 bucket 中实际条目可能更少。详见
+[Value Adapter 限制](configuration.md#value-adapter-限制)。
+只调整相关限制；更大的采集量可能增加 eBPF 程序大小、事件大小和探针开销。
+
+## depth-limit
+
+语义规划器在 `[value_adapters].max_nesting_depth`（默认 4）处停止继续展开。
+提示路径指出受影响的更深层内容。穿过普通 struct 或进入枚举 payload 也会
+消耗一层。这不是内存读取失败，也不表示根值丢失。
+可以单独打印较浅的字段，或有针对性地提高深度上限。
+原生 DWARF 格式化另有独立上限，达到时显示 `<MAX_DEPTH_EXCEEDED>`。
+
+## recursive-type
+
+规划器在当前展开路径遇到重复的 DWARF 类型，因此保留已有展示，不再无限
+跟随。这是类型图的循环保护，不能据此断定运行时对象之间存在循环引用。
+提高深度上限不会关闭该保护；可以单独检查字段，或显式解引用已知指针。
+
+## capture-budget
+
+编译后的嵌套采集无法放入共享字节预算。根值展示或其他已采集字段仍会保留，
+可以确定时会指出受影响路径。建议单独打印该字段、降低嵌套深度或集合宽度，
+或有针对性地增大 `ebpf.mem_dump_cap`。这项限制在探针运行前即可确定。
diff --git a/e2e-tests/README.md b/e2e-tests/README.md
index ca14540a..910ac309 100644
--- a/e2e-tests/README.md
+++ b/e2e-tests/README.md
@@ -23,3 +23,47 @@ sudo cargo test -p ghostscope-e2e-tests --tests --all-features -- --nocapture
 Routine host-host e2e skips the explicit container-topology cases. Run them by
 setting `E2E_RUN_CONTAINER_TOPOLOGY=1` or by using one of the docker-backed
 `E2E_GHOSTSCOPE_SANDBOX`/`E2E_TARGET_SANDBOX` topology settings.
+
+## Value diagnostic contracts
+
+[value_diagnostics_execution.rs](tests/value_diagnostics_execution.rs) checks
+the CLI behavior described in the [value diagnostics guide](../docs/value-diagnostics.md).
+Run this suite on its own with:
+
+```bash
+cargo build -p ghostscope -p dwarf-tool --all-features
+sudo cargo test -p ghostscope-e2e-tests --test value_diagnostics_execution --all-features -- --nocapture
+```
+
+All cases use the `test_value_diagnostics_` prefix and are included automatically
+in the normal CI e2e run. The Rust fixtures require the pinned `1.88.0` toolchain
+from [rust-compat-toolchains.txt](rust-compat-toolchains.txt). The optimized-out
+case uses the existing C fixture and first verifies its DWARF location state.
+
+| Scenario | Required observable behavior |
+| --- | --- |
+| Optimized-out variable | Printing shows `unavailable`; using it in an expression fails compilation and names the variable and probe-location limitation. |
+| Failed memory read | Root values, nested fields, and explicit memory dumps retain `unreadable`, errno, and the attempted address; readable siblings survive. Checked with both RingBuf and PerfEventArray. |
+| Null dereference | Explicit dereference reports its own error, separately from a failed memory read. |
+| Unsupported layout / read plan | Successful DWARF fallback retains raw fields and identifies the distinct reason. Failed fallback reports the underlying compilation error and adapter details. |
+| Byte / element limit | Captured prefixes remain visible, with the correct truncation reason; empty strings remain valid empty values. |
+| Depth / recursive-type limit | Static notes identify affected paths without claiming an inactive enum variant was read or a finite tree contains a runtime cycle. |
+| Diagnostic-only aggregate | Static depth notes retain the ordinary read path; null dereference and failed reads remain distinct, and neither failure is labeled as a depth limit. |
+| Register-backed argument | A DWARF location check proves the argument is in a register; its depth note survives just as it does for an address-backed peer. |
+| Capture budget | Root fields remain visible when nested expansion cannot fit; a static note identifies the budget limit. |
+| Event capture limit | Omitted payloads report capture truncation, without claiming a memory read failed. |
+| Offline documentation | `--value-diagnostics-help` matches the shipped English guide and bypasses invalid runtime inputs; both language guides contain every public reason. |
+
+Keep assertions on the stable marker, reason, retained data, exit status, and
+output stream. Static notes must remain available with `--no-log --no-status`,
+include a documentation entry point, and avoid duplicate notes for repeated
+prints. Ordinary structs and valid empty values serve as controls against
+false diagnostics. Do not snapshot timestamps, ASLR addresses, decoration, or
+whole explanatory paragraphs. Deliberately invalid fixture addresses are fixed
+constants, not application dereferences or corrupted standard-library values.
+Fixtures touch readable globals before the probe so that untouched page mappings
+do not accidentally turn a healthy control into another non-sleepable read error.
+
+When changing a public diagnostic, update its case here and both language
+guides together. Keep renderer and protocol edge cases in unit tests; this
+suite exercises the compiled CLI, real DWARF, eBPF capture, and final output.
diff --git a/e2e-tests/tests/common/termination.rs b/e2e-tests/tests/common/termination.rs
index 72857b04..0d98900f 100644
--- a/e2e-tests/tests/common/termination.rs
+++ b/e2e-tests/tests/common/termination.rs
@@ -115,9 +115,8 @@ pub(crate) async fn terminate_tokio_child_with_escalation(
         .context("child process does not have an OS pid for SIGTERM")?;
     send_sigterm(pid, label)?;
 
-    match tokio::time::timeout(graceful_timeout, child.wait()).await {
-        Ok(result) => return result.map(Some).map_err(Into::into),
-        Err(_) => {}
+    if let Ok(result) = tokio::time::timeout(graceful_timeout, child.wait()).await {
+        return result.map(Some).map_err(Into::into);
     }
 
     child
diff --git a/e2e-tests/tests/entry_value_recovery_execution.rs b/e2e-tests/tests/entry_value_recovery_execution.rs
index d578ca1f..1966f287 100644
--- a/e2e-tests/tests/entry_value_recovery_execution.rs
+++ b/e2e-tests/tests/entry_value_recovery_execution.rs
@@ -505,7 +505,7 @@ async fn test_non_inline_entry_value_recovers_touch_parameters_at_runtime() -> a
         "Expected exact non-inline entry_value recovery inside touch(). STDOUT: {ghostscope_stdout}\nSTDERR: {ghostscope_stderr}"
     );
     assert!(
-        !ghostscope_stdout.contains("<optimized out>"),
+        !ghostscope_stdout.contains("<unavailable: optimized out>"),
         "touch() parameters should not be optimized out. STDOUT: {ghostscope_stdout}\nSTDERR: {ghostscope_stderr}"
     );
 
@@ -665,7 +665,7 @@ async fn test_post_call_entry_value_recovers_state_members_at_runtime() -> anyho
 STDERR: {ghostscope_stderr}"
     );
     assert!(
-        !ghostscope_stdout.contains("<optimized out>"),
+        !ghostscope_stdout.contains("<unavailable: optimized out>"),
         "Post-call entry_value should not be optimized out. STDOUT: {ghostscope_stdout}
 STDERR: {ghostscope_stderr}"
     );
@@ -854,7 +854,7 @@ async fn test_entry_value_breg_stack_parameter_recovers_at_runtime() -> anyhow::
         "Expected entry_value(breg7 + 8) stack recovery. STDOUT: {ghostscope_stdout}\nSTDERR: {ghostscope_stderr}"
     );
     assert!(
-        !ghostscope_stdout.contains("<optimized out>"),
+        !ghostscope_stdout.contains("<unavailable: optimized out>"),
         "entry_value(breg7 + 8) stack parameter should not be optimized out. STDOUT: {ghostscope_stdout}\nSTDERR: {ghostscope_stderr}"
     );
 
diff --git a/e2e-tests/tests/fixtures/rust_adapter_rejection_program/sized/alloc.rs b/e2e-tests/tests/fixtures/rust_adapter_rejection_program/sized/alloc.rs
new file mode 100644
index 00000000..208ba8d9
--- /dev/null
+++ b/e2e-tests/tests/fixtures/rust_adapter_rejection_program/sized/alloc.rs
@@ -0,0 +1,124 @@
+pub mod string {
+    pub struct String {
+        pub raw: u64,
+    }
+}
+#[used]
+#[no_mangle]
+pub static G_REJECTED_STRING: string::String = string::String { raw: 42 };
+#[inline(never)]
+#[no_mangle]
+pub extern "C" fn observe_adapter_rejection() -> usize {
+    std::hint::black_box(&G_REJECTED_STRING as *const _ as usize)
+}
+fn main() {
+    loop {
+        // Fault in the root objects before the probe. Merely taking their
+        // addresses leaves untouched read-only pages unavailable to a normal
+        // uprobe. These structs own no allocations; the raw pointers are
+        // copied here, never dereferenced by the target.
+        unsafe {
+            std::hint::black_box(std::ptr::read_volatile(&G_REJECTED_STRING));
+            std::hint::black_box(std::ptr::read_volatile(&G_PLAIN));
+            std::hint::black_box(std::ptr::read_volatile(std::ptr::addr_of!(G_UNREADABLE)));
+            std::hint::black_box(std::ptr::read_volatile(std::ptr::addr_of!(G_MIXED)));
+            std::hint::black_box(std::ptr::read_volatile(std::ptr::addr_of!(G_NULL)));
+            std::hint::black_box(std::ptr::read_volatile(std::ptr::addr_of!(
+                G_NO_ELEMENT_TYPE
+            )));
+        }
+        std::hint::black_box(observe_adapter_rejection());
+        std::thread::sleep(std::time::Duration::from_millis(20));
+    }
+}
+
+#[repr(C)]
+pub struct Leaf {
+    pub number: u64,
+}
+#[repr(C)]
+pub struct Middle {
+    pub leaf: Leaf,
+}
+#[repr(C)]
+pub struct Plain {
+    pub middle: Middle,
+}
+#[used]
+#[no_mangle]
+pub static G_PLAIN: Plain = Plain {
+    middle: Middle {
+        leaf: Leaf { number: 99 },
+    },
+};
+
+// These are ordinary fixture structs, not invalid instances of std types.
+// Their qualified identities and fields deliberately exercise adapter paths.
+pub mod ffi {
+    pub mod c_str {
+        #[repr(C)]
+        pub struct Bytes {
+            pub data_ptr: *const u8,
+            pub length: usize,
+        }
+        #[repr(C)]
+        pub struct CString {
+            pub inner: Bytes,
+        }
+    }
+}
+#[used]
+#[no_mangle]
+pub static mut G_UNREADABLE: ffi::c_str::CString = ffi::c_str::CString {
+    inner: ffi::c_str::Bytes {
+        data_ptr: 1 as *const u8,
+        length: 9,
+    },
+};
+#[used]
+#[no_mangle]
+pub static mut G_NULL: *const u64 = std::ptr::null();
+#[repr(C)]
+pub struct Mixed {
+    pub good: u64,
+    pub bad: ffi::c_str::CString,
+}
+#[used]
+#[no_mangle]
+pub static mut G_MIXED: Mixed = Mixed {
+    good: 73,
+    bad: ffi::c_str::CString {
+        inner: ffi::c_str::Bytes {
+            data_ptr: 1 as *const u8,
+            length: 9,
+        },
+    },
+};
+
+pub mod vec {
+    #[repr(C)]
+    pub struct Pointer {
+        pub pointer: *const u8,
+    }
+    #[repr(C)]
+    pub struct Buffer {
+        pub ptr: Pointer,
+    }
+    // Layout validation succeeds, but a const parameter cannot supply Vec's
+    // required DW_TAG_template_type_parameter. No real Vec is corrupted.
+    #[repr(C)]
+    pub struct Vec<const N: usize> {
+        pub buf: Buffer,
+        pub len: usize,
+    }
+}
+#[used]
+#[no_mangle]
+pub static mut G_NO_ELEMENT_TYPE: vec::Vec<3> = vec::Vec {
+    buf: vec::Buffer {
+        ptr: vec::Pointer {
+            pointer: std::ptr::null(),
+        },
+    },
+    len: 7,
+};
diff --git a/e2e-tests/tests/fixtures/rust_value_diagnostics_program/main.rs b/e2e-tests/tests/fixtures/rust_value_diagnostics_program/main.rs
new file mode 100644
index 00000000..13028277
--- /dev/null
+++ b/e2e-tests/tests/fixtures/rust_value_diagnostics_program/main.rs
@@ -0,0 +1,112 @@
+#![allow(static_mut_refs)]
+
+use std::cell::Cell;
+
+pub struct Node {
+    pub label: String,
+    pub children: Vec<Node>,
+}
+
+pub enum Branch {
+    Empty,
+    Limited(Cell<String>),
+}
+
+pub struct Outer {
+    pub middle: Middle,
+}
+pub struct Middle {
+    pub leaf: Leaf,
+}
+pub struct Leaf {
+    pub value: Cell<u64>,
+}
+#[used]
+#[no_mangle]
+pub static mut G_WRAPPED: Outer = Outer {
+    middle: Middle {
+        leaf: Leaf {
+            value: Cell::new(91),
+        },
+    },
+};
+#[used]
+#[no_mangle]
+pub static mut G_NULL_WRAPPED: *const Outer = std::ptr::null();
+#[used]
+#[no_mangle]
+pub static mut G_BAD_WRAPPED: *const Outer = 1 as *const Outer;
+#[used]
+#[no_mangle]
+pub static mut G_GOOD_WRAPPED: *const Outer = std::ptr::addr_of!(G_WRAPPED);
+
+#[used]
+#[no_mangle]
+pub static G_TEXT: &str = "alphabet";
+#[used]
+#[no_mangle]
+pub static G_EMPTY: &str = "";
+#[used]
+#[no_mangle]
+pub static mut G_ITEMS: Vec<String> = Vec::new();
+#[used]
+#[no_mangle]
+pub static mut G_NESTED: Vec<Vec<String>> = Vec::new();
+#[used]
+#[no_mangle]
+pub static mut G_CELL: Cell<String> = Cell::new(String::new());
+#[used]
+#[no_mangle]
+pub static mut G_INACTIVE: Branch = Branch::Empty;
+#[used]
+#[no_mangle]
+pub static mut G_TREE: Node = Node {
+    label: String::new(),
+    children: Vec::new(),
+};
+
+#[inline(never)]
+#[no_mangle]
+pub extern "C" fn observe_diagnostics() {
+    // The target initializes its values before the first probe hit and never
+    // mutates them afterward. Recursive types form a finite, acyclic tree.
+    std::hint::black_box(std::ptr::addr_of!(G_TREE));
+}
+
+fn main() {
+    unsafe {
+        G_ITEMS = vec!["alpha".into(), "beta".into(), "omega".into()];
+        G_NESTED = vec![vec!["deep alpha".into()], vec!["deep beta".into()]];
+        G_CELL = Cell::new("cell value".into());
+        G_TREE = Node {
+            label: "root".into(),
+            children: vec![Node {
+                label: "leaf".into(),
+                children: Vec::new(),
+            }],
+        };
+    }
+    loop {
+        unsafe {
+            std::hint::black_box(G_WRAPPED.middle.leaf.value.get());
+            // Fault in the pointer objects without dereferencing their values.
+            std::hint::black_box(std::ptr::read_volatile(std::ptr::addr_of!(G_NULL_WRAPPED)));
+            std::hint::black_box(std::ptr::read_volatile(std::ptr::addr_of!(G_BAD_WRAPPED)));
+            std::hint::black_box(std::ptr::read_volatile(std::ptr::addr_of!(G_GOOD_WRAPPED)));
+        }
+        // Initialize mappings for the static string metadata and contents;
+        // non-sleepable probes cannot fault in untouched read-only pages.
+        for text in unsafe {
+            [
+                std::ptr::read_volatile(&G_TEXT),
+                std::ptr::read_volatile(&G_EMPTY),
+            ]
+        } {
+            for byte in text.as_bytes() {
+                std::hint::black_box(unsafe { std::ptr::read_volatile(byte) });
+            }
+        }
+        observe_diagnostics();
+        std::thread::sleep(std::time::Duration::from_millis(20));
+    }
+}
diff --git a/e2e-tests/tests/fixtures/rust_value_diagnostics_program/register.rs b/e2e-tests/tests/fixtures/rust_value_diagnostics_program/register.rs
new file mode 100644
index 00000000..e08d77bb
--- /dev/null
+++ b/e2e-tests/tests/fixtures/rust_value_diagnostics_program/register.rs
@@ -0,0 +1,32 @@
+use std::cell::Cell;
+
+type Nested = Cell<Cell<Cell<u64>>>;
+
+#[used]
+#[no_mangle]
+pub static mut G_REGISTER_PEER: Nested = Cell::new(Cell::new(Cell::new(73)));
+
+#[inline(never)]
+#[no_mangle]
+pub extern "C" fn observe_register(value: Nested) -> u64 {
+    // Keep a real call site: noinline alone does not stop interprocedural
+    // simplification of a pure identity function.
+    std::hint::black_box(value.into_inner().into_inner().into_inner())
+}
+
+fn main() {
+    loop {
+        // The eight-byte cells own no allocations. Keep the memory-backed peer
+        // resident without changing the register-backed argument's location.
+        unsafe {
+            std::ptr::write_volatile(
+                std::ptr::addr_of_mut!(G_REGISTER_PEER),
+                Cell::new(Cell::new(Cell::new(73))),
+            );
+        }
+        std::hint::black_box(observe_register(Cell::new(Cell::new(Cell::new(
+            std::hint::black_box(41),
+        )))));
+        std::thread::sleep(std::time::Duration::from_millis(20));
+    }
+}
diff --git a/e2e-tests/tests/globals_target_execution.rs b/e2e-tests/tests/globals_target_execution.rs
index 341635b8..f8bcc2c8 100644
--- a/e2e-tests/tests/globals_target_execution.rs
+++ b/e2e-tests/tests/globals_target_execution.rs
@@ -803,7 +803,7 @@ trace lib_tick {
         "memcmp should not succeed without offsets. STDOUT: {stdout}"
     );
     assert!(
-        !target_stdout.contains("read_user failed"),
+        !target_stdout.contains("memory read failed"),
         "Should not surface raw read_user errors for PID {pid}. STDOUT: {stdout}"
     );
 
diff --git a/e2e-tests/tests/optimized_inline_call_value_execution.rs b/e2e-tests/tests/optimized_inline_call_value_execution.rs
index 49143464..09550b62 100644
--- a/e2e-tests/tests/optimized_inline_call_value_execution.rs
+++ b/e2e-tests/tests/optimized_inline_call_value_execution.rs
@@ -245,72 +245,6 @@ async fn test_optimized_inline_parameters_have_exact_values_before_internal_call
     Ok(())
 }
 
-#[tokio::test]
-async fn test_optimized_out_local_print_emits_marker_at_runtime() -> anyhow::Result<()> {
-    init();
-
-    let binary_path = FIXTURES.get_test_binary("inline_call_value_program")?;
-    let analyzer = ghostscope_dwarf::DwarfAnalyzer::from_exec_path(&binary_path).await?;
-    let query_results = analyzer.query_source_line_best_effort(
-        "inline_call_value_program.c",
-        INLINE_BEFORE_CALL_TRACE_LINE,
-    )?;
-    anyhow::ensure!(
-        query_results.iter().any(|result| {
-            result.variables.iter().any(|variable| {
-                variable.name == "local_x"
-                    && matches!(variable.location, VariableLocation::OptimizedOut)
-            })
-        }),
-        "Expected local_x to be visible but optimized out at inline_call_value_program.c:{INLINE_BEFORE_CALL_TRACE_LINE}: {query_results:?}"
-    );
-
-    let target = spawn_inline_call_value_program(&binary_path).await?;
-    let script = format!(
-        "trace inline_call_value_program.c:{INLINE_BEFORE_CALL_TRACE_LINE} {{\n    print local_x;\n}}\n"
-    );
-    let (exit_code, stdout, stderr) =
-        run_ghostscope_with_script_for_target(&script, 4, &target).await?;
-    target.terminate().await?;
-
-    if should_skip_for_ebpf_env(exit_code, &stderr) {
-        return Ok(());
-    }
-
-    assert_eq!(exit_code, 0, "stderr={stderr} stdout={stdout}");
-    assert!(
-        stdout.contains("<optimized out>") || stdout.contains("<optimized_out>"),
-        "Expected direct print of optimized-out local_x to emit an optimized-out marker. STDOUT: {stdout}\nSTDERR: {stderr}"
-    );
-
-    Ok(())
-}
-
-#[tokio::test]
-async fn test_optimized_out_local_value_expression_is_rejected() -> anyhow::Result<()> {
-    init();
-
-    let binary_path = FIXTURES.get_test_binary("inline_call_value_program")?;
-    let target = spawn_inline_call_value_program(&binary_path).await?;
-    let script = format!(
-        "trace inline_call_value_program.c:{INLINE_BEFORE_CALL_TRACE_LINE} {{\n    if local_x == 0 {{ print \"VALUE\"; }}\n}}\n"
-    );
-    let (_exit_code, stdout, stderr) =
-        run_ghostscope_with_script_for_target(&script, 3, &target).await?;
-    target.terminate().await?;
-
-    let has_banner = stderr.contains("Script compilation failed")
-        || stderr.contains("No uprobe configurations created");
-    let has_message =
-        stderr.contains("local_x") && stderr.contains("optimized out at the selected probe PC");
-    assert!(
-        has_banner && has_message,
-        "Expected optimized-out local_x to be rejected in a value expression.\nSTDOUT: {stdout}\nSTDERR: {stderr}"
-    );
-
-    Ok(())
-}
-
 #[tokio::test]
 async fn test_optimized_inline_parameters_survive_internal_call_sites() -> anyhow::Result<()> {
     init();
diff --git a/e2e-tests/tests/rust_adapter_diagnostics_execution.rs b/e2e-tests/tests/rust_adapter_diagnostics_execution.rs
deleted file mode 100644
index cd9b4a17..00000000
--- a/e2e-tests/tests/rust_adapter_diagnostics_execution.rs
+++ /dev/null
@@ -1,70 +0,0 @@
-//! CLI diagnostics for rejected Rust value adapters.
-
-mod common;
-
-use std::path::{Path, PathBuf};
-
-use common::{
-    init,
-    rust_toolchain::{compile_standalone_fixture, fixture_tempdir, rustc_for_toolchain},
-};
-
-const TOOLCHAIN: &str = "1.88.0";
-
-fn compile_fixture(rustc: &Path, output_dir: &Path) -> anyhow::Result<PathBuf> {
-    // The source filename makes rustc use `alloc` as the crate name, producing
-    // the qualified type identity `alloc::string::String` in target DWARF.
-    let source = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
-        .join("tests/fixtures/rust_adapter_rejection_program/alloc.rs");
-    let binary = output_dir.join("rust_adapter_rejection_program");
-    compile_standalone_fixture(rustc, TOOLCHAIN, &source, &binary)?;
-    Ok(binary)
-}
-
-#[tokio::test]
-async fn test_cli_reports_rust_adapter_rejection_when_dwarf_fallback_fails() -> anyhow::Result<()> {
-    init();
-
-    let rustc = rustc_for_toolchain(TOOLCHAIN)
-        .ok_or_else(|| anyhow::anyhow!("required Rust toolchain {TOOLCHAIN} is not installed"))?;
-    let temp_dir = fixture_tempdir()?;
-    let binary = compile_fixture(&rustc, temp_dir.path())?;
-    let target = common::targets::TargetLauncher::binary(&binary)
-        .current_dir(temp_dir.path())
-        .spawn()
-        .await?;
-    tokio::time::sleep(std::time::Duration::from_millis(250)).await;
-
-    let script = r#"
-trace observe_adapter_rejection {
-    print "SHOULD_NOT_LOAD:{}", G_REJECTED_STRING;
-}
-"#;
-    let result = common::runner::GhostscopeRunner::new()
-        .with_script(script)
-        .attach_to(&target)
-        .timeout_secs(5)
-        .enable_sysmon_for_target(false)
-        .run()
-        .await;
-    target.terminate().await?;
-
-    let (exit_code, stdout, stderr) = result?;
-    let output = format!("{stdout}\n{stderr}");
-    assert_ne!(exit_code, 0, "expected compilation failure: {output}");
-    for expected in [
-        "Variable 'G_REJECTED_STRING' has no concrete DWARF size",
-        "Rust value adapter diagnostic (ordinary DWARF fallback also failed):",
-        "adapter: String",
-        "type: alloc::string::String",
-        "rejected at: layout-validation",
-        "reason: expected `vec.buf[.inner].ptr` and `vec.len`",
-        "target rustc: 1.88.0",
-        "target DWARF:",
-        "producer:",
-    ] {
-        assert!(output.contains(expected), "missing '{expected}': {output}");
-    }
-
-    Ok(())
-}
diff --git a/e2e-tests/tests/rust_legacy_btree_execution.rs b/e2e-tests/tests/rust_legacy_btree_execution.rs
index 0f269e41..6e5f6260 100644
--- a/e2e-tests/tests/rust_legacy_btree_execution.rs
+++ b/e2e-tests/tests/rust_legacy_btree_execution.rs
@@ -127,7 +127,7 @@ mem_dump_cap = 90
         );
         assert!(!stdout.contains("<INVALID_"), "invalid payload: {stdout}");
         assert!(
-            !stdout.contains("<truncated>"),
+            !stdout.contains("<truncated:"),
             "truncated payload: {stdout}"
         );
     }
diff --git a/e2e-tests/tests/rust_legacy_hash_execution.rs b/e2e-tests/tests/rust_legacy_hash_execution.rs
index 277f4ea8..59c75807 100644
--- a/e2e-tests/tests/rust_legacy_hash_execution.rs
+++ b/e2e-tests/tests/rust_legacy_hash_execution.rs
@@ -102,7 +102,7 @@ mem_dump_cap = 2048
     );
     assert!(!stdout.contains("<INVALID_"), "invalid payload: {stdout}");
     assert!(
-        !stdout.contains("<truncated>"),
+        !stdout.contains("<truncated:"),
         "truncated payload: {stdout}"
     );
 
diff --git a/e2e-tests/tests/rust_legacy_sequence_execution.rs b/e2e-tests/tests/rust_legacy_sequence_execution.rs
index d2f305b4..1d025947 100644
--- a/e2e-tests/tests/rust_legacy_sequence_execution.rs
+++ b/e2e-tests/tests/rust_legacy_sequence_execution.rs
@@ -84,7 +84,7 @@ mem_dump_cap = 256
     );
     assert!(!stdout.contains("<INVALID_"), "invalid payload: {stdout}");
     assert!(
-        !stdout.contains("<truncated>"),
+        !stdout.contains("<truncated:"),
         "truncated payload: {stdout}"
     );
 
diff --git a/e2e-tests/tests/rust_legacy_string_execution.rs b/e2e-tests/tests/rust_legacy_string_execution.rs
index ad9998ed..cc940391 100644
--- a/e2e-tests/tests/rust_legacy_string_execution.rs
+++ b/e2e-tests/tests/rust_legacy_string_execution.rs
@@ -87,7 +87,7 @@ mem_dump_cap = 64
     );
     assert!(!stdout.contains("<INVALID_"), "invalid payload: {stdout}");
     assert!(
-        !stdout.contains("<truncated>"),
+        !stdout.contains("<truncated:"),
         "truncated payload: {stdout}"
     );
 
diff --git a/e2e-tests/tests/rust_path_execution.rs b/e2e-tests/tests/rust_path_execution.rs
index 775822de..6f424747 100644
--- a/e2e-tests/tests/rust_path_execution.rs
+++ b/e2e-tests/tests/rust_path_execution.rs
@@ -68,19 +68,19 @@ mem_dump_cap = 16
     for expected in [
         concat!(
             "R188_PATH:\"borrowed/path\":\"owned/path\":\"\":",
-            "\"abcdefghijklmnop\" <truncated>"
+            "\"abcdefghijklmnop\" <truncated: byte limit>"
         ),
         concat!(
             "R188_PATH:\"borrowed/path\":\"bad/\\xff/path\":\"\":",
-            "\"abcdefghijklmnop\" <truncated>"
+            "\"abcdefghijklmnop\" <truncated: byte limit>"
         ),
         concat!(
             "R188_PATH_RAW:borrowed/path:",
             "62 61 64 2f ff 2f 70 61 74 68"
         ),
         concat!(
-            "R188_PATH_LONG_RAW:abcdefghijklmnop <truncated>:",
-            "61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 <truncated>"
+            "R188_PATH_LONG_RAW:abcdefghijklmnop <truncated: capture limit>:",
+            "61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 <truncated: capture limit>"
         ),
     ] {
         assert!(stdout.contains(expected), "missing '{expected}': {stdout}");
diff --git a/e2e-tests/tests/rust_script_execution.rs b/e2e-tests/tests/rust_script_execution.rs
index 1dae05b5..9b1da732 100644
--- a/e2e-tests/tests/rust_script_execution.rs
+++ b/e2e-tests/tests/rust_script_execution.rs
@@ -501,6 +501,11 @@ async fn test_rust_nested_value_plans_recurse_into_semantic_children() -> anyhow
         element.nested.is_none(),
         "max_nesting_depth=1 must stop before the String adapter: {depth_one:#?}"
     );
+    assert!(
+        depth_one.diagnostics.iter().any(|note| note.path == "[][]"
+            && note.reason == ghostscope_protocol::ValueDiagnosticReason::DepthLimit),
+        "missing field-specific depth diagnostic: {depth_one:#?}"
+    );
 
     Ok(())
 }
@@ -1929,7 +1934,9 @@ trace observe_nested_owners {
         stdout.lines().any(|line| {
             line.contains(r#"RNESTED:Cell { value: "cell nested" }"#)
                 && line.contains(r#"RefCell(borrow=0) { value: "refcell nested", borrow: 0 }"#)
-                && line.contains(r#"["alpha", "nested rust", "omega", "delta"] <truncated>"#)
+                && line.contains(
+                    r#"["alpha", "nested rust", "omega", "delta"] <truncated: element limit>"#,
+                )
                 && line.contains("[[1, 2], [3, 5, 8], [-13]]")
                 && line.contains(r#"[["deep alpha"], ["deep beta"]]"#)
         }),
@@ -1937,7 +1944,7 @@ trace observe_nested_owners {
     );
     assert!(
         stdout.lines().any(|line| {
-            line.contains(r#"RNESTED_C:["alpha c", "beta c", "gamma c", "delta c"] <truncated>"#)
+            line.contains(r#"RNESTED_C:["alpha c", "beta c", "gamma c", "delta c"] <truncated: element limit>"#)
         }),
         "Expected nested Rust CString output: {stdout}"
     );
@@ -2100,7 +2107,7 @@ max_sequence_elements = 2
         .find(|line| line.contains("RNESTED_LIMIT:"))
         .ok_or_else(|| anyhow::anyhow!("missing nested sequence limit output: {stdout}"))?;
     assert!(
-        line.contains(r#"RNESTED_LIMIT:["alpha", "nested rust"] <truncated>"#),
+        line.contains(r#"RNESTED_LIMIT:["alpha", "nested rust"] <truncated: element limit>"#),
         "Unexpected nested sequence limit output: {line}"
     );
     assert!(
@@ -2145,7 +2152,7 @@ max_trace_event_size = 32768
     assert!(
         stdout
             .lines()
-            .any(|line| line.contains("RNESTED_BUDGET:<truncated>")),
+            .any(|line| line.contains("RNESTED_BUDGET:<truncated: capture limit>")),
         "Expected an emitted truncated nested value: {stdout}"
     );
     assert!(
@@ -2189,9 +2196,9 @@ max_trace_event_size = 256
 
     assert_eq!(exit_code, 0, "stderr={stderr} stdout={stdout}");
     assert!(
-        stdout
-            .lines()
-            .any(|line| line.contains("RNESTED_EVENT_BUDGET:<truncated>:<truncated>")),
+        stdout.lines().any(|line| line.contains(
+            "RNESTED_EVENT_BUDGET:<truncated: capture limit>:<truncated: capture limit>"
+        )),
         "Expected structurally valid nested truncation output: {stdout}"
     );
     assert!(
@@ -2698,7 +2705,7 @@ mem_dump_cap = 9
         .find(|line| line.contains("RHASH_CAP:"))
         .ok_or_else(|| anyhow::anyhow!("missing capped Rust HashMap output: {stdout}"))?;
     assert!(line.contains("HashMap(size=2)"), "{line}");
-    assert!(line.contains("<truncated>"), "{line}");
+    assert!(line.contains("<truncated: capture limit>"), "{line}");
     assert!(!line.contains("<INVALID_"), "{line}");
     assert!(
         !stdout.contains("ExprError"),
@@ -2875,7 +2882,7 @@ mem_dump_cap = 450
         "Expected complete internal Rust BTreeSet output: {stdout}"
     );
     assert!(
-        !stdout.contains("<truncated>"),
+        !stdout.contains("<truncated:"),
         "Unexpected truncation: {stdout}"
     );
     assert!(!stdout.contains("<INVALID_"), "Invalid payload: {stdout}");
@@ -2905,7 +2912,7 @@ trace observe_deep_btree_collections {
             .find(|line| line.contains(marker))
             .ok_or_else(|| anyhow::anyhow!("missing {marker} output: {stdout}"))?;
         assert!(line.contains("size=160"), "{line}");
-        assert!(line.contains("<truncated>"), "{line}");
+        assert!(line.contains("<truncated: capture limit>"), "{line}");
         assert!(!line.contains("<INVALID_"), "{line}");
     }
     assert!(
@@ -2945,7 +2952,7 @@ mem_dump_cap = 9
     assert!(
         stdout
             .lines()
-            .any(|line| line.contains("RDEQUE_CAP:[10, 20] <truncated>")),
+            .any(|line| line.contains("RDEQUE_CAP:[10, 20] <truncated: capture limit>")),
         "Expected capped Rust VecDeque output: {stdout}"
     );
     assert!(
@@ -2985,7 +2992,7 @@ mem_dump_cap = 9
     assert!(
         stdout
             .lines()
-            .any(|line| line.contains("RVEC_CAP:[10, -20] <truncated>")),
+            .any(|line| line.contains("RVEC_CAP:[10, -20] <truncated: capture limit>")),
         "Expected element-aligned capped Rust Vec output: {stdout}"
     );
     assert!(
@@ -3189,7 +3196,7 @@ mem_dump_cap = 3
         .find(|line| line.contains("RSTR_CAP:"))
         .ok_or_else(|| anyhow::anyhow!("Expected capped Rust str output: {stdout}"))?;
     assert!(
-        cap_line.contains(r#"RSTR_CAP:"hel" <truncated>"#),
+        cap_line.contains(r#"RSTR_CAP:"hel" <truncated: byte limit>"#),
         "Unexpected capped Rust str output: {cap_line}"
     );
     assert!(
@@ -3201,7 +3208,9 @@ mem_dump_cap = 3
         .find(|line| line.contains("RSTR_CAP_RAW:"))
         .ok_or_else(|| anyhow::anyhow!("Expected raw capped Rust str output: {stdout}"))?;
     assert!(
-        cap_raw_line.contains("RSTR_CAP_RAW:hel <truncated>:68 65 6c <truncated>"),
+        cap_raw_line.contains(
+            "RSTR_CAP_RAW:hel <truncated: capture limit>:68 65 6c <truncated: capture limit>"
+        ),
         "Unexpected raw capped Rust str output: {cap_raw_line}"
     );
     assert!(
diff --git a/e2e-tests/tests/rust_version_matrix_execution.rs b/e2e-tests/tests/rust_version_matrix_execution.rs
index 2d42dee4..e8821e08 100644
--- a/e2e-tests/tests/rust_version_matrix_execution.rs
+++ b/e2e-tests/tests/rust_version_matrix_execution.rs
@@ -279,7 +279,7 @@ mem_dump_cap = 512
         "{toolchain}: invalid payload: {stdout}"
     );
     anyhow::ensure!(
-        !stdout.contains("<truncated>"),
+        !stdout.contains("<truncated:"),
         "{toolchain}: truncated payload: {stdout}"
     );
     eprintln!("completed Rust e2e toolchain {toolchain}");
diff --git a/e2e-tests/tests/value_diagnostics_execution.rs b/e2e-tests/tests/value_diagnostics_execution.rs
new file mode 100644
index 00000000..e995a86b
--- /dev/null
+++ b/e2e-tests/tests/value_diagnostics_execution.rs
@@ -0,0 +1,782 @@
+//! User-facing value diagnostic contracts, exercised through the real CLI.
+//! Assert reasons, retained values, streams, and exit status. Do not snapshot
+//! timestamps, ASLR addresses, decoration, or entire explanatory paragraphs.
+
+mod common;
+
+use std::path::{Path, PathBuf};
+
+use common::{
+    init,
+    runner::GhostscopeRunner,
+    rust_toolchain::{
+        compile_standalone_fixture_with_codegen_options, fixture_tempdir, rustc_for_toolchain,
+    },
+    targets::{TargetHandle, TargetLauncher},
+    FIXTURES,
+};
+
+const TOOLCHAIN: &str = "1.88.0";
+const VALUES: &str = "rust_value_diagnostics_program/main.rs";
+const FALLBACK: &str = "rust_adapter_rejection_program/sized/alloc.rs";
+const UNSIZED: &str = "rust_adapter_rejection_program/alloc.rs";
+const OFFLINE_HELP: &str = "ghostscope --value-diagnostics-help";
+
+#[derive(Debug)]
+struct CliOutput {
+    code: i32,
+    stdout: String,
+    stderr: String,
+}
+
+impl From<(i32, String, String)> for CliOutput {
+    fn from((code, stdout, stderr): (i32, String, String)) -> Self {
+        Self {
+            code,
+            stdout,
+            stderr,
+        }
+    }
+}
+
+impl CliOutput {
+    fn success(&self) {
+        assert_eq!(self.code, 0, "{self:#?}");
+        assert!(!self.stdout.contains("Display note"), "{self:#?}");
+        for unexpected in ["<INVALID_", "<MISSING_ARG>", "ExprError"] {
+            assert!(!self.stdout.contains(unexpected), "{self:#?}");
+        }
+    }
+
+    fn compile_failure(&self, reason: &str) {
+        assert_ne!(self.code, 0, "{self:#?}");
+        assert!(self.stderr.contains("Failed targets:"), "{self:#?}");
+        assert!(self.stderr.contains(reason), "{self:#?}");
+        assert!(
+            self.stdout.trim().is_empty(),
+            "failed compilation emitted events: {self:#?}"
+        );
+        assert!(
+            !self.stderr.contains("check your script syntax"),
+            "misleading generic advice: {self:#?}"
+        );
+    }
+
+    fn events(&self, tag: &str) -> Vec<&str> {
+        let values = self
+            .stdout
+            .lines()
+            .filter_map(|line| line.split_once(tag).map(|(_, value)| value))
+            .collect::<Vec<_>>();
+        assert!(!values.is_empty(), "missing {tag}: {self:#?}");
+        assert!(
+            !self.stderr.contains(tag),
+            "event leaked to stderr: {self:#?}"
+        );
+        values
+    }
+
+    fn note(&self, path: &str, reason: &str) {
+        assert!(
+            self.stderr
+                .lines()
+                .any(|line| line.contains(&format!(": {path}"))
+                    && line.contains(&format!("[{reason}]"))),
+            "missing note for {path} [{reason}]: {self:#?}"
+        );
+        for expected in [
+            "Type:",
+            "Detail:",
+            OFFLINE_HELP,
+            &format!("docs/value-diagnostics.md#{reason}"),
+        ] {
+            assert!(
+                self.stderr.contains(expected),
+                "missing {expected}: {self:#?}"
+            );
+        }
+    }
+}
+
+fn quiet_runner(script: &str, config: &str) -> GhostscopeRunner {
+    GhostscopeRunner::new()
+        .with_script(script)
+        .with_config_content(config)
+        .with_cli_args(["--no-log", "--no-status"])
+        .timeout_secs(4)
+        .enable_sysmon_for_target(false)
+}
+
+fn compile_fixture(source: &str, directory: &Path) -> anyhow::Result<PathBuf> {
+    compile_fixture_with_options(source, directory, &["opt-level=0"])
+}
+
+fn compile_fixture_with_options(
+    source: &str,
+    directory: &Path,
+    codegen_options: &[&str],
+) -> anyhow::Result<PathBuf> {
+    let rustc = rustc_for_toolchain(TOOLCHAIN)
+        .ok_or_else(|| anyhow::anyhow!("required Rust toolchain {TOOLCHAIN} is not installed"))?;
+    let source = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/fixtures")
+        .join(source);
+    let binary = directory.join("value_diagnostics_program");
+    compile_standalone_fixture_with_codegen_options(
+        &rustc,
+        TOOLCHAIN,
+        &source,
+        &binary,
+        codegen_options,
+    )?;
+    Ok(binary)
+}
+
+async fn capture(target: &TargetHandle, runner: GhostscopeRunner) -> anyhow::Result<CliOutput> {
+    Ok(runner.attach_to(target).run().await?.into())
+}
+
+async fn run_fixture(source: &str, runner: GhostscopeRunner) -> anyhow::Result<CliOutput> {
+    let directory = fixture_tempdir()?;
+    let binary = compile_fixture(source, directory.path())?;
+    let target = TargetLauncher::binary(&binary)
+        .current_dir(directory.path())
+        .spawn()
+        .await?;
+    let result = capture(&target, runner).await;
+    target.terminate().await?;
+    result
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_layout_fallback_is_visible_without_logging() -> anyhow::Result<()> {
+    init();
+    for mode in ["plain", "pretty"] {
+        let output = run_fixture(
+            FALLBACK,
+            quiet_runner(
+                r#"
+trace observe_adapter_rejection {
+    print "FALLBACK:{}", G_REJECTED_STRING;
+    print "AGAIN:{}", G_REJECTED_STRING;
+    print "PLAIN:{}", G_PLAIN;
+}"#,
+                "[value_adapters]\nmax_nesting_depth = 1\n",
+            )
+            .with_cli_args(["--script-output", mode]),
+        )
+        .await?;
+        output.success();
+        for tag in ["FALLBACK:", "AGAIN:"] {
+            for value in output.events(tag) {
+                assert!(
+                    value.contains("raw: 42")
+                        && value.contains("<internal fields: layout unsupported>"),
+                    "{value}"
+                );
+                assert!(!value.contains("<unreadable:"), "{value}");
+            }
+        }
+        for value in output.events("PLAIN:") {
+            assert!(value.contains("number: 99"), "{value}");
+            assert!(
+                !value.contains("<internal fields:") && !value.contains("display limits"),
+                "{value}"
+            );
+        }
+        output.note("G_REJECTED_STRING", "layout-unsupported");
+        assert_eq!(
+            output
+                .stderr
+                .matches("Help: docs/value-diagnostics.md#layout-unsupported")
+                .count(),
+            1,
+            "{output:#?}"
+        );
+        assert!(
+            output
+                .stderr
+                .contains("expected `vec.buf[.inner].ptr` and `vec.len`"),
+            "{output:#?}"
+        );
+        assert!(!output.stderr.contains("G_PLAIN"), "{output:#?}");
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_failed_fallback_is_a_compile_error() -> anyhow::Result<()> {
+    init();
+    let output = run_fixture(
+        UNSIZED,
+        quiet_runner(
+            r#"trace observe_adapter_rejection { print "SHOULD_NOT_LOAD:{}", G_REJECTED_STRING; }"#,
+            "",
+        ),
+    )
+    .await?;
+    output.compile_failure("Variable 'G_REJECTED_STRING' has no concrete DWARF size");
+    for expected in [
+        "ordinary DWARF fallback also failed",
+        "adapter: String",
+        "type: alloc::string::String",
+        "rejected at: layout-validation",
+        "expected `vec.buf[.inner].ptr` and `vec.len`",
+        "target rustc: 1.88.0",
+        "target DWARF:",
+        "producer:",
+        "docs/value-diagnostics.md#layout-unsupported",
+        OFFLINE_HELP,
+    ] {
+        assert!(
+            output.stderr.contains(expected),
+            "missing {expected}: {output:#?}"
+        );
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_read_plan_fallback_has_a_distinct_reason() -> anyhow::Result<()> {
+    init();
+    let output = run_fixture(
+        FALLBACK,
+        quiet_runner(
+            r#"trace observe_adapter_rejection { print "PLAN:{}", G_NO_ELEMENT_TYPE; }"#,
+            "",
+        ),
+    )
+    .await?;
+    output.success();
+    output.note("G_NO_ELEMENT_TYPE", "read-plan-unsupported");
+    for value in output.events("PLAN:") {
+        assert!(
+            value.contains("len: 7") && value.contains("<internal fields: read plan unsupported>"),
+            "{value}"
+        );
+        assert!(
+            !value.contains("layout unsupported") && !value.contains("<unreadable:"),
+            "{value}"
+        );
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_read_failure_preserves_errno_and_siblings() -> anyhow::Result<()> {
+    init();
+    let read_error =
+        regex::Regex::new(r"<unreadable: memory read failed; errno=-[0-9]+; address=0x1>")?;
+    for perf in [false, true] {
+        let output = run_fixture(
+            FALLBACK,
+            quiet_runner(
+                r#"
+trace observe_adapter_rejection {
+    print "READ:{}", G_UNREADABLE;
+    print "MIXED:{}", G_MIXED;
+    print "DUMP:{:x.8}", cast(1, "u64 *");
+    print "NULL:{}", *G_NULL;
+    print "HEALTHY:{}", G_PLAIN;
+}"#,
+                "",
+            )
+            .force_perf_event_array(perf),
+        )
+        .await?;
+        output.success();
+        for tag in ["READ:", "MIXED:", "DUMP:"] {
+            for value in output.events(tag) {
+                assert!(read_error.is_match(value), "{value}");
+                assert!(
+                    !value.contains("<unavailable:")
+                        && !value.contains("<internal fields:")
+                        && !value.contains("<truncated:"),
+                    "{value}"
+                );
+                if tag == "MIXED:" {
+                    assert!(
+                        value.contains("good: 73") && value.contains("bad:"),
+                        "{value}"
+                    );
+                }
+            }
+        }
+        for value in output.events("NULL:") {
+            assert!(
+                value.contains("<error: null pointer dereference>"),
+                "{value}"
+            );
+            assert!(!value.contains("memory read failed"), "{value}");
+        }
+        assert!(
+            output
+                .events("HEALTHY:")
+                .iter()
+                .all(|value| value.contains("number: 99")),
+            "{output:#?}"
+        );
+        assert!(!output.stderr.contains("Display note"), "{output:#?}");
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_optimized_out_print_and_expression_are_distinct(
+) -> anyhow::Result<()> {
+    init();
+    // The existing compiler-specific fixture pins this source line and checks
+    // its DWARF. Fail if the intended unavailable location stops being emitted.
+    const LINE: u32 = 20;
+    let binary = FIXTURES.get_test_binary("inline_call_value_program")?;
+    let analyzer = ghostscope_dwarf::DwarfAnalyzer::from_exec_path(&binary).await?;
+    let locations = analyzer.query_source_line_best_effort("inline_call_value_program.c", LINE)?;
+    assert!(
+        locations.iter().any(
+            |location| location
+                .variables
+                .iter()
+                .any(|variable| variable.name == "local_x"
+                    && matches!(
+                        variable.location,
+                        ghostscope_dwarf::VariableLocation::OptimizedOut
+                    ))
+        ),
+        "{locations:?}"
+    );
+    for (body, unavailable) in [
+        (
+            r#"print "OPT:{}", local_x; print "LIVE:{}", original_x;"#,
+            true,
+        ),
+        (r#"if local_x == 0 { print "SHOULD_NOT_LOAD"; }"#, false),
+    ] {
+        let target = TargetLauncher::binary(&binary).spawn().await?;
+        let script = format!("trace inline_call_value_program.c:{LINE} {{ {body} }}");
+        let result = capture(&target, quiet_runner(&script, "")).await;
+        target.terminate().await?;
+        let output = result?;
+        if unavailable {
+            output.success();
+            assert!(
+                output
+                    .events("OPT:")
+                    .iter()
+                    .all(|value| value.contains("<unavailable: optimized out>")),
+                "{output:#?}"
+            );
+            assert!(
+                output
+                    .events("LIVE:")
+                    .iter()
+                    .all(|value| value.trim().parse::<i64>().is_ok()),
+                "{output:#?}"
+            );
+            assert!(
+                !output.stdout.contains("<unreadable:")
+                    && !output.stdout.contains("<internal fields:"),
+                "{output:#?}"
+            );
+        } else {
+            output.compile_failure("optimized out at the selected probe PC");
+            assert!(output.stderr.contains("local_x"), "{output:#?}");
+        }
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_byte_limit_preserves_prefix_and_empty_value() -> anyhow::Result<()>
+{
+    init();
+    let output = run_fixture(
+        VALUES,
+        quiet_runner(
+            r#"trace observe_diagnostics { print "BYTES:{}", G_TEXT; print "EMPTY:{}", G_EMPTY; }"#,
+            "[ebpf]\nmem_dump_cap = 3\n",
+        ),
+    )
+    .await?;
+    output.success();
+    assert!(
+        output
+            .events("BYTES:")
+            .iter()
+            .all(|value| *value == r#""alp" <truncated: byte limit>"#),
+        "{output:#?}"
+    );
+    assert!(
+        output
+            .events("EMPTY:")
+            .iter()
+            .all(|value| *value == r#""""#),
+        "{output:#?}"
+    );
+    assert!(
+        !output.stdout.contains("<unreadable:") && !output.stderr.contains("Display note"),
+        "{output:#?}"
+    );
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_element_limit_preserves_prefix() -> anyhow::Result<()> {
+    init();
+    let output = run_fixture(
+        VALUES,
+        quiet_runner(
+            r#"trace observe_diagnostics { print "ELEMENTS:{}", G_ITEMS; }"#,
+            "[value_adapters]\nmax_sequence_elements = 2\n",
+        ),
+    )
+    .await?;
+    output.success();
+    for value in output.events("ELEMENTS:") {
+        assert_eq!(value, r#"["alpha", "beta"] <truncated: element limit>"#);
+        assert!(!value.contains("omega"), "{value}");
+    }
+    assert!(!output.stderr.contains("Display note"), "{output:#?}");
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_depth_limit_and_inactive_variant_are_static() -> anyhow::Result<()>
+{
+    init();
+    let output = run_fixture(
+        VALUES,
+        quiet_runner(
+            r#"
+trace observe_diagnostics {
+    print "DEPTH:{}", G_NESTED;
+    print "AGAIN_DEPTH:{}", G_NESTED;
+    print "INACTIVE_VALUE:{}", G_INACTIVE;
+}"#,
+            "[value_adapters]\nmax_nesting_depth = 1\n",
+        ),
+    )
+    .await?;
+    output.success();
+    output.note("G_NESTED[][]", "depth-limit");
+    output.note("G_INACTIVE::Limited.__0.value", "depth-limit");
+    assert_eq!(
+        output
+            .stderr
+            .lines()
+            .filter(|line| line.contains("G_NESTED[][]") && line.contains("[depth-limit]"))
+            .count(),
+        1,
+        "{output:#?}"
+    );
+    for tag in ["DEPTH:", "INACTIVE_VALUE:"] {
+        for value in output.events(tag) {
+            assert!(
+                value.contains("<nested display limits: depth limit; see trace details>"),
+                "{value}"
+            );
+            assert!(
+                !value.contains("<unreadable:") && !value.contains("<not expanded:"),
+                "{value}"
+            );
+            if tag == "INACTIVE_VALUE:" {
+                assert!(
+                    value.contains("Empty")
+                        && !value.contains("Limited(")
+                        && !value.contains("<truncated:"),
+                    "{value}"
+                );
+            }
+        }
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_notes_preserve_ordinary_reads() -> anyhow::Result<()> {
+    init();
+    let directory = fixture_tempdir()?;
+    let binary = compile_fixture(VALUES, directory.path())?;
+    let analyzer = ghostscope_dwarf::DwarfAnalyzer::from_exec_path(&binary).await?;
+    let (_, read_plan) = analyzer
+        .plan_global_access_read_plan(
+            &binary,
+            "G_WRAPPED",
+            &ghostscope_dwarf::VariableAccessPath::default(),
+        )?
+        .expect("wrapped global read plan");
+    let resolved = analyzer
+        .resolved_type_for_plan(&read_plan)?
+        .expect("wrapped global type");
+    let options = ghostscope_dwarf::ValueReadPlanOptions {
+        max_nesting_depth: 1,
+    };
+    let resolution =
+        analyzer.resolve_value_read_plan_with_options(&resolved, Some(&binary), options)?;
+    assert!(
+        resolution.plan.is_none(),
+        "notes must not select a semantic capture: {resolution:?}"
+    );
+    assert!(resolution
+        .diagnostics
+        .iter()
+        .any(|note| note.reason == ghostscope_protocol::ValueDiagnosticReason::DepthLimit));
+    assert!(analyzer
+        .value_read_plan_with_options(&resolved, Some(&binary), options)?
+        .is_none());
+
+    let target = TargetLauncher::binary(&binary)
+        .current_dir(directory.path())
+        .spawn()
+        .await?;
+    let result = capture(
+        &target,
+        quiet_runner(
+            r#"
+trace observe_diagnostics {
+    print "ROOT_VALUE:{}", G_WRAPPED;
+    print "GOOD_VALUE:{}", *G_GOOD_WRAPPED;
+    print "NULL_VALUE:{}", *G_NULL_WRAPPED;
+    print "BAD_VALUE:{}", *G_BAD_WRAPPED;
+}"#,
+            "[value_adapters]\nmax_nesting_depth = 1\n",
+        ),
+    )
+    .await;
+    target.terminate().await?;
+    let output = result?;
+    output.success();
+    for expression in [
+        "G_WRAPPED",
+        "*G_GOOD_WRAPPED",
+        "*G_NULL_WRAPPED",
+        "*G_BAD_WRAPPED",
+    ] {
+        output.note(expression, "depth-limit");
+    }
+    for tag in ["ROOT_VALUE:", "GOOD_VALUE:"] {
+        for value in output.events(tag) {
+            assert!(
+                value.contains("91")
+                    && value.contains("<nested display limits: depth limit; see trace details>"),
+                "{value}"
+            );
+            assert!(
+                !value.contains("<unreadable:") && !value.contains("<error:"),
+                "{value}"
+            );
+        }
+    }
+    for value in output.events("NULL_VALUE:") {
+        assert!(
+            value.contains("<error: null pointer dereference>"),
+            "{value}"
+        );
+        assert!(
+            !value.contains("memory read failed") && !value.contains("depth limit"),
+            "{value}"
+        );
+    }
+    for value in output.events("BAD_VALUE:") {
+        assert!(
+            value.contains("<unreadable: memory read failed; errno=")
+                && value.contains("address=0x1>"),
+            "{value}"
+        );
+        assert!(
+            !value.contains("null pointer") && !value.contains("depth limit"),
+            "{value}"
+        );
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_register_arguments_retain_static_notes() -> anyhow::Result<()> {
+    init();
+    let directory = fixture_tempdir()?;
+    let binary = compile_fixture_with_options(
+        "rust_value_diagnostics_program/register.rs",
+        directory.path(),
+        &["opt-level=2"],
+    )?;
+    let analyzer = ghostscope_dwarf::DwarfAnalyzer::from_exec_path(&binary).await?;
+    let mut found_register = false;
+    for address in analyzer.lookup_function_addresses("observe_register") {
+        let context = analyzer.resolve_pc(&address)?;
+        if let Some(plan) = analyzer.plan_variable_by_name(&context, "value")? {
+            let materialized =
+                plan.materialization_plan(&ghostscope_dwarf::RuntimeCapabilities::default());
+            if matches!(
+                materialized.materialization,
+                ghostscope_dwarf::VariableMaterialization::DirectValue {
+                    value: ghostscope_dwarf::PlannedValue::RegisterValue { .. }
+                }
+            ) {
+                found_register = true;
+            }
+        }
+    }
+    assert!(
+        found_register,
+        "fixture must retain a register-backed parameter at the probe PC"
+    );
+    let target = TargetLauncher::binary(&binary)
+        .current_dir(directory.path())
+        .spawn()
+        .await?;
+    let result = capture(
+        &target,
+        quiet_runner(
+            r#"
+trace observe_register {
+    print "REGISTER_VALUE:{}", value;
+    print "MEMORY_VALUE:{}", G_REGISTER_PEER;
+}"#,
+            "[value_adapters]\nmax_nesting_depth = 1\n",
+        ),
+    )
+    .await;
+    target.terminate().await?;
+    let output = result?;
+    output.success();
+    output.note("value", "depth-limit");
+    output.note("G_REGISTER_PEER", "depth-limit");
+    for (tag, expected) in [("REGISTER_VALUE:", "41"), ("MEMORY_VALUE:", "73")] {
+        for value in output.events(tag) {
+            assert!(
+                value.contains(expected)
+                    && value.contains("<nested display limits: depth limit; see trace details>"),
+                "{value}"
+            );
+            assert!(
+                !value.contains("<unreadable:") && !value.contains("<unavailable:"),
+                "{value}"
+            );
+        }
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_capture_budget_retains_root_fields() -> anyhow::Result<()> {
+    init();
+    let output = run_fixture(
+        VALUES,
+        quiet_runner(
+            r#"trace observe_diagnostics { print "BUDGET:{}", G_CELL; }"#,
+            "[ebpf]\nmem_dump_cap = 24\n",
+        ),
+    )
+    .await?;
+    output.success();
+    output.note("G_CELL", "capture-budget");
+    for value in output.events("BUDGET:") {
+        assert!(
+            value.contains("<not expanded: capture budget>") && value.contains("len: 10"),
+            "{value}"
+        );
+        assert!(
+            !value.contains("<unreadable:") && !value.contains("<truncated:"),
+            "{value}"
+        );
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_recursive_type_keeps_finite_tree_readable() -> anyhow::Result<()> {
+    init();
+    let output = run_fixture(
+        VALUES,
+        quiet_runner(
+            r#"trace observe_diagnostics { print "TREE:{}", G_TREE; }"#,
+            r#"
+[ebpf]
+mem_dump_cap = 4096
+[value_adapters]
+max_nesting_depth = 8
+max_sequence_elements = 1
+"#,
+        ),
+    )
+    .await?;
+    output.success();
+    output.note("G_TREE.children[]", "recursive-type");
+    for value in output.events("TREE:") {
+        assert!(
+            value.contains(r#"label: "root""#)
+                && value.contains("<nested display limits: recursive type; see trace details>"),
+            "{value}"
+        );
+        assert!(
+            !value.contains("<unreadable:") && !value.contains("depth limit"),
+            "{value}"
+        );
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_event_limit_does_not_claim_a_read_failure() -> anyhow::Result<()> {
+    init();
+    let output = run_fixture(
+        VALUES,
+        quiet_runner(
+            r#"trace observe_diagnostics { print "EVENT:{}:{}", G_CELL, G_CELL; }"#,
+            "[ebpf]\nmem_dump_cap = 1024\nmax_trace_event_size = 256\n",
+        ),
+    )
+    .await?;
+    output.success();
+    for value in output.events("EVENT:") {
+        assert_eq!(
+            value,
+            "<truncated: capture limit>:<truncated: capture limit>"
+        );
+    }
+    assert!(!output.stderr.contains("Display note"), "{output:#?}");
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_value_diagnostics_offline_help_explains_public_reasons() -> anyhow::Result<()> {
+    init();
+    // The invalid configuration and PID must never reach runtime setup.
+    let output: CliOutput = quiet_runner("invalid script", "[invalid TOML")
+        .with_pid(u32::MAX)
+        .with_cli_args(["--value-diagnostics-help"])
+        .run()
+        .await?
+        .into();
+    assert_eq!(output.code, 0, "{output:#?}");
+    assert!(output.stderr.is_empty(), "{output:#?}");
+    assert_eq!(
+        output.stdout,
+        include_str!("../../docs/value-diagnostics.md")
+    );
+    let chinese = include_str!("../../docs/zh/value-diagnostics.md");
+    for reason in [
+        "optimized-out",
+        "memory-read-failed",
+        "layout-unsupported",
+        "read-plan-unsupported",
+        "byte-limit",
+        "element-limit",
+        "capture-limit",
+        "depth-limit",
+        "recursive-type",
+        "capture-budget",
+    ] {
+        for guide in [output.stdout.as_str(), chinese] {
+            assert!(
+                guide.lines().any(|line| line == format!("## {reason}")),
+                "missing documented reason {reason}"
+            );
+        }
+    }
+    assert!(
+        output.stdout.contains("--sleepable-uprobe")
+            && output.stdout.contains("sleepable_uprobe = true")
+    );
+    Ok(())
+}
diff --git a/ghostscope-compiler/src/ebpf/codegen/args.rs b/ghostscope-compiler/src/ebpf/codegen/args.rs
index eff7e57f..60c2320b 100644
--- a/ghostscope-compiler/src/ebpf/codegen/args.rs
+++ b/ghostscope-compiler/src/ebpf/codegen/args.rs
@@ -1,64 +1,77 @@
 use super::*;
 
-#[derive(Default)]
-struct SemanticValueResolution {
-    plan: Option<ghostscope_dwarf::ValueReadPlan>,
-    rejection: Option<ghostscope_dwarf::ValueAdapterReport>,
-}
+use ghostscope_dwarf::ValueReadPlanResolution;
 
 impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
     pub(super) const UNKNOWN_CHAR_ARRAY_READ_FALLBACK: usize = 256;
 
+    fn diagnosed_arg(
+        &mut self,
+        arg: ComplexArg<'ctx>,
+        diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
+    ) -> ComplexArg<'ctx> {
+        for diagnostic in diagnostics {
+            self.trace_context
+                .add_value_diagnostic(ghostscope_protocol::TraceValueDiagnostic {
+                    variable_index: arg.var_name_index,
+                    type_index: arg.type_index,
+                    diagnostic,
+                });
+        }
+        arg
+    }
+
+    fn finish_value_arg(
+        &mut self,
+        result: Result<ComplexArg<'ctx>>,
+        mut diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
+        report: Option<ghostscope_dwarf::ValueAdapterReport>,
+    ) -> Result<ComplexArg<'ctx>> {
+        let arg = result.map_err(|error| match &report {
+            Some(report) => error.with_value_adapter_rejection(report.clone()),
+            None => error,
+        })?;
+        if matches!(
+            self.trace_context.get_type(arg.type_index),
+            Some(ghostscope_dwarf::TypeInfo::OptimizedOut { .. })
+        ) {
+            return Ok(arg);
+        }
+        if let Some(report) = report {
+            if let ghostscope_dwarf::ValueAdapterOutcome::Rejected { stage, reason } =
+                report.outcome
+            {
+                diagnostics.push(ghostscope_protocol::ValueDiagnostic {
+                    path: String::new(),
+                    type_name: report.qualified_type_name.unwrap_or(report.type_name),
+                    reason: stage.diagnostic_reason(),
+                    detail: format!(
+                        "{}: {reason}",
+                        report.adapter.as_deref().unwrap_or("value adapter")
+                    ),
+                });
+            }
+        }
+        Ok(self.diagnosed_arg(arg, diagnostics))
+    }
+
     fn semantic_value_read_plan(
         &self,
         resolved_type: &ghostscope_dwarf::ResolvedType,
         type_module_path: Option<&std::path::Path>,
-    ) -> Result<SemanticValueResolution> {
+    ) -> Result<ValueReadPlanResolution> {
         let Some(analyzer) = self.process_analyzer else {
-            return Ok(SemanticValueResolution::default());
-        };
-        let options = ghostscope_dwarf::ValueReadPlanOptions {
-            max_nesting_depth: self.compile_options.value_adapter_max_nesting_depth,
+            return Ok(ValueReadPlanResolution::default());
         };
-        let report = analyzer
-            .explain_value_read_plan_with_options(resolved_type, type_module_path, options)
-            .map_err(|error| CodeGenError::DwarfError(error.to_string()))?;
-        match &report.outcome {
-            // Adapter reports intentionally describe named source-language
-            // adapters only. Operational resolution may still compose those
-            // adapters through an ordinary Rust struct.
-            ghostscope_dwarf::ValueAdapterOutcome::NotApplicable => analyzer
-                .value_read_plan_with_options(resolved_type, type_module_path, options)
-                .map(|plan| SemanticValueResolution {
-                    plan,
-                    rejection: None,
-                })
-                .map_err(|error| CodeGenError::DwarfError(error.to_string())),
-            ghostscope_dwarf::ValueAdapterOutcome::Applied { plan } => {
-                Ok(SemanticValueResolution {
-                    plan: Some((**plan).clone()),
-                    rejection: None,
-                })
-            }
-            ghostscope_dwarf::ValueAdapterOutcome::Rejected { stage, reason } => {
-                debug!(
-                    target: "ghostscope_dwarf::value_adapter",
-                    adapter = report.adapter.as_deref().unwrap_or("unknown"),
-                    type_name = report.type_name,
-                    qualified_type_name = ?report.qualified_type_name,
-                    producer = ?report.producer.as_ref().map(|producer| producer.raw.as_str()),
-                    rustc_version = ?report.rustc_version,
-                    dwarf_version = ?report.dwarf_version,
-                    ?stage,
-                    %reason,
-                    "Rust value adapter rejected target DWARF; using DWARF presentation"
-                );
-                Ok(SemanticValueResolution {
-                    plan: None,
-                    rejection: Some(report),
-                })
-            }
-        }
+        analyzer
+            .resolve_value_read_plan_with_options(
+                resolved_type,
+                type_module_path,
+                ghostscope_dwarf::ValueReadPlanOptions {
+                    max_nesting_depth: self.compile_options.value_adapter_max_nesting_depth,
+                },
+            )
+            .map_err(|error| CodeGenError::DwarfError(error.to_string()))
     }
 
     fn complex_arg_from_value_read_plan(
@@ -69,6 +82,7 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
         plan: ghostscope_dwarf::ValueReadPlan,
     ) -> Result<ComplexArg<'ctx>> {
         let cap = self.compile_options.mem_dump_cap as usize;
+        let mut diagnostics = plan.diagnostics.clone();
         if plan.nested.is_some() {
             if let Some(value) = compile_nested_value_source(
                 &plan,
@@ -76,9 +90,13 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
                 self.compile_options.value_adapter_max_sequence_elements,
             )? {
                 let output_type = value.output_type.clone();
-                let presentation = nested_value_presentation(&value)?;
+                let presentation = nested_value_presentation(
+                    &value,
+                    self.compile_options.value_adapter_max_sequence_elements,
+                )?;
                 let data_len = value.total_len;
-                return Ok(ComplexArg {
+                collect_capture_diagnostics(&plan, &value, "", cap, &mut diagnostics);
+                let arg = ComplexArg {
                     var_name_index: self.trace_context.add_variable_name(display_name)?,
                     type_index: self
                         .trace_context
@@ -89,13 +107,20 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
                         descriptor,
                         value: Box::new(value),
                     },
-                });
+                };
+                return Ok(self.diagnosed_arg(arg, diagnostics));
             }
+            let unsupported_condition = matches!(&plan.nested, Some(ghostscope_dwarf::ValueNestedPlan::Variant { fields }) if fields.iter().all(|field| compile_nested_variant_condition(&field.condition).is_none()));
+            diagnostics.push(ghostscope_protocol::ValueDiagnostic {
+                path: String::new(), type_name: plan.root_type.summary.type_name(),
+                reason: if unsupported_condition { ghostscope_protocol::ValueDiagnosticReason::ReadPlanUnsupported } else { ghostscope_protocol::ValueDiagnosticReason::CaptureBudget },
+                detail: if unsupported_condition { "Enum discriminants cannot select nested captures; using the root display".to_string() } else { format!("ebpf.mem_dump_cap = {cap} bytes cannot fit the nested capture; using the root display") },
+            });
             debug!(
                 target: "ghostscope_dwarf::value_adapter",
                 type_name = plan.root_type.summary.type_name(),
                 cap,
-                "Nested value plan exceeded its static capture budget; using the root adapter"
+                "Nested value plan could not be lowered within its capture constraints; using the root adapter"
             );
         }
         let ghostscope_dwarf::ValueReadPlan {
@@ -105,6 +130,7 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
             sequence_element: _,
             hash_table_fields: _,
             nested: _,
+            diagnostics: _,
         } = plan;
         let mut output_type = dwarf_type;
         let (data_len, source) = match capture {
@@ -396,7 +422,7 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
             }
         };
 
-        Ok(ComplexArg {
+        let arg = ComplexArg {
             var_name_index: self.trace_context.add_variable_name(display_name)?,
             type_index: self
                 .trace_context
@@ -404,7 +430,8 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
             access_path: Vec::new(),
             data_len,
             source,
-        })
+        };
+        Ok(self.diagnosed_arg(arg, diagnostics))
     }
 
     pub(super) fn complex_arg_from_dwarf_read_plan(
@@ -421,13 +448,14 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
                 Some(resolved_type) => {
                     self.semantic_value_read_plan(&resolved_type, plan.module_path.as_deref())?
                 }
-                None => SemanticValueResolution::default(),
+                None => ValueReadPlanResolution::default(),
             }
         } else {
-            SemanticValueResolution::default()
+            ValueReadPlanResolution::default()
         };
-        let SemanticValueResolution {
+        let ValueReadPlanResolution {
             plan: semantic_plan,
+            diagnostics,
             rejection,
         } = semantic_resolution;
         let fallback_result = (|| {
@@ -672,12 +700,7 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
             }
         })();
 
-        match rejection {
-            Some(report) => {
-                fallback_result.map_err(|error| error.with_value_adapter_rejection(report))
-            }
-            None => fallback_result,
-        }
+        self.finish_value_arg(fallback_result, diagnostics, rejection)
     }
 
     fn complex_arg_from_dynamic_lvalue(
@@ -685,19 +708,23 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
         expr: &crate::script::ast::Expr,
         lvalue: crate::ebpf::expression::DynamicLvalue<'ctx>,
     ) -> Result<ComplexArg<'ctx>> {
-        let SemanticValueResolution { plan, rejection } = self.semantic_value_read_plan(
+        let ValueReadPlanResolution {
+            plan,
+            diagnostics,
+            rejection,
+        } = self.semantic_value_read_plan(
             &lvalue.type_info.resolved_type,
             lvalue.type_info.type_module_path.as_deref(),
         )?;
-        if let Some(plan) = plan {
-            return self.complex_arg_from_value_read_plan(
-                self.expr_to_name(expr),
-                lvalue.type_info.resolved_type.summary,
-                lvalue.address,
-                plan,
-            );
-        }
         let fallback_result = (|| {
+            if let Some(plan) = plan {
+                return self.complex_arg_from_value_read_plan(
+                    self.expr_to_name(expr),
+                    lvalue.type_info.resolved_type.summary,
+                    lvalue.address,
+                    plan,
+                );
+            }
             let dwarf_type = lvalue.type_info.resolved_type.summary;
             let data_len = Self::compute_read_size_for_type(&dwarf_type);
             if data_len == 0 {
@@ -717,12 +744,7 @@ impl<'ctx, 'dw> EbpfContext<'ctx, 'dw> {
                 },
             })
         })();
-        match rejection {
-            Some(report) => {
-                fallback_result.map_err(|error| error.with_value_adapter_rejection(report))
-            }
-            None => fallback_result,
-        }
+        self.finish_value_arg(fallback_result, diagnostics, rejection)
     }
 
     fn complex_arg_from_cast_expr(
diff --git a/ghostscope-compiler/src/ebpf/codegen/value_capture/diagnostics.rs b/ghostscope-compiler/src/ebpf/codegen/value_capture/diagnostics.rs
new file mode 100644
index 00000000..82528f7d
--- /dev/null
+++ b/ghostscope-compiler/src/ebpf/codegen/value_capture/diagnostics.rs
@@ -0,0 +1,102 @@
+use super::*;
+use ghostscope_dwarf::{ValueNestedPlan, ValueReadPlan};
+use ghostscope_protocol::{ValueDiagnostic, ValueDiagnosticReason};
+
+/// Compare requested semantic children with the bounded capture actually
+/// compiled. This observes lowering; it never changes reads to obtain a note.
+pub(in crate::ebpf::codegen) fn collect_capture_diagnostics(
+    plan: &ValueReadPlan,
+    source: &NestedValueSource,
+    path: &str,
+    budget: usize,
+    notes: &mut Vec<ValueDiagnostic>,
+) {
+    let mut unsupported_conditions = Vec::new();
+    let mut child = |plan: &ValueReadPlan, actual: Option<&NestedValueSource>, suffix: &str| {
+        let path = format!("{path}{suffix}");
+        if let Some(actual) = actual {
+            collect_capture_diagnostics(plan, actual, &path, budget, notes);
+        } else {
+            notes.push(ValueDiagnostic {
+                path, type_name: plan.root_type.summary.type_name(),
+                reason: ValueDiagnosticReason::CaptureBudget,
+                detail: format!("Nested capture did not fit ebpf.mem_dump_cap = {budget} bytes; the available root fields are retained"),
+            });
+        }
+    };
+    match (&plan.nested, &source.children) {
+        (
+            Some(ValueNestedPlan::ProjectedValue { value }),
+            NestedValueChildrenSource::ProjectedValue { child: actual, .. },
+        ) => child(value, Some(actual), ".value"),
+        (
+            Some(ValueNestedPlan::ProjectedView { fields }),
+            NestedValueChildrenSource::ProjectedView { fields: actual },
+        ) => {
+            for field in fields {
+                child(
+                    &field.value,
+                    actual
+                        .iter()
+                        .find(|f| f.field_index == field.field_index)
+                        .map(|f| f.child.as_ref()),
+                    &plan.field_path(field.field_index),
+                );
+            }
+        }
+        (
+            Some(ValueNestedPlan::HashTable { fields }),
+            NestedValueChildrenSource::HashTable { fields: actual, .. },
+        ) => {
+            for field in fields {
+                child(
+                    &field.value,
+                    actual
+                        .iter()
+                        .find(|f| f.field_index == field.field_index)
+                        .map(|f| f.child.as_ref()),
+                    plan.hash_field_path(field.field_index),
+                );
+            }
+        }
+        (
+            Some(ValueNestedPlan::Variant { fields }),
+            NestedValueChildrenSource::Variant { fields: actual },
+        ) => {
+            for field in fields {
+                if compile_nested_variant_condition(&field.condition).is_none() {
+                    unsupported_conditions.push(ValueDiagnostic {
+                        path: format!("{path}{}", plan.variant_field_path(field)),
+                        type_name: field.value.root_type.summary.type_name(),
+                        reason: ValueDiagnosticReason::ReadPlanUnsupported,
+                        detail: "The enum discriminant cannot select this nested capture"
+                            .to_string(),
+                    });
+                    continue;
+                }
+
+                child(
+                    &field.value,
+                    actual
+                        .iter()
+                        .find(|f| {
+                            f.part_index == field.part_index
+                                && f.variant_index == field.variant_index
+                                && f.member_index == field.member_index
+                                && f.payload_field_index == field.payload_field_index
+                        })
+                        .map(|f| f.field.child.as_ref()),
+                    &plan.variant_field_path(field),
+                );
+            }
+        }
+        (
+            Some(ValueNestedPlan::Sequence { element }),
+            NestedValueChildrenSource::Sequence {
+                element: actual, ..
+            },
+        ) => child(element, Some(actual), "[]"),
+        _ => {}
+    }
+    notes.extend(unsupported_conditions);
+}
diff --git a/ghostscope-compiler/src/ebpf/codegen/value_capture/mod.rs b/ghostscope-compiler/src/ebpf/codegen/value_capture/mod.rs
index 18129026..d38afbfa 100644
--- a/ghostscope-compiler/src/ebpf/codegen/value_capture/mod.rs
+++ b/ghostscope-compiler/src/ebpf/codegen/value_capture/mod.rs
@@ -1,10 +1,12 @@
 use super::{CodeGenError, EbpfContext, Result};
 
+mod diagnostics;
 mod layout;
 mod lowering;
 mod model;
 mod presentation;
 
+pub(super) use diagnostics::*;
 pub(super) use layout::*;
 pub(super) use lowering::*;
 pub(super) use model::*;
diff --git a/ghostscope-compiler/src/ebpf/codegen/value_capture/presentation.rs b/ghostscope-compiler/src/ebpf/codegen/value_capture/presentation.rs
index d67d3fda..83f2686b 100644
--- a/ghostscope-compiler/src/ebpf/codegen/value_capture/presentation.rs
+++ b/ghostscope-compiler/src/ebpf/codegen/value_capture/presentation.rs
@@ -2,6 +2,7 @@ use super::*;
 
 pub(in crate::ebpf::codegen) fn nested_value_presentation(
     value: &NestedValueSource,
+    max_sequence_elements: usize,
 ) -> Result<ghostscope_dwarf::ValuePresentation> {
     let children = match &value.children {
         NestedValueChildrenSource::None => return Ok(value.presentation.clone()),
@@ -13,7 +14,7 @@ pub(in crate::ebpf::codegen) fn nested_value_presentation(
                             "nested child slot offset does not fit the protocol".to_string(),
                         )
                     })?,
-                    value: Box::new(nested_child_presentation(child)?),
+                    value: Box::new(nested_child_presentation(child, max_sequence_elements)?),
                 }),
             }
         }
@@ -35,7 +36,10 @@ pub(in crate::ebpf::codegen) fn nested_value_presentation(
                                             .to_string(),
                                     )
                                 })?,
-                                value: Box::new(nested_child_presentation(&field.child)?),
+                                value: Box::new(nested_child_presentation(
+                                    &field.child,
+                                    max_sequence_elements,
+                                )?),
                             },
                         })
                     })
@@ -80,7 +84,10 @@ pub(in crate::ebpf::codegen) fn nested_value_presentation(
                                     .to_string(),
                             )
                         })?,
-                        value: Box::new(nested_child_presentation(&field.child)?),
+                        value: Box::new(nested_child_presentation(
+                            &field.child,
+                            max_sequence_elements,
+                        )?),
                     })
                 })
                 .collect::<Result<Vec<_>>>()?,
@@ -114,7 +121,10 @@ pub(in crate::ebpf::codegen) fn nested_value_presentation(
                                         )
                                     },
                                 )?,
-                                value: Box::new(nested_child_presentation(&field.field.child)?),
+                                value: Box::new(nested_child_presentation(
+                                    &field.field.child,
+                                    max_sequence_elements,
+                                )?),
                             },
                         })
                     })
@@ -143,7 +153,8 @@ pub(in crate::ebpf::codegen) fn nested_value_presentation(
                     "nested sequence count does not fit the protocol".to_string(),
                 )
             })?,
-            element: Box::new(nested_child_presentation(element)?),
+            element_limit: Some(max_sequence_elements as u64),
+            element: Box::new(nested_child_presentation(element, max_sequence_elements)?),
         },
     };
     Ok(ghostscope_dwarf::ValuePresentation::Nested {
@@ -159,6 +170,7 @@ pub(in crate::ebpf::codegen) fn nested_value_presentation(
 
 pub(in crate::ebpf::codegen) fn nested_child_presentation(
     value: &NestedValueSource,
+    max_sequence_elements: usize,
 ) -> Result<ghostscope_protocol::NestedValuePresentation> {
     Ok(ghostscope_protocol::NestedValuePresentation {
         payload_len: u64::try_from(value.total_len).map_err(|_| {
@@ -167,6 +179,6 @@ pub(in crate::ebpf::codegen) fn nested_child_presentation(
             )
         })?,
         type_info: Box::new(value.output_type.clone()),
-        presentation: Box::new(nested_value_presentation(value)?),
+        presentation: Box::new(nested_value_presentation(value, max_sequence_elements)?),
     })
 }
diff --git a/ghostscope-compiler/src/ebpf/codegen/value_capture/tests.rs b/ghostscope-compiler/src/ebpf/codegen/value_capture/tests.rs
index 9bde539a..665e17c9 100644
--- a/ghostscope-compiler/src/ebpf/codegen/value_capture/tests.rs
+++ b/ghostscope-compiler/src/ebpf/codegen/value_capture/tests.rs
@@ -341,6 +341,7 @@ fn string_value_plan() -> ValueReadPlan {
             excluded_tail_bytes: 0,
         },
         sequence_element: None,
+        diagnostics: Vec::new(),
         hash_table_fields: Vec::new(),
         nested: None,
     }
@@ -360,6 +361,7 @@ fn nested_string_sequence_plan() -> ValueReadPlan {
             element_stride: 24,
         },
         sequence_element: Some(string.root_type.clone()),
+        diagnostics: Vec::new(),
         hash_table_fields: Vec::new(),
         nested: Some(ValueNestedPlan::Sequence {
             element: Box::new(string),
@@ -405,6 +407,7 @@ fn many_variant_strings_plan(variant_count: usize) -> ValueReadPlan {
             fields: Vec::new(),
         },
         sequence_element: None,
+        diagnostics: Vec::new(),
         hash_table_fields: Vec::new(),
         nested: Some(ValueNestedPlan::Variant { fields }),
     }
@@ -441,6 +444,7 @@ fn nested_string_hash_map_plan() -> ValueReadPlan {
             bucket_order: HashTableBucketOrder::Reverse,
         },
         sequence_element: None,
+        diagnostics: Vec::new(),
         hash_table_fields: Vec::new(),
         nested: Some(ValueNestedPlan::HashTable {
             fields: vec![
@@ -558,3 +562,28 @@ fn nested_hash_table_capture_reuses_field_plans_for_bounded_buckets() {
     };
     assert_eq!(bucket_count, 2);
 }
+
+#[test]
+fn unlowerable_variant_condition_is_not_reported_as_a_capture_budget() {
+    let mut plan = many_variant_strings_plan(2);
+    let Some(ValueNestedPlan::Variant { fields }) = &mut plan.nested else {
+        panic!("expected variant plan");
+    };
+    let ValueNestedVariantCondition::Discriminant { member, .. } = &mut fields[0].condition else {
+        panic!("expected discriminant condition");
+    };
+    member.member_type = TypeInfo::BaseType {
+        name: "unsupported-width".to_string(),
+        size: 3,
+        encoding: ghostscope_dwarf::constants::DW_ATE_unsigned.0 as u16,
+    };
+    let source = compile_nested_value_source(&plan, 256, 4).unwrap().unwrap();
+    let mut diagnostics = Vec::new();
+    collect_capture_diagnostics(&plan, &source, "", 256, &mut diagnostics);
+    assert_eq!(diagnostics.len(), 1);
+    assert_eq!(
+        diagnostics[0].reason,
+        ghostscope_protocol::ValueDiagnosticReason::ReadPlanUnsupported
+    );
+    assert!(diagnostics[0].path.contains("variant0"));
+}
diff --git a/ghostscope-compiler/src/lib.rs b/ghostscope-compiler/src/lib.rs
index 94f87315..9706566b 100644
--- a/ghostscope-compiler/src/lib.rs
+++ b/ghostscope-compiler/src/lib.rs
@@ -116,6 +116,7 @@ fn format_value_adapter_rejection(report: &ghostscope_dwarf::ValueAdapterReport)
     let ghostscope_dwarf::ValueAdapterOutcome::Rejected { stage, reason } = &report.outcome else {
         return None;
     };
+    let reason_code = stage.diagnostic_reason().code();
     let stage = match stage {
         ghostscope_dwarf::ValueAdapterStage::LayoutValidation => "layout-validation",
         ghostscope_dwarf::ValueAdapterStage::ReadPlanConstruction => "read-plan-construction",
@@ -147,6 +148,9 @@ fn format_value_adapter_rejection(report: &ghostscope_dwarf::ValueAdapterReport)
     if let Some(producer) = &report.producer {
         lines.push(format!("  producer: {}", producer.raw));
     }
+    lines.push(format!(
+        "  Help: docs/value-diagnostics.md#{reason_code} (offline: ghostscope --value-diagnostics-help)"
+    ));
     Some(lines.join("\n"))
 }
 
diff --git a/ghostscope-dwarf/src/analyzer/type_context.rs b/ghostscope-dwarf/src/analyzer/type_context.rs
index 53b149e2..a3deb697 100644
--- a/ghostscope-dwarf/src/analyzer/type_context.rs
+++ b/ghostscope-dwarf/src/analyzer/type_context.rs
@@ -6,14 +6,18 @@ use crate::{
     TypeLayoutError, TypeOrigin, TypeProjection, TypeProjectionLayout, ValueAdapterOutcome,
     ValueAdapterReport, ValueAdapterStage, ValueCapturePlan, ValueNestedFieldPlan,
     ValueNestedHashTableFieldPlan, ValueNestedPlan, ValueReadPlan, ValueReadPlanOptions,
-    VariableAccessSegment, VariableReadPlan,
+    ValueReadPlanResolution, VariableAccessSegment, VariableReadPlan,
 };
+use ghostscope_protocol::{ValueDiagnostic, ValueDiagnosticReason};
 use std::path::Path;
 
 enum ShallowValueReadPlan {
     Applied(Box<ValueReadPlan>),
     NotApplicable,
-    Rejected,
+    Rejected {
+        reason: ValueDiagnosticReason,
+        detail: String,
+    },
 }
 
 impl DwarfAnalyzer {
@@ -329,25 +333,48 @@ impl DwarfAnalyzer {
         )
     }
 
-    /// Build a semantic capture plan with explicit nesting limits.
+    /// Build a semantic capture plan with explicit nesting limits. Consumers
+    /// that also need notes when no plan applies should use
+    /// [`Self::resolve_value_read_plan_with_options`].
     pub fn value_read_plan_with_options(
         &self,
         current: &ResolvedType,
         type_module_path: Option<&Path>,
         options: ValueReadPlanOptions,
     ) -> Result<Option<ValueReadPlan>> {
+        let mut resolution =
+            self.resolve_value_read_plan_with_options(current, type_module_path, options)?;
+        if let Some(plan) = &mut resolution.plan {
+            plan.diagnostics = resolution.diagnostics;
+        }
+        Ok(resolution.plan)
+    }
+
+    /// Resolve capture and static notes separately. Diagnostic-only aggregates
+    /// keep `plan = None`, preserving ordinary address and register reads.
+    pub fn resolve_value_read_plan_with_options(
+        &self,
+        current: &ResolvedType,
+        type_module_path: Option<&Path>,
+        options: ValueReadPlanOptions,
+    ) -> Result<ValueReadPlanResolution> {
         let report =
             self.explain_value_read_plan_with_options(current, type_module_path, options)?;
-        match report.outcome {
-            ValueAdapterOutcome::NotApplicable => Ok(self.aggregate_value_read_plan(
+        let mut diagnostics = Vec::new();
+        let mut plan = match report.outcome {
+            ValueAdapterOutcome::NotApplicable => self.aggregate_value_read_plan(
                 current,
                 type_module_path,
                 0,
                 options.max_nesting_depth,
                 &mut Vec::new(),
-            )),
-            ValueAdapterOutcome::Applied { plan } => Ok(Some(*plan)),
-            ValueAdapterOutcome::Rejected { stage, reason } => {
+                &mut diagnostics,
+            ),
+            ValueAdapterOutcome::Applied { plan } => Some(*plan),
+            ValueAdapterOutcome::Rejected {
+                ref stage,
+                ref reason,
+            } => {
                 tracing::debug!(
                     target: "ghostscope_dwarf::value_adapter",
                     adapter = report.adapter.as_deref().unwrap_or("unknown"),
@@ -361,9 +388,21 @@ impl DwarfAnalyzer {
                     %reason,
                     "Source-language value adapter rejected target DWARF; using DWARF presentation"
                 );
-                Ok(None)
+                return Ok(ValueReadPlanResolution {
+                    plan: None,
+                    diagnostics,
+                    rejection: Some(report),
+                });
             }
+        };
+        if let Some(plan) = &mut plan {
+            diagnostics.append(&mut plan.diagnostics);
         }
+        Ok(ValueReadPlanResolution {
+            plan,
+            diagnostics,
+            rejection: None,
+        })
     }
 
     /// Explain whether a source-language adapter can present this value.
@@ -479,14 +518,20 @@ impl DwarfAnalyzer {
             crate::language::ValueLayoutResolution::NotApplicable => {
                 return Ok(ShallowValueReadPlan::NotApplicable);
             }
-            crate::language::ValueLayoutResolution::Rejected { .. } => {
-                return Ok(ShallowValueReadPlan::Rejected);
+            crate::language::ValueLayoutResolution::Rejected { reason, .. } => {
+                return Ok(ShallowValueReadPlan::Rejected {
+                    reason: ValueDiagnosticReason::LayoutUnsupported,
+                    detail: reason.to_string(),
+                });
             }
         };
         Ok(
             match crate::language::build_value_read_plan(self, current, type_module_path, layout)? {
                 Some(plan) => ShallowValueReadPlan::Applied(Box::new(plan)),
-                None => ShallowValueReadPlan::Rejected,
+                None => ShallowValueReadPlan::Rejected {
+                    reason: ValueDiagnosticReason::ReadPlanUnsupported,
+                    detail: "Dependent debug information could not form a capture plan".to_string(),
+                },
             },
         )
     }
@@ -498,6 +543,7 @@ impl DwarfAnalyzer {
         depth: usize,
         max_nesting_depth: usize,
         ancestors: &mut Vec<TypeId>,
+        diagnostics: &mut Vec<ValueDiagnostic>,
     ) -> Option<ValueReadPlan> {
         let plan = match self.value_read_plan_shallow(current, type_module_path) {
             Ok(ShallowValueReadPlan::Applied(plan)) => *plan,
@@ -508,9 +554,18 @@ impl DwarfAnalyzer {
                     depth,
                     max_nesting_depth,
                     ancestors,
+                    diagnostics,
                 );
             }
-            Ok(ShallowValueReadPlan::Rejected) => return None,
+            Ok(ShallowValueReadPlan::Rejected { reason, detail }) => {
+                diagnostics.push(ValueDiagnostic {
+                    path: String::new(),
+                    type_name: current.summary.type_name(),
+                    reason,
+                    detail,
+                });
+                return None;
+            }
             Err(error) => {
                 tracing::debug!(
                     target: "ghostscope_dwarf::value_adapter",
@@ -518,6 +573,12 @@ impl DwarfAnalyzer {
                     %error,
                     "Nested value adapter could not form a child plan; using DWARF presentation"
                 );
+                diagnostics.push(ValueDiagnostic {
+                    path: String::new(),
+                    type_name: current.summary.type_name(),
+                    reason: ValueDiagnosticReason::ReadPlanUnsupported,
+                    detail: error.to_string(),
+                });
                 return None;
             }
         };
@@ -538,6 +599,7 @@ impl DwarfAnalyzer {
         depth: usize,
         max_nesting_depth: usize,
         ancestors: &mut Vec<TypeId>,
+        diagnostics: &mut Vec<ValueDiagnostic>,
     ) -> Option<ValueReadPlan> {
         let plan =
             crate::language::build_aggregate_value_read_plan(self, current, type_module_path)?;
@@ -549,7 +611,80 @@ impl DwarfAnalyzer {
             max_nesting_depth,
             ancestors,
         );
-        plan.nested.is_some().then_some(plan)
+        if plan.nested.is_some() {
+            Some(plan)
+        } else {
+            diagnostics.extend(plan.diagnostics);
+            None
+        }
+    }
+
+    /// Bounded diagnostic-only lookahead. Ordinary structs containing only
+    /// physical fields must not acquire a spurious "depth limit" warning.
+    /// This never adds a read or follows the runtime pointer graph.
+    fn has_semantic_display_descendant(
+        &self,
+        current: &ResolvedType,
+        type_module_path: Option<&Path>,
+        remaining: &mut usize,
+        visited: &mut Vec<TypeId>,
+    ) -> bool {
+        if *remaining == 0 {
+            return false;
+        }
+        *remaining -= 1;
+        if let Some(id) = current.identity.layout_dwarf_id() {
+            if visited.contains(&id) {
+                return false;
+            }
+            visited.push(id);
+        }
+        match self.value_read_plan_shallow(current, type_module_path) {
+            Ok(ShallowValueReadPlan::Applied(_) | ShallowValueReadPlan::Rejected { .. }) => true,
+            Ok(ShallowValueReadPlan::NotApplicable) => {
+                let Some(plan) = crate::language::build_aggregate_value_read_plan(
+                    self,
+                    current,
+                    type_module_path,
+                ) else {
+                    return false;
+                };
+                let mut found = false;
+                let mut inspect = |child: &ResolvedType, _: &str| {
+                    if !found {
+                        found = self.has_semantic_display_descendant(
+                            child,
+                            type_module_path,
+                            remaining,
+                            visited,
+                        );
+                    }
+                    None
+                };
+                let _ = crate::language::build_nested_value_read_plan(
+                    self,
+                    current,
+                    &plan.capture,
+                    type_module_path,
+                    &mut inspect,
+                );
+                if found {
+                    return true;
+                }
+                if let ValueCapturePlan::InlineView { fields, .. } = &plan.capture {
+                    return fields.iter().any(|field| {
+                        self.has_semantic_display_descendant(
+                            &field.resolved_type,
+                            type_module_path,
+                            remaining,
+                            visited,
+                        )
+                    });
+                }
+                false
+            }
+            Err(_) => false,
+        }
     }
 
     fn enrich_nested_value_read_plan(
@@ -561,63 +696,84 @@ impl DwarfAnalyzer {
         max_nesting_depth: usize,
         ancestors: &mut Vec<TypeId>,
     ) -> ValueReadPlan {
-        if depth >= max_nesting_depth {
-            return plan;
-        }
         let current_id = current.identity.layout_dwarf_id();
-        if current_id.is_some_and(|type_id| ancestors.contains(&type_id)) {
-            return plan;
-        }
+        let repeated = current_id.is_some_and(|type_id| ancestors.contains(&type_id));
+        let limit = if depth >= max_nesting_depth {
+            Some(ValueDiagnosticReason::DepthLimit)
+        } else if repeated {
+            Some(ValueDiagnosticReason::RecursiveType)
+        } else {
+            None
+        };
         if let Some(type_id) = current_id {
             ancestors.push(type_id);
         }
-
-        let language_nested = {
-            let mut resolve_nested = |child: &ResolvedType| {
-                self.try_nested_value_read_plan(
+        let mut diagnostics = Vec::new();
+        let mut resolve_nested = |child: &ResolvedType, path: &str| {
+            let mut child_diagnostics = Vec::new();
+            if let Some(reason) = limit {
+                // Use bounded type-only lookahead to avoid warning about plain
+                // structs. No additional runtime capture is planned.
+                let candidate = self.has_semantic_display_descendant(
                     child,
                     type_module_path,
-                    depth + 1,
-                    max_nesting_depth,
-                    ancestors,
-                )
-            };
-            crate::language::build_nested_value_read_plan(
-                self,
-                current,
-                &plan.capture,
+                    &mut 64,
+                    &mut Vec::new(),
+                );
+                if candidate {
+                    diagnostics.push(ValueDiagnostic {
+                        path: path.to_string(), type_name: child.summary.type_name(), reason,
+                        detail: if reason == ValueDiagnosticReason::DepthLimit {
+                            format!("value_adapters.max_nesting_depth = {max_nesting_depth}; deeper contents keep their existing field representation")
+                        } else { "Expansion stopped at a repeated DWARF type; deeper contents keep their existing field representation".to_string() },
+                    });
+                }
+                return None;
+            }
+            let child_plan = self.try_nested_value_read_plan(
+                child,
                 type_module_path,
-                &mut resolve_nested,
-            )
+                depth + 1,
+                max_nesting_depth,
+                ancestors,
+                &mut child_diagnostics,
+            );
+            if let Some(plan) = &child_plan {
+                child_diagnostics.extend(plan.diagnostics.clone());
+            }
+            diagnostics.extend(
+                child_diagnostics
+                    .into_iter()
+                    .map(|note| note.prefixed(path)),
+            );
+            child_plan
         };
-
+        let language_nested = crate::language::build_nested_value_read_plan(
+            self,
+            current,
+            &plan.capture,
+            type_module_path,
+            &mut resolve_nested,
+        );
         let mut build_generic_nested = || match &plan.capture {
-            ValueCapturePlan::ProjectedValue { value } => self
-                .try_nested_value_read_plan(
-                    &value.resolved_type,
-                    type_module_path,
-                    depth + 1,
-                    max_nesting_depth,
-                    ancestors,
-                )
-                .map(|value| ValueNestedPlan::ProjectedValue {
-                    value: Box::new(value),
-                }),
+            ValueCapturePlan::ProjectedValue { value } => {
+                resolve_nested(&value.resolved_type, ".value").map(|value| {
+                    ValueNestedPlan::ProjectedValue {
+                        value: Box::new(value),
+                    }
+                })
+            }
             ValueCapturePlan::InlineView { fields, .. } => {
                 let nested_fields = fields
                     .iter()
                     .enumerate()
                     .filter_map(|(field_index, field)| {
-                        self.try_nested_value_read_plan(
-                            &field.resolved_type,
-                            type_module_path,
-                            depth + 1,
-                            max_nesting_depth,
-                            ancestors,
-                        )
-                        .map(|value| ValueNestedFieldPlan {
-                            field_index,
-                            value: Box::new(value),
+                        let path = plan.field_path(field_index);
+                        resolve_nested(&field.resolved_type, &path).map(|value| {
+                            ValueNestedFieldPlan {
+                                field_index,
+                                value: Box::new(value),
+                            }
                         })
                     })
                     .collect::<Vec<_>>();
@@ -631,16 +787,12 @@ impl DwarfAnalyzer {
                     .enumerate()
                     .filter(|(_, field)| field.capture == crate::ProjectedViewFieldCapture::Value)
                     .filter_map(|(field_index, field)| {
-                        self.try_nested_value_read_plan(
-                            &field.value.resolved_type,
-                            type_module_path,
-                            depth + 1,
-                            max_nesting_depth,
-                            ancestors,
-                        )
-                        .map(|value| ValueNestedFieldPlan {
-                            field_index,
-                            value: Box::new(value),
+                        let path = plan.field_path(field_index);
+                        resolve_nested(&field.value.resolved_type, &path).map(|value| {
+                            ValueNestedFieldPlan {
+                                field_index,
+                                value: Box::new(value),
+                            }
                         })
                     })
                     .collect::<Vec<_>>();
@@ -652,15 +804,7 @@ impl DwarfAnalyzer {
             | ValueCapturePlan::IndirectRingSequence { .. } => plan
                 .sequence_element
                 .as_ref()
-                .and_then(|element| {
-                    self.try_nested_value_read_plan(
-                        element,
-                        type_module_path,
-                        depth + 1,
-                        max_nesting_depth,
-                        ancestors,
-                    )
-                })
+                .and_then(|element| resolve_nested(element, "[]"))
                 .map(|element| ValueNestedPlan::Sequence {
                     element: Box::new(element),
                 }),
@@ -669,16 +813,12 @@ impl DwarfAnalyzer {
                     .hash_table_fields
                     .iter()
                     .filter_map(|field| {
-                        self.try_nested_value_read_plan(
-                            &field.resolved_type,
-                            type_module_path,
-                            depth + 1,
-                            max_nesting_depth,
-                            ancestors,
-                        )
-                        .map(|value| ValueNestedHashTableFieldPlan {
-                            field_index: field.field_index,
-                            value: Box::new(value),
+                        let path = plan.hash_field_path(field.field_index);
+                        resolve_nested(&field.resolved_type, path).map(|value| {
+                            ValueNestedHashTableFieldPlan {
+                                field_index: field.field_index,
+                                value: Box::new(value),
+                            }
                         })
                     })
                     .collect::<Vec<_>>();
@@ -686,17 +826,17 @@ impl DwarfAnalyzer {
                     fields: nested_fields,
                 })
             }
-            ValueCapturePlan::IndirectBytes { .. } | ValueCapturePlan::IndirectBTree { .. } => None,
+            _ => None,
         };
         let nested = match language_nested {
-            crate::language::NestedValuePlanResolution::Handled(nested) => nested,
             crate::language::NestedValuePlanResolution::NotApplicable => build_generic_nested(),
+            crate::language::NestedValuePlanResolution::Handled(plan) => plan,
         };
-
         if current_id.is_some() {
             ancestors.pop();
         }
         plan.nested = nested;
+        plan.diagnostics = diagnostics;
         plan
     }
 
diff --git a/ghostscope-dwarf/src/language/mod.rs b/ghostscope-dwarf/src/language/mod.rs
index db2e5bb5..1051f753 100644
--- a/ghostscope-dwarf/src/language/mod.rs
+++ b/ghostscope-dwarf/src/language/mod.rs
@@ -84,7 +84,7 @@ pub(crate) fn build_nested_value_read_plan(
     current: &crate::ResolvedType,
     capture: &crate::ValueCapturePlan,
     type_module_path: Option<&Path>,
-    resolve_nested: &mut dyn FnMut(&crate::ResolvedType) -> Option<crate::ValueReadPlan>,
+    resolve_nested: &mut dyn FnMut(&crate::ResolvedType, &str) -> Option<crate::ValueReadPlan>,
 ) -> NestedValuePlanResolution {
     let crate::ValueCapturePlan::InlineView { output_type, .. } = capture else {
         return NestedValuePlanResolution::NotApplicable;
@@ -297,8 +297,9 @@ mod tests {
             build_aggregate_value_read_plan(&context, &current, None),
             None
         );
-        let mut resolve_nested =
-            |_child: &ResolvedType| panic!("non-Rust composition must not resolve nested values");
+        let mut resolve_nested = |_child: &ResolvedType, _path: &str| {
+            panic!("non-Rust composition must not resolve nested values")
+        };
         assert_eq!(
             build_nested_value_read_plan(
                 &context,
@@ -326,8 +327,9 @@ mod tests {
             Some(origin(SourceLanguage::Rust)),
         );
         let context = PanicValueAdapterContext;
-        let mut resolve_nested =
-            |_child: &ResolvedType| panic!("ordinary inline views use generic recursion");
+        let mut resolve_nested = |_child: &ResolvedType, _path: &str| {
+            panic!("ordinary inline views use generic recursion")
+        };
 
         assert_eq!(
             build_nested_value_read_plan(
@@ -357,8 +359,9 @@ mod tests {
             Some(origin(SourceLanguage::C)),
         );
         let context = PanicValueAdapterContext;
-        let mut resolve_nested =
-            |_child: &ResolvedType| panic!("non-Rust variants must not resolve nested values");
+        let mut resolve_nested = |_child: &ResolvedType, _path: &str| {
+            panic!("non-Rust variants must not resolve nested values")
+        };
 
         assert_eq!(
             build_nested_value_read_plan(
diff --git a/ghostscope-dwarf/src/language/rust/composition.rs b/ghostscope-dwarf/src/language/rust/composition.rs
index 44577625..9a42fde3 100644
--- a/ghostscope-dwarf/src/language/rust/composition.rs
+++ b/ghostscope-dwarf/src/language/rust/composition.rs
@@ -68,7 +68,7 @@ pub(super) fn build_variant_nested_plan(
     context: &dyn ValueAdapterContext,
     current: &ResolvedType,
     type_module_path: Option<&Path>,
-    resolve_nested: &mut dyn FnMut(&ResolvedType) -> Option<ValueReadPlan>,
+    resolve_nested: &mut dyn FnMut(&ResolvedType, &str) -> Option<ValueReadPlan>,
 ) -> Option<ValueNestedPlan> {
     if current.origin.as_ref().map(|origin| origin.language) != Some(SourceLanguage::Rust) {
         return None;
@@ -148,7 +148,10 @@ pub(super) fn build_variant_nested_plan(
                     if offset != payload_field.offset {
                         continue;
                     }
-                    let Some(value) = resolve_nested(&projection.resolved_type) else {
+                    let Some(value) = resolve_nested(
+                        &projection.resolved_type,
+                        &format!("::{}.{}", member.name, payload_field.name),
+                    ) else {
                         continue;
                     };
                     fields.push(ValueNestedVariantFieldPlan {
diff --git a/ghostscope-dwarf/src/language/rust/mod.rs b/ghostscope-dwarf/src/language/rust/mod.rs
index 25c57278..a407de23 100644
--- a/ghostscope-dwarf/src/language/rust/mod.rs
+++ b/ghostscope-dwarf/src/language/rust/mod.rs
@@ -46,7 +46,7 @@ pub(super) fn build_variant_nested_plan(
     context: &dyn crate::language::adapter::ValueAdapterContext,
     current: &crate::ResolvedType,
     type_module_path: Option<&std::path::Path>,
-    resolve_nested: &mut dyn FnMut(&crate::ResolvedType) -> Option<crate::ValueReadPlan>,
+    resolve_nested: &mut dyn FnMut(&crate::ResolvedType, &str) -> Option<crate::ValueReadPlan>,
 ) -> Option<crate::ValueNestedPlan> {
     composition::build_variant_nested_plan(context, current, type_module_path, resolve_nested)
 }
diff --git a/ghostscope-dwarf/src/lib.rs b/ghostscope-dwarf/src/lib.rs
index fee1d43f..da0fd859 100644
--- a/ghostscope-dwarf/src/lib.rs
+++ b/ghostscope-dwarf/src/lib.rs
@@ -61,10 +61,11 @@ pub use semantics::{
     ValueAdapterReport, ValueAdapterStage, ValueCapturePlan, ValueHashTableField,
     ValueNestedFieldPlan, ValueNestedHashTableFieldPlan, ValueNestedPlan,
     ValueNestedVariantCondition, ValueNestedVariantFieldPlan, ValueReadPlan, ValueReadPlanOptions,
-    VariableAccessPath, VariableAccessSegment, VariableLookupError, VariableLoweringKind,
-    VariableLoweringPlan, VariableMaterialization, VariableMaterializationPlan, VariablePlan,
-    VariableQueryDiagnostic, VariableReadPlan, VisibleVariable, VisibleVariablesResult,
-    DEFAULT_VALUE_ADAPTER_NESTING_DEPTH, MAX_VALUE_ADAPTER_NESTING_DEPTH,
+    ValueReadPlanResolution, VariableAccessPath, VariableAccessSegment, VariableLookupError,
+    VariableLoweringKind, VariableLoweringPlan, VariableMaterialization,
+    VariableMaterializationPlan, VariablePlan, VariableQueryDiagnostic, VariableReadPlan,
+    VisibleVariable, VisibleVariablesResult, DEFAULT_VALUE_ADAPTER_NESTING_DEPTH,
+    MAX_VALUE_ADAPTER_NESTING_DEPTH,
 };
 
 pub use semantics::{
diff --git a/ghostscope-dwarf/src/semantics/mod.rs b/ghostscope-dwarf/src/semantics/mod.rs
index 29a763dd..7b5a5727 100644
--- a/ghostscope-dwarf/src/semantics/mod.rs
+++ b/ghostscope-dwarf/src/semantics/mod.rs
@@ -46,7 +46,7 @@ pub use value::{
     ValueAdapterOutcome, ValueAdapterReport, ValueAdapterStage, ValueCapturePlan,
     ValueHashTableField, ValueNestedFieldPlan, ValueNestedHashTableFieldPlan, ValueNestedPlan,
     ValueNestedVariantCondition, ValueNestedVariantFieldPlan, ValueReadPlan, ValueReadPlanOptions,
-    DEFAULT_VALUE_ADAPTER_NESTING_DEPTH, MAX_VALUE_ADAPTER_NESTING_DEPTH,
+    ValueReadPlanResolution, DEFAULT_VALUE_ADAPTER_NESTING_DEPTH, MAX_VALUE_ADAPTER_NESTING_DEPTH,
 };
 pub(crate) use variable_plan::PlanError;
 pub use variable_plan::{
diff --git a/ghostscope-dwarf/src/semantics/value.rs b/ghostscope-dwarf/src/semantics/value.rs
index 7f9e7b63..4c5f44a6 100644
--- a/ghostscope-dwarf/src/semantics/value.rs
+++ b/ghostscope-dwarf/src/semantics/value.rs
@@ -25,6 +25,17 @@ impl Default for ValueReadPlanOptions {
     }
 }
 
+/// Operational adapter selection with diagnostics independent of capture.
+/// A missing plan keeps the ordinary DWARF read path, even when notes exist.
+#[derive(Debug, Clone, Default)]
+pub struct ValueReadPlanResolution {
+    pub plan: Option<ValueReadPlan>,
+    /// Root-relative static notes, including notes from an applied plan.
+    pub diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
+    /// Rejected root adapter metadata for reporting a failed DWARF fallback.
+    pub rejection: Option<ValueAdapterReport>,
+}
+
 /// A language-selected presentation and the physical reads needed to produce
 /// its protocol payload.
 #[derive(Debug, Clone, PartialEq)]
@@ -46,9 +57,60 @@ pub struct ValueReadPlan {
     /// implement nested capture can ignore this metadata and retain the
     /// existing one-level presentation.
     pub nested: Option<ValueNestedPlan>,
+    /// Static display limits relative to this root, including possible enum
+    /// branches. They do not change the capture or assert a runtime failure.
+    pub diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
 }
 
 impl ValueReadPlan {
+    pub fn field_path(&self, index: usize) -> String {
+        let output = match &self.capture {
+            ValueCapturePlan::InlineView { output_type, .. }
+            | ValueCapturePlan::ProjectedView { output_type, .. } => output_type,
+            _ => &self.root_type.summary,
+        };
+        if let crate::TypeInfo::StructType { members, .. } = crate::strip_type_aliases(output) {
+            if let Some(member) = members.get(index) {
+                return format!(".{}", member.name);
+            }
+        }
+        format!(".field{index}")
+    }
+
+    pub fn hash_field_path(&self, index: usize) -> &'static str {
+        match &self.presentation {
+            ValuePresentation::HashTable {
+                entry: ghostscope_protocol::HashTableEntryPresentation::Map { .. },
+                ..
+            } if index == 0 => "[].key",
+            _ => "[].value",
+        }
+    }
+
+    pub fn variant_field_path(&self, field: &ValueNestedVariantFieldPlan) -> String {
+        if let crate::TypeInfo::VariantType { variant_parts, .. } =
+            crate::strip_type_aliases(&self.root_type.summary)
+        {
+            if let Some(member) = variant_parts
+                .get(field.part_index)
+                .and_then(|part| part.variants.get(field.variant_index))
+                .and_then(|variant| variant.members.get(field.member_index))
+            {
+                if let crate::TypeInfo::StructType { members, .. } =
+                    crate::strip_type_aliases(&member.member_type)
+                {
+                    if let Some(payload) = members.get(field.payload_field_index) {
+                        return format!("::{}.{}", member.name, payload.name);
+                    }
+                }
+            }
+        }
+        format!(
+            "::variant{}.field{}",
+            field.variant_index, field.payload_field_index
+        )
+    }
+
     pub(crate) fn new(
         root_type: crate::ResolvedType,
         presentation: ValuePresentation,
@@ -61,6 +123,7 @@ impl ValueReadPlan {
             sequence_element: None,
             hash_table_fields: Vec::new(),
             nested: None,
+            diagnostics: Vec::new(),
         }
     }
 }
@@ -139,6 +202,17 @@ pub enum ValueAdapterStage {
     ReadPlanConstruction,
 }
 
+impl ValueAdapterStage {
+    pub fn diagnostic_reason(self) -> ghostscope_protocol::ValueDiagnosticReason {
+        match self {
+            Self::LayoutValidation => ghostscope_protocol::ValueDiagnosticReason::LayoutUnsupported,
+            Self::ReadPlanConstruction => {
+                ghostscope_protocol::ValueDiagnosticReason::ReadPlanUnsupported
+            }
+        }
+    }
+}
+
 /// Result of selecting and constructing a source-language value adapter.
 #[derive(Debug, Clone, PartialEq)]
 pub enum ValueAdapterOutcome {
diff --git a/ghostscope-protocol/src/format_printer.rs b/ghostscope-protocol/src/format_printer.rs
index 2a1ab7c2..9ebe7e14 100644
--- a/ghostscope-protocol/src/format_printer.rs
+++ b/ghostscope-protocol/src/format_printer.rs
@@ -541,7 +541,7 @@ impl FormatPrinter {
             if !output.is_empty() {
                 output.push(' ');
             }
-            output.push_str("<truncated>");
+            output.push_str("<truncated: capture limit>");
         }
     }
 
@@ -580,6 +580,80 @@ impl FormatPrinter {
         data: &[u8],
         status: u8,
         trace_context: &TraceContext,
+    ) -> String {
+        let mut output = Self::format_complex_variable_status_impl(
+            var_name_index,
+            type_index,
+            access_path,
+            data,
+            status,
+            trace_context,
+        );
+        if matches!(status, s if s == VariableStatus::Ok as u8 || s == VariableStatus::ZeroLength as u8 || (s == VariableStatus::Truncated as u8 && !data.is_empty()))
+        {
+            let mut nested_limits = Vec::new();
+            for note in trace_context.value_diagnostics.iter().filter(|note| {
+                note.variable_index == var_name_index && note.type_index == type_index
+            }) {
+                if note.diagnostic.path.is_empty() {
+                    output.push(' ');
+                    output.push_str(note.diagnostic.reason.marker());
+                } else if !nested_limits.contains(&note.diagnostic.reason) {
+                    nested_limits.push(note.diagnostic.reason);
+                }
+            }
+            // These are static limits, including possible enum branches. Do
+            // not claim an inactive branch failed a runtime read.
+            if !nested_limits.is_empty() {
+                let reasons = nested_limits
+                    .iter()
+                    .map(|reason| reason.short_label())
+                    .collect::<Vec<_>>()
+                    .join(", ");
+                output.push_str(&format!(
+                    " <nested display limits: {reasons}; see trace details>"
+                ));
+            }
+        }
+        output
+    }
+
+    fn truncation_marker(data: &[u8], presentation: &ValuePresentation) -> &'static str {
+        match presentation {
+            ValuePresentation::Utf8String | ValuePresentation::ByteString => {
+                "<truncated: byte limit>"
+            }
+            ValuePresentation::Nested { root, children, .. } => {
+                if let (
+                    ValuePresentation::Sequence { element_stride, .. },
+                    NestedValueChildrenPresentation::Sequence {
+                        element_limit: Some(limit),
+                        slot_count,
+                        ..
+                    },
+                ) = (root.as_ref(), children.as_ref())
+                {
+                    if let Some((original, captured, _)) =
+                        Self::parse_sequence_payload(data, *element_stride)
+                    {
+                        if original > captured && captured == *slot_count && captured == *limit {
+                            return "<truncated: element limit>";
+                        }
+                    }
+                }
+                Self::truncation_marker(data, root)
+            }
+            _ => "<truncated: capture limit>",
+        }
+    }
+
+    fn format_complex_variable_status_impl(
+        var_name_index: u16,
+        type_index: u16,
+        access_path: &str,
+        data: &[u8],
+        status: u8,
+        trace_context: &TraceContext,
     ) -> String {
         let var_name = trace_context
             .get_variable_name(var_name_index)
@@ -601,12 +675,13 @@ impl FormatPrinter {
             let payload_omitted = status == VariableStatus::Truncated as u8
                 && Self::presentation_payload_bytes(data, presentation).is_none();
             let mut formatted_data = if payload_omitted {
-                "<truncated>".to_string()
+                "<truncated: capture limit>".to_string()
             } else {
                 Self::format_data_with_presentation(data, type_info, presentation)
             };
             if status == VariableStatus::Truncated as u8 && !payload_omitted {
-                formatted_data.push_str(" <truncated>");
+                formatted_data.push(' ');
+                formatted_data.push_str(Self::truncation_marker(data, presentation));
             }
             return if access_path.is_empty() {
                 format!("{var_name} = {formatted_data}")
@@ -654,9 +729,9 @@ impl FormatPrinter {
             }
             s if s == VariableStatus::ReadError as u8 => match (errno, addr) {
                 (Some(e), Some(a)) => {
-                    format!("<read_user failed errno={e} at 0x{a:x}> ({type_suffix}*)")
+                    format!("<unreadable: memory read failed; errno={e}; address=0x{a:x}> ({type_suffix}*)")
                 }
-                _ => format!("<read_user failed> ({type_suffix}*)"),
+                _ => format!("<unreadable: memory read failed> ({type_suffix}*)"),
             },
             s if s == VariableStatus::AccessError as u8 => {
                 format!("<address compute failed> ({type_suffix}*)")
@@ -664,7 +739,9 @@ impl FormatPrinter {
             s if s == VariableStatus::OffsetsUnavailable as u8 => {
                 format!("<proc offsets unavailable> ({type_suffix}*)")
             }
-            s if s == VariableStatus::Truncated as u8 => format!("<truncated> ({type_suffix}*)"),
+            s if s == VariableStatus::Truncated as u8 => {
+                format!("<truncated: capture limit> ({type_suffix}*)")
+            }
             s if s == VariableStatus::ZeroLength as u8 => format!("<len<=0> ({type_suffix})"),
             _ => format!("<error status={status}> ({type_suffix}*)"),
         };
@@ -896,6 +973,7 @@ impl FormatPrinter {
                 slot_stride,
                 slot_count,
                 element,
+                ..
             } => {
                 let ValuePresentation::Sequence { element_stride, .. } = root else {
                     return "<INVALID_NESTED_SEQUENCE>".to_string();
@@ -998,7 +1076,8 @@ impl FormatPrinter {
         ) {
             let mut value = Self::format_data_with_presentation(data, type_info, presentation);
             if status == VariableStatus::Truncated as u8 {
-                value.push_str(" <truncated>");
+                value.push(' ');
+                value.push_str(Self::truncation_marker(data, presentation));
             }
             return value;
         }
@@ -1026,9 +1105,9 @@ impl FormatPrinter {
                             addr.try_into()
                                 .expect("nested read-error address length checked"),
                         );
-                        format!("<read_user failed errno={errno} at 0x{addr:x}> ({type_name}*)")
+                        format!("<unreadable: memory read failed; errno={errno}; address=0x{addr:x}> ({type_name}*)")
                     }
-                    _ => format!("<read_user failed> ({type_name}*)"),
+                    _ => format!("<unreadable: memory read failed> ({type_name}*)"),
                 }
             }
             s if s == VariableStatus::AccessError as u8 => {
@@ -2292,7 +2371,7 @@ impl FormatPrinter {
             TypeInfo::UnknownType { name } => {
                 format!("<UNKNOWN_TYPE_{name}_{}_BYTES>", data.len())
             }
-            TypeInfo::OptimizedOut { .. } => "<optimized out>".to_string(),
+            TypeInfo::OptimizedOut { .. } => "<unavailable: optimized out>".to_string(),
         }
     }
 
@@ -3332,7 +3411,7 @@ mod tests {
                 },
                 &presentation,
             ),
-            "HashMap(size=1) {\"alpha\" <truncated>: [3, 5, 8]}"
+            "HashMap(size=1) {\"alpha\" <truncated: byte limit>: [3, 5, 8]}"
         );
     }
 
@@ -3572,7 +3651,7 @@ mod tests {
                 &[huge_count],
                 &trace_context,
             ),
-            "34 12 <truncated>"
+            "34 12 <truncated: capture limit>"
         );
     }
 
@@ -3624,7 +3703,7 @@ mod tests {
                 VariableStatus::Truncated as u8,
                 &trace_context,
             ),
-            "set = HashSet(size=2) {5} <truncated>"
+            "set = HashSet(size=2) {5} <truncated: capture limit>"
         );
     }
 
@@ -3716,7 +3795,7 @@ mod tests {
                 VariableStatus::Truncated as u8,
                 &trace_context,
             ),
-            "set = BTreeSet(size=3) {1, 10} <truncated>"
+            "set = BTreeSet(size=3) {1, 10} <truncated: capture limit>"
         );
 
         let empty_prefix = btree_set_payload(3, 0, 2, 0, &[]);
@@ -3729,7 +3808,7 @@ mod tests {
                 VariableStatus::Truncated as u8,
                 &trace_context,
             ),
-            "set = BTreeSet(size=3) {} <truncated>"
+            "set = BTreeSet(size=3) {} <truncated: capture limit>"
         );
         assert_eq!(
             FormatPrinter::format_complex_variable_with_status(
@@ -3740,7 +3819,7 @@ mod tests {
                 VariableStatus::Truncated as u8,
                 &trace_context,
             ),
-            "set = <truncated>"
+            "set = <truncated: capture limit>"
         );
         let raw_format = trace_context.add_string("{:x}".to_string()).unwrap();
         let variable = ParsedComplexVariable {
@@ -3752,7 +3831,7 @@ mod tests {
         };
         assert_eq!(
             FormatPrinter::format_complex_print_data(raw_format, &[variable], &trace_context,),
-            "01 00 00 00 0a 00 00 00 <truncated>"
+            "01 00 00 00 0a 00 00 00 <truncated: capture limit>"
         );
         let omitted_raw = ParsedComplexVariable {
             var_name_index: name_index,
@@ -3763,7 +3842,7 @@ mod tests {
         };
         assert_eq!(
             FormatPrinter::format_complex_print_data(raw_format, &[omitted_raw], &trace_context,),
-            "<truncated>"
+            "<truncated: capture limit>"
         );
 
         let mut malformed = data;
@@ -4095,7 +4174,7 @@ mod tests {
                 &trace_context,
             ),
             "cell = RefCell(borrow=<unavailable>) { value: 17, borrow: <OUT_OF_BOUNDS> } \
-             <truncated>"
+             <truncated: capture limit>"
         );
     }
 
@@ -4116,7 +4195,7 @@ mod tests {
                 VariableStatus::Truncated as u8,
                 &trace_context,
             ),
-            "path = \"a\\xff\" <truncated>"
+            "path = \"a\\xff\" <truncated: byte limit>"
         );
     }
 
@@ -4222,7 +4301,7 @@ mod tests {
                 &[variable.clone(), variable],
                 &trace_context,
             ),
-            "abc <truncated>|61 62 63 <truncated>"
+            "abc <truncated: capture limit>|61 62 63 <truncated: capture limit>"
         );
     }
 
@@ -4254,7 +4333,7 @@ mod tests {
         );
 
         assert_eq!(empty, "message = \"\"");
-        assert_eq!(truncated, "message = \"abc\" <truncated>");
+        assert_eq!(truncated, "message = \"abc\" <truncated: byte limit>");
     }
 
     #[test]
@@ -4283,7 +4362,7 @@ mod tests {
                 VariableStatus::ReadError as u8,
                 &trace_context,
             ),
-            "message = <read_user failed errno=-14 at 0x1234> (struct &str*)"
+            "message = <unreadable: memory read failed; errno=-14; address=0x1234> (struct &str*)"
         );
     }
 
@@ -4540,7 +4619,7 @@ mod tests {
                 &[truncated.clone(), truncated],
                 &trace_context,
             ),
-            "nested!! <truncated>|6e 65 73 74 65 64 21 21 <truncated>"
+            "nested!! <truncated: capture limit>|6e 65 73 74 65 64 21 21 <truncated: capture limit>"
         );
 
         let mut error_payload = vec![0; VARIABLE_READ_ERROR_PAYLOAD_LEN];
@@ -4570,8 +4649,8 @@ mod tests {
                 &trace_context,
             ),
             concat!(
-                "<read_user failed errno=-14 at 0x1234> (struct String*)|",
-                "<read_user failed errno=-14 at 0x1234> (struct String*)"
+                "<unreadable: memory read failed; errno=-14; address=0x1234> (struct String*)|",
+                "<unreadable: memory read failed; errno=-14; address=0x1234> (struct String*)"
             )
         );
     }
@@ -4607,6 +4686,7 @@ mod tests {
                 first_slot_offset: root_payload_len as u64,
                 slot_stride: child_slot_len as u64,
                 slot_count: 2,
+                element_limit: None,
                 element: Box::new(NestedValuePresentation {
                     payload_len: child_payload_len as u64,
                     type_info: Box::new(string_type.clone()),
@@ -4617,7 +4697,7 @@ mod tests {
 
         assert_eq!(
             FormatPrinter::format_data_with_presentation(&data, &string_type, &presentation),
-            r#"["alpha", "betatron" <truncated>]"#
+            r#"["alpha", "betatron" <truncated: byte limit>]"#
         );
     }
 
@@ -4689,7 +4769,7 @@ mod tests {
         );
 
         assert_eq!(empty, "values = []");
-        assert_eq!(truncated, "values = [10, 20] <truncated>");
+        assert_eq!(truncated, "values = [10, 20] <truncated: capture limit>");
         assert_eq!(zst, "values = [(), (), ()]");
     }
 
@@ -4752,7 +4832,7 @@ mod tests {
                 VariableStatus::Truncated as u8,
                 &trace_context,
             ),
-            "values = <truncated>"
+            "values = <truncated: capture limit>"
         );
     }
 
@@ -5048,7 +5128,7 @@ mod tests {
 
         let out = FormatPrinter::format_complex_print_data(fmt_idx, &vars, &trace_context);
         assert!(
-            out.contains("read_user failed errno=-14"),
+            out.contains("memory read failed; errno=-14"),
             "unexpected: {out}"
         );
         assert!(out.contains("0x123456789abcdef0"), "missing addr: {out}");
diff --git a/ghostscope-protocol/src/lib.rs b/ghostscope-protocol/src/lib.rs
index 337bea43..adadaac4 100644
--- a/ghostscope-protocol/src/lib.rs
+++ b/ghostscope-protocol/src/lib.rs
@@ -6,8 +6,11 @@
 pub mod bpf_abi;
 mod format_template;
 mod type_kind;
+mod value_diagnostic;
 mod value_presentation;
 
+pub use value_diagnostic::{TraceValueDiagnostic, ValueDiagnostic, ValueDiagnosticReason};
+
 pub mod format_printer;
 pub mod streaming_parser;
 pub mod trace_context;
diff --git a/ghostscope-protocol/src/trace_context.rs b/ghostscope-protocol/src/trace_context.rs
index 03236d16..20a00e60 100644
--- a/ghostscope-protocol/src/trace_context.rs
+++ b/ghostscope-protocol/src/trace_context.rs
@@ -82,9 +82,39 @@ pub struct TraceContext {
 
     /// Variable names for debugging and display
     pub variable_names: Vec<String>,
+    /// Compile-time display limits, retained even when logging is disabled.
+    #[serde(default)]
+    pub value_diagnostics: Vec<crate::TraceValueDiagnostic>,
 }
 
 impl TraceContext {
+    pub fn add_value_diagnostic(&mut self, note: crate::TraceValueDiagnostic) {
+        if !self.value_diagnostics.contains(&note) {
+            self.value_diagnostics.push(note);
+        }
+    }
+
+    pub fn resolved_value_diagnostics(&self) -> Vec<crate::ValueDiagnostic> {
+        let mut diagnostics = Vec::new();
+        for note in &self.value_diagnostics {
+            let note = note.diagnostic.clone().prefixed(
+                self.get_variable_name(note.variable_index)
+                    .unwrap_or("<value>"),
+            );
+            if !diagnostics.contains(&note) {
+                diagnostics.push(note);
+            }
+        }
+        diagnostics
+    }
+
+    pub fn value_diagnostic_messages(&self) -> Vec<String> {
+        self.resolved_value_diagnostics()
+            .iter()
+            .map(|note| note.message(""))
+            .collect()
+    }
+
     /// Create a new empty trace context
     pub fn new() -> Self {
         Self {
@@ -92,6 +122,7 @@ impl TraceContext {
             types: Vec::new(),
             value_presentations: Vec::new(),
             variable_names: Vec::new(),
+            value_diagnostics: Vec::new(),
         }
     }
 
@@ -206,6 +237,7 @@ impl TraceContext {
         self.types.clear();
         self.value_presentations.clear();
         self.variable_names.clear();
+        self.value_diagnostics.clear();
     }
 
     /// Get total memory usage estimate in bytes
@@ -217,7 +249,17 @@ impl TraceContext {
         // (this is a rough estimate since TypeInfo can vary significantly in size)
         let types_size = self.types.len() * 100;
 
-        strings_size + variable_names_size + types_size
+        let diagnostic_size: usize = self
+            .value_diagnostics
+            .iter()
+            .map(|note| {
+                std::mem::size_of_val(note)
+                    + note.diagnostic.path.len()
+                    + note.diagnostic.type_name.len()
+                    + note.diagnostic.detail.len()
+            })
+            .sum();
+        strings_size + variable_names_size + types_size + diagnostic_size
     }
 }
 
@@ -594,3 +636,71 @@ mod tests {
         assert_eq!(err.attempted_index(), usize::from(u16::MAX) + 1);
     }
 }
+
+#[cfg(test)]
+mod diagnostic_tests {
+    use super::*;
+    use crate::format_printer::FormatPrinter;
+    use crate::{TraceValueDiagnostic, ValueDiagnostic, ValueDiagnosticReason, VariableStatus};
+
+    #[test]
+    fn display_notes_survive_serialization_and_do_not_hide_runtime_errors() {
+        let mut context = TraceContext::new();
+        let variable = context.add_variable_name("value".to_string()).unwrap();
+        let type_index = context
+            .add_type(TypeInfo::BaseType {
+                name: "u64".to_string(),
+                size: 8,
+                encoding: gimli::DW_ATE_unsigned.0 as u16,
+            })
+            .unwrap();
+        let note = TraceValueDiagnostic {
+            variable_index: variable,
+            type_index,
+            diagnostic: ValueDiagnostic {
+                path: String::new(),
+                type_name: "Example".to_string(),
+                reason: ValueDiagnosticReason::LayoutUnsupported,
+                detail: "unrecognized field layout".to_string(),
+            },
+        };
+        context.add_value_diagnostic(note.clone());
+        context.add_value_diagnostic(note);
+        let context: TraceContext =
+            serde_json::from_str(&serde_json::to_string(&context).unwrap()).unwrap();
+        assert_eq!(context.value_diagnostics.len(), 1);
+        let mut multiple = context.clone();
+        let second_type = multiple
+            .add_type(multiple.get_type(type_index).unwrap().clone())
+            .unwrap();
+        let mut second_note = multiple.value_diagnostics[0].clone();
+        second_note.type_index = second_type;
+        multiple.add_value_diagnostic(second_note);
+        assert_eq!(multiple.resolved_value_diagnostics().len(), 1);
+        assert_eq!(multiple.value_diagnostic_messages().len(), 1);
+        multiple.clear();
+        assert!(multiple.value_diagnostics.is_empty());
+        assert!(multiple.resolved_value_diagnostics().is_empty());
+        let rendered = FormatPrinter::format_complex_variable_with_status(
+            variable,
+            type_index,
+            "",
+            &42_u64.to_le_bytes(),
+            VariableStatus::Ok as u8,
+            &context,
+        );
+        assert_eq!(rendered, "value = 42 <internal fields: layout unsupported>");
+        let failed = FormatPrinter::format_complex_variable_with_status(
+            variable,
+            type_index,
+            "",
+            &[],
+            VariableStatus::ReadError as u8,
+            &context,
+        );
+        assert!(failed.contains("<unreadable: memory read failed>"));
+        assert!(!failed.contains("internal fields"));
+        assert!(context.value_diagnostic_messages()[0]
+            .contains("docs/value-diagnostics.md#layout-unsupported"));
+    }
+}
diff --git a/ghostscope-protocol/src/value_diagnostic.rs b/ghostscope-protocol/src/value_diagnostic.rs
new file mode 100644
index 00000000..b5c24cfe
--- /dev/null
+++ b/ghostscope-protocol/src/value_diagnostic.rs
@@ -0,0 +1,98 @@
+//! Static explanations of value display limits, independent of logging.
+//! They do not assert that a probe ran or a conditional branch was active.
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ValueDiagnosticReason {
+    LayoutUnsupported,
+    ReadPlanUnsupported,
+    DepthLimit,
+    RecursiveType,
+    CaptureBudget,
+}
+
+impl ValueDiagnosticReason {
+    pub fn code(self) -> &'static str {
+        match self {
+            Self::LayoutUnsupported => "layout-unsupported",
+            Self::ReadPlanUnsupported => "read-plan-unsupported",
+            Self::DepthLimit => "depth-limit",
+            Self::RecursiveType => "recursive-type",
+            Self::CaptureBudget => "capture-budget",
+        }
+    }
+
+    pub fn summary(self) -> &'static str {
+        match self {
+            Self::LayoutUnsupported => {
+                "contents unavailable: unsupported memory layout; showing internal fields"
+            }
+            Self::ReadPlanUnsupported => {
+                "contents unavailable: unsupported debug information; showing internal fields"
+            }
+            Self::DepthLimit => "nested contents not expanded: depth limit",
+            Self::RecursiveType => "nested contents not expanded: recursive type",
+            Self::CaptureBudget => "nested contents not expanded: capture budget",
+        }
+    }
+
+    pub fn short_label(self) -> &'static str {
+        match self {
+            Self::LayoutUnsupported => "layout unsupported",
+            Self::ReadPlanUnsupported => "read plan unsupported",
+            Self::DepthLimit => "depth limit",
+            Self::RecursiveType => "recursive type",
+            Self::CaptureBudget => "capture budget",
+        }
+    }
+
+    pub fn marker(self) -> &'static str {
+        match self {
+            Self::LayoutUnsupported => "<internal fields: layout unsupported>",
+            Self::ReadPlanUnsupported => "<internal fields: read plan unsupported>",
+            Self::DepthLimit => "<not expanded: depth limit>",
+            Self::RecursiveType => "<not expanded: recursive type>",
+            Self::CaptureBudget => "<not expanded: capture budget>",
+        }
+    }
+}
+
+/// Paths are relative to the printed expression. `[]` describes elements;
+/// variant-qualified paths describe a possible branch, not a runtime failure.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ValueDiagnostic {
+    pub path: String,
+    pub type_name: String,
+    pub reason: ValueDiagnosticReason,
+    pub detail: String,
+}
+
+impl ValueDiagnostic {
+    pub fn prefixed(mut self, path: &str) -> Self {
+        self.path.insert_str(0, path);
+        self
+    }
+
+    pub fn message(&self, expression: &str) -> String {
+        format!(
+            "{}{}: {} [{}]\n  Type: {}\n  Detail: {}\n  Help: docs/value-diagnostics.md#{} (offline: ghostscope --value-diagnostics-help)",
+            expression,
+            self.path,
+            self.reason.summary(),
+            self.reason.code(),
+            self.type_name,
+            self.detail,
+            self.reason.code(),
+        )
+    }
+}
+
+/// One expression/type pair in a compiled trace. Type indices distinguish
+/// semantic printing from explicit memory formats of the same expression.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct TraceValueDiagnostic {
+    pub variable_index: u16,
+    pub type_index: u16,
+    pub diagnostic: ValueDiagnostic,
+}
diff --git a/ghostscope-protocol/src/value_presentation.rs b/ghostscope-protocol/src/value_presentation.rs
index e065b7a2..1cead3a6 100644
--- a/ghostscope-protocol/src/value_presentation.rs
+++ b/ghostscope-protocol/src/value_presentation.rs
@@ -182,6 +182,9 @@ pub enum NestedValueChildrenPresentation {
         first_slot_offset: u64,
         slot_stride: u64,
         slot_count: u64,
+        /// Configured width, distinct from slots reduced by the byte budget.
+        #[serde(default)]
+        element_limit: Option<u64>,
         element: Box<NestedValuePresentation>,
     },
     HashTable {
diff --git a/ghostscope-ui/src/components/app/runtime_status.rs b/ghostscope-ui/src/components/app/runtime_status.rs
index 27b190a5..25a7b682 100644
--- a/ghostscope-ui/src/components/app/runtime_status.rs
+++ b/ghostscope-ui/src/components/app/runtime_status.rs
@@ -629,6 +629,7 @@ impl App {
                 binary,
                 script_preview,
                 pc,
+                value_diagnostics,
             } => {
                 self.clear_waiting_state();
 
@@ -695,6 +696,12 @@ impl App {
                 if let Some(ref preview) = script_preview {
                     response.push_str(&format!("  Script:\n{preview}\n"));
                 }
+                for note in &value_diagnostics {
+                    response.push_str(&format!("  Display note: {}\n", note.message("")));
+                }
+                response.push_str(
+                    "  Value status help: ghostscope --value-diagnostics-help (docs/value-diagnostics.md)\n",
+                );
                 // Also create styled version
                 let styled_lines = {
                     let temp = crate::events::RuntimeStatus::TraceInfo {
@@ -706,6 +713,7 @@ impl App {
                         binary: binary.clone(),
                         script_preview: None,
                         pc,
+                        value_diagnostics: value_diagnostics.clone(),
                     };
                     if let Some(mut base) = temp.format_trace_info_styled() {
                         if let Some(ref preview) = script_preview {
@@ -1130,6 +1138,11 @@ impl App {
                     }
                 }
 
+                for detail in &details {
+                    for message in detail.value_diagnostic_messages() {
+                        response.push_str(&format!("  {message}\n"));
+                    }
+                }
                 // Styled version
                 let mut styled = Vec::new();
                 use crate::components::command_panel::style_builder::{
@@ -1208,6 +1221,13 @@ impl App {
                     }
                 }
 
+                for detail in &details {
+                    for message in detail.value_diagnostic_messages() {
+                        for line in message.lines() {
+                            styled.push(ratatui::text::Line::from(format!("  {line}")));
+                        }
+                    }
+                }
                 let action = Action::AddResponseWithStyle {
                     content: response,
                     styled_lines: Some(styled),
diff --git a/ghostscope-ui/src/components/command_panel/response_formatter.rs b/ghostscope-ui/src/components/command_panel/response_formatter.rs
index 862e09c6..6f157d68 100644
--- a/ghostscope-ui/src/components/command_panel/response_formatter.rs
+++ b/ghostscope-ui/src/components/command_panel/response_formatter.rs
@@ -340,6 +340,11 @@ impl ResponseFormatter {
                     }
                     _ => {}
                 }
+                for note in &detail.value_diagnostics {
+                    for line in note.message("").lines() {
+                        lines.push(ratatui::text::Line::from(format!("    {line}")));
+                    }
+                }
             }
         }
 
diff --git a/ghostscope-ui/src/components/command_panel/script_editor.rs b/ghostscope-ui/src/components/command_panel/script_editor.rs
index 61c1698e..77c8d526 100644
--- a/ghostscope-ui/src/components/command_panel/script_editor.rs
+++ b/ghostscope-ui/src/components/command_panel/script_editor.rs
@@ -818,6 +818,9 @@ impl ScriptEditor {
                     ));
                 }
             }
+            for note in &exec_result.value_diagnostics {
+                result.push(format!("  Display note: {}", note.message("")));
+            }
         }
 
         result.join("\n")
diff --git a/ghostscope-ui/src/events/runtime.rs b/ghostscope-ui/src/events/runtime.rs
index 66fdeba3..816a4d22 100644
--- a/ghostscope-ui/src/events/runtime.rs
+++ b/ghostscope-ui/src/events/runtime.rs
@@ -116,6 +116,20 @@ pub struct TraceLoadDetail {
     pub trace_id: Option<u32>,
     pub status: LoadStatus,
     pub error: Option<String>,
+    pub value_diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
+}
+
+impl TraceLoadDetail {
+    pub fn value_diagnostic_messages(&self) -> Vec<String> {
+        let target = match self.trace_id {
+            Some(id) => format!("trace #{id} ({})", self.target),
+            None => self.target.clone(),
+        };
+        self.value_diagnostics
+            .iter()
+            .map(|note| format!("Display note · {target}: {}", note.message("")))
+            .collect()
+    }
 }
 
 /// Status of loading a trace
@@ -145,6 +159,7 @@ pub struct ScriptExecutionResult {
     pub source_file: Option<String>,
     pub source_line: Option<u32>,
     pub is_inline: Option<bool>,
+    pub value_diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
 }
 
 /// Detailed compilation result for a script with multiple targets
@@ -246,6 +261,7 @@ pub enum RuntimeStatus {
         binary: String,
         script_preview: Option<String>,
         pc: u64,
+        value_diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
     },
     /// All trace info with structured data for UI rendering
     TraceInfoAll {
@@ -433,6 +449,7 @@ impl RuntimeStatus {
                 binary,
                 script_preview,
                 pc,
+                value_diagnostics,
             } => {
                 // Header line
                 let mut result =
@@ -475,6 +492,12 @@ impl RuntimeStatus {
                     result.push_str(&format!("  {key}{spaces}: {value}\n"));
                 }
 
+                for note in value_diagnostics {
+                    result.push_str(&format!("  Display note: {}\n", note.message("")));
+                }
+                result.push_str(
+                    "  Value status help: ghostscope --value-diagnostics-help (docs/value-diagnostics.md)\n",
+                );
                 Some(result)
             }
             _ => None,
@@ -496,6 +519,7 @@ impl RuntimeStatus {
                 binary,
                 script_preview: _,
                 pc,
+                value_diagnostics,
             } => {
                 let mut lines = Vec::new();
 
@@ -584,6 +608,14 @@ impl RuntimeStatus {
                     (None, None) => {}
                 }
 
+                for note in value_diagnostics {
+                    for line in note.message("").lines() {
+                        lines.push(Line::from(format!("  {line}")));
+                    }
+                }
+                lines.push(Line::from(
+                    "  Value status help: ghostscope --value-diagnostics-help (docs/value-diagnostics.md)",
+                ));
                 Some(lines)
             }
             RuntimeStatus::TraceInfoAll { summary, traces } => {
diff --git a/ghostscope-ui/src/model/panel_state.rs b/ghostscope-ui/src/model/panel_state.rs
index e48cfb53..3fe65d4d 100644
--- a/ghostscope-ui/src/model/panel_state.rs
+++ b/ghostscope-ui/src/model/panel_state.rs
@@ -488,6 +488,7 @@ impl BatchLoadingState {
                         trace_id,
                         status,
                         error: None,
+                        value_diagnostics: result.value_diagnostics.clone(),
                     });
                 }
                 crate::events::ExecutionStatus::Failed(error) => {
@@ -496,6 +497,7 @@ impl BatchLoadingState {
                         trace_id: None,
                         status: crate::events::LoadStatus::Failed,
                         error: Some(error.clone()),
+                        value_diagnostics: result.value_diagnostics.clone(),
                     });
                 }
                 crate::events::ExecutionStatus::Skipped(_) => {}
@@ -1407,6 +1409,7 @@ mod tests {
                 source_file: None,
                 source_line: None,
                 is_inline: None,
+                value_diagnostics: Vec::new(),
             }],
             total_count: 1,
             success_count: 1,
@@ -1425,6 +1428,7 @@ mod tests {
                 source_file: None,
                 source_line: None,
                 is_inline: None,
+                value_diagnostics: Vec::new(),
             }],
             total_count: 1,
             success_count: 0,
diff --git a/ghostscope-ui/tests/ansi_color_test.rs b/ghostscope-ui/tests/ansi_color_test.rs
index 0e100125..17d4f10b 100644
--- a/ghostscope-ui/tests/ansi_color_test.rs
+++ b/ghostscope-ui/tests/ansi_color_test.rs
@@ -19,6 +19,7 @@ fn test_trace_results_success_color() {
             source_file: None,
             source_line: None,
             is_inline: None,
+            value_diagnostics: Vec::new(),
         }],
         trace_ids: vec![0],
     };
@@ -65,6 +66,7 @@ fn test_trace_results_failed_color() {
             source_file: None,
             source_line: None,
             is_inline: None,
+            value_diagnostics: Vec::new(),
         }],
         trace_ids: vec![],
     };
@@ -112,6 +114,7 @@ fn test_trace_results_mixed_colors() {
                 source_file: None,
                 source_line: None,
                 is_inline: None,
+                value_diagnostics: Vec::new(),
             },
             ScriptExecutionResult {
                 target_name: "test.c:20".to_string(),
@@ -121,6 +124,7 @@ fn test_trace_results_mixed_colors() {
                 source_file: None,
                 source_line: None,
                 is_inline: None,
+                value_diagnostics: Vec::new(),
             },
             ScriptExecutionResult {
                 target_name: "test.c:30".to_string(),
@@ -130,6 +134,7 @@ fn test_trace_results_mixed_colors() {
                 source_file: None,
                 source_line: None,
                 is_inline: None,
+                value_diagnostics: Vec::new(),
             },
         ],
         trace_ids: vec![0, 1],
@@ -175,6 +180,7 @@ fn test_trace_results_preserve_multiline_failure_diagnostics() {
             source_file: None,
             source_line: None,
             is_inline: None,
+            value_diagnostics: Vec::new(),
         }],
         trace_ids: vec![],
     };
@@ -190,3 +196,74 @@ fn test_trace_results_preserve_multiline_failure_diagnostics() {
         "multiline diagnostic was lost: {result}"
     );
 }
+
+#[test]
+fn display_limits_remain_successful_and_are_visible_in_trace_details() {
+    let note = ghostscope_protocol::ValueDiagnostic {
+        path: "request.name".to_string(),
+        type_name: "String".to_string(),
+        reason: ghostscope_protocol::ValueDiagnosticReason::LayoutUnsupported,
+        detail: "missing pointer and length".to_string(),
+    };
+    let details = ScriptCompilationDetails {
+        trace_ids: vec![3],
+        total_count: 1,
+        success_count: 1,
+        failed_count: 0,
+        results: vec![ScriptExecutionResult {
+            target_name: "handle_request".to_string(),
+            binary_path: "/app".to_string(),
+            pc_address: 0x1234,
+            status: ExecutionStatus::Success,
+            source_file: None,
+            source_line: None,
+            is_inline: None,
+            value_diagnostics: vec![note.clone()],
+        }],
+    };
+    let output = ScriptEditor::format_compilation_results(&details, None, &EmojiConfig::new(false));
+    assert!(output.contains("1 successful"));
+    assert!(output.contains("request.name: contents unavailable"));
+    assert!(output.contains("docs/value-diagnostics.md#layout-unsupported"));
+    let loaded = ghostscope_ui::events::TraceLoadDetail {
+        target: "handle_request".to_string(),
+        trace_id: Some(3),
+        status: ghostscope_ui::events::LoadStatus::Created,
+        error: None,
+        value_diagnostics: vec![note.clone()],
+    };
+    assert!(loaded.value_diagnostic_messages()[0]
+        .contains("trace #3 (handle_request): request.name: contents unavailable"));
+    let batch = ghostscope_ui::components::command_panel::ResponseFormatter::format_batch_load_summary_styled(
+        "traces.gs", 1, 1, 0, 0, &[loaded],
+    )
+    .iter()
+    .map(|line| line.to_string())
+    .collect::<Vec<_>>()
+    .join("\n");
+    assert!(batch.find("trace #3").unwrap() < batch.find("request.name").unwrap());
+    let status = ghostscope_ui::events::RuntimeStatus::TraceInfo {
+        trace_id: 3,
+        target: "handle_request".to_string(),
+        status: ghostscope_ui::events::TraceStatus::Active,
+        pid: Some(1),
+        host_pid: None,
+        binary: "/app".to_string(),
+        script_preview: None,
+        pc: 0x1234,
+        value_diagnostics: vec![note],
+    };
+    let plain = status.format_trace_info().unwrap();
+    let styled = status
+        .format_trace_info_styled()
+        .unwrap()
+        .iter()
+        .map(|line| line.to_string())
+        .collect::<Vec<_>>()
+        .join("\n");
+    for output in [plain, styled] {
+        assert!(output.contains("request.name: contents unavailable"));
+        assert!(output.contains("missing pointer and length"));
+        assert!(output.contains("docs/value-diagnostics.md#layout-unsupported"));
+    }
+}
diff --git a/ghostscope/src/cli/docs.rs b/ghostscope/src/cli/docs.rs
index 94a5638e..7b39c2f9 100644
--- a/ghostscope/src/cli/docs.rs
+++ b/ghostscope/src/cli/docs.rs
@@ -1,5 +1,10 @@
 pub const SCRIPT_HELP: &str = include_str!("scripting.md");
+pub const VALUE_DIAGNOSTICS_HELP: &str = include_str!("value-diagnostics.md");
 
 pub fn print_script_help() {
     print!("{SCRIPT_HELP}");
 }
+
+pub fn print_value_diagnostics_help() {
+    print!("{VALUE_DIAGNOSTICS_HELP}");
+}
diff --git a/ghostscope/src/cli/mod.rs b/ghostscope/src/cli/mod.rs
index 0e09cadd..9176a3c5 100644
--- a/ghostscope/src/cli/mod.rs
+++ b/ghostscope/src/cli/mod.rs
@@ -193,5 +193,5 @@ fn print_human_report(args: &BpffsPruneArgs, report: &BpffsPruneReport) {
 }
 
 // Re-export main functions for convenience
-pub use docs::print_script_help;
+pub use docs::{print_script_help, print_value_diagnostics_help};
 pub use script_runtime::run_command_line_runtime_with_config;
diff --git a/ghostscope/src/cli/value-diagnostics.md b/ghostscope/src/cli/value-diagnostics.md
new file mode 120000
index 00000000..f6bf2673
--- /dev/null
+++ b/ghostscope/src/cli/value-diagnostics.md
@@ -0,0 +1 @@
+../../../docs/value-diagnostics.md
\ No newline at end of file
diff --git a/ghostscope/src/config/args.rs b/ghostscope/src/config/args.rs
index aa9f5501..118fbdba 100644
--- a/ghostscope/src/config/args.rs
+++ b/ghostscope/src/config/args.rs
@@ -39,6 +39,7 @@ pub enum ParsedCommand {
     Trace(Box<ParsedArgs>),
     Bpffs(BpffsCommand),
     ScriptHelp,
+    ValueDiagnosticsHelp,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -229,6 +230,10 @@ pub struct Args {
     #[arg(long, action = clap::ArgAction::SetTrue)]
     pub script_help: bool,
 
+    /// Print the embedded guide to value failures, display fallbacks, and capture limits and exit
+    #[arg(long, action = clap::ArgAction::SetTrue, conflicts_with = "script_help")]
+    pub value_diagnostics_help: bool,
+
     /// Start in TUI mode (default behavior when no script provided)
     #[arg(long, action = clap::ArgAction::SetTrue)]
     pub tui: bool,
@@ -407,10 +412,10 @@ impl Args {
     fn parse_args_from(args: Vec<String>) -> ParsedCommand {
         let bpffs_prune_invocation = Self::is_bpffs_prune_invocation(&args);
         let args_pos = args.iter().position(|arg| arg == "--args");
-        let script_help_invocation = Self::is_script_help_invocation(&args, args_pos);
-
-        if script_help_invocation {
-            return Self::try_parse_dispatch(&args).unwrap_or_else(|e| e.exit());
+        if Self::is_reference_help_invocation(&args, args_pos) {
+            // Documentation requests do not inspect the target's arguments.
+            return Self::try_parse_dispatch(&args[..args_pos.unwrap_or(args.len())])
+                .unwrap_or_else(|e| e.exit());
         }
 
         if let Some(args_pos) = args_pos {
@@ -446,10 +451,10 @@ impl Args {
         )
     }
 
-    fn is_script_help_invocation(args: &[String], args_pos: Option<usize>) -> bool {
+    fn is_reference_help_invocation(args: &[String], args_pos: Option<usize>) -> bool {
         args[..args_pos.unwrap_or(args.len())]
             .iter()
-            .any(|arg| arg == "--script-help")
+            .any(|arg| matches!(arg.as_str(), "--script-help" | "--value-diagnostics-help"))
     }
 
     fn parse_trace_args(args: Vec<String>) -> ParsedArgs {
@@ -492,6 +497,13 @@ impl Args {
     fn try_parse_dispatch(args: &[String]) -> std::result::Result<ParsedCommand, clap::Error> {
         let matches = Self::command_with_bpffs().try_get_matches_from(args.iter().cloned())?;
 
+        if matches.get_flag("script_help") {
+            return Ok(ParsedCommand::ScriptHelp);
+        }
+        if matches.get_flag("value_diagnostics_help") {
+            return Ok(ParsedCommand::ValueDiagnosticsHelp);
+        }
+
         if let Some(("bpffs", sub_matches)) = matches.subcommand() {
             let bpffs = BpffsArgs::from_arg_matches(sub_matches)?;
             return Ok(ParsedCommand::Bpffs(match bpffs.command {
@@ -500,9 +512,6 @@ impl Args {
         }
 
         let parsed = Args::from_arg_matches(&matches)?;
-        if parsed.script_help {
-            return Ok(ParsedCommand::ScriptHelp);
-        }
         let binary_path = parsed.binary.clone();
         let binary_args = parsed.remaining.clone();
         Ok(ParsedCommand::Trace(Box::new(
@@ -800,6 +809,7 @@ mod tests {
         let help = Args::command_with_bpffs().render_long_help().to_string();
         assert!(help.contains("bpffs"));
         assert!(help.contains("--script-help"));
+        assert!(help.contains("--value-diagnostics-help"));
         assert!(help.contains("--args"));
     }
 
@@ -857,15 +867,68 @@ mod tests {
     }
 
     #[test]
-    fn ignores_script_help_after_args_for_detection() {
-        let args = vec![
+    fn reference_help_respects_target_argument_boundary() {
+        for flag in ["--script-help", "--value-diagnostics-help"] {
+            let args = vec![
+                "ghostscope".to_string(),
+                "--args".to_string(),
+                "demo-program".to_string(),
+                flag.to_string(),
+            ];
+            assert!(!Args::is_reference_help_invocation(&args, Some(1)));
+            let ParsedCommand::Trace(parsed) = Args::parse_args_from(args) else {
+                panic!("target help flag must remain a target argument");
+            };
+            assert_eq!(parsed.binary_args, vec![flag]);
+
+            let parsed = Args::parse_args_from(vec![
+                "ghostscope".to_string(),
+                flag.to_string(),
+                "--args".to_string(),
+                "demo-program".to_string(),
+                "--target-only-flag".to_string(),
+            ]);
+            assert!(matches!(
+                (flag, parsed),
+                ("--script-help", ParsedCommand::ScriptHelp)
+                    | (
+                        "--value-diagnostics-help",
+                        ParsedCommand::ValueDiagnosticsHelp
+                    )
+            ));
+        }
+    }
+
+    #[test]
+    fn value_diagnostics_help_bypasses_trace_and_maintenance_actions() {
+        for args in [
+            vec!["ghostscope", "--value-diagnostics-help"],
+            vec![
+                "ghostscope",
+                "--value-diagnostics-help",
+                "--config",
+                "/missing/config.toml",
+            ],
+            vec![
+                "ghostscope",
+                "--value-diagnostics-help",
+                "bpffs",
+                "prune",
+                "--all",
+            ],
+        ] {
+            assert!(matches!(
+                Args::try_parse_dispatch(&args.into_iter().map(String::from).collect::<Vec<_>>()),
+                Ok(ParsedCommand::ValueDiagnosticsHelp)
+            ));
+        }
+        let error = Args::try_parse_dispatch(&[
             "ghostscope".to_string(),
-            "--args".to_string(),
-            "demo-program".to_string(),
             "--script-help".to_string(),
-        ];
-
-        assert!(!Args::is_script_help_invocation(&args, Some(1)));
+            "--value-diagnostics-help".to_string(),
+        ])
+        .unwrap_err();
+        assert_eq!(error.kind(), clap::error::ErrorKind::ArgumentConflict);
     }
 
     #[test]
diff --git a/ghostscope/src/main.rs b/ghostscope/src/main.rs
index a76f066e..4724e258 100644
--- a/ghostscope/src/main.rs
+++ b/ghostscope/src/main.rs
@@ -26,6 +26,10 @@ async fn main() -> Result<()> {
             cli::print_script_help();
             return Ok(());
         }
+        config::ParsedCommand::ValueDiagnosticsHelp => {
+            cli::print_value_diagnostics_help();
+            return Ok(());
+        }
     };
 
     // Load and merge configuration
diff --git a/ghostscope/src/script/attach.rs b/ghostscope/src/script/attach.rs
index 5debaaaa..d414e0a4 100644
--- a/ghostscope/src/script/attach.rs
+++ b/ghostscope/src/script/attach.rs
@@ -312,6 +312,7 @@ pub(super) async fn register_attached_trace(
                     config.assigned_trace_id
                 ),
                 address_global_index: config.resolved_address_index,
+                value_diagnostics: config.trace_context.resolved_value_diagnostics(),
             });
 
     if let Err(e) = session
diff --git a/ghostscope/src/script/cli.rs b/ghostscope/src/script/cli.rs
index 840b7335..ee50edd6 100644
--- a/ghostscope/src/script/cli.rs
+++ b/ghostscope/src/script/cli.rs
@@ -23,9 +23,7 @@ pub fn compile_script_for_cli(
         Err(SessionCompileError::Compile(e)) => {
             let friendly = e.user_message().into_owned();
             error!("Script compilation failed: {}", friendly);
-            return Err(anyhow::anyhow!(
-                "Script compilation failed: {friendly}. Please check your script syntax and try again."
-            ));
+            return Err(anyhow::anyhow!("Script compilation failed: {friendly}"));
         }
         Err(SessionCompileError::Setup(e)) => return Err(e),
     };
@@ -62,6 +60,15 @@ pub fn compile_script_for_cli(
         }
     }
 
+    for config in &compilation_result.uprobe_configs {
+        for message in config.trace_context.value_diagnostic_messages() {
+            eprintln!(
+                "Display note · trace {} at 0x{:x}: {message}",
+                config.assigned_trace_id,
+                config.function_address.unwrap_or(0)
+            );
+        }
+    }
     Ok(compilation_result)
 }
 
diff --git a/ghostscope/src/script/tui.rs b/ghostscope/src/script/tui.rs
index 232cb794..9d8b3cbd 100644
--- a/ghostscope/src/script/tui.rs
+++ b/ghostscope/src/script/tui.rs
@@ -122,6 +122,7 @@ fn compilation_failed_details(binary_path: String, friendly: String) -> ScriptCo
             source_file: None,
             source_line: None,
             is_inline: None,
+            value_diagnostics: Vec::new(),
         }],
         total_count: 1,
         success_count: 0,
@@ -169,6 +170,7 @@ fn build_tui_results(
             source_file,
             source_line,
             is_inline,
+            value_diagnostics: config.trace_context.resolved_value_diagnostics(),
         });
         success_count += 1;
     }
@@ -182,6 +184,7 @@ fn build_tui_results(
             source_file: None,
             source_line: None,
             is_inline: None,
+            value_diagnostics: Vec::new(),
         });
         failed_count += 1;
     }
diff --git a/ghostscope/src/trace/instance.rs b/ghostscope/src/trace/instance.rs
index 496f38e0..0d9dec49 100644
--- a/ghostscope/src/trace/instance.rs
+++ b/ghostscope/src/trace/instance.rs
@@ -32,7 +32,8 @@ pub(super) struct TraceInstance {
     pub(super) actor: Option<TraceActorHandle>, // Owns the eBPF loader for this trace
     pub supports_backtrace_runtime_updates: bool,
     pub ebpf_function_name: String, // eBPF function name for uprobe attachment
-    pub address_global_index: Option<usize>, // Global 1-based index of the resolved address
+    pub address_global_index: Option<usize>,
+    pub value_diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>, // Global 1-based index of the resolved address
 }
 
 pub(super) struct TraceInstanceArgs {
@@ -47,6 +48,7 @@ pub(super) struct TraceInstanceArgs {
     pub supports_backtrace_runtime_updates: bool,
     pub ebpf_function_name: String,
     pub address_global_index: Option<usize>,
+    pub value_diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
 }
 
 impl TraceInstance {
@@ -64,6 +66,7 @@ impl TraceInstance {
             supports_backtrace_runtime_updates: args.supports_backtrace_runtime_updates,
             ebpf_function_name: args.ebpf_function_name,
             address_global_index: args.address_global_index,
+            value_diagnostics: args.value_diagnostics,
         }
     }
 
diff --git a/ghostscope/src/trace/manager.rs b/ghostscope/src/trace/manager.rs
index bd1d93db..28a0c495 100644
--- a/ghostscope/src/trace/manager.rs
+++ b/ghostscope/src/trace/manager.rs
@@ -55,6 +55,7 @@ pub struct AddTraceParams {
     pub supports_backtrace_runtime_updates: bool,
     pub ebpf_function_name: String,
     pub address_global_index: Option<usize>,
+    pub value_diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -192,6 +193,7 @@ impl TraceManager {
             supports_backtrace_runtime_updates: params.supports_backtrace_runtime_updates,
             ebpf_function_name: params.ebpf_function_name,
             address_global_index: params.address_global_index,
+            value_diagnostics: params.value_diagnostics,
         });
 
         self.traces.insert(params.trace_id, trace_instance);
@@ -329,6 +331,7 @@ impl TraceManager {
             pc: trace.pc,
             ebpf_function_name: trace.ebpf_function_name.clone(),
             address_global_index: trace.address_global_index,
+            value_diagnostics: trace.value_diagnostics.clone(),
         })
     }
 
@@ -704,6 +707,7 @@ mod tests {
             supports_backtrace_runtime_updates: true,
             ebpf_function_name: String::new(),
             address_global_index: None,
+            value_diagnostics: Vec::new(),
         });
         manager
             .traces
diff --git a/ghostscope/src/trace/snapshot.rs b/ghostscope/src/trace/snapshot.rs
index 3cd158cd..452fc26f 100644
--- a/ghostscope/src/trace/snapshot.rs
+++ b/ghostscope/src/trace/snapshot.rs
@@ -15,6 +15,7 @@ pub struct TraceSnapshot {
     #[allow(dead_code)]
     pub ebpf_function_name: String,
     pub address_global_index: Option<usize>,
+    pub value_diagnostics: Vec<ghostscope_protocol::ValueDiagnostic>,
 }
 
 /// Summary statistics for all traces
diff --git a/ghostscope/src/tui/coordinator.rs b/ghostscope/src/tui/coordinator.rs
index 582867ef..238b2c43 100644
--- a/ghostscope/src/tui/coordinator.rs
+++ b/ghostscope/src/tui/coordinator.rs
@@ -668,6 +668,7 @@ async fn compile_script_for_tui_details(
                             source_file: None,
                             source_line: None,
                             is_inline: None,
+                            value_diagnostics: Vec::new(),
                         }],
                         total_count: 1,
                         success_count: 0,
@@ -691,6 +692,7 @@ async fn compile_script_for_tui_details(
                 source_file: None,
                 source_line: None,
                 is_inline: None,
+                value_diagnostics: Vec::new(),
             }],
             total_count: 1,
             success_count: 0,
diff --git a/ghostscope/src/tui/info_handlers.rs b/ghostscope/src/tui/info_handlers.rs
index c4510a57..57402775 100644
--- a/ghostscope/src/tui/info_handlers.rs
+++ b/ghostscope/src/tui/info_handlers.rs
@@ -26,6 +26,7 @@ pub async fn handle_info_trace(
                     binary: snapshot.binary_path,
                     script_preview: Some(snapshot.script_content),
                     pc: snapshot.pc,
+                    value_diagnostics: snapshot.value_diagnostics,
                 });
         } else {
             let _ = runtime_channels
diff --git a/skills/ghostscope-runtime-analysis/SKILL.md b/skills/ghostscope-runtime-analysis/SKILL.md
index f773cd7c..382655f3 100644
--- a/skills/ghostscope-runtime-analysis/SKILL.md
+++ b/skills/ghostscope-runtime-analysis/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ghostscope-runtime-analysis
-description: Explain GhostScope and turn the project docs into concrete tracing commands, trace scripts, privilege setup, and issue-report workflows for source-aware runtime analysis. Use when the user asks how to install GhostScope, provide source tree and DWARF inputs, handle eBPF privileges, attach to a PID or binary, choose between `-p` and `-t`, inspect variables or source-aware call stacks, write GhostScope trace scripts, use Input Mode commands, work through container or PID-namespace CLI scenarios, or triage GhostScope failures, crashes, and GitHub issue reports.
+description: Explain GhostScope and turn the project docs into concrete tracing commands, trace scripts, privilege setup, and issue-report workflows for source-aware runtime analysis. Use when the user asks how to install GhostScope, provide source tree and DWARF inputs, handle eBPF privileges, attach to a PID or binary, choose between `-p` and `-t`, inspect variables or source-aware call stacks, explain value-display diagnostics, write GhostScope trace scripts, use Input Mode commands, work through container or PID-namespace CLI scenarios, or triage GhostScope failures, crashes, and GitHub issue reports.
 ---
 
 # GhostScope Runtime Analysis
@@ -30,6 +30,13 @@ copy of GhostScope behavior. When the user is writing in Chinese, prefer the
 - Exact CLI flags or launch syntax: run `ghostscope --help` first, and use subcommand help such as `ghostscope bpffs prune --help` when relevant. If `ghostscope` is unavailable but the shared workspace is the GhostScope repo, fall back to `references/cli-cookbook.md`, then `docs/configuration.md` or `docs/zh/configuration.md`.
 - TUI commands such as `trace`, `info`, `source`, `save traces`, or `srcpath`: read `references/cli-cookbook.md`, then `docs/input-commands.md` or `docs/zh/input-commands.md`.
 - Trace script authoring: run `ghostscope --script-help` first and treat its output as the source of truth for the current installed DSL. If `ghostscope` is unavailable but the shared workspace is the GhostScope repo, fall back to `docs/scripting.md` or `docs/zh/scripting.md`.
+- Value unavailable, unreadable memory, internal fields, or partial capture:
+  check `ghostscope --help`, then read `ghostscope --value-diagnostics-help` when supported.
+  This is the installed binary's offline diagnostic reference and needs no
+  target or eBPF privileges. If the binary is unavailable or too old to expose
+  the flag, use `docs/value-diagnostics.md` or `docs/zh/value-diagnostics.md`
+  when available, noting any version difference. Do not maintain a separate
+  catalog of diagnostic reasons in the skill.
 - Container or PID confusion: read `docs/container.md` or `docs/zh/container.md`.
 - Limits or caveats: read `docs/limitations.md` or `docs/zh/limitations.md`.
 - Crash, cannot-capture, or bug-report preparation: read `references/issue-reporting.md`, then `docs/install.md`, `docs/container.md`, and `docs/limitations.md` or their `docs/zh/` counterparts.
@@ -75,6 +82,13 @@ copy of GhostScope behavior. When the user is writing in Chinese, prefer the
 - If the command needs privileges and the user is likely to rerun it, prefer offering either a `setcap` command or a ready-to-run `sudo` wrapper script.
 - When asking the user for logs, check the current logging docs/help first and
   include the flags or config required to actually enable log output.
+- For value diagnostics, preserve the exact marker, affected expression/path,
+  and static display note from CLI output or `info trace <id>`. Explain the
+  matching reason and next step from the value guide before asking for logs.
+  Distinguish unavailable locations, failed reads, unsupported display layouts,
+  and partial captures. A note about a possible enum branch is not evidence
+  that the branch was active or that its memory read failed. Suggest sleepable
+  uprobes only under the guide's conditions, including the latency tradeoff.
 
 5. Avoid common mistakes.
 - Do not invent GhostScope DSL syntax. Validate it against `ghostscope --script-help`, or fall back to `docs/scripting.md` or `docs/zh/scripting.md` only when GhostScope is unavailable.
diff --git a/skills/ghostscope-runtime-analysis/VERSION b/skills/ghostscope-runtime-analysis/VERSION
index bbdeab62..1750564f 100644
--- a/skills/ghostscope-runtime-analysis/VERSION
+++ b/skills/ghostscope-runtime-analysis/VERSION
@@ -1 +1 @@
-0.0.5
+0.0.6
diff --git a/skills/ghostscope-runtime-analysis/references/cli-cookbook.md b/skills/ghostscope-runtime-analysis/references/cli-cookbook.md
index 54103c1f..deb75a00 100644
--- a/skills/ghostscope-runtime-analysis/references/cli-cookbook.md
+++ b/skills/ghostscope-runtime-analysis/references/cli-cookbook.md
@@ -51,6 +51,20 @@ ghostscope --script-help
 Use this as the source of truth for the currently installed GhostScope script syntax.
 If `ghostscope` is unavailable but you are working inside the GhostScope repository, fall back to `docs/scripting.md`.
 
+### Understand Value Output
+
+Check `ghostscope --help` for support, then read the installed value guide:
+
+```bash
+ghostscope --value-diagnostics-help
+```
+
+This prints the embedded guide without loading configuration or requiring a
+target or eBPF privileges. Match the observed marker and the CLI display note
+or TUI `info trace <id>` details to its reason. If the binary is unavailable or
+does not support the flag, use `docs/value-diagnostics.md` or
+`docs/zh/value-diagnostics.md` when available and identify any version mismatch.
+
 ### Ask For Source And Debug Inputs
 
 Before giving file:line tracing or variable-inspection workflows, confirm:
diff --git a/skills/ghostscope-runtime-analysis/references/doc-map.md b/skills/ghostscope-runtime-analysis/references/doc-map.md
index bd21b063..91dff42c 100644
--- a/skills/ghostscope-runtime-analysis/references/doc-map.md
+++ b/skills/ghostscope-runtime-analysis/references/doc-map.md
@@ -95,6 +95,20 @@ Useful search patterns:
 rg -n "^## Trace Statements|^## Variables|^## Special Variables|^## Examples|trace <pattern>" docs/scripting.md
 ```
 
+### Value diagnostics
+
+For unavailable values, memory-read failures, raw internal fields, or partial
+captures, prefer `ghostscope --value-diagnostics-help` after confirming the flag in
+`ghostscope --help`. It reads the guide shipped with the installed version
+without a target, privileges, a source checkout, or network access.
+
+Repository sources, or fallback for older binaries:
+- `docs/value-diagnostics.md`
+- `docs/zh/value-diagnostics.md`
+- `docs/input-commands.md` or `docs/zh/input-commands.md` for `info trace <id>`
+
+Keep the binary version and docs version distinct when using a fallback.
+
 ### Caveats and troubleshooting
 
 Use these when the user hits runtime issues or asks about unsupported cases:
diff --git a/skills/ghostscope-runtime-analysis/references/issue-reporting.md b/skills/ghostscope-runtime-analysis/references/issue-reporting.md
index cb555394..2dd2c5e5 100644
--- a/skills/ghostscope-runtime-analysis/references/issue-reporting.md
+++ b/skills/ghostscope-runtime-analysis/references/issue-reporting.md
@@ -17,6 +17,9 @@ Use this flow when GhostScope crashes, cannot capture as expected, shows obvious
   `[dwarf].search_paths`, `--debug-file`, `--allow-loose-debug-match`, and
   debuginfod settings
 - Relevant logs or captured output
+- For value-display failures: the exact marker, expression/path, type, stable
+  reason and detail from CLI display notes or `info trace <id>`, and the
+  matching explanation from `ghostscope --value-diagnostics-help` when supported
 - Expected behavior
 - Actual behavior or crash text
 - Container or WSL context when relevant
@@ -64,6 +67,8 @@ When issue prep is needed:
 - Unknown source tree path for a source-oriented workflow
 - Wrong PID namespace assumption for `-p`
 - Shared-library `-t` case that actually needs `--enable-sysmon-shared-lib`
+- Documented value-display or capture limits, using the installed value guide
+  before treating raw fields or a partial capture as an unexplained failure
 
 2. If the problem still looks like a GhostScope bug, crash, or unexplained failure:
 - Generate the `/tmp` report