# PyNamer Project Rules

**Implementation Patterns:**
1. **Image Processing:**
   - Always maintain aspect ratio when resizing.
   - Use LANCZOS resampling for quality downscaling.
   - Handle transparency conversion when saving as JPEG.
   - Keep original image files untouched until final rename operation.

2. **Filename Generation:**
   - Enforce snake_case format.
   - Remove special characters.
   - Handle duplicate filenames by appending incrementing numbers.

3. **Error Handling:**
   - Log detailed errors for debugging.
   - Fail gracefully with clear user feedback.
   - Preserve original files on errors.

4. **Configuration:**
   - Sensible defaults for all configurable parameters.
   - Environment variables can override sensitive settings (API keys).
   - Config changes require restart (no hot-reloading).

**User Preferences:**
- Default to JPEG format for resized images (better compression).
- Default max dimension of 1024px (balances quality and efficiency).
- Dry-run mode enabled by flag for safety.

**Known Challenges:**
- Large images may still consume significant memory during processing.
- Some LLM models may have different optimal image sizes/formats.
- Transparency handling requires special consideration when converting formats.

**Workflow Patterns:**
- Always check file existence and supported formats first.
- Process images sequentially (no parallel processing yet).
- Log each major operation step for traceability.