Document PAM categorical sidecar behavior on open_geotiff/to_geotiff (#3592)

[brendancol]

Closes #3592

Doc-only. to_geotiff writes a PAM .aux.xml sidecar whenever the DataArray carries attrs['category_names'], and open_geotiff merges category_names/category_colors back from that sidecar on local reads. The behavior landed in #3483 and is tested; it just wasn't written down anywhere.

• open_geotiff: new Notes paragraph covering the sidecar merge (all four read paths, fail-safe on missing/malformed/foreign sidecars, file-like sources skip it).
• to_geotiff: new description paragraph covering the categorical sidecar write (keyed on attrs alone, every dispatch path including .vrt, file-like destinations skip it, categorical wins over color_ramp).
• docs/source/user_guide/attrs_contract.rst: rows for category_names and category_colors, with the sidecar caveat and the length-mismatch rule for colors.

No behavior changes. Backend coverage n/a (docs only).

Each documented claim was executed against the code before writing it down: categorical round-trip on the eager, dask, and VRT read paths; sidecar emitted from the .vrt writer; a stats-only foreign sidecar ignored on read; colors dropped on length mismatch (write-side check in build_pam_xml).

Test plan:

• xrspatial/geotiff/tests/parity/test_signature_contract.py (25 passed)
• test_polish.py, unit/test_signatures.py, parity/test_reference.py (255 passed)
• -k "pam or sidecar or categor" across the geotiff suite (143 passed)
• docutils parse of attrs_contract.rst (no table errors)

Found by the documentation sweep. The sweep state CSV update rides along on this branch.

[brendancol]

PR Review: Document PAM categorical sidecar behavior (#3592)

Doc-only PR: two docstring additions and two new attrs-contract rows. Reviewed by checking each documented claim against the code rather than the usual backend/numerics checklist, most of which does not apply here.

Blockers

None.

Suggestions

None.

Nits

• xrspatial/geotiff/__init__.py (open_geotiff Notes): "Local string-path reads also pick up categorical metadata" is scoped correctly, but a reader might wonder about URL string sources. The lookup runs for any string source and simply never matches a remote URL (os.path.exists on url + '.aux.xml' is False), so the text is accurate as written. Fine to leave.

Verified claims

• The "every backend" read claim matches the four _attach_category_attrs call sites (eager, dask, GPU, VRT) in xrspatial/geotiff/__init__.py.
• The "every dispatch path" write claim matches the four _write_sidecars() call sites in xrspatial/geotiff/_writers/eager.py, including the .vrt path.
• "Categorical wins when both apply" matches the color_ramp and not _cat_names and not pack gate.
• The color length-mismatch rule in the new category_colors row matches build_pam_xml's write-side check.
• Round-trip, dask merge, VRT sidecar emit, and stats-only-sidecar rejection were all executed against the branch and behave as documented.
• parity/test_signature_contract.py (25), the docstring assertion suites (255), and the PAM-focused subset (143) all pass with the new text.

The issue number cited in the rst row (#3482) is the original issue rather than the implementing PR (#3483), which matches how other rows cite provenance.