feat(documents): folder CRUD API routes

GET /api/v1/document-folders → full tree (documents.view).
POST /api/v1/document-folders → create (documents.manage_folders).
PATCH /api/v1/document-folders/[id] → rename OR move (union schema —
refuses both in one body so audit logs stay one-op-per-call).
DELETE /api/v1/document-folders/[id] → soft-rescue delete; returns 204.

PATCH passes ctx.userId through to the service-level audit-log
emitters (renameFolder + moveFolder gained userId in Task 4 fixes).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/api/v1/document-folders/[id]/route.ts

@@ -0,0 +1,55 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+import {
+  renameFolderSchema,
+  moveFolderSchema,
+} from '@/lib/validators/document-folders';
+import {
+  renameFolder,
+  moveFolder,
+  deleteFolderSoftRescue,
+} from '@/lib/services/document-folders.service';
+
+/**
+ * PATCH supports either { name } (rename) or { parentId } (move).
+ * Refuses both in the same body — keeps the audit log clean
+ * (one operation per call) and prevents the rep from accidentally
+ * doing two unrelated changes in one click.
+ */
+const patchBodySchema = z.union([renameFolderSchema, moveFolderSchema]);
+
+export const PATCH = withAuth(
+  withPermission('documents', 'manage_folders', async (req, ctx, params) => {
+    try {
+      const folderId = params.id;
+      if (!folderId) throw new NotFoundError('Folder');
+      const body = await parseBody(req, patchBodySchema);
+      let updated;
+      if ('name' in body) {
+        updated = await renameFolder(ctx.portId, folderId, body.name, ctx.userId);
+      } else {
+        updated = await moveFolder(ctx.portId, folderId, body.parentId, ctx.userId);
+      }
+      return NextResponse.json({ data: updated });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('documents', 'manage_folders', async (_req, ctx, params) => {
+    try {
+      const folderId = params.id;
+      if (!folderId) throw new NotFoundError('Folder');
+      await deleteFolderSoftRescue(ctx.portId, folderId, ctx.userId);
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);