diff --git a/docs/crash-report.md b/docs/crash-report.md
index 2c329ab..720d4ea 100644
--- a/docs/crash-report.md
+++ b/docs/crash-report.md
@@ -6,7 +6,16 @@ file when an unexpected panic occurs.  No data is ever sent automatically.
 ## What is collected
 
 When `[crash_report] enabled = true` and a panic happens, parsec writes a
-file to `~/.cache/parsec/crash-<timestamp>.json` containing:
+`crash-<timestamp>.json` file under the platform cache directory:
+
+| Platform | Directory |
+|---|---|
+| Linux | `$XDG_CACHE_HOME/parsec/`, or `~/.cache/parsec/` when unset |
+| macOS | `~/Library/Caches/parsec/` |
+| Windows | `%LOCALAPPDATA%\parsec\` |
+
+The exact directory is selected by [`dirs::cache_dir()`](https://docs.rs/dirs/latest/dirs/fn.cache_dir.html).
+Each report contains:
 
 | Field | Example | Notes |
 |---|---|---|
@@ -41,8 +50,8 @@ The default is `enabled = false` — **nothing is saved unless you opt in**.
 
 If you experience a crash and want to help:
 
-1. Find the report: `ls ~/.cache/parsec/crash-*.json`
-2. Review its contents before sharing (it is plain JSON)
+1. Run `parsec crash-report list` to find the report ID
+2. Review it with `parsec crash-report show <id>` (it is plain JSON)
 3. Open a GitHub issue: <https://github.com/erishforG/git-parsec/issues/new>
 4. Paste or attach the file
 
@@ -50,9 +59,10 @@ You are never required to share a crash report.
 
 ## Retention
 
-Reports are stored locally in `~/.cache/parsec/`.  They are never automatically
-deleted by parsec; you can remove them at any time:
+Reports stay in the platform cache directory until you remove them. Preview a
+cleanup first, then delete all saved reports with:
 
 ```sh
-rm ~/.cache/parsec/crash-*.json
+parsec --dry-run crash-report clear
+parsec crash-report clear
 ```
diff --git a/src/cli/commands/crash_report.rs b/src/cli/commands/crash_report.rs
index f590ffc..dc58e54 100644
--- a/src/cli/commands/crash_report.rs
+++ b/src/cli/commands/crash_report.rs
@@ -2,7 +2,8 @@
 //!
 //! Crash reports are opt-in JSON files written by the panic hook (Phase 1) to
 //! `<OS cache dir>/parsec/crash-<timestamp>.json`
-//! (e.g. `~/.cache/parsec/crash-20260101T000000Z.json` on Linux/macOS).
+//! (e.g. `~/.cache/parsec/crash-1704067200.json` on Linux or
+//! `~/Library/Caches/parsec/crash-1704067200.json` on macOS).
 //!
 //! ## Subcommands
 //!
diff --git a/src/config/settings.rs b/src/config/settings.rs
index 1f2d677..cd60afa 100644
--- a/src/config/settings.rs
+++ b/src/config/settings.rs
@@ -457,7 +457,7 @@ impl Default for UpdateConfig {
 /// Controls opt-in crash report collection (#298).
 ///
 /// No data is transmitted automatically.  When `enabled = true`, a JSON
-/// report is written to `~/.cache/parsec/crash-<ts>.json` on panic.  The
+/// report is written to `<OS cache dir>/parsec/crash-<ts>.json` on panic.  The
 /// user must choose to share it.  See `docs/crash-report.md`.
 ///
 /// # Example (`~/.config/parsec/config.toml`)
diff --git a/src/panic_handler.rs b/src/panic_handler.rs
index e792389..ce78dc6 100644
--- a/src/panic_handler.rs
+++ b/src/panic_handler.rs
@@ -4,7 +4,7 @@
 //! Registers a custom panic hook that:
 //! 1. Prints a user-friendly crash banner to **stderr** (always).
 //! 2. When `enabled = true` (opt-in), writes a structured JSON report to
-//!    `~/.cache/parsec/crash-<timestamp>.json` so users can share it
+//!    `<OS cache dir>/parsec/crash-<timestamp>.json` so users can share it
 //!    with the maintainers.
 //!
 //! No data is **transmitted** automatically.  The user must opt in via config
@@ -33,7 +33,8 @@ const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
 /// Call this once at startup, before any `tokio` threads are spawned.
 ///
 /// When `enabled` is `true` the hook will also write a JSON crash report to
-/// the OS cache directory (`~/.cache/parsec/` on Linux/macOS).
+/// the OS cache directory (for example, `~/.cache/parsec/` on Linux or
+/// `~/Library/Caches/parsec/` on macOS).
 pub fn setup(enabled: bool) {
     REPORT_ENABLED.store(enabled, Ordering::SeqCst);