# 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.