docs: explain Linux AppImage FUSE dependency and workaround

[kaiollzim]

Description

Add a Linux AppImage troubleshooting section to the README with terminal diagnostics, FUSE 2 installation commands for Ubuntu 22.04/24.04 and Debian 12/13, and the --appimage-extract-and-run fallback.

Motivation

When FUSE 2 is missing, launching from a file manager can appear to do nothing. These instructions help users expose the error and resolve the missing dependency, including the renamed libfuse2t64 package on newer distributions.

Type of Change

• Documentation Update

Related Issue(s)

Fixes #818

Testing Guide

• git diff --check passed before committing; reviewed the README diff.
• Confirmed the executable filename against the v1.3.3 release asset.
• Checked the fallback against the official AppImage guide.
• Verified package names in the official Ubuntu 22.04, Ubuntu 24.04, Debian 12, and Debian 13 catalogs.
• Documentation only; app tests and Linux runtime checks were not run on the macOS development host. On Linux, reviewers can follow the new section with the release AppImage.

Checklist

• I have performed a self-review of the change.
• I have linked the related issue.
• Screenshots, videos, and a changelog update are not applicable to this documentation change.

Summary by CodeRabbit

• Documentation
  • Added troubleshooting guidance for AppImage launch failures caused by missing FUSE support on Linux.
  • Included distribution-specific installation instructions for required FUSE libraries.
  • Documented a command-line workaround for running AppImages without FUSE.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: d5330380-2ae9-43ae-969f-aefd9476df01

📥 Commits

Reviewing files that changed from the base of the PR and between 4b20a1a and 1aeea85.

📒 Files selected for processing (1)

• README.md

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The README adds Linux troubleshooting guidance for AppImages that fail because FUSE 2 is missing. It documents terminal diagnosis, package installation for supported Ubuntu and Debian versions, and the --appimage-extract-and-run workaround.

Changes

AppImage FUSE troubleshooting

Layer / File(s)	Summary
Add Linux AppImage troubleshooting guidance README.md	Adds instructions to diagnose the terminal error, install libfuse2t64 or libfuse2, and bypass FUSE with --appimage-extract-and-run.

Priority: ➖ Normal — Impact reflects medium issue severity.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 1aeea

This adds Linux AppImage troubleshooting guidance for missing FUSE 2, including diagnosis, package installation, and a fallback launch mode. No current merge-readiness risk is identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR addresses the core requirements in issue #818 by documenting terminal diagnostics, Ubuntu/Debian FUSE package installation, and the --appimage-extract-and-run workaround. It does not document t…	Add Fedora guidance, such as sudo dnf install fuse, or explicitly document why Fedora is outside the intended scope of this README update.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the README documentation change for the Linux AppImage FUSE dependency and workaround.
Description check	✅ Passed	The description includes the required purpose, motivation, change type, related issue, testing guidance, and checklist information. It appropriately explains why screenshots and runtime tests do not a…
Out of Scope Changes check	✅ Passed	The changes are limited to README troubleshooting documentation directly related to the linked AppImage FUSE issue. No unrelated code or content changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

Full details: Linked Issues check

Explanation

The PR addresses the core requirements in issue #818 by documenting terminal diagnostics, Ubuntu/Debian FUSE package installation, and the --appimage-extract-and-run workaround. It does not document the Fedora installation command requested by the issue.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}