docs: update README to be inline with Ansible partner guidelines

Closes #528

README.md

@@ -1,18 +1,20 @@
 [![Galaxy version](https://img.shields.io/badge/dynamic/json?style=flat&label=Galaxy&prefix=v&url=https://galaxy.ansible.com/api/v3/plugin/ansible/content/published/collections/index/crowdstrike/falcon/versions/?is_highest=true&query=data[0].version)](https://galaxy.ansible.com/ui/repo/published/crowdstrike/falcon/)
-[![Ansible Lint](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/ansible-lint.yml/badge.svg)](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/ansible-lint.yml)
-[![Ansible Test](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/ansible-test.yml/badge.svg)](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/ansible-test.yml)
-[![YAML Lint](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/yamllint.yml/badge.svg)](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/yamllint.yml)
-[![Python Lint](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/linting.yml/badge.svg)](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/linting.yml)
 
-# Ansible Collection - crowdstrike.falcon
+# CrowdStrike Falcon Collection
+
+The CrowdStrike Falcon Ansible Collection serves as a comprehensive toolkit for streamlining your interactions with the CrowdStrike Falcon platform.
+
+## Description
 
-The Falcon Ansible Collection serves as a comprehensive toolkit for streamlining your interactions with the CrowdStrike Falcon platform.
+This collection streamlines the management of CrowdStrike Falcon deployments by offering pre-defined roles, modules, inventory plugins, and lookup plugins. It enables automated installation, configuration, and removal of the Falcon sensor across multiple platforms including macOS, Linux, and Windows. The collection also provides robust API integration capabilities through the CrowdStrike FalconPy SDK.
 
-## Ansible version compatibility
+## Requirements
+
+### Ansible version compatibility
 
 Tested with the Ansible Core >= 2.15.0 versions, and the current development version of Ansible. Ansible Core versions before 2.15.0 are not supported.
 
-## Python version compatibility
+### Python version compatibility
 
 This collection is reliant on the [CrowdStrike FalconPy SDK](https://www.falconpy.io/) for its Python interface. In line with the [Python versions supported by FalconPy](https://github.com/CrowdStrike/falconpy#supported-versions-of-python), a minimum Python version of `3.7` is required for this collection to function properly.
 
@@ -86,19 +88,17 @@ Name | Description
 
 <!--end eda content-->
 
-## Installing this collection
+## Installation
 
-### Using `ansible-galaxy` CLI
+### Installing the Collection from Ansible Galaxy
 
-To install the Falcon Ansible Collection using the command-line interface, execute the following:
+Before using this collection, you need to install it with the Ansible Galaxy command-line tool:
 
 ```terminal
 ansible-galaxy collection install crowdstrike.falcon
 ```
 
-### Using a `requirements.yml` File
-
-To include the collection in a `requirements.yml` file and install it through `ansible-galaxy`, use the following format:
+You can also include the collection in a `requirements.yml` file and install it through `ansible-galaxy`, use the following format:
 
 ```yaml
 ---
@@ -112,7 +112,7 @@ Then run:
 ansible-galaxy collection install -r requirements.yml
 ```
 
-### Additional notes
+#### Additional notes
 
 - **Upgrading the Collection**: Note that if you've installed the collection from Ansible Galaxy, it won't automatically update when you upgrade the `ansible` package. To manually upgrade to the latest version, use:
 
@@ -126,7 +126,9 @@ ansible-galaxy collection install -r requirements.yml
     ansible-galaxy collection install crowdstrike.falcon:==0.1.0
     ```
 
-### Python dependencies
+- See [using Ansible collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html) for more details.
+
+### Required Python dependencies
 
 The Python module dependencies are not automatically handled by `ansible-galaxy`. To install these dependencies, you have the following options:
 
@@ -147,9 +149,44 @@ The Python module dependencies are not automatically handled by `ansible-galaxy`
 To use this Ansible collection effectively, you'll need to authenticate with the CrowdStrike Falcon API. We've prepared a detailed guide
 outlining the various authentication mechanisms supported. Check out the [Authentication Guide](docs/authentication.md) for step-by-step instructions.
 
-## Using this collection
+## Use Cases
+
+### Using the Built-In Roles
+
+Install and configure the CrowdStrike Falcon Sensor at version N-2:
+
+```yaml
+- hosts: all
+  vars:
+    falcon_client_id: <FALCON_CLIENT_ID>
+    falcon_client_secret: <FALCON_CLIENT_SECRET>
+  roles:
+  - role: crowdstrike.falcon.falcon_install
+    vars:
+      falcon_sensor_version_decrement: 2
+
+  - role: crowdstrike.falcon.falcon_configure
+    vars:
+      # falcon_cid is autodetected using falcon_client_id|secret vars
+      falcon_tags: 'falcon,example,tags'
+```
+
+Install the latest sensor and prepare golden image:
+
+```yaml
+- hosts: target-host
+  vars:
+    falcon_client_id: <FALCON_CLIENT_ID>
+    falcon_client_secret: <FALCON_CLIENT_SECRET>
+  roles:
+  - role: crowdstrike.falcon.falcon_install
+
+  - role: crowdstrike.falcon.falcon_configure
+    vars:
+      falcon_remove_aid: yes
+```
 
-### Example using modules
+### Using Modules and Plugins
 
 ```yaml
 ---
@@ -162,49 +199,58 @@ outlining the various authentication mechanisms supported. Check out the [Authen
       filter: "platform_name:'windows'"
       sort: "version|desc"
     delegate_to: localhost
+
+  - name: Get information about all Windows hosts (using host_ids lookup)
+    crowdstrike.falcon.host_info:
+      hosts: "{{ lookup('crowdstrike.falcon.host_ids', windows_host_filter) }}"
+    vars:
+      windows_host_filter: 'platform_name:"Windows"'
 ```
 
-### Example using the built-in roles to install Falcon
+### Using Dynamic Inventories
 
-Install and configure the CrowdStrike Falcon Sensor at version N-2:
+Get detailed information for all Linux hosts in reduced functionality mode:
 
 ```yaml
-- hosts: all
-  vars:
-    falcon_client_id: <FALCON_CLIENT_ID>
-    falcon_client_secret: <FALCON_CLIENT_SECRET>
-  roles:
-  - role: crowdstrike.falcon.falcon_install
-    vars:
-      falcon_sensor_version_decrement: 2
-  - role: crowdstrike.falcon.falcon_configure
-    vars:
-      # falcon_cid is autodetected using falcon_client_id|secret vars
-      falcon_tags: 'falcon,example,tags'
+# sample file: linux_rfm.falcon_hosts.yml
+plugin: crowdstrike.falcon.falcon_hosts
+filter: "platform_name:'Linux' + reduced_functionality_mode:'yes'"
 ```
 
-### Example using the Event Stream EDA source via Ansible Rulebook
+Discover systems in your environment that don't have Falcon installed in the past day:
+
+```yaml
+# sample file: sketchy_hosts.falcon_discover.yml
+plugin: crowdstrike.falcon.falcon_discover
+filter: "entity_type:'unmanaged'+first_seen_timestamp:>'now-1d'"
+```
+
+### React to Security Events with the EDA Event Source
 
 This example requires Ansible EDA to be installed. See the [Ansible Rulebook documentation](https://ansible.readthedocs.io/projects/rulebook/en/latest/getting_started.html) for more information.
 
 ```shell
 ansible-rulebook -i inventory -r crowdstrike.falcon.event_stream_example -E FALCON_CLIENT_ID,FALCON_CLIENT_SECRET
 ```
 
-## Release Notes
+## Testing
 
-See the [changelog](./CHANGELOG.rst) for a history of notable changes to this collection.
+[![Ansible Lint](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/ansible-lint.yml/badge.svg)](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/ansible-lint.yml)
+[![Ansible Test](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/ansible-test.yml/badge.svg)](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/ansible-test.yml)
+[![YAML Lint](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/yamllint.yml/badge.svg)](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/yamllint.yml)
+[![Python Lint](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/linting.yml/badge.svg)](https://github.com/CrowdStrike/ansible_collection_falcon/actions/workflows/linting.yml)
 
-## More information
+The CrowdStrike Falcon Ansible collection uses automated testing through Molecule integrated with GitHub Actions. Tests are executed automatically every night, ensuring continuous validation of:
 
-- [Ansible Collection Overview](https://github.com/ansible-collections/overview)
-- [Ansible User Guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)
-- [Ansible Using Collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html)
-- [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
-- [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
-- [Ansible Rulebook Introduction](https://ansible.readthedocs.io/projects/rulebook/en/latest/getting_started.html)
-- [Event Driven Ansible Introduction](https://www.ansible.com/blog/getting-started-with-event-driven-ansible)
-- [CrowdStrike FalconPy SDK](https://www.falconpy.io/)
+- All built-in roles and their functionality
+- Multiple deployment scenarios
+- Compatibility across supported operating systems
+
+This automated testing pipeline helps maintain collection reliability and quickly identifies potential issues across different environments and use cases.
+
+To learn more about how we use Molecule, check out the [molecule](./molecule/) directory.
+
+Nightly Results: [Actions](https://github.com/CrowdStrike/ansible_collection_falcon/actions)
 
 ## Contributing
 
@@ -214,12 +260,27 @@ All contributions are welcome!
 As of release > 3.2.18, we will now be following Ansible's development patterns for implementing Ansible's changelog fragments. This will require a changelog fragment to any PR that is not documentation or trivial. Most changelog entries will
 likely be `bugfixes` or `minor_changes`. Please refer to the documentation for [Ansible's changelog fragments](https://docs.ansible.com/ansible/devel/community/development_process.html#creating-changelog-fragments) to learn more.
 
-## Questions or Support?
+## Support
 
 CrowdStrike Ansible Collection is a community-driven, open source project aimed at simplifying the integration and utilization of CrowdStrike's Falcon platform with Ansible automation. While not an official CrowdStrike product, the CrowdStrike Ansible Collection is maintained by CrowdStrike and supported in collaboration with the open source developer community.
 
 For additional information, please refer to the [SUPPORT.md](./SUPPORT.md) file.
 
-# License
+## Release Notes
+
+See the [CHANGELOG.rst](./CHANGELOG.rst) for a history of notable changes to this collection.
+
+## Related information
+
+- [Ansible Collection Overview](https://github.com/ansible-collections/overview)
+- [Ansible User Guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)
+- [Ansible Using Collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html)
+- [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
+- [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
+- [Ansible Rulebook Introduction](https://ansible.readthedocs.io/projects/rulebook/en/latest/getting_started.html)
+- [Event Driven Ansible Introduction](https://www.ansible.com/blog/getting-started-with-event-driven-ansible)
+- [CrowdStrike FalconPy SDK](https://www.falconpy.io/)
+
+## License Information
 
-See the [license](LICENSE) for more information.
+See the [LICENSE](LICENSE) for more information.