docs: clarify evidence bundle observability

README.md

@@ -8,11 +8,24 @@ PerformanceEvidenceProbe lets you inspect runtime performance without instrument
 
 Run a command or attach to a process, keep the raw observations, and reconstruct a deterministic summary later. For counters covered by the availability contract, an observed zero is distinct from unavailable evidence, and semantically different platform measurements are not substituted. See the [platform limits](#cross-platform-behavior), including the current Linux/macOS timing limitations.
 
+## What you get
+
+A completed bundle lets you inspect the following **within its documented platform and mode boundary**:
+
+- **Observation boundary, lifecycle, and outcome.** Process records bind an observed PID to its start time and boot identity. Timestamped samples preserve live-root observation points; events retain launch/attach, exit or other terminal, handle-release, and collector-degradation outcomes when they occur. The completed manifest separately records `run_state` (`COMPLETE` or `TARGET_FAILED`) and measurement validity/completeness, so Probe collection state is not conflated with the workload outcome.
+- **Time and CPU activity.** Windows raw monotonic samples support first-to-last-sample elapsed time and sample-gap evidence. Per-process user/kernel CPU counters are retained, and Windows launch Job accounting supports derived run CPU totals and utilization. Linux and macOS retain qualified direct-root user/kernel CPU and thread samples, but their current zero `elapsed_ns` and gap fields are **not** timing evidence.
+- **Memory and I/O evidence with stated semantics.** Windows samples retain per-process working-set/private-byte values, observed-process-set sums, read/write byte and operation counters, and (in launch mode) Job I/O accounting. The derived memory peaks are sampled maxima, not operating-system lifetime peaks. Linux and macOS do not substitute superficially similar memory or I/O measurements for these Windows-defined metrics.
+- **Process and descendant scope.** Windows `run` retains Windows Job aggregate counts/accounting and snapshot-discovered process identities, subject to process races, access, and the configured retained-handle bound; default Windows `attach` observes the requested root only. Linux and macOS observe only the direct run root or attached root and make no descendant, process-tree-closure, or complete-process-total claim.
+- **Collector and host context.** Raw samples separately record Probe CPU activity where available. Windows additionally records Probe memory, I/O, thread, and handle observations plus host, configuration, and capability metadata. These are collector observations, not a complete measurement of all collection overhead.
+- **Reviewable raw evidence rather than false zeroes.** Availability-contract counters are either numeric observations (including a truthful `0`) or omitted with one typed `metric_unavailable` declaration naming its metric, scope, and reason. `summary.json` is deterministic derived output from the saved raw streams, so its retained measurements and status can be traced back to raw samples and events.
+
+See [Cross-platform behavior](#cross-platform-behavior) for the qualified scope and current Linux/macOS limits, and [Evidence semantics](#evidence-semantics) for raw-record and summary authority.
+
 ## What it does
 
-- Creates a unique evidence bundle for a launched command or an observed PID.
-- Preserves raw process identities, samples, lifecycle events, context metadata, and a derived `summary.json`.
-- Uses a full-accounting Windows collector and intentionally narrower qualified collectors on Linux and macOS.
+- Creates a unique evidence bundle for a launched command or an observed PID, then records process identities, raw samples, and lifecycle events through a bounded single-writer NDJSON path.
+- On Windows, the qualified full-accounting collector assigns a launched root to a non-destructive accounting Job, periodically samples the observed process set, and attempts bounded descendant discovery. Linux and macOS use intentionally narrower qualified direct-root collectors; default attach is observational on every platform.
+- Finalizes the raw streams before regenerating `summary.json`, then writes platform context and a completion manifest. An interrupted collector can leave parseable raw streams, but not a completed bundle.
 - Records process/run-level evidence to support performance analysis and benchmarking, without providing call-stack profiling, automatic diagnosis, or benchmark certification.
 
 ## Quick start
@@ -133,16 +146,6 @@ Or in a POSIX shell:
 "$probe" summarize --help
 ```
 
-## What you get
-
-A completed bundle normally contains raw `processes.ndjson`, `samples.ndjson`, and `events.ndjson`; context files including `manifest.json`; and a derived `summary.json`.
-
-- **Raw observations** are the primary record.
-- **Events** explain lifecycle, retention, degradation, and terminal-observation outcomes.
-- **Manifest and context** identify the run, host, target, configuration, capabilities, and completed artifacts.
-- **Summary** is deterministic derived output that can be regenerated from the raw evidence.
-- **Validity and completeness** distinguish trustworthy bounded evidence from degraded, declared-partial, invalid, or unfinished output.
-
 ## Sample output
 
 The examples below were captured from the same controlled `perf-workload cpu-single` scenario using v0.2.0-compatible current-main code on the three qualified platforms. They are sanitized illustrative evidence output, **not cross-machine benchmark results**: the machines differ in CPU, architecture, operating system, and hardware. Each completed bundle was independently reconstructed with `perf-probe summarize`; the regenerated `summary.json` bytes matched the captured summary.