Ryoku
Ryoku is an Arch Linux desktop: a Hyprland compositor, a single Quickshell shell
that draws the bar, the dock, the launcher, the popouts and the widgets, and a
set of Go command-line tools that own the config. This skill is for changing a
running Ryoku system on behalf of its user. It is not for developing Ryoku
itself (editing the source checkout, writing migrations, cutting a release).
When to use this skill
Use it whenever a request would change the desktop or read its state: the bar
layout and widgets, the dock, Hyprland behaviour, themes and wallpaper, keybinds,
idle and lock, plugins, or any ~/.config file Ryoku owns. If you are about to
guess a path or edit a config file under ~/.config, stop and use this skill.
Do not use it to modify the Ryoku source tree, and never treat a shipped file as
a place to store a user's choice.
Read the vault first
A maintained map of THIS machine lives in the Rashin vault at
~/.local/share/ryoku/rashin/. Read it before searching the filesystem or
guessing where anything lives:
AGENTS.md: the entry contract and the vault's own rules.
desktop.md: the map. Every subsystem, the config path that owns it, the
binary that owns it, and how to reload it. Its generated "Bar and dock"
section lists every bar widget id, its visibility key, and the bar and dock
commands. Read this before touching the bar.
system.md, packages.md, user.md, habits.md: hardware, packages, where
this user diverges from the shipped defaults, and this user's directories and
tool stack.
user.md lists the user's own choices; never revert one to a shipped default
without being asked. Write durable notes to memory/, dated notes to
journal/YYYY-MM-DD.md; never edit inside a rashin:generated fence, a reindex
overwrites it.
Topic guides sit beside this file. Read the matching one first:
bar.md: the QS Bar and the dock, their layout model, and the
ryoku-shell bar / ryoku-shell dock commands.
plugins.md: installing, listing, and removing shell plugins
with ryoku plugin, and Ryostore.
Safety rules
Ryoku separates the files it ships from the files you own, so an update can
refresh the base freely while your changes stand. Respect the split:
- Never edit a shipped file in place.
/usr/share/ryoku/ (the packaged
base) and the files Ryoku lays into ~/.config/quickshell/ are re-laid on
every ryoku update (ryoku materialize clobbers every shipped file), so an
edit there is lost on the next update. Reading them is safe and useful.
- A user override goes to the overlay:
~/.config/ryoku/user_edits/, which
mirrors ~/.config. A file there wins at its mirrored path and survives every
update. To change a shipped Hyprland or app config, drop your version at the
mirrored path under user_edits (a fork), or, better, use the dedicated
override file the tool already reads (hypr/user.lua, hypr/settings.lua,
kitty/user.conf, fish/user.fish), which the package never ships and never
touches. ryoku reset <path> drops an overlay file back to the base.
- Prefer a command over a file edit. The tool that owns a setting is its one
writer; hand-editing its store drifts. Ryoku Settings' own state (bar, colours,
launcher, device lighting) lives under
~/.config/ryoku/*.json, written by
their tools (the shell daemon, ryoku-hub, ryogami); do not hand-edit those
JSON stores, drive them through the command or the GUI so one writer stays in
charge.
Command discovery
Ryoku's behaviour lives behind five command-line tools, all self-documenting.
Prefer a command to a file edit; read a command's --help before running it.
| Tool |
Owns |
ryoku |
Updates, rollback, status, reload, materialize, reset, doctor. See docs/cli.md. |
ryoku-shell |
The live shell: the bar, the dock, menus, popouts, and the shell.json settings store (the sole writer of shell.json). |
ryoku-hub |
Ryoku Settings and the Hyprland config it generates (hypr get, hypr matugen set, ...). |
ryogami |
Wallpapers and the colour palette (`ryogami wallpaper set |
ryoku-rashin |
The optional agent OS: the vault, wiring, the dashboard, index, wire. |
ryoku --help # the ryoku CLI surface
ryoku-shell bar catalog # every bar widget, its id, and its settings
ryoku-shell bar list # the live bar, per section, with shown state
ryogami wallpaper --help
To find WHERE a setting is read (which QML file, which key), use prowl-agent
inside the vault's read-only source mirror at
~/.local/share/ryoku/rashin/source/, which indexes the live ~/.config:
cd ~/.local/share/ryoku/rashin/source && prowl-agent search "barPosition"
cd ~/.local/share/ryoku/rashin/source && prowl-agent find barShellStyle
The mirror is read-only and rebuilt on every reindex; never edit files in it,
edit the real path desktop.md names.
Decision framework
When a request would change the system, in order:
- Is there a command for it? Use it. The bar and dock have a full CLI
(
ryoku-shell bar ..., ryoku-shell dock ..., see bar.md); wallpaper has
ryogami wallpaper set; updates have ryoku update.
- Is it a plugin? A shell widget installs from git with
ryoku plugin add <url> --bar, or from Ryostore; see plugins.md. Never
run a plugin's code to install it. A Hyprland compositor plugin (title
bars, cursor motion, key sounds, a .so the compositor loads) is managed
by ryoku-hub hypr plugins list|rebuild|add|remove and Settings >
Plugins; a "version mismatch" after an update means
ryoku-hub hypr plugins rebuild --stale.
- Is it a config edit with no command? Edit the override, never the shipped
file: the tool's own
user.* file, or a fork at the mirrored path under
~/.config/ryoku/user_edits/. Then reload (ryoku reload, or hyprctl reload for Hyprland).
- Is it a theme or wallpaper? Drive it through
ryogami and ryoku-hub,
which own the colour master; never write the palette or theme shadow by hand.
- Is it a package?
ryoku update for the whole system; pacman/yay for one
package.
- Unsure a command exists? Read the tool's
--help, or desktop.md.
Example requests
- "Move the clock to the right" ->
ryoku-shell bar move clock --section right
- "Hide the GPU widget" ->
ryoku-shell bar hide gpu
- "Show the battery widget again" ->
ryoku-shell bar show battery
- "Put the bar at the bottom" ->
ryoku-shell bar position bottom
- "Make the bar islands" ->
ryoku-shell bar form islands
- "Reset the bar to defaults" ->
ryoku-shell bar defaults
- "Open the bar settings" ->
ryoku-shell bar settings
- "Turn the dock off" ->
ryoku-shell dock hide
- "Pin Firefox to the dock" ->
ryoku-shell dock pin firefox
- "Add a weather plugin from GitHub" ->
ryoku plugin add <git-url> --bar
- "List my installed plugins" ->
ryoku plugin list
- "Lock after ten minutes" -> fork
hypr/hypridle.conf into
~/.config/ryoku/user_edits/hypr/hypridle.conf and set the lock listener's
timeout to 600, then ryoku materialize lays the fork live and
pkill -x hypridle; setsid hypridle -c ~/.config/hypr/hypridle.conf &
restarts the idle daemon on it (hypridle reads its config only at start;
hyprctl reload does not reach it)
- "Change my wallpaper" ->
ryogami wallpaper set <path>
- "Next wallpaper" ->
ryogami wallpaper next
- "Update the system" ->
ryoku update
- "Roll back a bad update" ->
ryoku rollback
1---2name: ryoku3description: >4 Customize a Ryoku desktop: an Arch Linux system with a Hyprland compositor and5 a Quickshell shell (the QS Bar, the dock, widgets, the launcher, and the Hub).6 Use for end-user requests that touch the desktop or its config. Triggers:7 Hyprland, window rules, keybinds, monitors, gaps, borders, the bar, the dock,8 bar widgets, plugins, themes, wallpaper, colours, night light, idle, lock9 screen, and user-facing ryoku commands (ryoku, ryoku-shell, ryoku-hub,10 ryogami, ryoku-rashin). Read the vault first; act through commands, not by11 editing shipped files.12metadata:13 source: https://skillmd.com/skills/neur0map/ryoku14---1516# Ryoku1718Ryoku is an Arch Linux desktop: a Hyprland compositor, a single Quickshell shell19that draws the bar, the dock, the launcher, the popouts and the widgets, and a20set of Go command-line tools that own the config. This skill is for changing a21running Ryoku system on behalf of its user. It is not for developing Ryoku22itself (editing the source checkout, writing migrations, cutting a release).2324## When to use this skill2526Use it whenever a request would change the desktop or read its state: the bar27layout and widgets, the dock, Hyprland behaviour, themes and wallpaper, keybinds,28idle and lock, plugins, or any `~/.config` file Ryoku owns. If you are about to29guess a path or edit a config file under `~/.config`, stop and use this skill.3031Do not use it to modify the Ryoku source tree, and never treat a shipped file as32a place to store a user's choice.3334## Read the vault first3536A maintained map of THIS machine lives in the Rashin vault at37`~/.local/share/ryoku/rashin/`. Read it before searching the filesystem or38guessing where anything lives:3940- `AGENTS.md`: the entry contract and the vault's own rules.41- `desktop.md`: the map. Every subsystem, the config path that owns it, the42 binary that owns it, and how to reload it. Its generated "Bar and dock"43 section lists every bar widget id, its visibility key, and the bar and dock44 commands. Read this before touching the bar.45- `system.md`, `packages.md`, `user.md`, `habits.md`: hardware, packages, where46 this user diverges from the shipped defaults, and this user's directories and47 tool stack.4849`user.md` lists the user's own choices; never revert one to a shipped default50without being asked. Write durable notes to `memory/`, dated notes to51`journal/YYYY-MM-DD.md`; never edit inside a `rashin:generated` fence, a reindex52overwrites it.5354Topic guides sit beside this file. Read the matching one first:5556- [`bar.md`](bar.md): the QS Bar and the dock, their layout model, and the57 `ryoku-shell bar` / `ryoku-shell dock` commands.58- [`plugins.md`](plugins.md): installing, listing, and removing shell plugins59 with `ryoku plugin`, and Ryostore.6061## Safety rules6263Ryoku separates the files it ships from the files you own, so an update can64refresh the base freely while your changes stand. Respect the split:6566- **Never edit a shipped file in place.** `/usr/share/ryoku/` (the packaged67 base) and the files Ryoku lays into `~/.config/quickshell/` are re-laid on68 every `ryoku update` (`ryoku materialize` clobbers every shipped file), so an69 edit there is lost on the next update. Reading them is safe and useful.70- **A user override goes to the overlay:** `~/.config/ryoku/user_edits/`, which71 mirrors `~/.config`. A file there wins at its mirrored path and survives every72 update. To change a shipped Hyprland or app config, drop your version at the73 mirrored path under `user_edits` (a fork), or, better, use the dedicated74 override file the tool already reads (`hypr/user.lua`, `hypr/settings.lua`,75 `kitty/user.conf`, `fish/user.fish`), which the package never ships and never76 touches. `ryoku reset <path>` drops an overlay file back to the base.77- **Prefer a command over a file edit.** The tool that owns a setting is its one78 writer; hand-editing its store drifts. Ryoku Settings' own state (bar, colours,79 launcher, device lighting) lives under `~/.config/ryoku/*.json`, written by80 their tools (the shell daemon, `ryoku-hub`, `ryogami`); do not hand-edit those81 JSON stores, drive them through the command or the GUI so one writer stays in82 charge.8384## Command discovery8586Ryoku's behaviour lives behind five command-line tools, all self-documenting.87Prefer a command to a file edit; read a command's `--help` before running it.8889| Tool | Owns |90|---|---|91| `ryoku` | Updates, rollback, status, reload, materialize, reset, doctor. See `docs/cli.md`. |92| `ryoku-shell` | The live shell: the bar, the dock, menus, popouts, and the `shell.json` settings store (the sole writer of `shell.json`). |93| `ryoku-hub` | Ryoku Settings and the Hyprland config it generates (`hypr get`, `hypr matugen set`, ...). |94| `ryogami` | Wallpapers and the colour palette (`ryogami wallpaper set|next|random`). |95| `ryoku-rashin` | The optional agent OS: the vault, wiring, the dashboard, `index`, `wire`. |9697```bash98ryoku --help # the ryoku CLI surface99ryoku-shell bar catalog # every bar widget, its id, and its settings100ryoku-shell bar list # the live bar, per section, with shown state101ryogami wallpaper --help102```103104To find WHERE a setting is read (which QML file, which key), use `prowl-agent`105inside the vault's read-only source mirror at106`~/.local/share/ryoku/rashin/source/`, which indexes the live `~/.config`:107108```bash109cd ~/.local/share/ryoku/rashin/source && prowl-agent search "barPosition"110cd ~/.local/share/ryoku/rashin/source && prowl-agent find barShellStyle111```112113The mirror is read-only and rebuilt on every reindex; never edit files in it,114edit the real path `desktop.md` names.115116## Decision framework117118When a request would change the system, in order:1191201. **Is there a command for it?** Use it. The bar and dock have a full CLI121 (`ryoku-shell bar ...`, `ryoku-shell dock ...`, see `bar.md`); wallpaper has122 `ryogami wallpaper set`; updates have `ryoku update`.1232. **Is it a plugin?** A shell widget installs from git with124 `ryoku plugin add <url> --bar`, or from Ryostore; see `plugins.md`. Never125 run a plugin's code to install it. A Hyprland compositor plugin (title126 bars, cursor motion, key sounds, a `.so` the compositor loads) is managed127 by `ryoku-hub hypr plugins list|rebuild|add|remove` and Settings >128 Plugins; a "version mismatch" after an update means129 `ryoku-hub hypr plugins rebuild --stale`.1303. **Is it a config edit with no command?** Edit the override, never the shipped131 file: the tool's own `user.*` file, or a fork at the mirrored path under132 `~/.config/ryoku/user_edits/`. Then reload (`ryoku reload`, or `hyprctl133 reload` for Hyprland).1344. **Is it a theme or wallpaper?** Drive it through `ryogami` and `ryoku-hub`,135 which own the colour master; never write the palette or theme shadow by hand.1365. **Is it a package?** `ryoku update` for the whole system; pacman/yay for one137 package.1386. **Unsure a command exists?** Read the tool's `--help`, or `desktop.md`.139140## Example requests141142- "Move the clock to the right" -> `ryoku-shell bar move clock --section right`143- "Hide the GPU widget" -> `ryoku-shell bar hide gpu`144- "Show the battery widget again" -> `ryoku-shell bar show battery`145- "Put the bar at the bottom" -> `ryoku-shell bar position bottom`146- "Make the bar islands" -> `ryoku-shell bar form islands`147- "Reset the bar to defaults" -> `ryoku-shell bar defaults`148- "Open the bar settings" -> `ryoku-shell bar settings`149- "Turn the dock off" -> `ryoku-shell dock hide`150- "Pin Firefox to the dock" -> `ryoku-shell dock pin firefox`151- "Add a weather plugin from GitHub" -> `ryoku plugin add <git-url> --bar`152- "List my installed plugins" -> `ryoku plugin list`153- "Lock after ten minutes" -> fork `hypr/hypridle.conf` into154 `~/.config/ryoku/user_edits/hypr/hypridle.conf` and set the lock `listener`'s155 `timeout` to `600`, then `ryoku materialize` lays the fork live and156 `pkill -x hypridle; setsid hypridle -c ~/.config/hypr/hypridle.conf &`157 restarts the idle daemon on it (hypridle reads its config only at start;158 `hyprctl reload` does not reach it)159- "Change my wallpaper" -> `ryogami wallpaper set <path>`160- "Next wallpaper" -> `ryogami wallpaper next`161- "Update the system" -> `ryoku update`162- "Roll back a bad update" -> `ryoku rollback`