# Repository Guidelines

## Project Structure & Module Organization

I38Lock is an accessible C screen-locking utility based on i3lock. Core sources live at the repository root: `i3lock.c` handles the main program, while `xcb.c`, `randr.c`, `dpi.c`, `unlock_indicator.c`, and `accessibility_feedback.c` separate display, UI, and screen-reader concerns. Public project headers are under `include/`. The PAM service file is `pam/i38lock`, the manual page is `i38lock.1`, and packaging or CI support lives in `meson/`, `ci/`, and `.github/`.

## Build, Test, and Development Commands

Install the dependencies listed in `README.md`, then build out of tree:

```sh
meson setup build -Dprefix=/usr
ninja -C build
```

To reproduce CI's stricter compile check, configure a fresh build directory:

```sh
CFLAGS="-Wformat -Wformat-security -Wextra -Wno-unused-parameter -Werror" meson setup build-ci
ninja -C build-ci
```

Run `nix develop` first if using the provided Nix development shell. Avoid installing from a development build unless installation behavior is the focus of the change.

## Coding Style & Naming Conventions

The project uses C11 and the checked-in `.clang-format`. Use four-space indentation, braces for control statements, and existing snake_case naming patterns. Format C sources and headers with:

```sh
clang-format-15 -i $(git ls-files '*.c' 'include/*.h')
clang-format-15 --dry-run --Werror $(git ls-files '*.c' 'include/*.h')
```

## Testing Guidelines

There is no automated runtime test suite. Every change must compile with the strict warning flags above. For behavior changes, run `timeout --foreground 30s build/i38lock -n` from an X11 session, verify the affected workflow, then unlock by entering your password and pressing Enter. Install `pam/i38lock` first and keep the watchdog enabled to avoid locking yourself out of an active development session.

## Commit & Pull Request Guidelines

Recent commits use short imperative subjects, often scoped when useful, such as `meson: use explicit_bzero if it is available`. Keep each commit focused. Pull requests should explain the behavior change, include reproduction and verification steps, and link relevant issues. Include `i38lock --version` and environment details for bug fixes. Do not propose image-manipulation features; preprocess background images with external tools.