[dsghi]

Summary

With the default of zero minimum replicas, the first request after an idle period waits for a container to start, which can take 30 seconds or more. When the app is published through an existing Front Door profile whose origin response timeout is close to or shorter than that, Front Door returns 504 for that first call while later calls succeed. To a user it looks like random write failures.

The template references the Front Door profile as existing, so it doesn't own or change this profile-wide setting. This PR documents it instead:

• README, "Optional: custom domain and Azure Front Door": explains the symptom and gives the az afd profile show / az afd profile update --origin-response-timeout-seconds 60 commands. Notes that the setting is profile-wide (range 16–240 s) and mentions the containerAppMinReplicas alternative. Also says that a non-idempotent AppendDocument should be checked with GetDocumentMetadata or CompareDocument before retrying, since a write that returned 504 might still have been applied.
• README, Operating notes → Cold starts: links to that section.
• CHANGELOG [Unreleased] → Added: one entry.

Docs only. No code or template changes.

Independent review

An independent review agent checked the final diff. All seven findings are fixed in this PR:

1. The "30 seconds or less, that first call fails" wording overstated it → now "close to or shorter than [a cold start] … can fail".
2. The same overstatement in the CHANGELOG → reworded.
3. The retry advice was too broad (Upsert, Apply and Delete are already safe to retry) → narrowed to AppendDocument, which isn't idempotent.
4. The note didn't say where containerAppMinReplicas is set → added "in infra/main.bicep".
5. The cross-reference used a quoted section name → now a link, matching the README's other cross-references.
6. Readers couldn't check the current value → added the az afd profile show command and the 16–240 s range.
7. Mixed "replica" / "container" wording → standardized on "container".

The reviewer verified the az command and flag against az 2.88.0 and Microsoft Learn. It also confirmed that the timeout is a profile property on Standard/Premium and that the diff has no deployment-specific names. Microsoft Learn disagrees with itself about the default timeout (30 vs 60 s), so the README doesn't state one.

Testing

• Line endings are unchanged (CRLF in the working tree, LF in the index).
• On a live deployment that showed the 504s: after the timeout went from 30 to 60 s, a write sent while the app was scaled to zero returned 200 on a cold start of about 28 s.

🤖 Generated with Claude Code