docs: left-justify prerequisite tables

Author: david-waltermire

README.md

@@ -29,7 +29,7 @@ You can include these artifacts in your Maven POM as a dependency.
 
 ## Building
 
-This project can be built with [Apache Maven](https://maven.apache.org/) version 3.8.4 or greater.
+This project can be built with [Apache Maven](https://maven.apache.org/) version 3.9.0 or greater.
 
 The following instructions can be used to clone and build this project.
 

src/site/markdown/building.md.vm

@@ -5,7 +5,7 @@ This guide explains how to build ${project.name} 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 |
@@ -154,6 +154,18 @@ mvn install
 mvn license:format
 ```
 
+## Building the Site
+
+To build the project documentation site:
+
+```bash
+mvn install site -DskipTests
+```
+
+**Note:** The `install` and `site` goals must run together in a single Maven invocation. This is required because the Javadoc plugin needs access to the generated OSCAL model classes, which are only available after the `install` phase completes within the same Maven session.
+
+Running `mvn site` alone will fail with Javadoc errors about missing model classes.
+
 ## Generated Sources
 
 OSCAL model classes are generated during the build from Metaschema definitions in the `oscal/` submodule. These generated classes appear in:
@@ -174,5 +186,7 @@ For contribution guidelines, including code style requirements and the pull requ
 
 ## Next Steps
 
+Once you've built the project, explore these resources to start using the library:
+
 - [Installation](installation.html) - Add the library to your project
-- [API Overview](api-overview.html) - Learn about the core library classes
+- [Architecture](guides/architecture.html) - Understand the library structure

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

@@ -28,22 +28,22 @@ The configuration provides Claude with:
 
 ## Claude Plugins
 
-Enhanced capabilities are available through Claude plugins from the [metaschema-framework](https://github.com/metaschema-framework) organization:
+Enhanced capabilities are available through [Claude plugins](https://github.com/metaschema-framework/claude-plugins/tree/main) from the metaschema-framework organization:
 
 ### OSCAL Plugin
 
 The `oscal` plugin provides OSCAL-specific skills:
 
 | Skill | Description |
-|-------|-------------|
+|:------|:------------|
 | `oscal:oscal-basics` | OSCAL document structure, models, and concepts |
 
 ### Metaschema Plugin
 
 The `metaschema` plugin provides Metaschema knowledge:
 
 | Skill | Description |
-|-------|-------------|
+|:------|:------------|
 | `metaschema:metaschema-basics` | Introduction to Metaschema concepts |
 | `metaschema:metaschema-module-authoring` | Creating and modifying Metaschema modules |
 | `metaschema:metaschema-constraints-authoring` | Writing validation constraints |
@@ -54,7 +54,7 @@ The `metaschema` plugin provides Metaschema knowledge:
 The `metaschema-tools` plugin provides CLI and library guidance:
 
 | Skill | Description |
-|-------|-------------|
+|:------|:------------|
 | `metaschema-tools:metaschema-java-library` | Java library interfaces and patterns |
 | `metaschema-tools:using-metaschema-java` | CLI commands for validation and conversion |
 
@@ -63,7 +63,7 @@ The `metaschema-tools` plugin provides CLI and library guidance:
 The `oscal-tools` plugin provides CLI guidance:
 
 | Skill | Description |
-|-------|-------------|
+|:------|:------------|
 | `oscal-tools:using-oscal-cli` | OSCAL CLI commands and workflows |
 
 ## Installing Plugins
@@ -131,7 +131,9 @@ Claude Code integrates with the development workflow defined in CLAUDE.md:
 
 ## Related Resources
 
+For more information about Claude Code and the technologies used in this project:
+
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
-- [Metaschema Framework Plugins](https://github.com/metaschema-framework)
+- [Metaschema Framework Plugins](https://github.com/metaschema-framework/claude-plugins/tree/main)
 - [OSCAL Documentation](https://pages.nist.gov/OSCAL/)
 - [Metaschema Specification](https://metaschema.dev/)

src/site/markdown/guides/architecture.md.vm

@@ -4,9 +4,17 @@ This guide explains the architecture and module structure of liboscal-java.
 
 ## Overview
 
-liboscal-java is built on top of the [Metaschema Java Tools](https://github.com/metaschema-framework/metaschema-java) framework. It provides OSCAL-specific functionality while leveraging the general-purpose Metaschema capabilities.
+liboscal-java is built on top of the [Metaschema Java Tools](https://github.com/metaschema-framework/metaschema-java) framework. It provides OSCAL-specific functionality while leveraging the general-purpose Metaschema capabilities for serialization, validation, and querying.
 
-## Dependency Hierarchy
+Understanding the architecture helps you work effectively with the library, especially when debugging issues or extending its capabilities. The library follows a layered design where each layer builds on the capabilities provided by the layer below.
+
+## Library Structure
+
+This section describes how the library is organized and relates to its dependencies.
+
+### Dependency Hierarchy
+
+The following diagram shows how liboscal-java relates to the underlying Metaschema framework and the OSCAL model definitions:
 
 ```
 liboscal-java
@@ -18,21 +26,25 @@ liboscal-java
     └── OSCAL Metaschema modules (generated model classes)
         ├── oscal_catalog
         ├── oscal_profile
+        ├── oscal_mapping
         ├── oscal_ssp
         ├── oscal_component-definition
         ├── oscal_assessment-plan
         ├── oscal_assessment-results
         └── oscal_poam
 ```
 
-## Package Structure
+### Package Structure
+
+The library's Java packages are organized by functionality. The main entry point is `OscalBindingContext`, and all OSCAL model classes live under the `model` subpackage:
 
 ```
 dev.metaschema.oscal.lib
 ├── OscalBindingContext       # Central entry point
 ├── model/                    # Generated OSCAL model classes
 │   ├── Catalog
 │   ├── Profile
+│   ├── MappingCollection
 │   ├── SystemSecurityPlan
 │   ├── ComponentDefinition
 │   ├── AssessmentPlan
@@ -49,9 +61,11 @@ dev.metaschema.oscal.lib
 
 ## Key Components
 
+The following sections describe the main classes you'll interact with when using the library.
+
 ### OscalBindingContext
 
-The central class for working with OSCAL documents:
+The `OscalBindingContext` is your starting point for all OSCAL operations. It provides factory methods for creating serializers, deserializers, and validators:
 
 ```java
 OscalBindingContext context = OscalBindingContext.instance();
@@ -72,7 +86,7 @@ StaticContext staticCtx = context.getStaticContext();
 
 ### Generated Model Classes
 
-OSCAL model classes are generated during the build from Metaschema definitions:
+Rather than hand-writing Java classes for each OSCAL element, the library generates them from the official OSCAL Metaschema definitions. This ensures the Java model always matches the OSCAL specification:
 
 ```
 oscal/src/main/metaschema/
@@ -89,7 +103,7 @@ target/generated-sources/metaschema/
 
 ### ProfileResolver
 
-Resolves OSCAL profiles to catalogs:
+One of the most important OSCAL operations is profile resolution—converting a profile (which references controls in external catalogs) into a standalone resolved catalog. The `ProfileResolver` class handles this:
 
 ```java
 ProfileResolver resolver = new ProfileResolver();
@@ -105,18 +119,22 @@ Catalog resolved = resolver.resolve(profile);
 
 ### OSCAL Function Library
 
-OSCAL-specific Metapath functions:
+The library extends the base Metapath expression language with OSCAL-specific functions. These are automatically registered when you use `OscalBindingContext`:
 
 | Function | Purpose |
-|----------|---------|
+|:---------|:--------|
 | `has-oscal-namespace` | Check namespace membership |
 | `resolve-profile` | Resolve profile imports |
 | `resolve-reference` | Resolve internal references |
 
 ## Data Flow
 
+Understanding how data flows through the system helps when debugging issues or optimizing performance. This section traces the path of data through the major operations.
+
 ### Reading Documents
 
+When you deserialize an OSCAL document, the library detects the format, parses the content, and maps it to Java objects:
+
 ```
 File/URL
     ↓
@@ -135,6 +153,8 @@ Application Code
 
 ### Writing Documents
 
+Serialization is the reverse process—converting your Java objects back to XML, JSON, or YAML:
+
 ```
 Model Objects
     ↓
@@ -149,6 +169,8 @@ File/Stream
 
 ### Profile Resolution
 
+Profile resolution is more complex because it may involve loading external resources and applying multiple transformations:
+
 ```
 Profile (with imports)
     ↓
@@ -163,14 +185,16 @@ Merge Controls
 Resolved Catalog
 ```
 
-## Integration Points
+## Integration and Extension
 
-### Metaschema Framework
+This section describes how the library integrates with the Metaschema ecosystem and how you can extend it.
 
-liboscal-java extends the Metaschema framework:
+### Metaschema Framework Integration
+
+liboscal-java extends the base Metaschema framework with OSCAL-specific functionality. The following table shows how the library maps to Metaschema components:
 
 | Metaschema Component | liboscal-java Usage |
-|---------------------|---------------------|
+|:---------------------|:--------------------|
 | `IBindingContext` | `OscalBindingContext` extends it |
 | `IDeserializer` | Load OSCAL documents |
 | `ISerializer` | Write OSCAL documents |
@@ -179,24 +203,40 @@ liboscal-java extends the Metaschema framework:
 
 ### Extension Points
 
-**Custom Metapath Functions:**
+The library provides hooks for adding custom functionality without modifying the core code.
+
+#### Custom Metapath Functions
+
+You can extend the Metapath query language with domain-specific functions. This is useful when you need operations that aren't provided by the built-in function library:
+
 ```java
 // Register custom function
 context.registerFunction(myCustomFunction);
 ```
 
-**Custom Constraint Handlers:**
+#### Custom Constraint Handlers
+
+To customize how constraint violations are reported or handled, implement your own validation handler. This allows integration with logging frameworks, custom error reporting, or workflow systems:
+
 ```java
 IConstraintValidationHandler handler = new MyHandler();
 deserializer.setConstraintValidationHandler(handler);
 ```
 
-## Threading Model
+## Runtime Considerations
+
+This section covers topics important when deploying applications that use the library.
+
+### Threading Model
+
+When using the library in multi-threaded applications, understanding which components are thread-safe helps avoid subtle bugs. The general pattern is to share the context but create fresh serializers and deserializers for each operation:
 
-- `OscalBindingContext.instance()` is thread-safe
+- `OscalBindingContext.instance()` is thread-safe for reading configuration
 - Deserializers are single-use (create new per operation)
 - Serializers are single-use (create new per operation)
-- Model objects are not thread-safe for modification
+- Model objects are not thread-safe for concurrent modification
+
+The following example shows the recommended pattern for parallel processing:
 
 ```java
 // Good: Shared context, per-operation deserializers
@@ -209,14 +249,18 @@ executor.submit(() -> {
 });
 ```
 
-## Memory Considerations
+### Memory Considerations
+
+OSCAL documents can vary significantly in size, from small component definitions to comprehensive catalogs like NIST SP 800-53. Keep these factors in mind when working with larger documents:
 
-- Large catalogs (SP 800-53) can consume significant memory
-- Consider streaming for very large documents
-- Profile resolution loads entire import chain into memory
+- Large catalogs (SP 800-53) can consume significant memory when fully loaded
+- Consider streaming approaches for very large documents if you only need to process portions
+- Profile resolution loads the entire import chain into memory, which can be substantial for profiles with deep import hierarchies
 
 ## Build Process
 
+The library uses Maven for its build process. A key step is the automatic generation of Java model classes from the OSCAL Metaschema definitions. This ensures the Java API always matches the official OSCAL specification:
+
 ```
 1. Compile Metaschema Sources
    ↓
@@ -229,16 +273,22 @@ executor.submit(() -> {
 5. Package JAR
 ```
 
+If you're building from source, the generated classes appear in `target/generated-sources/metaschema/` and are automatically included in the compilation.
+
 ## Related Projects
 
+liboscal-java is part of a larger ecosystem of tools for working with OSCAL and Metaschema. Understanding these relationships helps when you need to trace issues or find additional capabilities:
+
 | Project | Relationship |
-|---------|--------------|
+|:--------|:-------------|
 | [metaschema-java](https://github.com/metaschema-framework/metaschema-java) | Core framework dependency |
 | [oscal-cli](https://github.com/metaschema-framework/oscal-cli) | CLI built on liboscal-java |
 | [OSCAL](https://github.com/usnistgov/OSCAL) | Source Metaschema definitions |
 
 ## Next Steps
 
+Continue learning about liboscal-java with these related guides:
+
 - [Loading OSCAL Modules](loading-oscal-modules.html) - Get started with the context
 - [Reading & Writing Data](reading-writing-data.html) - Work with documents
 - [Installation](../installation.html) - Add to your project

src/site/markdown/guides/executing-metapath.md.vm

@@ -15,12 +15,16 @@ import dev.metaschema.core.metapath.MetapathExpression;
 import dev.metaschema.core.metapath.IMetapathExpression;
 import dev.metaschema.core.metapath.item.IItem;
 import dev.metaschema.core.metapath.item.ISequence;
-import dev.metaschema.databind.model.IBoundObject;
+import dev.metaschema.databind.io.Format;
+import dev.metaschema.databind.io.IDeserializer;
+import java.nio.file.Path;
 
 OscalBindingContext context = OscalBindingContext.instance();
 
 // Load a catalog
-Catalog catalog = loadCatalog("catalog.json");
+IDeserializer<Catalog> deserializer = context.newDeserializer(
+    Format.JSON, Catalog.class);
+Catalog catalog = deserializer.deserialize(Path.of("catalog.json"));
 
 // Compile an expression
 IMetapathExpression expression = MetapathExpression.compile(
@@ -262,6 +266,8 @@ public class MetapathQueryCache {
 
 ## Next Steps
 
+Continue learning about liboscal-java with these related guides:
+
 - [Validating with Constraints](validating-with-constraints.html) - Validate queried data
 - [Reading & Writing Data](reading-writing-data.html) - Load documents to query
 - [Architecture](architecture.html) - Understand Metapath internals