# AIM: Ansible Inventory Manager

**Current candidate: 3.3.0rc4. Canonical Ansible Core: 2.19.11. Service/wire/event API: 1.0.**

AIM is an independent controller product with a built-in terminal (`aim`), a machine
interface (`aimctl`) and an additive Python facade (`aim.services.v1`). Add-ons consume
Core contracts; they do not patch Core, emulate its console or own execution semantics.

## This release

The new `aim_output_v1` publisher convention and catalog-owned schemas expose purposeful
operation data independently of task progress and per-target outcomes. Nine operations
now publish reports: role detection, disk usage, event exports, service recovery, OS
patching, Checkmk cleanup, user-config reading, agent installation and config updating.

Results are finite typed data, not raw Ansible stdout/debug/module dictionaries. Existing
nonreporting operations keep `operation_result: null`. Both summary and detail clients
receive final reports. The terminal retains native output; native Ansible retains its
own execution behavior and does not become a Core API consumer.

3.3.0rc4 makes Windows patching wave-based around the native `ansible.windows.win_updates`
orchestration. AIM submits the currently selected category set as one Windows Update wave
with `reboot: false`, lets the module/WUA process that wave, and evaluates reboot policy only
after the wave returns. A reboot ends the run by default; another post-reboot wave requires
explicit `os_patching_rescan_after_reboot: true`. AIM no longer implements a per-update
scheduler. Per-update result/HRESULT evidence is still normalized into `patch_summary_v1`.

## Install or update

Distribute the complete `AIM-Ansible-3.3.0rc4.zip` and matching `.zip.sha256` from a trusted
channel. A checksum checks integrity, not publisher authenticity. No Git or patch workflow.

```bash
cd /var/tmp
sha256sum -c AIM-Ansible-3.3.0rc4.zip.sha256
unzip AIM-Ansible-3.3.0rc4.zip
cd aim-core-3.3.0rc4
sudo python3 deploy/deploy.py update --dry-run
# Review the plan, then stop active jobs and source writers before applying.
sudo python3 deploy/deploy.py update --apply --quiesced
hash -r
aim --version
aimctl --version
aimctl capabilities
```

The deployer discovers the existing AIM interpreter from its recognized launcher. Only
supply `--aim-python /absolute/venv/bin/python` when discovery needs an explicit known path;
never pass an empty shell variable. Provision AIM's declared dependencies separately for
fresh installation, then use `install` instead of `update`. The deployer does not install
packages, modify services or enable external execution.

Existing `scripts/aim.yml`, inventories, Vaults, keys, environments, add-ons and customer
assets stay. The six explicitly retired Core documents listed in the deployment guide
are removed with recovery copies; unknown operator documents are not purged.

## Canonical documentation

Start at [the documentation index](scripts/docs/README.md). There is one current document
per topic, one current validation record and one current sanity checklist. Historical
changes remain only in [CHANGELOG](scripts/CHANGELOG.md), not competing release guides.

- [Release notes](scripts/docs/RELEASE_NOTES.md) and [validation](scripts/docs/VALIDATION.md)
- [Fresh installation](scripts/docs/INSTALLATION.md), [deployment/recovery](deploy/README.md), and [controller sanity tests](scripts/docs/SANITY.md)
- [Authoritative Core guide](AGENTS.md) and [add-on guide](ADDON_AGENTS.md)
- [API contract](scripts/docs/ADDON_API.md), [operation results](scripts/docs/OPERATION_RESULTS.md), [handoff](scripts/docs/RELEASE_HANDOFF.md)
- [Playbooks](scripts/docs/PLAYBOOKS.md), [Checkmk settings](scripts/docs/CHECKMK.md), [executor staging](scripts/docs/EXECUTOR_STAGING.md)

**Acceptance:** implementation/local tests do not certify this candidate on Windows,
Linux package managers or a deployed service sandbox. Previous controller successes
are historical evidence, not new test passes. External execution is still opt-in and
requires the authorized execution account, collection access and writable staging.