diff --git a/packages/integrations/alarm/README.md b/packages/integrations/alarm/README.md
index de28fd89..417b9d12 100644
--- a/packages/integrations/alarm/README.md
+++ b/packages/integrations/alarm/README.md
@@ -9,6 +9,7 @@ This package manages alarm automation including 8 automations and 0 scripts.
 ## Table of Contents
 
 - [Overview](#overview)
+- [Design Decisions](#design-decisions)
 - [Automations](#automations)
 - [Entity Reference](#entity-reference)
 
@@ -20,13 +21,27 @@ The alarm automation system provides intelligent control and monitoring.
 
 ```mermaid
 flowchart TB
-    subgraph Automations
+    subgraph Inputs["📥 Inputs"]
+        binary_sensor_alarmed_doors_and_windows["alarmed_doors_and_wi"]
+    end
+    subgraph Logic["🧠 Logic"]
         AlarmDisarmed["Alarm: Disarmed"]
         AlarmArmOvernightHom["Alarm: Arm Overnight Home Mode"]
-        AlarmArmOvernightHom["Alarm: Arm Overnight Home Mode Final Che"]
-        AlarmArmOvernightWhe["Alarm: Arm Overnight When Doors And Wind"]
+        AlarmArmOvernightHom["Alarm: Arm Overnight Home Mode"]
+        AlarmArmOvernightWhe["Alarm: Arm Overnight When Door"]
         AlarmArmed["Alarm: Armed"]
     end
+    subgraph Outputs["📤 Outputs"]
+        alias: Turn on bedroom light to warn not all doors/windows are closed_[""]
+        light_under_bed_left["under_bed_left"]
+        light_under_bed_right["under_bed_right"]
+        light_bedroom_lamp_left["bedroom_lamp_left"]
+        light_bedroom_lamp_right["bedroom_lamp_right"]
+    end
+    binary_sensor_alarmed_doors_and_windows --> AlarmDisarmed
+    AlarmDisarmed --> alias: Turn on bedroom light to warn not all doors/windows are closed_
+    AlarmDisarmed --> light_under_bed_left
+    AlarmDisarmed --> light_under_bed_right
 ```
 
 ### File Structure
@@ -39,6 +54,18 @@ packages/integrations/
 
 ---
 
+## Design Decisions
+
+Key architectural decisions captured from the YAML configuration:
+
+- **Alarm: Disarmed** has a master enable switch for easy disabling
+- **Alarm: Arm Overnight Home Mode** triggers on state transitions (edge detection) rather than continuous state
+- **Alarm: Arm Overnight Home Mode** has a master enable switch for easy disabling
+- **Alarm: Arm Overnight Home Mode Final Check** uses scheduled times for predictable daily routines
+- **Alarm: Arm Overnight When Doors And Windows Shut** triggers on state transitions (edge detection) rather than continuous state
+
+---
+
 ## Automations
 
 ### Alarm: Disarmed
@@ -184,4 +211,4 @@ packages/integrations/
 | Automation not triggering | Entity states and conditions |
 | Script failing | Service calls and entity availability |
 
-*Last updated: 2026-04-07*
+*Last updated: 2026-04-08*
diff --git a/packages/rooms/office/README.md b/packages/rooms/office/README.md
index 16c74af0..98f0468a 100644
--- a/packages/rooms/office/README.md
+++ b/packages/rooms/office/README.md
@@ -9,6 +9,8 @@ This package manages the office room automation in the Home Assistant configurat
 ## Table of Contents
 
 - [Overview](#overview)
+- [Design Decisions](#design-decisions)
+- [Dependencies](#dependencies)
 - [Architecture](#architecture)
 - [Automations](#automations)
   - [Motion Detection](#motion-detection)
@@ -79,6 +81,35 @@ flowchart TB
 
 ---
 
+## Design Decisions
+
+Key architectural decisions captured from the YAML configuration:
+
+- **Temperature-based automations** use tiered thresholds (26°C, 29°C, 31°C) for escalating responses — based on summer temperatures experienced in the room
+- **Time delays** (10 minutes for computer shutdown, 2 minutes for motion detection) account for temporary disconnections and transient states
+- **Office: Open Blinds In The Morning** uses morning schedule aligned with typical workday start
+- **Office: Computer Turned Off After Sunrise** and **Office: Playing Computer Games** consider sun position for daylight-aware behavior
+- **Office: Motion Detected** has a master enable switch for easy disabling
+- **Office: Computer Turned On** triggers on state transitions (edge detection) rather than continuous state
+- **Office: Computer Turned Off For A Period Of Time** considers occupancy/presence (UDM Pro availability) in its logic
+- Uses ambient light sensors for adaptive lighting that responds to natural light conditions
+
+---
+
+## Dependencies
+
+This package relies on the following components:
+
+### Integrations
+- `EcoFlow` — Office plug management for energy optimization
+
+### Related Packages
+- [Front Garden](../front_garden/README.md) — Shares outdoor brightness sensor for blind control
+- [Living Room](../living_room/README.md) — Shares computer presence groups for blind control
+- [Porch](../porch/README.md) — Front door notifications trigger office lights
+
+---
+
 ## Architecture
 
 ### File Structure
@@ -860,4 +891,4 @@ Most automations use "Debug" log level. Set to "Normal" or "Warning" in producti
 
 ---
 
-*Last updated: 2026-03-01*
+*Last updated: 2026-04-08*