Linux support: platform-aware discovery instead of Windows-shaped guesses

The backend already branched on os.name for shell and process handling, so
execution was never Windows-only. What was Windows-only were the *discovery*
lists — the places the system looks for optional components. On Linux those
lists simply never matched, so a capability that was present appeared absent.
Nothing crashed; things quietly did not work, which is worse.

Now probed per platform:

- Obsidian vault: adds ~/Notes, ~/vault, and the Linux sync-client conventions
  (Nextcloud, Dropbox, Syncthing) plus /vault and /data/obsidian for container
  mounts; macOS gets the iCloud-synced vault location. The Windows and OneDrive
  paths are kept, now behind an os.name check rather than tried everywhere.
- Obsidian vault registry: was APPDATA only. Adds the macOS Application Support
  path, $XDG_CONFIG_HOME (falling back to ~/.config), and the Flatpak location
  under ~/.var/app/md.obsidian.Obsidian.
- Tesseract: PATH is now tried first — which is how every Linux package manager
  and Homebrew install it — before falling back to platform-specific locations.
  tessdata likewise gains the Debian, Fedora, Arch and Homebrew directories.
- Agent workspace: ~/Desktop/workspace was assumed to exist. On a headless
  server, or a system with a non-English XDG name, it does not. Falls back to
  ~/skynetclaw-workspace.

docs/LINUX.md documents what a Linux install actually needs: system packages per
distribution, a local model, the full discovery table, a systemd --user unit,
the port map with an explicit warning that 8766 has no authentication and must
not be exposed to a network, and the known gaps — .bat/.ps1 do not apply, macOS
is not in CI, language data for OCR installs separately, and some agent prompt
guidance still reads Windows-first.

Listing the gaps rather than leaving them to be discovered is the point; a
platform claim that has not been tested is not a claim worth making.

Verified: 601 tests pass, import OK with 267 routes, discovery still resolves
correctly on the Windows host it was changed on.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ElmatadorZ

README.md

@@ -215,6 +215,9 @@ See [NOTICE](NOTICE) for the full statement.
 | **Windows** | ✅ verified in CI | `install.bat` · `start.bat` |
 | **macOS** | ⚠️ should work (POSIX path); **not yet in CI** | use the commands above |
 
+Linux specifics — system packages, discovery paths, systemd unit, known gaps:
+**[docs/LINUX.md](docs/LINUX.md)**.
+
 CI installs from `requirements.txt` alone on Ubuntu and Windows across Python 3.10 / 3.11 / 3.12,
 runs the migration, boots the server, and requires `/api/system/health` to report `ok`. If that
 badge is red, the claim that this works is not currently true.

backend/doc_reader.py

@@ -72,23 +72,41 @@ def _html(path: str) -> str:
 
 
 def _find_tesseract() -> str:
+    """Locate the tesseract binary. PATH first — that is how it is installed on
+    Linux (apt/dnf/pacman), macOS (brew), and increasingly on Windows too.
+    The explicit lists are fallbacks for installers that skip PATH."""
     import shutil
     cmd = shutil.which("tesseract")
     if cmd:
         return cmd
-    for p in (r"C:\Program Files\Tesseract-OCR\tesseract.exe",
-              r"C:\Program Files (x86)\Tesseract-OCR\tesseract.exe"):
+    if os.name == "nt":
+        cands = (r"C:\Program Files\Tesseract-OCR\tesseract.exe",
+                 r"C:\Program Files (x86)\Tesseract-OCR\tesseract.exe")
+    else:
+        cands = ("/usr/bin/tesseract",            # Debian/Ubuntu, Fedora, Arch
+                 "/usr/local/bin/tesseract",      # source builds, Intel brew
+                 "/opt/homebrew/bin/tesseract",   # Apple-silicon brew
+                 "/snap/bin/tesseract")
+    for p in cands:
         if os.path.exists(p):
             return p
     return ""
 
 
 def _find_tessdata() -> str:
     """A tessdata dir that contains Thai (tha.traineddata)."""
+    home = os.path.expanduser("~")
     cands = [os.environ.get("TESSDATA_PREFIX", ""),
-             os.path.join(os.path.expanduser("~"), "llamacpp_test", "tessdata"),
-             r"C:\Program Files\Tesseract-OCR\tessdata",
-             r"C:\Program Files (x86)\Tesseract-OCR\tessdata"]
+             os.path.join(home, "llamacpp_test", "tessdata")]
+    if os.name == "nt":
+        cands += [r"C:\Program Files\Tesseract-OCR\tessdata",
+                  r"C:\Program Files (x86)\Tesseract-OCR\tessdata"]
+    else:
+        cands += ["/usr/share/tesseract-ocr/5/tessdata",   # Debian/Ubuntu (v5)
+                  "/usr/share/tesseract-ocr/4.00/tessdata",  # older Debian
+                  "/usr/share/tessdata",                     # Fedora/Arch
+                  "/usr/local/share/tessdata",
+                  "/opt/homebrew/share/tessdata"]            # Apple-silicon brew
     for d in cands:
         if d and os.path.exists(os.path.join(d, "tha.traineddata")):
             return d

backend/main.py

@@ -3915,8 +3915,16 @@ async def browse_file(title: str = "Select File", filter: str = "All Files|*.*")
 @app.get("/api/browse/obsidian-vaults")
 async def find_obsidian_vaults():
     vaults=[]
-    for cfg in [Path(os.environ.get("APPDATA",""))/"obsidian"/"obsidian.json",
-                Path.home()/"AppData"/"Roaming"/"obsidian"/"obsidian.json"]:
+    # Obsidian stores its vault registry in the host's config location, which
+    # differs per platform. Probe all of them; missing ones are simply skipped.
+    _cfgs = [Path(os.environ.get("APPDATA", "")) / "obsidian" / "obsidian.json",
+             Path.home() / "AppData" / "Roaming" / "obsidian" / "obsidian.json",          # Windows
+             Path.home() / "Library" / "Application Support" / "obsidian" / "obsidian.json",  # macOS
+             Path(os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config"))
+             / "obsidian" / "obsidian.json",                                              # Linux
+             Path.home() / ".var" / "app" / "md.obsidian.Obsidian" / "config"
+             / "obsidian" / "obsidian.json"]                                              # Linux flatpak
+    for cfg in _cfgs:
         if cfg.exists():
             try:
                 data=json.loads(cfg.read_text(encoding="utf-8"))
@@ -7419,11 +7427,19 @@ async def api_upload(file: UploadFile = File(...), workspace_folder: str = Form(
         import doc_reader as _dr
         ws = (workspace_folder or "").strip()
         if not ws:
-            for _cand in [os.path.join(os.path.expanduser("~"), "OneDrive", "Desktop", "workspace"),
-                          os.path.join(os.path.expanduser("~"), "Desktop", "workspace")]:
+            _home = os.path.expanduser("~")
+            # Desktop is not guaranteed on Linux (headless, or a non-English
+            # XDG name), so fall back to a plain ~/skynetclaw-workspace there.
+            _cands = [os.path.join(_home, "OneDrive", "Desktop", "workspace"),
+                      os.path.join(_home, "Desktop", "workspace"),
+                      os.path.join(_home, "skynetclaw-workspace")]
+            for _cand in _cands:
                 if os.path.isdir(_cand):
                     ws = _cand; break
-            ws = ws or os.path.join(os.path.expanduser("~"), "Desktop", "workspace")
+            if not ws:
+                ws = (os.path.join(_home, "Desktop", "workspace")
+                      if os.path.isdir(os.path.join(_home, "Desktop"))
+                      else os.path.join(_home, "skynetclaw-workspace"))
         updir = os.path.join(ws, "uploads")
         os.makedirs(updir, exist_ok=True)
         safe = os.path.basename(file.filename or "upload.bin").replace("..", "_")
@@ -7455,11 +7471,19 @@ async def api_news_report(req: Request):
             topics = [t.strip() for t in _re2.split(r"[,\n;|]", topics) if t.strip()]
         ws = body.get("workspace_folder")
         if not ws:
-            for _cand in [os.path.join(os.path.expanduser("~"), "OneDrive", "Desktop", "workspace"),
-                          os.path.join(os.path.expanduser("~"), "Desktop", "workspace")]:
+            _home = os.path.expanduser("~")
+            # Desktop is not guaranteed on Linux (headless, or a non-English
+            # XDG name), so fall back to a plain ~/skynetclaw-workspace there.
+            _cands = [os.path.join(_home, "OneDrive", "Desktop", "workspace"),
+                      os.path.join(_home, "Desktop", "workspace"),
+                      os.path.join(_home, "skynetclaw-workspace")]
+            for _cand in _cands:
                 if os.path.isdir(_cand):
                     ws = _cand; break
-            ws = ws or os.path.join(os.path.expanduser("~"), "Desktop", "workspace")
+            if not ws:
+                ws = (os.path.join(_home, "Desktop", "workspace")
+                      if os.path.isdir(os.path.join(_home, "Desktop"))
+                      else os.path.join(_home, "skynetclaw-workspace"))
         fname = (body.get("filename") or "news_report.html").strip()
         if not fname.lower().endswith(".html"):
             fname += ".html"

backend/obsidian_tools.py

@@ -11,12 +11,15 @@
 Vault discovery (in order):
   1. settings.json → 'obsidian_vault'
   2. settings.json → 'obsidian_vaults' (list, first entry)
-  3. C:/Users/<user>/Documents/Obsidian Vault
-  4. C:/Users/<user>/Obsidian
-  5. D:/Obsidian
+  3. cross-platform conventional locations under $HOME
+  4. host-specific locations (OneDrive on Windows, iCloud on macOS,
+     Nextcloud/Dropbox and container mounts on Linux)
+
+A vault is optional — SkynetClaw runs without one; the Scout's four tools
+simply report that none is configured.
 """
 from __future__ import annotations
-import json, os, re
+import json, os, re, sys
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -42,15 +45,36 @@ def get_vault() -> Optional[Path]:
     if isinstance(s.get("obsidian_vaults"), list) and s["obsidian_vaults"]:
         candidates.append(s["obsidian_vaults"][0])
 
-    # OS-typical paths
+    # OS-typical paths. The same Obsidian install lives somewhere different on
+    # each platform, so probe the host's conventions rather than assuming one.
     home = Path.home()
     candidates += [
         str(home / "Documents" / "Obsidian Vault"),
         str(home / "Obsidian"),
-        str(home / "OneDrive" / "Documents" / "Obsidian Vault"),
-        "D:/Obsidian",
-        "D:/Notes",
+        str(home / "Notes"),
+        str(home / "vault"),
     ]
+    if os.name == "nt":                                     # Windows
+        candidates += [
+            str(home / "OneDrive" / "Documents" / "Obsidian Vault"),
+            str(home / "OneDrive" / "Obsidian"),
+            "D:/Obsidian",
+            "D:/Notes",
+        ]
+    elif sys.platform == "darwin":                          # macOS
+        candidates += [
+            str(home / "Library" / "Mobile Documents"
+                / "iCloud~md~obsidian" / "Documents"),      # iCloud-synced vaults
+            str(home / "Documents" / "Obsidian"),
+        ]
+    else:                                                    # Linux / BSD
+        candidates += [
+            str(home / "Nextcloud" / "Obsidian"),
+            str(home / "Dropbox" / "Obsidian"),
+            str(home / "Sync" / "Obsidian"),
+            "/vault",                                        # docker-compose mount
+            "/data/obsidian",
+        ]
     for c in candidates:
         p = Path(c)
         if p.exists() and p.is_dir():

docs/INSTALL.md

@@ -155,6 +155,8 @@ personal file has crept in.
 
 Choosing and mixing models: **[MODELS.md](MODELS.md)**.
 
+Linux specifics — packages, discovery paths, systemd: **[LINUX.md](LINUX.md)**.
+
 ---
 
 ## Before enabling execution

docs/LINUX.md

@@ -0,0 +1,176 @@
+# Running SkynetClaw on Linux
+
+SkynetClaw is developed on Windows but the backend is platform-neutral, and CI
+proves that on Ubuntu on every push. This page covers what a Linux install
+actually needs.
+
+---
+
+## Quick path
+
+```bash
+git clone https://github.com/ElmatadorZ/skynetclaw.git
+cd skynetclaw
+./start.sh
+```
+
+`start.sh` creates the virtualenv, installs the five dependencies, seeds both
+config templates, runs the database migration, warns if Ollama is unreachable,
+and starts the server. It is idempotent — run it again any time.
+
+Or with `make`:
+
+```bash
+make setup && make run
+```
+
+Or skip Python entirely:
+
+```bash
+docker compose up -d
+docker compose exec ollama ollama pull llama3.1:8b
+```
+
+---
+
+## System packages
+
+Only Python is strictly required. Everything else is optional and degrades
+gracefully — a missing component disables one capability, it does not stop the
+system.
+
+### Debian / Ubuntu
+
+```bash
+sudo apt update
+sudo apt install -y python3 python3-venv python3-pip curl
+
+# optional — OCR for scanned PDFs and images
+sudo apt install -y tesseract-ocr tesseract-ocr-tha
+```
+
+### Fedora / RHEL
+
+```bash
+sudo dnf install -y python3 python3-pip curl
+sudo dnf install -y tesseract tesseract-langpack-tha      # optional
+```
+
+### Arch
+
+```bash
+sudo pacman -S python python-pip curl
+sudo pacman -S tesseract tesseract-data-tha               # optional
+```
+
+OCR is discovered from `PATH` first, so a package-manager install needs no
+configuration. Without it, `doc_reader` simply reports that OCR is unavailable.
+
+---
+
+## A local model
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+ollama serve &                    # or: systemctl --user start ollama
+ollama pull llama3.1:8b
+ollama pull qwen2.5-coder:7b      # the execution path
+```
+
+**No GPU required.** A 7–8B model runs on CPU; it is slower, not broken. With an
+NVIDIA GPU and the container toolkit installed, Ollama uses it automatically.
+
+Full provider matrix, including cloud APIs: **[MODELS.md](MODELS.md)**.
+
+---
+
+## What Linux discovers automatically
+
+These were Windows-shaped and are now probed per platform:
+
+| Capability | Linux locations searched |
+|---|---|
+| **Obsidian vault** | `~/Documents/Obsidian Vault`, `~/Obsidian`, `~/Notes`, `~/vault`, `~/Nextcloud/Obsidian`, `~/Dropbox/Obsidian`, `~/Sync/Obsidian`, `/vault`, `/data/obsidian` |
+| **Obsidian vault registry** | `$XDG_CONFIG_HOME/obsidian/obsidian.json`, `~/.config/obsidian/obsidian.json`, and the Flatpak path under `~/.var/app/md.obsidian.Obsidian/` |
+| **Tesseract binary** | `PATH`, then `/usr/bin`, `/usr/local/bin`, `/opt/homebrew/bin`, `/snap/bin` |
+| **tessdata** | `$TESSDATA_PREFIX`, `/usr/share/tesseract-ocr/5/tessdata`, `/usr/share/tessdata`, `/usr/local/share/tessdata` |
+| **Agent workspace** | `~/Desktop/workspace` when a Desktop exists, otherwise `~/skynetclaw-workspace` — headless servers and non-English XDG names are handled |
+
+Set an explicit vault path in `backend/settings.json` to skip discovery entirely.
+
+---
+
+## Shell execution on Linux
+
+The agent's `shell_command` tool runs through the platform's own shell. The
+system already branches on `os.name`, so PowerShell-specific handling applies
+only on Windows; on Linux commands go to `/bin/sh` unchanged.
+
+This is the highest-risk capability in the system. The GPS-2 gate is
+deny-by-default and irreversible actions require a human gate — leave those on.
+See [NOTICE](../NOTICE).
+
+---
+
+## Running as a service
+
+`systemd --user` unit, adjusting `WorkingDirectory`:
+
+```ini
+# ~/.config/systemd/user/skynetclaw.service
+[Unit]
+Description=SkynetClaw
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/skynetclaw
+ExecStart=%h/skynetclaw/start.sh
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now skynetclaw
+systemctl --user status skynetclaw
+journalctl --user -u skynetclaw -f
+```
+
+For a system-wide unit, run it as a dedicated unprivileged user whose home is the
+only workspace the agent can reach.
+
+---
+
+## Ports
+
+| Port | Service | Bound to |
+|---|---|---|
+| 8766 | SkynetClaw backend | `127.0.0.1` by default |
+| 11434 | Ollama | localhost |
+| 8080 | execution runtime (optional) | localhost |
+
+The backend binds to loopback deliberately. **Do not expose 8766 to a network**
+without putting authentication in front of it — the API can run tools and write
+files, and it has no built-in authentication.
+
+---
+
+## Known Linux gaps
+
+Stated rather than discovered later:
+
+- **`.bat` / `.ps1` launchers do not apply.** Use `start.sh`, `make`, or Docker.
+- **macOS is not in CI.** It should work — the Linux code path is POSIX — but it
+  is untested, so it is marked as such in the README rather than claimed.
+- **Tesseract language data** for non-English OCR must be installed separately
+  (`tesseract-ocr-tha` and friends).
+- **File-path handling in agent prompts** is written with Windows examples in
+  places. It functions on Linux, but a model may occasionally produce
+  Windows-style guidance in its explanations.
+
+If you hit something else, please open an issue with the distribution, the
+Python version, and the failing output.