chore: Address comments

Author: arne-aignx

CLI_REFERENCE.md

@@ -145,6 +145,7 @@ $ aignostics application [OPTIONS] COMMAND [ARGS]...
 * `list`: List available applications.
 * `dump-schemata`: Output the input schema of the application...
 * `describe`: Describe application.
+* `version`: Inspect application versions and their release documents.
 * `run`: List, submit and manage application runs
 
 ### `aignostics application list`
@@ -204,6 +205,106 @@ $ aignostics application describe [OPTIONS] APPLICATION_ID
 * `--format TEXT`: Output format: 'text' (default) or 'json'  [default: text]
 * `--help`: Show this message and exit.
 
+### `aignostics application version`
+
+Inspect application versions and their release documents.
+
+**Usage**:
+
+```console
+$ aignostics application version [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `document`: List, describe, and download public release documents attached to an application version.
+
+#### `aignostics application version document`
+
+List, describe, and download public release documents attached to an application version (e.g. output schemas, model manuals).
+
+**Usage**:
+
+```console
+$ aignostics application version document [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `list`: List public release documents attached to an application version.
+* `describe`: Show metadata for a single public release document.
+* `download`: Download a public release document to a local path.
+
+##### `aignostics application version document list`
+
+List public release documents attached to an application version.
+
+**Usage**:
+
+```console
+$ aignostics application version document list [OPTIONS] APPLICATION_ID
+```
+
+**Arguments**:
+
+* `APPLICATION_ID`: Id of application to list release documents for.  [required]
+
+**Options**:
+
+* `--application-version TEXT`: Version of the application. If not provided, the latest version will be used.
+* `--format TEXT`: Output format: 'text' (default) or 'json'  [default: text]
+* `--help`: Show this message and exit.
+
+##### `aignostics application version document describe`
+
+Show metadata for a single public release document.
+
+**Usage**:
+
+```console
+$ aignostics application version document describe [OPTIONS] APPLICATION_ID DOCUMENT_NAME
+```
+
+**Arguments**:
+
+* `APPLICATION_ID`: Id of application to describe release documents for.  [required]
+* `DOCUMENT_NAME`: Document filename (e.g. 'output_description.pdf').  [required]
+
+**Options**:
+
+* `--application-version TEXT`: Version of the application. If not provided, the latest version will be used.
+* `--format TEXT`: Output format: 'text' (default) or 'json'  [default: text]
+* `--help`: Show this message and exit.
+
+##### `aignostics application version document download`
+
+Download a public release document to a local path.
+
+**Usage**:
+
+```console
+$ aignostics application version document download [OPTIONS] APPLICATION_ID DOCUMENT_NAME
+```
+
+**Arguments**:
+
+* `APPLICATION_ID`: Id of application to download release documents for.  [required]
+* `DOCUMENT_NAME`: Document filename (e.g. 'output_description.pdf').  [required]
+
+**Options**:
+
+* `--application-version TEXT`: Version of the application. If not provided, the latest version will be used.
+* `--output PATH`: Destination directory. Defaults to the current working directory.  [default: (<current-working-directory>)]
+* `--help`: Show this message and exit.
+
 ### `aignostics application run`
 
 List, submit and manage application runs
@@ -579,9 +680,9 @@ $ aignostics application run result download [OPTIONS] RUN_ID [DESTINATION_DIREC
 * `--create-subdirectory-for-run / --no-create-subdirectory-for-run`: Create a subdirectory for the results of the run in the destination directory  [default: create-subdirectory-for-run]
 * `--create-subdirectory-per-item / --no-create-subdirectory-per-item`: Create a subdirectory per item in the destination directory  [default: create-subdirectory-per-item]
 * `--wait-for-completion / --no-wait-for-completion`: Wait for run completion and download results incrementally  [default: wait-for-completion]
-* `--qupath-project / --no-qupath-project`: Create a QuPath project referencing input slides and results. 
-The QuPath project will be created in a subfolder of the destination directory. 
-This option requires the QuPath extension for Launchpad: start the Launchpad with `uvx --with "aignostics" aignostics ...` 
+* `--qupath-project / --no-qupath-project`: Create a QuPath project referencing input slides and results.
+The QuPath project will be created in a subfolder of the destination directory.
+This option requires the QuPath extension for Launchpad: start the Launchpad with `uvx --with "aignostics" aignostics ...`
 This options requires installation of the QuPath application: Run uvx --with "aignostics" aignostics qupath install  [default: no-qupath-project]
 * `--help`: Show this message and exit.
 

specifications/SPEC_PLATFORM_SERVICE.md

@@ -349,7 +349,7 @@ class Documents:
         by ``requests`` and is therefore not forwarded to the storage backend.
         Returns the absolute path to the written file.
 
-        ``destination`` must be an existing directory; the file is written as
+        ``destination`` must be a directory; the file is written as
         ``{destination}/{document_name}``. The requested document name is the
         canonical filename and is used regardless of any ``Content-Disposition``
         served by the storage backend.

src/aignostics/platform/resources/applications.py

@@ -429,11 +429,7 @@ def download_to_path(self, document_name: str, destination: Path | str) -> Path:
         If ``destination`` is a directory, the file is written as
         ``{destination}/{document_name}``; the requested document name is the canonical
         filename and is used regardless of any ``Content-Disposition`` served by the
-        storage backend. If ``destination`` is a file path, the file is written there
-        verbatim. Parent directories are created if they do not yet exist.
-
-        Document downloads do not carry a CRC32C checksum (unlike run artifacts);
-        integrity is bounded by HTTPS transport and the signed-URL lifetime.
+        storage backend. Parent directories are created if they do not yet exist.
 
         Args:
             document_name (str): The document filename.
@@ -605,6 +601,8 @@ def _stream_document(  # noqa: PLR0913, PLR0917
             raise ServiceException(status=HTTPStatus.SERVICE_UNAVAILABLE.value, reason="Request timed out") from e
         except requests.ConnectionError as e:
             raise ServiceException(status=HTTPStatus.SERVICE_UNAVAILABLE.value, reason="Connection failed") from e
+        except requests.RequestException as e:
+            raise ServiceException(status=HTTPStatus.SERVICE_UNAVAILABLE.value, reason="Request failed") from e
 
     def read_content(self, document_name: str) -> bytes:
         """Fetch a release document's raw content into memory.

tests/aignostics/platform/resources/applications_test.py

@@ -344,7 +344,7 @@ def test_documents_download_to_path_rejects_non_directory(documents: Documents,
     file_path = tmp_path / "some_file.pdf"
     file_path.write_bytes(b"content")
 
-    with pytest.raises(ValueError, match="must be a directory"):
+    with pytest.raises(ValueError, match="is an existing file"):
         documents.download_to_path(DOCUMENT_OUTPUT_DESCRIPTION_PDF, file_path)