Revamp README with best-practice guidance

[allamiro]

Summary

• update the Ruff configuration to use the new lint section and refresh Optional annotations
• clean up typing throughout the package to rely on modern builtins and collections.abc imports while tightening CLI typing
• normalize mapping helpers and converters to satisfy Ruff formatting and produce clearer fallback handling
• resolve mypy strict failures by guarding timezone lookups, sanitizing parsed datetime results, and normalizing CEF extension iteration
• refresh the README with best-practice structure, installation guidance, CLI/API documentation, and contributor workflow details

Testing

• not run (documentation-only follow-up)

---