Improve recovery for misplaced execution-scoped flags

[kioku]

Summary

• add targeted diagnostics for misplaced execution-scoped flags during dynamic aperture api parsing
• emit command-specific remediation hints for trailing execution flags and misplaced --api on shortcut execution
• add unit and integration coverage for the observed failure cases from issue Improve recovery for misplaced execution-scoped flags #171

Validation

• cargo test
• cargo fmt --check
• cargo clippy --all-targets --all-features
• cargo test --features integration --test dynamic_help_examples_integration_tests api_trailing_dry_run_emits_targeted_placement_hint
• cargo test --features integration --test dynamic_help_examples_integration_tests run_misplaced_api_filter_emits_targeted_placement_hint

Closes #171

[kioku]

Issue 171 Implementation Plan

Summary

Improve CLI recoverability when execution-scoped flags are placed after dynamic operation tokens. Add targeted remediation hints for common misplaced flags (notably trailing --dry-run on aperture api and misplaced --api on aperture run) so users get actionable correction guidance instead of only a generic parse failure.

Branch

171/improve-misplaced-flag-recovery

Implementation Steps

1. Add misplaced-flag diagnostics in src/cli/commands/api.rs for dynamic parse failures.
   • Detect reserved execution flags that appear after the operation path begins.
   • Return Error::invalid_command(...).with_suggestion(...) with command-specific examples.
   • Include a dedicated --api remediation message that points to aperture run --api <context> <shortcut> ....
2. Add focused unit tests in src/cli/commands/api.rs for misplaced-flag detection and hint generation logic.
3. Add integration coverage for the two observed failure cases in tests/dynamic_help_examples_integration_tests.rs:
   • trailing --dry-run after a fully qualified aperture api operation
   • misplaced --api after a run shortcut token

Testing Approach

• Run targeted unit tests for cli::commands::api.
• Run targeted integration tests for the new scenarios in dynamic_help_examples_integration_tests (feature integration).
• Run cargo fmt on changed files.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 93.93939% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/cli/commands/api.rs	93.93%	6 Missing ⚠️

📢 Thoughts on this report? Let us know!