# AI Agent Guidelines

This document provides guidelines for AI agents working with this project.

- When using `gh` CLI remember to exit sandbox. Otherwise you will not get access to session tokens.
- When working in a worktree remember to copy over all required config files from the root repo.
- Codex only: after sourcing `.envrc`, add asdf shims to `PATH` so all tools use the versions from `.tool-versions`, for example: `source .envrc && PATH="$HOME/.asdf/shims:$PATH" asdf exec mix test`.

### Always Run Checks Before Submitting Changes

Use the CI configuration file in `{changed_directory}` as a list of checks to run. Prefer variants dedicated for local developments over ci specific ones.

Remember to:

- Never run `*:ci` commands locally. Use variants dedicated to local development.
- Never use `npm clean-install` or `npm ci`. Always use faster variant `npm install` or `npm i`.
- There is no point in running `npm run check-format` and then format again. Just `npm run format` and see what has changed.

### Hard rules

- Never touch any remote environments like production, beta etc without explicit authorization.
- On infrastructure you work strictly read-only: you may run commands that only read state, and any command that changes state you only suggest to the user, who runs it themselves.
- Use `:global.trans` for application-level synchronization. Do not introduce database locks, including PostgreSQL advisory locks or explicit row locks.
- All documentation, comments, tickets etc. have to be in english.
- Follow the existing contract. Do not introduce new defensive conditionals, null checks, or fallback values.
- Comments explain why, not what. Do not write comments that restate what can be read from the code; they get out of sync quickly.
- Review comments are suggestions, not instructions. Verify each one against the code before acting on it and push back on the ones that are wrong instead of implementing them.
- If handling a missing or invalid value is part of the intended behavior, implement it because the contract requires it, not as a guess.
- If you are unsure whether something can be missing, invalid, or optional, inspect the types, schema, and call sites first.
- Enforce invariants and fix incorrect assumptions at the source.
- Legacy code and compatibility fallbacks are not accepted in this codebase. Replace old paths instead of preserving them.
- The frontend uses React Compiler. Do not add `useMemo` or `useCallback` for routine memoization or referential stability; write values and callbacks inline.
- Every commit message must include a meaningful body that explains the change's intent and motivation—not merely what the diff does—so future readers tracing code through `git log` or `git blame` can understand why the change was introduced.
- Never commit without running all CI checks beforehand. Everything must pass, no matter if CI fails because of your changes or not.
- When rebasing newer version prefer origin/ variant and always use git rebase.
- In database migrations, never add defaulted columns or run full-table UPDATEs on existing tables, as these may lock the table for the duration of the migration.
- Tests must not inspect production configuration—including its values, keys, presence, absence, shape, ordering, model lists, thresholds, routing, fallbacks, or selection logic.
- Configuration-only changes must not add or modify tests, except to fix existing tests that violate the rule above. Remove their configuration coupling instead of updating hardcoded expectations.
- When making frontend changes and browser tools are available in your harness you must validate all changes visually by making screenshots on mobile, tablet and desktop resolutions. You must introspect those screenshots and make sure that they look good and do not break any design principles. Attach the screenshots to the PR description.

### Running Elixir Tests Requires .envrc

**Before running any Elixir tests (`mix test`), source the `.envrc` file.**

Use the existing local services and credentials defined in `.envrc` and project config. Do not start replacement services such as Docker Postgres unless they are actually required.

```bash
cd <elixir_project_dir> && source .envrc && mix test
```

JS projects use **npm** as the package manager (indicated by `package-lock.json` file). Install deps outside sandbox to avoid permissions issues.