[avds2]

Problem and resulting guidance

The guides mixed canonical and preferred AI entrypoints, treated below-profile targets as unavailable, implied whole-bundle resource/transaction guarantees, and omitted the actual collector API and sidecar semantics. This documentation-only revision checks current main (1b513b8) and makes those contracts explicit: prefer context.ai.json, preserve baseline/profile selection, distinguish incomplete observations, and scope byte limits and directory/archive failure separately.

Rewrite and organize README, FORMAT, COLLECTORS, CONTRIBUTING, SECURITY and the threat model; add TROUBLESHOOTING; preserve historical audit/changelog context with exact revision/CI references; update bug/feature/PR templates. The catalog covers all 25 collectors and profile settings; the contributor guide includes executable metadata/detection/acquisition and helper signatures. Runtime and test code are unchanged.

The review also found a remaining code limitation: run_owner_capture/probe_owner_capture still select BusyBox setpriv by presence although publication feature-checks it. Optional per-user probes may fail under sudo without runuser. The guides document the exact affected boundary rather than claiming the previous Alpine handoff test proves all owner probes work. Fixing that code is outside this documentation revision.

Validation

• All 10 Markdown documents: 32 relative links/anchors, 16 Bash-block syntax checks and one parsed JSON model fragment passed; GitHub YAML parsed successfully.
• All 25 documented catalog rows and profile resource settings matched runtime metadata/configuration.
• The complete contributor example ran against the real API: metadata, detection, acquisition and strict typed records passed.
• CLI checks passed for named-target/profile baseline gates, directory-only/archive-only output, rejection rules and sidecar schema versions.
• make check: all 31 regression scripts passed locally.
• bash tests/smoke-distribution.sh: all four profiles passed archive/manifest/AI/privacy/budget checks.
• CI run 37045014444: all seven jobs passed (Python 3.9/3.11/3.13 plus Debian, Fedora, Arch and Alpine check/smoke containers).
• git diff --check passed. Local tests run in the existing restricted namespace; they do not establish every live hardware/session configuration.