chore(coderd): aitasks: add internal-only api doc comments (#20020)

Adds api doc comments calling out experimental status.

Should be merged alongside https://github.com/coder/coder/pull/20019

coderd/aitasks.go

@@ -82,8 +82,18 @@ func (api *API) aiTasksPrompts(rw http.ResponseWriter, r *http.Request) {
 	})
 }
 
-// This endpoint is experimental and not guaranteed to be stable, so we're not
-// generating public-facing documentation for it.
+// @Summary Create a new AI task
+// @Description: EXPERIMENTAL: this endpoint is experimental and not guaranteed to be stable.
+// @ID create-task
+// @Security CoderSessionToken
+// @Tags Experimental
+// @Param user path string true "Username, user ID, or 'me' for the authenticated user"
+// @Param request body codersdk.CreateTaskRequest true "Create task request"
+// @Success 201 {object} codersdk.Task
+// @Router /api/experimental/tasks/{user} [post]
+//
+// EXPERIMENTAL: This endpoint is experimental and not guaranteed to be stable.
+// This endpoint creates a new task for the given user.
 func (api *API) tasksCreate(rw http.ResponseWriter, r *http.Request) {
 	var (
 		ctx     = r.Context()
@@ -316,6 +326,19 @@ type tasksListResponse struct {
 	Count int             `json:"count"`
 }
 
+// @Summary List AI tasks
+// @Description: EXPERIMENTAL: this endpoint is experimental and not guaranteed to be stable.
+// @ID list-tasks
+// @Security CoderSessionToken
+// @Tags Experimental
+// @Param q query string false "Search query for filtering tasks"
+// @Param after_id query string false "Return tasks after this ID for pagination"
+// @Param limit query int false "Maximum number of tasks to return" minimum(1) maximum(100) default(25)
+// @Param offset query int false "Offset for pagination" minimum(0) default(0)
+// @Success 200 {object} coderd.tasksListResponse
+// @Router /api/experimental/tasks [get]
+//
+// EXPERIMENTAL: This endpoint is experimental and not guaranteed to be stable.
 // tasksList is an experimental endpoint to list AI tasks by mapping
 // workspaces to a task-shaped response.
 func (api *API) tasksList(rw http.ResponseWriter, r *http.Request) {
@@ -419,6 +442,17 @@ func (api *API) tasksList(rw http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// @Summary Get AI task by ID
+// @Description: EXPERIMENTAL: this endpoint is experimental and not guaranteed to be stable.
+// @ID get-task
+// @Security CoderSessionToken
+// @Tags Experimental
+// @Param user path string true "Username, user ID, or 'me' for the authenticated user"
+// @Param id path string true "Task ID" format(uuid)
+// @Success 200 {object} codersdk.Task
+// @Router /api/experimental/tasks/{user}/{id} [get]
+//
+// EXPERIMENTAL: This endpoint is experimental and not guaranteed to be stable.
 // taskGet is an experimental endpoint to fetch a single AI task by ID
 // (workspace ID). It returns a synthesized task response including
 // prompt and status.
@@ -525,6 +559,17 @@ func (api *API) taskGet(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, tasks[0])
 }
 
+// @Summary Delete AI task by ID
+// @Description: EXPERIMENTAL: this endpoint is experimental and not guaranteed to be stable.
+// @ID delete-task
+// @Security CoderSessionToken
+// @Tags Experimental
+// @Param user path string true "Username, user ID, or 'me' for the authenticated user"
+// @Param id path string true "Task ID" format(uuid)
+// @Success 202 "Task deletion initiated"
+// @Router /api/experimental/tasks/{user}/{id} [delete]
+//
+// EXPERIMENTAL: This endpoint is experimental and not guaranteed to be stable.
 // taskDelete is an experimental endpoint to delete a task by ID (workspace ID).
 // It creates a delete workspace build and returns 202 Accepted if the build was
 // created.
@@ -600,6 +645,18 @@ func (api *API) taskDelete(rw http.ResponseWriter, r *http.Request) {
 	rw.WriteHeader(http.StatusAccepted)
 }
 
+// @Summary Send input to AI task
+// @Description: EXPERIMENTAL: this endpoint is experimental and not guaranteed to be stable.
+// @ID send-task-input
+// @Security CoderSessionToken
+// @Tags Experimental
+// @Param user path string true "Username, user ID, or 'me' for the authenticated user"
+// @Param id path string true "Task ID" format(uuid)
+// @Param request body codersdk.TaskSendRequest true "Task input request"
+// @Success 204 "Input sent successfully"
+// @Router /api/experimental/tasks/{user}/{id}/send [post]
+//
+// EXPERIMENTAL: This endpoint is experimental and not guaranteed to be stable.
 // taskSend submits task input to the tasks sidebar app by dialing the agent
 // directly over the tailnet. We enforce ApplicationConnect RBAC on the
 // workspace and validate the sidebar app health.
@@ -670,6 +727,19 @@ func (api *API) taskSend(rw http.ResponseWriter, r *http.Request) {
 	rw.WriteHeader(http.StatusNoContent)
 }
 
+// @Summary Get AI task logs
+// @Description: EXPERIMENTAL: this endpoint is experimental and not guaranteed to be stable.
+// @ID get-task-logs
+// @Security CoderSessionToken
+// @Tags Experimental
+// @Param user path string true "Username, user ID, or 'me' for the authenticated user"
+// @Param id path string true "Task ID" format(uuid)
+// @Success 200 {object} codersdk.TaskLogsResponse
+// @Router /api/experimental/tasks/{user}/{id}/logs [get]
+//
+// EXPERIMENTAL: This endpoint is experimental and not guaranteed to be stable.
+// taskLogs reads task output by dialing the agent directly over the tailnet.
+// We enforce ApplicationConnect RBAC on the workspace and validate the sidebar app health.
 func (api *API) taskLogs(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()