Represent operation canonicality and intent in Forge metadata #7

Problem

Generated command catalogues can contain legacy, versioned, user-scoped, and account-scoped operations that describe the same intent. They currently lack enough metadata for consumers to identify the preferred operation or explain the difference between siblings.

HTTP-derived categories can also misrepresent actions: a POST that analyzes or validates data may be described as a create operation. Search quality then depends too heavily on incidental wording.

Expected metadata

Forge should be able to represent:

• a canonical or preferred operation and its alternatives;
• replacement, legacy, version, and support relationships;
• semantic action or intent separately from the HTTP method;
• scope distinctions such as user, account, and zone;
• compact searchable capabilities when important concepts exist only in response schemas;
• human-readable disambiguation between intentional siblings.

Acceptance criteria

• OpenAPI extensions or overlays can express canonicality and semantic intent.
• Resolved operation metadata exposes these fields to all generators.
• Consumers can prefer supported operations without product-specific runtime rules.
• Generic fixtures cover versioned duplicates, scope variants, non-CRUD POST actions, and response-derived capabilities.
• The metadata contract and fallback behavior are documented.