all: add CLAUDE.md for Claude Code guidance

CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build Commands
+
+```bash
+./build.sh build                              # Debug build (default)
+./build.sh build --build-type Release         # Release build
+./build.sh build --aos-service sm             # Build only SM
+./build.sh build --aos-service sm,iam         # Build specific services
+./build.sh build --clean                      # Clean before building
+./build.sh test                               # Run all unit tests
+./build.sh coverage                           # Run tests with lcov coverage
+./build.sh lint                               # Static analysis (cppcheck)
+./build.sh doc                                # Generate Doxygen docs
+```
+
+To run a single test after building:
+
+```bash
+cd build && ctest -R <test_name_regex>
+```
+
+Manual CMake workflow (for custom options):
+
+```bash
+cd build
+conan install ../conan/ --output-folder . --settings=build_type=Debug --build=missing
+cmake .. -DCMAKE_TOOLCHAIN_FILE=./conan_toolchain.cmake -DWITH_TEST=ON -DCMAKE_BUILD_TYPE=Debug
+cmake --build . --parallel
+```
+
+## Code Standards
+
+- **C++17**, compiled with `-Wall -Werror -Wextra -Wpedantic`
+- Format code with `clang-format` (WebKit-based style, 120-char line limit, config in `.clang-format`)
+- Format CMake files with `cmake-format` (config in `.cmake-format`)
+- Static analysis: `cppcheck` with `suppressions.txt`
+- Testing framework: Google Test / Google Mock
+
+## Architecture
+
+AosCore is a service-oriented system with four service binaries
+that communicate via **gRPC/Protobuf**:
+
+- **CM** (Communication Manager, `aos_cm`) - cloud connectivity
+  (WebSocket/HTTPS), unit configuration, coordinates SM and IAM
+- **IAM** (Identity & Access Manager, `aos_iam`) - certificate
+  management, PKCS#11 HSM support, node identification
+- **MP** (Message Proxy, `aos_mp`) - inter-service communication
+  proxy; supports Xen vchan (`WITH_VCHAN`) or socket transport
+- **SM** (Service Manager, `aos_sm`) - service lifecycle, image
+  management, monitoring, alerts; runtimes: container, boot, rootfs
+
+Each service follows the same structure: `src/<service>/app/`
+contains the entry point (Poco `ServerApplication` subclass),
+with submodules for config, database (SQLite), and
+service-specific logic.
+
+### Key source layout
+
+- `src/common/` - Shared libraries used by all services:
+  cloudprotocol, config, crypto, downloader, logging
+  (journald/stdio), migration, OCI spec, protobuf conversions
+- `src/common/tests/` - Shared test infrastructure: mocks, stubs, and test utilities
+- `src/<service>/tests/` - Per-service unit tests (collocated with modules)
+
+### External dependencies (fetched via CMake FetchContent)
+
+- **aos_core_lib_cpp** - Core C++ library (error types, interfaces, common abstractions)
+- **aos_core_api** - Protobuf/gRPC API definitions
+
+### Conan-managed dependencies
+
+gRPC, Protobuf, Poco (Foundation/JSON/Net/Crypto/DataSQLite), OpenSSL, libcurl, GTest, pkcs11provider