diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..82a5917
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,22 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Multi-project repository for Raspberry Pi Pico (RP2040) firmware. Each project is a self-contained subfolder with its own Docker build, CMake config, and source tree.
+
+## Projects
+
+- `color_switcher/` — WS2812B LED control with USB-CDC serial commands. See `color_switcher/CLAUDE.md` for project-specific architecture, build commands, and conventions.
+
+## Common Conventions
+
+All projects in this repo follow the same embedded C conventions:
+
+- **Component structure:** each component has `inc/` (public API), `prg/` (implementation + private header), `cfg/` (configuration)
+- **Layered architecture:** STD_TYPES (library) → MCU (hardware drivers) → HAL (abstractions) → APP (application logic) → SYS (orchestrator)
+- **Coding style:** MISRA-C influenced — single return per function, fixed-width types from STD_TYPES (never native C types except void), Hungarian naming, no function calls in conditions
+- **Build system:** Dockerized ARM cross-compilation with modular CMake. No local toolchain required.
+- **Always add descriptive comments** to all code and config files
+- **Avoid magic numbers** — use named constants in config headers
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5bd4b12
--- /dev/null
+++ b/README.md
@@ -0,0 +1,42 @@
+# Pico Projects
+
+A collection of Raspberry Pi Pico (RP2040) firmware projects. Each project is self-contained in its own subfolder with its own Dockerized build system, CMake configuration, and source code.
+
+## Projects
+
+| Project | Description | Target Board |
+|---|---|---|
+| [color_switcher](color_switcher/) | Interactive color-switching firmware with USB-CDC serial commands and WS2812B LED control via PIO | Waveshare RP2040-Zero |
+
+## Getting Started
+
+Each project is independent. To work on one, `cd` into its folder:
+
+```bash
+cd color_switcher/
+docker compose build              # first time only
+docker compose run --rm pico-build bash build.sh   # compile
+./flash.sh                        # flash to Pico (hold BOOTSEL + plug in)
+```
+
+See each project's own `README.md` for project-specific instructions.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
+
+No local ARM toolchain needed — everything builds inside Docker containers.
+
+## Repository Structure
+
+```
+pico/
+├── color_switcher/          # WS2812B color switcher with USB/UART comm
+│   ├── cmake/               # modular CMake build system
+│   ├── src/                 # layered C firmware (MCU → HAL → APP → SYS)
+│   ├── Dockerfile           # containerized ARM cross-compilation
+│   ├── docker-compose.yml
+│   ├── build.sh / flash.sh
+│   └── CLAUDE.md / README.md
+└── README.md                # this file
+```
\ No newline at end of file