BRD-1127: Rewrite CLAUDE.md around V2 (public-safe); add ValueObjects child doc

[SteponasK]

Rewrite CLAUDE.md to durable best-practice per BRD-1127 (durable architecture + gotchas, no ticket/recency trivia, volatile values point to code, scoped child docs in code dirs; v1 treated as deprecated).

Jira: https://invertus.atlassian.net/browse/BRD-1127

Docs-only; no code affected.

[gemini-code-assist]

Code Review

This pull request refactors and updates the repository's documentation in CLAUDE.md to streamline guidance, explicitly deprecate V1, and add sections on price correctness and index alias semantics. It also introduces a new src/V2/ValueObjects/CLAUDE.md file detailing the architecture, conventions, and directory structure of V2 ValueObjects. The review feedback correctly identifies an inconsistency in CLAUDE.md where response-side types are incorrectly described as having builders and jsonSerialize(), and provides a code suggestion to clarify that they are parsed using fromArray() instead.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The description states that all listed ValueObjects in src/V2/ValueObjects/ (including Response) have "a builder, and a jsonSerialize() verified against a fixture." However, as documented in src/V2/ValueObjects/CLAUDE.md, response-side types (Response/) do not use builders or jsonSerialize(), but are instead parsed using fromArray(). To avoid confusion, we should clarify that Response types are parsed from API responses rather than serialized as outgoing payloads.

Suggested change

- **Payloads**: strict immutable readonly ValueObjects in `src/V2/ValueObjects/` (BulkOperations, Index, Normalize, Product, Response, Search, SearchSettings, Synonym, Common), each with constructor validation, a builder, and a `jsonSerialize()` verified against a fixture. See `src/V2/ValueObjects/CLAUDE.md` for the conventions.

- **Payloads**: strict immutable readonly ValueObjects in `src/V2/ValueObjects/` (BulkOperations, Index, Normalize, Product, Search, SearchSettings, Synonym, Common), each with constructor validation, a builder, and a `jsonSerialize()` verified against a fixture. See `src/V2/ValueObjects/CLAUDE.md` for the conventions. Response-side types (`Response/`) are parsed from API responses using `fromArray()`.