fix(sdk): propagate missing daemon error codes to all SDKs and document list() response shapes

[MDzaja]

What

Two related agent-experience fixes across all five SDKs.

1. Error-code parity (behavioural fix)

INVALID_FILE_PATH and FILE_READ_FAILED were added to the TypeScript SDK in #146 but
never propagated, so Python, Ruby, Go and Java silently degraded to generic
status-based errors for codes the daemon really emits.

Verified against production:

Trigger	Wire code	Before (Python)	After
download a directory	INVALID_FILE_PATH (400)	DaytonaBadRequestError	DaytonaInvalidFilePathError
NUL-byte path	FILE_READ_FAILED (500)	DaytonaInternalServerError	DaytonaFileReadFailedError

Parents match TypeScript (400 → bad request, 500 → internal server error). Go uses
sentinels + errors.Is, consistent with its existing design. Purely additive — no
existing class, mapping or signature changed.

2. list() response shapes (docs)

snapshot.list() returns a wrapper ({ items: [...] }), not an array, but every example
read as though it were — so .map() on the result throws. Added a "List method return
shapes" table to each SDK README and made the wrapper explicit in the doc-comments.

Also fixed 22 Go doc examples that referenced non-existent accessors
(client.Snapshots / client.Volumes; the real fields are singular client.Snapshot /
client.Volume) — these could never have compiled. Caught by executing the examples
rather than reading them.

Plus: sdk-ruby now documents the existing >= 3.2 requirement from its gemspec, and
sdk-java's README uses a self-updating Maven Central badge instead of a hardcoded
version.

---

Summary by cubic

Propagates missing daemon filesystem error codes to all SDKs and clarifies list() return shapes with concise examples and corrected Go accessors.

• Bug Fixes

  • Error-code parity: added INVALID_FILE_PATH (400) and FILE_READ_FAILED (500) to sdk-python, sdk-ruby, sdk-go, and sdk-java; Go exposes ErrInvalidFilePath/ErrFileReadFailed; Java ExceptionMapper wired; tests added across Go/Java/Python/Ruby.

• Docs

  • Added “List method return shapes” to sdk-typescript, sdk-python, sdk-ruby, sdk-go, and sdk-java READMEs/docs; examples use .items/getters, destructure results in TypeScript, and print page/total counts; Go examples fixed to client.Snapshot/client.Volume.
  • sdk-ruby README notes Ruby >= 3.2; sdk-java README includes a Maven Central badge.

^{Written for commit c4a47bc. Summary will update on new commits.}

[vidoc-agent]

Vidoc security review

Tip

Good to merge — no security issues found. Reviewed 45 changed files.

💬 Have questions? Tag @vidoc in a comment and I'll answer.

[cubic-dev-ai]

Review completed against the latest diff

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 14 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>