ryoku-dev/ryoku-arch/ryoku

Ryoku

Ryoku is an Arch Linux desktop: a Hyprland or niri compositor (ryoku wm status says which), 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, window-manager 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.

Ownership inside the vault: the generated maps (AGENTS.md, desktop.md, system.md, packages.md, ryoku-repo.md, user.md, habits.md) are rewritten on every reindex, so read them and never edit them. memory/ and journal/ are yours: write durable notes and dated notes (journal/YYYY-MM-DD.md) there and they survive. user.md lists the user's own choices; never revert one to a shipped default without being asked.

When a user is new to Ryoku, cite the long-form wiki at ~/.local/share/ryoku/rashin/wiki/. It is shipped read-only; start at README.md, then link the page that matches the question instead of assuming Linux, QML, Go, or compositor knowledge.

Topic guides sit beside this file. Read the matching one first:

• `gui.md`: the GUI map. Every intent to its Ryoku Hub page, shell

picker, or QS Bar Settings route, how to open it, and the command it wraps.

• `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.

• `feature.md`: the ladder for a feature the desktop does not

have yet. Check the store, then the machine, then the built-ins; build a plugin only when all three come up empty.

• `troubleshoot.md`: the break/fix playbook. Gather the logs

first (ryoku-rashin logs <app>), diagnose, fix through the owning command, verify, and know the rollback paths.

• `wm.md`: the window-manager seam, provider capabilities and actions,

safe Hyprland Lua and niri KDL overrides, reload, and verification.

• `build.md`: the feature ladder, shell plugin workflow, QML design

rules, the neutral Wm singleton, and Go development in a checkout.

Answer policy: GUI first

When a user asks HOW to change something, lead with the GUI path: the exact keybind or the Ryoku Hub page. The Hub opens with Super+comma; deep-link one page with ryoku-shell hub open <section> (the section key names the page, e.g. keybinds, gpu, lockscreen). Give the command after, as the fallback or the way to script the same change. When the user asks YOU to change it, act through the command (the GUI is for the human), then say what you changed and where to see or undo it in the GUI. Never hand back a bare shell command for a change that has a page or a picker.

Two surfaces have no Hub page. Wallpaper and theme are the shell picker (Super+W, ryogami wallpaper ui) and the bar Wallpaper widget; the bar layout and the dock are QS Bar Settings (ryoku-shell bar settings), not the Hub. See `gui.md` for the full intent-to-surface map.

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:

• Ask `ryoku owner <path>` before you touch a file. It classifies the path

(a shipped ryoku file, a generated one, a tool store, a seed, a user-override, or the user's own) and prints where the change belongs. Never edit a path it calls ryoku, generated, or store; edit where it points.

• 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 compositor config, use the dedicated last-loaded override (hypr/user.lua or niri/user.kdl) that ryoku owner names. A whole-file fork belongs at the mirrored path under user_edits; you own that file and stop receiving upstream changes to it. 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.

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 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 search "barPosition"
cd ~/.local/share/ryoku/rashin/source && prowl 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:

1. Is there a GUI for it? A Ryoku Hub page (ryoku-shell hub open <section>,

Super+comma), the wallpaper picker (Super+W), or QS Bar Settings (ryoku-shell bar settings). If a user asks how to do it, name the surface first; whether you or they drive it, the change still lands through the command that page wraps, so read on.

1. 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.

1. Is it a config edit with no command? Ask ryoku owner <path>, then edit

the override it names, never the shipped file. Use wm.md for the compositor-specific file, validation, reload, and proof.

1. Is it a feature the desktop does not have? Climb feature.md:

ryostore catalog (does the store ship it?), ryoku-shell bar catalog and ryoku plugin list (is it installed but hidden?), then build it as 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 desktop plugins list|rebuild|add|remove and Hub > Plugins; a "version mismatch" after an update means ryoku-hub desktop plugins rebuild --stale.

1. 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.

1. Is it a package? ryoku update for the whole system; pacman/yay for one

package.

1. Unsure a command exists? Read the tool's --help, or desktop.md.

Example requests

• "Put the bar at the bottom" -> QS Bar Settings > Layout

(ryoku-shell bar settings layout), or ryoku-shell bar position bottom

• "Move the clock to the right" -> QS Bar Settings > Layout, or

ryoku-shell bar move clock --section right

• "Hide the GPU widget" -> QS Bar Settings > Widgets, or ryoku-shell bar hide gpu
• "Make the bar islands" -> QS Bar Settings > Bars, or ryoku-shell bar form islands
• "Add a crypto price applet to the QS Bar" -> climb feature.md:

ryostore catalog (a store plugin may already do it), then ryoku-shell bar catalog (a hidden built-in?), then ryoku plugin new and the plugin contract in plugins.md. Never start at "write a widget".

• "Open the bar settings" -> ryoku-shell bar settings (the launcher mark opens it too)
• "Turn the dock off" -> QS Bar Settings > Dock, or ryoku-shell dock hide
• "Pin Firefox to the dock" -> QS Bar Settings > Dock, or ryoku-shell dock pin firefox
• "Change my wallpaper" -> press Super+W and pick one (the wallpaper picker);

scripted: ryogami wallpaper set <path>

• "Remap a key" -> Ryoku Hub > Keybinds (Super+comma, ryoku-shell hub open keybinds)
• "Lock after ten minutes" -> Ryoku Hub > Graphics & Power > Idle

(ryoku-shell hub open gpu); scripted, ryoku-power idle set ac.lockSec 600 (and battery.lockSec), then ryoku-idle apply re-renders and restarts the idle daemon

• "Add a weather plugin from GitHub" -> ryoku plugin add <git-url> --bar
• "List my installed plugins" -> Ryoku Hub > Add-ons, or ryoku plugin list
• "Update the system" -> Ryoku Hub > Updates, or ryoku update
• "Roll back a bad update" -> ryoku rollback