Merge pull request #95 from AerynOS/moss/state-remove-ranges

state-mgmt: Restructure, and document state remove

Author: CookieSource

src/content/docs/Users/System Management/moss-state-management.mdx

@@ -1,126 +1,186 @@
 ---
 title: Manage Moss States and Packages
-lastUpdated: 2026-02-20T13:33:00Z
-description: Learn how to inspect and switch states, search for software, and keep an AerynOS system up to date with moss.
+lastUpdated: 2026-03-12T10:33:00Z
+description: Learn how to update, install, remove, and search for packages, and how to inspect, switch and clean up states with moss.
 ---
 
 Moss keeps track of packaging-related operations that change the state of the /usr directory by creating a new filesystem transaction (fstx) for each associated moss operation, be it package installation, removal, or upgrades. 
 
-Use the commands below to inspect and manage those states, discover software, and keep your system current.
+Use the commands below to manage your installed software packages, and keep your system current.
 
-## Check the current state
 
-1. List the active state to confirm what is running right now.
+## Update the system
+
+Keep the entire system current with a sync operation.
 
 ```bash
-moss state active
+sudo moss sync --update
 ```
 
-2. Review the state history when you need context for a rollback.
+`--update` (`-u`) pulls fresh repository metadata before applying upgrades. Moss records the result as a new state, so you can roll back if something goes wrong.
+
+
+## Search for packages
+
+Use keyword searches to discover software by name or summary.
 
 ```bash
-moss state list
+sudo moss search something
 ```
 
-Use the state ID (the number after `State #`) when you need to query or activate a specific snapshot.
+Add `--installed` (`-i`) if you only want to search software that is already present on the system.
 
-## Activate a different state
 
-Follow these steps to roll back or advance to another state safely.
+## Search for installed files
 
-1. Identify the target state ID with `moss state list`.
-2. Activate that state.
+Look up which package delivered a specific file when you troubleshoot or audit an installation.
 
 ```bash
-sudo moss state activate 128
+sudo moss search-file filename
 ```
 
-3. Verify the change.
+`moss search-file` scans files from installed packages only.
+
+
+## Install new software packages
+
+1. Refresh repository metadata when needed.
 
 ```bash
-moss state active
+sudo moss repo update
 ```
 
-Activating a state atomically swaps the currently active state's /usr directory with the new state's /usr directory, using the Linux kernel [`renameat2` syscall](https://www.man7.org/linux/man-pages/man2/rename.2.html).
+2. Install one or more packages.
 
-On successful activation of the new state, it is recommended to reboot the system, so that long-running services start with the expected binaries, libraries, and configurations.
+```bash
+sudo moss install somepackage
+```
 
-## Search for packages
+Moss creates a new state automatically. Confirm success with `moss state active`.
 
-Use keyword searches to discover software by name or summary.
+
+## Remove software packages
+
+Uninstall packages you no longer need.
 
 ```bash
-sudo moss search fractional
+sudo moss remove somepackage
 ```
 
-Add `--installed` (`-i`) if you only want to search software that is already present on the system.
+Moss snapshots the removal in a new state. Use `moss state list` to find the previous state if you have to recover.
 
-## Search for installed files
 
-Look up which package delivered a specific file when you troubleshoot or audit an installation.
+## List currently installed software packages
+
 
 ```bash
-sudo moss search-file libEGL.so
+moss list installed
 ```
 
-`moss search-file` scans files from installed packages only.
 
-## Fetch package stones
+## Atomic and independent states
 
-Use `moss fetch` to download one or more package `.stone` files by name without installing them on the current system.
+In the preceding examples, it was briefly mentioned that moss creates new "states".
+
+When using moss, state management is an important concept. This section details the fundamentals of moss state management.
+
+Moss is based on the concept of atomic updates. Atomic in this context means "independent units". Each time the user instructs moss to change the state of the system, moss creates a new, independent state. Because each state is independent, it allows moss to roll back to an earlier state, and roll forward to a later state.
+
+
+### Check the current active state
+
+1. List the active state to confirm what is running right now.
 
 ```bash
-moss fetch howdy-git
+moss state active
 ```
 
-Fetch multiple packages into a custom output directory:
+2. Review the state history when you need context for a rollback.
 
 ```bash
-moss fetch howdy-git fractional --output-dir ~/stones
+moss state list
 ```
 
-`moss fetch` writes downloaded files to the current directory by default. Add `--verbose` when you need more detailed progress output.
-If a package cannot be resolved, refresh repository metadata and try again:
+Use the state ID (the number after `State #`) when you need to query, activate, or remove a specific state.
 
-## Install software
 
-1. Refresh repository metadata when needed.
+### Activate a different state
+
+Follow these steps to roll back or advance to another state safely.
+
+1. Identify the target state ID with `moss state list`.
+2. Activate that state.
 
 ```bash
-sudo moss repo update
+sudo moss state activate 128
 ```
 
-2. Install one or more packages.
+3. Verify the change.
 
 ```bash
-sudo moss install howdy-git
+moss state active
 ```
 
-Moss creates a new state automatically. Confirm success with `moss state active`.
+Activating a state atomically swaps the currently active state's /usr directory with the new state's /usr directory, using the Linux kernel [`renameat2` syscall](https://www.man7.org/linux/man-pages/man2/rename.2.html).
 
-## Update the system
+On successful activation of the new state, it is recommended to reboot the system, so that long-running services start with the expected binaries, libraries, and configurations.
 
-Keep the entire system current with a sync operation.
+
+### Clean up retained states
+
+Over time, a system managed by moss will accumulate more and more states. Each state takes up space that is equivalent to the difference in packages between one state to another. If two states share a lot of package versions, the storage needed to keep the difference between states will be small.
+
+There are two ways to clean up retained states:
+
+- Prune, which removes all states except the N latest states
+- Remove, which is capable of removing individual states and ranges of states.
+
+### Prune states
+
+This will prune state history to keep only the 10 latest states, including the current active state:
 
 ```bash
-sudo moss sync --update
+sudo moss state prune
 ```
 
-`--update` (`-u`) pulls fresh repository metadata before applying upgrades. Moss records the result as a new state, so you can roll back if something goes wrong.
+If you want to keep a different number of states, the `-k` / `--keep` parameter will let you specify the number of states you wish to keep:
+
+```bash
+# Keep the five latest states, including the active state
+sudo moss state prune --keep 5
+# or
+sudo moss state prune -k 5
+```
 
-## Remove software
+### Remove specific states
 
-Uninstall packages you no longer need.
+Sometimes, it is useful to be able to remove one or more specific states. This can be accomplished with the `state remove` operation.
 
 ```bash
-sudo moss remove howdy-git
+moss state remove 2 8-12 15 17-21
 ```
 
-Moss snapshots the removal in a new state. Use `moss state list` to find the previous state if you have to recover.
+As you can see, `state remove` enables you to remove both individual states and ranges of states. Ranges are inclusive, meaning the start and end states of the specified range are also removed.
 
-## List currently installed software
 
+## Fetch package .stone files for backup purposes
+
+If you would like to keep an archive of stones, moss supports a fetch operation.
+
+Use `moss fetch` to download one or more package `.stone` files by name without installing them on the current system.
 
 ```bash
-moss list installed
+moss fetch somepackage
+```
+
+Fetch multiple packages into a custom output directory:
+
+```bash
+moss fetch package1 package2 --output-dir ~/stones
 ```
+
+`moss fetch` writes downloaded files to the current directory by default. Add `--verbose` when you need more detailed progress output. If a package cannot be resolved, refresh repository metadata and try again.
+
+Note also that moss fetches .stones against currently active repository `stone.index` files.
+
+You can list your currently active repository index with `moss repo list`.