# Coding Guidelines

## General style

- Prefer straightforward Python
- Use type hints
- Keep functions small and focused
- Add docstrings to public functions and classes
- Avoid overengineering
- Prefer composition over deep inheritance

## Error handling

- Fail clearly
- Provide helpful error messages
- Distinguish user-facing CLI errors from internal exceptions
- Avoid silently swallowing errors

## Logging

- Use structured and informative logging where useful
- Avoid noisy logs in normal CLI output
- Keep machine-readable command output clean when `--json` is used

## File operations

- Be careful with moves, copies, and overwrites
- Prefer atomic writes for JSON files when possible
- Never corrupt existing metadata due to partial writes

## Idempotence

Where possible, commands should behave safely when run multiple times.

Examples:
- re-importing the same file should detect duplicates
- `render-summary` should be repeatable
- `reindex` should be safe to rerun

## Testing

Add tests for:
- path layout logic
- metadata read/write behavior
- duplicate detection
- reindex behavior
- summary rendering
- search behavior
- CLI output contracts for core commands

Prefer unit tests for core logic and targeted integration tests for CLI behavior.