Document full installation and update links for ferese-wm

README.md

@@ -45,22 +45,26 @@ rules, displays, widgets and login items are configurable too. Start with the
 
 ## Install
 
-The current installation guide covers Fedora with SDDM. After installing the
+Install Ferese on Linux with any Wayland-capable login manager, a command-based
-[prerequisites](docs/installation.md), run:
+greeter, or a local TTY. Start with the [installation guide](docs/installation.md)
+for system dependencies and Rust 1.95 or newer, then build as your normal user:
 
 ```sh
+git clone https://github.com/ferese-wm/ferese.git
+cd ferese
 ./scripts/install.sh
 ```
 
-Log out, select **Ferese** at the login screen, and sign in. The installer keeps
+Log out and select **Ferese** at your login screen. For greeters that take a
-your configuration and the previous release for rollback. See
+session command, use `/usr/local/bin/ferese-session`. The installer preserves
-[installation and recovery](docs/installation.md) for the full setup and safety
+your configuration and other sessions, and retains the previous release for
-notes.
+rollback. The guide covers [all startup methods](docs/installation.md#start-a-session),
+optional tools, updates, and recovery.
 
 To preview Ferese inside your current Wayland desktop instead:
 
 ```sh
-cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl
+cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl -p ferese-lock
 target/release/ferese --backend nested --grant-effects --grant-shell-control -- \
   target/release/ferese-shell
 ```
@@ -87,6 +91,7 @@ Settings → Shortcuts** to change them or assign gestures to other actions.
 - [Configuration reference](docs/configuration.md)
 - [Desktop widgets](docs/desktop-widgets.md)
 - [Notifications](docs/notifications.md)
+- [Native locker](docs/locking.md)
 
 ## Development
 

docs/installation.md

@@ -1,35 +1,201 @@
 # Installation
 
+Ferese runs on Linux and installs as a standalone Wayland session. Use any login
+manager that can launch Wayland sessions, a command-based greeter, or a local
+TTY. You do not need to replace your existing login manager or desktop.
+
+## Requirements
+
+You need a working graphics driver with DRM/KMS and EGL support, an authenticated
+local login session with seat access through logind or seatd, D-Bus, and
+Linux-PAM for the native locker. A nested preview needs an existing Wayland
+desktop instead of direct access to the graphics device.
+
+Build with **Rust 1.95 or newer**, a C/C++ toolchain, CMake, pkg-config, and the
+native development libraries below. The installer builds Ferese, its shell,
+Settings, command-line tools, and locker together. It does not install system
+packages or enable services for you.
+
+### Fedora
+
+```sh
+sudo dnf install git curl gcc gcc-c++ make cmake pkgconf-pkg-config \
+  wayland-devel libxkbcommon-devel libinput-devel systemd-devel libseat-devel \
+  mesa-libgbm-devel mesa-libEGL-devel libdrm-devel fontconfig-devel \
+  freetype-devel expat-devel dbus-daemon dbus-tools desktop-file-utils foot pam
+```
+
+### Arch Linux
+
+```sh
+sudo pacman -S --needed base-devel git curl cmake pkgconf wayland libxkbcommon \
+  libinput systemd seatd mesa libdrm fontconfig freetype2 expat dbus \
+  desktop-file-utils foot pam
+```
+
+### Debian and Ubuntu
+
+```sh
+sudo apt update
+sudo apt install build-essential git curl cmake pkg-config libwayland-dev \
+  libxkbcommon-dev libinput-dev libudev-dev libseat-dev libgbm-dev libegl-dev \
+  libdrm-dev libfontconfig1-dev libfreetype-dev libexpat1-dev dbus-bin \
+  dbus-user-session desktop-file-utils foot libpam0g
+```
+
+These are package recipes, not a claim that every distribution release has been
+tested. Fedora is the currently exercised installation path. Older releases
+may need newer packages or additional repositories. For other distributions,
+install the equivalent libraries; see the upstream
+[Smithay dependencies](https://github.com/Smithay/smithay#system-dependencies).
+
+### Rust toolchain
+
+Check your toolchain:
+
+```sh
+rustc --version
+cargo --version
+```
+
+If Rust is missing, install it using the instructions at
+[rustup.rs](https://rustup.rs/), then reopen your terminal. With rustup installed,
+you can select the required version for this checkout after cloning:
+
+```sh
+rustup toolchain install 1.95.0
+rustup override set 1.95.0
+```
+
 ## Build and install
 
-On Fedora with SDDM, install a Rust toolchain (1.95 or newer), native build
+Run these commands as your normal user:
-dependencies, `desktop-file-utils`, D-Bus and `foot`. Wallpaper browsing also
-needs `zenity`; locking needs swaylock or swaylock-effects.
-Screenshots need `grim`, `slurp`, `satty`, `wl-clipboard`, and Python 3.
-Print Screen captures the active monitor; Super+Shift+S selects an area.
-Use `ferese-screenshot --all` to capture all monitors in one image.
-
-Clone the repository, then run the installer as your normal user:
 
 ```sh
-git clone https://github.com/borngraced/ferese.git
+git clone https://github.com/ferese-wm/ferese.git
 cd ferese
 ./scripts/install.sh
 ```
 
-The script builds locked release binaries, then requests elevation to install.
+The script builds locked release binaries, then requests administrator access
-It preserves your configuration and other desktop sessions. Log out and select
+through `sudo` or `pkexec` for installation. Do not run the whole build as root.
-**Ferese** at the login screen. Upgrades require logging out and back in too.
+The first build needs network access to fetch Rust dependencies.
+
+The installer adds:
+
+- Versioned releases under `/usr/local/lib/ferese/releases/`, with `current` and
+  `previous` links for upgrades and rollback.
+- Commands under `/usr/local/bin/`, including `ferese-session`, `ferese-settings`,
+  `feresectl`, `ferese-lock`, and `ferese-screenshot`.
+- A Wayland session entry at `/usr/share/wayland-sessions/ferese.desktop`.
+- A Settings application entry, icons, the default wallpaper, and an example config.
+- `/etc/pam.d/ferese-lock`, using your distribution's authentication stack.
+  An existing administrator-supplied policy is preserved.
+
+Your existing configuration and other desktop sessions are preserved. The
+installer does not change your default session or login manager.
+
+### Initial configuration
+
+Ferese has built-in defaults. To start from the example without replacing an
+existing config:
 
 ```sh
-./scripts/install.sh --dry-run
+mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/ferese"
-./scripts/install.sh --offline --release-id my-build
+if [ ! -e "${XDG_CONFIG_HOME:-$HOME/.config}/ferese/config.kdl" ]; then
-./scripts/install.sh --skip-build
+  cp /usr/local/lib/ferese/current/config.example.kdl \
+    "${XDG_CONFIG_HOME:-$HOME/.config}/ferese/config.kdl"
+fi
 ```
 
-Use `--help` for all options. New configs can be copied from
+Open **Control Center → Settings** after login, or run `ferese-settings`.
-`/usr/local/lib/ferese/current/config.example.kdl` to
+See [Configuration](configuration.md) for themes, displays, shortcuts, and startup
-`~/.config/ferese/config.kdl`. See [Configuration](configuration.md).
+applications. The default terminal shortcut uses `foot`; change the terminal
+command in Settings if you prefer another terminal.
+
+## Start a session
+
+### Graphical login managers
+
+Save your work and log out. Open your login screen's session selector, choose
+**Ferese**, and sign in. Any manager that supports Wayland sessions and reads
+`/usr/share/wayland-sessions/` can discover the installed entry. The selector's
+location and whether it appears before or after choosing your account depend
+on the login manager.
+
+If Ferese is missing, confirm that the session entry exists and its launcher is
+executable:
+
+```sh
+ls -l /usr/share/wayland-sessions/ferese.desktop
+test -x /usr/local/bin/ferese-session && echo "Session launcher is ready"
+desktop-file-validate /usr/share/wayland-sessions/ferese.desktop
+```
+
+Check your manager's documentation for enabling Wayland session discovery. A
+manager that only launches X11 sessions cannot start Ferese through that path;
+use a Wayland-capable greeter or the TTY method below.
+
+### Command-based greeters
+
+If your greeter asks for a session command instead of reading desktop files, use:
+
+```sh
+/usr/local/bin/ferese-session
+```
+
+For a setup such as greetd, configure that as the command launched **after user
+authentication**, using your greeter's session-command option. Preserve the
+existing authentication and greeter configuration. Do not set Ferese itself as
+the privileged greeter process. See the
+[greetd documentation](https://sr.ht/~kennylevinsen/greetd/) for your chosen frontend.
+
+The launcher starts the compositor and shell together, sets the desktop
+environment variables, and starts a D-Bus session when one is not already
+available. Launch it instead of the bare compositor for a complete desktop.
+
+### From a TTY
+
+Log out of the graphical session, switch to a local console with
+**Ctrl+Alt+F2** (or another available function key), and sign in as your normal
+user. Then run:
+
+```sh
+/usr/local/bin/ferese-session
+```
+
+Your login must provide `XDG_RUNTIME_DIR` and access to the active seat through
+logind or seatd. If either is missing, fix the distribution's login/session setup;
+do not work around it by running Ferese as root or making device nodes writable.
+For non-systemd systems, follow your distribution's seatd and user-session setup.
+Do not start the DRM backend inside an existing graphical session; use a nested
+preview there.
+
+## Optional desktop tools
+
+Install these through your distribution when you want the corresponding features:
+
+| Feature | Tools or services |
+| --- | --- |
+| Wallpaper file picker | `zenity` |
+| Screenshots and editing | `grim`, `slurp`, `satty`, `wl-clipboard`, Python 3 |
+| Idle locking | `swayidle` with the included `ferese-lock` |
+| Network controls | NetworkManager and its running service |
+| Audio controls | PipeWire, WirePlumber, and `wpctl` |
+| Bluetooth controls | BlueZ, `bluetoothctl`, and its running service |
+
+Package names and availability vary by distribution. In particular, install
+Satty using its [upstream instructions](https://github.com/Satty-org/Satty#install)
+if your repositories do not provide it. Ferese does not enable these services
+or replace your existing service configuration during installation.
+
+Print Screen captures the active monitor; **Super+Shift+S** selects an area.
+Use `ferese-screenshot --all` to capture all monitors in one image.
+
+The native locker follows your shell theme. Open **Settings → Lock Screen** to
+customize it, or run `ferese-lock --preview` to see an ordinary preview window.
+Test real unlocking before enabling automatic locking; see
+[Native locker](locking.md) for authentication, idle locking, and limitations.
 
 ## Preview and logs
 
@@ -37,32 +203,99 @@ To preview a source build before installing, run these commands from the checkou
 inside an existing Wayland desktop:
 
 ```sh
-cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl
+cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl -p ferese-lock
 target/release/ferese --backend nested --grant-effects --grant-shell-control -- \
   target/release/ferese-shell
 ```
 
+After installation, the equivalent launcher is:
 
-Run `ferese-session --nested` inside an existing Wayland desktop. For a hardware
+```sh
-session, use the login screen or a spare TTY; never run Ferese as root or start
+ferese-session --nested
-its DRM backend inside an active graphical session.
+```
 
-Logs are stored in `${XDG_STATE_HOME:-~/.local/state}/ferese/`. Keep an existing
+The session launcher stores logs in `${XDG_STATE_HOME:-$HOME/.local/state}/ferese/`.
-desktop available while testing scaling, monitor hotplug, suspend and locking.
+A directly launched source build writes to its terminal. Keep another desktop
+available while testing scaling, monitor hotplug, suspend, and locking.
 
-The session launcher enables the screencopy protocol for screenshot tools.
+The launcher enables the screencopy protocol for screenshot tools. Set
-Set `FERESE_ENABLE_SCREENCOPY=0` in the session environment to disable it.
+`FERESE_ENABLE_SCREENCOPY=0` in the session environment to disable it. When
-When enabled, Wayland clients can capture the unlocked desktop. Capture remains
+enabled, Wayland clients can capture the unlocked desktop. Capture remains
 blocked while the session is locked. Launcher changes take effect at next login.
 
+## Updating
+
+From your existing checkout, with any local edits saved:
+
+```sh
+git pull --ff-only
+./scripts/install.sh
+```
+
+Log out and back in to use the new release. Running sessions keep their existing
+processes and release paths until restarted.
+
+Installer options:
+
+```sh
+./scripts/install.sh --dry-run
+./scripts/install.sh --offline --release-id my-build
+./scripts/install.sh --skip-build
+```
+
+`--dry-run` prints the planned commands. `--offline` requires dependencies to be
+cached already. `--skip-build` installs the binaries already in `target/release/`;
+use it only after building all five components from the intended revision.
+Run `./scripts/install.sh --help` for all options.
+
 ## Logout and recovery
 
 Save your work before **Super+Shift+E** or `feresectl exit`: logout is immediate.
-If frozen, switch to another TTY with Ctrl+Alt+F1–F12, terminate the specific
+If Ferese freezes, switch to another TTY with **Ctrl+Alt+F1–F12**, sign in, and
-Ferese process, and select your other desktop on the next login. Restarting SDDM
+identify the affected compositor process:
-also ends other sessions, so avoid it with unsaved work.
 
-Installed binaries live in `/usr/local/lib/ferese/releases/`. While Ferese is
+```sh
-stopped, select a retained release with the `current` symlink; `previous` points
+pgrep -a -u "$USER" -x ferese
-to the prior installation. To hide the session option, move
+```
-`/usr/share/wayland-sessions/ferese.desktop` out of that directory.
+
+Terminate only that session's process with `kill PID`, replacing `PID` with the
+correct process ID. This ends its applications and can lose unsaved work. You
+can then select your other desktop at the next login.
+
+### Roll back a release
+
+While Ferese is stopped, inspect the retained releases:
+
+```sh
+readlink /usr/local/lib/ferese/current
+readlink /usr/local/lib/ferese/previous
+ls /usr/local/lib/ferese/releases/
+```
+
+If `previous` exists and points to the release you want, switch back:
+
+```sh
+sudo sh -eu -c '
+  cd /usr/local/lib/ferese
+  previous_release=$(readlink previous)
+  test -x "$previous_release/ferese-session"
+  ln -sfn -- "$previous_release" current-rollback
+  mv -Tf -- current-rollback current
+'
+```
+
+Then log in again. This changes the selected binaries; it does not restore your
+config or replace the PAM policy. Settings keeps a backup when saving config
+changes; see [Saving and validation](configuration.md#saving-and-validation).
+
+### Remove the login option
+
+To hide Ferese from login managers while keeping its releases and your config:
+
+```sh
+sudo mv /usr/share/wayland-sessions/ferese.desktop \
+  /usr/local/lib/ferese/ferese.desktop.disabled
+```
+
+For a command-based greeter, remove Ferese from its session choices using that
+greeter's configuration. Reinstalling restores the desktop session entry.

scripts/build-site.py

@@ -10,13 +10,14 @@ from markdown_it import MarkdownIt
 
 ROOT = Path(__file__).resolve().parent.parent
 OUTPUT = ROOT / 'build' / 'site'
-REPO = 'https://github.com/borngraced/ferese'
+REPO = 'https://github.com/ferese-wm/ferese'
 PAGES = [
     ('index', 'Introduction', ROOT / 'site/content/index.md'),
     ('installation', 'Installation', ROOT / 'docs/installation.md'),
     ('configuration', 'Configuration', ROOT / 'docs/configuration.md'),
     ('desktop-widgets', 'Desktop widgets', ROOT / 'docs/desktop-widgets.md'),
     ('notifications', 'Notifications', ROOT / 'docs/notifications.md'),
+    ('locking', 'Native locker', ROOT / 'docs/locking.md'),
 ]
 md = MarkdownIt('commonmark', {'html': False}).enable('table')
 OUTPUT.mkdir(parents=True, exist_ok=True)

site/README.md

@@ -28,7 +28,7 @@ site sources or Markdown guides, then refresh the browser.
 
 Select **Settings → Pages → Source → GitHub Actions**. The Pages workflow
 publishes site and documentation changes pushed to `main`, or can run manually.
-Expected URL: https://borngraced.github.io/ferese/.
+Expected URL: https://ferese-wm.github.io/ferese/.
 
 Local links are relative, including documentation search, so publishing under
 the `/ferese/` project path works. Screenshots are copied from `docs/images`

site/content/index.md

@@ -6,7 +6,7 @@ This handbook covers installing Ferese, finding your way around, and making the
 
 ## Start with your first session
 
-1. Read [Installation](installation.md) for the supported setup, building, and recovery.
+1. Read [Installation](installation.md) for dependencies, building, login-manager or TTY startup, and recovery.
 2. Open **Control Center → Settings** to choose a theme and configure your desktop.
 3. Explore the [configuration reference](configuration.md) for layouts, shortcuts, window rules, and displays.
 
@@ -31,6 +31,8 @@ Three-finger swipes move between workspaces and windows. Open **Control Center
 
 Use **Settings** for everyday customization. Choose an appearance preset, change the wallpaper, adjust shell and window corners, or add a clock and sticky notes through [Desktop widgets](desktop-widgets.md).
 
+[Native locker](locking.md) covers lock-screen appearance, authentication, and idle locking.
+
 [Notifications](notifications.md) explains popup cards, history, Do Not Disturb, and app actions.
 
 If you prefer a text editor, your configuration lives at:
@@ -56,4 +58,4 @@ cargo test --workspace --locked
 cargo fmt --all --check
 ```
 
-The [source repository](https://github.com/borngraced/ferese) is the place to explore implementation details and report issues. When reporting a problem, include how to reproduce it, whether you used the nested or DRM backend, and relevant logs.
+The [source repository](https://github.com/ferese-wm/ferese) is the place to explore implementation details and report issues. When reporting a problem, include how to reproduce it, whether you used the nested or DRM backend, and relevant logs.

site/index.html

@@ -19,7 +19,7 @@
     <meta property="og:type" content="website" />
     <meta
       property="og:image"
-      content="https://borngraced.github.io/ferese/assets/ferese-desktop.png"
+      content="https://ferese-wm.github.io/ferese/assets/ferese-desktop.png"
     />
     <meta name="twitter:card" content="summary_large_image" />
     <title>Ferese — A desktop that feels like yours</title>
@@ -38,7 +38,7 @@
         <nav aria-label="Main navigation">
           <a href="./" aria-current="page">Overview</a
           ><a href="docs/">Documentation</a
-          ><a href="https://github.com/borngraced/ferese"
+          ><a href="https://github.com/ferese-wm/ferese"
             >GitHub <svg class="link-arrow" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M7 17 17 7M7 7h10v10"/></svg></a
           >
         </nav>
@@ -56,7 +56,7 @@
         <div class="product-links">
           <a class="button" href="docs/installation.html">Install Ferese</a>
           <a class="button secondary" href="docs/">Documentation</a>
-          <a class="source-link" href="https://github.com/borngraced/ferese"
+          <a class="source-link" href="https://github.com/ferese-wm/ferese"
             >Source code <svg class="link-arrow" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M7 17 17 7M7 7h10v10"/></svg></a
           >
         </div>
@@ -108,13 +108,13 @@
         <h2>Getting started</h2>
         <p>
           The <a href="docs/installation.html">installation guide</a> covers
-          Fedora with SDDM. You can also
+          dependencies, setup with any Wayland-capable login manager, and TTY startup. You can also
           <a href="docs/installation.html#preview-and-logs">preview Ferese</a>
           inside an existing Wayland session before installing.
         </p>
         <p>
           Built in Rust on Smithay. Development happens
-          <a href="https://github.com/borngraced/ferese">on GitHub</a>.
+          <a href="https://github.com/ferese-wm/ferese">on GitHub</a>.
         </p>
       </section>
     </main>