feat(repo): add root command support for v1.3.0

[ikelaiah]

Pull Request: Release v1.3.0 - Optional Root Commands

Target Release: v1.3.0

Release Date: July 28, 2026

Summary

This PR adds opt-in root-command execution so cli-fp applications can run
directly as app [options] without requiring a named command. It preserves
the existing ICLIApplication contract and two-argument factory behavior.

Closes #14.

Type of Change

• New backward-compatible feature
• Documentation correction
• Test and CI coverage
• Breaking change

Framework

• Add the backward-compatible three-argument CreateCLIApplication
  overload.
• Execute the root command for an empty argument list or leading
  root-level option.
• Preserve named command and nested-subcommand resolution.
• Keep sole help/version requests and first-argument completion-script
  options authoritative.
• Share parsing, validation, defaults, and exception handling between root
  and named commands.
• Reset application parsing state between executions.

Help and Completion

• Show root description and parameters in general help.
• Show root parameters in complete help.
• Complete root flags in Bash and PowerShell.
• Complete root boolean and enum values.
• Preserve commands-first empty-token completion behavior.

Generator

• Add optional schema-v1 rootCommand parsing and serialization.
• Generate a protected user-owned root command stub.
• Generate root parameter registration and application wiring.
• Preserve output for specifications without a root command.
• Extend unit, golden, runtime, and compile-smoke coverage.

Compatibility

Existing code remains valid:

App := CreateCLIApplication('MyApp', '1.0.0');

Root behavior is enabled only through the new overload:

App := CreateCLIApplication('MyApp', '1.0.0', RootCommand);

No migration is required for existing applications or schema-v1
clifp.json files.

Examples and Release Metadata

• Add RootCommandDemo.
• Add v1.3.0 release notes and changelog entries.
• Update the Lazarus package and README version to 1.3.0.

Documentation

• Rework README onboarding for root, named, and combined CLI applications.
• Correct public API signatures and compile-check key Pascal examples.
• Fix code-generator instructions and case-sensitive Linux build commands.
• Align Bash and PowerShell completion guides with current behavior.
• Clarify date-time parsing, Boolean defaults, password handling, and
  custom-completion limitations.
• Repair documentation links and label dated test reports as historical
  snapshots.

Verification

• Framework test suite: 38 tests, 0 failures.
• RootCommandDemo Release build and runtime smoke tests.
• Full Windows code-generator suite.
• Generated root-command application compile and runtime smoke test.
• GitHub Actions on Linux and Windows.
• No conflicts with the base branch.

Release Readiness

• Changelog finalized for July 28, 2026.
• Release notes finalized for July 28, 2026.
• Version metadata targets 1.3.0.
• Documentation links and examples verified.

After merge, create the v1.3.0 tag and publish the prepared release notes.