Clarify hb Lambda + OpenAPI guidance

[gaelic-ghost]

Summary

Update the server-side Swift/Hummingbird guidance for the current hb CLI Lambda + OpenAPI bootstrap path.

What we discovered

• hb 0.5.0 downloaded template 2.7.0.
• hb init now asks first whether the app is Server or Lambda.
• For Lambda, the template asks for APIGateway, APIGatewayV2, or FunctionURL.
• Selecting Lambda + APIGatewayV2 + OpenAPI generates a SwiftPM package that uses:
  • hummingbird-lambda
  • OpenAPIHummingbird
  • swift-openapi-generator
  • swift-openapi-runtime
• The generated app registers generated OpenAPI handlers on a Hummingbird Router, then adapts that router to API Gateway V2 via APIGatewayV2LambdaFunction.
• This means the current hb Lambda path is not the same as the standalone awslabs/swift-openapi-lambda transport path. OpenAPI is the shared contract layer, but the hb template keeps Hummingbird routing as the registration surface.

Guidance update requested

Clarify the Hummingbird/server-side Swift skills so they describe this compatibility shape:

• Use hb init for fresh Hummingbird services.
• For Lambda + API Gateway V2 projects generated by hb, treat hummingbird-lambda as the deployment adapter and OpenAPIHummingbird as the OpenAPI registration transport.
• Mention swift-openapi-lambda as a separate valid OpenAPI Lambda transport, but not the transport used by the current Hummingbird template.
• For projects that may need both long-running server and Lambda deployments, recommend keeping the generated APIProtocol implementation transport-neutral, with thin executable/adapter targets for Hummingbird server and Lambda mode.
• Update any older guidance that assumes OpenAPI + Lambda means swift-openapi-lambda by default.

Evidence from local bootstrap

The generated TokenBroker package passed swift test after replacing the template hello endpoint with GET /healthz.

Relevant generated dependency shape:

• hummingbird-project/hummingbird from 2.25.0
• hummingbird-project/hummingbird-lambda from 2.1.0
• hummingbird-project/swift-openapi-hummingbird from 2.0.1
• apple/swift-openapi-generator
• apple/swift-openapi-runtime

Acceptance criteria

• Hummingbird bootstrap guidance distinguishes Server and Lambda choices in the current hb CLI.
• OpenAPI/RPC guidance clearly distinguishes OpenAPIHummingbird + hummingbird-lambda from swift-openapi-lambda.
• Auth/deployment guidance for API Gateway V2 mentions that protected APIs should use app/device evidence, authorizers, or another explicit auth boundary rather than relying on an openly available endpoint.