docs(claudemd): document full set of v2-pinned DSM APIs

[cmeans-claude-dev]

Summary

Closes #42.

The "Version pinning" bullet under ## Key Conventions → DSM API Client previously named only CopyMove, Delete, and Search as v2-pinned. Audit of src/ (grep -rn "max_version=2\|min(.*max_version, 2)") found two more pins the bullet didn't mention:

• SYNO.FileStation.Upload (src/mcp_synology/core/client.py:354, inside upload_file) — Upload is a special-case multipart POST not routed through request(), so its v2 pin lives in the upload code path with min(info.max_version, 2). v3 advertises a JSON body the multipart code can't speak.
• SYNO.FileStation.List getinfo (src/mcp_synology/modules/filestation/metadata.py:80) — added by PR fix(filestation): per-path serial for multi-path getinfo and delete #77 to dodge the v3 multipath quirk that surfaced as v0.5.0 regression: delete_files and get_file_info silently mishandle multi-path arrays #68.

The bullet now lists all five APIs with file pointers and the rationale: "removing any of these pins reintroduces silent failures on DSM 7.x — the v3 request format DSM advertises is metadata, not a mandate." A future refactor can't innocently strip a pin and rediscover the bug.

Audit verification

$ grep -rn "max_version=2\|min(.*max_version, 2)" src/
src/mcp_synology/modules/filestation/search.py:78:    search_version = min(2, client.negotiate_version("SYNO.FileStation.Search", max_version=2))
src/mcp_synology/modules/filestation/metadata.py:80:    getinfo_version = min(2, client.negotiate_version("SYNO.FileStation.List", max_version=2))
src/mcp_synology/modules/filestation/operations.py:309:    copymove_version = min(2, client.negotiate_version("SYNO.FileStation.CopyMove", max_version=2))
src/mcp_synology/modules/filestation/operations.py:467:    delete_version = min(2, client.negotiate_version("SYNO.FileStation.Delete", max_version=2))
src/mcp_synology/core/client.py:354:        resolved_version = version if version is not None else min(info.max_version, 2)

5 pins → 5 mentions in the convention. No undocumented pins remain.

Files changed

• CLAUDE.md — single bullet rewritten under ## Key Conventions → DSM API Client
• CHANGELOG.md — ### Changed entry under ## Unreleased

Test plan

• CI green
• grep -c "Upload\|List getinfo" CLAUDE.md returns ≥1
• No code change, so functional smoke not needed

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

QA Round 1 — PASS (no findings)

Doc-only PR on head 337ae8f. 2 files / +3 / -1.

Verified

Audit claim: Re-ran grep -rn "max_version=2\|min(.*max_version, 2)" src/ independently — found exactly the 5 pins the PR body lists, in the same locations:

API	File	Line
CopyMove	modules/filestation/operations.py	309
Delete	modules/filestation/operations.py	467
Search	modules/filestation/search.py	78
List getinfo	modules/filestation/metadata.py	80
Upload	core/client.py	354

I also ran a broader grep -rnE "version=2|min\(2," to catch alternative patterns the PR's regex might miss. One additional hit: src/mcp_synology/modules/__init__.py:120 result = await handler(negotiated_version=2, **kwargs). That's illustrative docstring example code inside the VersionedHandler class, not an actual v2 pin — false positive. PR's 5-pin enumeration is exhaustive.

Updated bullet: Now names all five APIs, each with a file pointer; explains why Upload's pin lives in core/client.py (multipart POST not routed through request()); credits #77 for the List getinfo pin and ties it to #68; and closes with the rationale ("removing any of these pins reintroduces silent failures on DSM 7.x — the v3 request format DSM advertises is metadata, not a mandate") so a future refactor can't innocently strip a pin.

CHANGELOG: New ### Changed entry under ## Unreleased, slotted above the existing #88 entry. KaC ordering preserved (### Added block above ### Changed block).

Test plan

• CI green — 12/12 required incl. vdsm integration tests SUCCESS on this exact head.
• grep -c "Upload\|List getinfo" CLAUDE.md returned 1 (≥1 satisfied).
• No code change → no functional smoke needed.

Disposition

Ready for QA Signoff applied as the final act. With this in, #51's LOW/docs queue drops from 4 to 3 (#43, #45, #46 remain).

[cmeans]

Applying Ready for QA Signoff — clean doc-only PR. Independently re-ran the audit grep + a broader pattern scan; PR's 5-pin enumeration (CopyMove, Delete, Search, List getinfo, Upload) is exhaustive. Updated CLAUDE.md bullet correctly names all five with file pointers and the rationale. CHANGELOG ## Unreleased ### Changed entry slotted above #88's. CI 12/12 green incl. vdsm. All 3 test-plan checkboxes flipped. Closes #42 — #51's LOW/docs queue drops to #43, #45, #46.

[cmeans]

LGTM