docs: VM handoff — CLAUDE.md, Ubuntu bootstrap, headless-Sway setup for M0

Prepares the move to the NVIDIA-GPU Ubuntu VM where M0/M2 run (macOS can't drive the
Wayland/GPU stack). The repo carries the context, since Claude Code sessions are
machine-local and don't transfer.

- CLAUDE.md: project state + design invariants + don't-regress security notes. Auto-loads
  every session, so a fresh session on the VM continues from here.
- scripts/bootstrap-ubuntu.sh: verifies the (already-installed) NVIDIA/NVENC stack,
  installs rustup + PipeWire/portal/wlroots/Sway + DRM/EGL/GBM/VA dev deps; GATES the
  FFmpeg -dev headers so apt can't clobber a custom NVENC build; checks nvidia-drm.modeset.
- scripts/headless/: headless-Sway + xdg-desktop-portal-wlr config templates, the
  NVIDIA-wlroots env workarounds, run-headless-sway.sh, and a wf-recorder->hevc_nvenc
  capture smoke test (proves capture->NVENC with no Rust).
- docs/linux-setup.md: M0 walkthrough + verified gotchas (modeset, headless backend,
  vGPU NVENC licensing, dmabuf->NVENC CPU-copy fallback, FFmpeg-dev gate, crate versions).

Ubuntu 24.04 package names/versions verified against the live archive; scripts pass
shellcheck and `bash -n`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

scripts/headless/capture-smoke-test.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Prove the capture->NVENC chain end to end WITHOUT writing any Rust, using wf-recorder
+# (wlr-screencopy) piped into hevc_nvenc. Run from a shell where headless Sway is up and
+# WAYLAND_DISPLAY + XDG_RUNTIME_DIR are exported (see run-headless-sway.sh output).
+#
+# Usage: scripts/headless/capture-smoke-test.sh [output.mkv] [WxH-unused]
+#   Ctrl-C to stop; then play/inspect the file (e.g. ffprobe out.mkv).
+set -euo pipefail
+
+OUT="${1:-/tmp/lumen-headless-test.mkv}"
+: "${WAYLAND_DISPLAY:?set WAYLAND_DISPLAY (e.g. wayland-1) — is headless Sway running?}"
+: "${XDG_RUNTIME_DIR:?set XDG_RUNTIME_DIR=/run/user/\$(id -u)}"
+
+command -v wf-recorder >/dev/null || { echo "wf-recorder missing — run scripts/bootstrap-ubuntu.sh"; exit 1; }
+
+echo "recording HEADLESS-1 -> $OUT  (wlr-screencopy -> hevc_nvenc, low-latency). Ctrl-C to stop."
+# Low-latency NVENC params verified for FFmpeg 6.x/7.x: preset p1, tune ull, no B-frames.
+exec wf-recorder -o HEADLESS-1 -c hevc_nvenc \
+    -p preset=p1 -p tune=ull -p rc=cbr -p bf=0 -p delay=0 \
+    -f "$OUT"

scripts/headless/env.sh

@@ -0,0 +1,16 @@
+# shellcheck shell=bash
+# Source before launching headless Sway / the lumen host on an NVIDIA VM:
+#   source scripts/headless/env.sh
+# These are the wlroots-on-NVIDIA workarounds the research turned up (gles2 is the
+# known-good renderer; Vulkan is flaky on the proprietary driver — try it only later).
+
+export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+export XDG_CURRENT_DESKTOP=sway          # so xdg-desktop-portal selects the wlr backend
+export WLR_BACKENDS=headless             # no physical connectors on a headless VM GPU
+export WLR_LIBINPUT_NO_DEVICES=1         # don't error on having no input devices
+export WLR_NO_HARDWARE_CURSORS=1         # NVIDIA hw cursors are broken under wlroots
+export WLR_RENDERER=gles2                # known-good on NVIDIA; Vulkan often won't start
+export __GLX_VENDOR_LIBRARY_NAME=nvidia  # GLVND: dispatch GL/EGL to the NVIDIA driver
+export GBM_BACKEND=nvidia-drm            # route GBM through nvidia-drm (libnvidia-egl-gbm1)
+# Escape hatch to prove the pipeline with a software renderer if EGL/GBM misbehaves:
+#   export WLR_RENDERER_ALLOW_SOFTWARE=1 WLR_RENDERER=pixman

scripts/headless/portals.conf

@@ -0,0 +1,5 @@
+# ~/.config/xdg-desktop-portal/sway-portals.conf  (xdg-desktop-portal 1.18+ format)
+# Force the wlroots backend to service ScreenCast; gtk handles the rest.
+[preferred]
+default=gtk
+org.freedesktop.impl.portal.ScreenCast=wlr

scripts/headless/run-headless-sway.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Launch headless Sway on the NVIDIA VM with a private D-Bus session so the ScreenCast
+# portal activates. Prints the WAYLAND_DISPLAY (default wayland-1) to use from other shells.
+#
+# Prereq: scripts/bootstrap-ubuntu.sh has run and nvidia-drm.modeset=Y (reboot if not).
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "$HERE/env.sh"
+mkdir -p "$XDG_RUNTIME_DIR" 2>/dev/null || true
+chmod 700 "$XDG_RUNTIME_DIR" 2>/dev/null || true
+
+echo "starting headless Sway (renderer=$WLR_RENDERER). From another shell on this user:"
+echo "    export XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR WAYLAND_DISPLAY=wayland-1"
+echo "    swaymsg -t get_outputs        # expect HEADLESS-1"
+echo
+
+# --unsupported-gpu is mandatory on Sway 1.9 with the proprietary NVIDIA driver.
+exec dbus-run-session -- sway --unsupported-gpu

scripts/headless/sway.config

@@ -0,0 +1,10 @@
+# Minimal headless Sway config for the lumen M0 capture spike.
+# Under WLR_BACKENDS=headless, Sway 1.9 auto-creates one output named HEADLESS-1
+# (fixed 1920x1080); this just resizes it. For extra outputs: `swaymsg create_output`
+# (auto-named HEADLESS-2, ...). Set the resolution to your target client size.
+
+xwayland disable
+output HEADLESS-1 resolution 1920x1080 position 0 0
+
+# A terminal is handy when poking at the session over `swaymsg`.
+bindsym Mod4+Return exec foot

scripts/headless/xdpw.config

@@ -0,0 +1,6 @@
+# ~/.config/xdg-desktop-portal-wlr/config
+# Headless ScreenCast: there is no GUI output chooser, so select the output by name.
+[screencast]
+chooser_type=none
+output_name=HEADLESS-1
+max_fps=60