docs(cx-api): explain what enabling userPoolDomainNameMethodWithoutCu…

[dfernaro]

Issue # (if applicable)

Closes #34317.

Reason for this change

@aws-cdk/aws-route53-targets:userPoolDomainNameMethodWithoutCustomResource renders as:

Flag type: Backwards incompatible bugfix

followed by three lines saying that a custom resource is, or is not, created. That heading is generated from the flag's FlagType, not written prose, so the most alarming thing on the page is also the only thing that stands out — and nothing explains what the swap actually does to the template, or what migrating involves.

@blimmer reported flipping it on several projects with no downtime and asked why it reads as a breaking change. The thread discussed it but no documentation change was made.

Description of changes

Rewrites the flag's detailsMd to describe both paths and what actually differs:

	Flag disabled	Flag enabled
Method	UserPoolDomain.cloudFrontDomainName (deprecated)	UserPoolDomain.cloudFrontEndpoint
Mechanism	AwsCustomResource calling DescribeUserPoolDomain	getAtt('CloudFrontDistribution') on AWS::Cognito::UserPoolDomain
Value read	DomainDescription.CloudFrontDistribution	CloudFrontDistribution

Both read the same CloudFrontDistribution value, so the alias record resolves to the same CloudFront domain name either way. Enabling the flag changes how the template obtains it, not what the record points at. That is the point the documentation was missing, and it matches what @blimmer observed.

Two further things, neither of which came up in the issue thread:

• Removing the custom resource also removes the IAM statement granting cognito-idp:DescribeUserPoolDomain. That statement is scoped to * — the code comment notes the action does not support resource-level permissions — so enabling the flag also drops a wildcard permission. Worth knowing, since it argues for enabling it.
• The shared AwsCustomResource provider Lambda and its role are removed only if nothing else in the stack still uses AwsCustomResource. That function is a per-stack singleton keyed on PROVIDER_FUNCTION_UUID, so stating unconditionally that the Lambda disappears would be wrong for most real stacks.

Also adds compatibilityWithOldBehaviorMd, which this flag was missing. It is optional for FlagType.BugFix and ten existing BugFix flags already set it.

The FlagType is deliberately left as BugFix. Enabling really does change the synthesized template, so the classification is correct; what was missing was the detail needed to judge it. Happy to reconsider if maintainers would rather reclassify.

FEATURE_FLAGS.md is regenerated from features.ts. No code or behaviour change.

Describe any new or updated permissions being added

None. The change is documentation only. It does describe an existing permission — the cognito-idp:DescribeUserPoolDomain statement that the custom resource creates — but does not add or alter one.

Description of how you validated changes

No unit or integration tests, as no code changed.

• Every claim was checked against the source: UserPoolDomainTarget.bind for the branch, cloudFrontEndpoint and cloudFrontDomainName for the two mechanisms, and AwsCustomResource for the singleton provider function.
• The flag is referenced in exactly one place in the library, so the described scope is complete.
• FEATURE_FLAGS.md regenerated with ts-node --prefer-ts-exts ./cx-api/build-tools/flag-report.ts; re-running it produces no further diff. recommended-feature-flags.json is untouched, as recommendedValue did not change.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license