Add ARM and package policy documentation

[mjc]

Scope

Add ARM and package policy documentation

Branch-added tests

Build/documentation tests cover ARM target policy, package metadata, and the documented SDK surface.

This is a dependency-ordered slice of VESCR-401; it stays below the 5,000-line review budget and preserves the source-tree accounting manifest.

Summary by CodeRabbit

• New Features

  • Added an audio-beep device command with validated responses and clear playback status reporting.
  • Added a fixed 440 Hz, 50 ms, 0.5 V audio smoke test for supported hardware.
  • Added safeguards for malformed requests, unavailable audio, and insufficient response buffers.

• Bug Fixes

  • Improved loopback response-length validation.
  • Prevented invalid control calculations and thread-stack settings from causing unsafe behavior.

• Documentation

  • Documented audio probe usage, safety requirements, command classification, workspace layout, and SDK compatibility.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 26f57e6f-4b24-47a3-b75d-04c6c393a15a

📥 Commits

Reviewing files that changed from the base of the PR and between f3f2d3f and c94f50c.

📒 Files selected for processing (15)

• crates/cargo-vescpkg/src/lib.rs
• crates/vesc-protocol/src/audio_smoke.rs
• crates/vesc-protocol/src/lib.rs
• docs/cargo-vescpkg-command.md
• docs/express-abi.md
• docs/rust-package-api-roadmap.md
• docs/sdk-compatibility.md
• docs/workspace-layout.md
• examples/alloc-smoke/src/main.rs
• examples/control-loop-smoke/src/lib.rs
• examples/loopback/README.md
• examples/loopback/src/app_data.rs
• examples/loopback/src/audio.rs
• examples/loopback/src/main.rs
• tools/safe-example-check.sh

---

📝 Walkthrough

Walkthrough

The change adds a typed FOC-audio beep protocol and cargo vescpkg audio-beep probe. The loopback example handles fixed beep requests. Smoke-test examples gain bounds, saturation, and thread-error handling. Workspace, ABI, compatibility, and command documentation are updated.

Changes

Audio beep probe

Layer / File(s)	Summary
Audio beep wire protocol crates/vesc-protocol/src/audio_smoke.rs, crates/vesc-protocol/src/lib.rs	Adds fixed-size beep request and response codecs, typed statuses, decode errors, and malformed-packet tests.
Loopback audio handling examples/loopback/src/audio.rs, examples/loopback/src/app_data.rs, examples/loopback/src/main.rs, tools/safe-example-check.sh	Adds fixed-parameter FOC-audio handling, typed status mapping, app-data dispatch, tests, and module validation.
Audio-beep CLI and command documentation crates/cargo-vescpkg/src/lib.rs, docs/cargo-vescpkg-command.md, examples/loopback/README.md	Adds the CLI command, shared device argument parsing, response validation, command inventory coverage, and fixed-output usage documentation.

Smoke-test example hardening

Layer / File(s)	Summary
Alloc smoke response validation examples/alloc-smoke/src/main.rs	Checks loopback response lengths before slicing and copying response data.
Control-loop safety and error handling examples/control-loop-smoke/src/lib.rs	Adds must-use annotations, saturating narrowing, typed error documentation, thread-start error mapping, and saturation tests.

Workspace and validation documentation

Layer / File(s)	Summary
Workspace and API documentation docs/workspace-layout.md, docs/rust-package-api-roadmap.md, docs/sdk-compatibility.md	Updates workspace ownership, migration references, deferred validation, and host protocol boundaries.
Express ABI validation documentation docs/express-abi.md	Documents host-test coverage and target-side validation limits.
Loopback example documentation examples/loopback/README.md	Updates upstream references, source mapping, EEPROM behavior, and thread lifecycle details.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant cargo-vescpkg
  participant CustomAppDataProbe
  participant LoopbackAppData
  participant AudioHandler
  cargo-vescpkg->>CustomAppDataProbe: Send encoded beep command
  CustomAppDataProbe->>LoopbackAppData: Deliver app-data packet
  LoopbackAppData->>AudioHandler: Handle audio smoke command
  AudioHandler-->>LoopbackAppData: Return encoded status
  LoopbackAppData-->>CustomAppDataProbe: Return response bytes
  CustomAppDataProbe-->>cargo-vescpkg: Decode beep response

Loading

Poem

A rabbit sends one careful tone,
Through typed wires brightly shown.
The loopback ears reply, “Played!”
Bounds and limits stand arrayed.
Documentation hops along.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch mjc/vescr-401-docs-arm-split

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.97.1)

Clippy execution failed

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

🟢 Approval recommended

The changes are cohesive, tested at the protocol/handler/CLI layers, and no functional or safety regressions were identified in the reviewed diffs.

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 1
• Review effort level: Lite