From ae01c59b975e4a751cf251433a60b61c978fdbea Mon Sep 17 00:00:00 2001
From: equinoy <equinoy@pepperdash.com>
Date: Wed, 15 Jul 2026 09:52:07 -0500
Subject: [PATCH] docs(readme): document room combiner operation lifecycle and
 combinationOperationTimeoutSeconds default behavior

---
 README.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/README.md b/README.md
index b485eade..0ad097ca 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,38 @@ Utilization of Essentials Framework falls into the following categories:
 
 For detailed documentation, see the [Wiki](https://github.com/PepperDash/EssentialsFramework/wiki).
 
+## Room Combiner Operation Lifecycle
+
+Essentials room combiner now exposes an operation lifecycle that clients can use to show progress and terminal status during scenario changes.
+
+Lifecycle states:
+- Idle
+- InProgress
+- Completed
+- Failed
+- TimedOut
+
+The lifecycle is exposed on room combiners that implement the operation-status extension and is included in app server combiner messages under the combinationOperation payload.
+
+Configuration:
+- combinationOperationTimeoutSeconds (optional): timeout in seconds for an in-progress operation.
+- Default when omitted: 300 seconds.
+- Values less than or equal to 0 are treated as invalid and fall back to the default.
+
+Example room combiner properties:
+
+```json
+{
+	"defaultToManualMode": false,
+	"defaultScenarioKey": "divided",
+	"combinationOperationTimeoutSeconds": 30,
+	"roomKeys": ["roomA", "roomB"]
+}
+```
+
+Operational note:
+- When an operation reaches a terminal state (Completed, Failed, TimedOut), the operation timeout timer is stopped.
+
 ## Support
 
 * Check out our [Discord Server](https://discord.gg/rWyeRH3K)