Merge pull request #19 from dfeen87/copilot/optimize-documentation-for-onboarding

docs: second-pass hardening — fix stale versions, broken refs, and incorrect Quick Start commands

Author: dfeen87

CHANGELOG.md

@@ -24,7 +24,7 @@ All notable changes to HLV-RAPS are documented in this file.
 - Fix broken include paths in `advanced_propulsion_control_unit.hpp`
 
 ### Maintainability
-- Add `VERSION` file (`2.4.0`)
+- Add `VERSION` file (`3.2.0`)
 - Add `CHANGELOG.md`
 - Add `RAPSVersion` namespace constants to `raps_core_types.hpp`
 - Update REST API health endpoint to use `RAPSVersion::STRING`

CITATION.cff

@@ -8,7 +8,7 @@ authors:
     email: dfeen87@gmail.com
   - family-names: "Krüger"
     given-names: "Marcel"
-year: 2025
+year: 2026
 license: non-commercial
 repository-code: "https://github.com/dfeen87/HLV-RAPS"
 url: "https://github.com/dfeen87/HLV-RAPS"

README.md

@@ -275,20 +275,20 @@ ctest --test-dir build --output-on-failure
 
 ### Running the RTOS Demo
 
-```bash
-# Build and run the RTOS demonstration
-# (Adjust toolchain/platform as needed for your target)
-./build/hlv_rtos_demo
-```
+The RTOS demonstration (`examples/hlv_demo/hlv_rtos_demo.cpp`) is a reference integration example for embedded/RTOS targets. Building it requires a platform-specific toolchain; there is no standalone CMake target provided. Refer to the source file for integration guidance.
 
 ### Running the REST API Server
 
 ```bash
 # Build and run the API server demo
-./build/rest_api_demo
+cmake -S examples/api_client -B build/api_demo
+cmake --build build/api_demo
+
+# In one terminal, start the server
+./build/api_demo/rest_api_demo
 
 # In another terminal, access the API
-curl http://localhost:8080/api/status
+curl http://localhost:8080/health
 ```
 
 📖 **For detailed build instructions**, see the repository documentation in `docs/`.

docs/TELEMETRY_DASHBOARD.md

@@ -1,4 +1,4 @@
-# RAPS Telemetry & Dashboard (v2.3)
+# RAPS Telemetry & Dashboard (v3.2)
 
 This document defines the **read-only observability layer** for RAPS.
 
@@ -77,9 +77,9 @@ Use `tools/telemetry_report.cpp` to generate a lightweight summary report:
 ./telemetry_report raps.telemetry.jsonl
 ```
 
-This is the default v2.3 "dashboard": simple, deterministic, portable.
+This is the default v3.2 "dashboard": simple, deterministic, portable.
 
-Future v2.4+ may add a richer HTML visualization, but only after trust is earned.
+Future v3.3+ may add a richer HTML visualization, but only after trust is earned.
 
 ---
 
@@ -91,7 +91,7 @@ Future v2.4+ may add a richer HTML visualization, but only after trust is earned
 
 ---
 
-# RAPS v2.3.0 — Telemetry & Observability Layer
+# RAPS v3.2.0 — Telemetry & Observability Layer
 
 This release introduces a **production-hardened, read-only telemetry layer** for RAPS.
 

docs/architecture.md

@@ -1,3 +1,4 @@
+# System Architecture
 
 Cross-cutting layers:
 
@@ -150,5 +151,5 @@ No code paths are exclusive to SIL or HIL.
 
 ## 8. Time and Type Consistency
 
-All timing and common scalar types are centralized in:
+All timing and common scalar types are centralized in `src/common/types.hpp`.
 

docs/contracts/TELEMETRY_STORAGE_CONTRACT.md

@@ -235,14 +235,14 @@ Before deployment, verify:
 
 This contract is versioned and maintained alongside RAPS releases.
 
-**Current version**: 1.0 (RAPS v2.3.0)
+**Current version**: 1.0 (RAPS v3.2.0)
 
 **Change policy**:
 - Breaking changes require major version bump
 - New fields may be added in minor versions
 - Deprecations announced one release in advance
 
 For questions or clarifications, refer to:
-- `docs/telemetry_dashboard_v2.3.md`
+- `docs/TELEMETRY_DASHBOARD.md`
 - `data/telemetry/README.md`
 - `src/telemetry/telemetry_run_dir.hpp`

docs/sil_hil.md

@@ -55,6 +55,7 @@ HIL emphasizes:
 
 SIL and HIL differ **only** at the hardware abstraction boundary:
 
+```
         +---------------------+
         |   Core Processing   |
         |   Policy Evaluation |
@@ -65,8 +66,9 @@ SIL and HIL differ **only** at the hardware abstraction boundary:
                    |
     +--------------+--------------+
     |                             |
-Reference Backend Real Backend
-(SIL) (HIL)
+Reference Backend          Real Backend
+    (SIL)                      (HIL)
+```
 
 
 This guarantees that: