Implement app deployment improvements

docs/operator-setup.md

@@ -0,0 +1,62 @@
+# Operator Setup
+
+Run these checks before deploying or rotating any S5 workload:
+
+```bash
+make check-tools
+make check-sops
+```
+
+## Required Tools
+
+- `kubectl`
+- `helm`
+- `sops`
+- `python3`
+
+Install the CNPG plugin for better database diagnostics:
+
+```bash
+kubectl krew install cnpg
+```
+
+`make check-tools` fails when required tools are missing and warns when
+`kubectl cnpg` is unavailable. The Makefile status targets fall back to
+plain Kubernetes resources, but the plugin output is the preferred view
+for primary/replica health and backup state.
+
+## SOPS Age Key Bootstrap
+
+SOPS-encrypted values in this repo expect an age identity at:
+
+```text
+~/.config/sops/age/keys.txt
+```
+
+Bootstrap procedure:
+
+1. Receive the operator age identity through an out-of-band channel.
+2. Create the directory with owner-only permissions:
+   ```bash
+   mkdir -p ~/.config/sops/age
+   chmod 700 ~/.config/sops ~/.config/sops/age
+   ```
+3. Write the identity to `~/.config/sops/age/keys.txt`.
+4. Restrict the file:
+   ```bash
+   chmod 600 ~/.config/sops/age/keys.txt
+   ```
+5. Verify decryption:
+   ```bash
+   make check-sops
+   ```
+
+Do not commit age identities, decrypted values, or copied SOPS plaintext
+to this repo.
+
+## Rotation
+
+To rotate access, add the new recipient to the relevant SOPS files,
+re-encrypt, verify with both old and new operators, then remove the old
+recipient in a separate change. Keep at least one known-good recovery
+operator key available during the transition.