docs(AGENTS): codify recurring PR review feedback as rules

[wowi42]

Summary

Mined the last 100 closed PRs on this repo and surfaced the patterns reviewers raised more than once. Added them to AGENTS.md as explicit rules so future agents/contributors follow them up-front instead of learning them in review.

New / extended rules:

• Shell safety extended to all user-controlled values regardless of type (ports, ints, paths) — reviewers have flagged unquoted ints as an injection risk.
• Optional parameter defaults clarified to require T | None, not Optional[T].
• Distinguish unset from empty, branch on if x is not None:, not truthy if x:, when a param is T | None.
• FactBase typing, annotate command() / process() and don't re-wrap output (it's already a list[str]).
• Fact "show file or empty" pattern, prefer ! test -e PATH || cat PATH over cat PATH 2>/dev/null || true so real cat errors aren't swallowed.
• Reuse existing helpers in operations.util.file_utils before adding new chown/chmod/path utilities.
• No assert in src/, python -O strips them; raise an explicit exception instead.
• PR atomic scope, one change per PR; split unrelated __init__.py re-exports, drive-by refactors, and unrelated test edits.

Related issues

None.

Test plan

• AGENTS.md renders correctly as Markdown locally.
• No code changes — nothing to run for tests/lint.

Labels

Suggested: docs, meta.

Checklist

• Based on 3.x
• Focused on a single change (no unrelated refactors / churn)
• Docs added or updated for user-facing changes

[DonDebonair]

I added a new ## Coding Conventions header in AGENTS.md. Some of the additions in this PR should probably be moved there as they are not specific to adding facts/operations.