From e14e9a15ad8a1feb8162db097600d91ea659808a Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Sun, 24 May 2026 15:11:06 +0300
Subject: [PATCH] Vibe documents

---
 DEBUG.md  | 40 ++++++++++++++++++++++++++++++++++++++++
 README.md | 19 ++++++++++++++++++-
 2 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 DEBUG.md

diff --git a/DEBUG.md b/DEBUG.md
new file mode 100644
index 0000000..3cd32bd
--- /dev/null
+++ b/DEBUG.md
@@ -0,0 +1,40 @@
+# Debug Commands
+
+Development/test commands exposed via the Zephyr shell. Not intended for end users.
+
+### `debug mode` — Mode thread control
+
+| Command | Description |
+|---|---|
+| `debug mode start` | Start the mode thread |
+| `debug mode stop` | Stop the mode thread |
+| `debug mode restart` | Stop then start the mode thread |
+
+### `debug led` — PWM bar
+
+| Command | Args | Description |
+|---|---|---|
+| `debug led fade` | `<ms>` | Fade the PWM bar over `ms` milliseconds |
+| `debug led progress` | `<0-100>` | Set PWM bar to a percentage |
+
+### `debug leds` — Addressable LED strip
+
+| Command | Args | Description |
+|---|---|---|
+| `debug leds all` | `<r> <g> <b>` | Set all LEDs to an RGB value (0–255) |
+| `debug leds clear` | — | Clear all LEDs |
+| `debug leds fade` | `<ms> <r> <g> <b>` | Fade in/out to color over `ms` ms (0–255) |
+| `debug leds fade_to` | `<ms> <r> <g> <b>` | Fade to color over `ms` ms; pass `-1` to keep a channel unchanged |
+| `debug leds color` | `<name>` | Set strip to a named color (e.g. `yellow`) |
+
+### `debug imu` — IMU
+
+| Command | Description |
+|---|---|
+| `debug imu read` | Read and print raw accelerometer X/Y/Z axes |
+
+### `debug light` — Ambient light sensor
+
+| Command | Description |
+|---|---|
+| `debug light read` | Read and print the ambient light sensor value |
\ No newline at end of file
diff --git a/README.md b/README.md
index 59b327b..71046f1 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,19 @@
-# chill
+# Chill
 
+Zephyr RTOS firmware with mode control, addressable LEDs, PWM bar, IMU, and ambient light sensing. Config is persisted to flash via NVS.
+
+## Shell Commands
+
+All commands are available over the Zephyr shell (USB).
+
+### `mode`
+
+| Command | Args | Description |
+|---|---|---|
+| `mode set` | `<phase_a_ms> <phase_b_ms>` | Set phase durations, save to flash, and restart |
+| `mode color` | `<name>` | Set LED color by name, save to flash, and restart |
+| `mode duration` | `<ms>` | Set color animation duration, save to flash, and restart |
+| `mode status` | — | Print current config (phases, color, duration) |
+| `mode colors` | — | List all available color names with RGB values |
+
+> See [DEBUG.md](DEBUG.md) for development/test commands.
\ No newline at end of file