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`

help/C/org.udpscope.app/overview.page

@@ -171,15 +171,21 @@
     <title>Installing this manual</title>
     <p>The manual is a help set the desktop viewer reads off disk, so <key>F1</key> opens it only
     once a copy sits where <cmd>help:</cmd> resolves. Either of two targets installs it on its own,
-    without building the application, and each prints where it wrote:</p>
+    without building the application, and each prints where it wrote. Prefer the system-wide one:
+    it is the copy every viewer can read, and the reason is worth knowing before you pick the
+    other:</p>
     <list>
-      <item><p>For your own account, needing no root:
-      <cmd>cmake --build build --target install-help-user</cmd> writes it under
-      <file>$XDG_DATA_HOME</file> (default <file>~/.local/share</file>).</p></item>
       <item><p>For a system-wide or packaged install:
       <cmd>cmake --build build --target install-help</cmd> writes it under the configured
-      <cmd>CMAKE_INSTALL_PREFIX</cmd>, so point that at <file>/usr</file> and wrap the target in
-      <cmd>sudo</cmd>.</p></item>
+      <cmd>CMAKE_INSTALL_PREFIX</cmd>, so point that at <file>/usr</file>
+      (<cmd>cmake -DCMAKE_INSTALL_PREFIX=/usr ..</cmd>) and wrap the target in
+      <cmd>sudo</cmd>. A viewer reads its figures as separate files, and its sandbox exposes the
+      system help directories, so this copy always shows them.</p></item>
+      <item><p>For your own account, needing no root:
+      <cmd>cmake --build build --target install-help-user</cmd> writes it under
+      <file>$XDG_DATA_HOME</file> (default <file>~/.local/share</file>). Be aware that the same
+      sandbox does <em>not</em> expose the user's data directory: those pages open, but a viewer
+      such as Yelp shows them without their figures.</p></item>
     </list>
   </section>
 

src/help_window.cpp

@@ -77,13 +77,16 @@ void on_help_launched(GObject* source, GAsyncResult* result, gpointer user) {
                 ", so what is missing is a viewer for the `help:` URI it is opened with: install "
                 "one (for example `yelp`) or make it the desktop's default for that scheme.";
     } else {
+      // The system-wide install is named *first* on purpose: a set under the user's data
+      // directory is one a sandboxed viewer (Yelp) cannot read its figures from -- the pages
+      // open without their images -- so the no-root route carries that caveat rather than
+      // leading. The message is kept no longer than the one it replaces; do the same on edit.
       detail += "The manual does not look installed: nothing named \"help:" UDPSCOPE_HELP_NAME
-                "\" was found under $XDG_DATA_HOME/help/<lang>/" UDPSCOPE_HELP_NAME "/ or "
-                "$XDG_DATA_DIRS/help/<lang>/" UDPSCOPE_HELP_NAME "/. Install it with\n\n"
-                "    cmake --build build --target install-help-user\n\n"
-                "which writes the manual where `help:" UDPSCOPE_HELP_NAME "` resolves it under "
-                "your data directory, and prints the path it wrote. If there is no `help:` viewer "
-                "either, install one as well (for example `yelp`).";
+                "\" was found where `help:` resolves. Install it system-wide:\n\n"
+                "    cmake -DCMAKE_INSTALL_PREFIX=/usr .. && sudo cmake --build build --target install-help\n\n"
+                "That writes where the viewer looks. The no-root `install-help-user` writes under "
+                "your data directory instead: a sandboxed viewer shows those pages without their "
+                "figures. A `help:` viewer (for example `yelp`) is needed as well.";
     }
     gtk_alert_dialog_set_detail(alert, detail.c_str());
     gtk_alert_dialog_show(alert, launch->parent);