The macOS wrapper starts the container service itself when it is down (from dev 685ce778cf34)

doc/install/klammertext.zsh

@@ -7,8 +7,10 @@
 #
 # Then open a new terminal and use `ktext`, `kdesc`, `kdiag` like normal
 # commands.  Requires Apple Silicon + macOS 26 or later, with Apple's
-# `container` runtime installed and its service started (`container system
-# start`).  Install `container` from the signed .pkg at
+# `container` runtime installed and its service started once by hand
+# (`container system start`, which sets up its kernel the first time); after
+# that the wrapper starts the service itself whenever it is down, as it is
+# after every restart.  Install `container` from the signed .pkg at
 # https://github.com/apple/container/releases (NOT Homebrew).  See
 # doc/install/macos_container_install.md for the full guide.
 # -----------------------------------------------------------------------------
@@ -17,8 +19,18 @@
 # native arm64 build, so no --platform / --rosetta is needed.
 KLAMMERTEXT_IMAGE="${KLAMMERTEXT_IMAGE:-akopra/klammertext:latest}"
 
+# The container service does not survive a restart, and without it every
+# command fails with a connection error.  So start it when it is down
+# (`container system status` exits 1 then) before anything needs it.
+_klammertext_service() {
+  container system status >/dev/null 2>&1 \
+    || container system start >/dev/null 2>&1 \
+    || { echo "klammertext: the container service did not start; run \`container system start\` to see why" >&2; return 1; }
+}
+
 _klammertext_run() {
   local cmd="$1"; shift
+  _klammertext_service || return 1
   container run --rm \
     -v "$PWD:/work" -w /work \
     "$KLAMMERTEXT_IMAGE" "$cmd" "$@"
@@ -33,6 +45,7 @@ kdiag() { _klammertext_run kdiag "$@"; }
 # Download or update to the latest published image (delete first so the moving
 # `latest` tag is definitely refreshed).
 klammertext-update() {
+  _klammertext_service || return 1
   container image delete "$KLAMMERTEXT_IMAGE" 2>/dev/null
   container image pull "$KLAMMERTEXT_IMAGE"
 }

doc/install/macos_container_install.md

@@ -26,8 +26,10 @@ Apple Silicon. It's free.
    container system start
    ```
 
-You only do this once. You can check the service any time with
-`container system status`.
+You only do this once: the first start sets up the service's kernel. After
+a restart the service is down again, and the wrapper you install in Step 3
+starts it for you the next time you run a Klammertext command. You can check
+the service any time with `container system status`.
 
 ## Step 2 — Download Klammertext
 
@@ -142,8 +144,8 @@ That's it — you're running Klammertext.
   still runs your source build and `ktextc` runs the container.
 - **Quitting.** Klammertext only runs while you're using it; there's nothing
   left running afterward. If you want to stop the `container` service entirely,
-  run `container system stop`; start it again with `container system start` next
-  time.
+  run `container system stop`; the wrapper starts it again the next time you
+  run a Klammertext command.
 
 ## Editor support (Emacs, Sublime Text)
 
@@ -167,9 +169,10 @@ Each package's README explains its installation.
   open a fresh Terminal.
 - **`container: command not found`** — the `container` runtime isn't installed
   (Step 1), or the Terminal window predates the install (open a new one).
-- **A command hangs or won't connect** — the `container` service isn't running.
-  Run `container system start` (check with `container system status`), then try
-  again.
+- **`the container service did not start`** — the wrapper starts the
+  `container` service when it is down, and this time it could not. Run
+  `container system start` yourself to see the service's own message (check
+  with `container system status`), then try again.
 - **A run aborted and now seems stuck** — `container run --rm` can leave the
   container behind after an error. Clear leftovers with: