docs: simplify hydrologist-facing documentation (milestone m1)

[CooperBigFoot]

docs: simplify hydrologist-facing documentation (milestone m1)

What changed

• docs(site): enable syntax highlighting, code copy button, and light/dark palette #21 updated mkdocs.yml with syntax highlighting, a code-copy button, and a light/dark palette for the docs site.
• docs(site): rewrite how-it-works on precomputed catchment connections #22 rewrote docs/how-it-works.md around precomputed catchment connections and the plain watershed framing.
• docs(export): remove HDX mentions from basin GeoParquet export page #23 removed unsupported HDX mentions from docs/basin-geoparquet-export.md.
• docs(pyshed): slim README to quickstart, move tuning knobs to API.md #24 slimmed crates/python/README.md to a quickstart and moved pyshed tuning knobs into crates/python/API.md.
• docs(readme): rewrite top-level README for hydrologists with plain pitch and uv install #25 rewrote the top-level README.md for hydrologists, centered the pitch on giving shed a point on a river and getting the whole upstream area that drains to it, and switched install instructions to uv add pyshed with a pip fallback.
• docs(site): align index, quickstart, datasets, and credits to plain watershed framing #26 aligned docs/index.md, docs/quickstart.md, docs/guide/datasets.md, and docs/credits.md to the same plain-language watershed framing.

Why

This milestone makes the docs easier to read for hydrologists evaluating shed. The new framing is direct: give shed a point on a river and it returns the whole upstream area that drains to it, the watershed.

The campaign also removes unsupported performance numbers, removes HDX from user-facing docs, and keeps advanced pyshed tuning details out of the PyPI README so the package page stays focused on installation and first use.

No version bumps and no tags are included, following the curated-release policy.

Verification

• Inspected main..milestone-m1: six squash-merged step PRs, docs(site): enable syntax highlighting, code copy button, and light/dark palette #21 through docs(site): align index, quickstart, datasets, and credits to plain watershed framing #26.
• Confirmed the final diff touches ten files: README.md, crates/python/API.md, crates/python/README.md, docs/basin-geoparquet-export.md, docs/credits.md, docs/guide/datasets.md, docs/how-it-works.md, docs/index.md, docs/quickstart.md, and mkdocs.yml.
• Confirmed diff size: 10 files changed, 215 insertions, 442 deletions.
• Every step PR was plan-reviewed and diff-reviewed before merge.
• Final automated style-lint sweep over all ten edited files passed with zero residues.
• Strict MkDocs build passes.