P4-W5: Compatibility pass — verify wallet API, reorganize docs, add surface tests

[user1303836]

Summary

Phase 4, Work Packet 5: Compatibility pass ensuring wallet-focused API paths still function after Phase 3–4 changes, with documentation reorganized to prefer the dataset-centric API as the forward path.

• README.md: Reorganized API reference into three subsections (Ingestion & Job Control, Wallet-Scoped Stable, Dataset Preferred) with API philosophy guidance. Documented 5 previously unlisted target/network endpoints.
• api/src/main.rs: Added 30 compatibility tests verifying all wallet and dataset endpoints are routed, return expected response shapes, and share authentication.

Validation

Check	Result
cargo fmt --all --check	✅ Pass
cargo clippy --workspace --all-targets -- -D warnings	✅ Pass
cargo test --workspace	✅ 810 tests, 0 failures
All 27 API endpoints in README match routes in api/src/main.rs	✅ Verified
README.md ↔ CLAUDE.md API surface sync	✅ In sync
30 compatibility tests cover routing, auth, response shapes	✅ Pass

Note: CLAUDE.md is gitignored and not tracked in the repository, so it does not appear in the PR diff. The on-disk copy was updated to match the README reorganization.

Test plan

• Review README.md API subsection reorganization and philosophy guidance
• Review 30 new compatibility tests in api/src/main.rs
• Confirm all wallet-scoped endpoints remain unchanged and accessible
• Confirm dataset-centric endpoints are correctly documented
• Verify CI passes (fmt, clippy, test, build)

🤖 Generated with Claude Code

[user1303836]

Remote Review — P4-W5: Compatibility pass

Verdict: Review pass is clear. No blocking issues found.

What was checked

Area	Result
README ↔ route registrations	✅ All 27 endpoints in README match api/src/main.rs routes
CLAUDE.md ↔ README sync	✅ Endpoint lists and section structure are in sync
Forward-path clarity	✅ "Which API Should I Use?" section and (Stable)/(Preferred) headers make guidance unambiguous
No wallet endpoint removal	✅ Diff only adds tests + reorganizes docs; no wallet handler code modified
No wallet-only assumptions	✅ New test code is target-type agnostic
Test coverage	✅ 30 compatibility tests covering routing, auth, and response shapes
CI (so far)	✅ Formatting, ✅ Clippy — Tests and Build (release) still in progress

Non-blocking observations

1. Two endpoints lack explicit routing+auth test coverage: POST /v1/stream/:stream_id/stop and GET /v1/jobs/:job_id are documented in the README and registered in the router but have no dedicated compat_* routing or auth test. They were not modified by this PR so this is low-risk, but adding them would make the compatibility suite truly exhaustive.

2. Stream/job-poll endpoints missing from auth tests: compat_ingestion_endpoints_require_auth covers ingest, ingest/batch, and normalize but skips stream/start, stream/:id/stop, streams, and jobs/:job_id. Again non-blocking since these routes are unchanged.

3. CI still in progress: Tests and Build (release) jobs are pending. Merge should wait for all four checks to pass.

From the PR-comment review perspective, this packet is ready to merge once CI completes green.