docs: restructure how-to.md into focused topic pages

how-to.md had become a catch-all with no way to discover it beyond
README's single link to it. Split its remaining sections into topic pages
(resource usage, host integration, logs, multiplatform images, runtime
configuration, inspection, shell completions), merge tmpfs into
volumes.md as "Mounts and volumes", and move system-properties docs into
container-system-config.md. how-to.md itself becomes a short index.

README also gains a minimal "Run your first container" step before
"Next steps".

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

Author: egernst

README.md

@@ -31,6 +31,16 @@ Start the system service with:
 container system start
 ```
 
+### Run your first container
+
+```bash
+container run --rm alpine echo hello
+```
+
+This pulls the `alpine` image, runs it in a lightweight Linux VM, prints `hello`, and
+removes the container when it exits. See the [tutorial](./docs/tutorials/start-here.md)
+for a fuller walkthrough that builds and publishes an image of your own.
+
 ### Upgrade or downgrade
 
 For both upgrading and downgrading, you can manually download and install the signed installer package by following the steps from [initial install](#initial-install) or use the `update-container.sh` script (installed to `/usr/local/bin`).

docs/container-inspection.md

@@ -0,0 +1,72 @@
+# Inspecting containers and images
+
+Get detailed, machine-readable information about your containers and images.
+
+## Get container or image details
+
+`container image list` and `container list` provide basic information for all of your images and containers. You can also use `list` and `inspect` commands to print detailed machine-readable output for resources.
+
+Use the `inspect` command and send the result to the `jq` command to get pretty-printed JSON for the images or containers that you specify:
+
+<pre>
+% container image inspect web-test | jq
+[
+  {
+    "configuration": {
+      "name": "web-test:latest",
+...
+    },
+    "variants": [
+      {
+        "platform": {
+          "os": "linux",
+          "architecture": "arm64"
+        },
+        "config": {
+          "created": "2025-05-08T22:27:23Z",
+          "architecture": "arm64",
+...
+% container inspect my-web-server | jq
+[
+  {
+    "configuration": {
+      "mounts": [],
+      "id": "my-web-server",
+      "resources": {
+        "cpus": 4,
+        "memoryInBytes": 1073741824,
+      },
+...
+    },
+    "status": {
+      "state": "running",
+      "networks": [
+        {
+          "ipv4Address": "192.168.64.3/24",
+          "ipv4Gateway": "192.168.64.1",
+          "hostname": "my-web-server.test.",
+          "network": "default"
+        }
+      ],
+...
+    }
+  }
+]
+</pre>
+
+Use the `list` command with the `--format` option to display information for all images or containers. In this example, the `--all` option shows stopped as well as running containers, and `jq` selects the IP address for each running container:
+
+<pre>
+% container ls --format json --all | jq '.[] | select ( .status.state == "running" ) | [ .configuration.id, .status.networks[0].ipv4Address ]'
+[
+  "my-web-server",
+  "192.168.64.3/24"
+]
+[
+  "buildkit",
+  "192.168.64.2/24"
+]
+</pre>
+
+See [Networking](./networking.md) for how to publish ports, reach the host from a
+container, set a custom MAC address, and create isolated networks.

docs/container-system-config.md

@@ -9,6 +9,43 @@ For a guided walk-through on setting default values, see [Container system confi
 
 Source of truth: [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](../Sources/ContainerPersistence/ContainerSystemConfig.swift). 
 
+## Viewing your configuration
+
+Use `container system property list` (alias `ls`) to print the merged configuration
+the `container` service is actually using — combining your `config.toml` with
+hardcoded defaults for anything you haven't set:
+
+```console
+% container system property list
+[build]
+cpus = 2
+memory = "2048mb"
+rosetta = true
+image = "ghcr.io/apple/container-builder-shim/builder:0.13.1"
+
+[container]
+cpus = 4
+memory = "1gb"
+
+[dns]
+domain = "test"
+
+[kernel]
+binaryPath = "opt/kata/share/kata-containers/vmlinux-6.18.15-186"
+url = "https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst"
+digest = "sha256:f63d54507d1f18635d94475077e4c2330de4d8e05cedf25f7c38f063b0e66a91"
+
+[network]
+
+[registry]
+domain = "docker.io"
+
+[vminit]
+image = "ghcr.io/apple/containerization/vminit:0.34.0"
+```
+
+Pass `--format json` for machine-readable output.
+
 ## Top-level schema
 
 ```toml
@@ -35,6 +72,16 @@ Resources and image used for the builder VM that runs `container build`.
 | `memory`  | [MemorySize](#memorysize-format)  | `"2048mb"`                                           | RAM allocation for the builder VM. |
 | `image`   | `String`    | `ghcr.io/apple/container-builder-shim/builder:<tag>` | Reference for the builder image. The tag segment is taken from the project's bundled `container-builder-shim` version. |
 
+To prevent the use of Rosetta translation during container builds on a Mac with Apple
+silicon, set `rosetta = false`:
+
+```toml
+[build]
+rosetta = false
+```
+
+This ensures builds only produce native arm64 images, with no x86_64 emulation.
+
 ## `[container]`
 
 Defaults applied when `container run` / `container create` is invoked without `--cpus` or `--memory`.
@@ -48,11 +95,7 @@ Defaults applied when `container run` / `container create` is invoked without `-
 
 | Key      | Type      | Default | Description                                                                |
 |----------|-----------|---------|----------------------------------------------------------------------------|
-| `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.
+| `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. See [Networking: Set up DNS-based container names](./networking.md#set-up-dns-based-container-names) for the full walkthrough. |
 
 ## `[kernel]`
 

docs/host-integration.md

@@ -0,0 +1,88 @@
+# Host integration
+
+Bridge your container and your Mac: forward your SSH agent in, or reach a host
+service from inside a container.
+
+## Mount your host SSH authentication socket in your container
+
+Use the `--ssh` option to mount the macOS SSH authentication socket into your container, so that you can clone private git repositories and perform other tasks requiring passwordless SSH authentication.
+
+When you use `--ssh`, it performs the equivalent of the options `--volume "${SSH_AUTH_SOCK}:/var/host-services/ssh-auth.sock" --env SSH_AUTH_SOCK=/var/host-services/ssh-auth.sock"`. The added benefit of `--ssh` is that when you stop your container, log out, log back in, and restart your container, the system automatically updates the target path for the socket mount to the new value of `SSH_AUTH_SOCK`, so that socket forwarding continues to function.
+
+```console
+% container run -it --rm --ssh alpine:latest sh 
+/ # env
+SHLVL=1
+HOME=/root
+TERM=xterm
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+SSH_AUTH_SOCK=/var/host-services/ssh-auth.sock
+PWD=/
+/ # apk add openssh-client
+(1/6) Installing openssh-keygen (10.0_p1-r7)
+(2/6) Installing ncurses-terminfo-base (6.5_p20250503-r0)
+(3/6) Installing libncursesw (6.5_p20250503-r0)
+(4/6) Installing libedit (20250104.3.1-r1)
+(5/6) Installing openssh-client-common (10.0_p1-r7)
+(6/6) Installing openssh-client-default (10.0_p1-r7)
+Executing busybox-1.37.0-r18.trigger
+OK: 12 MiB in 22 packages
+/ # ssh-add -l
+...auth key output...
+/ # apk add git
+(1/12) Installing brotli-libs (1.1.0-r2)
+(2/12) Installing c-ares (1.34.5-r0)
+(3/12) Installing libunistring (1.3-r0)
+(4/12) Installing libidn2 (2.3.7-r0)
+(5/12) Installing nghttp2-libs (1.65.0-r0)
+(6/12) Installing libpsl (0.21.5-r3)
+(7/12) Installing zstd-libs (1.5.7-r0)
+(8/12) Installing libcurl (8.14.1-r1)
+(9/12) Installing libexpat (2.7.1-r0)
+(10/12) Installing pcre2 (10.43-r1)
+(11/12) Installing git (2.49.1-r0)
+(12/12) Installing git-init-template (2.49.1-r0)
+Executing busybox-1.37.0-r18.trigger
+OK: 24 MiB in 34 packages
+/ # git clone git@github.com:some-org/some-private-repo.git
+Cloning into 'some-private-repo'...
+...
+```
+
+## Access a host service from a container
+
+> [!IMPORTANT]
+> Due to macOS security constraints around packet filter rules, this feature has limited functionality:
+> - Creating a localhost domain disables Private Relay.
+> - The local domain packet filter rule is removed on a restart.
+
+Create a DNS domain with `--localhost <ipv4-address>` to make a domain used by a container to access a host service. Any IPv4 address can be used as `<ipv4-address>`, which will be assigned to the domain name in container.
+
+Choose an IP address that is least likely to conflict with any networks or reserved IP addresses in your environment. Reasonably safe address ranges include:
+
+- The documentation ranges 192.0.2.0/24, 198.51.100.0/24, and 203.0.113.0/24.
+- The 172.16.0.0/12 private range.
+
+To connect a host HTTP server from a container, run:
+
+```bash
+mkdir -p /tmp/test; cd /tmp/test; echo "hello" > index.html
+python3 -m http.server 8000 --bind 127.0.0.1
+```
+
+Create a domain for host connection:
+
+```bash
+sudo container system dns create host.container.internal --localhost 203.0.113.113
+```
+
+Test access to the host HTTP server from a container:
+
+```console
+% container run -it --rm alpine/curl curl http://host.container.internal:8000
+hello
+```
+
+This uses the same underlying DNS mechanism described in [Networking: Set up DNS-based
+container names](./networking.md#set-up-dns-based-container-names), just with
+`--localhost` pointing the domain at a host address instead of a container.