docs: update appstreams README with new features

Document the new features added in this PR:
- Stream switching (automatic upgrades/downgrades)
- Generic DNF options support
- Audit trail attributes (handle, comment)

Add usage examples for stream switching and DNF options.

Author: nickanderson

promise-types/appstreams/README.md

@@ -1,5 +1,3 @@
-# AppStreams Promise Type
-
 A CFEngine custom promise type for managing AppStream modules on compatible systems.
 
 ## Overview
@@ -10,6 +8,9 @@ The `appstreams` promise type allows you to manage AppStream modules, which are
 
 - Enable, disable, install, and remove AppStream modules
 - Support for specifying streams and profiles
+- Automatic stream switching (upgrades and downgrades)
+- Generic DNF configuration options support
+- Audit trail support via handle and comment attributes
 
 ## Installation
 
@@ -83,13 +84,56 @@ bundle agent main
 }
 ```
 
+### Stream switching (upgrade or downgrade)
+
+When a module is already installed with a different stream, the promise type automatically switches to the requested stream:
+
+```
+bundle agent main
+{
+  appstreams:
+      "php"
+        handle => "main_php_stream_82",
+        comment => "Upgrade PHP from 8.1 to 8.2 for new features",
+        state => "installed",
+        stream => "8.2",
+        profile => "minimal";
+}
+```
+
+This will automatically switch from any currently installed stream (e.g., 8.1) to stream 8.2.
+
+### Using DNF options
+
+You can pass generic DNF configuration options to control package installation behavior:
+
+```
+bundle agent main
+{
+  appstreams:
+      "php"
+        state => "installed",
+        stream => "8.2",
+        profile => "minimal",
+        options => {
+          "install_weak_deps=false",
+          "best=true"
+        };
+}
+```
+
+This installs PHP 8.2 minimal profile without weak dependencies (like httpd).
+
 ## Attributes
 
 The promise type supports the following attributes:
 
 - `state` (optional) - Desired state of the module: `enabled`, `disabled`, `installed`, `removed`, `default`, or `reset` (default: `enabled`)
 - `stream` (optional) - Specific stream of the module to use. Set to `default` to use the module's default stream.
 - `profile` (optional) - Specific profile of the module to install. Set to `default` to use the module stream's default profile.
+- `options` (optional) - List of DNF configuration options as "key=value" strings (e.g., `{ "install_weak_deps=false", "best=true" }`). Invalid options will cause the promise to fail.
+- `handle` (optional) - CFEngine handle for the promise, recorded in DNF history for audit traceability.
+- `comment` (optional) - CFEngine comment for the promise, recorded in DNF history for audit traceability.
 
 ## Requirements