Imported from dino1729/ansible-new-linux-setup (AGENTS.md). Install upstream with npx skills add dino1729/ansible-new-linux-setup. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• main.yml is the orchestration entry point; it wires the role order and expects inventory localhost, for local installs.
• Idempotent roles live under roles/ (e.g., roles/nvidia_driver, roles/pyenv, roles/ollama_openwebui); keep role-specific defaults/vars inside the role to avoid leaking globals.
• Shared settings belong in group_vars/all/os_compatibility.yml, which documents supported distros and GPU matrices—extend it before touching GPU logic.
• Helper automation is kept in scripts/, currently scripts/run-local.sh, while Galaxy dependencies are pinned in requirements.yml and logging defaults in ansible.cfg.
• Architecture notes and rationale go to ARCHITECTURE.md; high-level docs stay in README.md.

Build, Test, and Development Commands

• Install Ansible collections: ansible-galaxy collection install -r requirements.yml.
• Full local run (auto-detects GPU): ./scripts/run-local.sh.
• Dev-tools-only smoke test: ./scripts/run-local.sh --minimal.
• Fine-grained runs: ansible-playbook main.yml -i "localhost," -c local -K -e "with_cuda=false" (adjust vars per feature toggle).
• Validate YAML structure with ansible-playbook main.yml --syntax-check before pushing.

Coding Style & Naming Conventions

• YAML uses 2-space indentation, lowercase keys, and descriptive task names (name: Install CUDA repo key).
• Prefer role defaults over hard-coded vars, and keep boolean feature flags consistent with existing with_* naming.
• Bash scripts should be set -euo pipefail, log to /tmp, and accept long-form flags (see scripts/run-local.sh).
• When adding callbacks or plugins, register them in ansible.cfg with one-per-line clarity.

Testing Guidelines

• Run ansible-lint plus ansible-playbook main.yml --check -i "localhost," -c local -K to confirm idempotence.
• Exercise GPU-sensitive roles with ./scripts/run-local.sh --no-driver, --no-cuda, and --minimal --with-docker to cover matrix branches.
• Document newly verified OS versions in group_vars/all/os_compatibility.yml and include any constraints under known_issues.

Commit & PR Guidelines

• Use imperative, scope-prefixed commits such as role(pyenv): add python-build deps to mirror the role layout.
• Reference the feature flags or OS targets touched inside the commit body and link the relevant doc section when behavior changes.
• PRs should summarize the playbook impact, list the exact command(s) used for testing, attach logs if GPU paths were exercised, and mention any required sudo/environment assumptions.

Security & Configuration Tips

• Never broaden sudo usage inside roles; leverage become: true only at the task level and respect ansible.cfg pipelining.
• Secrets (API keys for AI tools) must enter through vault-encrypted vars or environment prompts—do not bake them into group_vars.
• Keep download sources HTTPS-only and pin driver/CUDA versions in group_vars before introducing new binaries.