From f87b6be787e503a00ee1f0704983960991708db9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vin=C3=ADcius=20Ferr=C3=A3o?=
 <2031761+viniciusferrao@users.noreply.github.com>
Date: Fri, 21 Aug 2026 00:00:14 -0300
Subject: [PATCH] docs(genesis): document signed extension bundles

---
 .../guides/code/genesis_openembedded_plan.rst | 12 ++++++--
 xCAT-genesis-builder/README.md                | 29 +++++++++++++++++++
 2 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/docs/source/developers/guides/code/genesis_openembedded_plan.rst b/docs/source/developers/guides/code/genesis_openembedded_plan.rst
index 20e82d267..b8afa4eaf 100644
--- a/docs/source/developers/guides/code/genesis_openembedded_plan.rst
+++ b/docs/source/developers/guides/code/genesis_openembedded_plan.rst
@@ -207,6 +207,12 @@ Genesis verifies Ed25519 signatures before loading extensions with
 site may build a restricted extension from an authorized private source
 mirror when the vendor license forbids public redistribution.
 
+The extension exporter binds the image, manifest, signature, public key, and
+checksums into one directory.  A site layer adds that directory to the
+``xcat-genesis-extensions`` recipe and sets
+``XCAT_GENESIS_EXTENSION_BUNDLE`` to its name.  The signing key remains
+outside both the bundle and the source repository.
+
 Licensing and release records
 -----------------------------
 
@@ -216,9 +222,9 @@ licenses and blocks recipes protected by ``LICENSE_FLAGS`` until the builder
 accepts them explicitly.
 
 Each release records source revisions, patches, configuration, artifact
-checksums, licenses, and an SPDX software bill of materials.  The build uses
-the Yocto release key stored in this repository and verifies its fingerprint;
-it does not contact a public keyserver.
+checksums, licenses, an SPDX software bill of materials, and a VEX report.
+The build uses the Yocto release key stored in this repository and verifies
+its fingerprint; it does not contact a public keyserver.
 
 xCAT server boundary
 --------------------
diff --git a/xCAT-genesis-builder/README.md b/xCAT-genesis-builder/README.md
index c149ddb82..fd6b56d4d 100644
--- a/xCAT-genesis-builder/README.md
+++ b/xCAT-genesis-builder/README.md
@@ -45,6 +45,35 @@ mknb x86_64
 `mknb` verifies the kernel and initramfs checksums before replacing the files
 under the configured TFTP root.
 
+### Signed extensions
+
+Build an extension recipe with the same machine configuration as the Genesis
+image. Then export it with the site's Ed25519 release key:
+
+```sh
+xCAT-genesis-builder/oe/export-extension x86_64 my-extension \
+    xCAT-genesis-builder/oe/.work/build/tmp/deploy \
+    /secure/genesis-extension.key /secure/genesis-extension.pub \
+    /tmp/my-extension-bundle
+```
+
+The private key stays outside the source tree. The exported bundle contains
+the extension image, manifest, signature, public key, and checksums.
+
+A site layer can include that directory in its Genesis image with a small
+append file:
+
+```bitbake
+FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
+SRC_URI += "file://my-extension-bundle"
+XCAT_GENESIS_EXTENSION_BUNDLE = "my-extension-bundle"
+```
+
+Place the exported directory below the append file's `files` directory.
+Genesis verifies every bundled extension before registration and stops the
+boot workflow if the image, manifest, signature, key, release, or architecture
+does not match.
+
 Genesis records registration time and memory use in `/run/xcat/metrics.env`.
 After copying that file from a test VM, create a report with image sizes and
 runtime measurements: