Document domain registration

content/(account)/pricing.mdx

@@ -44,7 +44,7 @@ The first two are real usage from the last 30 days.
 
 | Domain | Price | Counts toward your limit |
 | --- | --- | --- |
-| Registered through Spacefast | At cost: registry price plus ICANN fee | No |
+| [Registered through Spacefast](/registration) | At cost: registry price plus ICANN fee | No |
 | Registered through WordPress.com, or on Spacefast DNS | Free to connect | No |
 | Any other domain | Free to connect | Yes |
 

content/(serve)/domains.mdx

@@ -6,6 +6,8 @@ sidebar: { order: 2 }
 
 A domain you own can be pointed at a Space and promoted to its primary, live address.
 
+Don't have one yet? [Register a domain](/registration) through Spacefast and skip the DNS steps below: it runs on Spacefast DNS, so the records are written for you.
+
 A domain belongs to a **team**, not to a Space. You add it once to the team's inventory, then assign it to a Space. One hostname serves exactly one Space; one Space can hold many hostnames.
 
 ## Connect a domain

content/meta.ts

@@ -9,6 +9,7 @@ export default defineMeta({
     "concepts",
     "publish",
     "serve",
+    "registration",
     "dynamic",
     "infrastructure",
     "account",

content/registration/contacts-and-privacy.mdx

@@ -0,0 +1,76 @@
+---
+title: Owner details and privacy
+description: The contact details a registered domain needs, who owns it, and what WHOIS shows about you
+sidebar: { order: 2 }
+---
+
+Every registered domain needs valid owner details. [ICANN](https://www.icann.org/), the organization that sets the rules for domain names, requires them. They identify who owns the domain and are used to settle ownership disputes. Spacefast hides them from the public by default, at no extra cost.
+
+## What you need to provide
+
+The first time you buy a domain, checkout asks for the **Domain owner**:
+
+| Field | Required |
+| --- | --- |
+| First and last name | Yes |
+| Organization | No. Fill it in when a company owns the domain. |
+| Street address, city, state or region, postal code, country | Yes. State or region is required for every country. |
+| Email address | Yes |
+| Phone number | Yes |
+
+Spacefast saves these details and fills them in next time, so you type them once. Use a real person or company: registries can suspend a domain registered to made-up details.
+
+:::tip[Pick an email address that doesn't depend on the domain]
+Avoid an address on the domain itself, like `admin@yourgroovydomain.com` for `yourgroovydomain.com`. If the domain stops working, so does that inbox, and that's where the important mail goes.
+:::
+
+From the terminal, save owner details from a JSON file, then list them:
+
+```bash
+sf domains contacts add --file contact.json
+sf domains contacts ls
+```
+
+The file takes `firstName`, `lastName`, `organization`, `address1`, `address2`, `city`, `state`, `postalCode`, `countryCode` (two letters), `email`, and `phone`. Pass the saved contact to a purchase with `--contact dcon_...`. Without it, the newest contact you saved is used.
+
+## Who owns the domain
+
+Saved owner details belong to the person who saved them, not to the whole team. That matters:
+
+- **Only that person can change the name, organization, or email address** on them. Anyone who can buy domains for the team can fix the street address or phone number.
+- **Changes reach the registry.** Editing saved details updates every domain registered to them. To register a domain to other saved details, its owner sends `contactId` with `updateDomainRegistration`.
+- **A new owner locks the domain for 60 days.** Changing the owner's name, organization, or email is a change of owner under ICANN's rules, so the registrar keeps the domain from moving to another registrar for 60 days.
+- **API keys can't save owner details.** An owner is always a person, so a team API key gets `domain_contact_requires_person`. Sign in as a person, or save the details in the dashboard first.
+
+An agent buying a domain for you should ask you for these details and never invent them. To keep them out of the chat, save them yourself (in the dashboard's domain search or with `sf domains contacts add`) and let the agent reuse the saved contact.
+
+## Verify your email address
+
+ICANN requires registrars to confirm the owner's email address. If you get an email asking you to verify the contact details for your domain, open it and click the link. Registries can suspend a domain whose owner details stay unverified.
+## Privacy protection
+
+Privacy protection is on by default for every domain you register through Spacefast, at no extra cost. Public WHOIS and RDAP lookups don't show your name, address, email, or phone number. Those fields come back redacted.
+
+You can turn privacy off on the domain's **Registration** card (or with `privacySetting` on the API). The owner details then become public in WHOIS. Turn it off only when you want them listed, for example for a business that publishes its address anyway.
+
+Your details still exist, and in a few cases they can be shared:
+
+- **To run the domain.** The registry for the extension, the registrar, and the data escrow provider that ICANN requires all hold a copy.
+- **To settle a dispute.** When someone files a [UDRP](https://www.icann.org/resources/pages/help/dndr/udrp-en) or [URS](https://www.icann.org/resources/pages/urs-2014-01-09-en) complaint about the domain, ICANN requires the registrar to reveal the owner details to the dispute provider, privacy or not.
+- **Through tiered access.** ICANN lets parties with a legitimate purpose, such as law enforcement, request registrant data from the registrar. The registrar reviews each request case by case.
+
+## Who the registrar is
+
+Spacefast registers domains through Automattic Inc., the same registrar behind WordPress.com. Automattic is the ICANN-accredited registrar of record you'll see in WHOIS.
+
+To report spam, phishing, malware, or other abuse on a domain registered through Spacefast, email the registrar's abuse contact at `domainabuse@automattic.com`.
+
+## Errors you might see
+
+| Code | What happened | What to do |
+| --- | --- | --- |
+| [`domain_contact_not_found`](/errors/domain_contact_not_found) | The contact ID doesn't exist, or belongs to another team. | List contacts with `sf domains contacts ls` and use one from there. |
+| `domain_contact_not_owned` | The contact belongs to someone else, so you can't register a domain to it. | Save your own details, or ask that person to buy it. |
+| `domain_contact_identity_locked` | Only the person who saved the contact can change its name, organization, or email address. | Ask them, or save new details. |
+| `domain_contact_requires_person` | A team API key tried to save owner details. | Use a personal sign-in, or let a person fill them in at checkout. |
+| [`registrant_contact_invalid`](/errors/registrant_contact_invalid) | The registrar rejected the owner details. Your payment for the domain was refunded. | Fix the details (a full street address, a valid phone with country code) and buy again. |

content/registration/dns-and-nameservers.mdx

@@ -0,0 +1,120 @@
+---
+title: DNS and nameservers
+description: Manage DNS records for a domain registered through Spacefast, set up email, and move DNS to another provider
+sidebar: { order: 4 }
+---
+
+A domain you register through Spacefast uses Spacefast DNS from day one. Its nameservers are `ns1.spacefast.com` and `ns2.spacefast.com`, and you manage its records in the dashboard or the CLI. Agents connected over MCP can manage them too.
+
+## What's in a new zone
+
+A freshly registered domain starts with an empty zone: only the SOA and NS records every zone needs. It doesn't point anywhere yet.
+
+When you [add the domain to a Space](/domains), Spacefast writes the records that make it serve, including the `www` twin. You don't add those by hand. In the DNS list they're marked as managed for you. Remove the domain from the Space and those records go with it.
+
+Everything else (email, verification records for other services, subdomains that point somewhere else) you add yourself.
+
+## Add, edit, or delete records
+
+<Tabs>
+<Tab title="Dashboard">
+
+1. Open your team's **Domains** and click the domain.
+2. In the **DNS** section, click **Add record**, or click an existing record to edit or delete it.
+3. Your changes are drafts until you click **Review changes**, check the diff, and click **Apply changes**. All changes in a batch apply together, or none do.
+
+To set up a mail provider in one go, click **Add a service** and pick it. Google Workspace, Microsoft 365, Fastmail, Proton Mail, Zoho Mail, iCloud Mail, and Resend are built in.
+
+</Tab>
+<Tab title="CLI">
+
+```bash
+sf domains dns ls yourgroovydomain.com
+sf domains dns add yourgroovydomain.com --type MX --name @ --value mail.example.com --priority 10
+sf domains dns add yourgroovydomain.com --type TXT --name @ --value "v=spf1 include:_spf.example.com ~all"
+```
+
+Use `sf domains dns update` and `sf domains dns rm` to change or remove a record, and `sf domains dns batch` to apply several changes at once.
+
+</Tab>
+</Tabs>
+
+### Supported record types
+
+| Type | What it's for |
+| --- | --- |
+| `A` | Points a name to an IPv4 address. |
+| `AAAA` | Points a name to an IPv6 address. |
+| `ALIAS` | Points the apex to another hostname, like a CNAME that's allowed at the root. |
+| `CNAME` | Makes one hostname an alias of another. |
+| `MX` | Routes email for this name to a mail server. Takes a priority. |
+| `TXT` | Holds verification, SPF, DKIM, DMARC, or other text values. |
+| `SRV` | Publishes a service with priority, weight, and port. |
+| `CAA` | Limits which certificate authorities can issue certificates. |
+| `NS` | Delegates a subdomain to other nameservers. |
+
+TTL goes from 60 seconds to one day, and defaults to one hour. Use a short TTL while you're setting things up and a longer one once it's stable.
+
+### Import and export
+
+Moving from another DNS provider? Export a BIND zone file there, then click **Import zone** and paste it in. Records become drafts you review before applying. Turn on **Remove records not in the file** to replace the zone instead of adding to it. Lines with unsupported record types are skipped and listed.
+
+**Export zone** downloads the zone as a `.zone` file or copies it. **Copy for AI agent** copies it in a form you can paste straight into a chat.
+
+From the terminal:
+
+```bash
+sf domains dns export yourgroovydomain.com
+```
+
+## Set up email
+
+A domain registered through Spacefast doesn't come with a mailbox. Use any email provider and add the records it gives you:
+
+- **MX records** route incoming mail to the provider.
+- **SPF** (a `TXT` record at `@` starting `v=spf1`) lists the servers allowed to send as your domain.
+- **DKIM** (a `TXT` or `CNAME` record your provider names) signs outgoing mail.
+- **DMARC** (a `TXT` record at `_dmarc`) tells receivers what to do with mail that fails the checks. Gmail and Yahoo require it for anyone sending more than 5,000 messages a day.
+
+Only one email provider can receive mail for a domain at a time. Remove the old MX records when you switch.
+
+Your website and your email are separate. The records Spacefast writes for your Space never touch MX, SPF, DKIM, or DMARC.
+
+## Use other nameservers
+
+You can delegate the whole domain to another DNS provider (Cloudflare, Route 53, your mail host's DNS) by changing its nameservers.
+
+First copy your records to the new provider, or the site and email stop working when the nameservers change. Export them with `sf domains dns export yourgroovydomain.com`, import the file at the new provider, and check that every record arrived, including MX, SPF, DKIM, and DMARC. Then change the nameservers:
+
+```bash
+sf domains nameservers set yourgroovydomain.com ns1.example-dns.com,ns2.example-dns.com
+```
+
+Give at least two nameservers. The command asks before it moves DNS off Spacefast. Your records in Spacefast DNS are kept, so you can come back.
+
+Once the domain uses other nameservers:
+
+- **Spacefast stops answering for it.** Records you add in Spacefast DNS no longer apply. Manage everything at the new provider.
+- **To serve a Space, add the records Spacefast asks for there.** See [Custom domains](/domains) for the records and verification.
+- **The registration doesn't move.** You still renew the domain through Spacefast.
+
+To bring DNS back to Spacefast, set the nameservers to Spacefast's pair:
+
+```bash
+sf domains nameservers set yourgroovydomain.com ns1.spacefast.com,ns2.spacefast.com
+```
+
+Check the current setup with `sf domains nameservers yourgroovydomain.com`.
+
+:::note[Changes take time to show up]
+Nameserver changes can take up to 48 hours to reach every network, and record changes up to the record's TTL. During that window some visitors see the old setup and some see the new one. Clearing your device's DNS cache or trying another network helps you see the change sooner.
+:::
+
+## Errors you might see
+
+| Code | What happened | What to do |
+| --- | --- | --- |
+| [`dns_zone_awaiting_registration`](/errors/dns_zone_awaiting_registration) | You changed DNS before the registration finished. The change is saved, and Spacefast DNS serves it once the domain is registered. | Wait for the registration to complete. |
+| [`nameservers_required`](/errors/nameservers_required) | A domain registered through Spacefast leaves Spacefast DNS only by naming other nameservers. | Pass the new provider's nameservers to `sf domains nameservers set`. |
+| [`registrar_nameservers_refused`](/errors/registrar_nameservers_refused) | The registry refused the nameserver change. Nothing changed. | Check the nameserver hostnames exist and resolve, then try again. |
+| [`registrar_writes_disabled`](/errors/registrar_writes_disabled) | Registrar changes are briefly paused. Nothing changed. | Try again later. |