# Contributing to Bookmark

Bookmark is an early-stage, fully open-source tool built for Books in Hand,
a nonprofit that keeps books out of landfills. It's still scaffolding —
there's no working end-to-end app yet, so the best contributions right now
are small, focused, and coordinated first.

## Before You Start

This project is young enough that priorities can shift quickly. Please open
an issue (or comment on an existing one) describing what you'd like to work
on before submitting a large pull request — it avoids duplicated effort and
makes sure the change fits the current phase of the build.

See `CLAUDE.md` (also readable as `AGENTS.md`) in the repo root for full
architecture and design context, including what's in scope for the current
phase and what's intentionally deferred.

## Ground Rules

- **Deterministic where it matters.** Size-bucketing (small/medium/large)
  feeds the nonprofit's tax and 501(c)(3) reporting. It must stay
  geometry/visibility-based — never OCR, ML, or LLM-derived. Don't change
  this without understanding why.
- **No cloud dependencies in the current phase.** Keep the intake pipeline
  fully local.
- **Say what the mechanism actually is.** Use precise terms — "LLM",
  "vision-LLM (VLM)", "OCR", "barcode decode" — rather than the generic
  word "AI" in code, comments, docs, or UI copy.
- **Human review before publish.** Any future LLM/VLM-assisted output
  (e.g. cover text extraction) is a draft for a human to approve, never
  auto-published.

## Development Workflow

```bash
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -v
```

This project follows test-driven development — new modules should ship
with tests under `tests/` that don't require real camera hardware
(synthetic frames, mocked `cv2.VideoCapture`, `TestClient` for the API).

## Commit Style

Conventional-commit-style subjects: `feat:`, `fix:`, `docs:`, `chore:`,
`test:`, `refactor:`. Keep commits small and focused — one logical change
per commit.

## Submitting Changes

1. Fork the repo and create a branch for your change.
2. Make sure `pytest -v` passes.
3. Open a pull request describing what changed and why.
4. Be patient — this is a volunteer-maintained nonprofit project, so review
   may take a few days.

## Questions

Open an issue — it's the best way to reach the maintainers and keeps
context visible for future contributors.