Adding custom environment variables details (#2869)

## Type of change

**Documentation enhancement**

This PR adds documentation for custom environment variables in Custom
Assembly, expanding the existing custom annotations section to cover
both features comprehensively.

### What should this PR do?

resolves chainguard-dev/internal#5257

### Why are we making this change?

Custom Assembly supports adding custom environment variables to
Chainguard Containers, but this capability was not documented. Users
need to understand how to set runtime defaults and configuration values
for their customized container images.

### What are the acceptance criteria? 

- [ ] Documentation clearly explains how to add custom environment
variables using chainctl
- [ ] Includes a practical example with common use cases (NODE_ENV,
API_URL, PORT, LOG_LEVEL, CACHE_TTL)
- [ ] Documents the restriction on CHAINGUARD_ prefixed environment
variables
- [ ] Section is logically organized alongside custom annotations
documentation
- [ ] Code examples use proper YAML formatting

### How should this PR be tested?

1. Review the documentation for clarity and completeness
2. Verify that the YAML examples are properly formatted
3. Confirm that the environment variable restrictions are clearly stated
4. Check that the new section flows naturally with the existing custom
annotations section
5. Optionally: Test the documented commands against a Custom Assembly
container to verify accuracy

---------

Signed-off-by: Mark Drake <mark@chainguard.dev>

Author: SharpRake

content/chainguard/chainguard-images/features/ca-docs/custom-assembly-chainctl.md

@@ -134,7 +134,11 @@ cgr.dev/example.com/custom-node
 Note that you **must** pass the new image's name when using the `--save-as` option; `chainctl` will return an error if you don't include a new name. Additionally, you can only use this option with the `edit` subcommand; you cannot create a new image declaratively using the `apply` subcommand.
 
 
-## Adding Custom Annotations
+## Adding Custom Annotations and Environment Variables
+
+Custom Assembly lets you extend Chainguard Containers with your own metadata and runtime defaults by adding custom annotations and environment variables through `chainctl`.
+
+### Custom annotations
 
 Chainguard Containers include metadata in the form of *annotations*. These annotations provide important information about the container image's origin, contents, and characteristics. 
 
@@ -146,7 +150,7 @@ chainctl image repo build edit --parent $ORGANIZATION --repo $CONTAINER
 
 In the text editor, add an `annotations` section to the bottom of the file like the following example:
 
-```
+```yaml
 contents:
   packages:
     - jq
@@ -164,6 +168,37 @@ You can also apply custom annotations declaratively using the `apply` subcommand
 
 Note that Custom Assembly blocks `org.opencontainers` and `dev.chainguard` annotations from being changed. 
 
+### Custom environment variables
+
+Chainguard Containers often come with a set of predefined environment variables. These are useful for setting certain configuration details that are available to the container at runtime.
+
+You can follow the same procedure for adding custom annotations to add custom environment variables to your Custom Assembly container images. Start by running a `chainctl image repo build edit` command: 
+
+```shell
+chainctl image repo build edit --parent $ORGANIZATION --repo $CONTAINER
+```
+
+In the text editor, add an `environment` section like the following example:
+
+```yaml
+contents:
+  packages:
+    - jq
+    - git
+    - curl
+
+environment:
+  NODE_ENV: production
+  API_URL: https://api.example.com
+  PORT: "3000"
+  LOG_LEVEL: info
+  CACHE_TTL: "300"
+```
+
+After saving and confirming these changes, Custom Assembly will add these five custom environment variables to the container image. As with packages and annotations, you can also apply custom environment variables declaratively using the `apply` subcommand, as outlined previously.
+
+Be aware that Custom Assembly blocks any environment variable that begins with `CHAINGUARD_` from being added or changed. This is to prevent conflicts with configuration details managed by Chainguard.
+
 
 ## Retrieving Information about Custom Assembly Containers