# Agent Guidelines for atex

## Commands

- **Test**: `mix test` (all), `mix test test/path/to/file_test.exs` (single
  file), `mix test test/path/to/file_test.exs:42` (single test at line)
- **Format**: `mix format` (auto-formats all code)
- **Lint**: `mix credo` (static analysis, TODO checks disabled)
- **Compile**: `mix compile`
- **Docs**: `mix docs`

## Code Style

- **Imports**: Use `alias` for modules (e.g.,
  `alias Atex.Config.OAuth, as: Config`), import macros sparingly
- **Formatting**: Elixir 1.18+, auto-formatted via `.formatter.exs` with
  `import_deps: [:typedstruct, :peri, :plug]`
- **Naming**: snake_case for functions/variables, PascalCase for modules,
  descriptive names (e.g., `authorization_metadata`, not `auth_meta`)
- **Types**: Use `@type` and `@spec` for all public functions; leverage
  TypedStruct for structs
- **Moduledocs**: All public modules need `@moduledoc`, public functions need
  `@doc` with examples
  - When writing lists in documentation, use `-` as the list character.
- **Error Handling**: Return `{:ok, result}` or `{:error, reason}` tuples; use
  pattern matching in case statements
- **Pattern Matching**: Prefer pattern matching over conditionals; use guards
  when appropriate
- **Macros**: Use `deflexicon` macro for lexicon definitions; use `defschema`
  (from Peri) for validation schemas
- **Tests**: Async by default (`use ExUnit.Case, async: true`), use doctests
  where applicable
- **Dependencies**: Core deps include Peri (validation), Req (HTTP), JOSE
  (JWT/OAuth), TypedStruct (structs)

## Important Notes

- **Update CHANGELOG.md** when adding features, changes, or fixes