docs(brain): add JSDoc documentation

apps/api/src/brain/brain.controller.ts

@@ -12,11 +12,25 @@ import { AuthGuard } from "../auth/guards/auth.guard";
 import { WorkspaceGuard, PermissionGuard } from "../common/guards";
 import { Workspace, Permission, RequirePermission } from "../common/decorators";
 
+/**
+ * @description Controller for AI/brain operations on workspace data.
+ * Provides endpoints for querying, searching, and getting context across
+ * tasks, events, and projects within a workspace.
+ */
 @Controller("brain")
 @UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
 export class BrainController {
   constructor(private readonly brainService: BrainService) {}
 
+  /**
+   * @description Query workspace entities with flexible filtering options.
+   * Allows filtering tasks, events, and projects by various criteria.
+   * @param queryDto - Query parameters including entity types, filters, and search term
+   * @param workspaceId - The workspace ID (injected from request context)
+   * @returns Filtered tasks, events, and projects with metadata
+   * @throws UnauthorizedException if user lacks workspace access
+   * @throws ForbiddenException if user lacks required permissions
+   */
   @Post("query")
   @RequirePermission(Permission.WORKSPACE_ANY)
   async query(
@@ -26,6 +40,16 @@ export class BrainController {
     return this.brainService.query({ ...queryDto, workspaceId });
   }
 
+  /**
+   * @description Get current workspace context for AI operations.
+   * Returns a summary of active tasks, overdue items, upcoming events, and projects.
+   * @param contextDto - Context options specifying which entities to include
+   * @param workspaceId - The workspace ID (injected from request context)
+   * @returns Workspace context with summary counts and optional detailed entity lists
+   * @throws UnauthorizedException if user lacks workspace access
+   * @throws ForbiddenException if user lacks required permissions
+   * @throws NotFoundException if workspace does not exist
+   */
   @Get("context")
   @RequirePermission(Permission.WORKSPACE_ANY)
   async getContext(
@@ -35,6 +59,16 @@ export class BrainController {
     return this.brainService.getContext({ ...contextDto, workspaceId });
   }
 
+  /**
+   * @description Search across all workspace entities by text.
+   * Performs case-insensitive search on titles, descriptions, and locations.
+   * @param searchTerm - Text to search for across all entity types
+   * @param limit - Maximum number of results per entity type (max: 100, default: 20)
+   * @param workspaceId - The workspace ID (injected from request context)
+   * @returns Matching tasks, events, and projects with metadata
+   * @throws UnauthorizedException if user lacks workspace access
+   * @throws ForbiddenException if user lacks required permissions
+   */
   @Get("search")
   @RequirePermission(Permission.WORKSPACE_ANY)
   async search(