fix: add skills note

skills/news-harvester/SKILL.md

@@ -214,6 +214,34 @@ When `harvest.js` prints the `🚫 采集中止 — 需要人工介入` block, *
 
 ---
 
+## Chromium display failures (Linux / Wayland)
+
+A *different* failure mode from exit code 70: Chromium never becomes ready and the error log contains `Missing X server or $DISPLAY` (or `platform failed to initialize` / `ozone`). `ensure-chromium.js` auto-detects this and appends a `displayDiagnostic` block showing the current `$DISPLAY` / `$WAYLAND_DISPLAY` state.
+
+**Root cause.** This skill's bash shell (e.g. an agent's non-GUI shell) is not attached to a graphical session, so `DISPLAY` / `WAYLAND_DISPLAY` are unset. A `browser` source in windowed mode (`chromium.headless: false`) needs a real display to open a window. `--ozone-platform-hint=auto` is already passed, so on Wayland it picks the right backend once the variables exist — the only missing piece is the environment.
+
+**The display-variable values change across reboots**, so read the live values from the GUI session's process environment rather than hardcoding them. Example for **KDE Plasma Wayland** (uid 1000 — adjust the uid and the session process to match the user's desktop: `gnome-shell` for GNOME, `sway` for Sway):
+
+```bash
+# Read the live display variables from the GUI session process
+tr '\0' '\n' < /proc/$(pgrep -u 1000 -x plasmashell)/environ \
+  | grep -E '^(DISPLAY|WAYLAND_DISPLAY|XDG_RUNTIME_DIR|XAUTHORITY)='
+# typical: DISPLAY=:1  WAYLAND_DISPLAY=wayland-0  XDG_RUNTIME_DIR=/run/user/1000  XAUTHORITY=/run/user/1000/xauth_XXXX
+```
+
+Then `export` those values before the skill command — the browser window appears on the user's real desktop:
+
+```bash
+cd "<skill-root>" && \
+  export DISPLAY=:1 XAUTHORITY=/run/user/1000/xauth_XXXX \
+         XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 && \
+  node scripts/harvest.js <source_id> <count>
+```
+
+> **macOS / Windows** are unaffected — they don't use the Ozone backend and always have a display. This is a Linux-only issue. Running `--login` from a terminal *inside* the desktop session is the simplest alternative.
+
+---
+
 ## Category Detection
 
 | Keywords | Category |

skills/news-source-analyzer/SKILL.md

@@ -168,6 +168,34 @@ Category emoji: 地缘政治→🌏, 科技/AI→🤖, 中美关系→🇨🇳,
 
 ---
 
+## Chromium display failures (Linux / Wayland)
+
+A *different* failure mode from exit code 70: Chromium never becomes ready and the error log contains `Missing X server or $DISPLAY` (or `platform failed to initialize` / `ozone`). `ensure-chromium.js` auto-detects this and appends a `displayDiagnostic` block showing the current `$DISPLAY` / `$WAYLAND_DISPLAY` state.
+
+**Root cause.** This skill's bash shell (e.g. an agent's non-GUI shell) is not attached to a graphical session, so `DISPLAY` / `WAYLAND_DISPLAY` are unset. A `browser` source in windowed mode (`chromium.headless: false`) needs a real display to open a window. `--ozone-platform-hint=auto` is already passed, so on Wayland it picks the right backend once the variables exist — the only missing piece is the environment.
+
+**The display-variable values change across reboots**, so read the live values from the GUI session's process environment rather than hardcoding them. Example for **KDE Plasma Wayland** (uid 1000 — adjust the uid and the session process to match the user's desktop: `gnome-shell` for GNOME, `sway` for Sway):
+
+```bash
+# Read the live display variables from the GUI session process
+tr '\0' '\n' < /proc/$(pgrep -u 1000 -x plasmashell)/environ \
+  | grep -E '^(DISPLAY|WAYLAND_DISPLAY|XDG_RUNTIME_DIR|XAUTHORITY)='
+# typical: DISPLAY=:1  WAYLAND_DISPLAY=wayland-0  XDG_RUNTIME_DIR=/run/user/1000  XAUTHORITY=/run/user/1000/xauth_XXXX
+```
+
+Then `export` those values before the skill command — the browser window appears on the user's real desktop:
+
+```bash
+cd "<skill-root>" && \
+  export DISPLAY=:1 XAUTHORITY=/run/user/1000/xauth_XXXX \
+         XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 && \
+  node scripts/inspect-source.js <homepageUrl> --scroll 3   # or preview.js
+```
+
+> **macOS / Windows** are unaffected — they don't use the Ozone backend and always have a display. This is a Linux-only issue. Running `--login` from a terminal *inside* the desktop session is the simplest alternative.
+
+---
+
 ## References
 
 | File | When to read |