# AGENTS.md (mw-pfeddersheim-workstation)

## Project Overview
This repository manages the infrastructure, configuration, and maintenance for Michael Wegener's primary workstation at satware AG (Pfeddersheim location). It uses Ansible for system configuration and shell scripts for maintenance.

## Key Directories
- `ansible/`: Configuration-as-Code via Ansible roles and playbooks.
- `docs/`: PARA-structured documentation (Product, ADR, Learnings, Tech).
- `scripts/`: Automation and maintenance scripts.
- `config/`: Templates for system configuration files.

## Essential Commands
| Task | Command |
|------|---------|
| Apply Configuration | `ansible-playbook ansible/workstation.yml` |
| System Maintenance | `bash scripts/maintenance.sh` |
| Package Cleanup (dry-run) | `bash scripts/cleanup.sh --check` |
| Package Cleanup (apply) | `bash scripts/cleanup.sh --apply` |
| NVIDIA Recovery (broken GUI) | `bash scripts/nvidia-recovery.sh --apply` |
| **Post-recovery** | **Reboot required to restore GUI login** |
| Verify Ansible | `ansible-playbook ansible/workstation.yml --check` |

## Standards
- **Baby Steps™**: Small, verifiable changes (<200 LOC per commit).
- **PARA Documentation**: Keep documentation updated in the `docs/` folder.
- **Zero-Trust**: Secrets must be handled via Ansible Vault or environment variables.

## Guardrails
- **NEVER** commit raw secrets to the repository.
- **ALWAYS** run Ansible with `--check` before applying changes.
- **NEVER** modify system configuration directly if it can be managed via Ansible.
- **Secrets Management**: All secrets stored in Bitwarden (`bitwarden.jantec.xyz`) and cached locally in `gnome-keyring` (D-Bus secrets service). See `docs/product/passwords.md` for details.

## Rules Hierarchy
- Global rules: `Rules/`
- Project rules: `.clinerules/`
- Agent instructions: `AGENTS.md` (this file)