[IvanGirderboot]

What changed

• Moves inventory/example/group_vars/all.yml to inventory/example/group_vars/all/main.yml, next to vault.yml.example.
• Points scripts/configure.py, scripts/init-local-inventory.sh, scripts/generate-variable-reference.py, README.md, and the docs (concepts, configuration, first-deployment, getting-started) at the new path. Also updates the pointer comment in the root group_vars/all.yml.
• Adds a fail-fast pre-task to playbooks/site.yml, playbooks/bootstrap.yml, and playbooks/network.yml. It stops the run when group_vars/all.yml sits next to a group_vars/all/ directory and tells the operator to move the file. scripts/configure.py validation reports the same error.
• scripts/qa.py rejects reintroducing the old example path.
• Adds a docs/configuration.md note explaining the layout and a CHANGELOG entry with the one-line migration.

Why

When an inventory has both group_vars/all.yml and a group_vars/all/ directory, Ansible loads only the directory and silently ignores the file. DataLoader.find_vars_files tries the bare name before the .yml extension and stops at the first match. I confirmed this in the ansible-core 2.21.4 source.

The example inventory shipped exactly that layout. So every local inventory created from it, whether by init-local-inventory.sh, the configurator, or a manual copy, has had hamstack_callsign, hamstack_grid_locator, hamstack_timezone, and every other site value silently dropped, with roles falling back to their own defaults. Found while setting up a real local inventory: ansible <host> -m debug -a var=hamstack_callsign reported it undefined.

Validation

• python3 scripts/qa.py — passed
• yamllint . — every changed YAML file is clean. Locally, the full-repo run still reports .venv/ contents until yamllint: skip .venv and .cache like ansible-lint does #3 merges; CI is unaffected.
• ansible-lint — exit 0 (existing warnings only)
• Relevant playbook(s) pass ansible-playbook --syntax-check (site.yml, bootstrap.yml, network.yml)
• A second Ansible run was checked for unexpected changes when live hardware/software was exercised — N/A, no hardware exercised

Tested hardware/OS and commands used: Linux (WSL2) controller, ansible-core 2.21.4, against a copy of the example inventory with a local-connection host:

• Old layout (all.yml next to all/): ansible-playbook playbooks/site.yml --check stops at the new pre-task with the move instruction.
• New layout (all/main.yml): the pre-task passes, and ansible -m debug -a var=hamstack_site_name resolves the site value, which was undefined before.
• python3 scripts/generate-variable-reference.py --check — current.
• py_compile on the changed Python scripts and bash -n on init-local-inventory.sh — clean.

Release/user impact

Manual migration for existing local inventories:

mv inventory/local/group_vars/all.yml inventory/local/group_vars/all/main.yml

Until they do that, site.yml, bootstrap.yml, and network.yml stop with that instruction rather than running with missing site values. After moving the file, site values that were previously ignored will start applying. Review hamstack_callsign, hamstack_timezone, and the rest before the next run, because a deployment that has been running on role defaults may see real changes.

The playbooks/profiles/* playbooks have no pre-tasks today and don't get the guard. They do benefit from the corrected example layout.

Documentation and secrets

• Public variable changes are reflected in examples/docs and docs/variables.md is regenerated — no variable names changed; reference regenerated and --check passes
• No real credentials, private inventory, event-only secrets, or sensitive artifacts are included
• Upstream-derived code/configuration retains required attribution and licensing information — N/A

🤖 Generated with Claude Code