Docs: correct API-reference drift, stale comments, and changelog

[RyanCodrai]

Addresses #101 (and more found in a full doc sweep). Docs-only / comments-only — no code behavior change.

User-facing docs

README.md

• Python persistence example used the non-existent .tq extension → .tv.
• Rust snippets called TurboQuantIndex::new / IdMapIndex::new (both return Result) and used the value directly — wouldn't compile. Added .unwrap() to match the crate's own doctests.

docs/api.md

• bit_width documented as {2, 4}; the core accepts {2, 3, 4}.
• File-format diagrams were stale (described the pre-magic v1 layout). .tv now carries a TVPI magic + version 3 + per-vector scales + a TQ+ trailer; .tvim is version 3 (was documented as 1, which the loader now rejects). Updated both diagrams and the surrounding notes.

docs/integrations/llama_index.md

• Filter docs were inverted: NOT, ANY, ALL, and TEXT_MATCH_INSENSITIVE are all implemented (doc claimed they raise NotImplementedError), and TEXT_MATCH is case-sensitive (doc said case-insensitive). Corrected the operator/condition lists and the semantics note. Documented that an intra-batch duplicate node_id raises (vs the langchain/haystack keep-last behavior).

docs/integrations/agno.md

• "Every public method has an async counterpart" was false; listed the methods that actually have async variants and the sync-only ones.

Code comments

• search.rs module doc claimed only "AVX2 on x86"; it actually has an AVX-512BW kernel selected at runtime with an AVX2 fallback (+ scalar fallback). Also corrected an AVX-512 comment that named a never-called avx2_block_epilogue helper.
• llama_index.py from_persist_dir docstring said the side-car uses .pkl; it is .nodes.json.
• dump_state.rs example referenced benchmarks/rabitq_poc/poc_apples_to_apples.py, removed in Remove benchmarks/rabitq_poc research scratch #97; reworded generically.

CHANGELOG

• Added an [Unreleased] entry for the merged bug: intra-batch duplicate IDs create orphaned vectors (langchain, agno) #90 / bug: upsert deletes old data before validating new data — data loss on validation failure #89 integration fixes.
• Repointed the stale [Unreleased] compare link (py-v0.4.2 → v0.8.0).

Validation

• cargo test -p turbovec --doc passes.
• cargo build -p turbovec --examples compiles clean.
• All doc links/images resolve; full public-API doc coverage confirmed.

Reported by @gabrielemidulla (#101); remaining items surfaced in a two-pass doc/comment audit.

🤖 Generated with Claude Code