From 6b65a72b35dc2c7bd3ea2dac72a7a717381585cd Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 8 Dec 2025 15:41:31 +0000
Subject: [PATCH] Update documentation to reference diagrams and explain Pragma
 header requirement

Co-authored-by: arthurfiorette <47537704+arthurfiorette@users.noreply.github.com>
---
 docs/src/config/request-specifics.md | 10 ++++++++--
 docs/src/guide/debugging.md          | 14 ++++++++++++++
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/docs/src/config/request-specifics.md b/docs/src/config/request-specifics.md
index 346f34e..a93db4b 100644
--- a/docs/src/config/request-specifics.md
+++ b/docs/src/config/request-specifics.md
@@ -123,9 +123,15 @@ Headers included:
 - `Pragma: no-cache`
 - `Expires: 0`
 
-::: info Safari Compatibility
+::: info iOS Safari Compatibility
 
-The `max-age=0` directive was added to ensure compatibility with Safari (including iOS Safari), which has historically been more aggressive with caching and may not fully respect the `no-cache` directive alone. This combination of headers ensures reliable cache prevention across all major browsers.
+The `Pragma: no-cache` header is specifically required for iOS Safari compatibility due to a [WebKit bug (#170714)](https://bugs.webkit.org/show_bug.cgi?id=170714). While `Pragma` is an HTTP/1.0 header considered legacy, iOS Safari requires it to properly prevent caching. Without this header, iOS Safari may still cache responses despite the `Cache-Control` directives.
+
+Additionally, the `max-age=0` directive was added to ensure compatibility with Safari, which has historically been more aggressive with caching and may not fully respect the `no-cache` directive alone. This combination of headers ensures reliable cache prevention across all major browsers.
+
+For more details, see:
+- [Issue #579: iOS Safari caching behavior](https://github.com/arthurfiorette/axios-cache-interceptor/issues/579)
+- [Issue #471: Safari cache issues](https://github.com/arthurfiorette/axios-cache-interceptor/issues/471)
 
 :::
 
diff --git a/docs/src/guide/debugging.md b/docs/src/guide/debugging.md
index b3d8929..e4e57c9 100644
--- a/docs/src/guide/debugging.md
+++ b/docs/src/guide/debugging.md
@@ -64,6 +64,20 @@ const axios = setupCache(Axios, {
 And much more, depending on your context, situation and configuration. **Any misbehavior
 that you find will have a log to explain it.**
 
+## Understanding Debug Messages
+
+To help you understand what each debug message means and what action is being taken, we've created comprehensive flow diagrams that document the entire request/response cycle and explain every debug message:
+
+- **[Debug Messages Guide](https://github.com/arthurfiorette/axios-cache-interceptor/blob/main/debug-messages-guide.mermaid)** - Complete guide explaining what each debug message means, why it occurred, and what happens next
+- **[Request/Response Flow Overview](https://github.com/arthurfiorette/axios-cache-interceptor/blob/main/request-response-flow-overview.mermaid)** - High-level diagram of the complete request flow
+- **[All Flow Diagrams](https://github.com/arthurfiorette/axios-cache-interceptor/blob/main/DIAGRAMS_README.md)** - Complete documentation of all available diagrams
+
+These diagrams will help you:
+- Understand what conditions led to a specific debug message
+- Follow the path your request takes through the interceptors
+- Troubleshoot unexpected caching behavior
+- Learn how different cache states transition
+
 ::: details Sample of logs sent to console.
 
 ```json