docs: add CLAUDE.md with build, test and architecture guidance

[openipc-ai]

Summary

Adds a CLAUDE.md at the repository root so coding agents (and new contributors) get the repo's build, test and architecture context without rediscovering it.

• Build: native and cross commands exactly as pr-build-check.yml / release.yml run them, the UPX-pack requirement for legacy kernels, and the CMake knobs that matter. Two gotchas are called out: CMAKE_C_FLAGS is hard-reset at the top of CMakeLists.txt so command-line flags are lost, and BUILD_SHARED_LIBS=ON is what drops -static for a dynamic/ASAN build.
• Tests and CI: cYAML_test, tools/test_pipeline.sh, the three-architecture PR build gate, the rolling latest vs v* release scheme, and the dispatch-only lab test workflow.
• Architecture: the detection flow from getchipname() through the UART-base and /proc/cpuinfo tables, the HAL as per-vendor installed global function pointers, chip_generation as the switch key every subcommand dispatches on, sensor probing over possible_i2c_addrs, the board detector table, the STANDALONE_LIBRARY split between ipctool and libipchw, and what adding a new SoC or vendor touches.

Verification

• Native Release build succeeds and produces ipctool, ipcinfo, cYAML_test, libipchw.a.
• ./build/cYAML_test passes all six cases.
• tools/test_pipeline.sh passes end to end.
• Every file path and symbol named in the document was checked against the current tree.

Documentation only; no code changes.

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can tweak Display preferences with a live preview to see your comment before it ships

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Add repository build, test, and architecture guidance

📝 Documentation 🕐 10-20 Minutes

AI Description

• Adds root-level guidance for native builds, cross-compilation, testing, CI, and formatting
 workflows.
• Documents hardware detection, vendor HAL dispatch, sensor probing, and library build boundaries.
• Records legacy-kernel, architecture-specific, and contributor pitfalls to prevent repeated
 discovery.

Diagram

graph TD
  Guide["CLAUDE.md"] --> Build["Build Guidance"] --> CI["CI Workflows"]
  Guide --> Tests["Test Guidance"] --> CI
  Guide --> Architecture["Architecture Guide"] --> Detection["SoC Detection"] --> HAL["Vendor HAL"] --> Outputs["Hardware Reports"]

Loading

High-Level Assessment

A root-level CLAUDE.md is the appropriate approach because coding agents discover it automatically and contributors can access the same consolidated guidance. Distributing this material across the README and existing architecture documents was considered, but would reduce discoverability and preserve the context fragmentation this change addresses.

Files changed (1) +183 / -0

Documentation (1) +183 / -0

CLAUDE.mdAdd contributor and coding-agent repository guide +183/-0

Add contributor and coding-agent repository guide

• Introduces consolidated build, cross-compilation, testing, CI, formatting, and release guidance. It also documents hardware detection, vendor HAL dispatch, sensor and board probing, architecture-specific constraints, host tooling, and the standalone library boundary.

CLAUDE.md