Document that JSON_Diagnostics CMake option doesn't apply to pre-installed packages (#5270)

Closes #3106. set(JSON_Diagnostics ON) before find_package() has no
effect on a package built and installed elsewhere (Homebrew, vcpkg, a
system package, etc.) -- the compile definition is baked into the
exported nlohmann_jsonTargets.cmake at install time and the generated
config script never re-reads that variable. Verified empirically
against the real Homebrew-installed 3.12.0 package: the exported
target carries a fixed $<$<BOOL:OFF>:JSON_DIAGNOSTICS=1>, and the
suggested set(JSON_Diagnostics ON) snippet produces no change in
exception output.

Documents the actual working fix (overriding the imported target's
INTERFACE_COMPILE_DEFINITIONS property after find_package()) and the
multi-target "JSON_DIAGNOSTICS redefined" pitfall reported earlier in
the issue thread.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

docs/mkdocs/docs/api/macros/json_diagnostics.md

diff --git a/docs/mkdocs/docs/api/macros/json_diagnostics.md b/docs/mkdocs/docs/api/macros/json_diagnostics.md
index 91bdc1b..d60df5e 100644
--- a/docs/mkdocs/docs/api/macros/json_diagnostics.md
+++ b/docs/mkdocs/docs/api/macros/json_diagnostics.md
@@ -38,7 +38,8 @@
 
     Diagnostic messages can also be controlled with the CMake option
     [`JSON_Diagnostics`](../../integration/cmake.md#json_diagnostics) (`OFF` by default)
-    which defines `JSON_DIAGNOSTICS` accordingly.
+    which defines `JSON_DIAGNOSTICS` accordingly. Note this only applies when building the
+    library from source — see the pre-installed-package caveat on that page.
 
 ## Examples
 

docs/mkdocs/docs/integration/cmake.md

diff --git a/docs/mkdocs/docs/integration/cmake.md b/docs/mkdocs/docs/integration/cmake.md
index 05d1d34..a8a6d52 100644
--- a/docs/mkdocs/docs/integration/cmake.md
+++ b/docs/mkdocs/docs/integration/cmake.md
@@ -135,6 +135,31 @@
 
 Enable [extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) by defining macro [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This option is `OFF` by default.
 
+!!! warning "Does not apply to a pre-installed package"
+
+    This option only takes effect when building nlohmann/json from source as part of your own
+    CMake project (e.g. via [`FetchContent`](#fetchcontent) or [`add_subdirectory`](#external)).
+    It has **no effect** on a package that was already built and installed elsewhere (Homebrew,
+    vcpkg, a system package, etc.) — the resulting compile definition is baked into the exported
+    `nlohmann_jsonTargets.cmake` at install time, and `set(JSON_Diagnostics ON)` before
+    `find_package()` does not change it (verified against the Homebrew-installed package: the
+    exported target still carries a fixed `$<$<BOOL:OFF>:JSON_DIAGNOSTICS=1>`, regardless of any
+    variable set in the consuming project).
+
+    To enable extended diagnostics for a pre-installed package, override the imported target's
+    property directly after `find_package()`:
+
+    ```cmake
+    find_package(nlohmann_json REQUIRED)
+    set_target_properties(nlohmann_json::nlohmann_json PROPERTIES
+        INTERFACE_COMPILE_DEFINITIONS "JSON_DIAGNOSTICS=1")
+    ```
+
+    This only works cleanly when your project is the sole consumer of that imported target. If
+    nlohmann_json is pulled in from more than one place in your dependency graph with different
+    `JSON_DIAGNOSTICS` values, you may see a `"JSON_DIAGNOSTICS" redefined` compiler error, since
+    conflicting `-D` flags can end up on the same compile command line.
+
 ### `JSON_Diagnostic_Positions`
 
 Enable position diagnostics by defining macro [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md). This option is `OFF` by default.