# Playbooks and reporting contracts

**Current AIM 3.3.0rc8.** The catalog is authoritative for typed inputs, requirements and report declarations.

Run options omitted by a caller remain inherited from inventory/role defaults. Core
requires explicit compatible hosts and final scope review; group shortcuts expand to
deduplicated explicit hosts. `aim_debug` adds only selected diagnostics, not raw API output.

Normal terminal operations validate existing Vault passwords before launch and retain
the workflow on a typo. New-encryption/create prompts stay native. Catalog connections
use inventory/Vault credentials; automatic replay is never performed after launch.

## Catalog audit

| Key | Platforms | Report schema |
|---|---|---|
| `checkmk_install_agent` | linux, windows | `checkmk_agent_state_v1` |
| `checkmk_update_scripts_config` | linux, windows | `checkmk_agent_config_v1` |
| `checkmk_read_windows_config` | windows | `checkmk_user_config_v1` |
| `checkmk_cleanup_scripts` | linux, windows | `managed_cleanup_preview_v1` |
| `debug_test_connection` | linux, windows | None; native target outcomes/progress |
| `debug_show_disk_usage` | linux, windows | `filesystem_usage_v1` |
| `debug_detect_host_roles` | linux, windows | `host_capabilities_v1` |
| `maintenance_export_event_logs` | windows | `event_log_export_v1` |
| `maintenance_start_stopped_services` | windows | `service_start_summary_v1` |
| `maintenance_patch_os` | linux, windows | `patch_summary_v1` |
| `maintenance_reboot_hosts` | linux, windows | None; native target outcomes/progress |
| `sophos_apply_baseline` | sophosxgs | None; native target outcomes/progress |
| `sophos_apply_customer` | sophosxgs | None; native target outcomes/progress |
| `pfsense_apply_baseline` | pfsense | None; native target outcomes/progress |

Customer Sophos profiles share the catalogued customer operation; their five concrete
playbooks remain unchanged and publish no operation payload. Firewall policies, connection
test and reboot behavior were not redesigned for reporting.

## Schema and operational details

See [OPERATION_RESULTS.md](OPERATION_RESULTS.md) for field meanings and missing/partial/
check-mode behavior. Read [CHECKMK.md](CHECKMK.md) for managed filename/section ownership.
Role READMEs retain local default settings. `list_playbooks` exposes the current typed
input definitions and resolved report schemas; add-ons need not keep copies of this table.

## OS patch reporting

The catalog exposes `os_patching_reboot`, `os_patching_reboot_delay_minutes`,
`os_patching_reboot_message`, Windows categories, and the Windows-only
`os_patching_rescan_after_reboot` flag. The message/delay apply only when AIM initiates a
reboot.

Windows delegates each current patch wave to one native `ansible.windows.win_updates`
`state: installed` invocation with `reboot: false`. The module/WUA owns selection and
sequencing inside that selected category wave; AIM does not loop individual updates or use
`accept_list` to manufacture its own scheduler. Per-update records returned by the module
are normalized for reporting.

If the completed wave requires reboot, AIM either defers it or performs the reviewed
message/delay/reboot. By default (`os_patching_rescan_after_reboot: false`) that reboot ends
the run, so another wave requires a new operator-approved execution. When explicitly
enabled, AIM may start another native wave after reboot; continuation is defensively bounded
to 12 wave invocations. A failed wave is never automatically replayed.

If a wave finishes without reboot, AIM performs one final read-only discovery for reporting
only. Windows reports expose individual installed and failed updates, bounded HRESULT
classifications, `continuation_required`, and whether the reported pending list is
authoritative.

Linux snapshots use dpkg-query/RPM before and after the existing operation, retaining
architecture and parallel installed version sets. Every net difference is published;
intermediate no-net-change transactions are not observable from snapshots. No package
stdout scraping or guessed versions. Check mode never claims installation.

## Service recovery

Initial stopped/eligible/excluded states, actual attempts and post-start observations
are all separate. `failed_to_start` gives fixed reasons and numeric codes where known.
The default fail-on-error policy still fails the run after a report is published.

## Security

Catalogs, roles and inventory are trusted controller code. Report schemas are reviewed
public data contracts, not automatic secret scanners. Operator-owned Checkmk config
can contain credentials; its reader filters known secret/command fields and publishes
redacted paths. No general raw-file/data export was enabled.