docs: consolidate DNS domain setup explanation into networking.md

DNS setup was split across three docs, each describing only one of the
two required steps. Give it one canonical walkthrough in networking.md's
new "Set up DNS-based container names" section, and trim the other docs
to link there instead of re-deriving it. Also fixes a stale
`container network list` example.

Signed-off-by: Eric Ernst <eric_ernst@apple.com>

Author: egernst

docs/container-system-config.md

@@ -50,6 +50,10 @@ Defaults applied when `container run` / `container create` is invoked without `-
 |----------|-----------|---------|----------------------------------------------------------------------------|
 | `domain` | `String?` | unset   | Local DNS domain appended to container hostnames (e.g. `"test"` makes `my-web-server` resolvable as `my-web-server.test`). When unset, no domain is appended. |
 
+Setting `domain` here tells the `container` service what domain to register container
+hostnames under. See [Networking: Set up DNS-based container
+names](./networking.md#set-up-dns-based-container-names) for the full walkthrough.
+
 ## `[kernel]`
 
 Guest kernel used when launching container VMs. Defaults change per release as kernels are bumped — check the [source](../Sources/ContainerPersistence/ContainerSystemConfig.swift) for current values.

docs/networking.md

@@ -3,26 +3,83 @@
 Learn how `container` networks containers with one another, with the host, and with
 external systems.
 
-## Overview
-
 Running `container system start` creates a vmnet network named `default`, to which your
-containers attach unless you specify otherwise. Every container on a network receives a
-DNS name reachable from the host and from other containers on the same network. The
-domain suffix comes from the `[dns] domain` setting in `~/.config/container/config.toml`
-(see [`config.toml` reference](./container-system-config.md#dns)) — for example, with
-`domain = "test"` set, a container named `my-web-server` is reachable at
-`my-web-server.test`.
+containers attach unless you specify otherwise. Every container gets an IP address on
+its network, always reachable by that IP from the host and from other containers on the
+same network (find it with `container inspect <name>`).
+
+## Set up DNS-based container names
+
+Reaching a container by name instead of IP goes through `container`'s embedded DNS
+service. Set this up in two steps:
+
+### Step 1: Tell the `container` service what domain to use
+
+Edit `~/.config/container/config.toml`:
+
+```toml
+[dns]
+domain = "test"
+```
+
+Restart the service so it picks up the change:
+
+```bash
+container system stop
+container system start
+```
+
+From this point on, every container you run gets registered under `<name>.test` inside
+`container`'s DNS service, and every container's own DNS resolver is configured to look
+up `.test` names there too.
+
+### Step 2: Tell macOS to use that domain too
+
+Step 1 only affects the `container` service and the containers it runs — your Mac's own
+DNS resolver still knows nothing about `test`. Point it at `container`'s DNS service:
+
+```bash
+sudo container system dns create test
+```
+
+Enter your administrator password when prompted. This writes a resolver file to
+`/etc/resolver/` that tells macOS: for any `*.test` query, ask `127.0.0.1` instead of
+your normal DNS server.
+
+Both steps are needed. See [`[dns]` reference](./container-system-config.md#dns) for the
+config-key-level detail.
+
+With both steps done, confirm it end-to-end from your Mac:
+
+```console
+% container run -d --rm --name my-web-server python:alpine python3 -m http.server 8000
+% curl http://my-web-server.test:8000
+```
 
 ## Container-to-container networking
 
-From one container, use another container's DNS name to reach a service it exposes:
+From one container, use another container's DNS name to reach a service it exposes.
+This requires the DNS setup above ([Set up DNS-based container
+names](#set-up-dns-based-container-names)):
 
 ```bash
 container run --rm -d --name http-server python:alpine python3 -m http.server
 container run -it --rm alpine/curl curl -v http://http-server.test:8000
 container stop http-server
 ```
 
+> [!WARNING]
+> This works for containers on the `default` network using a domain-qualified name
+> (`http-server.test`, as above). It does **not** currently work for looking up another
+> container by its *bare* hostname (no domain suffix) on a custom network created with
+> `container network create` — the kind of zero-configuration, Compose-style service
+> discovery some users expect. That gap is tracked upstream as
+> [apple/container#1809](https://github.com/apple/container/issues/1809) (open feature
+> request, not yet implemented) and related broader reports in
+> [apple/container#856](https://github.com/apple/container/issues/856). Until resolved,
+> reach a container on a custom network by its IP address instead (`container inspect
+> <name>` to find it).
+
 ## Forward traffic from `localhost` to your container
 
 Use the `--publish` option to forward TCP or UDP traffic from your loopback IP to the container you run. The option value has the form `[host-ip:]host-port:container-port[/protocol]`, where protocol may be `tcp` or `udp`, case insensitive.
@@ -153,9 +210,9 @@ Run `container network list` to see the networks that exist:
 
 ```console
 % container network list
-NETWORK  STATE    SUBNET
-default  running  192.168.64.0/24
-foo      running  192.168.65.0/24
+NETWORK  SUBNET
+default  192.168.64.0/24
+foo      192.168.65.0/24
 %
 ```
 

docs/tutorials/container-system-config-tutorial.md

@@ -33,7 +33,7 @@ touch ~/.config/container/config.toml
 
 Open the file in the editor of your choice and add only the sections and keys you want to change. 
 
-For this tutorial, increase the default CPU and memory limits used for each new container and set a DNS domain for resolving container IP addresses from the host. 
+For this tutorial, increase the default CPU and memory limits used for each new container, and set a DNS domain so containers get hostnames under that domain (a container named `my-web-server` becomes `my-web-server.test`).
 
 ```toml
 [container]
@@ -55,6 +55,19 @@ container system stop
 container system start
 ```
 
+### Route macOS DNS queries for the domain to `container`
+
+The `[dns] domain` change above only affects the `container` service and the containers
+it runs. Complete the setup by telling macOS to route `*.test` queries there too:
+
+```bash
+sudo container system dns create test
+```
+
+Enter your administrator password when prompted. See [Networking: Set up DNS-based
+container names](../networking.md#set-up-dns-based-container-names) for what this step
+does.
+
 ### Verify the values are loaded
 
 Use `container system property list` (alias `ls`) to print the merged configuration that the `container` service is using. 

docs/tutorials/start-here.md

@@ -105,7 +105,16 @@ Use the `--help` flag to see which abbreviations exist.
 
 ### Set up a local DNS domain (optional)
 
-`container` includes an embedded DNS service that simplifies access to your containerized applications. If you want to configure a local DNS domain named `test` for this tutorial, run:
+`container` includes an embedded DNS service that simplifies access to your containerized applications. For what each step does, see [Networking: Set up DNS-based container names](../networking.md#set-up-dns-based-container-names); the short version, to set up a domain named `test`:
+
+Set `domain = "test"` under `[dns]` in `~/.config/container/config.toml`, then restart the service:
+
+```bash
+container system stop
+container system start
+```
+
+Then tell macOS to route `*.test` queries to `container`'s DNS service:
 
 ```bash
 sudo container system dns create test