Move operating system operations under os namespace

Author: marcofortina

README.md

@@ -195,7 +195,7 @@ Current categories:
 commands:      local.command, remote.command
 filesystem:    fs.*
 archive:       archive.*
-packages:      pkg.*
+packages:      os.package.*
 systemd:       systemctl.*
 users/groups:  user.*, group.*
 processes:     process.*

docs/TECHNICAL_DESIGN.md

@@ -111,7 +111,7 @@ Current builtins are grouped into these categories:
 commands:      local.command, remote.command
 filesystem:    fs.*
 archive:       archive.*
-packages:      pkg.*
+packages:      os.package.*
 system:       system.service.*, system.systemd.*, system.kernel.*, system.process.*, system.cron.*, system.journal.*, system.log.*
 identity:      identity.user.*, identity.group.*
 transfer:      transfer.*

docs/concepts/execution-model.md

@@ -39,7 +39,7 @@ A substep calls one plugin:
 
 ```yaml
 - id: install_nginx
-  use: pkg.install
+  use: os.package.install
   with:
     name: nginx
     sudo: true

docs/guides/creating-plugins.md

@@ -42,7 +42,7 @@ Good examples:
 
 ```text
 fs.file.template
-pkg.install
+os.package.install
 system.service.enable
 transfer.upload
 ```

docs/guides/facts.md

@@ -21,9 +21,9 @@ Automax gathers remote Linux facts for conditional workflows, reports and run di
 
 Individual plugins are also available:
 
-- `facts.os`
+- `os.facts`
 - `facts.network`
-- `facts.packages`
+- `os.package.facts`
 - `facts.services`
 
 Package facts support Debian/Ubuntu through `dpkg-query` and Red Hat-like systems through `rpm`.

docs/guides/package-repositories.md

@@ -9,7 +9,7 @@ Automax manages package repository keys and repository definitions for Debian/Ub
 
 ```yaml
 - id: install_vendor_key
-  use: pkg.key.add
+  use: os.package.key.add
   with:
     name: vendor
     manager: apt
@@ -19,7 +19,7 @@ Automax manages package repository keys and repository definitions for Debian/Ub
 
 ```yaml
 - id: add_vendor_apt_repo
-  use: pkg.repo.add
+  use: os.package.repo.add
   with:
     name: vendor
     manager: apt
@@ -32,7 +32,7 @@ For RHEL-like systems, provide a `.repo` file body with `content` or `src` and `
 
 ```yaml
 - id: add_vendor_dnf_repo
-  use: pkg.repo.add
+  use: os.package.repo.add
   with:
     name: vendor
     manager: dnf

docs/plugins/alternatives.md

@@ -3,35 +3,36 @@ Copyright (C) 2026 Marco Fortina
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Alternatives plugins
+# OS alternatives plugins
 
 Use these plugins for Linux alternatives without hiding distro differences between
 Debian-style `update-alternatives` and RHEL-style `alternatives`.
 
 ## Read-only inventory
 
-`alternatives.list` returns the alternatives known on the target. On Debian-like
+`os.alternatives.list` returns the alternatives known on the target. On Debian-like
 systems it renders `update-alternatives --get-selections`; on RHEL-like systems it
 falls back to the alternatives state directories because the native tool is
 name-oriented.
 
-`alternatives.get` reads one alternative name with `update-alternatives --query`
-or `alternatives --display`. It is read-only and is suitable for prechecks before
-changing a selected implementation.
+`os.alternatives.get` reads one alternative name with `update-alternatives --query`
+or `alternatives --display`. `os.alternatives.check` asserts that the selected
+implementation already points to the expected path.
 
 ## Mutating selection
 
-`alternatives.set` selects the implementation path for one alternative name. Use
-`alternatives.get` first when a job needs to prove the current value before
+`os.alternatives.set` selects the implementation path for one alternative name. Use
+`os.alternatives.get` first when a job needs to prove the current value before
 changing it.
 
 ```yaml
-use: alternatives.get
+use: os.alternatives.check
 with:
   name: java
+  path: /usr/lib/jvm/java-21/bin/java
 
 ---
-use: alternatives.set
+use: os.alternatives.set
 with:
   name: java
   path: /usr/lib/jvm/java-21/bin/java

docs/plugins/facts-cron.md

@@ -8,7 +8,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 ## Facts
 
 Use `facts.gather` for a combined host snapshot, or the narrower read-only
-plugins `facts.os`, `facts.network`, `facts.packages` and `facts.services` when a
+plugins `os.facts`, `facts.network`, `os.package.facts` and `facts.services` when a
 job only needs one area. These plugins are precheck-friendly and do not change the
 target.