docs: expand website documentation with guides and architecture

.vscode/settings.json

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

README.md

@@ -102,9 +102,40 @@ To disable colored output, use the `--no-color` flag:
 oscal-cli --no-color <command>
 ```
 
+### Shell Completion
+
+The CLI supports tab completion for Bash and Zsh shells, providing intelligent suggestions for commands, subcommands, and options.
+
+**Bash:**
+
+```bash
+# Generate and source completion (temporary, current session only)
+source <(oscal-cli generate-completion bash)
+
+# Or save to a file and source it in your ~/.bashrc for persistence
+oscal-cli generate-completion bash > ~/.oscal-completion.bash
+echo 'source ~/.oscal-completion.bash' >> ~/.bashrc
+```
+
+**Zsh:**
+
+```zsh
+# Ensure your completions directory exists
+mkdir -p ~/.zsh/completions
+
+# Generate completion script
+oscal-cli generate-completion zsh > ~/.zsh/completions/_oscal-cli
+
+# Add to your ~/.zshrc if not already configured
+echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
+echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
+```
+
+After setting up completion, restart your shell or source the configuration file.
+
 ## 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,195 @@
+# Building from Source
+
+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 |
+
+Ensure `JAVA_HOME` is set correctly:
+
+```bash
+# macOS
+export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+
+# Linux (adjust path to your installation)
+export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
+
+# 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/oscal-cli.git
+cd oscal-cli
+```
+
+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
+```
+
+This produces the CLI distribution in `target/oscal-cli-enhanced-*-oscal-cli.zip`.
+
+### Run Tests Only
+
+```bash
+mvn test
+```
+
+### Run a Single Test
+
+```bash
+# Run a single test class
+mvn test -Dtest=CLITest
+
+# Run a single test method
+mvn test -Dtest=CLITest#testValidate
+```
+
+### 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
+- Checkstyle code style checks
+- SpotBugs static analysis
+- 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
+```
+
+## Running the Built CLI
+
+After building, you can run the CLI directly:
+
+```bash
+# Extract the distribution
+unzip target/oscal-cli-enhanced-*-oscal-cli.zip -d target/cli
+
+# Run the CLI
+target/cli/bin/oscal-cli --help
+```
+
+## Building Container Images
+
+To build a local container image:
+
+```bash
+# Build with Docker
+docker build -t oscal-cli:local .
+
+# Test the image
+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
+
+**Symptom:** Build fails with missing OSCAL or Metaschema 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:
+
+```bash
+java -version
+mvn -version
+```
+
+### Maven Version Too Old
+
+**Symptom:** Build fails with plugin compatibility errors or enforcer rule failures.
+
+**Solution:** Upgrade Maven to 3.9.0 or later:
+
+```bash
+mvn -version
+```
+
+### Out of Memory
+
+**Symptom:** Build fails with `OutOfMemoryError`.
+
+**Solution:** Increase Maven's heap size:
+
+```bash
+export MAVEN_OPTS="-Xmx2g"
+mvn install
+```
+
+## Contributing
+
+For contribution guidelines, including code style requirements and the pull request process, see [CONTRIBUTING.md](${project.scm.url}/blob/develop/CONTRIBUTING.md).
+
+## Next Steps
+
+- [Installation](installation.html) - Install the pre-built CLI
+- [CLI Reference](guides/cli-reference.html) - Complete command reference

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

@@ -0,0 +1,114 @@
+# Using with Claude Code
+
+[Claude Code](https://claude.ai/code) is an AI-powered coding assistant that can help you work with OSCAL CLI more effectively.
+
+## Overview
+
+Claude Code plugins provide specialized skills for:
+
+- **OSCAL document validation** - Validating catalogs, profiles, SSPs, and other OSCAL artifacts
+- **Format conversion** - Converting between XML, JSON, and YAML formats
+- **Profile resolution** - Resolving profiles to produce baseline catalogs
+- **Metapath queries** - Writing expressions to query OSCAL content
+- **CLI assistance** - Running commands and interpreting output
+
+## Prerequisites
+
+1. [Install Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+
+## Available Plugins
+
+### OSCAL Plugin
+
+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 |
+
+## Example Workflows
+
+### Validate an OSCAL Document
+
+Ask Claude:
+> "Validate my SSP at `ssp.json` and explain any errors"
+
+Claude will run the validation and help you understand and fix issues.
+
+### Convert Between Formats
+
+Ask Claude:
+> "Convert my catalog from XML to JSON"
+
+Claude will guide you through the conversion process.
+
+### Resolve a Profile
+
+Ask Claude:
+> "Help me resolve my NIST 800-53 profile to a baseline catalog"
+
+Claude will explain profile resolution and run the appropriate command.
+
+### Query OSCAL Content
+
+Ask Claude:
+> "Write a Metapath expression to find all controls with a specific label"
+
+Claude will construct the expression and show how to use it with the CLI.
+
+### Debug Validation Errors
+
+Ask Claude:
+> "I'm getting validation errors on my component definition. Can you help?"
+
+Claude will analyze the errors and suggest fixes.
+
+## Tips for Effective Use
+
+1. **Be specific** - Mention file paths and exact error messages
+2. **Provide context** - Share the OSCAL document type you're working with
+3. **Ask for explanations** - Claude can explain OSCAL concepts and requirements
+4. **Request examples** - Ask for sample OSCAL snippets or CLI commands
+
+## Common Commands
+
+Here are CLI commands that Claude can help you with:
+
+```bash
+# Validate OSCAL content
+oscal-cli validate document.json
+
+# Convert formats
+oscal-cli convert --to=json catalog.xml catalog.json
+
+# Resolve a profile
+oscal-cli resolve-profile profile.xml resolved-catalog.xml
+
+# Evaluate Metapath expressions
+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)