README.md

@@ -12,6 +12,7 @@ abbreviation system for keyboard-driven workflows.
 - [Overview](#overview)
 - [Session Logging](#session-logging)
 - [Documentation](#documentation)
+- [OS Compatibility](#os-compatibility)
 - [Installation](#installation)
 - [Personalization](#personalization)
 - [Minimal Mode](#minimal-mode)
@@ -170,6 +171,36 @@ The pager falls back through: **ov** → **bat** → **man -l** → **less** →
 
 ---
 
+## OS Compatibility
+
+This is a **Linux-only** configuration. It is developed and tested on an
+Arch Linux system; `fish-deps` also detects `apt`, `dnf`, `zypper`, and `yum`
+for broader distro support, but coverage outside Arch is thinner.
+
+A number of functions call Linux-specific subsystems directly, with no
+fallback: `systemd-inhibit` (`wake-lock`), `zramctl`/`swapon` (`swapstat`),
+`sbctl` and UEFI Secure Boot state (`sbver`), `wl-copy`/`xclip` for clipboard
+access (`y`, `p`, `paste`, `hist` — Wayland or X11 only, no `pbcopy`/`pbpaste`
+fallback), and GNU coreutils flags like `stat -c`/`numfmt` (`sudo-toggle`,
+`dng2avif`), which differ or don't exist under a BSD userland.
+
+**macOS** is not supported — `_fish_deps_detect_pm` checks for `brew`, but
+that alone doesn't make the functions above work; they have no macOS
+equivalent path today.
+
+**Windows** is not supported. Fish has no native Windows build, and this
+config isn't tested under WSL either. WSL2 can run `systemd`, so basic shell
+use may work, but Secure Boot/zram state is meaningless inside a VM and
+clipboard integration has no WSL-specific path here.
+
+**Assumed present on any Linux system this runs on:** `git`, `gpg`, `tar`,
+and GNU coreutils. These aren't tracked by `fish-deps` — they're base-system
+utilities, not opt-in software with an install journey to manage.
+
+See [OS Compatibility](https://fish.rootiest.fyi/10-installation/#os-compatibility) in the project wiki for more.
+
+---
+
 ## Installation
 
 This config is managed as a Git repository. To use it on a new machine:

docs/fish-config.index

@@ -360,6 +360,15 @@ fish-plugins-manifest=## fish_plugins Manifest
 # ── Section 10: Installation ────────────────────────────────────
 installation=# 10. INSTALLATION
 install=# 10. INSTALLATION
+os=## OS Compatibility
+os-compatibility=## OS Compatibility
+operating-system=## OS Compatibility
+compatibility=## OS Compatibility
+linux=## OS Compatibility
+macos=## OS Compatibility
+mac=## OS Compatibility
+windows=## OS Compatibility
+wsl=## OS Compatibility
 sentinel=## Return Sentinel
 updating=## Updating
 

docs/manual/10-installation.md

@@ -6,6 +6,13 @@ sidebar:
 helpKeywords:
 - installation
 - install
+- os
+- operating system
+- compatibility
+- linux
+- macos
+- windows
+- wsl
 ---
 
 This configuration is managed as a git repository. To deploy on a new machine:
@@ -17,6 +24,41 @@ Then open a new Fish shell. Fisher installs automatically on first launch
 and the Catppuccin Mocha theme is applied. All other plugin functionality is
 bundled directly with this config and requires no additional installation.
 
+## OS Compatibility
+
+This is a **Linux-only** configuration. It is developed and tested on an
+Arch Linux system; `fish-deps` also detects `apt`, `dnf`, `zypper`, and
+`yum` for broader distro support, but coverage outside Arch is thinner.
+
+IMPORTANT: A number of functions call Linux-specific subsystems directly, with
+no fallback:
+- `systemd-inhibit` (`wake-lock`)
+- `zramctl` / `swapon` (`swapstat`)
+- `sbctl` and UEFI Secure Boot state (`sbver`)
+- `wl-copy` / `xclip` for clipboard access (`y`, `p`, `paste`, `hist`) —
+  Wayland or X11 only, no `pbcopy`/`pbpaste` fallback
+- GNU coreutils flags such as `stat -c` and `numfmt` (`sudo-toggle`,
+  `dng2avif`), which differ or don't exist under a BSD userland
+
+**macOS** is not supported. `_fish_deps_detect_pm` does check for `brew`, but
+that alone does not make the functions above work — they have no macOS
+equivalent path today.
+
+**Windows** is not supported. Fish itself has no native Windows build;
+upstream's own "Windows" install docs are Cygwin/WSL workarounds, not a real
+port. This config is not tested under WSL either. WSL2 runs a real Linux
+kernel and can run `systemd`, so basic shell use may work, but `zramctl`,
+`sbctl`, and Secure Boot state are meaningless inside a VM, and clipboard
+integration would need a WSL-specific path (`clip.exe`, `win32yank`) that
+does not exist here.
+
+**Assumed present on any Linux system this runs on:** `git`, `gpg`, `tar`,
+and GNU coreutils (for `stat`, `date`, `numfmt`). These are not tracked by
+`fish-deps` — see the [Dependency Catalog](/06-dependency-catalog/) — because
+they are base-system utilities, not opt-in software with an install journey
+to manage. A system missing any of them is missing basic Linux tooling, not
+a `fish-deps` gap.
+
 ## Return Sentinel
 
 `config.fish` ends with a return sentinel guard. Any lines appended after it by