Document --environment in puppet agent help

[miharp]

Summary

Fixes #652, raised by @defnull while reviewing OpenVoxProject/openvox-docs#477.

puppet agent --help listed about twenty options in USAGE and nothing else, so it read as an exhaustive list. The only hint that any puppet.conf setting is accepted as a long argument was a prose note fifty lines further down at the top of OPTIONS, which is easy to miss when scanning for a specific flag.

Changes to the help text in lib/puppet/application/agent.rb:

• Add --environment to USAGE and OPTIONS. It is the one setting whose command-line form changes agent behaviour beyond overriding the config value: lib/puppet/configurer.rb checks set_by_cli?(:environment) and, when true, skips both the last-run environment and the node request. That is the documented way to move an agent out of an environment it switched to on an earlier run. The entry also notes that an ENC can still redirect the run unless strict_environment_mode is set.
• Add a generic [--<setting> <VALUE>] to USAGE with a sentence pointing at the OPTIONS note.
• Drop the "Note the special 'no-' prefix" sentence from the --no-daemonize entry. That entry is itself the no- form, and the OPTIONS intro already uses --daemonize / --no-daemonize as its worked example.
• Regenerate man/man8/puppet-agent.8. Only the agent page is included; the other pages changed by rake gen_manpages differed only in the date header.

Verification

• bundle exec rubocop lib/puppet/application/agent.rb: no offenses
• bundle exec rspec spec/unit/application/agent_spec.rb: 87 examples, 0 failures
• bundle exec puppet agent --help: USAGE and the new --environment entry render as intended
• mandoc -Tlint on the regenerated page: only the pre-existing date-format warning

Assisted by Claude.

[trefzer]

I think setting strict_environment_mode does make it fail. As far as I know it's not possible to switch the environment if it is set through ENC. (don't know if you can overwrite it if set in the cert).

[miharp]

You're right, and the wording was misleading. --environment can't beat an ENC in either mode. Without strict_environment_mode the agent follows the ENC and re-requests the catalog; with it, the agent refuses the mismatched catalog and the run fails. Reworded in a7196fd to say exactly that.

On the cert: the pp_environment extension exists as an OID but nothing in the agent, node, or catalog code reads it to pick an environment. It only surfaces as a trusted fact, so an ENC or site.pp would have to act on it explicitly.

[bastelfreak]

It would be a great openvox-server 9 feature to enforce the environment from pp_environment

[miharp]

@bastelfreak ok to merge?