Complete OpenAPI 3.0 follow-up for servers/events mocks and skill doc accuracy

[Copilot]

This PR closes the remaining OpenAPI 3.0 gaps called out for events, mock server workflows, and servers ergonomics, while correcting mismatches in skill/docs text. It adds first-class server-variable handling in generated CLIs and strengthens event emission coverage to real endpoints.

• OpenAPI model: server variables

  • Extended spec.Server to include variables (default, enum, description) via a new ServerVariable type.
  • Added parsing coverage for servers.variables from OpenAPI YAML/JSON.

• Generated CLI: server-template interpolation

  • Generated cmd/root.go now supports per-variable overrides for templated server URLs:
    • flag: --server-var-<name>
    • env: <CLI>_SERVER_VAR_<NAME>
  • Resolution order per variable: flag → env → OpenAPI default.
  • Added shared env-name normalization helper (internal/spec/env.go) to keep generator and skill prompt behavior consistent.

• Events/mock: endpoint emission coverage

  • Added end-to-end test coverage for GenerateEventPayload + EmitEvent sending a synthesized event payload to an HTTP endpoint and validating delivered fields.

• Skill + docs accuracy

  • Updated dynamic skill prompt generation to document server-variable overrides.
  • Corrected static skill docs (skills/climate.md, skills/climate-generator/SKILL.md) where output behavior was overstated as always-JSON.
  • Updated OpenAPI support matrix and compose design docs to reflect current servers behavior and event-mock wording.

Example (new generated CLI behavior):

# OpenAPI server: https://{region}.api.example.com/{basePath}
myapi --server-var-region us --server-var-base-path v2 pets list
# or via env:
# MYAPI_SERVER_VAR_REGION=us
# MYAPI_SERVER_VAR_BASE_PATH=v2

[Copilot]

Pull request overview

Closes remaining OpenAPI 3.0 gaps around servers (server variables), improves generated CLI ergonomics for templated server URLs, and tightens docs/skill text accuracy—plus adds a more end-to-end event emission test to real HTTP endpoints.

Changes:

• Extend the OpenAPI model + parser coverage for servers[].variables and add env-name normalization for server-variable overrides.
• Update generator + skill prompt output to support --server-var-<name> and <CLI>_SERVER_VAR_<NAME> overrides with interpolation into templated server URLs.
• Improve event/mock testing by exercising payload generation + emission to an HTTP endpoint; correct docs/skill output-format statements.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
skills/climate.md	Corrects output-format documentation to reflect text/Markdown commands.
skills/climate-generator/SKILL.md	Aligns skill doc “Notes” with actual output behavior (JSON vs plain text).
internal/spec/types.go	Adds Server.Variables and ServerVariable to represent OpenAPI server template variables.
internal/spec/spec_test.go	Adds tests for parsing server variables and env-var name normalization.
internal/spec/env.go	Introduces shared ServerVariableEnvName helper for consistent env naming.
internal/skill/skill.go	Documents server-variable override flags/env vars in generated skill prompts.
internal/skill/skill_test.go	Adds coverage ensuring prompts include server-variable override docs.
internal/mock/mock_test.go	Adds end-to-end-ish test: generate payload + emit to an HTTP endpoint.
internal/generator/generator.go	Generates --server-var-* flags, env overrides, and URL interpolation in cmd/root.go.
internal/generator/generator_test.go	Verifies generated root.go contains flags/env vars and interpolation logic.
docs/openapi-3-support-matrix.md	Updates support matrix to mark servers+variables implemented and clarify callbacks wording.
docs/design-compose.md	Updates compose design doc to reflect primary server URL + variable override behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.