docs: clarify two-image rationale around supply chain auditability

The deciding factor between upstream and system images is supply chain
auditability, not features. The system image uses only Ubuntu apt packages
with every binary built, signed, and distributed by Canonical. Updated
messaging in README, USER_GUIDE, and both Dockerfile headers. Also marked
macOS Docker tests as verified.

Author: abitofhelp

Dockerfile

@@ -20,9 +20,11 @@
 #   • ARM cross-compiler for embedded development
 #
 # Recommended for:
-#   • Developers who need the latest C++20/23/26 compiler features
+#   • Teams that want the latest C++20/23/26 compiler features and tooling
 #   • Projects using vcpkg for dependency management
-#   • Teams that want the newest static analysis tools (clang-tidy)
+#
+# For auditable supply chains with no third-party repositories, use
+# Dockerfile.system instead — every binary comes from Ubuntu's apt.
 #
 # For the alternate Dockerfile using only Ubuntu's apt packages,
 # see Dockerfile.system.

Dockerfile.system

@@ -17,9 +17,10 @@
 # No external package repositories are added.
 #
 # Recommended for:
-#   • Teams that want compiler updates tied to Ubuntu's release cycle
+#   • Organizations requiring auditable supply chains — every binary is
+#     built, signed, and distributed by Canonical via Ubuntu's apt
 #   • CI/CD pipelines that need stable, reproducible builds
-#   • Developers who prefer minimal external dependencies
+#   • Teams whose policies prohibit third-party package repositories
 #
 # For the default Dockerfile using upstream LLVM + Kitware CMake + vcpkg,
 # see Dockerfile.

README.md

@@ -70,8 +70,8 @@ Both images use Ubuntu 24.04 and support amd64 + arm64 multi-arch builds.
 
 | Image | Ubuntu VM (amd64) | macOS Intel (amd64) | MacBook Pro (arm64) |
 |-------|:---:|:---:|:---:|
-| `dev-container-cpp` | Passed | Pending | Pending |
-| `dev-container-cpp-system` | Passed | Pending | Pending |
+| `dev-container-cpp` | Passed | Passed | Pending |
+| `dev-container-cpp-system` | Passed | Passed | Pending |
 
 ## Image Names
 
@@ -89,11 +89,12 @@ This repository ships two Dockerfiles representing two valid toolchain strategie
 | `Dockerfile` (default) | Ubuntu 24.04 | LLVM repo Clang 20, Kitware CMake, vcpkg | amd64, arm64 | `dev-container-cpp` |
 | `Dockerfile.system` | Ubuntu 24.04 | Ubuntu apt packages only | amd64, arm64 | `dev-container-cpp-system` |
 
-**Which should I use?** Start with the default (`Dockerfile`) for the latest
-C++20/23/26 compiler features, newest static analysis tools, and vcpkg package
-management. Use `Dockerfile.system` if you prefer everything from Ubuntu's apt
-repositories with no external dependencies. See USER_GUIDE §0 for detailed
-rationale.
+**Which should I use?** The deciding factor is **supply chain auditability**.
+The system image installs everything from Ubuntu's apt repositories — every
+binary is built, signed, and distributed by Canonical. Use it when your
+organization requires auditable supply chains with no third-party repositories.
+The default image adds LLVM, Kitware, and vcpkg repositories for the latest
+tooling. See USER_GUIDE §0 for detailed rationale.
 
 ## Why This Container Is Useful
 

USER_GUIDE.md

@@ -18,26 +18,33 @@
 
 ### 0.1 Why there are two Dockerfiles
 
-C++ projects benefit from the latest compiler features (C++20/23/26 support),
-the newest static analysis tools (clang-tidy checks), and up-to-date build
-systems (CMake 4.x). The upstream image provides these by adding the official
-LLVM APT repository, Kitware's CMake repository, and vcpkg for package
-management.
-
-At the same time, some teams prefer everything from Ubuntu's apt repositories
-with no external dependencies — fewer moving parts, predictable updates tied
-to Ubuntu's release cycle.
-
-Rather than declare one approach wrong, this project ships both:
-
-| Dockerfile | Base | Compiler source | Architectures | Image name |
-|------------|------|-----------------|---------------|------------|
-| `Dockerfile` (default) | Ubuntu 24.04 | LLVM repo Clang 20, Kitware CMake, vcpkg | amd64, arm64 | `dev-container-cpp` |
-| `Dockerfile.system` | Ubuntu 24.04 | Ubuntu apt packages only | amd64, arm64 | `dev-container-cpp-system` |
-
-**Start with the default.** It gives you the latest C++ compiler features and
-vcpkg for dependency management. Switch to `Dockerfile.system` if you prefer
-Ubuntu's packaged compilers and want no external repository dependencies.
+The core difference is **supply chain auditability**, not features.
+
+The **system image** installs every package from Ubuntu's apt repositories —
+no external sources. Every binary is built, signed, and distributed by
+Canonical. Organizations that require auditable supply chains, reproducible
+builds tied to a distribution's release cycle, or compliance with packaging
+policies that prohibit third-party repositories should use this image.
+
+The **upstream image** adds three external repositories: LLVM's official APT
+repository (Clang 20), Kitware's APT repository (CMake 4.x), and vcpkg
+(Microsoft's C++ package manager). These provide the latest compiler features
+(C++23/26 support), the newest clang-tidy checks, and access to 2300+ C++
+libraries via vcpkg. The trade-off is that builds depend on sources outside
+Ubuntu's package pipeline.
+
+Both images are functionally equivalent for C++20 development. Both support
+amd64 + arm64. Both include the same embedded toolchain, debuggers, and
+general developer tools.
+
+| Dockerfile | Compiler source | External repos | Image name |
+|------------|-----------------|:--------------:|------------|
+| `Dockerfile` (default) | LLVM repo Clang 20, Kitware CMake 4.x, vcpkg | 3 | `dev-container-cpp` |
+| `Dockerfile.system` | Ubuntu apt packages only (Clang 18, CMake 3.28) | 0 | `dev-container-cpp-system` |
+
+**Choose by policy, not preference.** If your organization requires that all
+binaries come from your distribution's package pipeline, use `Dockerfile.system`.
+Otherwise, start with the default for the latest tooling.
 
 ### 0.2 Supported architectures
 
@@ -507,9 +514,9 @@ release. Remove or update entries as they are verified.
 | Area                              | Status       | Notes                                                        |
 |-----------------------------------|--------------|--------------------------------------------------------------|
 | Rootless nerdctl (local)          | Verified     | Ubuntu 24.04 base, nerdctl. Build + smoke test passed.       |
-| Docker rootful (macOS)            | Pending      | Not yet tested.                                              |
-| GitHub Actions build workflow     | Pending      | Not yet tested (no push to GitHub yet).                      |
-| GitHub Actions publish workflow   | Pending      | Not yet tested (no push to GitHub yet).                      |
+| Docker rootful (macOS)            | Verified     | macOS Intel host, Docker. Build + smoke test passed.         |
+| GitHub Actions build workflow     | Pending      | Not yet tested.                                              |
+| GitHub Actions publish workflow   | Pending      | Not yet tested.                                              |
 | Podman rootless (local)           | Blocked      | `--userns=keep-id` fails in Parallels VM (kernel restriction). |
 | Kubernetes deployment             | Not tested   | Image is designed to be compatible; no cluster available.    |
 
@@ -518,9 +525,9 @@ release. Remove or update entries as they are verified.
 | Area                              | Status       | Notes                                                        |
 |-----------------------------------|--------------|--------------------------------------------------------------|
 | Rootless nerdctl (local)          | Verified     | Ubuntu 24.04 base, nerdctl. Build + smoke test passed.       |
-| Docker rootful (macOS)            | Pending      | Not yet tested.                                              |
-| GitHub Actions build workflow     | Pending      | Not yet tested (no push to GitHub yet).                      |
-| GitHub Actions publish workflow   | Pending      | Not yet tested (no push to GitHub yet).                      |
+| Docker rootful (macOS)            | Verified     | macOS Intel host, Docker. Build + smoke test passed.         |
+| GitHub Actions build workflow     | Pending      | Not yet tested.                                              |
+| GitHub Actions publish workflow   | Pending      | Not yet tested.                                              |
 | Podman rootless (local)           | Blocked      | `--userns=keep-id` fails in Parallels VM (kernel restriction). |
 | Kubernetes deployment             | Not tested   | Image is designed to be compatible; no cluster available.    |