docs: expand website documentation with guides and architecture

README.md

@@ -117,6 +117,37 @@ To disable colored output, use the `--no-color` flag:
 metaschema-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 <(metaschema-cli shell-completion bash)
+
+# Or save to a file and source it in your ~/.bashrc for persistence
+metaschema-cli shell-completion bash > ~/.metaschema-completion.bash
+echo 'source ~/.metaschema-completion.bash' >> ~/.bashrc
+```
+
+**Zsh:**
+
+```zsh
+# Ensure your completions directory exists
+mkdir -p ~/.zsh/completions
+
+# Generate completion script
+metaschema-cli shell-completion zsh > ~/.zsh/completions/_metaschema-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.
+
 ## Relationship to prior work
 
 The contents of this repository is based on work from the [Metaschema Java repository](https://github.com/usnistgov/metaschema-java/) maintained by the National Institute of Standards and Technology (NIST), the [contents of which have been dedicated in the worldwide public domain](https://github.com/usnistgov/metaschema-java/blob/1a496e4bcf905add6b00a77a762ed3cc31bf77e6/LICENSE.md) using the [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) public domain dedication. This repository builds on this prior work, maintaining the [CCO license](https://github.com/metaschema-framework/metaschema-java/blob/main/LICENSE.md) on any new works in this repository.

src/site/markdown/building.md.vm

@@ -0,0 +1,166 @@
+# Building from Source
+
+This guide explains how to build the Metaschema Java project 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/metaschema-java.git
+cd metaschema-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=MetaschemaModuleTest
+
+# Run a single test method
+mvn test -Dtest=MetaschemaModuleTest#testLoadModule
+```
+
+### 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
+```
+
+## Common Build Issues
+
+### Submodule Not Initialized
+
+**Symptom:** Build fails with missing Metaschema 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:
+
+```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
+```
+
+## Building the Site
+
+To build the project documentation site:
+
+```bash
+mvn site
+```
+
+The generated site appears in `target/site/`. For multi-module builds, each module's site is in its respective `target/site/` directory.
+
+## 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) - Add the library to your project
+- [Architecture](guides/architecture.html) - Understand the module structure

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

@@ -0,0 +1,112 @@
+# Using with Claude Code
+
+[Claude Code](https://claude.ai/code) is an AI-powered coding assistant that can help you work with Metaschema and OSCAL tools more effectively.
+
+## Overview
+
+Claude Code plugins provide specialized skills for:
+
+- **Metaschema authoring** - Creating and validating Metaschema modules
+- **OSCAL document creation** - Building catalogs, profiles, SSPs
+- **CLI assistance** - Running commands and interpreting output
+- **Metapath expressions** - Writing and debugging queries
+
+## Prerequisites
+
+1. [Install Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+2. Install the [Metaschema plugins](https://github.com/metaschema-framework/claude-plugins/tree/main)
+
+## Available Plugins
+
+### Metaschema Plugin
+
+Skills for working with Metaschema definitions:
+
+| Skill | Description |
+|:------|:------------|
+| `metaschema:metaschema-basics` | Introduction to Metaschema concepts |
+| `metaschema:metaschema-module-authoring` | Creating and modifying modules |
+| `metaschema:metaschema-constraints-authoring` | Defining validation constraints |
+| `metaschema:metapath-expressions` | Writing Metapath queries |
+
+### OSCAL Plugin
+
+Skills for working with OSCAL documents:
+
+| Skill | Description |
+|:------|:------------|
+| `oscal:oscal-basics` | OSCAL document types and structure |
+
+### Tool Plugins
+
+Skills for using CLI and library tools:
+
+| Skill | Description |
+|:------|:------------|
+| `oscal-tools:using-oscal-cli` | Running oscal-cli commands |
+| `metaschema-tools:using-metaschema-java` | Using the Metaschema Java library |
+
+### Development Plugin
+
+For contributors to the Metaschema framework:
+
+| Skill | Description |
+|:------|:------------|
+| `dev-metaschema:development-workflow` | TDD, debugging, testing patterns |
+| `dev-metaschema:repo-organization` | Project structure and relationships |
+| `dev-metaschema:unit-test-writing` | Writing comprehensive tests |
+
+## Example Workflows
+
+### Generate Java Classes from Metaschema
+
+Ask Claude:
+> "Help me set up the Maven plugin to generate Java classes from my Metaschema module"
+
+Claude will guide you through the plugin configuration and code generation process.
+
+### Write a Metapath Expression
+
+Ask Claude:
+> "Help me write a Metapath expression that finds all controls with a specific property"
+
+Claude will use the Metapath skill to construct and explain the expression.
+
+### Validate a Metaschema Module
+
+Ask Claude:
+> "Validate my Metaschema module at `src/main/metaschema/my-model.xml`"
+
+Claude will run validation and explain any errors.
+
+### Debug Constraint Errors
+
+Ask Claude:
+> "I'm getting constraint validation errors. Can you help me understand what's wrong?"
+
+Claude will analyze the errors, explain the constraint requirements, and suggest fixes.
+
+## Tips for Effective Use
+
+1. **Be specific** - Mention file paths and exact error messages
+2. **Provide context** - Share relevant portions of your Metaschema definitions
+3. **Ask for explanations** - Claude can explain why something is required by the specification
+4. **Request examples** - Ask for sample code or Metaschema snippets
+
+## Integration with This Library
+
+When working with the Metaschema Java library, Claude can help you:
+
+- Configure the Maven plugin for code generation
+- Write code using generated binding classes
+- Execute Metapath queries programmatically
+- Implement custom constraint validators
+- Troubleshoot serialization and deserialization issues
+
+## Learn More
+
+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 Specification](https://framework.metaschema.dev/specification/)
+- [Metapath Reference](https://framework.metaschema.dev/specification/metapath/)