add program files

README.md

@@ -1,2 +1,90 @@
 # audibooksorter
 
+An audiobook sorter for Audiobookshelf libraries. Give the root path of your Audiobookshelf library and the tool will materialize a sorted structure arranged by:
+
+-Author
+--Series
+----Title
+
+
+# Title Folder Naming
+
+In addition to the book title, the title folder can include the publish year, series sequence, the subtitle, and the narrator.
+
+Here are a bunch of ways the same book could be named:
+
+Wizards First Rule
+
+Wizards First Rule {Sam Tsoutsouvas}
+
+1994 - Wizards First Rule
+
+Wizards First Rule - A Really Good Subtitle
+
+1994 - Book 1 - Wizards First Rule
+
+1994 - Volume 1. Wizards First Rule {Sam Tsoutsouvas}
+
+Vol 1 - 1994 - Wizards First Rule
+
+1994 - Wizards First Rule - Volume 1
+
+Vol. 1 - 1994 - Wizards First Rule - A Really Good Subtitle {Sam Tsoutsouvas}
+
+(1994) - Wizards First Rule - A Really Good Subtitle
+
+1 - Wizards First Rule
+
+1. Wizards First Rule
+
+    Subtitle: Parsing out subtitles into a separate field is optional and must be enabled in settings. Subtitle must be separated by " - ".
+    Series Sequence: Case insensitive & decimals supported.
+        The sequence can be placed anywhere in the folder name.
+        It must be followed by " - " or ". "
+        If it is not at the beginning of the folder name, it must be preceded by " - " and "Vol" "Vol." "Volume" or "Book"
+    Publish Year: The publish year must be the first part of the name OR directly after a series sequence, and separated by " - " on both sides.
+    Narrator: Must be wrapped in curly braces. e.g. {Sam Tsoutsouvas}.
+    Disc Numbers: The title folder can contain subfolders for discs as long as they are named "Disc", "CD", or "Disk" with a number following (case insensitive). Example: "Disc 1", "CD 2", "Disk 3", "Disc 004", or no space between like "Disc1". 
+
+# Author Folder Naming 
+Supports "Last, First" author naming as well as multiple authors separated by ",", ";", "&" or "and".
+
+Valid author folder names:
+
+Ichiro Kishimi
+
+Kishimi, Ichiro
+
+Ichiro Kishimi, Fumitake Koga
+
+Kishimi, Ichiro, Koga, Fumitake
+
+Ichiro Kishimi & Fumitake Koga
+
+Kishimi, Ichiro & Koga, Fumitake
+
+Terry Goodkind, Ichiro Kishimi and Fumitake Koga
+
+## Development setup
+
+This repository now uses [PDM](https://pdm.fming.dev) for packaging so tooling, dependencies, and the src layout stay in sync.
+
+1. Install PDM (`pipx install pdm` or `pip install --user pdm`).
+2. Create a virtual environment via `pdm venv create --with python3.11` if your system Python does not match the required version.
+3. Install the application and dev requirements with `pdm install --dev`.
+
+PDM writes metadata to `pdm.lock`; regenerate it with `pdm lock --refresh` whenever dependencies change.
+
+## Common commands
+
+- Run the CLI: `pdm run python -m audiobooksorter.cli --library /path/to/library --output ./sorted_library` (pass a JSON export from `samples/` only when running tests)
+- Format and lint: `pdm run ruff check --fix && pdm run ruff format`
+- Test with coverage: `pdm run pytest -q`
+
+## Library ingestion
+
+The sorter walks the supplied library directory looking for `metadata.json` files (one per audiobook folder). Those metadata files must at least contain `title` and `author`, and may optionally declare `series` and `seriesIndex`. For integration tests and CI you can still point `--library` at a JSON export; the CLI will treat JSON inputs as fixtures and skip filesystem moves.
+
+## Project layout
+
+Source code lives under `src/audiobooksorter/` with ingestion, sorter, and export modules split into subpackages so the command-line interface stays thin. Static assets are kept in `assets/`, while anonymized example exports live in `samples/`. Pytest suites mirror the package structure inside `tests/`.