docs(cli): add parser migration guardrails

AGENTS.md

@@ -96,3 +96,5 @@ Guide for future agents working on this codebase. Focus on traps, cross-cutting
 - Respect exit semantics: uncaught exceptions routed to `exit.withError`; GraphQL errors call `process.exit(1)` unless explicitly disabled; 401 auth errors exit with guidance.
 - Watch shared state: current implementation mutates a global; ensure new parser avoids cross-command bleeding when multiple command instances run in-process (tests/CLI wrappers).
 - Login guardrails in `vip.js` let certain commands bypass auth; preserve equivalent shortcuts or add explicit non-interactive flags for CI.
+- Normalize short-option equals syntax: rewrite `-x=value` to `-x value` before parsing for short options that expect values; track which short options take values to avoid breaking boolean flags that should remain flag-only.
+- Apply tracked defaults after parsing: when an option has both a default and a custom parser function, apply the default only when `opts[optionName] === undefined` after the parser runs, so that explicit values and defaults maintain parity with the parser contract (see test `parses short options using equals syntax without prefixing values` in `__tests__/lib/cli/command.js`).

docs/COMMANDER-MIGRATION.md

@@ -16,6 +16,7 @@ Goal: remove the abandoned `args` package, keep CLI behavior stable, and support
 - `_opts` controls are still honored: app/env context fetch, confirmation gating, output formatting, wildcard command handling, required positional args.
 - Shared formatting/output and telemetry hooks are still in the wrapper path.
 - Local nested subcommand dispatch still works via sibling executable resolution.
+- Short-option equals normalization: `-x=value` is rewritten to `-x value` for short options expecting values before parsing; boolean short flags are not affected. Tracked option defaults are applied after parsing when the option remains undefined post-parse, preserving default+parser parity.
 
 ## Post-Migration Hardening