Add System management documentation & Monitoring file for developer documentation

astro.config.mjs

@@ -47,6 +47,14 @@ export default defineConfig({
                 },
               ],
             },
+            {
+              label: "System Management",
+              items: [
+                { slug: "users/system-management" },
+                { slug: "users/system-management/configuration-locations" },
+                { slug: "users/system-management/moss-state-management" },
+              ],
+            },
             {
               label: "Desktops",
               items: [
@@ -79,6 +87,7 @@ export default defineConfig({
                 { slug: "packaging/recipes/overview" },
                 { slug: "packaging/recipes/upstreams" },
                 { slug: "packaging/recipes/metadata" },
+                { slug: "packaging/recipes/monitoring" },
                 { slug: "packaging/recipes/build-deps" },
                 { slug: "packaging/recipes/package-definition" },
                 {

src/content/docs/Packaging/Recipes/monitoring.mdx

@@ -0,0 +1,121 @@
+---
+title: Monitoring
+lastUpdated: 2025-09-28T16:14:34Z
+description: Create and maintain monitoring.yaml so release automation and security alerts stay accurate.
+---
+
+Every recipe should ship a `monitoring.yaml` so our tooling can watch for upstream releases and security issues. Use this reference to populate the file consistently and to find the data required for each field.
+
+## File layout
+
+A minimal monitoring file includes release tracking and optional security metadata:
+
+```yaml
+releases:
+  id: 00000
+  rss: https://example.com/project/releases.atom
+security:
+  cpe:
+    - vendor: example
+      product: project
+```
+
+Indent with two spaces and keep related comments inline so CI and reviewers can follow your reasoning.
+
+## Release tracking
+
+`releases.id`
+: Numeric identifier from [release-monitoring.org](https://release-monitoring.org) (Anitya). Look up the upstream project and note the number in the URL, for example `https://release-monitoring.org/project/300958` for Python.
+
+`releases.rss`
+: URL to an Atom/RSS feed for new releases. Use `~` if no feed exists.
+
+### Common feed patterns
+
+- **GitHub**: `https://github.com/<org>/<repo>/releases.atom` or `.../tags.atom`
+- **GitLab / KDE Invent**: append `/-/tags?format=atom` to the project URL, for example `https://invent.kde.org/plasma/plasma-desktop/-/tags?format=atom`
+- **PyPI**: no feed is required; prefer `~` and rely on the Anitya ID
+- **Freedesktop GitLab**: `https://gitlab.freedesktop.org/<path>/-/tags?format=atom`
+- **Custom sites**: many upstreams publish a `releases.xml`/`atom.xml` file; link directly when available
+
+### Ignore patterns
+
+Use `releases.ignore` to skip versions our repo does not track. Provide a short comment and regular expressions that match the releases to drop.
+
+```yaml
+releases:
+  id: 320206
+  ignore:
+    # Qt 6 builds are out of scope for qt5 packages
+    - ^6\.
+  rss: ~
+```
+
+Prefer anchored expressions (`^` / `$`) to avoid false positives.
+
+## Security metadata
+
+`security.cpe`
+: List of Common Platform Enumeration entries to watch in the NVD feed. Search [nvd.nist.gov](https://nvd.nist.gov/products/cpe) for vendor and product strings. Add every applicable CPE when upstream ships multiple identifiers.
+
+`security.ignore`
+: Optional list of CVE IDs or regexes our package should ignore (for example, CVEs that only affect optional components).
+
+If no CPE exists, set the value to `~` and add a dated comment noting the last time you checked.
+
+```yaml
+security:
+  cpe: ~
+  # No known CPE as of 2024-09-01
+```
+
+## Where to find the data
+
+1. **Start with release-monitoring.org**: search for the upstream name. 
+2. **Collect feeds**: confirm the `releases.atom` or `/-/tags?format=atom` URL opens in a browser. Use curl or `wget -qO- <feed>` locally when you need to double-check.
+3. **Identify CPE strings**: search the NVD catalog or reuse values from similar recipes. Many projects share vendor IDs (for example, both upstream `python` and the `urllib3` package provide CPEs).
+4. **Document exceptions**: add comments whenever you set `ignore` patterns or leave fields empty so future maintainers understand the decision.
+
+## Example templates
+
+### GitHub project with security feed
+
+```yaml
+releases:
+  id: 4078
+  rss: https://github.com/urllib3/urllib3/releases.atom
+security:
+  cpe:
+    - vendor: urllib3
+      product: urllib3
+    - vendor: python
+      product: urllib3
+```
+
+### GitLab project with prerelease filter
+
+```yaml
+releases:
+  id: 5440
+  ignore:
+    # Track the current stable branch only
+    - 258.*
+  rss: https://gitlab.freedesktop.org/systemd/systemd/-/tags?format=atom
+security:
+  cpe:
+    - vendor: systemd_project
+      product: systemd
+```
+
+### No CPE available
+
+```yaml
+releases:
+  id: 19755
+  rss: ~
+security:
+  cpe: ~
+  # No CPE published as of 2023-03-23
+```
+
+Keep monitoring files in sync with upstream changes. When a project moves or renames releases, update the ID and feed so our automated tooling continues to work.

src/content/docs/Users/System Management/configuration-locations.mdx

@@ -0,0 +1,48 @@
+---
+title: Configuration Locations
+lastUpdated: 2025-09-28T16:14:34Z
+description: Understand where packages ship their default configuration and how to override it on a stateless system.
+---
+
+AerynOS ships configuration in a stateless layout. Packages deliver defaults in `/usr/share/defaults`, while administrator and user changes live elsewhere so updates can proceed without overwriting your work.
+
+## System defaults
+
+Default files mirror the traditional `/etc` hierarchy under `/usr/share/defaults`.
+
+| Purpose | Default location | Example contents |
+| --- | --- | --- |
+| Base system settings | `/usr/share/defaults/etc` | `ld.so.conf`, `libnl`, `tpm2-tss` |
+| PAM policies | `/usr/share/defaults/pam.d` | `sudo`, `system-login`, `polkit-1` |
+| Shell profiles | `/usr/share/defaults/profile` and `/usr/share/defaults/profile.d` | `00-aeryn.sh`, interactive shell tweaks |
+| Service defaults | `/usr/share/defaults/environment.d` | Session-wide environment snippets |
+| Sudo configuration | `/usr/share/defaults/sudo` | `sudoers`, drop-in files |
+| SSH defaults | `/usr/share/defaults/ssh` | `ssh_config`, `sshd_config` |
+
+
+Packages may add more directories under `/usr/share/defaults` as required. The layout always mirrors where the file would appear under `/etc` on a traditional filesystem.
+
+## System overrides
+
+Place administrator overrides in `/etc`. Files in `/etc` shadow anything under `/usr/share/defaults` and survive package updates. Use drop-in directories such as `/etc/pam.d` or `/etc/sudoers.d` to keep customisations scoped and easy to audit.
+
+When you need to revert to the shipped defaults, remove the override from `/etc` and Moss will fall back to the matching file in `/usr/share/defaults`.
+
+## User-level configuration
+
+Desktop and application settings follow the XDG Base Directory specification. Store per-user changes in:
+
+- `~/.config` for configuration files
+- `~/.local/share` for data files
+
+These paths override both `/etc` and `/usr/share/defaults` for the owning user.
+
+## Where to look next
+
+Run the following command to explore the current defaults on your system:
+
+```bash
+ls /usr/share/defaults
+```
+
+Combine this with `moss search-file` to identify which package owns a specific default file when you need to adjust or report an issue.

src/content/docs/Users/System Management/index.mdx

@@ -0,0 +1,10 @@
+---
+title: System Management
+lastUpdated: 2025-09-28T16:14:34Z
+description: Keep an AerynOS system healthy with stateless configuration guidance and moss lifecycle tasks.
+---
+import DirectoryList from '@components/DirectoryList.astro';
+
+Use this section to manage an installed system, from understanding where configuration lives to operating moss states safely.
+
+<DirectoryList/>

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

@@ -0,0 +1,105 @@
+---
+title: Manage Moss States and Packages
+lastUpdated: 2025-09-28T16:14:34Z
+description: Learn how to inspect and switch states, search for software, and keep an AerynOS system up to date with moss.
+---
+
+Moss keeps AerynOS stateless by tracking every change as a state. Use the commands below to inspect those states, discover software, and keep your system current.
+
+## Check the current state
+
+1. List the active state to confirm what is running right now.
+
+```bash
+sudo moss state active
+```
+
+2. Review the state history when you need context for a rollback.
+
+```bash
+sudo moss state list
+```
+
+Use the state ID (the number after `State #`) when you need to query or activate a specific snapshot.
+
+## 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 state activate 128
+```
+
+3. Verify the change.
+
+```bash
+sudo moss state active
+```
+
+Activating a state rewrites the live system to match that snapshot. Reboot afterwards so long-running services start with the expected binaries and configuration.
+
+## Search for packages
+
+Use keyword searches to discover software by name or summary.
+
+```bash
+sudo moss search fractional
+```
+
+Add `--installed` if you only want to search software that is already present on the system.
+
+## Search for installed files
+
+Look up which package delivered a specific file when you troubleshoot or audit an installation.
+
+```bash
+sudo moss search-file libEGL.so
+```
+
+`moss search-file` scans files from installed packages only.
+
+## Install software
+
+1. Refresh repository metadata when needed.
+
+```bash
+sudo moss repo update
+```
+
+2. Install one or more packages.
+
+```bash
+sudo moss install howdy-git
+```
+
+Moss creates a new state automatically. Confirm success with `moss state active`.
+
+## Update the system
+
+Keep the entire system current with a sync operation.
+
+```bash
+sudo moss sync --update
+```
+
+`--update` pulls fresh repository metadata before applying upgrades. Moss records the result as a new state, so you can roll back if something goes wrong.
+
+## Remove software
+
+Uninstall packages you no longer need.
+
+```bash
+sudo moss remove howdy-git
+```
+
+Moss snapshots the removal in a new state. Use `moss state list` to find the previous state if you have to recover.
+
+## List currently installed software
+
+
+```bash
+moss list 
+```