added docs

docs/DEVELOPMENT.md

@@ -0,0 +1,67 @@
+# AIM Development Guide
+
+## Project root
+
+``` text
+/etc/ansible/scripts/
+├── pyproject.toml
+└── src/
+    └── aim/
+```
+
+The environment is installed editable:
+
+``` bash
+/etc/ansible/.venv/bin/python -m pip install -e /etc/ansible/scripts
+```
+
+## Architecture
+
+Backend areas include inventory loading/writing/validation, customer
+management, backup/session recovery, locking, permissions, playbooks,
+SSH, Vault, Sophos and WinRM.
+
+The 2.1 UI is split into focused modules under `src/aim/ui/`, including
+shared components, selection, execution, customers, hosts, access,
+playbooks, administration and target selection.
+
+## UI conventions
+
+-   Orange `#ff7a00` is the AIM/bitformer accent.
+-   Green = success.
+-   Yellow = warning.
+-   Red = failure.
+-   No ASCII logo.
+-   Header identity: `bitformer · AIM · Ansible Inventory Manager`.
+-   Pagination: `p / n`.
+-   Numbered navigation: Enter/`0` = Back or Cancel.
+-   Multi-select: number toggles; Enter reviews; `0` cancels.
+
+Opening menus should not unexpectedly run Ansible, contact hosts,
+decrypt Vaults or prompt for passwords.
+
+## Inventory invariants
+
+`hosts.yml` is authoritative. Preserve arbitrary valid YAML/custom
+keys/comments where possible.
+
+Writes should be validated and atomic, with stale-write/concurrency
+protection and a session recovery backup.
+
+Do not change unrelated Ansible connection/authentication parameters as
+part of feature work.
+
+## Packaging
+
+Production packages should contain runtime source and metadata, without
+caches, `.pyc`, test artifacts, legacy Bash implementations or developer
+notes unless explicitly requested.
+
+A release archive should expose `pyproject.toml` and `src/` at its root
+rather than adding an extra wrapper directory.
+
+## Versioning
+
+Use a patch release for contained fixes and a feature/minor release for
+larger functional changes. Update package metadata and the changelog
+together.