added docs

docs/INVENTORY.md

@@ -0,0 +1,122 @@
+# AIM Inventory Model
+
+## Source of truth
+
+The authoritative inventory is:
+
+``` text
+/etc/ansible/inventories/<customer>/hosts.yml
+```
+
+AIM does not use `.hosts.tsv` as a secondary database and does not
+reverse-sync TSV data into YAML.
+
+AIM uses round-trip YAML handling so valid manually maintained
+structures/comments can be preserved where possible.
+
+## Platform groups
+
+Default top-level platform groups:
+
+``` text
+linux
+windows
+sophosxgs
+pfsense
+```
+
+Platform remains top-level because it determines connection semantics
+such as SSH, WinRM or HTTPAPI.
+
+Hosts may have multiple memberships and optional one-level functional
+subgroups.
+
+## Linux
+
+Linux group variables normally include the SSH connection and service
+account. The customer SSH key directory is:
+
+``` text
+group_vars/linux/.ssh/
+```
+
+not:
+
+``` text
+group_vars/linux/files/.ssh/
+```
+
+`ansible_ssh_pass` may remain configured as a legacy
+remote-login-password fallback. A private-key passphrase is a separate
+secret.
+
+## Windows
+
+Domain-joined Windows hosts normally inherit the group-level service
+identity/password.
+
+A local-account host can override credentials in:
+
+``` text
+host_vars/<fqdn>/main.yml
+```
+
+Shared local example:
+
+``` yaml
+ansible_user: svc_bf-ansible
+ansible_password: "{{ vault_windows_local_ansible_password }}"
+```
+
+Host-specific example:
+
+``` yaml
+ansible_user: svc_bf-ansible
+ansible_password: "{{ vault_ansible_password_server01_example_lan }}"
+```
+
+## Host vars
+
+Every newly managed host has:
+
+``` text
+host_vars/<fqdn>/main.yml
+```
+
+Existing host-vars content is not blindly overwritten.
+
+## Customer defaults
+
+AIM customer defaults live in:
+
+``` text
+/etc/ansible/inventories/<customer>/.aim.yml
+```
+
+Example:
+
+``` yaml
+domain_suffix: bfmiglabor.lan
+network_address: 10.20.30.0
+netmask: 255.255.255.0
+ad_dns_domain: intra.company.de
+ad_netbios_domain: COMPANY
+```
+
+The AD DNS domain is used for service-account UPNs. NetBIOS remains
+metadata/legacy naming information.
+
+## Safe writes
+
+Inventory mutations use the conceptual sequence:
+
+``` text
+candidate temp file
+→ local YAML validation
+→ compare
+→ session backup
+→ atomic replace
+```
+
+AIM also protects against stale/concurrent writes and uses an inventory
+lock.