Document the REST API and type the McritClient (#54)

[r0ny123]

Closes #54, which asks to look at falcon-apispec and to complete the docstrings and type hints of McritClient.

falcon-apispec, assessed

falcon-apispec 0.4.0 installs fine, but it only produces something useful when every responder carries an OpenAPI YAML block in its docstring and the request/response shapes are described as marshmallow schemas. MCRIT answers plain dicts and storage entry toDict() shapes from 54 responders, so adopting it would mean writing and maintaining schemas for all of them plus two new runtime dependencies (apispec, marshmallow) for a document that nothing else consumes. Not adopted. Instead the reference is generated from what already exists: the route table and the responder docstrings.

Changes

• Responder docstrings for all 54 endpoints: what the endpoint does, its query/body parameters and what it answers (including error codes). The timing decorator now uses functools.wraps, so responders keep their name and docstring.
• mcrit/server/api_reference.py renders docs/api_reference.md from falcon.inspect over the real app: method, path, description, and the McritClient method that calls the endpoint (private helpers and the partialmethod-based search_* methods are attributed to their public names). --check exits 1 when the committed file is stale. README links the reference.
• tests/testApiReference.py: every route is documented, the client cross-reference is right (spot checks plus the exact list of the four endpoints without a client method), and the committed reference equals the generated one, so the document cannot drift.
• McritClient: a class docstring, and docstrings plus parameter and return annotations for the constructor and all 52 public methods, naming the endpoint each one calls. Annotations describe the default mode; raw_responses=True is routed through one Any-typed helper instead of being encoded into every return type.
• Typing the client surfaced four places in McritConsole that iterate a client answer which can be None after a failed request; they now fall back to an empty list/dict.

Full suite: 206 passed. ruff, ruff format and ty (whole tree, as CI runs it) clean.

[r0ny123]

Live check with this branch deployed (the functools.wraps change touches every responder): 17 typed client calls against the running server answered the documented types, among them getFamilies (dict of FamilyEntry), getSamplesByFamilyId (dict of SampleEntry), isFamilyId(999999) (False), getSampleById(999999) (None), getQueueData (list of Job), getJobCount (int), search_functions (dict with cursor), getMatchesForPicHash with and without summary, and raw_responses=True (a requests.Response). python -m mcrit.server.api_reference --check reports the committed reference current.

Note for merge order: the "every route documented" test will flag responders added by other open PRs, so those branches (#31 recompute_family_stats, #37 repair_minhashes, the jobs count and the function rename) carry a docstring for their new responder now.