added docs

docs/OPERATIONS.md

@@ -0,0 +1,104 @@
+# AIM Operations Guide
+
+## Navigation
+
+AIM is organized around a customer context:
+
+``` text
+Customer
+├── Hosts Management
+├── Access Management
+├── Vault Management
+├── Group Variables
+├── Host Variables
+├── Playbooks
+└── Administration
+```
+
+For numbered navigation menus, Enter or `0` means Back/Cancel; at the
+main menu it means Exit. Single selectors use Enter/`0` to cancel.
+Multi-select uses numbers to toggle, Enter to review, and `0` to cancel.
+Paginated views use `p / n` for Previous / Next.
+
+## Customer overview
+
+Opening a customer should provide local information without unexpectedly
+contacting hosts, running Ansible or decrypting Vaults. The dashboard
+includes inventory YAML state, Vault presence, host/platform counts and
+available customer defaults.
+
+## Hosts
+
+`hosts.yml` is the source of truth.
+
+Creating a host also ensures:
+
+``` text
+host_vars/<fqdn>/main.yml
+```
+
+For ordinary non-Sophos hosts this file may be empty. Existing host
+variable files are not overwritten. Removing a host also removes its
+corresponding host-vars directory.
+
+Routine add/update/remove operations perform local YAML validation and
+do not request the Vault password.
+
+## Access Management
+
+Linux access manages SSH keys/service-user access.
+
+Windows access includes temporary WinRM testing, local account creation,
+domain account creation/repair, member-server domain access, domain
+WinRM GPO rollout and configured-service-user testing.
+
+See `WINDOWS.md` for the Windows model.
+
+## Vault Management
+
+Vault operations include information, create, edit and delete.
+
+A new Vault is populated as plaintext with mode `0600`, YAML-validated,
+then encrypted using:
+
+``` bash
+ansible-vault encrypt --vault-id <customer>@prompt vault.yml
+```
+
+A failed encryption must not leave populated plaintext secrets behind.
+
+## Variables
+
+Group and host variable views are generally operator-readable without
+AIM rewriting arbitrary custom configuration. AIM only changes values in
+workflows explicitly designed to do so.
+
+Template consolidation is explicit and non-destructive: missing AIM
+defaults/comments can be added, while existing non-empty values and
+custom keys are retained.
+
+## Playbooks
+
+Curated categories include CheckMK, Debug, Maintenance and Sophos XGS.
+Compatible host/group selection is used to build the Ansible `--limit`.
+
+Interactive playbooks and operations that require password/Vault prompts
+retain live terminal access.
+
+## Administration
+
+Administration includes inventory validation, template consolidation,
+recovery and customer defaults.
+
+Explicit inventory validation performs YAML parsing and
+`ansible-inventory`. When a customer Vault exists, validation uses the
+customer's Vault identity and may prompt for its password.
+
+AIM maintains one pre-change inventory recovery backup per inventory per
+AIM process/session:
+
+``` text
+hosts.aim-session.bak.yml
+```
+
+Restores are explicit and YAML-validated.