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; command logic is modularized in commands/ (e.g. scan, parse, enrich, analyze, plan, execute).
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.

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.

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.

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.

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.

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.