feat: API sync and documentation audit - 100% endpoint coverage (#94)

Code quality:
- Add Zod validation to 14 route handlers that used raw JSON.parse
  (favicon, find-duplicates, barcode-read, upscale, blur-faces,
  erase-object, colorize, enhance-faces, red-eye-removal,
  remove-background/effects, auth, api-keys, roles, teams,
  analytics, settings, user-files)
- Standardize error responses to safeParse + formatZodErrors pattern
- Replace unsafe `as` type casts with schema validation

OpenAPI spec (89 -> 115 operations):
- Add 14 missing tool endpoints (adjust-colors, sharpening,
  optimize-for-web, image-enhancement, noise-removal, red-eye-removal,
  restore-photo, passport-photo, colorize, enhance-faces, image-to-base64)
- Add 12 missing non-tool endpoints (analytics, features, audit-log,
  roles, admin-health)
- Add typed error schemas for 401/403/409 responses
- Add descriptions to all path parameters
- Bump version from 0.9.0 to 1.15.9

Documentation:
- Fix 8 incorrect env var defaults in configuration guide
- Add 15 undocumented env vars to configuration guide
- Fix tool ID mismatch (color-adjustments -> adjust-colors)
- Add 4 new API sections (Roles, Audit Log, Analytics, Features)
- Add image-enhancement to AI engine reference
- Update AI tool count from 13 to 14 across all docs
- Add 6 missing doc links to README

apps/api/src/routes/tools/upscale.ts

@@ -7,6 +7,7 @@ import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import sharp from "sharp";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
@@ -15,6 +16,15 @@ import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
 import { registerToolProcessFn } from "../tool-factory.js";
 
+const settingsSchema = z.object({
+  scale: z.union([z.number(), z.string()]).transform(Number).default(2),
+  model: z.string().default("auto"),
+  faceEnhance: z.boolean().default(false),
+  denoise: z.union([z.number(), z.string()]).transform(Number).default(0),
+  format: z.string().default("png"),
+  quality: z.union([z.number(), z.string()]).transform(Number).default(95),
+});
+
 /**
  * AI image upscaling route.
  * Uses Real-ESRGAN when available, falls back to Lanczos.
@@ -71,13 +81,26 @@ export function registerUpscale(app: FastifyInstance) {
     }
 
     try {
-      const settings = settingsRaw ? JSON.parse(settingsRaw) : {};
-      const scale = Number(settings.scale) || 2;
-      const model = settings.model || "auto";
-      const faceEnhance = Boolean(settings.faceEnhance);
-      const denoise = Number(settings.denoise) || 0;
-      const format = settings.format || "png";
-      const outputQuality = Number(settings.quality) || 95;
+      let settings: z.infer<typeof settingsSchema>;
+      try {
+        const parsed = settingsRaw ? JSON.parse(settingsRaw) : {};
+        const result = settingsSchema.safeParse(parsed);
+        if (!result.success) {
+          return reply
+            .status(400)
+            .send({ error: "Invalid settings", details: formatZodErrors(result.error.issues) });
+        }
+        settings = result.data;
+      } catch {
+        return reply.status(400).send({ error: "Settings must be valid JSON" });
+      }
+
+      const scale = settings.scale;
+      const model = settings.model;
+      const faceEnhance = settings.faceEnhance;
+      const denoise = settings.denoise;
+      const format = settings.format;
+      const outputQuality = settings.quality;
       request.log.info(
         { toolId: "upscale", imageSize: fileBuffer.length, scale, model, format },
         "Starting upscale",