Document preview hosts and custom domain name rules on Fabric

[dawsontoth]

Documents two Fabric changes that HarperFast/central-manager#917 makes, with HarperFast/host-manager#244:

• Preview hosts: every cluster serves isolated applications under app. and its own host name, pr-42.app.<cluster name>.<organization subdomain>.harperfabric.com. There is no setting.
• Custom domain name rules: names are case-insensitive and stored in lowercase, must be valid hostnames, cannot be a cluster's host name or a name under it, and belong to one organization once verified.

Depends-on: #715

Merge order

1. Document isolated applications, branched databases, and per-PR CI previews #715, which adds the isolated-applications section this page links to.
2. HarperFast/central-manager#917, which carries the merged HarperFast/central-manager#887, then HarperFast/host-manager#244, deployed.
3. This PR, once those are live, so the page does not describe preview hosts before they work.

For the human reviewer

1. Preview hosts moved under app. Let's Encrypt refuses the wildcard of a cluster's host name beside the instance names one label under it, as review of host-manager#244 found and Let's Encrypt staging confirmed, so previews are pr-42.app.<cluster name>.…; app was your call. The page no longer warns against naming a preview after an instance, since the two no longer overlap.
2. The design changed under this PR. Preview hosts were a per-cluster namespace keyed on the cluster ID and turned on through the Fabric API. At your call they moved to a wildcard under each cluster's own host name, on every cluster, with no setting, so the API instructions, the cluster ID and the open question about API authentication are gone.
3. When previews work on an existing cluster. The page says a cluster created earlier gains them one instance at a time, within about seven weeks, and that until then previews on a multi-instance cluster are intermittent, since a request that lands on an instance without the new certificate fails TLS. That is the cost of adding the wildcard at each certificate's normal renewal rather than re-issuing the fleet at once. From February 2027 Let's Encrypt's shorter certificates shorten the window; the page would then say so.
4. The same-site boundary is documented, not enforced (decision 7 in central-manager#917). The page tells customers to preview only code they would trust in production, recommends __Host- names (with Secure, Path=/ and no Domain) for cookies production relies on, says Harper's own session cookie cannot take that prefix because its name is fixed (hdb-session), and that SameSite does not separate a preview from production.

Changes

• fabric/cluster-creation-management.md rewrites the Preview Hosts section:
  • the host name shape, and that Fabric creates the DNS record and certificate with no setting;
  • that only isolated applications answer, a preview host is exactly one label below app. and the cluster's host name;
  • which clusters and when existing ones start serving them;
  • what sharing a site with production means: cookies, __Host- names, Harper's session cookie, and SameSite.
• fabric/custom-domains.md adds the name rules under Adding a Custom Domain, linking to preview hosts.

Verification

• Docs-only. npx prettier --check is clean on both files.
• Each statement was checked against the companion code:
  • the host name shape and the one-label rule match central-manager's *.app.<cluster> record and host-manager's wildcard application routing, which covers one label;
  • "only isolated applications" and "no response" match host-manager never routing the wildcard to the shared workers;
  • the instance host names, central-manager's <location>-<n>.<cluster host name>, sit outside app., so no preview host can be one;
  • the renewal timing matches host-manager's 40-day renewal threshold on 90-day certificates;
  • Harper's session cookie name is fixed: security/auth.ts builds it as [origin-]hdb-session;
  • the custom domain rules match customDomains.js and clusterHostNames.
• Nothing here is observable end to end until #917 and Fix Open Graph images to render well across all social media sites #244 deploy; the deployed canary in #917's rollout covers it.

Related PRs: none found
Complexity: easy

🤖 Generated with Claude Code

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex; adjudicated=domain; declined=cursor-grok,cursor-kimi,cursor-muse; rounds=5; full=1 @ 62dff49}

_{Review-Attention: skim ~2m (decisions: previews-same-site-as-production, always-on-previews, renewal-driven-rollout, fabric-owned-preview-hosts) @ 62dff49}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-718

This preview will update automatically when you push new commits.