From 2128ce52448fb812b1f08e05b0bf952b862f131a Mon Sep 17 00:00:00 2001
From: swananan <jt26wzz@gmail.com>
Date: Wed, 9 Sep 2026 18:36:51 +0800
Subject: [PATCH] feat: explain value display failures and capture limits

Expose stable value diagnostics in printed values and trace details so
users can distinguish unavailable variables, failed reads, adapter
fallbacks, and capture limits. Preserve path-qualified notes in CLI and
TUI output independently of capture selection and register locations.

Embed --value-diagnostics-help, provide matching English and Chinese
guidance, and update the runtime-analysis skill to 0.0.6. Explain failed
read triage without treating errno or static display limits as a cause.

Consolidate diagnostic e2e coverage around reasons, retained values,
streams, and exit status, including ordinary null-pointer reads and
register-backed arguments with static display notes.
---
 .github/workflows/ci.yml                      |   5 +-
 README-zh.md                                  |   6 +-
 README.md                                     |   6 +-
 docs/architecture.md                          |  30 +
 docs/configuration.md                         |   4 +
 docs/input-commands.md                        |   2 +
 docs/limitations.md                           |   2 +
 docs/scripting.md                             |  11 +-
 docs/value-diagnostics.md                     | 175 ++++
 docs/zh/architecture.md                       |  24 +
 docs/zh/configuration.md                      |   4 +
 docs/zh/input-commands.md                     |   2 +
 docs/zh/limitations.md                        |   2 +
 docs/zh/scripting.md                          |  11 +-
 docs/zh/value-diagnostics.md                  | 145 ++++
 e2e-tests/README.md                           |  44 +
 e2e-tests/tests/common/termination.rs         |   5 +-
 .../tests/entry_value_recovery_execution.rs   |   6 +-
 .../sized/alloc.rs                            | 124 +++
 .../rust_value_diagnostics_program/main.rs    | 112 +++
 .../register.rs                               |  32 +
 e2e-tests/tests/globals_target_execution.rs   |   2 +-
 .../optimized_inline_call_value_execution.rs  |  66 --
 .../rust_adapter_diagnostics_execution.rs     |  70 --
 .../tests/rust_legacy_btree_execution.rs      |   2 +-
 e2e-tests/tests/rust_legacy_hash_execution.rs |   2 +-
 .../tests/rust_legacy_sequence_execution.rs   |   2 +-
 .../tests/rust_legacy_string_execution.rs     |   2 +-
 e2e-tests/tests/rust_path_execution.rs        |   8 +-
 e2e-tests/tests/rust_script_execution.rs      |  37 +-
 .../tests/rust_version_matrix_execution.rs    |   2 +-
 .../tests/value_diagnostics_execution.rs      | 782 ++++++++++++++++++
 ghostscope-compiler/src/ebpf/codegen/args.rs  | 180 ++--
 .../ebpf/codegen/value_capture/diagnostics.rs | 102 +++
 .../src/ebpf/codegen/value_capture/mod.rs     |   2 +
 .../codegen/value_capture/presentation.rs     |  24 +-
 .../src/ebpf/codegen/value_capture/tests.rs   |  29 +
 ghostscope-compiler/src/lib.rs                |   4 +
 ghostscope-dwarf/src/analyzer/type_context.rs | 318 +++++--
 ghostscope-dwarf/src/language/mod.rs          |  17 +-
 .../src/language/rust/composition.rs          |   7 +-
 ghostscope-dwarf/src/language/rust/mod.rs     |   2 +-
 ghostscope-dwarf/src/lib.rs                   |   9 +-
 ghostscope-dwarf/src/semantics/mod.rs         |   2 +-
 ghostscope-dwarf/src/semantics/value.rs       |  74 ++
 ghostscope-protocol/src/format_printer.rs     | 140 +++-
 ghostscope-protocol/src/lib.rs                |   3 +
 ghostscope-protocol/src/trace_context.rs      | 112 ++-
 ghostscope-protocol/src/value_diagnostic.rs   |  98 +++
 ghostscope-protocol/src/value_presentation.rs |   3 +
 .../src/components/app/runtime_status.rs      |  20 +
 .../command_panel/response_formatter.rs       |   5 +
 .../components/command_panel/script_editor.rs |   3 +
 ghostscope-ui/src/events/runtime.rs           |  32 +
 ghostscope-ui/src/model/panel_state.rs        |   4 +
 ghostscope-ui/tests/ansi_color_test.rs        |  77 ++
 ghostscope/src/cli/docs.rs                    |   5 +
 ghostscope/src/cli/mod.rs                     |   2 +-
 ghostscope/src/cli/value-diagnostics.md       |   1 +
 ghostscope/src/config/args.rs                 |  95 ++-
 ghostscope/src/main.rs                        |   4 +
 ghostscope/src/script/attach.rs               |   1 +
 ghostscope/src/script/cli.rs                  |  13 +-
 ghostscope/src/script/tui.rs                  |   3 +
 ghostscope/src/trace/instance.rs              |   5 +-
 ghostscope/src/trace/manager.rs               |   4 +
 ghostscope/src/trace/snapshot.rs              |   1 +
 ghostscope/src/tui/coordinator.rs             |   2 +
 ghostscope/src/tui/info_handlers.rs           |   1 +
 skills/ghostscope-runtime-analysis/SKILL.md   |  16 +-
 skills/ghostscope-runtime-analysis/VERSION    |   2 +-
 .../references/cli-cookbook.md                |  14 +
 .../references/doc-map.md                     |  14 +
 .../references/issue-reporting.md             |   5 +
 74 files changed, 2762 insertions(+), 420 deletions(-)
 create mode 100644 docs/value-diagnostics.md
 create mode 100644 docs/zh/value-diagnostics.md
 create mode 100644 e2e-tests/tests/fixtures/rust_adapter_rejection_program/sized/alloc.rs
 create mode 100644 e2e-tests/tests/fixtures/rust_value_diagnostics_program/main.rs
 create mode 100644 e2e-tests/tests/fixtures/rust_value_diagnostics_program/register.rs
 delete mode 100644 e2e-tests/tests/rust_adapter_diagnostics_execution.rs
 create mode 100644 e2e-tests/tests/value_diagnostics_execution.rs
 create mode 100644 ghostscope-compiler/src/ebpf/codegen/value_capture/diagnostics.rs
 create mode 100644 ghostscope-protocol/src/value_diagnostic.rs
 create mode 120000 ghostscope/src/cli/value-diagnostics.md

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