added docs

docs/WINDOWS.md

@@ -0,0 +1,133 @@
+# Windows, WinRM and Active Directory
+
+## Service account
+
+The standard service account is:
+
+``` text
+svc_bf-ansible
+```
+
+For an AD domain, the configured identity is normally the UPN:
+
+``` text
+svc_bf-ansible@<ad_dns_domain>
+```
+
+The normal domain-account Vault variable is:
+
+``` yaml
+vault_windows_ansible_password: "..."
+```
+
+The shared-local-account Vault variable is:
+
+``` yaml
+vault_windows_local_ansible_password: "..."
+```
+
+## Windows credential models
+
+New Windows hosts can use:
+
+1.  Domain service account
+2.  Shared local service account
+3.  Host-specific local service account
+
+Local credential choices are host-specific overrides and must not
+rewrite `group_vars/windows/main.yml` for every Windows machine.
+
+## Domain account creation
+
+AIM can create/repair the domain service identity and add it to the
+appropriate built-in Administrators context used by the current design.
+It does not make the account a Domain Admin.
+
+Administrative bootstrap credentials should only be requested where
+genuinely required.
+
+## Member-server access
+
+AIM can grant the existing domain service identity local Administrators
+membership on selected member servers. Domain Controllers are
+rejected/skipped for this workflow.
+
+## Domain WinRM GPO rollout
+
+The rollout uses one prepared, already-manageable Domain Controller as
+its administration point.
+
+The managed objects are:
+
+``` text
+AD group: GG_bitformer_Ansible_Admins
+GPO:      bitformer - Ansible WinRM
+Task:     bitformer - Configure Ansible WinRM
+```
+
+The GPO configures the local Administrators membership, deploys the
+WinRM setup payload/scheduled task, configures HTTPS WinRM and firewall
+access, and verifies the resulting state.
+
+### Multiple target OUs
+
+A single GPO should be linked to multiple selected OUs rather than
+creating a separate GPO for Servers, Clients, etc.
+
+Example:
+
+``` text
+bitformer - Ansible WinRM
+├── OU=Servers,DC=intra,DC=company,DC=de
+└── OU=Clients,DC=intra,DC=company,DC=de
+```
+
+The OU selector should therefore support multi-selection.
+
+GPO link management is **additive and idempotent**:
+
+-   Selected OU already linked: keep/repair as appropriate.
+-   Selected OU not linked: create the link.
+-   Unselected OU: do nothing.
+
+Selecting only `Servers` on a later run must **not** imply that an
+existing `Clients` link should be removed.
+
+Link removal should be an explicit operation if/when AIM implements it.
+
+### Child OUs
+
+AIM links the GPO to the selected OU. It should not create redundant
+links on every descendant OU merely to emulate inheritance. Normal Group
+Policy inheritance handles descendants unless AD policy configuration
+changes that behavior.
+
+### Domain Controllers
+
+The Domain Controllers OU must remain unavailable/rejected for the
+normal member-machine WinRM rollout.
+
+## WinRM payload
+
+The payload ensures WinRM is running, configures/reuses a suitable
+certificate or creates a self-signed Server Authentication certificate,
+creates the HTTPS listener, allows TCP/5986 and verifies the final
+state.
+
+The scheduled task runs immediately after registration and can retry
+periodically. After successful verification it disables itself.
+
+## Troubleshooting
+
+Useful client-side checks include:
+
+``` powershell
+gpupdate /force
+gpresult /h C:\Temp\gpresult.html
+Get-Service WinRM
+winrm enumerate winrm/config/listener
+Get-ScheduledTask -TaskName "bitformer - Configure Ansible WinRM"
+```
+
+Also inspect Group Policy operational logs and Task Scheduler events
+when Group Policy Preferences reports a task import failure.