fix(cloudformation): return stack output URLs on a reachable origin

[Neaox]

Completes the host-addressing plan: H4 (CloudFormation stack output URLs) and H6 (documentation sweep). Follows #345, #350.

The bug

CDK composes an API Gateway invoke URL in the template itself:

["https://", {"Ref":"Api"}, ".execute-api.us-east-1.", {"Ref":"AWS::URLSuffix"}, "/", {"Ref":"Stage"}, "/"]

So DescribeStacks handed back https://abc.execute-api.us-east-1.amazonaws.com/prod/ — a URL that resolves to real AWS.

Why not substitute AWS::URLSuffix

The plan originally proposed resolving AWS::URLSuffix to the configured hostname. That cannot work: the scheme is a literal and there is no port, and the pseudo-parameter can express neither. A value containing :4566 would also make it lie about what it is. It still resolves to amazonaws.com, faithful to AWS at the template level.

The correction belongs at output emission, where Overcast has already assembled the finished string and still holds the request context:

m, ok := middleware.ParseHostRoute(u.Host)   // the grammar that ROUTES inbound
if !ok { return value }                       // not ours — untouched
serviceutil.HostRoutedURLFromBase(h.clientBaseURL(ctx), m.Label, m.ID, m.Region, u.Path)

• DRY. No regex, no new knowledge of AWS hostname shapes. It reuses ParseHostRoute (which decides inbound routing) and HostRoutedURLFromBase (the helper every service already mints through), so the grammar is stated once and applied in both directions.
• Scheme and port come free, from the caller's own origin.
• Conservative. Only a registered host-route label is claimed, so ECR registry URIs, S3 URLs, ARNs and plain strings pass through untouched — Overcast does not serve those hostnames and must not claim to. Pinned by a test.
• Context-based rather than request-based so the Query and typed (Smithy) paths share one implementation; the typed path has no *http.Request.

clientBaseURL mirrors serviceutil.ClientBaseURL's precedence — a configured OVERCAST_HOSTNAME wins over the address the caller dialled, but the caller's scheme and port are kept. That lookup lives in the CloudFormation package because middleware imports serviceutil, not the reverse.

Two corrections to the plan, both from evidence

The IAM service-principal hazard does not exist. The plan warned that substituting the suffix would corrupt principals built as Fn::Join ["", ["states.", {"Ref": "AWS::URLSuffix"}]]. Synthesised compat/suites/cdk plus a fixture covering three ServicePrincipal forms, ECR, S3 website and virtual-hosted URLs, CloudFront, Cognito hosted UI and API Gateway — for us-east-1, cn-north-1 and region-agnostic:

Stack	AWS::URLSuffix sites	Service principals
AuditAws	3 — all Outputs	all literal
AuditCn	3 — same	all literal
AuditAgnostic	3 — same	all literal

Zero principal use sites in any partition, including with an explicit region on the principal. CDK v2 resolves them through its region-info database. S3 website, CloudFront and Cognito URLs never touch the suffix — they come from Fn::GetAtt on real attributes.

The nested-stack TemplateURL was never broken. I had called it a latent bug. Both fetchers — resolveTemplateBody and nestedStackHandler.fetchTemplate — parse the URL and dispatch u.Path internally, discarding the host. Overcast never dials it, and the nested-stack tests pass.

H6 — documentation sweep

Every doc stating which hostnames or URL forms Overcast supports, reviewed. Two were actively wrong:

• migration-from-localstack.md said virtual-hosted style "requires DNS resolution of *.localhost which doesn't work without extra configuration" and told readers to force path-style. Both forms work, the bare one needs no s3. prefix (unlike LocalStack), and OVERCAST_HOSTNAME makes it resolve everywhere.
• sdk-cli.md linked to #s3-asset-upload-fails-on-windows-or-macos; the heading is #s3-asset-upload-fails-on-windows, so the link was dead.

apigateway.md and appsync.md gained the endpoint-URL sections they never had — the host-routed forms, what apiEndpoint and the uris/dns maps report and why they differ, and why dns.REALTIME reports the appsync-api host. Both inserted before the generated capability block, which is untouched.

networking.md is also realigned: #350 added appsync-realtime-api and cloudfront to the inventory table but not to the "what works today" table, the precedence rule, or the reserved-label note.

Verification

gofmt, go build -tags slim ./..., go vet -tags slim ./..., full ./internal/... and ./tests/integration/..., make lint-go (golangci-lint v2.8.0), and docs-index --check all clean on main @ 76d2b5ba.

Written test-first: the failing test asserted a dialable URL and untouched non-URL outputs before any implementation existed.