# Repository Guidelines

> Runtime code sits inside vexor/: Typer entrypoints (cli.py, main.py) delegate to service layers (services/indexservice.py, services/searchservice.py, services/configservice.py, services/skillservice.py) and shared…

- Skill: `tools-only/repository-guidelines-6` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/repository-guidelines-6`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/repository-guidelines-6/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/repository-guidelines-6

---

# Repository Guidelines

## Project Structure & Module Organization
Runtime code sits inside `vexor/`: Typer entrypoints (`cli.py`, `__main__.py`) delegate to service layers (`services/index_service.py`, `services/search_service.py`, `services/config_service.py`, `services/skill_service.py`) and shared helpers (`cache.py`, `config.py`, `text.py`, `utils.py`, `modes.py`). Provider adapters for Gemini/OpenAI/Local live under `providers/`. Documentation (`docs/development.md`, `docs/roadmap.md`, `docs/workflow-diagram.md`) and assets (`assets/`) explain workflows and future work, while build outputs only appear in `dist/`. Tests mirror the structure—`tests/unit/` covers helpers/services and `tests/integration/` drives CLI runs such as `test_cli.py` and `test_end_to_end.py`.

## Build, Test, and Development Commands
- `pip install -e .[dev]` installs Vexor plus pytest, coverage, and packaging helpers.
- `python -m vexor --help` smoke-tests the CLI; use `vexor index --path . --mode head` and `vexor search "config loader" --path . --mode name` for realistic runs.
- `pytest` stays offline via fake providers; scope down with `pytest tests/unit -k cache` and add `--maxfail=1 -ra` for quick failures.
- `pytest --cov=vexor --cov-report=term-missing` should pass before merging to hold the Codecov badge steady.
- `python -m build` (wheel+sdist) produces release artifacts mirrored by CI.

## Coding Style & Naming Conventions
Follow PEP 8 (4-space indent, ~100-char lines). Use `snake_case` for modules/functions, `PascalCase` for classes, and lowercase imperative Typer command names. Type-annotate new code, surface CLI validation errors via `typer.BadParameter`, and route user-facing copy through `text.py` so Rich styling remains consistent. Tests live in `test_<subject>.py`, prefer fixtures/stubs to real APIs, and assert structured output instead of console strings.

## Testing Guidelines
Unit suites validate deterministic logic (cache pruning, mode validation, extension handling), while integration suites spawn the CLI to verify Rich tables, config flows, and search/index orchestration. Keep fake provider fixtures current so runs remain offline. Pair every change with happy-path and failure coverage (invalid mode, missing config, empty query) and add regressions whenever cache or provider layers change.

## Commit & Pull Request Guidelines
History favors concise, imperative commit subjects (“Add vexor logo image”). PRs should explain motivation, list exercised commands or screenshots, link issues, and confirm `pytest --cov` output. Call out config-path, cache-schema, or provider changes so reviewers can check backward compatibility, and update README/docs when behavior shifts.

## Security, Configuration & Maintenance
Never commit API keys or provider endpoints; rely on `vexor config --set-api-key`, provider env vars, or ignored `.env` files. Cache/config data lives in `~/.vexor`—reset with `vexor config --clear-index-all` when troubleshooting stale indexes. Sanitize filesystem paths, treat embedding outputs as untrusted input before writing to disk, and update README/docs/this guide whenever workflows change.