OpenAPI spec at /api/docs with a Scalar viewer, opt-in via FEAT_API_DOCS

src/routes/api/self-update/+server.ts

@@ -237,6 +237,16 @@ function buildNetworkEnvVars(inspectData: any): string[] {
  * SSE stream endpoint for self-update.
  * Pulls image, creates new container, then launches minimal sidecar.
  */
+/**
+ * @openapi
+ * summary: Pull a new Dockhand image and hand off to an updater sidecar that replaces this running container
+ * body: {newImage:string!}
+ * body-example: {"newImage":"fnsys/dockhand:v1.0.40"}
+ * resp-200: text/event-stream SSE response (steps: pulling_image, building_config, pulling_updater, creating_container, launching_updater, then a "launched"/"error" event) — or, with "Accept: application/json", the final event as plain JSON
+ * resp-400: newImage missing, not running in Docker, or the Docker socket is read-only
+ * resp-403: Admin access required
+ * resp-500: Failed to inspect own container or determine its name before starting the update
+ */
 export const POST: RequestHandler = async ({ request, cookies }) => {
 	const auth = await authorize(cookies);
 	if (auth.authEnabled && !auth.isAdmin) {

src/routes/api/self-update/check/+server.ts

@@ -86,6 +86,12 @@ async function localDockerFetch(path: string, options: RequestInit = {}): Promis
  * Uses localDockerFetch exclusively to avoid environment routing issues
  * when the image comes from a private registry.
  */
+/**
+ * @openapi
+ * summary: Check whether a newer Dockhand image is available (version-tag compare via GitHub changelog, or registry-digest compare for mutable tags like :latest)
+ * resp-200: {updateAvailable:boolean!, currentImage:string, newImage:string, latestVersion:string, currentDigest:string, newDigest:string, containerName:string, isComposeManaged:boolean, isLocalImage:boolean, error:string} (also used for "not running in Docker" / inspection / changelog / registry failures — reported as updateAvailable:false + error, not an HTTP error status)
+ * resp-403: Admin access required
+ */
 export const GET: RequestHandler = async ({ cookies }) => {
 	const auth = await authorize(cookies);
 	if (auth.authEnabled && !auth.isAdmin) {

src/routes/api/self-update/progress/+server.ts

@@ -61,6 +61,15 @@ function stripDockerLogHeaders(raw: Uint8Array): string {
 /**
  * Poll updater container logs and status for progress tracking.
  */
+/**
+ * @openapi
+ * summary: Poll the self-update sidecar container's logs and exit state for progress tracking
+ * query: id:string! Updater container id (from POST /api/self-update)
+ * resp-200: {logs:string!, status:string!, exitCode:integer}
+ * resp-400: Container ID is required
+ * resp-403: Admin access required
+ * resp-500: Failed to inspect the updater container, or failed to fetch its progress
+ */
 export const GET: RequestHandler = async ({ url, cookies }) => {
 	const auth = await authorize(cookies);
 	if (auth.authEnabled && !auth.isAdmin) {