hive-c0re: annotate remaining dashboard routes with utoipa

hive-c0re/src/dashboard/state_files.rs

@@ -11,11 +11,12 @@ use std::path::Path;
 
 use axum::response::{IntoResponse, Response};
 use serde::Deserialize;
+use utoipa::IntoParams;
 
 use super::error_response;
 use crate::paths::{AGENTS_ROOT, SHARED_ROOT};
 
-#[derive(Deserialize)]
+#[derive(Deserialize, IntoParams)]
 pub(super) struct StateFileQuery {
     path: String,
 }
@@ -163,6 +164,20 @@ pub fn scan_validated_paths(body: &str) -> Vec<String> {
     out
 }
 
+/// `GET /api/state-file?path=…` — serve an allow-listed per-agent
+/// `state/` or `shared/` file. Raster images get their real
+/// content-type; everything else is served as (possibly truncated)
+/// text.
+#[utoipa::path(
+    get,
+    path = "/api/state-file",
+    params(StateFileQuery),
+    responses(
+        (status = 200, description = "file contents (text, truncated at 1 MiB) or image bytes"),
+        (status = 500, description = "path outside the allow-list, not a regular file, or read failed"),
+    ),
+    tag = "state_files"
+)]
 pub(super) async fn get_state_file(
     axum::extract::Query(q): axum::extract::Query<StateFileQuery>,
 ) -> Response {