help: recommend the system-wide install and record the location trap

A Mallard set under $XDG_DATA_HOME/help is one Yelp cannot draw the figures
of: its sandbox exposes the system help directories but not the user's data
directory, and each figure is a separate file the page references. The pages
open without their images, and through the app's help: URI the viewer spins
for ever because the failed image fetch means the page's load event never
fires -- which reads as a navigation failure, not a missing resource.

The alert and the manual both recommended install-help-user as the no-root
route, so they led users into exactly that case. Name the system-wide install
first and state the user-local caveat where the advice is given, and record
the finding in the GTK traps invariant so the next figure that will not draw
is not chased as a markup or a file problem.

docs/claude/invariants-gtk-and-chrome.md

@@ -158,9 +158,9 @@ Part of [CLAUDE.md](../../CLAUDE.md). These are rules that cost a defect to lear
   document that was never installed, so `help_installed_path()` walks the specification's own
   `$XDG_DATA_HOME/help/<lang>/<id>/` then `$XDG_DATA_DIRS/help/<lang>/<id>/` for an `index.page` and
   the dialog says which one it is: with the manual there, install a viewer (for example `yelp`); with
-  it absent, the identifier, the expected installed path and the install command
-  (`cmake --build build --target install-help-user`, which installs it under the user data
-  directory; `install-help` is the prefix-wide form for a system or packaged install) — and a
+  it absent, the identifier and the install command, the **system-wide** form first
+  (`cmake -DCMAKE_INSTALL_PREFIX=/usr .. && sudo cmake --build build --target install-help`), the
+  no-root `install-help-user` second with its caveat (see the location rule below) — and a
   viewer as well, the second possibility the error alone cannot rule out. Reporting a missing
   *document* as a missing *handler* is the defect that shape avoids.
 
@@ -181,6 +181,26 @@ Part of [CLAUDE.md](../../CLAUDE.md). These are rules that cost a defect to lear
   (GTK4 must be forced to the Cairo renderer, `GSK_RENDERER=cairo`, or the X11 surface reads back
   blank). Mallard is translatable with `itstool`, but there is no i18n set-up here: only the `C`
   set is authored.
+
+  **A user-local help set is one Yelp cannot draw the figures of, so the system-wide install is
+  the one to recommend — and this is a *location* rule, not a markup or a file rule.** Yelp
+  sandboxes its WebKit subprocess, and that sandbox exposes the system help directories
+  (`/usr/share/help`, `/usr/local/share/help`) but not `$XDG_DATA_HOME/help`: the pages load,
+  their `<media>` figures do not, because each figure is a *separate file* the page references
+  rather than something embedded in it. The symptoms read as anything but a location problem —
+  opening a page *as a file* renders it with no images, and opening it through the app's `help:`
+  URI leaves the viewer spinning **for ever**, the failed image fetch meaning the page's load
+  event never fires while the sidebar title still updates, which looks like a navigation failure
+  rather than a missing resource. A shipped GNOME page that carries a figure
+  (`/usr/share/help/C/accerciser/api_browser_plugin.page`) draws either way, which is what
+  isolates the cause to where the set *lives*. `make install-help` (into `/usr/local`) followed
+  by `yelp /usr/local/share/help/C/<id>/<topic>.page` works; the same set under
+  `~/.local/share/help` does not. Two genuine defects were chased and fixed before the location
+  was found — a `<figure>` with no `<desc>` and a `bKGD` chunk the PNG spec forbids on an
+  alpha image — so do not read a figure that will not draw as a repeat of either, and do not
+  revert those fixes: this is why both the failure alert in `src/help_window.cpp` and the
+  manual's own `overview.page` name the system-wide install first and state the user-local one's
+  caveat beside it.
 - **The chooser carries the same help affordances as the window, and the tour request crosses as a
   value — not a global.** The source chooser runs *before* `App` exists, so a user who has not started
   yet is the one least able to find the help; its header bar therefore has a help `GtkMenuButton`