docs: Weekly AI README upgrade — FAQ / Common Pitfalls

[github-actions]

🤖 Automated README Upgrade

This PR was auto-generated by the weekly README upgrade workflow.

This week's focus: FAQ / Common Pitfalls

The AI was given the full list of exported functions and their roxygen2
documentation, and made a single cohesive improvement to README.md.

What to check:

• The added content is accurate
• Code examples actually run
• The tone and style match the rest of the README
• No existing content was accidentally removed

Merge if it looks good. Each week the bot will focus on a different section.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.66%. Comparing base (1648dab) to head (d9587e6).
⚠️ Report is 1 commits behind head on devel.

Additional details and impacted files

@@           Coverage Diff           @@
##            devel      #79   +/-   ##
=======================================
  Coverage   78.66%   78.66%           
=======================================
  Files           7        7           
  Lines         825      825           
=======================================
  Hits          649      649           
  Misses        176      176           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.