dl-organizer/AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization
- Core package lives in `src/vlm/`.
- CLI entrypoint is `src/vlm/cli.py` (`vlm` console script). Shared CLI helpers live in `cli_helpers.py`. Command logic is in `commands/` (scan, parse, enrich, analyze, plan, execute, review_plan, report, quarantine_cmd, state_cmd, config_cmd).
- Functional modules by concern: scanning (`scanner.py`), parsing (`parser.py`), enrichment (`enrichment.py`, `cache.py`, `providers/`), analysis/planning/execution (`analysis.py`, `planner.py`, `executor.py`), I/O helpers (`io.py`), utilities (`utils.py`), state/reporting/logging (`state.py`, `reports.py`, `logging_config.py`), config (`config.py`), models (`models.py`).
- Tests live in `tests/` and mirror feature areas (e.g. `tests/test_scanner.py`, `tests/test_cli_state.py`, `tests/test_enrichment.py`).
- Project metadata and tool config are in `pyproject.toml`.

## Build, Test, and Development Commands
- `uv pip install -e .` installs the package in editable mode.
- `uv pip install -e ".[dev]"` installs dev dependencies (`pytest`, `hypothesis`, `pytest-cov`, `ruff`).
- `uv run pytest -q` runs the full test suite.
- `uv run pytest tests/test_logging.py` runs a targeted test file during iteration.
- `uv run ruff check src tests` runs the linter (also in CI).
- `vlm --help` verifies CLI startup and available commands.

## Coding Style & Naming Conventions
- Use Python 3.10+ idioms, 4-space indentation, and PEP 8 naming.
- Modules/functions/variables: `snake_case`; classes: `PascalCase`; constants: `UPPER_SNAKE_CASE`.
- Keep modules focused on a single responsibility; prefer small pure helpers in domain modules.
- Add type hints for public functions and non-trivial internal APIs.
- Use absolute imports in `src/vlm/`: `from vlm.module import ...` (avoid new relative imports).
- Ruff (`E`, `F`, `I`) is configured in `pyproject.toml`; CI runs `ruff check src tests`.

## Testing Guidelines
- Framework: `pytest`; property-based tests use `hypothesis`.
- Naming (enforced in config): files `test_*.py`, functions `test_*`, classes `Test*`.
- Add/extend tests with each behavior change, including CLI error paths and edge cases.
- Prefer narrow unit tests for module logic plus targeted CLI integration tests via `CliRunner`.

## Commit & Pull Request Guidelines
- Current history is minimal; use clear, imperative commit subjects (example: `fix logging fallback for unwritable log dir`).
- Keep commits focused; avoid mixing refactors and behavior changes unless tightly coupled.
- PRs should include: summary, rationale, test evidence (`pytest` output), and any CLI-visible output changes.
- Link related issues/tasks when applicable and call out config or migration impacts.

## Security & Configuration Tips
- Do not commit local paths, personal media metadata, or generated state/log artifacts.
- Validate config changes against `vlm --help` and at least one end-to-end CLI flow before merging.


## Documentation baseline
- Updated to reflect release 0.2.0 baseline as of 2026-06-01.
- Canonical release notes are tracked in `CHANGELOG.md`.
- Default workflow artifacts: `artifacts/` (do not commit generated CSV/JSON).