docs(manifest): clarify environment variable usage for exec scripts

Distinguish between USM_* prefixed environment variables for internal
USM process use and non-prefixed variables for executable scripts.
Add comprehensive documentation of all available environment variables
and emphasize that scripts should use DESTDIR, PREFIX, LIBDIR, etc.,
not the USM_* variants which are reserved for USM's internal operation.

slopdocs/structure.usm.manifest.executable-scripts.md

@@ -16,7 +16,24 @@ Required script that compiles source code into binaries.
 - With `simpleBuildEnvironment` flag: Build directory (source tree is copied first)
 
 **Environment Variables**:
-- `USM_DESTDIR`, `USM_PREFIX`, `USM_BINDIR`, etc. are set
+USM sets these non-prefixed variables for execs:
+- `DESTDIR`: Destination directory
+- `PREFIX`: Installation prefix
+- `BINDIR`: Binary directory
+- `INCLUDEDIR`: Include directory
+- `DATADIR`: Data directory
+- `INFODIR`: Info directory
+- `LIBDIR`: Library directory
+- `MANDIR`: Manual directory
+- `LIBEXECDIR`: Libexec directory
+- `LOCALEDIR`: Locale directory
+- `LOCALSTATEDIR`: Local state directory
+- `SBINDIR`: System binary directory
+- `SHAREDSTATEDIR`: Shared state directory
+- `SYSCONFIGDIR`: Configuration directory
+- `TAGSDIR`: Tags directory
+
+Note: The `USM_*` prefixed environment variables are for the USM process itself and should not be used in exec scripts.
 
 **Example**:
 ```bash
@@ -160,7 +177,8 @@ Optional script that runs tests after build but before installation.
 - With `simpleBuildEnvironment` flag: Build directory
 
 **Environment Variables**:
-- `USM_DESTDIR`, `USM_PREFIX`, `USM_BINDIR`, etc. are set
+USM sets the same non-prefixed variables as described in the build script section:
+- `DESTDIR`, `PREFIX`, `BINDIR`, `INCLUDEDIR`, `DATADIR`, `INFODIR`, `LIBDIR`, `MANDIR`, `LIBEXECDIR`, `LOCALEDIR`, `LOCALSTATEDIR`, `SBINDIR`, `SHAREDSTATEDIR`, `SYSCONFIGDIR`, `TAGSDIR`
 
 **Use Case**: Unit tests, integration tests, validation of build artifacts
 
@@ -196,7 +214,9 @@ Scripts should:
 - Handle cleanup on failure
 
 ### Environment Variables
-USM sets these variables for all scripts:
+
+#### USM Process Variables (Internal Use)
+The following `USM_*` prefixed environment variables are used by the USM process itself to configure paths:
 - `USM_DESTDIR`: Destination directory
 - `USM_PREFIX`: Installation prefix
 - `USM_BINDIR`: Binary directory
@@ -212,6 +232,27 @@ USM sets these variables for all scripts:
 - `USM_SHAREDSTATEDIR`: Shared state directory
 - `USM_SYSCONFIGDIR`: Configuration directory
 - `USM_TAGSDIR`: Tags directory
+- `USM_CONFIGDIR`: USM configuration directory
+
+#### Executable Script Variables (For Scripts)
+USM sets these non-prefixed variables for all executable scripts:
+- `DESTDIR`: Destination directory
+- `PREFIX`: Installation prefix
+- `BINDIR`: Binary directory
+- `INCLUDEDIR`: Include directory
+- `DATADIR`: Data directory
+- `INFODIR`: Info directory
+- `LIBDIR`: Library directory
+- `MANDIR`: Manual directory
+- `LIBEXECDIR`: Libexec directory
+- `LOCALEDIR`: Locale directory
+- `LOCALSTATEDIR`: Local state directory
+- `SBINDIR`: System binary directory
+- `SHAREDSTATEDIR`: Shared state directory
+- `SYSCONFIGDIR`: Configuration directory
+- `TAGSDIR`: Tags directory
+
+**Important**: Executable scripts should use the non-prefixed variables (e.g., `${PREFIX}`, `${LIBDIR}`) and NOT the `USM_*` prefixed variables, which are for internal USM process use only.
 
 ## Script Locations
 

slopdocs/structure.usm.manifest.resource-types.md

@@ -120,9 +120,11 @@ Examples:
 
 USM resolves resource paths in this order:
 1. Check standard system locations for the resource type
-2. Use environment variables when set (USM_PREFIX, USM_LIBDIR, etc.)
+2. Use USM_* environment variables when set (USM_PREFIX, USM_LIBDIR, etc.)
 3. Fall back to default paths
 
+Note: The USM_* environment variables are for the USM process itself and are used to configure how USM resolves paths internally.
+
 ## Common Usage Patterns
 
 ### Development Libraries
@@ -191,6 +193,16 @@ USM respects these environment variables for path customization:
 - `USM_DATADIR`: Data directory
 - `USM_MANDIR`: Manual page directory
 - `USM_TAGSDIR`: Tags directory
+- `USM_INFODIR`: Info directory
+- `USM_LIBEXECDIR`: Libexec directory
+- `USM_LOCALEDIR`: Locale directory
+- `USM_LOCALSTATEDIR`: Local state directory
+- `USM_SBINDIR`: System binary directory
+- `USM_SHAREDSTATEDIR`: Shared state directory
+- `USM_SYSCONFIGDIR`: Configuration directory
+- `USM_CONFIGDIR`: USM configuration directory
+
+Note: These USM_* variables are for the USM process itself. Executable scripts should use the non-prefixed versions (DESTDIR, PREFIX, LIBDIR, etc.) as documented in the executable scripts reference.
 
 ---