docs: document the datumctl dns plugin and Datum's DNS model

alb/dns-setup.mdx

@@ -6,16 +6,20 @@
 This guide prepares a domain for use with a Datum Application Load Balancer by creating a DNS zone, an apex ALIAS record, and a subdomain CNAME — all pointing at the Application Load Balancer endpoint.
 
 <Note>
 This guide assumes your domain is already delegated to Datum nameservers. See [DNS](/domain-dns/dns) for nameserver details and ALIAS record behavior.
 </Note>
 
+<Warning>
+Datum does not provision a zone until you have verified that you own the domain. If the zone below stays unprogrammed, verification is the first thing to check — see [Verify domain ownership](/domain-dns/domain-verification).
+</Warning>
+
 ---
 
 ## Prerequisites
 
 - `datumctl` installed and authenticated
 - A valid **Project**
 - Domain delegated to Datum nameservers
 
 ---
 
@@ -23,7 +27,7 @@
 
 ### Step 1: Set Variables
 
 The `TARGET` value is your Application Load Balancer endpoint hostname. Find it in the Datum portal under your Application Load Balancer's generated hostname, or via:
 
 ```bash
 datumctl get httpproxy <name> --namespace default -o yaml
@@ -263,7 +267,7 @@
 
 | Symptom | Root Cause | Resolution |
 |---------|------------|------------|
-| Zone stuck at `PROGRAMMED=False` | Domain not delegated to Datum nameservers | Update nameservers at your registrar |
+| Zone stuck at `PROGRAMMED=False` | Most often the domain has not been verified, which also shows the zone as `Rejected`. Delegation is unrelated — a zone programmes whether or not the registrar points at Datum. | Verify domain ownership, then wait for the zone to programme. See [Verify domain ownership](/domain-dns/domain-verification). |
 | `nslookup` / `dig` returns NXDOMAIN | Zone not yet propagated | Wait 1–2 minutes and retry |
 | ALIAS resolves to wrong address | `TARGET` missing trailing dot | Re-apply the record with a trailing dot on the target |
 | Record not appearing | `--validate=false` omitted | Re-apply with `--validate=false` |

datumctl/plugins/using-plugins.mdx

@@ -1,10 +1,10 @@
 ---
 title: "Using Plugins"
 sidebarTitle: "Using plugins"
 description: "Install, run, and manage datumctl plugins that extend the CLI with additional commands."
 ---
 
 Plugins extend `datumctl` with additional commands without changing the core CLI. A plugin is an independent binary that datumctl runs on your behalf — once installed, you invoke it exactly like a built-in command.
 
 <Info>
   Plugins are optional. You never need one to use `datumctl`, and the core CLI works the same whether or not you have any installed.
@@ -18,7 +18,7 @@
 datumctl compute --help
 ```
 
 datumctl injects your current organization, project, and a fresh short-lived access token into the plugin automatically, so plugins work with your [active context](/datumctl/contexts-and-scoping) and [credentials](/datumctl/auth/managing-accounts) without a separate login.
 
 Plugins come from **catalogs** (also called indexes). The official **datum** catalog is curated by Datum and always available with no setup — its plugins carry an `official` trust badge. You can also add third-party catalogs, whose plugins carry a `third-party` badge. See [Adding catalogs](/datumctl/plugins/adding-catalogs) to register more.
 
@@ -39,6 +39,8 @@
 
 Results show the plugin name, the catalog it came from, its version, its trust badge, and a short description.
 
+Plugins with a full guide of their own are listed under **Available plugins** in the sidebar — currently the [DNS plugin](/datumctl/plugins/dns).
+
 Prefer to explore interactively? `plugin browse` opens a filterable picker where you can inspect a plugin's details and install it in place:
 
 ```bash
@@ -72,7 +74,7 @@
 ```
 
 <Info>
   If a bare name exists in more than one catalog, datumctl lists the matches instead of guessing. Qualify the name with its catalog (for example `acme/deploy`) to choose.
 </Info>
 
 ### Pinning a version
@@ -88,7 +90,7 @@
 datumctl plugin install your-org/datumctl-dns@v1.2.0
 ```
 
 Without `@version`, datumctl installs the version the catalog recommends.
 
 ### Restoring your plugin set
 
@@ -108,9 +110,9 @@
 
 | Status   | Meaning                                             |
 |----------|-----------------------------------------------------|
 | `ok`     | Installed and compatible with this datumctl.        |
 | `update` | A newer version is available in its catalog.        |
 | `!`      | Built for a different datumctl version.             |
 | `?`      | Version information is unavailable.                 |
 
 ## Running an installed plugin
@@ -121,7 +123,7 @@
 datumctl compute --help
 ```
 
 Tab completion works transparently — datumctl forwards completion requests to the plugin, so completing subcommands and flags just works:
 
 ```bash
 datumctl compute <TAB>
@@ -141,10 +143,10 @@
 
 ## How plugins stay trustworthy
 
 datumctl treats a plugin as untrusted code and protects you in a few ways:
 
 - **HTTPS-only downloads.** Plugin archives and catalog manifests are fetched over HTTPS only. Downloads to private, loopback, or link-local addresses are refused, and redirects are re-checked on every hop.
 - **Checksum verification on every run.** datumctl records a SHA256 fingerprint of each plugin binary at install time and verifies it *every time the plugin runs*. If a managed plugin binary is modified after installation, datumctl refuses to run it.
 - **Trust badges.** Every plugin and catalog shows whether it is `official` (Datum's curated **datum** catalog) or `third-party`, so you always know the source.
 
 <Warning>
@@ -153,7 +155,7 @@
 
 ### Trusting a plugin already on your PATH
 
 If you have a plugin binary on your `PATH` that datumctl did not install (named `datumctl-<name>` or `milo-<name>`), datumctl blocks it from running until you explicitly trust it:
 
 ```bash
 # Allow an unmanaged PATH plugin to run
@@ -163,7 +165,7 @@
 datumctl plugin untrust dns
 ```
 
 Trusting records the binary's path and fingerprint. If the binary changes afterward, datumctl blocks it again until you re-run `plugin trust`.
 
 ## Next steps
 

docs.json

@@ -107,8 +107,13 @@
           {
             "group": "Domains & DNS",
             "pages": [
+              "domain-dns/dns",
               "domain-dns/domains",
-              "domain-dns/dns"
+              "domain-dns/domain-verification",
+              "domain-dns/dns-zones",
+              "domain-dns/dns-records",
+              "domain-dns/alias-records",
+              "domain-dns/migrate-dns"
             ]
           },
           {
@@ -175,7 +180,13 @@
             ]
           },
           {
-            "group": "Plugins",
+            "group": "Available plugins",
+            "pages": [
+              "datumctl/plugins/dns"
+            ]
+          },
+          {
+            "group": "Managing plugins",
             "pages": [
               "datumctl/plugins/using-plugins",
               "datumctl/plugins/adding-catalogs",

domain-dns/alias-records.mdx

@@ -0,0 +1,56 @@
+---
+title: "ALIAS records"
+description: "Point a hostname — including the zone apex — at another hostname while still returning A and AAAA answers. Other providers call this CNAME flattening."
+---
+
+An **ALIAS** record points a name at another hostname the way a CNAME does, but returns **A and AAAA answers** to clients instead of a CNAME. That makes it usable at the **zone apex**, where standard DNS forbids a CNAME.
+
+Different providers use different names for the same idea:
+
+- **Cloudflare** usually calls it **CNAME flattening**.
+- Other providers call it **ALIAS**, **ANAME**, or a **flattened CNAME**.
+
+## When to use an ALIAS record
+
+Use ALIAS when you want "point this name at that hostname" behavior but you can't or shouldn't use a CNAME. Most commonly:
+
+- At the **zone apex** (`example.com`), where standard DNS rules don't allow a CNAME.
+- When you're targeting a hostname whose addresses change — a CDN or a hosted service — but clients need to receive A and AAAA records.
+
+A Datum Application Load Balancer endpoint is a typical target. See [DNS setup for an Application Load Balancer](/alb/dns-setup).
+
+## Name and value
+
+**Name** — the hostname inside the zone you're creating the record for.
+
+- For the zone apex, use `@`, the zone-file notation for the zone root.
+- For a subdomain, use the label: `www` for `www.example.com`.
+
+**Value** — a target hostname, such as `myapp.hosting-provider.com.`
+
+- ALIAS values are hostnames, not IP addresses.
+- The target must ultimately resolve to A or AAAA records, directly or through further DNS indirection.
+- End the target with a dot. Without one it's treated as relative to your zone. See [Write values](/domain-dns/dns-records#write-values).
+
+## How it works
+
+ALIAS isn't a standardized DNS record type that recursive resolvers understand. The authoritative nameserver does the work instead:
+
+1. A client's resolver asks for `A` or `AAAA` for the ALIAS name, for example `example.com`.
+2. Datum resolves the ALIAS target — `myapp.hosting-provider.com` — to its current `A` and `AAAA` records.
+3. Datum returns those answers as if they'd been configured directly on the ALIAS name.
+
+The consequence worth remembering: clients don't see a CNAME in the response. They see A and AAAA records for the name they asked about.
+
+## ALIAS compared with CNAME
+
+| | CNAME | ALIAS |
+|---|---|---|
+| What the client receives | A CNAME, which the resolver then chases | A and AAAA records, synthesized by Datum |
+| Allowed at the apex | No | Yes |
+| Portable to other providers | Yes, it's a standard type | Not directly — every provider spells it differently |
+
+## Limitations
+
+- **Portability.** ALIAS and flattening behavior isn't uniform across providers. If you move DNS elsewhere, you'll need to translate the record into whatever that provider supports — and a BIND zone file can't carry it, because `ALIAS` isn't a standard type. See [Migrate a zone](/domain-dns/migrate-dns).
+- **Answer types.** ALIAS synthesizes A and AAAA answers. It isn't a general replacement for other record types, and it doesn't carry the target's MX, TXT, or other records over to your name.

domain-dns/dns-records.mdx

@@ -0,0 +1,137 @@
+---
+title: "DNS records"
+description: "Supported record types, how to write names and values, TTLs, and what each record status means."
+---
+
+Records are the contents of a zone: the entries that turn a name into an address, a mail route, or a piece of text. You can manage them from the Datum Cloud portal, from `datumctl`, or through the API.
+
+## Record sets
+
+Datum groups records the way DNS does. Every record with the same name and the same type forms one **record set**, and all of its values share a TTL.
+
+```
+www   A   300   203.0.113.10
+www   A   300   203.0.113.11
+```
+
+That's one record set — `www`, type `A` — with two values. Adding a second address adds a value to the existing set rather than creating a competing record, and resolvers return both.
+
+## Supported record types
+
+| Type | What it does | Value |
+|---|---|---|
+| `A` | Points a name at an IPv4 address | `203.0.113.10` |
+| `AAAA` | Points a name at an IPv6 address | `2001:db8::1` |
+| `CNAME` | Makes a name an alias for another hostname | A hostname |
+| `ALIAS` | Apex-safe alias: points at a hostname but answers with addresses. See [ALIAS records](/domain-dns/alias-records) | A hostname |
+| `MX` | Routes mail for the domain | A preference number and a mail exchange hostname |
+| `TXT` | Holds free text — SPF, DKIM, DMARC, and service verification tokens | A text string |
+| `NS` | Delegates a subdomain to other nameservers | A nameserver hostname |
+| `SRV` | Advertises the host and port for a service | Priority, weight, port, and target |
+| `CAA` | States which certificate authorities may issue for the domain | A flag, a tag, and a value |
+| `TLSA` | Binds a certificate or key to a name for DANE | Usage, selector, matching type, and certificate data |
+| `HTTPS` | Advertises connection parameters for HTTPS clients, such as HTTP/3 support | Priority, target, and parameters |
+| `SVCB` | The general form of `HTTPS`, for other protocols | Priority, target, and parameters |
+| `PTR` | Maps an address back to a name | A hostname |
+| `SOA` | The zone's authority record. Datum manages this one | Managed for you |
+
+The apex NS records and the SOA record are written by Datum. See [Records Datum manages for you](/domain-dns/dns-zones#records-datum-manages-for-you).
+
+## Write names
+
+Record names are relative to the zone. In a zone for `example.com`:
+
+| You want | You write |
+|---|---|
+| `www.example.com` | `www` |
+| `example.com` itself | `@` |
+| `api.staging.example.com` | `api.staging` |
+| Anything not otherwise matched | `*` |
+| `_dmarc.example.com` | `_dmarc` |
+
+The most common mistake is writing the full name. `www.example.com` inside a zone for `example.com` creates a record for `www.example.com.example.com`.
+
+Underscore labels like `_dmarc`, `_acme-challenge`, and DKIM selectors are ordinary names — write them as they appear in the instructions you were given, minus the zone.
+
+## Write values
+
+Values that name another host must be **absolute**: end them with a dot.
+
+```
+mail.example.com.      correct
+mail.example.com       ambiguous
+mail                   wrong
+```
+
+A missing trailing dot makes the value relative to the zone, so `mail.example.com` becomes `mail.example.com.example.com` and resolution fails. This applies to CNAME, ALIAS, NS, MX exchanges, SRV targets, and PTR values.
+
+Two rules cover almost every mistake:
+
+- **Names are relative.** `www`, not `www.example.com`.
+- **Targets are absolute.** `mail.example.com.`, with the dot.
+
+## Set TTLs
+
+The TTL is how long resolvers may cache an answer. Every record set has one.
+
+Leave it unset and the record uses `Auto`, which resolves to five minutes — short enough that mistakes are cheap to fix, long enough to be efficient for most sites.
+
+Set it explicitly when you have a reason:
+
+- **Before a planned change**, lower the TTL well in advance so the old answer expires quickly when you make the cut.
+- **After things settle**, raise it for records that rarely change.
+
+Datum doesn't round TTLs to preset options. A TTL of 240 seconds stays 240 seconds.
+
+## Rules DNS itself imposes
+
+A few limits come from DNS, not from Datum, and every provider enforces them:
+
+- **A CNAME can't share a name with other records.** If `www` is a CNAME, it can't also have an A record or a TXT record.
+- **The apex can't be a CNAME.** The apex already has SOA and NS records, so a CNAME there is illegal. Use an [ALIAS record](/domain-dns/alias-records) instead.
+- **Only one SOA per zone**, and Datum owns it.
+
+## Record status
+
+Each record set reports a status.
+
+| Status | What it means |
+|---|---|
+| Programmed | The record is live on Datum's nameservers. |
+| Pending | The write is in flight. This is normal for a few moments after any change. |
+| Conflict | Something else already occupies that name. Most often the name accidentally includes the zone — check for `www.example.com` where `www` was meant. |
+| Not owner | Another record set already owns that name and type. Change the record through whatever owns it, or remove that owner first. |
+| Error | Datum couldn't program the record. The record's detail view carries the message. |
+| Rejected | The value was refused as invalid for its type. |
+
+A record stuck at Pending for more than a moment is worth inspecting; the detail view for the record carries the underlying message.
+
+<Note>
+Programmed means Datum is serving the record. It doesn't mean the world can see it — that also needs the domain [delegated](/domain-dns/dns-zones#delegation) to Datum, and it needs any previously cached answer to expire.
+</Note>
+
+## Managing records from the terminal
+
+The [`datumctl` DNS plugin](/datumctl/plugins/dns#add-and-change-records) covers records in full, including entering multi-part values, bulk-applying a zone file, and filtering by status:
+
+```sh
+datumctl dns record create example.com www A 203.0.113.10
+datumctl dns record list example.com
+```
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="ALIAS records" icon="arrows-turn-right" href="/domain-dns/alias-records">
+    Point the apex at a hostname and still answer with addresses.
+  </Card>
+  <Card title="DNS zones" icon="layer-group" href="/domain-dns/dns-zones">
+    Zone status, delegation, and managed records.
+  </Card>
+  <Card title="Migrate a zone" icon="right-left" href="/domain-dns/migrate-dns">
+    Import records in bulk from another provider.
+  </Card>
+  <Card title="DNS setup for an ALB" icon="server" href="/alb/dns-setup">
+    A worked example with an apex ALIAS and a subdomain CNAME.
+  </Card>
+</CardGroup>