feat: fix and extend glossary after feature rework

docs/explanation/builder.md

@@ -16,6 +16,7 @@ github_source_path: docs/explanation/builder.md
 github_target_path: docs/explanation/builder.md
 ---
 
+
 # How the Build System Works
 
 ## The Builder
@@ -58,7 +59,7 @@ The resolved version is passed to `make` as `DEFAULT_VERSION` and combined with
 
 For example, `./build aws-gardener_prod-amd64` on `main` produces artifacts prefixed `aws-gardener_prod-amd64-today-<short_commit>`.
 
-The four-level naming hierarchy — cname, flavor, versioned flavor, and artifact base name — is defined in [ADR 0035](/reference/adr/0035-cname-flavor-artifact-naming). For a full explanation of how features and feature types compose, see [Flavors](/explanation/flavors) and [Features](/explanation/features). For the canonical names specification, see [Flavors Reference](/reference/flavors#canonical-names).
+The four-level naming hierarchy — cname, flavor, versioned flavor, and artifact base name — is defined in [ADR 0035](/reference/adr/0035-cname-flavor-artifact-naming). For a full explanation of how features and feature types compose, see [Flavors](/explanation/flavors) and [Features](/explanation/features). For the canonical names specification, see [Flavors Reference](/reference/flavors#feature-list).
 
 ## Cross-Architecture Builds
 

docs/explanation/features.md

@@ -8,6 +8,7 @@ related_topics:
   - /reference/features/
   - /reference/adr/0034-feature-terminology.md
   - /reference/adr/0020-enforce-single-platform-by-default-in-builder.md
+  - /contributing/documentation/features
 github_org: gardenlinux
 github_repo: builder
 github_source_path: docs/explanation/features.md
@@ -18,7 +19,7 @@ github_target_path: docs/explanation/features.md
 
 ## What Is a Feature?
 
-A **feature** is the atomic building block of a Garden Linux image. Each feature is a named directory inside the `features/` tree of the Garden Linux repository containing at minimum an `info.yaml` file that declares its type and dependencies.
+A **feature** is the atomic building block of a Garden Linux image. Each feature is a named directory inside the `features/` tree of the Garden Linux repository containing at minimum an `info.yaml` file that declares its type and dependencies and a [`README.md` that explains the feature](/contributing/documentation/features).
 
 Features are not independent. They form a **directed acyclic graph (DAG)** where each feature may declare:
 

docs/how-to/building-images.md

@@ -58,7 +58,7 @@ Where:
   last component. Defaults to the host architecture when omitted.
 
 :::info Partial arguments are accepted
-You can pass any subset of the full [naming hierarchy](/reference/flavors#canonical-names):
+You can pass any subset of the full [naming hierarchy](/reference/flavors#feature-list):
 a bare cname (e.g. `aws-gardener_prod`), a flavor (cname + arch, e.g.
 `aws-gardener_prod-amd64`), or a versioned flavor (flavor + version, e.g.
 `aws-gardener_prod-amd64-1877.3`). Any missing component is resolved
@@ -110,7 +110,7 @@ apt install qemu-user-static
 
 :::
 
-## Build Secureboot / Trustedboot / TPM2 Images
+## Build Secureboot, Trustedboot and TPM2 Images
 
 Before building any image with the [`_tpm2`](/reference/features/_tpm2) or [`_trustedboot`](/reference/features/_trustedboot)
 feature, generate the signing certificates:

docs/how-to/custom-feature.md

@@ -5,6 +5,7 @@ related_topics:
   - /reference/supporting_tools/builder.md
   - /reference/features/
   - /how-to/custom-feature
+  - /contributing/documentation/features
 github_org: gardenlinux
 github_repo: builder
 github_source_path: docs/how-to/custom-feature.md
@@ -229,6 +230,22 @@ Commit and push your changes and GitHub will build the image for you.
 
 You have successfully created your first feature with the Builder and set up a CI pipeline to build the image.
 
+## Document your feature
+
+Every feature in Garden Linux must have a `README.md` that describes what it does,
+which files it provides, and how it relates to other features. For Garden Linux
+features, follow the [feature README authoring standard](/contributing/documentation/features).
+
+Run the scaffold helper to generate the `### Files` table and `### Related features`
+skeleton for your feature:
+
+```bash
+bin/gl-feature-readme-scaffold features/<name>
+```
+
+The script reads `info.yaml`, lists all files in the feature directory, and prints a
+ready-to-paste markdown table pre-linked to the [feature file reference](/reference/features/).
+
 ## Related Topics
 
 <RelatedTopics />