# Repository Guidelines

## Project Structure & Module Organization
- Core package lives in `src/vlm/`.
- CLI entrypoint is `src/vlm/cli.py` (`vlm` console script). Commands use `pass_context` and `CLIContext` from `context.py`; some command logic lives in `commands/` (e.g. `scan`, `analyze`, `plan`).
- 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` runs the full test suite.
- `pytest tests/test_logging.py` runs a targeted test file during iteration.
- `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.
- No formatter/linter is currently enforced in `pyproject.toml`; keep style consistent with existing files.

## 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.