readme: key advantages

Signed-off-by: CrazyMax <[email protected]>

Author: crazy-max

README.md

@@ -1,7 +1,26 @@
+[![Test workflow](https://img.shields.io/github/actions/workflow/status/docker/github-builder-experimental/.test.yml?label=test&logo=github&style=flat-square)](https://github.com/docker/github-builder-experimental/actions?workflow=.test)
+
 > [!CAUTION]
 > Do not use it for your production workflows yet!
 
-# GitHub Builder
+## :test_tube: Experimental
+
+This repository is considered **EXPERIMENTAL** and under active development
+until further notice. It is subject to non-backward compatible changes or
+removal in any future version.
+
+___
+
+* [About](#about)
+* [Key Advantages](#key-advantages)
+  * [Performance](#performance)
+  * [Security](#security)
+  * [Isolation & Reliability](#isolation--reliability)
+* [Usage](#usage)
+  * [Build reusable workflow](#build-reusable-workflow)
+  * [Bake reusable workflow](#bake-reusable-workflow)
+
+## About
 
 This repository provides official Docker-maintained [reusable GitHub Actions workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows)
 to securely build container images using Docker best practices. The workflows
@@ -10,13 +29,79 @@ the principles behind [Docker Hardened Images](https://docs.docker.com/dhi/),
 enabling open source projects to follow a seamless path toward higher levels of
 security and trust.
 
-## :test_tube: Experimental
+## Key Advantages
 
-This repository is considered **EXPERIMENTAL** and under active development
-until further notice. It is subject to non-backward compatible changes or
-removal in any future version.
+### Performance
+
+* **Native parallelization for multi-platform builds.**  
+  Workflows automatically distribute builds across runners based on target
+  platform to be built, improving throughput for other architectures without
+  requiring emulation or custom CI logic or self-managed runners.
+
+* **Optimized cache warming & reuse.**  
+  The builder uses the [GitHub Actions cache backend](https://docs.docker.com/build/cache/backends/gha/)
+  to persist layers across branches, PRs, and rebuilds. This significantly
+  reduces cold-start times and avoids repeating expensive dependency
+  installations, even for external contributors' pull requests.
+
+* **Centralized build infrastructure.**  
+  Repositories no longer need to configure buildx drivers, tune storage, or
+  adjust resource limits. The reusable workflow abstracts this away and
+  guarantees fast, consistent builds across any project that opts in.
+
+### Security
+
+* **Hardened multi-tenant builder with strict isolation.**  
+  Builds execute in an environment maintained by Docker with stronger guarantees
+  than ephemeral CI runners. This reduces the attack surface and limits the
+  ability of repository authors to influence the build environment beyond
+  declared inputs.
+
+* **Verifiable, immutable sources.**  
+  The trusted builder fetches source code using GitHub-provided OIDC identity
+  and the exact commit SHA. This ensures builds use the repository contents as
+  checked in—no CI step or workflow author can alter what is being built.
+
+* **Signed SLSA provenance for every build.**  
+  BuildKit generates SLSA-compliant provenance attestation artifacts that are
+  signed and attached to the produced images or local artifacts. Downstream
+  consumers can verify:
+  - which commit produced the image  
+  - what inputs and build parameters were used  
+  - which builder executed the build  
+
+* **Protection from CI tampering.**  
+  The user workflow never executes `docker build` directly. Instead, it
+  delegates the build to a separate, trusted builder. This prevents untrusted
+  workflow steps from modifying the build environment, injecting unexpected
+  flags, or producing misleading provenance.
+
+### Isolation & Reliability
+
+* **Strict separation between CI logic and build execution.**  
+  The calling workflow orchestrates the build but does not execute it. It
+  cannot modify builder state, override provenance, or run `docker build`
+  locally with arbitrary flags or privileged access.
+
+* **Immutable, reproducible build pipeline.**  
+  Builds run using declarative inputs only. This leads to:
+  - reproducibility (same inputs → same outputs)  
+  - auditability (inputs and outputs recorded in provenance)  
+  - reliability (no environment differences across CI runners or forks)  
+
+* **Reduced CI variability and config drift.**  
+  By relying on a centralized builder and reusable workflow, projects avoid
+  maintaining custom build logic per repository. Caching, provenance, SBOM
+  generation, and build settings behave uniformly across all adopters.
+
+* **Higher assurance for downstream consumers.**  
+  Because artifacts are produced in a controlled environment with SLSA
+  provenance, consumers can trust images even from unknown or untrusted
+  repos—an essential part of supply-chain hardening.
+
+## Usage
 
-## Build reusable workflow
+### Build reusable workflow
 
 ```yaml
 name: ci
@@ -72,7 +157,7 @@ on:
 
 You can find the list of available inputs in [`.github/workflows/build.yml`](.github/workflows/build.yml).
 
-## Bake reusable workflow
+### Bake reusable workflow
 
 ```yaml
 name: ci