docs(stack): custom-domains runbook (add a client custom domain via Cloudflare-for-SaaS)

[samo-agent]

Summary

• Adds docs/stack/custom-domains.md — the missing end-to-end operator runbook for attaching a client FQDN via CF-for-SaaS Custom Hostnames
• Adds index row in docs/stack/README.md pointing to the new file
• No code changes

What the doc covers

• Prerequisites: CLOUDFLARE_SAMOTEAM token (scope, zone, entitlement), SAMOHOST_SAAS_ZONE_ID optional fallback, cname.samo.team origin, app registration gate, CLI-must-run-on-CP requirement
• Exact commands: search, add, check, list, rm
• Step-by-step domain add flow (CF Custom Hostname creation → app VM vhost → CP vhost → state persist → DNS instructions)
• The three required customer DNS records (CNAME to cname.samo.team, DCV delegation CNAME _acme-challenge.<fqdn> → CF hash, ownership TXT) — called out in a table
• Verify-live via domain check (exit 0 only when both statuses are active)
• Worked example: www.samorev.xyz (PR feat(domain): MVP CLI for client custom domains (add/check/list/rm/search) #114, live)
• Gotchas: apex domains unsupported, grey-cloud CF DNS required, validation staleness (no CLI recovery — known gap), CF-active + error page = missing CP vhost, token degrade mode, static apps need active release
• Full runtime routing chain diagram

Fact-verification notes

All facts below were read from the code, not from the brief:

Claim	Verified in
CLOUDFLARE_SAMOTEAM is the token var name	src/commands/domain.ts:863
SAMOHOST_SAAS_ZONE_ID / SAMOHOST_SAAS_ZONE optional vars	src/commands/domain.ts:864-865
SAMOHOST_CUSTOM_HOSTNAME_TARGET default = cname.samo.team	src/commands/domain.ts:57,292
domain add degrades cleanly when token absent (warn, still writes vhost)	src/commands/domain.ts:60-65,305-307
CP vhost uses tls internal + header_up Host <httpHost>	src/env/script.ts:2989-2999
Static apps require health-proven active release	src/env/script.ts:2801
domain check exit 0 only when both hostname_status AND ssl_status are active	src/commands/domain.ts:475
dcv_delegation_records structure (cname + cname_target)	src/dns/cloudflare.ts:222
ownership_verification structure (type, name, value)	src/dns/cloudflare.ts:224
domain add note about --dcv http stalling on HTTPS-only CP	src/cli.ts:413-414

One brief fact corrected: the brief stated --dcv txt|http as the flag format; the actual CLI help and parser use --dcv txt / --dcv http (space, not pipe — pipe is just help-text notation). No impact on the doc (notation matches CLI help).

Not included

• No domain recheck command exists in the codebase; the known-gap note documents this explicitly.
• No code changes; this is docs-only.

🤖 Generated with Claude Code