Consolidate command-line argument tables into single unified reference and add --result alias

[Copilot]

Description

The README and User Guide split command-line arguments into separate markdown sections per mode (Global Options, Lint Mode, Capture Mode, Publish Mode), making it harder to see all options at a glance. Both docs now present all arguments in one unified table with inline group labels — matching how the CLI help message organises them.

README.md (## Command-Line Options):

• Removed ### Global Options, ### Lint Mode, ### Capture Mode, ### Publish Mode sub-sections
• Replaced with a usage synopsis + single table covering all options, using bold group-label rows (**General**, **Lint Mode**, **Capture Mode**, **Publish Mode**, **Self-Validation**)

docs/user_guide/guide.md (# Command-Line Reference):

• Removed per-command ### Options / ### Lint Options / ### Publish Options tables
• Added ## Options with the same unified table structure
• Per-mode sub-sections (## Lint Mode, ## Capture Mode, ## Publish Mode) retained for synopsis, behavior, and examples — option tables removed to avoid redundancy

Legacy --result alias (src/DemaConsulting.VersionMark/Cli/Context.cs):

• Added --result as a silent alias for --results in the argument parser for backward compatibility
• Not documented in README or User Guide — new users see only the canonical --results
• Added Context_Create_ResultFlag_SetsResultsFile test to verify the alias is accepted

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.VersionMark --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 .

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

The --result alias is intentionally undocumented — it exists solely for legacy compatibility. The README and User Guide continue to show only --results.

[Malcolmnixon]

@copilot Excellent, now while we're at it, can you add "--result" as an alias for "--results". Don't bother adding "--result" to the README.md or user guide, as it's just legacy argument support. We want new users to see the correct "--results", but silently handle "--result" and possibly add a test to make sure it's supported.

[Copilot]

@copilot Excellent, now while we're at it, can you add "--result" as an alias for "--results". Don't bother adding "--result" to the README.md or user guide, as it's just legacy argument support. We w...

Done in b5d6f4f. Added --result as a silent alias for --results in the argument parser (Context.cs) and added Context_Create_ResultFlag_SetsResultsFile to ContextTests.cs to verify it works. Not mentioned in the README or User Guide.

[Copilot]

Pull request overview

This PR consolidates command-line option documentation into unified tables in the README and User Guide, and adds a legacy --result alias for --results in the CLI argument parser with a corresponding unit test.

Changes:

• Consolidate command-line options into a single grouped table in README.md and docs/user_guide/guide.md.
• Add --result as an alias for --results in Context argument parsing.
• Add a unit test verifying the --result alias sets ResultsFile.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
test/DemaConsulting.VersionMark.Tests/Cli/ContextTests.cs	Adds coverage for the legacy --result alias.
src/DemaConsulting.VersionMark/Cli/Context.cs	Extends argument parsing to accept --result as an alias for --results.
docs/user_guide/guide.md	Replaces per-command option tables with a single grouped options table.
README.md	Replaces multiple options sections with a unified grouped options table and usage synopsis.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.