Usage: stratum software <action> [arguments]    (module type: setting)

Where the software comes from and how it is kept up to date:
APT repositories, each switched on or off on its own, with or without
source packages, and automatic daily upgrades by profile. Stratum ships
the official Debian repositories of the system's release (Debian 13
trixie, Debian 14 forky: @codename, @codename-updates, @codename-security,
@codename-backports) and the Stratum repository; more can be added as
definition files. In the menu: select "software", then "repositories"
(checklist: binary packages first, source packages at the bottom),
"components" (main, contrib, non-free, non-free-firmware) or "upgrades"
(one of the profiles).

Actions:
  status                      state, system, components, all repositories
  list                        table of the repositories
  enable                      enable the default repositories (debian, -updates,
                              -security, -backports and stratum, without source
                              packages) or the ones enabled before;
                              keeps the previous sources as *.stratum-software.bak
  enable <repo>...            enable the binary packages of these repositories
  disable                     disable all (except the required Stratum
                              repository) and restore the previous sources
  disable <repo>...           disable the binary packages of these repositories
  sources <repo> on|off       source packages (deb-src) of a repository
  components [component...]  show or choose the Debian components
  upgrades [profile]          show or choose the automatic upgrades:
                              complete, security (default) or turn-off
                              ("turn off" and "off" are accepted)
  configure <profile>         the same as upgrades <profile>
  options                     the upgrade profiles
  apply                       write the APT files of every repository and the
                              upgrade configuration again (no apt-get update)
  update                      apt-get update only
  refresh                     write the allowed origins of the automatic
                              upgrades again (e.g. after another package
                              added a repository)
  verify [repo...]            check that every enabled repository is reachable
                              and has a valid InRelease file (signed with its
                              SIGNED_BY keyring); changes nothing
  lists                       lists for the menu: repositories, components,
                              upgrades (one profile of three)
  toggles repositories|components|upgrades   the items of a list with their state
  set repositories <item>...  exactly these on, all others off; items are
                              <repo> (binary) and src:<repo> (source packages)
  set components <comp>...    exactly these components
  set upgrades <profile>      the upgrade profile
  settings                    nothing - a list-only module has no single-value settings
  pending                     nothing to confirm: changes are applied immediately
  help                        show this help
  (start and stop are accepted as synonyms of enable and disable)

Machine-readable output (for Control Desk and other tools):
  status --json               state, system, every list with every id (title,
                              description, enabled, origin), and which file is
                              written where
  lists --json                the three lists as the menu shows them
  set <list> <item>... --json what changed on disk: files written, removed,
                              backed up and restored, whether sources.list was
                              touched, and whether apt-get update ran
  upgrades --json             the profile, the effective unattended-upgrades
                              settings and the next run of the timer
  verify --json               every enabled repository with the URL, HTTP
                              status, InRelease and signature result
Every action runs apt-get update after changing the repositories
(STRATUM_NO_UPDATE=1 skips it). A change that would leave the system without
any APT source returns status 3; the core repeats it with STRATUM_FORCE=1.
Automatic upgrades: no automatic reboots; backports are never upgraded
automatically; they work only on official, supported Debian releases.

Components of the Debian repositories:
  main                free software (always recommended)
  contrib             free software that depends on non-free software
  non-free            software that is not free
  non-free-firmware   firmware that is not free (drivers for network cards, GPUs, ...)

The Debian repositories work only on a supported official Debian release
(/usr/lib/stratum/supported) - not on Raspberry Pi OS, Ubuntu or other
derivatives.

Files:
  /etc/stratum/software.conf                    components, enabled repos, sources,
                                                upgrade profile
  /etc/apt/apt.conf.d/52stratum-software        APT::Periodic and the allowed
                                                origins of the automatic upgrades
  /var/log/unattended-upgrades/                 logs of the automatic upgrades
  /etc/apt/sources.list.d/stratum-<repo>.sources  one file per repository - also for
                                                the ones that are off (commented out,
                                                with the command that switches them on)
  /etc/apt/sources.list.d/stratum.sources       the Stratum repository
  /etc/apt/sources.list.stratum-software.bak    the previous sources.list, kept
                                                when Stratum owns the Debian sources
  /usr/lib/stratum/software.d/<repo>.repo       repository definitions (Stratum)
  /etc/stratum/software.d/<repo>.repo           your own definitions; the same
                                                name overrides the Stratum one

Definition file (<repo>.repo, shell syntax; the file name is the id):
  NAME="Example"                    short name
  DESCRIPTION="what it contains"    one line
  URIS="https://example.org/apt"    deb822 URIs
  SUITES="@codename"                deb822 Suites; @codename = the system's release
                                    (trixie, forky), @version = its number (13, 14)
  COMPONENTS="main"                 "@debian" = the chosen Debian components
  SIGNED_BY="/usr/share/keyrings/example.gpg"
  SOURCES="yes"                     the repository has source packages (deb-src)
  REQUIRES="debian"                 only on a supported official Debian release (optional;
                                    "supported" = any supported system)
  REQUIRED="yes"                    always enabled, cannot be disabled; only its
                                    source packages can be switched (optional)
  DEFAULT="on"                      enabled by a plain "enable" (optional)
  DEFAULT_SOURCES="on"              its source packages too (optional)
  ARCHITECTURES="amd64 arm64"       published architectures (optional)
  FILE="name.sources"               APT file name instead of stratum-<repo>.sources;
                                    a file there that is not managed is backed up
  ORDER="50"                        position in the list
The values are read as literal assignments (quoted values, trailing comments);
the files are never executed.
Then:  stratum software enable <repo>
