docs: expand website documentation with guides and architecture

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

@@ -0,0 +1,192 @@
+# Building from Source
+
+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 |
+
+Ensure `JAVA_HOME` is set correctly:
+
+```bash
+# Linux/macOS
+export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+
+# Windows
+set JAVA_HOME=C:\Program Files\Java\jdk-17
+```
+
+## Clone the Repository
+
+Clone the repository with submodules:
+
+```bash
+git clone --recurse-submodules https://github.com/metaschema-framework/liboscal-java.git
+cd liboscal-java
+```
+
+If you already cloned without submodules, initialize them:
+
+```bash
+git submodule update --init --recursive
+```
+
+## Build Commands
+
+### Basic Build
+
+Build and install to your local Maven repository:
+
+```bash
+mvn install
+```
+
+### Run Tests Only
+
+```bash
+mvn test
+```
+
+### Run a Single Test
+
+```bash
+# Run a single test class
+mvn test -Dtest=ExamplesTest
+
+# Run a single test method
+mvn test -Dtest=ExamplesTest#testExample
+```
+
+### Skip Tests
+
+```bash
+mvn install -DskipTests
+```
+
+### CI/CD Build
+
+Replicate the full CI/CD build (recommended before pushing):
+
+```bash
+mvn install -PCI -Prelease
+```
+
+This enables additional checks including:
+- License header verification
+- Code style checks
+- Full test suite
+
+## Code Quality Commands
+
+### Check License Headers
+
+```bash
+mvn license:check
+```
+
+### Auto-format Source Code
+
+```bash
+mvn formatter:format
+```
+
+### Check for Checkstyle Issues
+
+```bash
+mvn checkstyle:check
+```
+
+## Common Build Issues
+
+### Submodule Not Initialized
+
+**Symptom:** Build fails with missing OSCAL schema files.
+
+**Solution:** Initialize submodules:
+
+```bash
+git submodule update --init --recursive
+```
+
+### Java Version Mismatch
+
+**Symptom:** Compilation errors or "unsupported class file version" errors.
+
+**Solution:** Ensure you're using Java 17 or later for building (required due to build plugin requirements):
+
+```bash
+java -version
+mvn -version
+```
+
+### Maven Version Too Old
+
+**Symptom:** Build fails with plugin compatibility errors.
+
+**Solution:** Upgrade Maven to 3.9.0 or later. Check your version:
+
+```bash
+mvn -version
+```
+
+### Out of Memory
+
+**Symptom:** Build fails with `OutOfMemoryError`.
+
+**Solution:** Increase Maven's heap size:
+
+```bash
+export MAVEN_OPTS="-Xmx2g"
+mvn install
+```
+
+### License Header Check Fails
+
+**Symptom:** Build fails during `license:check` phase.
+
+**Solution:** Run the formatter to add missing headers:
+
+```bash
+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:
+
+```
+target/generated-sources/metaschema/
+```
+
+If you make changes to the OSCAL Metaschema modules, run a clean build:
+
+```bash
+mvn clean install
+```
+
+## Contributing
+
+For contribution guidelines, including code style requirements and the pull request process, see [CONTRIBUTING.md](https://github.com/metaschema-framework/liboscal-java/blob/develop/CONTRIBUTING.md).
+
+## 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
+- [Architecture](guides/architecture.html) - Understand the library structure

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

@@ -0,0 +1,139 @@
+# Claude Code Integration
+
+${project.name} includes configuration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Anthropic's agentic coding tool. This integration enables AI-assisted development with context-aware guidance specific to OSCAL and this library.
+
+## Overview
+
+Claude Code can assist with:
+
+- Understanding the OSCAL data model and library architecture
+- Writing code that uses ${project.name} APIs
+- Debugging issues with OSCAL document processing
+- Implementing profile resolution and validation workflows
+- Following project coding conventions and best practices
+
+## Project Configuration
+
+This repository includes a `.claude/` directory with project-specific configuration:
+
+- **CLAUDE.md** - Project instructions and conventions that Claude follows
+- **settings.json** - Tool permissions and project settings
+
+The configuration provides Claude with:
+
+- Build and test commands specific to this project
+- Code style and architecture guidelines
+- Git workflow requirements (worktrees, PR process)
+- Links to relevant documentation
+
+## Claude Plugins
+
+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 |
+| `metaschema:metapath-expressions` | Metapath query language syntax |
+
+### Metaschema Tools Plugin
+
+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 |
+
+### OSCAL Tools Plugin
+
+The `oscal-tools` plugin provides CLI guidance:
+
+| Skill | Description |
+|:------|:------------|
+| `oscal-tools:using-oscal-cli` | OSCAL CLI commands and workflows |
+
+## Installing Plugins
+
+To install metaschema-framework plugins, use the Claude Code settings or install via command line:
+
+```bash
+# Install individual plugins
+claude plugins:install metaschema-framework/oscal
+claude plugins:install metaschema-framework/metaschema
+claude plugins:install metaschema-framework/metaschema-tools
+claude plugins:install metaschema-framework/oscal-tools
+```
+
+## Example Workflows
+
+### Understanding the Library
+
+Ask Claude to explain library concepts:
+
+```
+"Explain how OscalBindingContext works and when I would use it"
+"What's the difference between reading OSCAL as XML vs JSON?"
+"How does profile resolution work in this library?"
+```
+
+### Writing Code
+
+Ask Claude to help write code:
+
+```
+"Write code to load an OSCAL catalog from a JSON file"
+"Create a method that validates an SSP against its imported profile"
+"Show me how to programmatically create a component definition"
+```
+
+### Debugging
+
+Ask Claude to help debug issues:
+
+```
+"This profile resolution is failing with [error]. What's wrong?"
+"Why am I getting a validation error on this control?"
+"Help me understand this Metapath constraint violation"
+```
+
+### Following Best Practices
+
+Ask Claude about conventions:
+
+```
+"What's the correct way to handle null values in this library?"
+"How should I structure tests for OSCAL document processing?"
+"What naming conventions does this project use?"
+```
+
+## Development Workflow Integration
+
+Claude Code integrates with the development workflow defined in CLAUDE.md:
+
+1. **Git Worktrees** - Claude will guide you to use worktrees for feature development
+2. **PR Process** - Claude knows to push to your fork and target the develop branch
+3. **Testing** - Claude will run tests before suggesting code is complete
+4. **Code Style** - Claude applies the project's formatting and style conventions
+
+## 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/claude-plugins/tree/main)
+- [OSCAL Documentation](https://pages.nist.gov/OSCAL/)
+- [Metaschema Specification](https://metaschema.dev/)