docs: add a migration guide from 1.x to 2.0

README.md

@@ -305,6 +305,7 @@ Then open <https://localhost:5001>.
 
 The [guides](https://rameel.github.io/ramstack.htmxtoolkit/articles/index.html) cover everything from a first tutorial to recipes and troubleshooting.
 The [API reference](https://rameel.github.io/ramstack.htmxtoolkit/api/) describes every public type and member.
+Upgrading from 1.x? See [Migrate from 1.x to 2.0](https://rameel.github.io/ramstack.htmxtoolkit/articles/migrate-to-v2.html).
 
 ## Contributing
 

docs/articles/index.md

@@ -60,6 +60,7 @@ For an existing integration, browse the task guides below or [run the demo](samp
   <a class="guide-card" href="static-assets.md"><strong>Static assets and deployment</strong><span>Load the Toolkit script, configure caching, and publish the application.</span></a>
   <a class="guide-card" href="recipes.md"><strong>Common recipes</strong><span>Implement validation, polling, redirects, and cross-component updates.</span></a>
   <a class="guide-card" href="troubleshooting.md"><strong>Troubleshooting</strong><span>Diagnose failures from generated markup and browser network data.</span></a>
+  <a class="guide-card" href="migrate-to-v2.md"><strong>Migrate from 1.x to 2.0</strong><span>Update registration, configuration, Tag Helpers, and response code for 2.0.</span></a>
 </div>
 
 > [!TIP]

docs/articles/responses.md

@@ -211,11 +211,10 @@ See [Version compatibility](version-compatibility.md#response-events).
 
 Calling `TriggerEvent` several times adds events to the same response, and the browser receives the events
 of each header in call order. A JSON header cannot hold the same name twice, so when a name repeats within
-one header, all events of that header are sent under the reserved `rs:event` name and
-the [Toolkit script](antiforgery.md#what-the-toolkit-script-does) replays them in order.
+one header, the [Toolkit script](antiforgery.md#what-the-toolkit-script-does) delivers all events of that header in order.
 Keep the script loaded when using repeated event names: without it, none of the events
 in that header are triggered. In HTMX 4.x all timings share `HX-Trigger`, so this also applies to a name
-added with different timings. Do not use the name `rs:event`.
+added with different timings.
 
 ### Serialize details with source-generated metadata
 

docs/articles/toc.yml

@@ -54,6 +54,10 @@
   items:
     - name: Common recipes
       href: recipes.md
+- name: Upgrade
+  items:
+    - name: Migrate from 1.x to 2.0
+      href: migrate-to-v2.md
 - name: Help
   items:
     - name: Troubleshooting

docs/index.md

@@ -27,6 +27,7 @@ Choose your starting point:
 | Follow the course or find a task guide           | [Guides](articles/index.md)                                                                                         |
 | Look up a type or method                         | [API reference](api/index.md)                                                                                       |
 | Diagnose an integration problem                  | [Troubleshooting](articles/troubleshooting.md)                                                                      |
+| Upgrade from HtmxToolkit 1.x                     | [Migrate from 1.x to 2.0](articles/migrate-to-v2.md)                                                                |
 
 ## Supported environments
 

src/Ramstack.HtmxToolkit/HtmxResponse.cs

@@ -232,7 +232,6 @@ public HtmxResponse Reselect(string value) =>
     ///   is added more than once for a header, all events in that header are sent in a form that only
     ///   the Toolkit script (<c>htmx-toolkit.js</c>) can replay; without the script, none of them
     ///   is triggered. In HTMX 4.x, this also applies to a name added with different timings.
-    ///   The event name <c>rs:event</c> is reserved for this purpose and cannot be used.
     /// </para>
     /// <para>
     ///   Each call sets the header in <see cref="HttpResponse.Headers" />, replacing its value with
@@ -267,7 +266,6 @@ public HtmxResponse TriggerEvent(string eventName, HtmxTriggerTiming timing = Ht
     ///   is added more than once for a header, all events in that header are sent in a form that only
     ///   the Toolkit script (<c>htmx-toolkit.js</c>) can replay; without the script, none of them
     ///   is triggered. In HTMX 4.x, this also applies to a name added with different timings.
-    ///   The event name <c>rs:event</c> is reserved for this purpose and cannot be used.
     /// </para>
     /// <para>
     ///   Each call sets the header in <see cref="HttpResponse.Headers" />, replacing its value with
@@ -314,7 +312,6 @@ static HtmxResponse TriggerEventImpl(HtmxResponse response, string eventName, ob
     ///   is added more than once for a header, all events in that header are sent in a form that only
     ///   the Toolkit script (<c>htmx-toolkit.js</c>) can replay; without the script, none of them
     ///   is triggered. In HTMX 4.x, this also applies to a name added with different timings.
-    ///   The event name <c>rs:event</c> is reserved for this purpose and cannot be used.
     /// </para>
     /// <para>
     ///   Each call sets the header in <see cref="HttpResponse.Headers" />, replacing its value with