> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryoku.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Desktop tour

> The Ryoku shell surfaces you meet on the desktop, and where the desktop's files live.

Ryoku's desktop is Hyprland + the Ryoku shell. Hyprland composites, handles
input, and tiles windows; the Ryoku shell — a Quickshell (QML) frontend driven
by the `ryoku-shell` Go daemon — paints everything else: the frame, the pill,
the launcher, the overview, the screenshot tool, and the desktop widgets.

This page is a map of those surfaces. For the keyboard workflow — opening,
focusing, moving, and tiling windows — see [Navigation](/docs/navigation); to
configure any of it, see [Settings](/docs/settings).

## Shell surfaces

* **Frame.** The rounded screen border and the popouts that melt into it.
  Always present; it is the desktop's signature chrome.
* **Pill.** The morphing bar at the top of the screen, and its popouts. It has
  three island styles set in Ryoku Settings — the fused island, a floating
  pill, or none — each optionally revealed on hover; the frame stays the same in
  all three. Notifications, the update island, and the GNOME keyring prompt all
  grow from the pill, and it swells into the **control deck** (`Mod + D`: stash,
  tools, and utilities).
* **Launcher.** The command palette (`Mod + Space`): apps plus quick prefixes —
  `=` calc, `;` clipboard, `?` web, `/` actions, `@` YouTube Music, and `\` a
  Rashin ask — over a zero-query rest card with the solar-arc clock and weather.
* **Overview.** The full-screen workspace expo (`Mod + Tab`): scaled
  mini-desktops with live window previews. Click to switch or focus, drag
  windows between workspaces, and step between desktops. The
  [Navigation](/docs/navigation) page covers it in full.
* **Switcher.** A full-screen most-recently-used window switcher. Day to day you
  cycle windows through the overview above and directional focus (`Mod + Arrow`);
  see [Navigation](/docs/navigation).
* **Ryoshot.** Screenshot capture (full screen, region, or window) and
  annotation — rectangles, arrows, pen, marker, blur, and text, with undo/redo.
  `Mod + S` opens it; shots save as PNG to `~/Pictures/Screenshots`.
* **Keyring island.** The GNOME keyring password prompt, grown from the pill
  centre rather than a floating dialog. System-driven — it appears when an app
  needs your keyring unlocked.
* **Desktop widgets.** The clock and weather painted on the wallpaper.
  Right-click to move or configure; enable and lay them out from
  [Settings](/docs/settings) → Desktop Widgets.

The Go daemon (`ryoku-shell`, in `ryoku/shell/ipc/`) is the control plane: it
supervises the persistent components and decides what is on screen, and the QML
frontend renders it. Theme tokens flow from the wallpaper through `wallust`, so
picking a new wallpaper repaints every surface without restarting anything.

## Getting around

Nothing is open when you log in — Hyprland is a tiling compositor, so it only
shows what you launch. Open a window with `Mod + Return`, move focus with
`Mod + Arrow`, and switch workspaces with `Mod + 1 … 0`.

[Navigation](/docs/navigation) walks the whole workflow — opening, focusing,
moving, resizing, floating, workspaces, the scratchpad, and multi-monitor.
[Keybindings](/docs/keybindings) is the exhaustive bind reference.

## Where things live

| Thing                                                        | Path                                                                             |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Hyprland entry point                                         | `~/.config/hypr/hyprland.lua`                                                    |
| Personal Hyprland overrides (loaded last, yours always win)  | `~/.config/hypr/user.lua`                                                        |
| Manual monitor pinning                                       | `~/.config/hypr/monitors_user.lua` (see the shipped `monitors_user.lua.example`) |
| Generated seeds (written once on first run, never clobbered) | `~/.config/hypr/monitors.lua`, `~/.config/hypr/gpu.lua`                          |
| What Ryoku Settings writes                                   | `~/.config/hypr/settings.lua` and the shell config                               |
| Wallpapers                                                   | `~/Pictures/Wallpapers`                                                          |
| Per-app native overrides (left alone by updates)             | `~/.config/kitty/user.conf`, `~/.config/fish/user.fish`, etc.                    |

The Hyprland load order from `hyprland.lua` is: base modules, then the active
`theme`, then `settings` (what the Hub writes), then `user` (your overrides,
which win). [Customize](/docs/customize) covers what to put in each layer, and
[Settings](/docs/settings) documents the Hub that writes the `settings` layer.

## Logs

```bash theme={"dark"}
# The shell daemon log (refresh it with: ryoku reload)
tail -f ~/.local/state/ryoku-shell.log

# Hyprland compositor state
hyprctl monitors
hyprctl binds
```

`ryoku-shell` is autostarted by Hyprland at login; `ryoku reload` restarts it
and rewrites the log above.

## Next steps

* [Navigation](/docs/navigation): the keyboard workflow for windows and
  workspaces.
* [Settings](/docs/settings): the Hub — every panel that configures the desktop.
* [Keybindings](/docs/keybindings): the full shipped reference.
* [Customize](/docs/customize): wallpapers, themes, and `user.lua` overrides.