From 05e8df2f643a6e14d2a7ddd15bf8d4f90ca92250 Mon Sep 17 00:00:00 2001
From: Maxim Khomiakov <23268549+pihalf@users.noreply.github.com>
Date: Wed, 1 Jul 2026 09:29:05 +0200
Subject: [PATCH] docs: require unconfined Logseq (AppImage) on Linux, not
 snap/Flatpak

---
 README.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/README.md b/README.md
index f01aa6f..a9b5139 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,20 @@ In Logseq: **Settings > Advanced > Developer mode** (on) → **Plugins > Load un
 
 </details>
 
+### Linux: install the AppImage, not snap or Flatpak
+
+gitseq runs git through Logseq's bundled `dugite`, inheriting Logseq's `HOME` and `PATH`. Sandboxed Logseq builds break this:
+
+| Install | Works | Why |
+|---|---|---|
+| **AppImage** / unpacked `.deb` / AUR | ✅ | Unconfined: reads your real `~/.gitconfig`, and git's filters/hooks resolve host `git-crypt`/`git-lfs` on `PATH`. |
+| **Snap** | ❌ | Remaps `HOME` (→ "Author identity unknown") and its mount namespace hides host `/usr/bin` (→ "git-crypt: not found", exit 127). |
+| **Flatpak** | ⚠️ | Real `HOME` fixes identity + SSH, but the sandboxed `/usr` still hides `git-crypt`/`git-lfs`. |
+
+This affects any clean/smudge filter (`git-crypt`) and any hook-invoked binary (`git-lfs`), not just encryption. **On Linux, install the [AppImage](https://github.com/logseq/logseq/releases).**
+
+**Ubuntu 24.04+:** the AppImage needs an AppArmor `userns` profile to launch (or run it with `--no-sandbox`).
+
 ## Prerequisites
 
 Before using gitseq, your Logseq graph needs to be a git repo with a remote:
@@ -151,6 +165,8 @@ git-crypt unlock ~/.git-crypt-my-graph.key
 
 Open the graph in Logseq. Install gitseq. Done.
 
+> **Linux:** install Logseq as the AppImage, not snap or Flatpak — see [Linux: install the AppImage](#linux-install-the-appimage-not-snap-or-flatpak).
+
 ## CLI companion (optional)
 
 A Rust CLI for syncing outside Logseq (terminal, cron, automation):
@@ -170,6 +186,8 @@ cd cli && cargo build --release
 
 **Cmd+S doesn't work** — another plugin may have claimed it. Use `Cmd+Shift+P` → "gitseq: Sync Now".
 
+**"Author identity unknown" or "git-crypt: not found" (exit 127) on Linux** — you're on a sandboxed Logseq (snap/Flatpak). Install the [AppImage](#linux-install-the-appimage-not-snap-or-flatpak) instead.
+
 ## License
 
 MIT