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/route.ts

@@ -0,0 +1,47 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createFolderSchema } from '@/lib/validators/document-folders';
+import { listTree, createFolder } from '@/lib/services/document-folders.service';
+
+/**
+ * GET /api/v1/document-folders
+ *
+ * Returns the entire folder tree for the caller's port. Roots come
+ * back at the top level with `children` nested. Cached on the client
+ * via TanStack — folders change rarely; the manager mutations
+ * invalidate the query.
+ *
+ * Permission: documents.view (read-only; everyone in the port can
+ * browse the tree even if they can't manage it).
+ */
+export const GET = withAuth(
+  withPermission('documents', 'view', async (_req, ctx) => {
+    try {
+      const tree = await listTree(ctx.portId);
+      return NextResponse.json({ data: tree });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+/**
+ * POST /api/v1/document-folders
+ * Body: { name, parentId }
+ *
+ * Permission: documents.manage_folders.
+ */
+export const POST = withAuth(
+  withPermission('documents', 'manage_folders', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, createFolderSchema);
+      const folder = await createFolder(ctx.portId, ctx.userId, body);
+      return NextResponse.json({ data: folder }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);