Feature: CLI docstring example validation
  As a documentation maintainer
  I want to ensure CLI docstring examples respect positional argument order
  So that published documentation accurately reflects the command signature

  Scenario: Validator detects positional arguments before options
    Given I have a CLI command with positional arguments and options
    When I validate the command's docstring examples
    Then the validation should pass for examples with positional args before options

  Scenario: Validator rejects options before positional arguments
    Given I have a CLI command with positional arguments and options
    When I validate the command's docstring examples
    Then the validation should fail for examples with options before positional args

  Scenario: Validator handles commands without examples
    Given I have a CLI command without docstring examples
    When I validate the command's docstring examples
    Then the validation should pass for commands without examples

  Scenario: Validator parses example lines with shlex
    Given I have a CLI command with quoted arguments in examples
    When I validate the command's docstring examples
    Then the validation should correctly parse quoted arguments

  Scenario: Validator reports clear error messages
    Given I have a CLI command with invalid docstring examples
    When I validate the command's docstring examples
    Then the error message should identify the command and example line
    And the error message should explain the positional argument order requirement