Document VersionMark capture and publish functionality

[Copilot]

Pull Request

Description

Documented VersionMark's core functionality: capturing tool versions from CI/CD jobs and publishing consolidated version reports.

Documentation Changes

• README.md: Quick start guide with capture/publish workflow, configuration examples, command-line options
• docs/guide/guide.md: Comprehensive guide covering:
  • .versionmark.yaml configuration format (tool definitions, OS-specific overrides, regex patterns)
  • Capture mode with --job-id parameter
  • Publish mode with version consolidation logic
  • GitHub Actions integration example
  • Common workflows and troubleshooting
• AGENTS.md: Updated project context from template tool to VersionMark
• .cspell.json: Added VersionMark-specific terms

Key Concepts

Capture: Executes commands per .versionmark.yaml, extracts versions via regex, outputs JSON with job-id and timestamp.

Publish: Reads multiple JSON captures, consolidates versions. Common versions shown as "All jobs"; conflicts listed per job-id.

Example Configuration:

tools:
  - name: gcc
    command: gcc --version
    regex: 'gcc \(.*\) (\d+\.\d+\.\d+)'
    overrides:
      windows:
        command: gcc.exe --version
      linux:
        command: gcc --version

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

• Code builds successfully: dotnet build --configuration Release
• All unit tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.TemplateDotNetTool --configuration Release --framework net10.0
--no-build -- --validate
• Code produces zero warnings

Code Quality

• Code formatting is correct: dotnet format --verify-no-changes
• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• Spell checker passes: cspell "**/*.{md,cs}"
• Markdown linter passes: markdownlint "**/*.md"
• YAML linter passes: yamllint '**/*.{yml,yaml}'

Testing

• Added unit tests for new functionality
• Updated existing tests if behavior changed
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable)
• Updated ARCHITECTURE.md (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

Documentation-only change. Build/test checkboxes N/A as no code modified. All linting passes verified.

Original prompt

Update VersionMark documentation for:

• VersionMark works with .versionmark.yaml config file
• Has a capture mode which captures tool versions to json files
• Has a publish mode which publishes captured tool versions to markdown
• Config file lets user specify how to capture tool versions (commands to run, regex for version, os-specific overrides)
• Capture takes job-id
• Publish collapses common versions, but conflicting versions are reported differentiated by job-id

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.