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

# Updates

> How Ryoku updates itself, wraps each run in a snapper snapshot when configured, and rolls back when something breaks.

Ryoku updates through one command: `ryoku update`. When the system meets the
snapshot prerequisites it takes a snapper pre-snapshot, then brings the system
current from the signed `[ryoku]` repo, re-lays the base config with
`ryoku materialize`, and reloads the shell. There is one channel (`main`);
there is no channel switching, no git-pull update, and no ordered migration
ledger.

This page covers the update and snapshot model. The full `ryoku` command
reference — every flag for `update`, `status`, `snapshots`, `rollback`,
`doctor`, and `recovery` — lives in [CLI](/docs/cli).

## What `ryoku update` does

On a packaged install the run is:

1. Take a snapper pre-snapshot (best-effort, an unconfigured snapper never
   blocks the update).
2. `sudo pacman -Syu` to refresh and upgrade everything from the official Arch
   repos and the `[ryoku]` repo.
3. `yay -Sua` (when yay is present) to update any AUR packages.
4. `ryoku materialize` to re-lay Ryoku's base config under `~/.config`,
   override-safe.
5. Reload the shell.
6. Take a snapper post-snapshot.

Throughout, progress is published to `$XDG_RUNTIME_DIR/ryoku-update.json`, which
the shell's update island reads to show the run in the pill.

```bash theme={"dark"}
ryoku update
```

`ryoku update` also calls `ryoku doctor` itself, so stateful drift gets
reconciled as part of the same run.

<Info>
  On a maintainer's dev checkout the same command fetches the channel branch,
  fast-forwards, and redeploys with `ryoku/shell/deploy.sh`. The auto-detection
  is automatic; you do not pick a mode.
</Info>

## Status

`ryoku status` is read-only. It prints the active config base, the installed
`ryoku-desktop` version, what the `[ryoku]` repo offers, the count of pending
package updates (via `checkupdates` from `pacman-contrib`), and the snapshot
count.

```bash theme={"dark"}
ryoku status
```

The `--json` form is the data seam the Hub and the update island read; it is
not meant for humans.

## Snapshots and rollback

When the system meets the prerequisites, every `ryoku update` is wrapped in a
snapper pre/post snapshot pair. The prerequisites are a btrfs root with a
snapper `root` config that writes snapshots to the `@snapshots` subvolume at
`/.snapshots`. The standard ISO install sets all of this up, so on a normal
install the safety net is on from first boot.

It is best-effort by design. On a non-btrfs root, or on a machine where the
snapper `root` config is missing, `ryoku update` proceeds without a snapshot
rather than refusing to update. `ryoku doctor` runs inside every update and,
on a btrfs root with the `root` config missing, creates the config from the
same template the installer uses, registers it in `/etc/conf.d/snapper`,
fixes `/.snapshots` ownership, and enables the cleanup timer, so a drifted
or partially installed machine self-heals on the next run. On a non-btrfs
root, snapshots stay unavailable.

To see what you have:

```bash theme={"dark"}
ryoku status
ryoku snapshots
```

`ryoku status` prints the snapshot count; `ryoku snapshots` lists them, and
fails clearly when snapper is not configured. If it prints `The config 'root'
does not exist`, see [Troubleshoot](/docs/troubleshoot) for the exact
recovery path.

To roll back, pass an id; with no id, `ryoku rollback` lists them so you can
pick one. The same snapshots are selectable from the Limine boot menu when
`limine-snapper-sync` is installed and snapshots exist, so a truly broken
system can be recovered from the bootloader.

```bash theme={"dark"}
ryoku rollback
ryoku rollback 42
```

This hands off to `sudo snapper rollback`.

## Self-healing: `ryoku doctor`

`ryoku doctor` runs idempotent reconcilers for the stateful drift that packages
and config cannot express. A healthy machine is quiet. It runs inside every
`ryoku update`, so you rarely call it by hand; `ryoku doctor --check` previews
what it would change without touching anything.

```bash theme={"dark"}
ryoku doctor --check
```

For the full reconciler set and every doctor flag — `--check`, `--report`, and the opt-in, read-only
`--explain` — see [CLI](/docs/cli). To lean on doctor while chasing a specific
problem, see [Troubleshoot](/docs/troubleshoot).

## Recovery

When the desktop is too broken to update normally (a half-applied upgrade, a
corrupt config, a broken local build), `ryoku recovery` is the last resort. It
resets to `main` and redeploys, overwriting configs. It hands off to
`bin/ryoku-recovery`, preferring a local copy and otherwise fetching the
canonical script over the network, so it still works when the local install is
broken.

```bash theme={"dark"}
ryoku recovery
```

If even the graphical session is gone, drop to a TTY (`Ctrl+Alt+F2`), log in,
and run `ryoku rollback` or `ryoku recovery` from there. The Limine boot menu
offers the same snapper snapshots if the disk itself still boots.

## Where the packages come from

The desktop ships as signed pacman packages from the `[ryoku]` repo
(`release/packages/`). `ryoku-desktop` is the umbrella package and depends on
`ryoku-shell`, `ryoku-hub`, `ryoku`, `ryoku-blobs`, and `ryoku-keyring`. The
installer adds the `[ryoku]` repo, imports the release key from
`ryoku-keyring`, and installs `ryoku-desktop`; from then on, `ryoku update`
keeps the machine current.

`ryoku update` upgrades installed packages. It does not pacstrap newly listed
ones, so a newly added base package reaches only fresh installs.

Because every `[ryoku]` package is signed and pacman verifies it on install, an
update only ever applies packages from the real release key. See
[Security](/docs/security) for how to verify releases yourself.

## State the CLI keeps

The CLI keeps its state under `~/.local/state/ryoku/` — deploy pointers on dev
machines, the `materialized` manifest of Ryoku-owned files, and the latest
`doctor-report.txt`. During a run it publishes live progress to
`$XDG_RUNTIME_DIR/ryoku-update.json` for the pill's update island. See
[CLI](/docs/cli) for the full list.

## See also

* [Keybindings](/docs/keybindings) for the shortcuts that drive the update
  island and Ryoku Settings.
* [Troubleshoot](/docs/troubleshoot) when an update goes sideways.
* [Customize](/docs/customize) for the override files updates leave alone.
* [CLI](/docs/cli) for the full `ryoku` command reference.
* [Security](/docs/security) for signed releases and verifying downloads.
* [FAQ](/docs/faq) for quick answers on updating and rolling back.