docs(xet): document v2 CAS API + batch reconstruction; fix xorb chunk limit

[rajatarya]

Fixes public-docs drift found by the automated xet-docs-refresh audit (source of truth: xetcas@3c753ea, xet-core@v1.5.1).

docs/xet/api.md — document the /v2 API + batch reconstruction (fixes huggingface-internal/xetcas#1175)

The CAS API spec documented only four /v1 endpoints, but the client actively uses several more. Added:

• POST /v1/reconstructions — batch file reconstruction (batch_get_reconstruction).
• GET /v2/reconstructions/{file_id} — multi-range-optimized reconstruction (get_reconstruction_v2, QueryReconstructionResponseV2); fetch info keyed under xorbs.
• GET /v2/file-chunk-hashes/{file_id} — chunk-window / range-hash summaries for re-chunking dirty regions (get_file_chunk_hashes, FileChunkHashesResponse); requires the X-Range-Dirty header.
• POST /v2/shards — streaming (NDJSON) variant of shard upload (post_shard_v2).

docs/xet/xorb.md — correct the chunk-count limit (fixes huggingface-internal/xetcas#1176)

The doc stated there is "no explicit limit on the number of chunks in a Xorb." Source enforces MAX_XORB_CHUNKS = 8192 (xet_core_structures/src/xorb_object/constants.rs) in addition to the 64 MiB serialized-size cap; the client cuts a xorb once either bound is hit.

All additions match the source structs in xet_client/src/cas_types and the routes in cas_server/src/serve.rs.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only updates with no runtime or API behavior changes.

Overview
Brings the public Xet CAS docs in line with endpoints and limits the client already uses.

docs/xet/api.md adds four endpoint sections after the existing v1 APIs: POST /v1/reconstructions for batch file reconstruction (no byte ranges); GET /v2/reconstructions/{file_id} with QueryReconstructionResponseV2 and fetch info under xorbs (combined signed URLs and required Range values); GET /v2/file-chunk-hashes/{file_id} with mandatory X-Range-Dirty for incremental re-chunking; and POST /v2/shards as an NDJSON streaming upload with terminal success/error frames.

docs/xet/xorb.md replaces the claim that there is no chunk-count cap with MAX_XORB_CHUNKS (8192) alongside the 64 MiB serialized limit, and notes that clients start a new xorb when either bound is hit.

^{Reviewed by Cursor Bugbot for commit 9838b28. Bugbot is set up for automated code reviews on this repo. Configure here.}

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.