docs: improve and reorganize validate command documentation

Enhance the documentation structure with clearer sections, expanded details
about each validation step, and better formatting for command comparison
and CI/CD integration information. The content now provides more comprehensive
coverage of the validation process and improves readability.

slopdocs/utility.usm.manifest.validate.md

@@ -1,85 +1,114 @@
 # 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.
+The `usm manifest validate` command validates USM packages by building and installing them in a temporary environment, then verifying all declared resources are present and correctly located.
 
 ## Usage
 
 ```bash
-usm manifest validate [build path]
+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.
+### Arguments
+- `build-path`: Directory for package build (optional, auto-generated if not provided)
 
 ## Validation Process
 
-The validate command performs the following checks in sequence:
+### 1. Manifest Validation
+- Verifies MANIFEST.usm exists and is readable
+- Checks JSON syntax and required fields
+
+### 2. Dependency Verification
+- Validates management dependencies are available
+- Checks build dependencies are satisfied
+- Ensures runtime dependencies exist
+
+### 3. Package Metadata Checks
+- Warns if no license is provided
+- Warns if no markdown description is provided
+- Warns if no URL is provided
+
+### 4. Build Execution
+- Runs build script with progress reporting
+- Uses silent output to reduce noise
 
-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
+### 5. Installation Simulation
+- Creates temporary install directory
+- Runs install script if specified
+- Skips installation validation if no install script exists
 
-## Resource Validation
+### 6. Resource Validation
+Validates each declared resource based on path base:
 
-The command validates each resource based on its path base type:
+#### as-expected
+Checks file exists at standard system location in temporary install directory.
 
-- **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
+#### build:
+Checks file exists at specified path in build directory.
+
+#### source:
+Checks file exists at specified path in source directory.
+
+#### install:
+Checks file exists at specified path in install directory.
+
+### 7. Unexpected Resource Detection
+Scans install directory for resources not declared in manifest and reports warnings.
 
 ## 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
+| Code | Description |
+|------|-------------|
+| 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:
+### Basic Validation
 ```bash
 usm manifest validate
 ```
 
-### Validation with specified build directory:
+### Custom Build Directory
 ```bash
-usm manifest validate /tmp/usm-build
+usm manifest validate /tmp/my-build
 ```
 
-## Output
+## Output Details
 
-The command provides detailed feedback about:
-- Missing dependencies
-- License warnings
-- Build progress
-- Missing expected resources with location details
-- Unexpected resources found in install directory
+The command reports:
+- Missing dependencies with specific resource names
+- Warnings for missing metadata (license, markdown, URL)
+- Build progress percentage
+- Missing expected resources with location descriptions
+- Unexpected resources found during installation scan
 - Final validation status
 
-## Integration with CI/CD
+## CI/CD Integration
+
+Designed for automated environments:
+- Non-zero exit codes indicate failures
+- Detailed error messages for quick issue identification
+- Progress reporting compatible with CI logging
+- Automatic temporary directory cleanup
+
+## Command Comparison
 
-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
+| Command | Purpose |
+|---------|---------|
+| **validate** | Verifies package structure and resources |
+| **autoprovides** | Generates provides section from build output |
+| **test** | Runs package test scripts |
+| **install** | Installs package to system |
 
-## 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
+This command provides comprehensive package validation by building and installing packages in temporary environments to ensure all declared resources are correctly present and located.