ADD CLAUDE.md with repository guidance for Claude Code

[mkiani12]

What changed

Adds a CLAUDE.md at the repository root documenting the commands, architecture, and conventions that currently require reading several files to reconstruct.

Why

The FEZrs codebase has a strong, consistent internal contract (BaseTool → FileHandler → per-category calculators) that is not written down anywhere. New contributors — and AI-assisted contributions, which CONTRIBUTING.md explicitly welcomes — have to infer it by reading base.py, file_handler.py, and several calculators side by side. This file captures that contract in one place.

Contents

• Commands — test invocation (full suite, per-directory, per-test, -k), the split between the pinned requirements.txt and the uninstalled requirements-dev.txt geo stack, how to run the bundled examples, and bump2version.
• BaseTool lifecycle — the six-step contract plus its non-obvious behaviors: filename_prefix is always overwritten with the class name, execute() accepts but does not forward nrows/ncols to _export_file, and nearly every calculator re-declares execute() purely to change matplotlib defaults.
• Band I/O layer — FileHandler as the single pixel-entry point, the consequential difference between get_normalized_bands and get_metadata_bands, and the coupling between band_paths dict ordering, get_images_collection(), and PCACalculator.bindTheBandsToNumber.
• Layout — the 1:1 fezrs/tools/<cat>/ ↔ docs/<cat>.md ↔ tests/tools/<cat>/ mapping, with fezrs/__init__.py as the canonical import surface.
• Adding a calculator — a checklist plus the established mock-based test pattern (patching BaseTool.__init__ at the calculator's own module path) that keeps tests off the disk and off the network, per CONTRIBUTING.md.
• Release plumbing — .bumpversion.cfg as the single version source, the setup.py ↔ requirements.txt sync that tests/setup_test.py enforces, and the generated CITATION.cff.

Notes for reviewers

Documentation only. No code, no behavior changes, no new dependencies, no structural reorganization. README.md is untouched, per the CONTRIBUTING.md guideline.

Two pre-existing issues are documented but not fixed here, as both are out of scope for a docs-only change:

1. fezrs/tools/change_detection/, fezrs/tools/svm/, and fezrs/media/ have no __init__.py, so find_packages(include=["fezrs", "fezrs.*"]) in setup.py does not collect them. Worth verifying that an installed wheel actually contains those modules.
2. README.md and paper/paper.md both document a chart_export() method that does not exist in the code — the actual public method is histogram_export().

CLAUDE.md also notes that the feature/... branch convention in CONTRIBUTING.md conflicts with a feat/-prefix policy enforced locally on the author's machine, hence this branch name.