docs: cover macOS libssh and stale operator key

docs/guides/deploy-guide/seed.md

@@ -66,10 +66,34 @@ present, set `SEED_CONTAINER=false` before running any playbook.
 
 ## Option 2: Manual installation
 
+On Ubuntu all required packages come from the archive:
+
 ```bash
 sudo apt-get install git python3-pip python3-virtualenv sshpass libssh-dev
 ```
 
+On macOS the equivalent packages come from Homebrew:
+
+```bash
+brew install libssh pkg-config
+```
+
+`libssh` is not optional here. The local venv installs `ansible-pylibssh`, and
+that package only ships wheels for Linux and for x86_64 macOS. On macOS with
+Apple Silicon there is no matching wheel, so `uv` falls back to the source
+distribution and compiles it, which fails with a missing `libssh` unless the
+library and its headers are present. If the build still does not find them,
+point it at the Homebrew prefix explicitly:
+
+```bash
+export CFLAGS="-I$(brew --prefix libssh)/include"
+export LDFLAGS="-L$(brew --prefix libssh)/lib"
+```
+
+The [seed container](#option-1-seed-container) avoids all of this, because the
+playbooks then run inside the image and nothing is built on the seed node. It is
+the recommended option on macOS.
+
 ## Get a copy of the configuration repository
 
 Each environment managed with OSISM is based on a configuration repository. This was

docs/guides/operations-guide/operator_key_rotation.md

@@ -76,6 +76,17 @@ On the manager node:
   [...]
   ```
 * Commit and push the change to the repository.
+* In every checkout of the configuration repository that is used with
+  `environments/manager/run.sh` — the seed node, a workstation, the manager itself —
+  delete the operator private key that earlier runs left behind:
+  ```bash
+  rm -f environments/manager/id_rsa.operator
+  ```
+  `run.sh` writes this file from `operator_private_key` in `environments/secrets.yml`,
+  but only when it does not exist yet, and the file is listed in `.gitignore`. A copy
+  created before the rotation therefore survives every `git pull` unnoticed and
+  `run.sh` keeps authenticating with the old key. Removing it lets the next `run.sh`
+  write it again from the updated `secrets.yml`.
 
 ## Switching the manager to the new key
 

docs/guides/upgrade-guide/manager.mdx

@@ -98,6 +98,26 @@ are at the same commit by the time step 3 runs.
 
         </TabItem>
         </Tabs>
+    * Whenever the local venv path is used, the venv installs `ansible-pylibssh`, which
+      needs libssh on the machine that builds it. On Ubuntu this is `libssh-dev`. On
+      macOS with Apple Silicon there is no wheel for that package at all, so it is
+      compiled from source and the build fails with a missing `libssh` until
+      `brew install libssh pkg-config` has been run. See
+      [Option 2 of the seed chapter](../deploy-guide/seed.md#option-2-manual-installation)
+      for the details. On macOS the seed container path is the easier route, since
+      nothing is built locally then.
+    * `run.sh` authenticates against the manager with `environments/manager/id_rsa.operator`.
+      It writes that file from `operator_private_key` in `environments/secrets.yml`, but
+      only when it does not exist yet. The file is listed in `.gitignore`, so a copy from
+      an earlier run survives every `git pull` unnoticed. After the operator key has been
+      [rotated](../operations-guide/operator_key_rotation.md), delete the stale file so
+      that it is written again from `secrets.yml`, otherwise steps 2 and 3 keep offering
+      the old key and the SSH login fails:
+
+        ```bash
+        rm -f environments/manager/id_rsa.operator
+        ```
+
     * If Ansible Vault was used to encrypt `environments/manager/secrets.yml`, the vault
       password must be reachable. Its place in the configuration repository is
       `environments/.vault_pass`; `run.sh` finds that file on its own. It either contains