From 76301268ed9c2ee8a84fee20931ce29e439b4829 Mon Sep 17 00:00:00 2001
From: CrazyMax <1951866+crazy-max@users.noreply.github.com>
Date: Mon, 26 Oct 2026 11:24:29 +0100
Subject: [PATCH] build: explain Bake policy options in HCL

The guide incorrectly states that Bake policy options require CLI flags.
Document policy objects in HCL and show explicit loading with strict mode.

Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com>
---
 content/manuals/build/policies/usage.md | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/content/manuals/build/policies/usage.md b/content/manuals/build/policies/usage.md
index 7f195241fd..0086a3c3d1 100644
--- a/content/manuals/build/policies/usage.md
+++ b/content/manuals/build/policies/usage.md
@@ -353,8 +353,26 @@ $ docker buildx bake production   # Uses strict policies
 
 ### Bake with policy options
 
-Currently, bake doesn't support policy options (reset, strict, disabled) in the
-HCL file. Use command-line flags instead:
+Use objects in the `policy` list to configure policy loading and evaluation
+for a target. Each object supports `filename`, `reset`, `disabled`, `strict`,
+and `log-level`, with the same meanings as the
+[`docker buildx build --policy` options](#manual-policy-configuration).
+
+For example, load only the specified policy and require policy support from
+the builder:
+
+```hcl {title="docker-bake.hcl"}
+target "production" {
+  policy = [{
+    filename = "policies/production.rego"
+    reset    = true
+    strict   = true
+  }]
+}
+```
+
+Use `disabled = true` to disable policy evaluation for a target. For a
+per-invocation override across the selected targets, use the `--policy` flag:
 
 ```console
 $ docker buildx bake --policy disabled=true production