commit 4e1282f52f5ed5d6a558686057b3773317473b8f
Author: sirmrak <sirmrak@gmail.com>
Date:   Wed Jul 8 12:51:40 2026 +0300

    Добавить README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..77b8c65
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+English | [Русский](README.ru.md)
+# Motion Light
+
+A smart, FSM-based custom integration for Home Assistant to control lights based on motion, illuminance (lux), and manual overrides.
+
+## Key Features
+
+- **Smart Motion Control:** Supports main triggers (to turn on) and extend sensors (to keep on).
+- **Illuminance Check:** Only turns on lights if the ambient light is below a specified threshold.
+- **Manual Override Detection:** Intelligently detects when a user manually turns the light on or off and adjusts its behavior to avoid conflicts.
+- **Customizable Timers:** Motion filter (debounce), off-delay, and various cooldowns.
+- **Force Stop:** Supports a dedicated sensor to instantly turn off the light and pause automation.
+- **UI Configuration:** Fully configurable via Home Assistant Config and Options flows.
+
+## How It Works
+
+The integration uses a Finite State Machine (FSM) to manage states. The main states are:
+- **Idle / Detecting:** Waiting for motion or processing a trigger.
+- **On / Delaying / Active:** Light is on. "Delaying" means motion stopped, waiting for the off-delay timer. "Active" means motion was detected during the delay, resetting the timer.
+- **Manual On:** Light was turned on manually. It will stay on until manually turned off or until the "Forgot to turn off" timer expires.
+- **Manual Off Cooldown:** Light was turned off manually. The integration ignores motion sensors for a set period to prevent the light from turning right back on.
+
+## Installation
+
+1. Copy the `motion_light` folder to your `custom_components` directory, or install it via HACS.
+2. Restart Home Assistant.
+3. Go to **Settings > Devices & Services > Add Integration** and search for **Motion Light**.
+
+## Configuration
+
+During setup, you will be asked to provide:
+- **Main triggers:** Sensors that can turn the light on (e.g., motion sensors).
+- **Extend sensors:** Sensors that only reset the off-delay timer but cannot turn the light on from an idle state.
+- **Controlled switches:** The lights/switches to control.
+- **Illuminance sensor:** Optional sensor to check ambient light levels.
+- **Force stop sensor:** Optional sensor to force the light off.
+
+## Entities
+
+Once configured, the integration creates the following entities:
+
+**Sensor:**
+- **Status:** Shows the current FSM state (Idle, On, Delaying, Manual On, etc.).
+
+**Switches:**
+- **Control (Enabled):** Globally enables or disables the integration.
+- **Manual priority:** Enables or disables the manual override detection.
+
+**Numbers (Settings):**
+- **Motion filter:** Delay before turning on after motion is detected (debounce).
+- **Off delay:** How long to wait after motion stops before turning off.
+- **Lux threshold:** Maximum light level at which the automation is allowed to turn on.
+- **Lux cooldown:** Time to ignore the lux sensor after turning off (prevents flickering).
+- **'Forgot to turn off' timer:** How long a manually turned-on light stays on before auto-shutoff. *Set to 0 to disable auto-shutoff in manual mode.*
+- **Manual off cooldown:** How long to ignore motion sensors after a manual turn-off.
\ No newline at end of file