# Repository Guidelines

## Project Structure & Module Organization
- Root contains `sk.sh`, a Bash utility for temporarily disabling or enabling a user account with optional countdown, notifications, and shutdown logic.
- No nested modules yet; add supporting scripts under a new `scripts/` directory and keep reusable helpers in separate Bash files to avoid bloating `sk.sh`.
- Assets (e.g., custom sounds) should live under `assets/` if introduced; reference them via absolute paths in the script.

## Build, Test, and Development Commands
- `bash -n sk.sh` — Syntax check to catch parsing errors early.
- `sudo ./scripts/install.sh` — On Ubuntu/Debian creates `/etc/pam.d/skd` and sets `SKD_AUTH_PAM_SERVICE=skd` if unset.
- `shellcheck sk.sh` — Linting for style, safety, and portability; fix or suppress with clear rationale.
- `./sk.sh <user> disable|enable [countdown] [sound] [seconds]` — Run the tool; requires root. Use a test account when iterating.
- `sudo ./sk.sh demo_user disable countdown sound 90` — Example invocation combining optional modes.

## Coding Style & Naming Conventions
- Bash 4+; prefer `[[ ... ]]` tests, `local` inside functions, and `set -euo pipefail` for new scripts (add thoughtfully to existing files to avoid breaking flows).
- Functions: `snake_case` verbs (`send_notify`, `is_user_logged_in`). Constants: uppercase with underscores.
- Keep comments concise and operational (what/why). German comments are acceptable but favor clear English going forward.
- Prefer long-form flags and explicit paths; avoid implicit `$PATH` reliance when running privileged commands.

## Testing Guidelines
- Add unit-like checks via small harness scripts or bats tests under `tests/` if complexity grows.
- Validate shutdown/notification branches using a non-privileged test user; avoid running destructive paths on production users.
- When adding flags or behaviors, document expected outcomes and add example invocations to this file.

## Commit & Pull Request Guidelines
- Use imperative, present-tense commit messages; include scope when helpful (e.g., `lint: address shellcheck warnings`).
- PRs should state behavior changes, risks, and manual test steps. If UI/notifications change, include example command lines and observed output.
- Link related tickets or incident IDs where applicable; keep changes small and reviewable.

## Security & Configuration Tips
- Script assumes root; never hardcode passwords or tokens. Validate `$USER_TO_MANAGE` exists before mutating accounts.
- Be cautious with shutdown logic: guard new features to avoid unintended reboots on inactive sessions.
- When adding sounds or notifications, prefer system-provided assets and handle missing dependencies gracefully as in `sk.sh`.