Clean public release wording

marcofortina · marcofortina · commit 7fb175481027 · 2026-06-01T16:07:10.000+02:00
diff --git a/README.md b/README.md
@@ -16,7 +16,6 @@ Operational definitions are external to the Python sources:
 - secrets YAML
 - optional external plugins
 
-
 ## Documentation site
 
 The GitHub Pages site is the full public manual, not just a README mirror. It
@@ -45,7 +44,6 @@ A step opens one fresh SSH connection per target and reuses it for all its
 substeps. Runtime context is not kept in a shell session: values are passed
 through the Automax context, registered outputs and state store.
 
-
 ## YAML flow control
 
 Job YAML supports engine-level flow-control substeps in addition to plugin
@@ -202,7 +200,6 @@ automax run --job job.yaml --inventory inventory.yaml --from task.install
 automax run --job job.yaml --inventory inventory.yaml --from task.install:step.packages
 ```
 
-
 ## Job inspection and recovery
 
 Before running or resuming a job, operators can generate one masked review
diff --git a/docs/TECHNICAL_DESIGN.md b/docs/TECHNICAL_DESIGN.md
@@ -27,7 +27,6 @@ shell. Plugins that need step-local state can use the `ExecutionContext.step_sta
 mapping internally. Job authors should pass explicit plugin parameters such as
 `cwd` instead of relying on implicit cross-substep shell state.
 
-
 Flow-control nodes are engine-level constructs, not plugins. They let job authors
 branch, switch, retry nested blocks, loop, group blocks, set values, echo messages, assert conditions, pause explicitly, record no-op branches, fail deliberately, recover with
 `try`/`rescue`/`always`, and use `break`/`continue` in loops while keeping nested
diff --git a/docs/concepts/execution-model.md b/docs/concepts/execution-model.md
@@ -45,7 +45,6 @@ A substep calls one plugin:
     sudo: true
 ```
 
-
 Flow-control substeps do not call plugins directly. `if`, list-style `if`, `switch`, `retry`, `for`,
 `block`, `set` / `let`, `echo`, `assert`, `sleep`, `noop`, `fail`, `try` / `rescue` / `always`, `break` and
 `continue` are interpreted by the engine and then execute normal nested substeps
diff --git a/docs/guides/creating-plugins.md b/docs/guides/creating-plugins.md
@@ -74,7 +74,6 @@ the build when metadata, preview or dry-run quality gates regress. External
 plugins loaded with `--plugin-path` are described and audited through the same
 registry contract.
 
-
 ## External plugin SDK workflow
 
 Use the SDK commands to create a checked plugin source file before loading it in
diff --git a/docs/guides/kernel-tuning.md b/docs/guides/kernel-tuning.md
@@ -28,4 +28,4 @@ Automax manages Linux runtime kernel parameters through `system.kernel.sysctl.*`
     sudo: true
 ```
 
-Use `system.kernel.sysctl.get` for checks, `system.kernel.sysctl.reload` to reload persisted files, and `system.kernel.module.unload` / `system.kernel.module.persist` for module lifecycle management.
+Use `system.kernel.sysctl.get` for checks, `system.kernel.sysctl.reload` to reload persisted files, and `system.kernel.module.unload` / `system.kernel.module.persist` for module management.
diff --git a/docs/guides/templating.md b/docs/guides/templating.md
@@ -69,7 +69,6 @@ Registered outputs can be reused later in the same run:
 
 The full result then becomes available as `outputs.app_stat`.
 
-
 ## Flow-control values
 
 `if`, branch `when` conditions, and `for` values use the same Jinja context as
@@ -93,7 +92,6 @@ variable and through `item`. It also exposes `loop.index`, `loop.index0`,
         command: "echo {{ loop.index }} {{ member }}"
 ```
 
-
 ## Flow values and messages
 
 `set` and `let` evaluate native Jinja expressions and store values for later
diff --git a/docs/plugins/archive.md b/docs/plugins/archive.md
@@ -97,7 +97,6 @@ Extracts a zip archive on the remote target.
     creates: /opt/package/bin/app
 ```
 
-
 Archive plugins do not add `sudo` themselves. Run them as a user with the required remote permissions, or wrap exceptional privileged archive operations with an explicit `command.remote.run` until privileged archive support is added.
 
 ## Safe extraction
diff --git a/docs/plugins/commands.md b/docs/plugins/commands.md
@@ -40,7 +40,6 @@ Runs a command on the current target through the step-scoped SSH connection.
 `command.remote.run` is intentionally raw. For filesystem, package, service, archive,
 transfer, database or HTTP operations, prefer the dedicated plugin names.
 
-
 `command.local.run` uses the controller shell for string commands, matching Python `subprocess.run(..., shell=True)`. Keep it for trusted operator-authored jobs and prefer list-style commands in future extensions when shell parsing is not desired.
 
 `command.remote.run` accepts `cwd`, `timeout`, `stdin`, `pty`, `encoding`, `success_rc` and `changed`. Use explicit `cwd` on the substep that needs a working directory instead of relying on implicit shell state.
diff --git a/docs/plugins/database.md b/docs/plugins/database.md
@@ -131,7 +131,6 @@ register the canonical plugin in `build_builtin_registry()` or load it through a
 external plugin path. The shared base already handles statement validation,
 output shaping and common result metadata.
 
-
 ## Database health checks
 
 `database.sqlite.check` is a read-only controller-side health check plugin for the existing
diff --git a/docs/plugins/firewall.md b/docs/plugins/firewall.md
@@ -41,7 +41,7 @@ inspect or archive the active nftables ruleset. Use `network.firewall.iptables.l
 `network.firewall.iptables.policy` and `network.firewall.iptables.chain` to inspect iptables/ip6tables state before
 and after runtime rule changes.
 
-## Lifecycle safeguards
+## Change safeguards
 
 `network.firewall.firewalld.*` operations expose explicit runtime/permanent selection,
 `query_only` readback and `reload_mode`. `network.firewall.iptables.rule` supports ordered
diff --git a/docs/plugins/linux-operations.md b/docs/plugins/linux-operations.md
@@ -95,13 +95,11 @@ Use `system.host.check` for one-shot SSH-authenticated host reachability and
 wget, supports SHA256 verification, backs up an existing destination by default,
 and can install mode/owner/group metadata.
 
-
 ## LVM storage
 
 Use `storage.lvm.pv.add`, `storage.lvm.vg.add`, `storage.lvm.lv.add`, `storage.lvm.lv.extend`, `storage.lvm.pv.scan`, `storage.lvm.vg.scan`, `storage.lvm.lv.scan` and `storage.fs.resize` for physical volumes, volume groups, logical volumes, metadata scan and filesystem growth. These plugins expose deterministic manual commands and
 structured `plan --diff` previews before applying storage changes.
 
-
 ## Runtime network operations
 
 Use `network.link.interface`, `network.link.bond`, `network.link.bridge`, `network.link.vlan`,
@@ -110,46 +108,40 @@ and DNS resolver changes. DNS handling is
 backend-aware through the same safety rules as `network.dns.config`: managed or
 symlinked resolver files are not overwritten silently.
 
-
 ## Runtime service checks
 
 Use `network.connectivity.port.check` for target-side TCP/UDP connectivity checks,
 `network.http.request` for controller-side HTTP probes, and the `system.process.*` family for
-process lifecycle checks. The former service-health wrapper namespace is
+process checks. The former service-health wrapper namespace is
 intentionally not part of the public plugin surface.
 
-
 ## Certificate and PKI operations
 
 Use `security.pki.trust.install_ca`, `security.pki.key.permissions` and `security.pki.cert.expiry.check` to
 install CA certificates, enforce private-key permissions and validate certificate
 expiry windows. File-changing operations include preview data and backups where
 applicable.
 
-
 ## Package locks and pinning
 
 Use `os.package.hold.add`, `os.package.hold.remove`, `os.package.version.pin` and `os.package.repo.priority.set` to lock
 packages, pin versions and manage repository priorities across supported package
 managers. File-backed pinning and priority files are previewable and backed up by
 default.
 
-
 ## Advanced mounts and filesystem resizing
 
 Use `storage.mount.remount`, `storage.fs.resize` and `storage.mount.check` to remount filesystems,
 grow supported filesystems and check current runtime mount state with `findmnt`.
 Runtime mount state lives under `storage.mount.*`; persistent boot-time mount and
 swap configuration lives under `storage.fstab.*`.
 
-
 ## Logs and journal collection
 
 Use `system.log.grep`, `system.journal.collect`, `system.journal.grep` and `system.log.export` to inspect
 logs, grep journal output and emit stdout suitable for artifact capture. These
 plugins are read-oriented and document why no file diff is emitted.
 
-
 ## Controller-side mail notifications
 
 Use `notify.mail.send` to send SMTP notifications from the Automax controller. It does
diff --git a/docs/plugins/package-manager.md b/docs/plugins/package-manager.md
@@ -85,7 +85,7 @@ Use `os.package.owner` and `os.package.files` for troubleshooting package/file o
 `os.package.verify` for package-manager integrity checks and `os.package.clean` for explicit
 cache maintenance.
 
-## Package lifecycle hardening
+## Package hardening
 
 `os.package.hold.add`, `os.package.hold.remove`, `os.package.hold.list` and `os.package.hold.check` manage package holds. `os.package.install` supports version pinning during install, temporary repository
 selection, no-recommends installs, explicit downgrade allowance and optional lock
diff --git a/docs/plugins/security.md b/docs/plugins/security.md
@@ -18,7 +18,6 @@ Use `security.apparmor.status` for read-only status, `security.apparmor.profile`
 complain or remove one profile, and `security.apparmor.reload` to reload the AppArmor
 service.
 
-
 ## PAM hardening
 
 Use `security.pam.access`, `security.pam.faillock`, `security.pam.pwhistory`, `security.pam.succeed_if`,
diff --git a/docs/plugins/system.md b/docs/plugins/system.md
@@ -7,7 +7,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 `system.service.*` plugins manage systemd units on the remote target. Use `sudo: true` for system services. Use `user: true` for `systemctl --user` operations.
 
-## Lifecycle
+## Service operations
 
 ```yaml
 - id: start_service
@@ -96,5 +96,4 @@ SPDX-License-Identifier: AGPL-3.0-or-later
     sudo: true
 ```
 
-
 `system.service.active.check` and `system.service.enabled.check` return `ok=true` when the query runs successfully and expose the service state in `data.active` or `data.enabled`.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -151,7 +151,6 @@ automax runs export <run-id> --state-dir .automax/runs --format json --output ev
 automax runs bundle <run-id> --state-dir .automax/runs --output automax-evidence.zip
 ```
 
-
 ## OS information
 
 Detect operating-system release facts for inventory targets before capability
diff --git a/docs/reference/future-work.md b/docs/reference/future-work.md
@@ -78,7 +78,6 @@ Automax may support explicit operator approval points in interactive sessions:
 CI and unattended runs would need a non-interactive approval policy such as
 `--approve` or a signed approval file.
 
-
 ## Event stream contract
 
 Run state already records events. A future contract may formalize an append-only
@@ -98,9 +97,9 @@ SHA-256 checksums, can be verified with `automax plugins verify-package`,
 installed into locked local plugin directories with `automax plugins install`,
 updated with `automax plugins update`, removed with `automax plugins uninstall`,
 and loaded directly or from installed plugin directories with `--plugin-path`.
-The local lifecycle is intentionally lock-based; package repository publishing
-and optional signature workflows can be layered on top without changing the
-source-loading model.
+Local package management is intentionally lock-based. Package repository
+publishing and optional signature workflows can be layered on top without
+changing the source-loading model.
 
 ## Deploy plugins
 
@@ -153,7 +152,7 @@ workflows rather than turning it into a broad platform clone.
 
 ## Operational completeness roadmap
 
-The current plugin catalog already covers backup/restore lifecycle operations,
+The current plugin catalog already covers backup/restore operations,
 package install controls, explicit PAM hardening primitives and generated plugin
 metadata. Near-term work should therefore focus on evidence, consistency and
 operator trust rather than adding broad new plugin namespaces.
@@ -171,7 +170,7 @@ systemd and service operations
 firewall and network checks
 storage and filesystem safeguards
 database optional-driver smoke
-backup and restore lifecycle
+backup and restore operations
 ```
 
 These packs should stay outside normal unit tests when they need privileged
@@ -195,7 +194,7 @@ from disposable hosts rather than another static registry report.
 
 ### PAM and account-access evidence
 
-PAM hardening is implemented through explicit, service-scoped plugins:
+PAM hardening uses explicit, service-scoped plugins:
 `security.pam.access`, `security.pam.faillock`, `security.pam.pwhistory`,
 `security.pam.succeed_if`, `security.pam.service_line`, `security.pam.validate`,
 `security.pam.stack.facts` and `security.authselect.check`. Future PAM work
diff --git a/docs/reference/job-dsl.md b/docs/reference/job-dsl.md
@@ -284,7 +284,6 @@ must be the last branch when present:
             command: "echo A"
 ```
 
-
 Use `switch` / `case` / `default` when several branches compare the same value:
 
 ```yaml
@@ -305,7 +304,6 @@ Use `switch` / `case` / `default` when several branches compare the same value:
       fail: "Unknown service status: {{ outputs.service.data.status }}"
 ```
 
-
 Use flow-level `retry` to repeat a nested block until all its substeps succeed or
 attempts are exhausted:
 
@@ -346,7 +344,6 @@ under `loop` (`index`, `index0`, `first`, `last`, `length`):
         sudo: true
 ```
 
-
 Use `set` or `let` to store flow values without shell glue. Values are evaluated
 as native Jinja expressions, then become available as `{{ name }}`, `vars.name`
 and `outputs.name` for later substeps on the same target execution path:
@@ -368,9 +365,6 @@ Use `echo` for operator-visible messages without invoking a shell command:
   echo: "processing {{ item }}"
 ```
 
-
-
-
 Use `noop` for explicit no-op branches, placeholders or documented skip paths:
 
 ```yaml
@@ -401,7 +395,6 @@ Use `fail` to stop the current flow explicitly with a rendered message:
   when: "{{ not outputs.service_check.data.exists }}"
 ```
 
-
 Use `block` to group normal substeps under one condition, tag or logical id:
 
 ```yaml
diff --git a/docs/reference/testing-and-ci.md b/docs/reference/testing-and-ci.md
@@ -53,7 +53,6 @@ scripts/ssh-smoke.sh
 Privileged package, systemd, user and group checks are opt-in. See
 [Extended SSH smoke](../guides/ssh-smoke.md).
 
-
 ## Runtime evidence suite
 
 Use the runtime evidence suite when a disposable lab or VM target is available:
diff --git a/src/automax/core/secrets.py b/src/automax/core/secrets.py
@@ -4,8 +4,9 @@
 """
 External secrets providers.
 
-Only env and file providers are implemented now. The provider registry is intentionally
-small and explicit so new providers can be added without changing the execution engine.
+Supported providers are env, file and command. The provider registry stays
+small and explicit so additional providers can be added without changing the
+execution engine.
 """
 
 from __future__ import annotations
diff --git a/tests/test_documentation_and_regressions.py b/tests/test_documentation_and_regressions.py
diff --git a/tests/test_engine.py b/tests/test_engine.py
