Rework reference docs to align to current style guide, doc arch, and improvement proposals

[clayton-cornell]

PR Description

This PR aligns the Agent Flow Reference docs closer to the current style guide and implements several proposals for improvement.

• Update the placeholder syntax to follow the Style Guide: https://grafana.com/docs/writers-toolkit/write/style-guide/write-for-developers/#placeholder-variables (a decision was made to use <PLACEHOLDER> style.
• Update the block headings to match the proposal in: Blocks to show parents in docs headers. #5381
  • Sort table content by:
    • Required first
    • Optional sorted alphabetically
  • Remove block from the block subheadings
  • Sort the block descriptions to match the order in the tables
• Sort other lists alphabetically
• Update some of the spelling and language used (eg use don't instead of do not, spell out regular expression in descriptive text)
• Use semantic line breaks wherever possible
• Remove trailing spaces
• Remove leading spaces on bullet lists
• Insert hard returns between headings and body text
• Fix sentence capitalisation on descriptions in bulleted lists
• Fix product name capitalisation
• Fix acronym capitalization
• Add missing full stops (periods)
• Remove parenthesis in descriptive text where possible
• Format tables to be more readable in markdown
• Add underscore to <AGENT VERSION> syntax to update it to <AGENT_VERSION>

Which issue(s) this PR fixes

Notes to the Reviewer

PR Checklist

• CHANGELOG.md updated
• Documentation added
• Tests updated
• Config converters updated

[github-actions]

This PR has not had any activity in the past 30 days, so the needs-attention label has been added to it.
If you do not have enough time to follow up on this PR or you think it's no longer relevant, consider closing it.
The needs-attention label signals to maintainers that something has fallen through the cracks. No action is needed by you; your PR will be kept open and you do not have to respond to this comment. The label will be removed the next time this job runs if there is new activity.
Thank you for your contributions!

[clayton-cornell]

Closing this one. The reference docs are too much in-flux at teh moment to continue with this effort. It can be revisited at a future date.