docs: add validate command documentation to README

Add comprehensive documentation for the USM validate command including:
- Command syntax and usage examples
- Detailed validation process description
- Exit codes for CI/CD integration
- Reference to detailed documentation file

README.md

@@ -200,4 +200,38 @@ JSONL transaction journal format
 - USM will not manage the installation if an install exec is present
 - Compare backup and transaction snapshots for validation
 - Scripts can optionally handle installation but it must be verified that the expected files (and only the expected files) are installed
-- Add post-install and maybe post-transaction execs that are not subject to validations
+- Add post-install and maybe post-transaction execs that are not subject to validations
+
+## USM Commands
+
+### Manifest Commands
+
+- `usm manifest build <build path>`: Build the package
+- `usm manifest install <build path>`: Build and install the package to the system
+- `usm manifest remove`: Remove the package from the system
+- `usm manifest acquire`: Run the acquire script to download sources
+- `usm manifest package`: Create a package archive
+- `usm manifest autoprovides [--replace] [--debug] [build path]`: Scan installation and generate provides section
+- `usm manifest test [build path]`: Run package tests
+- `usm manifest validate [build path]`: Validate package by building and checking resources
+
+### Validation Command
+
+The `validate` command performs comprehensive validation of USM packages:
+
+```bash
+usm manifest validate [build path]
+```
+
+The validation process includes:
+- Manifest syntax validation
+- Dependency checking
+- License verification (with warning if missing)
+- Build execution with progress reporting
+- Install execution to temporary directory
+- Resource validation based on path base type (as-expected, build:, source:, install:)
+- Unexpected resource detection
+
+Exit codes indicate specific validation failures, making it suitable for CI/CD environments.
+
+For detailed information, see `slopdocs/utility.usm.manifest.validate.md`.

slopdocs/utility.usm.manifest.validate.md

@@ -0,0 +1,85 @@
+# USM Manifest Validate Command
+
+## Overview
+
+The `usm manifest validate` command performs comprehensive validation of USM packages by building and installing them in a temporary environment, then verifying that all declared resources are present and correctly located.
+
+## Usage
+
+```bash
+usm manifest validate [build path]
+```
+
+### Parameters
+
+- **build path** (optional): Directory where the package will be built. If not specified, a temporary directory will be created automatically.
+
+## Validation Process
+
+The validate command performs the following checks in sequence:
+
+1. **Manifest Validation**: Verifies that MANIFEST.usm can be read and parsed correctly
+2. **Dependency Check**: Ensures all required dependencies are available
+3. **License Check**: Warns if no license has been provided
+4. **Build Execution**: Runs the build script with progress reporting
+5. **Install Execution**: Runs the install script to a temporary directory
+6. **Resource Validation**: Verifies all declared resources exist at their expected locations
+7. **Unexpected Resource Detection**: Warns about resources found in install directory but not declared
+
+## Resource Validation
+
+The command validates each resource based on its path base type:
+
+- **as-expected**: Checks if the file exists at the expected location in the install directory
+- **build:**: Checks if the file exists at the specified path in the build directory
+- **source:**: Checks if the file exists at the specified path in the source directory
+- **install:**: Checks if the file exists at the specified path in the install directory
+
+## Exit Codes
+
+- **0**: Validation completed successfully
+- **247**: Error validating installation result
+- **248**: Expected resources not found
+- **249**: Error running install exec
+- **250**: Could not create temporary install directory
+- **251**: Error running build exec
+- **252**: Missing dependencies
+- **253**: Could not read MANIFEST.usm
+- **254**: No MANIFEST.usm file found
+- **255**: Could not create temporary build directory
+
+## Examples
+
+### Basic validation with automatic temporary directory:
+```bash
+usm manifest validate
+```
+
+### Validation with specified build directory:
+```bash
+usm manifest validate /tmp/usm-build
+```
+
+## Output
+
+The command provides detailed feedback about:
+- Missing dependencies
+- License warnings
+- Build progress
+- Missing expected resources with location details
+- Unexpected resources found in install directory
+- Final validation status
+
+## Integration with CI/CD
+
+The validate command is designed for use in continuous integration environments:
+- Non-zero exit codes indicate validation failures
+- Detailed error messages help identify issues quickly
+- Progress reporting works well with CI logging systems
+- Temporary directory cleanup ensures no side effects
+
+## Comparison with Other Commands
+
+- **autoprovides**: Scans and generates the provides section, while validate checks if existing provides are correct
+- **test**: Runs package tests, while validate verifies the package structure and resources
+- **install**: Installs to the system, while validate installs to a temporary directory for verification only