add program files

AGENTS.md

@@ -0,0 +1,25 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Source lives in `src/audiobooksorter/`: ingestion (`ingest.py`), sorting rules (`sorter/series_rules.py`), exporting (`export.py`), and the CLI (`cli.py`). Config defaults sit in `config/`, constants in `constants.py`, and shared logging in `logging.py`. Sample inputs for quick runs live in `samples/`. Test suites mirror the package under `tests/`, with fixtures in `tests/conftest.py`. Assets that do not execute (icons, mock exports) belong in `assets/`. Local library fixtures for manual checks live in `testdata/`.
+
+## Build, Test, and Development Commands
+Use Python 3.11+. Set up a venv and install dev tooling:
+```
+python -m venv .venv && source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e .[dev]
+```
+Preview ordering without writing files via `python -m audiobooksorter.cli --library ./testdata --dry-run`. Run against a JSON export with `python -m audiobooksorter.cli --library ./samples/library.json --output ./sorted_library.json`. Format and lint with `ruff check --fix` (plus `ruff format` if desired). Execute the suite using `pytest -q` (coverage gates are pre-configured).
+
+## Coding Style & Naming Conventions
+Follow PEP 8 with 4-space indentation and type hints on public surfaces. Prefer descriptive module names (`series_rules.py`, `ingest.py`) and uppercase constants. Use dataclasses for structured audiobook records and the shared logger from `logging.py` to centralize verbosity control.
+
+## Testing Guidelines
+Tests target `pytest` with coverage enforced at 90% (`pytest --cov=audiobooksorter --cov-report=term-missing`). Name files `test_<unit>.py` and tests `test_<behavior>`. Add regression cases whenever sorting order changes—especially around edge series, mixed narrators, or missing metadata—in both `tests/` and `testdata/` when a folder-based scenario is required.
+
+## Commit & Pull Request Guidelines
+Commit messages follow the `type(scope): summary` pattern (e.g., `feat(cli): add dry-run preview`). Reference issues in bodies (`Fixes #ID`). Pull requests should include a clear description of user-facing changes, testing evidence (command output is fine), and any migration notes for library paths or naming rules. Request review for sorting rule tweaks to avoid regressions in existing shelves.
+
+## Security & Configuration Tips
+Do not commit personal Audiobookshelf exports; anonymize anything checked into `samples/` or `testdata/`. Keep secrets (.env, tokens) out of the repo and load them at runtime. Validate file paths before writing outputs to avoid clobbering a user’s library.