From 3fb8c717e4509c88b3ca2a1827bb13bd32fde0cf Mon Sep 17 00:00:00 2001
From: DeeJanuz <45082401+DeeJanuz@users.noreply.github.com>
Date: Sat, 26 Sep 2026 18:00:52 -0600
Subject: [PATCH] Pin distrobox, add known limitations and a bug-report script

The installer clones distrobox 1.8.2.5 instead of the latest code, so an
upstream change can't break new installs. scripts/report.sh collects
versions, service states, settings, and logs for an issue, with Bluetooth
addresses and the headset serial masked. The README lists the known
limitations and how to report problems.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .gitignore        |  1 +
 README.md         | 21 ++++++++++++++++++
 install.sh        |  3 ++-
 scripts/report.sh | 55 +++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100755 scripts/report.sh

diff --git a/.gitignore b/.gitignore
index cf9b8ca..f911798 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@ target/
 .env.*
 captures/
 __pycache__/
+frametop-report-*.txt
diff --git a/README.md b/README.md
index 1a9027d..bbf8f36 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,27 @@ Map the mouse's extra buttons to actions such as **Toggle SteamVR dashboard** or
 
 Restarting the desktop (**Frametop Display Settings → Restart desktop**) closes its windows, but background work started in it, like servers, tmux, and builds, keeps running.
 
+## Known limitations
+
+This is an early release, tested on one Steam Frame (SteamOS 0.3.0 build 20260922, SteamVR 2.17.10).
+
+- A SteamOS or SteamVR update can break parts of it until Frametop catches up. If something stops working after an update, please report it (below).
+- The first install downloads 1–2 GB (a Fedora build container) and builds everything on the headset. It takes several minutes.
+- During a VR game, a controller button can't show the screens (the game owns the buttons). Open the SteamVR dashboard, press Meta+Shift+H, or use a mapped mouse button.
+- Flatscreen games don't count as VR games. If the controllers work the screens instead of such a game, set **Frametop Display Settings → Visibility & wrist → Controllers on the screens → Only with the SteamVR dashboard open**.
+- The screens show no mouse cursor of their own: the 3D mouse's dot, or SteamVR's laser, is the cursor.
+- Remote desktop over VNC (`./desktops.sh remote on`) needs Tailscale on the Frame.
+
+## Reporting problems
+
+In a terminal on the headset, run:
+
+```
+cd ~/frametop && scripts/report.sh
+```
+
+It writes `frametop-report-<date>.txt` with the versions, service states, settings, and recent logs (Bluetooth addresses and the headset's serial number are masked). [Open an issue](https://github.com/DeeJanuz/frametop/issues) with what you did, what you expected, and what happened, and attach the file.
+
 ## Update
 
 ```
diff --git a/install.sh b/install.sh
index f2b0a75..7803288 100755
--- a/install.sh
+++ b/install.sh
@@ -50,7 +50,8 @@ if on_frame 'test -x ~/.local/bin/distrobox'; then
   echo "already installed: $(on_frame '~/.local/bin/distrobox version | head -1')"
 else
   on_frame 'set -e; mkdir -p ~/dev/src
-[ -d ~/dev/src/distrobox ] || git clone --depth 1 https://github.com/89luca89/distrobox.git ~/dev/src/distrobox
+# A tested release, so an upstream change can't break new installs.
+[ -d ~/dev/src/distrobox ] || git clone --depth 1 --branch 1.8.2.5 https://github.com/89luca89/distrobox.git ~/dev/src/distrobox
 cd ~/dev/src/distrobox && ./install --prefix ~/.local'
 fi
 
diff --git a/scripts/report.sh b/scripts/report.sh
new file mode 100755
index 0000000..3f2f0f2
--- /dev/null
+++ b/scripts/report.sh
@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Collect what a Frametop bug report needs into one text file: versions, service states,
+# settings, and recent logs. Bluetooth addresses and the headset's serial number are masked.
+# Usage: scripts/report.sh   (in a terminal on the Frame, or from a PC over SSH)
+set -euo pipefail
+root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+. "$root/scripts/_env.sh"
+out=$root/frametop-report-$(date +%Y%m%d-%H%M%S).txt
+
+on_frame_script "$FRAME_REPO" > "$out" 2>&1 <<'EOF' || true
+repo=$1
+export XDG_RUNTIME_DIR=/run/user/$(id -u) DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus
+logs=~/.local/share/Steam/logs
+section() { printf '\n===== %s\n' "$*"; }
+
+section Versions
+grep -E '^(PRETTY_NAME|VERSION_ID|BUILD_ID|VARIANT_ID)=' /etc/os-release
+grep -m1 -o 'vrcompositor [0-9.]* startup' $logs/vrcompositor.txt 2>/dev/null || echo "SteamVR: not found"
+git -C "$repo" log -1 --format='Frametop %h (%cd)' --date=short 2>/dev/null || echo "Frametop: not a git checkout"
+~/.local/bin/distrobox version 2>/dev/null || echo "distrobox: not installed"
+podman container inspect -f 'dev container: running={{.State.Running}} image={{.ImageName}}' dev 2>/dev/null || echo "dev container: missing"
+
+section Services
+for u in frametop-input-relay frametop-pointer; do
+  echo "$u: $(systemctl --user is-enabled $u 2>/dev/null) / $(systemctl --user is-active $u 2>/dev/null)"
+done
+echo "desktop: $(pgrep -x ft-screens >/dev/null && echo running || echo 'not running'), plasmashell: $(pgrep -c plasmashell || true)"
+LD_LIBRARY_PATH=/opt/steamvr/bin/linuxarm64 /opt/steamvr/bin/linuxarm64/vrpathreg show 2>/dev/null | sed -n '/xternal/,$p'
+
+section Settings
+grep -v '^\s*#' ~/.config/frametop.conf 2>/dev/null | sed 's/\s*#.*//' | grep . || echo "no ~/.config/frametop.conf"
+python3 - <<'PY' 2>/dev/null || echo "no ~/.config/frametop-layout.json"
+import json, os
+d = json.load(open(os.path.expanduser("~/.config/frametop-layout.json")))
+print("mode:", d.get("mode"), " auto:", d.get("auto"), " primary:", d.get("primary"))
+for i, s in enumerate(d.get("screens", []), 1):
+    print(f"screen {i}: {s.get('size')} {s.get('metres')} m curve={s.get('curve', 0)} pinned={s.get('pin', {}).get('hand', '-') if isinstance(s.get('pin'), dict) else '-'}")
+print("visibility:", d.get("visibility"))
+PY
+
+section "Input relay (last 60 lines)"
+journalctl --user -u frametop-input-relay -n 60 --no-pager -o short 2>/dev/null
+section "Pointer helper (last 60 lines)"
+journalctl --user -u frametop-pointer -n 60 --no-pager -o short 2>/dev/null
+for f in /tmp/frametop-session.log /tmp/frametop-screens.log /tmp/frametop-layout.log; do
+  section "$f (last 60 lines)"
+  tail -n 60 "$f" 2>/dev/null || echo "missing"
+done
+section "SteamVR server: Frametop and errors (last 60 lines)"
+grep -a -i -E 'ft_pointer|frametop|\[error\]' $logs/vrserver.txt 2>/dev/null | tail -n 60
+EOF
+
+sed -i -E 's/([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}/xx:xx:xx:xx:xx:xx/g; s/cv\.[A-Z0-9]{8,}/cv.<serial>/g' "$out"
+echo "wrote $out"
+echo "Attach it to an issue at https://github.com/DeeJanuz/frametop/issues, with what you did, what you expected, and what happened."