docs: left-justify prerequisite tables

Author: david-waltermire

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "java.configuration.updateBuildConfiguration": "interactive"
+}

src/site/markdown/building.md.vm

@@ -5,7 +5,7 @@ This guide explains how to build the OSCAL CLI from source code.
 ## Prerequisites
 
 | Requirement | Minimum Version | Notes |
-|-------------|-----------------|-------|
+|:------------|:----------------|:------|
 | Java JDK    | 17              | Required for building (output JARs are JDK 11 compatible) |
 | Maven       | 3.9.0           | Required for building |
 | Git         | 2.0             | Required for cloning |
@@ -128,6 +128,16 @@ docker build -t oscal-cli:local .
 docker run --rm oscal-cli:local --help
 ```
 
+## Building the Site
+
+To build the project documentation site:
+
+```bash
+mvn site
+```
+
+The generated site appears in `target/site/`.
+
 ## Common Build Issues
 
 ### Submodule Not Initialized

src/site/markdown/claude-integration.md.vm

@@ -15,7 +15,7 @@ Claude Code plugins provide specialized skills for:
 ## Prerequisites
 
 1. [Install Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-2. Ensure the OSCAL plugins are available in your configuration
+2. Install the [Metaschema plugins](https://github.com/metaschema-framework/claude-plugins/tree/main)
 
 ## Available Plugins
 
@@ -24,23 +24,23 @@ Claude Code plugins provide specialized skills for:
 Skills for working with OSCAL documents:
 
 | Skill | Description |
-|-------|-------------|
+|:------|:------------|
 | `oscal:oscal-basics` | OSCAL document types and structure |
 
 ### OSCAL Tools Plugin
 
 Skills for using the CLI:
 
 | Skill | Description |
-|-------|-------------|
+|:------|:------------|
 | `oscal-tools:using-oscal-cli` | Running oscal-cli commands |
 
 ### Metaschema Plugin
 
 Skills for understanding OSCAL's underlying structure:
 
 | Skill | Description |
-|-------|-------------|
+|:------|:------------|
 | `metaschema:metaschema-basics` | Introduction to Metaschema concepts |
 | `metaschema:metapath-expressions` | Writing Metapath queries |
 
@@ -108,6 +108,8 @@ oscal-cli metapath eval -e "//control" catalog.json
 
 ## Learn More
 
+For more information about Claude Code, OSCAL, and the CLI, see these resources:
+
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
 - [OSCAL Documentation](https://pages.nist.gov/OSCAL/)
 - [CLI Reference](guides/cli-reference.html)

src/site/markdown/guides/cli-reference.md.vm

@@ -1,13 +1,13 @@
 # CLI Reference
 
-Complete reference for all oscal-cli commands.
+This page provides a complete reference for all oscal-cli commands and options. For task-oriented guides, see the individual guide pages linked at the bottom.
 
 ## Global Options
 
-These options are available for all commands:
+These options work with any command and control the general behavior of the CLI:
 
 | Option | Description |
-|--------|-------------|
+|:-------|:------------|
 | `--help`, `-h` | Show help for any command |
 | `--version`, `-V` | Show version information |
 | `--show-stack-trace` | Show detailed error information |
@@ -26,13 +26,13 @@ oscal-cli validate [options] <file>
 **Arguments:**
 
 | Argument | Description |
-|----------|-------------|
+|:---------|:------------|
 | `<file>` | Path or URL to OSCAL document |
 
 **Options:**
 
 | Option | Description |
-|--------|-------------|
+|:-------|:------------|
 | `--as=<format>` | Force input format: `xml`, `json`, `yaml` |
 
 **Examples:**
@@ -54,7 +54,7 @@ oscal-cli validate --show-stack-trace ssp.json
 **Exit Codes:**
 
 | Code | Meaning |
-|------|---------|
+|:-----|:--------|
 | 0 | Validation passed |
 | 1 | Validation failed |
 | 2 | Invalid arguments |
@@ -72,14 +72,14 @@ oscal-cli convert [options] <source> [destination]
 **Arguments:**
 
 | Argument | Description |
-|----------|-------------|
+|:---------|:------------|
 | `<source>` | Input file path or URL |
 | `[destination]` | Output file path (optional, stdout if omitted) |
 
 **Options:**
 
 | Option | Description |
-|--------|-------------|
+|:-------|:------------|
 | `--to=<format>` | Output format: `xml`, `json`, `yaml` (required) |
 | `--as=<format>` | Input format: `xml`, `json`, `yaml` |
 | `--overwrite` | Overwrite existing output file |
@@ -110,14 +110,14 @@ oscal-cli resolve-profile [options] <profile> [catalog]
 **Arguments:**
 
 | Argument | Description |
-|----------|-------------|
+|:---------|:------------|
 | `<profile>` | Input profile file or URL |
 | `[catalog]` | Output catalog file (optional, stdout if omitted) |
 
 **Options:**
 
 | Option | Description |
-|--------|-------------|
+|:-------|:------------|
 | `--to=<format>` | Output format: `xml`, `json`, `yaml` |
 | `--as=<format>` | Input format: `xml`, `json`, `yaml` |
 | `--overwrite` | Overwrite existing output file |
@@ -152,13 +152,13 @@ oscal-cli metapath eval [options] -e <expression> <file>
 **Arguments:**
 
 | Argument | Description |
-|----------|-------------|
+|:---------|:------------|
 | `<file>` | Input file to query |
 
 **Options:**
 
 | Option | Description |
-|--------|-------------|
+|:-------|:------------|
 | `-e <expression>` | Metapath expression to evaluate (required) |
 | `--to=<format>` | Output format: `xml`, `json`, `yaml` |
 
@@ -188,7 +188,7 @@ oscal-cli generate-completion <shell>
 **Arguments:**
 
 | Argument | Description |
-|----------|-------------|
+|:---------|:------------|
 | `<shell>` | Shell type: `bash` or `zsh` |
 
 **Examples:**
@@ -205,12 +205,13 @@ oscal-cli generate-completion zsh > _oscal-cli
 
 ## OSCAL Document Types
 
-The CLI recognizes these OSCAL document types automatically:
+The CLI automatically detects the document type by examining the root element. You don't need to specify the document type—validation and conversion work for all types:
 
 | Type | Root Element |
-|------|--------------|
+|:-----|:-------------|
 | Catalog | `catalog` |
 | Profile | `profile` |
+| Mapping | `mapping-collection` |
 | System Security Plan | `system-security-plan` |
 | Component Definition | `component-definition` |
 | Assessment Plan | `assessment-plan` |
@@ -219,10 +220,10 @@ The CLI recognizes these OSCAL document types automatically:
 
 ## Format Detection
 
-File formats are detected by extension:
+The CLI determines input format from the file extension. This works for most cases:
 
 | Extension | Format |
-|-----------|--------|
+|:----------|:-------|
 | `.xml` | XML |
 | `.json` | JSON |
 | `.yaml`, `.yml` | YAML |
@@ -231,23 +232,29 @@ Use `--as` to override detection for files with non-standard extensions.
 
 ## Environment Variables
 
+The CLI respects standard Java environment variables for configuration:
+
 | Variable | Description |
-|----------|-------------|
+|:---------|:------------|
 | `JAVA_HOME` | Java installation directory |
 | `JAVA_OPTS` | JVM options (e.g., `-Xmx2g`) |
 
 ## Container Reference
 
+When using Docker, the following tags and options are available:
+
 ### Image Tags
 
 | Tag | Description |
-|-----|-------------|
+|:----|:------------|
 | `latest` | Latest stable release |
 | `x.y.z` | Specific version |
 | `develop` | Latest development build |
 
 ### Volume Mounting
 
+Mount local directories to make your files accessible inside the container:
+
 ```bash
 # Mount current directory
 docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest ...
@@ -258,6 +265,8 @@ docker run --rm -v "/path/to/files:/data" ghcr.io/metaschema-framework/oscal-cli
 
 ### Resource Limits
 
+For large documents, you may need to increase container memory or CPU limits:
+
 ```bash
 # Limit memory
 docker run --rm -m 2g ghcr.io/metaschema-framework/oscal-cli:latest ...

src/site/markdown/guides/converting-formats.md.vm

@@ -2,9 +2,21 @@
 
 This guide explains how to convert OSCAL documents between XML, JSON, and YAML formats.
 
+## Why Convert?
+
+OSCAL supports three serialization formats—XML, JSON, and YAML—with identical semantics across all three. Organizations often need to convert between formats for various reasons:
+
+- **Tooling requirements** - Different tools in your workflow may require specific formats
+- **Standardization** - Establishing a single canonical format for your organization
+- **Human readability** - YAML is often preferred for manual editing, XML for transformation
+- **Integration** - APIs and web services typically prefer JSON
+- **Storage efficiency** - JSON is generally more compact than XML
+
+The OSCAL CLI makes conversion simple. Because OSCAL defines format-agnostic semantics, you can convert documents without data loss—the information remains identical regardless of format.
+
 ## Overview
 
-The `convert` command transforms OSCAL documents between supported formats while preserving all content and structure.
+The `convert` command transforms OSCAL documents between supported formats while preserving all content and structure. The command reads the input document, validates it against the OSCAL model, and writes it in the target format.
 
 ## Basic Conversion
 
@@ -34,15 +46,15 @@ oscal-cli convert --to=json component.yaml component.json
 
 ## Format Detection
 
-The CLI automatically detects the input format based on file extension:
+The CLI determines the input format automatically by examining the file extension. This makes typical conversions simple—you only need to specify the desired output format:
 
 | Extension | Format |
-|-----------|--------|
+|:----------|:-------|
 | `.xml`    | XML    |
 | `.json`   | JSON   |
 | `.yaml`, `.yml` | YAML |
 
-To override automatic detection:
+If your file uses a non-standard extension (or no extension), you can override automatic detection:
 
 ```bash
 oscal-cli convert --as=xml --to=json input.txt output.json
@@ -66,6 +78,8 @@ oscal-cli convert --to=json --overwrite catalog.xml catalog.json
 
 ## Converting All OSCAL Document Types
 
+Conversion works the same way for all OSCAL document types. The CLI detects the document type from the content and applies the appropriate conversion rules. Here are examples for each type:
+
 ### Catalogs
 
 ```bash
@@ -78,6 +92,12 @@ oscal-cli convert --to=json NIST_SP-800-53_catalog.xml NIST_SP-800-53_catalog.js
 oscal-cli convert --to=xml FedRAMP_HIGH_profile.json FedRAMP_HIGH_profile.xml
 ```
 
+### Mappings
+
+```bash
+oscal-cli convert --to=json mapping.xml mapping.json
+```
+
 ### System Security Plans
 
 ```bash
@@ -105,6 +125,8 @@ oscal-cli convert --to=json poam.xml poam.json
 
 ## Batch Conversion
 
+When migrating a collection of documents to a new format, shell scripting handles the repetitive work. The following examples show how to convert multiple files at once:
+
 ### Convert All XML to JSON
 
 #[[
@@ -127,6 +149,8 @@ find . -name "*.xml" -exec sh -c '
 
 ## Container Usage
 
+Docker provides a convenient way to run conversions without installing Java locally. Mount your working directory into the container to access your files:
+
 #[[
 ```bash
 # Convert a single file
@@ -145,6 +169,8 @@ docker run --rm -v "$(pwd):/data" \
 
 ## CI/CD Integration
 
+Automated format conversion is useful when publishing artifacts—for example, generating JSON versions of XML source files when creating a release:
+
 ### GitHub Actions - Convert on Release
 
 #[[
@@ -166,10 +192,12 @@ docker run --rm -v "$(pwd):/data" \
 
 ## Format Considerations
 
+Choosing a format depends on your use case. Each format has trade-offs that may influence your decision. The following tables summarize the key differences:
+
 ### XML vs JSON
 
 | Aspect | XML | JSON |
-|--------|-----|------|
+|:-------|:----|:-----|
 | Human readability | Good with formatting | Good |
 | File size | Larger | Smaller |
 | Comments | Supported | Not supported |
@@ -179,7 +207,7 @@ docker run --rm -v "$(pwd):/data" \
 ### YAML vs JSON
 
 | Aspect | YAML | JSON |
-|--------|------|------|
+|:-------|:-----|:-----|
 | Human readability | Excellent | Good |
 | Editing | Easy | Standard |
 | Comments | Supported | Not supported |
@@ -188,6 +216,8 @@ docker run --rm -v "$(pwd):/data" \
 
 ## Troubleshooting
 
+When conversion fails, the error messages point to the issue. Here are solutions for common problems:
+
 ### Invalid Input Format
 
 ```
@@ -215,6 +245,8 @@ oscal-cli convert --to=xml input.json output.xml
 
 ## Next Steps
 
+Continue learning about the OSCAL CLI with these related guides:
+
 - [Validating OSCAL](validating-oscal.html) - Validate before converting
 - [Resolving Profiles](resolving-profiles.html) - Resolve profiles to catalogs
 - [CLI Reference](cli-reference.html) - Complete command reference