@vibescope/mcp-server 0.2.4 → 0.2.5

package/src/api-client.ts

@@ -1,2499 +1,2499 @@
-/**
- * Vibescope API Client
- *
- * HTTP client for communicating with the Vibescope API.
- * All database operations are handled server-side through these endpoints.
- */
-
-const DEFAULT_API_URL = 'https://vibescope.dev';
-
-interface ApiClientConfig {
-	apiKey: string;
-	baseUrl?: string;
-}
-
-interface ApiResponse<T> {
-	ok: boolean;
-	status: number;
-	data?: T;
-	error?: string;
-}
-
-export class VibescopeApiClient {
-	private apiKey: string;
-	private baseUrl: string;
-
-	constructor(config: ApiClientConfig) {
-		this.apiKey = config.apiKey;
-		this.baseUrl = config.baseUrl || process.env.VIBESCOPE_API_URL || DEFAULT_API_URL;
-	}
-
-	private async request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>> {
-		const url = `${this.baseUrl}${path}`;
-
-		try {
-			const response = await fetch(url, {
-				method,
-				headers: {
-					'Content-Type': 'application/json',
-					'X-API-Key': this.apiKey
-				},
-				body: body ? JSON.stringify(body) : undefined
-			});
-
-			const data = await response.json();
-
-			if (!response.ok) {
-				return {
-					ok: false,
-					status: response.status,
-					error: data.error || `HTTP ${response.status}`,
-					data // Include full response data for additional error context
-				};
-			}
-
-			return {
-				ok: true,
-				status: response.status,
-				data
-			};
-		} catch (err) {
-			return {
-				ok: false,
-				status: 0,
-				error: err instanceof Error ? err.message : 'Network error'
-			};
-		}
-	}
-
-	// Auth endpoints
-	async validateAuth(): Promise<ApiResponse<{
-		valid: boolean;
-		user_id: string;
-		api_key_id: string;
-		key_name: string;
-	}>> {
-		return this.request('POST', '/api/mcp/auth/validate', {
-			api_key: this.apiKey
-		});
-	}
-
-	// Session endpoints
-	async startSession(params: {
-		project_id?: string;
-		git_url?: string;
-		mode?: 'lite' | 'full';
-		model?: 'opus' | 'sonnet' | 'haiku';
-		role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
-		hostname?: string; // Machine hostname for worktree tracking
-		agent_type?: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'; // Agent type for onboarding
-	}): Promise<ApiResponse<{
-		session_started: boolean;
-		session_id?: string;
-		persona?: string;
-		role?: string;
-		project?: {
-			id: string;
-			name: string;
-			description?: string;
-			goal?: string;
-			status?: string;
-			git_url?: string;
-			agent_instructions?: string;
-			tech_stack?: string[];
-			git_workflow?: string;
-			git_main_branch?: string;
-			git_develop_branch?: string;
-			git_auto_branch?: boolean;
-		};
-		active_tasks?: Array<{
-			id: string;
-			title: string;
-			status: string;
-			priority: number;
-			progress_percentage?: number;
-			estimated_minutes?: number;
-		}>;
-		blockers?: Array<{
-			id: string;
-			description: string;
-			status: string;
-		}>;
-		next_task?: {
-			id: string;
-			title: string;
-			priority: number;
-			estimated_minutes?: number;
-		} | null;
-		pending_requests?: Array<{
-			id: string;
-			request_type: string;
-			message: string;
-			created_at: string;
-		}>;
-		pending_requests_count?: number;
-		URGENT_QUESTIONS?: {
-			count: number;
-			oldest_waiting_minutes: number;
-			action_required: string;
-			requests: Array<{
-				id: string;
-				message: string;
-				waiting_minutes: number;
-			}>;
-		};
-		directive?: string;
-		blockers_count?: number;
-		validation_count?: number;
-		project_not_found?: boolean;
-		message?: string;
-		suggestion?: {
-			action: string;
-			example: string;
-			note: string;
-		};
-		// Agent onboarding - returned when a new agent type connects to an existing project
-		agent_setup?: {
-			agent_type: string;
-			is_new_agent_type: boolean;
-			setup_required: boolean;
-			instructions: string;
-			config_file: string; // e.g., '.gemini/GEMINI.md'
-			template_url?: string;
-			steps: string[];
-		};
-		// Stale worktrees that need cleanup
-		stale_worktrees?: Array<{
-			task_id: string;
-			task_title: string;
-			worktree_path: string;
-			worktree_hostname?: string | null;
-		}>;
-		stale_worktrees_count?: number;
-		cleanup_action?: string;
-		// Validation info for validators
-		awaiting_validation?: Array<{
-			id: string;
-			title?: string;
-		}>;
-		validation_priority?: boolean;
-		next_action?: string;
-		error?: string;
-	}>> {
-		return this.request('POST', '/api/mcp/sessions/start', params);
-	}
-
-	async heartbeat(sessionId: string, options?: {
-		current_worktree_path?: string | null;
-		hostname?: string; // Machine hostname for worktree tracking
-	}): Promise<ApiResponse<{
-		success: boolean;
-		session_id: string;
-		timestamp: string;
-	}>> {
-		return this.request('POST', '/api/mcp/sessions/heartbeat', {
-			session_id: sessionId,
-			...options
-		});
-	}
-
-	async endSession(sessionId: string): Promise<ApiResponse<{
-		success: boolean;
-		ended_session_id?: string;
-		session_summary?: {
-			agent_name: string;
-			tasks_completed_this_session: number;
-			tasks_awaiting_validation: number;
-			tasks_released: number;
-		};
-		reminders?: string[];
-	}>> {
-		return this.request('POST', '/api/mcp/sessions/end', {
-			session_id: sessionId
-		});
-	}
-
-	// Project endpoints
-	async listProjects(): Promise<ApiResponse<{
-		projects: Array<{
-			id: string;
-			name: string;
-			description?: string;
-			status: string;
-			git_url?: string;
-			goal?: string;
-			tech_stack?: string[];
-		}>;
-	}>> {
-		return this.request('GET', '/api/mcp/projects');
-	}
-
-	async createProject(params: {
-		name: string;
-		description?: string;
-		goal?: string;
-		git_url?: string;
-		tech_stack?: string[];
-	}): Promise<ApiResponse<{
-		success: boolean;
-		project: {
-			id: string;
-			name: string;
-		};
-	}>> {
-		return this.request('POST', '/api/mcp/projects', params);
-	}
-
-	async getProject(projectId: string, gitUrl?: string): Promise<ApiResponse<{
-		found: boolean;
-		project?: {
-			id: string;
-			name: string;
-			description?: string;
-			goal?: string;
-			status: string;
-			git_url?: string;
-			agent_instructions?: string;
-			tech_stack?: string[];
-			git_workflow?: string;
-			git_main_branch?: string;
-			git_develop_branch?: string;
-			git_auto_branch?: boolean;
-			git_auto_tag?: boolean;
-			deployment_instructions?: string;
-		};
-		active_tasks?: Array<{
-			id: string;
-			title: string;
-			description?: string;
-			priority: number;
-			status: string;
-			progress_percentage?: number;
-			estimated_minutes?: number;
-		}>;
-		open_blockers?: Array<{
-			id: string;
-			description: string;
-		}>;
-		recent_decisions?: Array<{
-			id: string;
-			title: string;
-			description?: string;
-		}>;
-		message?: string;
-	}>> {
-		const url = gitUrl
-			? `/api/mcp/projects/${projectId}?git_url=${encodeURIComponent(gitUrl)}`
-			: `/api/mcp/projects/${projectId}`;
-		return this.request('GET', url);
-	}
-
-	async updateProject(projectId: string, updates: {
-		name?: string;
-		description?: string;
-		goal?: string;
-		git_url?: string;
-		tech_stack?: string[];
-		status?: string;
-		git_workflow?: string;
-		git_main_branch?: string;
-		git_develop_branch?: string;
-		git_auto_branch?: boolean;
-		git_auto_tag?: boolean;
-		deployment_instructions?: string;
-		agent_instructions?: string;
-		// New project settings columns
-		git_delete_branch_on_merge?: boolean;
-		require_pr_for_validation?: boolean;
-		auto_merge_on_approval?: boolean;
-		validation_required?: boolean;
-		default_task_priority?: number;
-		require_time_estimates?: boolean;
-		fallback_activities_enabled?: boolean;
-		preferred_fallback_activities?: string[];
-	}): Promise<ApiResponse<{
-		success: boolean;
-		project_id: string;
-	}>> {
-		return this.request('PATCH', `/api/mcp/projects/${projectId}`, updates);
-	}
-
-	// Task endpoints
-	async getTasks(projectId: string, params?: {
-		status?: string;
-		limit?: number;
-		offset?: number;
-		include_subtasks?: boolean;
-		search_query?: string;
-		include_metadata?: boolean; // When true, returns all task fields; when false (default), only id/title/priority/status
-	}): Promise<ApiResponse<{
-		tasks: Array<{
-			id: string;
-			title: string;
-			description?: string;
-			priority: number;
-			status: string;
-			progress_percentage?: number;
-			estimated_minutes?: number;
-			started_at?: string;
-			completed_at?: string;
-			parent_task_id?: string;
-		}>;
-		total_count: number;
-		has_more: boolean;
-	}>> {
-		const queryParams = new URLSearchParams();
-		if (params?.status) queryParams.set('status', params.status);
-		if (params?.limit) queryParams.set('limit', params.limit.toString());
-		if (params?.offset) queryParams.set('offset', params.offset.toString());
-		if (params?.include_subtasks) queryParams.set('include_subtasks', 'true');
-		if (params?.search_query) queryParams.set('search_query', params.search_query);
-		if (params?.include_metadata) queryParams.set('include_metadata', 'true');
-
-		const query = queryParams.toString();
-		const url = `/api/mcp/projects/${projectId}/tasks${query ? `?${query}` : ''}`;
-		return this.request('GET', url);
-	}
-
-	async createTask(projectId: string, params: {
-		title: string;
-		description?: string;
-		priority?: number;
-		estimated_minutes?: number;
-		blocking?: boolean;
-		session_id?: string;
-		task_type?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		task_id: string;
-		title: string;
-		blocking?: boolean;
-		message?: string;
-	}>> {
-		return this.request('POST', `/api/mcp/projects/${projectId}/tasks`, params);
-	}
-
-	async getNextTask(projectId: string, sessionId?: string): Promise<ApiResponse<{
-		task?: {
-			id: string;
-			title: string;
-			description?: string;
-			priority: number;
-			estimated_minutes?: number;
-			blocking?: boolean;
-		} | null;
-		blocking_task?: boolean;
-		deployment_blocks_tasks?: boolean;
-		deployment?: {
-			id: string;
-			status: string;
-			env: string;
-		};
-		awaiting_validation?: Array<{
-			id: string;
-			title: string;
-		}>;
-		validation_priority?: string;
-		all_claimed?: boolean;
-		is_subtask?: boolean;
-		suggested_activity?: string;
-		directive?: string;
-		message?: string;
-		action?: string;
-	}>> {
-		const url = sessionId
-			? `/api/mcp/projects/${projectId}/next-task?session_id=${sessionId}`
-			: `/api/mcp/projects/${projectId}/next-task`;
-		return this.request('GET', url);
-	}
-
-	async getTask(taskId: string): Promise<ApiResponse<{
-		task: {
-			id: string;
-			title: string;
-			description?: string;
-			priority: number;
-			status: string;
-			progress_percentage?: number;
-			estimated_minutes?: number;
-			started_at?: string;
-			completed_at?: string;
-			git_branch?: string;
-			blocking?: boolean;
-			references?: Array<{ url: string; label?: string }>;
-			parent_task_id?: string;
-			working_agent_session_id?: string;
-		};
-	}>> {
-		return this.request('GET', `/api/mcp/tasks/${taskId}`);
-	}
-
-	/**
-	 * Get a single task by ID with optional subtasks and milestones
-	 */
-	async getTaskById(taskId: string, params?: {
-		include_subtasks?: boolean;
-		include_milestones?: boolean;
-	}): Promise<ApiResponse<{
-		task: {
-			id: string;
-			title: string;
-			description?: string;
-			priority: number;
-			status: string;
-			progress_percentage?: number;
-			estimated_minutes?: number;
-			started_at?: string;
-			completed_at?: string;
-			git_branch?: string;
-			references?: Array<{ url: string; label?: string }>;
-		};
-		subtasks?: Array<{
-			id: string;
-			title: string;
-			status: string;
-			progress_percentage?: number;
-		}>;
-		milestones?: Array<{
-			id: string;
-			title: string;
-			status: string;
-			order_index: number;
-		}>;
-	}>> {
-		return this.proxy('get_task', {
-			task_id: taskId,
-			include_subtasks: params?.include_subtasks,
-			include_milestones: params?.include_milestones,
-		});
-	}
-
-	/**
-	 * Search tasks by text query with pagination
-	 */
-	async searchTasks(projectId: string, params: {
-		query: string;
-		status?: string[];
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		tasks: Array<{
-			id: string;
-			title: string;
-			status: string;
-			priority: number;
-			snippet?: string;
-		}>;
-		total_matches: number;
-		hint?: string;
-	}>> {
-		return this.proxy('search_tasks', {
-			project_id: projectId,
-			query: params.query,
-			status: params.status,
-			limit: params.limit,
-			offset: params.offset,
-		});
-	}
-
-	/**
-	 * Get tasks filtered by priority with pagination
-	 */
-	async getTasksByPriority(projectId: string, params?: {
-		priority?: number;
-		priority_max?: number;
-		status?: string;
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		tasks: Array<{
-			id: string;
-			title: string;
-			priority: number;
-			status: string;
-			estimated_minutes?: number;
-		}>;
-		total_count: number;
-	}>> {
-		return this.proxy('get_tasks_by_priority', {
-			project_id: projectId,
-			priority: params?.priority,
-			priority_max: params?.priority_max,
-			status: params?.status,
-			limit: params?.limit,
-			offset: params?.offset,
-		});
-	}
-
-	/**
-	 * Get recent tasks (newest or oldest) with pagination
-	 */
-	async getRecentTasks(projectId: string, params?: {
-		order?: 'newest' | 'oldest';
-		status?: string;
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		tasks: Array<{
-			id: string;
-			title: string;
-			status: string;
-			priority: number;
-			created_at: string;
-			age?: string;
-		}>;
-		total_count: number;
-	}>> {
-		return this.proxy('get_recent_tasks', {
-			project_id: projectId,
-			order: params?.order,
-			status: params?.status,
-			limit: params?.limit,
-			offset: params?.offset,
-		});
-	}
-
-	/**
-	 * Get task statistics for a project
-	 */
-	async getTaskStats(projectId: string): Promise<ApiResponse<{
-		total: number;
-		by_status: {
-			backlog: number;
-			pending: number;
-			in_progress: number;
-			completed: number;
-			cancelled: number;
-		};
-		by_priority: {
-			1: number;
-			2: number;
-			3: number;
-			4: number;
-			5: number;
-		};
-		awaiting_validation: number;
-		oldest_pending_days: number | null;
-	}>> {
-		return this.proxy('get_task_stats', {
-			project_id: projectId,
-		});
-	}
-
-	async updateTask(taskId: string, updates: {
-		title?: string;
-		description?: string;
-		priority?: number;
-		status?: string;
-		progress_percentage?: number;
-		progress_note?: string;
-		estimated_minutes?: number;
-		git_branch?: string;
-		worktree_path?: string;
-		session_id?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		task_id: string;
-		git_workflow?: {
-			workflow: string;
-			base_branch: string;
-			suggested_branch: string;
-			worktree_required: boolean;
-		};
-		worktree_setup?: {
-			message: string;
-			commands: string[];
-			worktree_path: string;
-			branch_name: string;
-			cleanup_command: string;
-		};
-		next_step?: string;
-	}>> {
-		return this.request('PATCH', `/api/mcp/tasks/${taskId}`, updates);
-	}
-
-	async completeTask(taskId: string, params: {
-		summary?: string;
-		session_id?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		directive: string;
-		auto_continue: boolean;
-		completed_task_id: string;
-		next_task?: {
-			id: string;
-			title: string;
-			priority: number;
-			estimated_minutes?: number;
-		} | null;
-		context?: {
-			validation?: number;
-			blockers?: number;
-			deployment?: string;
-		};
-		next_action: string;
-		warnings?: string[];
-	}>> {
-		// Use proxy endpoint for consistency - direct endpoint had routing issues on Vercel
-		return this.proxy('complete_task', {
-			task_id: taskId,
-			summary: params.summary,
-		}, params.session_id ? { session_id: params.session_id, persona: null, instance_id: '' } : undefined);
-	}
-
-	async deleteTask(taskId: string): Promise<ApiResponse<{
-		success: boolean;
-		deleted_id: string;
-	}>> {
-		return this.request('DELETE', `/api/mcp/tasks/${taskId}`);
-	}
-
-	// Progress endpoints
-	async logProgress(projectId: string, params: {
-		summary: string;
-		details?: string;
-		task_id?: string;
-		session_id?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		progress_id: string;
-	}>> {
-		return this.request('POST', `/api/mcp/projects/${projectId}/progress`, params);
-	}
-
-	// Git workflow endpoint
-	async getGitWorkflow(projectId: string, taskId?: string): Promise<ApiResponse<{
-		workflow: string;
-		main_branch: string;
-		develop_branch?: string | null;
-		auto_branch?: boolean;
-		auto_tag?: boolean;
-		instructions: string[];
-		task?: {
-			id: string;
-			title: string;
-			current_branch?: string;
-			suggested_branch?: string | null;
-		};
-	}>> {
-		const url = taskId
-			? `/api/mcp/projects/${projectId}/git-workflow?task_id=${taskId}`
-			: `/api/mcp/projects/${projectId}/git-workflow`;
-		return this.request('GET', url);
-	}
-
-	// ============================================================================
-	// Proxy endpoint - Generic method for all operations
-	// ============================================================================
-	async proxy<T>(operation: string, args: Record<string, unknown>, sessionContext?: {
-		session_id: string | null;
-		persona: string | null;
-		instance_id: string;
-	}): Promise<ApiResponse<T>> {
-		return this.request('POST', '/api/mcp/proxy', {
-			operation,
-			args,
-			session_context: sessionContext
-		});
-	}
-
-	// ============================================================================
-	// Blocker endpoints
-	// ============================================================================
-	async getBlockers(projectId: string, params?: {
-		status?: string;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-	}): Promise<ApiResponse<{
-		blockers: Array<{
-			id: string;
-			description: string;
-			status: string;
-			resolution_note?: string;
-			created_at: string;
-			resolved_at?: string;
-		}>;
-		total_count?: number;
-		has_more?: boolean;
-	}>> {
-		return this.proxy('get_blockers', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async addBlocker(projectId: string, description: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		blocker_id: string;
-	}>> {
-		return this.proxy('add_blocker', { project_id: projectId, description }, sessionId ? {
-			session_id: sessionId,
-			persona: null,
-			instance_id: ''
-		} : undefined);
-	}
-
-	async resolveBlocker(blockerId: string, resolutionNote?: string): Promise<ApiResponse<{
-		success: boolean;
-		blocker_id: string;
-	}>> {
-		return this.proxy('resolve_blocker', {
-			blocker_id: blockerId,
-			resolution_note: resolutionNote
-		});
-	}
-
-	async deleteBlocker(blockerId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_blocker', { blocker_id: blockerId });
-	}
-
-	async getBlockersStats(projectId: string): Promise<ApiResponse<{
-		total: number;
-		by_status: Record<string, number>;
-	}>> {
-		return this.proxy('get_blockers_stats', {
-			project_id: projectId
-		});
-	}
-
-	// ============================================================================
-	// Decision endpoints
-	// ============================================================================
-	async getDecisions(projectId: string, options?: {
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-	}): Promise<ApiResponse<{
-		decisions: Array<{
-			id: string;
-			title: string;
-			description: string;
-			rationale?: string;
-			alternatives_considered?: string[];
-			created_at: string;
-		}>;
-	}>> {
-		return this.proxy('get_decisions', { project_id: projectId, ...options });
-	}
-
-	async logDecision(projectId: string, params: {
-		title: string;
-		description: string;
-		rationale?: string;
-		alternatives_considered?: string[];
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		decision_id: string;
-	}>> {
-		return this.proxy('log_decision', {
-			project_id: projectId,
-			...params
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async deleteDecision(decisionId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_decision', { decision_id: decisionId });
-	}
-
-	async getDecisionsStats(projectId: string): Promise<ApiResponse<{
-		total: number;
-	}>> {
-		return this.proxy('get_decisions_stats', {
-			project_id: projectId
-		});
-	}
-
-	// ============================================================================
-	// Idea endpoints
-	// ============================================================================
-	async getIdeas(projectId: string, params?: {
-		status?: string;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-	}): Promise<ApiResponse<{
-		ideas: Array<{
-			id: string;
-			title: string;
-			description?: string;
-			status: string;
-			doc_url?: string;
-			created_at: string;
-		}>;
-	}>> {
-		return this.proxy('get_ideas', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async addIdea(projectId: string, params: {
-		title: string;
-		description?: string;
-		status?: string;
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		idea_id: string;
-	}>> {
-		return this.proxy('add_idea', {
-			project_id: projectId,
-			...params
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async updateIdea(ideaId: string, updates: {
-		title?: string;
-		description?: string;
-		status?: string;
-		doc_url?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		idea_id: string;
-	}>> {
-		return this.proxy('update_idea', {
-			idea_id: ideaId,
-			...updates
-		});
-	}
-
-	async deleteIdea(ideaId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_idea', { idea_id: ideaId });
-	}
-
-	async convertIdeaToTask(ideaId: string, params?: {
-		priority?: number;
-		estimated_minutes?: number;
-		update_status?: boolean;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		task_id?: string;
-		task_title?: string;
-		idea_id?: string;
-		idea_status?: string;
-		message?: string;
-		error?: string;
-		existing_task_id?: string;
-	}>> {
-		return this.proxy('convert_idea_to_task', {
-			idea_id: ideaId,
-			...params
-		});
-	}
-
-	// ============================================================================
-	// Finding endpoints
-	// ============================================================================
-	async getFindings(projectId: string, params?: {
-		category?: string;
-		severity?: string;
-		status?: string;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-		summary_only?: boolean;
-	}): Promise<ApiResponse<{
-		findings: Array<{
-			id: string;
-			title: string;
-			description?: string;
-			category: string;
-			severity: string;
-			status: string;
-			file_path?: string;
-			line_number?: number;
-			resolution_note?: string;
-			created_at: string;
-		}>;
-		total_count?: number;
-		has_more?: boolean;
-	}>> {
-		return this.proxy('get_findings', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async getFindingsStats(projectId: string): Promise<ApiResponse<{
-		total: number;
-		by_status: Record<string, number>;
-		by_severity: Record<string, number>;
-		by_category: Record<string, number>;
-	}>> {
-		return this.proxy('get_findings_stats', {
-			project_id: projectId
-		});
-	}
-
-	async addFinding(projectId: string, params: {
-		title: string;
-		description?: string;
-		category?: string;
-		severity?: string;
-		file_path?: string;
-		line_number?: number;
-		related_task_id?: string;
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		finding_id: string;
-	}>> {
-		return this.proxy('add_finding', {
-			project_id: projectId,
-			...params
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async updateFinding(findingId: string, updates: {
-		title?: string;
-		description?: string;
-		severity?: string;
-		status?: string;
-		resolution_note?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		finding_id: string;
-	}>> {
-		return this.proxy('update_finding', {
-			finding_id: findingId,
-			...updates
-		});
-	}
-
-	async deleteFinding(findingId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_finding', { finding_id: findingId });
-	}
-
-	// ============================================================================
-	// Milestone endpoints
-	// ============================================================================
-	async getMilestones(taskId: string): Promise<ApiResponse<{
-		milestones: Array<{
-			id: string;
-			title: string;
-			description?: string;
-			status: string;
-			order_index: number;
-			created_at: string;
-			completed_at?: string;
-		}>;
-		stats: {
-			total: number;
-			completed: number;
-			progress_percentage: number;
-		};
-	}>> {
-		return this.proxy('get_milestones', { task_id: taskId });
-	}
-
-	async addMilestone(taskId: string, params: {
-		title: string;
-		description?: string;
-		order_index?: number;
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		milestone_id: string;
-	}>> {
-		return this.proxy('add_milestone', {
-			task_id: taskId,
-			...params
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async updateMilestone(milestoneId: string, updates: {
-		title?: string;
-		description?: string;
-		status?: string;
-		order_index?: number;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		milestone: {
-			id: string;
-			title: string;
-			status: string;
-		};
-	}>> {
-		return this.proxy('update_milestone', {
-			milestone_id: milestoneId,
-			...updates
-		});
-	}
-
-	async completeMilestone(milestoneId: string): Promise<ApiResponse<{
-		success: boolean;
-		milestone: {
-			id: string;
-			title: string;
-			status: string;
-		};
-	}>> {
-		return this.proxy('complete_milestone', { milestone_id: milestoneId });
-	}
-
-	async deleteMilestone(milestoneId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_milestone', { milestone_id: milestoneId });
-	}
-
-	// ============================================================================
-	// Request endpoints
-	// ============================================================================
-	async getPendingRequests(projectId: string, sessionId?: string, limit?: number, offset?: number): Promise<ApiResponse<{
-		requests: Array<{
-			id: string;
-			request_type: string;
-			message: string;
-			created_at: string;
-		}>;
-		total_count: number;
-		has_more: boolean;
-	}>> {
-		return this.proxy('get_pending_requests', {
-			project_id: projectId,
-			...(limit !== undefined && { limit }),
-			...(offset !== undefined && { offset }),
-		}, sessionId ? {
-			session_id: sessionId,
-			persona: null,
-			instance_id: ''
-		} : undefined);
-	}
-
-	async acknowledgeRequest(requestId: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('acknowledge_request', { request_id: requestId }, sessionId ? {
-			session_id: sessionId,
-			persona: null,
-			instance_id: ''
-		} : undefined);
-	}
-
-	async answerQuestion(requestId: string, answer: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('answer_question', {
-			request_id: requestId,
-			answer
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	// ============================================================================
-	// Validation endpoints
-	// ============================================================================
-	async getTasksAwaitingValidation(projectId: string): Promise<ApiResponse<{
-		tasks: Array<{
-			id: string;
-			title: string;
-			completed_at?: string;
-			completed_by_session_id?: string;
-		}>;
-	}>> {
-		return this.proxy('get_tasks_awaiting_validation', { project_id: projectId });
-	}
-
-	async claimValidation(taskId: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		task_id: string;
-	}>> {
-		return this.proxy('claim_validation', { task_id: taskId }, sessionId ? {
-			session_id: sessionId,
-			persona: null,
-			instance_id: ''
-		} : undefined);
-	}
-
-	async validateTask(taskId: string, params: {
-		approved: boolean;
-		validation_notes?: string;
-		skip_pr_check?: boolean;
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		approved: boolean;
-		task_id: string;
-		message?: string;
-		workflow?: string;
-	}>> {
-		return this.proxy('validate_task', {
-			task_id: taskId,
-			...params
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	// ============================================================================
-	// Fallback activity endpoints
-	// ============================================================================
-	async startFallbackActivity(projectId: string, activity: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		activity: string;
-		message: string;
-		git_workflow?: {
-			workflow: string;
-			base_branch: string;
-			worktree_recommended: boolean;
-			note: string;
-		};
-		worktree_setup?: {
-			message: string;
-			commands: string[];
-			worktree_path: string;
-			branch_name: string;
-			cleanup_command: string;
-			report_worktree: string;
-		};
-		next_step?: string;
-	}>> {
-		return this.proxy('start_fallback_activity', {
-			project_id: projectId,
-			activity
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async stopFallbackActivity(projectId: string, summary?: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('stop_fallback_activity', {
-			project_id: projectId,
-			summary
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async getActivityHistory(projectId: string, params?: {
-		activity_type?: string;
-		limit?: number;
-	}): Promise<ApiResponse<{
-		history: Array<{
-			id: string;
-			activity_type: string;
-			completed_at: string;
-			summary?: string;
-		}>;
-		latest_by_type: Record<string, unknown>;
-		count: number;
-	}>> {
-		return this.proxy('get_activity_history', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async getActivitySchedules(projectId: string, params?: {
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		schedules: Array<{
-			id: string;
-			activity_type: string;
-			schedule_type: string;
-			next_run_at?: string;
-			enabled: boolean;
-		}>;
-		total_count: number;
-		has_more: boolean;
-	}>> {
-		return this.proxy('get_activity_schedules', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	// ============================================================================
-	// Subtask endpoints
-	// ============================================================================
-	async addSubtask(parentTaskId: string, params: {
-		title: string;
-		description?: string;
-		priority?: number;
-		estimated_minutes?: number;
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		subtask_id: string;
-		parent_task_id: string;
-	}>> {
-		return this.proxy('add_subtask', {
-			parent_task_id: parentTaskId,
-			...params
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async getSubtasks(parentTaskId: string, status?: string): Promise<ApiResponse<{
-		subtasks: Array<{
-			id: string;
-			title: string;
-			description?: string;
-			priority: number;
-			status: string;
-			progress_percentage?: number;
-			estimated_minutes?: number;
-		}>;
-		stats: {
-			total: number;
-			completed: number;
-			progress_percentage: number;
-		};
-	}>> {
-		return this.proxy('get_subtasks', {
-			parent_task_id: parentTaskId,
-			status
-		});
-	}
-
-	// ============================================================================
-	// Activity feed endpoint
-	// ============================================================================
-	async getActivityFeed(projectId: string, params?: {
-		limit?: number;
-		since?: string;
-		types?: string[];
-		created_by?: string;
-	}): Promise<ApiResponse<{
-		activities: Array<{
-			type: string;
-			data: unknown;
-			timestamp: string;
-		}>;
-	}>> {
-		return this.proxy('get_activity_feed', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	// ============================================================================
-	// Deployment endpoints
-	// ============================================================================
-	async requestDeployment(projectId: string, params?: {
-		environment?: string;
-		version_bump?: string;
-		git_ref?: string;
-		notes?: string;
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		deployment_id: string;
-		status: string;
-	}>> {
-		return this.proxy('request_deployment', {
-			project_id: projectId,
-			...params
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async checkDeploymentStatus(projectId: string): Promise<ApiResponse<{
-		active_deployment: boolean;
-		deployment?: {
-			id: string;
-			status: string;
-			environment: string;
-			git_ref?: string;
-			created_at: string;
-		};
-	}>> {
-		return this.proxy('check_deployment_status', { project_id: projectId });
-	}
-
-	async claimDeploymentValidation(projectId: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		deployment_id: string;
-		message: string;
-	}>> {
-		return this.proxy('claim_deployment_validation', { project_id: projectId }, sessionId ? {
-			session_id: sessionId,
-			persona: null,
-			instance_id: ''
-		} : undefined);
-	}
-
-	async reportValidation(projectId: string, params: {
-		build_passed: boolean;
-		tests_passed: boolean;
-		error_message?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		deployment_id: string;
-		status: string;
-	}>> {
-		return this.proxy('report_validation', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async startDeployment(projectId: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		deployment_id: string;
-		instructions: string;
-	}>> {
-		return this.proxy('start_deployment', { project_id: projectId }, sessionId ? {
-			session_id: sessionId,
-			persona: null,
-			instance_id: ''
-		} : undefined);
-	}
-
-	async completeDeployment(projectId: string, params: {
-		success: boolean;
-		summary?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		deployment_id: string;
-		status: string;
-	}>> {
-		return this.proxy('complete_deployment', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async cancelDeployment(projectId: string, reason?: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('cancel_deployment', {
-			project_id: projectId,
-			reason
-		});
-	}
-
-	// ============================================================================
-	// Task reference endpoints
-	// ============================================================================
-	async addTaskReference(taskId: string, url: string, label?: string): Promise<ApiResponse<{
-		success: boolean;
-		reference: { url: string; label?: string };
-	}>> {
-		return this.proxy('add_task_reference', {
-			task_id: taskId,
-			url,
-			label
-		});
-	}
-
-	async removeTaskReference(taskId: string, url: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('remove_task_reference', {
-			task_id: taskId,
-			url
-		});
-	}
-
-	// ============================================================================
-	// Knowledge base endpoint
-	// ============================================================================
-	async queryKnowledgeBase(projectId: string, params?: {
-		scope?: 'summary' | 'detailed';
-		categories?: string[];
-		limit?: number;
-		search_query?: string;
-	}): Promise<ApiResponse<{
-		findings?: Array<{ id: string; title: string; category: string; severity: string; description?: string }>;
-		decisions?: Array<{ id: string; title: string; description: string; rationale?: string }>;
-		completed_tasks?: Array<{ id: string; title: string; completed_at: string; summary?: string }>;
-		resolved_blockers?: Array<{ id: string; description: string; resolution_note?: string }>;
-		progress?: Array<{ id: string; summary: string; details?: string }>;
-		qa?: Array<{ id: string; question: string; answer: string }>;
-	}>> {
-		return this.proxy('query_knowledge_base', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	// ============================================================================
-	// Session sync endpoint
-	// ============================================================================
-	async syncSession(sessionId: string, params?: {
-		total_tokens?: number;
-		token_breakdown?: Record<string, unknown>;
-		model_usage?: Record<string, unknown>;
-	}): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('sync_session', {
-			session_id: sessionId,
-			...params
-		});
-	}
-
-	/**
-	 * Report actual API token usage for accurate cost tracking.
-	 * This records token usage to the session and attributes cost to the current task.
-	 */
-	async reportTokenUsage(sessionId: string, params: {
-		input_tokens: number;
-		output_tokens: number;
-		model?: 'opus' | 'sonnet' | 'haiku';
-	}): Promise<ApiResponse<{
-		success: boolean;
-		reported: {
-			session_id: string;
-			model: string;
-			input_tokens: number;
-			output_tokens: number;
-			total_tokens: number;
-			estimated_cost_usd: number;
-		};
-		task_attributed: boolean;
-		task_id?: string;
-	}>> {
-		return this.proxy('report_token_usage', {
-			session_id: sessionId,
-			...params
-		});
-	}
-
-	// ============================================================================
-	// Organization endpoints
-	// ============================================================================
-	async listOrganizations(): Promise<ApiResponse<{
-		organizations: Array<{
-			id: string;
-			name: string;
-			slug: string;
-			description?: string;
-			role: string;
-		}>;
-	}>> {
-		return this.proxy('list_organizations', {});
-	}
-
-	async createOrganization(params: {
-		name: string;
-		slug?: string;
-		description?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		organization: { id: string; name: string; slug: string };
-	}>> {
-		return this.proxy('create_organization', params);
-	}
-
-	async updateOrganization(organizationId: string, updates: {
-		name?: string;
-		description?: string;
-		logo_url?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		organization_id: string;
-	}>> {
-		return this.proxy('update_organization', {
-			organization_id: organizationId,
-			...updates
-		});
-	}
-
-	async deleteOrganization(organizationId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_organization', { organization_id: organizationId });
-	}
-
-	async listOrgMembers(organizationId: string): Promise<ApiResponse<{
-		members: Array<{
-			user_id: string;
-			email: string;
-			role: string;
-			joined_at: string;
-		}>;
-	}>> {
-		return this.proxy('list_org_members', { organization_id: organizationId });
-	}
-
-	async inviteMember(organizationId: string, email: string, role?: string): Promise<ApiResponse<{
-		success: boolean;
-		invite_id: string;
-	}>> {
-		return this.proxy('invite_member', {
-			organization_id: organizationId,
-			email,
-			role
-		});
-	}
-
-	async updateMemberRole(organizationId: string, userId: string, role: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('update_member_role', {
-			organization_id: organizationId,
-			user_id: userId,
-			role
-		});
-	}
-
-	async removeMember(organizationId: string, userId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('remove_member', {
-			organization_id: organizationId,
-			user_id: userId
-		});
-	}
-
-	async shareProjectWithOrg(projectId: string, organizationId: string, permission?: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('share_project_with_org', {
-			project_id: projectId,
-			organization_id: organizationId,
-			permission
-		});
-	}
-
-	async unshareProject(projectId: string, organizationId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('unshare_project', {
-			project_id: projectId,
-			organization_id: organizationId
-		});
-	}
-
-	async leaveOrganization(organizationId: string): Promise<ApiResponse<{
-		success: boolean;
-		message: string;
-	}>> {
-		return this.proxy('leave_organization', { organization_id: organizationId });
-	}
-
-	async updateProjectShare(projectId: string, organizationId: string, permission: string): Promise<ApiResponse<{
-		success: boolean;
-		share: { permission: string };
-	}>> {
-		return this.proxy('update_project_share', {
-			project_id: projectId,
-			organization_id: organizationId,
-			permission
-		});
-	}
-
-	async listProjectShares(projectId: string): Promise<ApiResponse<{
-		shares: Array<{
-			id: string;
-			permission: string;
-			shared_at: string;
-			organization: { id: string; name: string; slug: string };
-		}>;
-		count: number;
-	}>> {
-		return this.proxy('list_project_shares', { project_id: projectId });
-	}
-
-	// ============================================================================
-	// Body of work endpoints
-	// ============================================================================
-	async createBodyOfWork(projectId: string, params: {
-		title: string;
-		description?: string;
-		auto_deploy_on_completion?: boolean;
-		deploy_environment?: string;
-		deploy_version_bump?: string;
-		deploy_trigger?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		body_of_work_id: string;
-	}>> {
-		return this.proxy('create_body_of_work', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async getBodyOfWork(bodyOfWorkId: string): Promise<ApiResponse<{
-		body_of_work: {
-			id: string;
-			title: string;
-			description?: string;
-			status: string;
-			auto_deploy_on_completion: boolean;
-		};
-		tasks: {
-			pre: Array<{ id: string; title: string; status: string }>;
-			core: Array<{ id: string; title: string; status: string }>;
-			post: Array<{ id: string; title: string; status: string }>;
-		};
-	}>> {
-		return this.proxy('get_body_of_work', { body_of_work_id: bodyOfWorkId });
-	}
-
-	async getBodiesOfWork(projectId: string, params?: {
-		status?: string;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-	}): Promise<ApiResponse<{
-		bodies_of_work: Array<{
-			id: string;
-			title: string;
-			description?: string;
-			status: string;
-			task_counts: { pre: number; core: number; post: number };
-		}>;
-	}>> {
-		return this.proxy('get_bodies_of_work', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async updateBodyOfWork(bodyOfWorkId: string, updates: {
-		title?: string;
-		description?: string;
-		auto_deploy_on_completion?: boolean;
-		deploy_environment?: string;
-		deploy_version_bump?: string;
-		deploy_trigger?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('update_body_of_work', {
-			body_of_work_id: bodyOfWorkId,
-			...updates
-		});
-	}
-
-	async deleteBodyOfWork(bodyOfWorkId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_body_of_work', { body_of_work_id: bodyOfWorkId });
-	}
-
-	async addTaskToBodyOfWork(bodyOfWorkId: string, taskId: string, phase?: string, orderIndex?: number): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('add_task_to_body_of_work', {
-			body_of_work_id: bodyOfWorkId,
-			task_id: taskId,
-			phase,
-			order_index: orderIndex
-		});
-	}
-
-	async removeTaskFromBodyOfWork(taskId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('remove_task_from_body_of_work', { task_id: taskId });
-	}
-
-	async activateBodyOfWork(bodyOfWorkId: string): Promise<ApiResponse<{
-		success: boolean;
-		status: string;
-	}>> {
-		return this.proxy('activate_body_of_work', { body_of_work_id: bodyOfWorkId });
-	}
-
-	async addTaskDependency(bodyOfWorkId: string, taskId: string, dependsOnTaskId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('add_task_dependency', {
-			body_of_work_id: bodyOfWorkId,
-			task_id: taskId,
-			depends_on_task_id: dependsOnTaskId
-		});
-	}
-
-	async removeTaskDependency(taskId: string, dependsOnTaskId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('remove_task_dependency', {
-			task_id: taskId,
-			depends_on_task_id: dependsOnTaskId
-		});
-	}
-
-	async getTaskDependencies(params: {
-		body_of_work_id?: string;
-		task_id?: string;
-	}): Promise<ApiResponse<{
-		dependencies: Array<{
-			id: string;
-			task_id: string;
-			depends_on_task_id: string;
-			created_at: string;
-		}>;
-	}>> {
-		return this.proxy('get_task_dependencies', params);
-	}
-
-	async getNextBodyOfWorkTask(bodyOfWorkId: string): Promise<ApiResponse<{
-		task?: {
-			id: string;
-			title: string;
-			priority: number;
-			phase: string;
-		} | null;
-		message?: string;
-	}>> {
-		return this.proxy('get_next_body_of_work_task', { body_of_work_id: bodyOfWorkId });
-	}
-
-	// ============================================================================
-	// Git issues endpoints
-	// ============================================================================
-	async addGitIssue(projectId: string, params: {
-		issue_type: string;
-		branch: string;
-		target_branch?: string;
-		pr_url?: string;
-		conflicting_files?: string[];
-		error_message?: string;
-		task_id?: string;
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		git_issue_id: string;
-	}>> {
-		return this.proxy('add_git_issue', {
-			project_id: projectId,
-			...params
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async resolveGitIssue(gitIssueId: string, params?: {
-		resolution_note?: string;
-		auto_resolved?: boolean;
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		git_issue_id: string;
-	}>> {
-		return this.proxy('resolve_git_issue', {
-			git_issue_id: gitIssueId,
-			...params
-		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
-	}
-
-	async getGitIssues(projectId: string, params?: {
-		status?: string;
-		issue_type?: string;
-		branch?: string;
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		git_issues: Array<{
-			id: string;
-			issue_type: string;
-			branch: string;
-			target_branch?: string;
-			pr_url?: string;
-			conflicting_files?: string[];
-			error_message?: string;
-			status: string;
-			created_at: string;
-			resolved_at?: string;
-		}>;
-	}>> {
-		return this.proxy('get_git_issues', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async deleteGitIssue(gitIssueId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_git_issue', { git_issue_id: gitIssueId });
-	}
-
-	// ============================================================================
-	// Cost tracking endpoints
-	// ============================================================================
-	async getCostSummary(projectId: string, params?: {
-		period?: 'daily' | 'weekly' | 'monthly';
-		limit?: number;
-	}): Promise<ApiResponse<{
-		summaries: Array<{
-			date: string;
-			total_cost: number;
-			input_tokens: number;
-			output_tokens: number;
-		}>;
-	}>> {
-		return this.proxy('get_cost_summary', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async getCostAlerts(): Promise<ApiResponse<{
-		alerts: Array<{
-			id: string;
-			threshold_amount: number;
-			threshold_period: string;
-			alert_type: string;
-			enabled: boolean;
-		}>;
-	}>> {
-		return this.proxy('get_cost_alerts', {});
-	}
-
-	async addCostAlert(params: {
-		threshold_amount: number;
-		threshold_period: 'daily' | 'weekly' | 'monthly';
-		alert_type?: 'warning' | 'critical';
-		project_id?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		alert_id: string;
-	}>> {
-		return this.proxy('add_cost_alert', params);
-	}
-
-	async updateCostAlert(alertId: string, updates: {
-		threshold_amount?: number;
-		threshold_period?: string;
-		alert_type?: string;
-		enabled?: boolean;
-	}): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('update_cost_alert', {
-			alert_id: alertId,
-			...updates
-		});
-	}
-
-	async deleteCostAlert(alertId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_cost_alert', { alert_id: alertId });
-	}
-
-	async getTaskCosts(projectId: string, limit?: number): Promise<ApiResponse<{
-		task_costs: Array<{
-			task_id: string;
-			title: string;
-			total_cost: number;
-			input_tokens: number;
-			output_tokens: number;
-		}>;
-	}>> {
-		return this.proxy('get_task_costs', {
-			project_id: projectId,
-			limit
-		});
-	}
-
-	async getBodyOfWorkCosts(params: {
-		body_of_work_id?: string;
-		project_id?: string;
-	}): Promise<ApiResponse<{
-		bodies_of_work: Array<{
-			body_of_work_id: string;
-			title: string;
-			project_id: string;
-			status: string;
-			task_count: number;
-			total_cost_usd: number;
-			total_tokens: number;
-			pre_phase_cost_usd: number;
-			core_phase_cost_usd: number;
-			post_phase_cost_usd: number;
-			model_breakdown: Record<string, { input: number; output: number }>;
-		}>;
-		count: number;
-		totals: {
-			total_cost_usd: number;
-			total_tokens: number;
-			total_tasks: number;
-		};
-	}>> {
-		return this.proxy('get_body_of_work_costs', params);
-	}
-
-	async getSprintCosts(params: {
-		sprint_id?: string;
-		project_id?: string;
-	}): Promise<ApiResponse<{
-		sprints: Array<{
-			sprint_id: string;
-			title: string;
-			project_id: string;
-			status: string;
-			sprint_number: number;
-			task_count: number;
-			total_cost_usd: number;
-			total_tokens: number;
-			cost_per_story_point: number | null;
-			committed_points: number;
-			velocity_points: number;
-			model_breakdown: Record<string, { input: number; output: number }>;
-		}>;
-		count: number;
-		totals: {
-			total_cost_usd: number;
-			total_tokens: number;
-			total_tasks: number;
-			total_velocity_points: number;
-			avg_cost_per_point: number | null;
-		};
-	}>> {
-		return this.proxy('get_sprint_costs', params);
-	}
-
-	async getTokenUsage(): Promise<ApiResponse<{
-		session_tokens: number;
-		estimated_cost: number;
-	}>> {
-		return this.proxy('get_token_usage', {});
-	}
-
-	// ============================================================================
-	// Batch operation endpoints
-	// ============================================================================
-	async batchUpdateTasks(updates: Array<{
-		task_id: string;
-		status?: string;
-		priority?: number;
-		progress_percentage?: number;
-		progress_note?: string;
-	}>): Promise<ApiResponse<{
-		success: boolean;
-		updated_count: number;
-	}>> {
-		return this.proxy('batch_update_tasks', { updates });
-	}
-
-	async batchCompleteTasks(completions: Array<{
-		task_id: string;
-		summary?: string;
-	}>): Promise<ApiResponse<{
-		success: boolean;
-		completed_count: number;
-		next_task?: { id: string; title: string } | null;
-	}>> {
-		return this.proxy('batch_complete_tasks', { completions });
-	}
-
-	// ============================================================================
-	// Deployment requirements and scheduling endpoints
-	// ============================================================================
-	async addDeploymentRequirement(projectId: string, params: {
-		type: string;
-		title: string;
-		description?: string;
-		file_path?: string;
-		stage?: string;
-		blocking?: boolean;
-		recurring?: boolean;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		requirement_id: string;
-	}>> {
-		return this.proxy('add_deployment_requirement', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async getDeploymentRequirements(projectId: string, params?: {
-		status?: string;
-		stage?: string;
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		requirements: Array<{
-			id: string;
-			type: string;
-			title: string;
-			description?: string;
-			status: string;
-			stage: string;
-		}>;
-		total_count: number;
-		has_more: boolean;
-	}>> {
-		return this.proxy('get_deployment_requirements', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async getDeploymentRequirementsStats(projectId: string): Promise<ApiResponse<{
-		total: number;
-		by_status: Record<string, number>;
-		by_stage: Record<string, number>;
-		by_type: Record<string, number>;
-	}>> {
-		return this.proxy('get_deployment_requirements_stats', {
-			project_id: projectId
-		});
-	}
-
-	async completeDeploymentRequirement(requirementId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('complete_deployment_requirement', { requirement_id: requirementId });
-	}
-
-	async scheduleDeployment(projectId: string, params: {
-		scheduled_at: string;
-		schedule_type?: string;
-		environment?: string;
-		version_bump?: string;
-		auto_trigger?: boolean;
-		hours_interval?: number;
-		notes?: string;
-		git_ref?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		schedule_id: string;
-	}>> {
-		return this.proxy('schedule_deployment', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async getScheduledDeployments(projectId: string, params?: {
-		includeDisabled?: boolean;
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		schedules: Array<{
-			id: string;
-			scheduled_at: string;
-			schedule_type: string;
-			hours_interval: number;
-			environment: string;
-			version_bump: string;
-			auto_trigger: boolean;
-			enabled: boolean;
-			git_ref?: string;
-			notes?: string;
-		}>;
-		total_count: number;
-		has_more: boolean;
-	}>> {
-		return this.proxy('get_scheduled_deployments', {
-			project_id: projectId,
-			include_disabled: params?.includeDisabled,
-			limit: params?.limit,
-			offset: params?.offset
-		});
-	}
-
-	async updateScheduledDeployment(scheduleId: string, updates: {
-		scheduled_at?: string;
-		schedule_type?: string;
-		hours_interval?: number;
-		environment?: string;
-		version_bump?: string;
-		auto_trigger?: boolean;
-		enabled?: boolean;
-		git_ref?: string;
-		notes?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		schedule_id: string;
-	}>> {
-		return this.proxy('update_scheduled_deployment', {
-			schedule_id: scheduleId,
-			...updates
-		});
-	}
-
-	async deleteScheduledDeployment(scheduleId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_scheduled_deployment', { schedule_id: scheduleId });
-	}
-
-	async triggerScheduledDeployment(scheduleId: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		deployment_id?: string;
-		schedule_id: string;
-		schedule_type: string;
-		next_scheduled_at?: string;
-		message?: string;
-	}>> {
-		return this.proxy('trigger_scheduled_deployment', { schedule_id: scheduleId }, sessionId ? {
-			session_id: sessionId,
-			persona: null,
-			instance_id: ''
-		} : undefined);
-	}
-
-	async checkDueDeployments(projectId: string): Promise<ApiResponse<{
-		due_schedules: Array<{
-			id: string;
-			scheduled_at: string;
-			environment: string;
-			version_bump: string;
-			schedule_type: string;
-		}>;
-		count: number;
-	}>> {
-		return this.proxy('check_due_deployments', { project_id: projectId });
-	}
-
-	// ============================================================================
-	// Project README endpoint
-	// ============================================================================
-	async updateProjectReadme(projectId: string, readmeContent: string): Promise<ApiResponse<{
-		success: boolean;
-		project_id: string;
-	}>> {
-		return this.proxy('update_project_readme', {
-			project_id: projectId,
-			readme_content: readmeContent
-		});
-	}
-
-	async getProjectSummary(projectId: string): Promise<ApiResponse<{
-		project: {
-			id: string;
-			name: string;
-			description?: string;
-			goal?: string;
-			status: string;
-			git_url?: string;
-			tech_stack?: string[];
-			git_workflow?: string;
-		};
-		tasks: {
-			total: number;
-			by_status: Record<string, number>;
-		};
-		blockers: {
-			total: number;
-			open: number;
-			resolved: number;
-		};
-		findings: {
-			total: number;
-			by_severity: Record<string, number>;
-			by_status: Record<string, number>;
-		};
-		agents: {
-			active_count: number;
-			total_tokens_this_session: number;
-			total_tool_calls: number;
-		};
-		activity: {
-			tasks_completed_today: number;
-			progress_entries_today: number;
-		};
-		deployment: {
-			active: boolean;
-			status: string | null;
-			last_deployment_at: string | null;
-		};
-		planning: {
-			active_sprints: number;
-			active_bodies_of_work: number;
-			pending_deployment_requirements: number;
-		};
-	}>> {
-		return this.proxy('get_project_summary', { project_id: projectId });
-	}
-
-	// ============================================================================
-	// Help Topics (database-backed)
-	// ============================================================================
-	async getHelpTopic(slug: string): Promise<ApiResponse<{
-		slug: string;
-		title: string;
-		content: string;
-	} | null>> {
-		return this.proxy('get_help_topic', { slug });
-	}
-
-	async getHelpTopics(): Promise<ApiResponse<Array<{
-		slug: string;
-		title: string;
-	}>>> {
-		return this.proxy('get_help_topics', {});
-	}
-
-	// ============================================================================
-	// File Checkout endpoints (multi-agent coordination)
-	// ============================================================================
-	async checkoutFile(projectId: string, filePath: string, reason?: string, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		checkout_id: string;
-		file_path: string;
-		already_checked_out?: boolean;
-		message: string;
-	}>> {
-		return this.proxy('checkout_file', {
-			project_id: projectId,
-			file_path: filePath,
-			reason
-		}, sessionId ? {
-			session_id: sessionId,
-			persona: null,
-			instance_id: ''
-		} : undefined);
-	}
-
-	async checkinFile(params: {
-		checkout_id?: string;
-		project_id?: string;
-		file_path?: string;
-		summary?: string;
-	}, sessionId?: string): Promise<ApiResponse<{
-		success: boolean;
-		checkout_id: string;
-		message: string;
-	}>> {
-		return this.proxy('checkin_file', params, sessionId ? {
-			session_id: sessionId,
-			persona: null,
-			instance_id: ''
-		} : undefined);
-	}
-
-	async getFileCheckouts(projectId: string, options?: {
-		status?: string;
-		file_path?: string;
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		checkouts: Array<{
-			id: string;
-			file_path: string;
-			status: string;
-			checked_out_at: string;
-			checkout_reason?: string;
-			checked_in_at?: string;
-			checkin_summary?: string;
-			checked_out_by?: string;
-		}>;
-	}>> {
-		return this.proxy('get_file_checkouts', {
-			project_id: projectId,
-			...options
-		});
-	}
-
-	async abandonCheckout(params: {
-		checkout_id?: string;
-		project_id?: string;
-		file_path?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		checkout_id: string;
-		message: string;
-	}>> {
-		return this.proxy('abandon_checkout', params);
-	}
-
-	async getFileCheckoutsStats(projectId: string): Promise<ApiResponse<{
-		total: number;
-		by_status: Record<string, number>;
-	}>> {
-		return this.proxy('get_file_checkouts_stats', { project_id: projectId });
-	}
-
-	// ============================================================================
-	// Worktree Management
-	// ============================================================================
-
-	async getStaleWorktrees(projectId: string, params?: {
-		hostname?: string;
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		project_id: string;
-		project_name: string;
-		hostname_filter: string | null;
-		stale_worktrees: Array<{
-			task_id: string;
-			task_title: string;
-			worktree_path: string;
-			worktree_hostname: string | null;
-			git_branch: string | null;
-			status: string;
-			completed_at: string | null;
-			updated_at: string;
-			pr_url: string | null;
-			stale_reason: 'task_finished' | 'potentially_abandoned';
-			can_cleanup_locally: boolean;
-		}>;
-		count: number;
-		local_count: number;
-		remote_count: number;
-		total_count: number;
-		has_more: boolean;
-		cleanup_instructions: string[] | null;
-		remote_worktree_note: string | null;
-	}>> {
-		const queryParams = new URLSearchParams({ project_id: projectId });
-		if (params?.hostname !== undefined) queryParams.set('hostname', params.hostname);
-		if (params?.limit !== undefined) queryParams.set('limit', String(params.limit));
-		if (params?.offset !== undefined) queryParams.set('offset', String(params.offset));
-		return this.request('GET', `/api/mcp/worktrees/stale?${queryParams.toString()}`);
-	}
-
-	async clearWorktreePath(taskId: string): Promise<ApiResponse<{
-		success: boolean;
-		task_id: string;
-	}>> {
-		return this.request('PATCH', `/api/mcp/tasks/${taskId}`, { worktree_path: null });
-	}
-
-	// ============================================================================
-	// Connector endpoints
-	// ============================================================================
-
-	async getConnectors(projectId: string, params?: {
-		type?: string;
-		status?: string;
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		connectors: Array<{
-			id: string;
-			name: string;
-			type: string;
-			description?: string;
-			status: string;
-			events: Record<string, boolean>;
-			events_sent: number;
-			last_triggered_at?: string;
-			last_error?: string;
-			last_error_at?: string;
-			created_at: string;
-		}>;
-		total_count: number;
-		has_more: boolean;
-	}>> {
-		return this.proxy('get_connectors', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async getConnector(connectorId: string): Promise<ApiResponse<{
-		connector: {
-			id: string;
-			name: string;
-			type: string;
-			description?: string;
-			config: Record<string, unknown>;
-			events: Record<string, boolean>;
-			status: string;
-			events_sent: number;
-			last_triggered_at?: string;
-			last_error?: string;
-			last_error_at?: string;
-			created_at: string;
-		};
-	}>> {
-		return this.proxy('get_connector', { connector_id: connectorId });
-	}
-
-	async addConnector(projectId: string, params: {
-		name: string;
-		type: string;
-		description?: string;
-		config?: Record<string, unknown>;
-		events?: Record<string, boolean>;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		connector_id: string;
-	}>> {
-		return this.proxy('add_connector', {
-			project_id: projectId,
-			...params
-		});
-	}
-
-	async updateConnector(connectorId: string, updates: {
-		name?: string;
-		description?: string;
-		config?: Record<string, unknown>;
-		events?: Record<string, boolean>;
-		status?: string;
-	}): Promise<ApiResponse<{
-		success: boolean;
-		connector_id: string;
-	}>> {
-		return this.proxy('update_connector', {
-			connector_id: connectorId,
-			...updates
-		});
-	}
-
-	async deleteConnector(connectorId: string): Promise<ApiResponse<{
-		success: boolean;
-	}>> {
-		return this.proxy('delete_connector', { connector_id: connectorId });
-	}
-
-	async testConnector(connectorId: string): Promise<ApiResponse<{
-		success: boolean;
-		event_id: string;
-		status?: number;
-		error?: string;
-	}>> {
-		return this.proxy('test_connector', { connector_id: connectorId });
-	}
-
-	async getConnectorEvents(params: {
-		connector_id?: string;
-		project_id?: string;
-		status?: string;
-		limit?: number;
-		offset?: number;
-	}): Promise<ApiResponse<{
-		events: Array<{
-			id: string;
-			connector_id: string;
-			event_type: string;
-			status: string;
-			response_status?: number;
-			error_message?: string;
-			attempts: number;
-			created_at: string;
-			sent_at?: string;
-		}>;
-		total_count: number;
-		has_more: boolean;
-	}>> {
-		return this.proxy('get_connector_events', params);
-	}
-
-	// ============================================================================
-	// Agent onboarding endpoints
-	// ============================================================================
-
-	/**
-	 * Confirm that agent setup is complete for a project.
-	 * This marks the agent type as onboarded so future sessions don't receive setup instructions.
-	 */
-	async confirmAgentSetup(projectId: string, agentType: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'): Promise<ApiResponse<{
-		success: boolean;
-		project_id: string;
-		agent_type: string;
-	}>> {
-		return this.proxy('confirm_agent_setup', {
-			project_id: projectId,
-			agent_type: agentType
-		});
-	}
-}
-
-// Singleton instance
-let apiClient: VibescopeApiClient | null = null;
-
-export function getApiClient(): VibescopeApiClient {
-	if (!apiClient) {
-		const apiKey = process.env.VIBESCOPE_API_KEY;
-		if (!apiKey) {
-			throw new Error('VIBESCOPE_API_KEY environment variable is required');
-		}
-		apiClient = new VibescopeApiClient({ apiKey });
-	}
-	return apiClient;
-}
-
-export function initApiClient(config: ApiClientConfig): VibescopeApiClient {
-	apiClient = new VibescopeApiClient(config);
-	return apiClient;
-}
+/**
+ * Vibescope API Client
+ *
+ * HTTP client for communicating with the Vibescope API.
+ * All database operations are handled server-side through these endpoints.
+ */
+
+const DEFAULT_API_URL = 'https://vibescope.dev';
+
+interface ApiClientConfig {
+	apiKey: string;
+	baseUrl?: string;
+}
+
+interface ApiResponse<T> {
+	ok: boolean;
+	status: number;
+	data?: T;
+	error?: string;
+}
+
+export class VibescopeApiClient {
+	private apiKey: string;
+	private baseUrl: string;
+
+	constructor(config: ApiClientConfig) {
+		this.apiKey = config.apiKey;
+		this.baseUrl = config.baseUrl || process.env.VIBESCOPE_API_URL || DEFAULT_API_URL;
+	}
+
+	private async request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>> {
+		const url = `${this.baseUrl}${path}`;
+
+		try {
+			const response = await fetch(url, {
+				method,
+				headers: {
+					'Content-Type': 'application/json',
+					'X-API-Key': this.apiKey
+				},
+				body: body ? JSON.stringify(body) : undefined
+			});
+
+			const data = await response.json();
+
+			if (!response.ok) {
+				return {
+					ok: false,
+					status: response.status,
+					error: data.error || `HTTP ${response.status}`,
+					data // Include full response data for additional error context
+				};
+			}
+
+			return {
+				ok: true,
+				status: response.status,
+				data
+			};
+		} catch (err) {
+			return {
+				ok: false,
+				status: 0,
+				error: err instanceof Error ? err.message : 'Network error'
+			};
+		}
+	}
+
+	// Auth endpoints
+	async validateAuth(): Promise<ApiResponse<{
+		valid: boolean;
+		user_id: string;
+		api_key_id: string;
+		key_name: string;
+	}>> {
+		return this.request('POST', '/api/mcp/auth/validate', {
+			api_key: this.apiKey
+		});
+	}
+
+	// Session endpoints
+	async startSession(params: {
+		project_id?: string;
+		git_url?: string;
+		mode?: 'lite' | 'full';
+		model?: 'opus' | 'sonnet' | 'haiku';
+		role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
+		hostname?: string; // Machine hostname for worktree tracking
+		agent_type?: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'; // Agent type for onboarding
+	}): Promise<ApiResponse<{
+		session_started: boolean;
+		session_id?: string;
+		persona?: string;
+		role?: string;
+		project?: {
+			id: string;
+			name: string;
+			description?: string;
+			goal?: string;
+			status?: string;
+			git_url?: string;
+			agent_instructions?: string;
+			tech_stack?: string[];
+			git_workflow?: string;
+			git_main_branch?: string;
+			git_develop_branch?: string;
+			git_auto_branch?: boolean;
+		};
+		active_tasks?: Array<{
+			id: string;
+			title: string;
+			status: string;
+			priority: number;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+		}>;
+		blockers?: Array<{
+			id: string;
+			description: string;
+			status: string;
+		}>;
+		next_task?: {
+			id: string;
+			title: string;
+			priority: number;
+			estimated_minutes?: number;
+		} | null;
+		pending_requests?: Array<{
+			id: string;
+			request_type: string;
+			message: string;
+			created_at: string;
+		}>;
+		pending_requests_count?: number;
+		URGENT_QUESTIONS?: {
+			count: number;
+			oldest_waiting_minutes: number;
+			action_required: string;
+			requests: Array<{
+				id: string;
+				message: string;
+				waiting_minutes: number;
+			}>;
+		};
+		directive?: string;
+		blockers_count?: number;
+		validation_count?: number;
+		project_not_found?: boolean;
+		message?: string;
+		suggestion?: {
+			action: string;
+			example: string;
+			note: string;
+		};
+		// Agent onboarding - returned when a new agent type connects to an existing project
+		agent_setup?: {
+			agent_type: string;
+			is_new_agent_type: boolean;
+			setup_required: boolean;
+			instructions: string;
+			config_file: string; // e.g., '.gemini/GEMINI.md'
+			template_url?: string;
+			steps: string[];
+		};
+		// Stale worktrees that need cleanup
+		stale_worktrees?: Array<{
+			task_id: string;
+			task_title: string;
+			worktree_path: string;
+			worktree_hostname?: string | null;
+		}>;
+		stale_worktrees_count?: number;
+		cleanup_action?: string;
+		// Validation info for validators
+		awaiting_validation?: Array<{
+			id: string;
+			title?: string;
+		}>;
+		validation_priority?: boolean;
+		next_action?: string;
+		error?: string;
+	}>> {
+		return this.request('POST', '/api/mcp/sessions/start', params);
+	}
+
+	async heartbeat(sessionId: string, options?: {
+		current_worktree_path?: string | null;
+		hostname?: string; // Machine hostname for worktree tracking
+	}): Promise<ApiResponse<{
+		success: boolean;
+		session_id: string;
+		timestamp: string;
+	}>> {
+		return this.request('POST', '/api/mcp/sessions/heartbeat', {
+			session_id: sessionId,
+			...options
+		});
+	}
+
+	async endSession(sessionId: string): Promise<ApiResponse<{
+		success: boolean;
+		ended_session_id?: string;
+		session_summary?: {
+			agent_name: string;
+			tasks_completed_this_session: number;
+			tasks_awaiting_validation: number;
+			tasks_released: number;
+		};
+		reminders?: string[];
+	}>> {
+		return this.request('POST', '/api/mcp/sessions/end', {
+			session_id: sessionId
+		});
+	}
+
+	// Project endpoints
+	async listProjects(): Promise<ApiResponse<{
+		projects: Array<{
+			id: string;
+			name: string;
+			description?: string;
+			status: string;
+			git_url?: string;
+			goal?: string;
+			tech_stack?: string[];
+		}>;
+	}>> {
+		return this.request('GET', '/api/mcp/projects');
+	}
+
+	async createProject(params: {
+		name: string;
+		description?: string;
+		goal?: string;
+		git_url?: string;
+		tech_stack?: string[];
+	}): Promise<ApiResponse<{
+		success: boolean;
+		project: {
+			id: string;
+			name: string;
+		};
+	}>> {
+		return this.request('POST', '/api/mcp/projects', params);
+	}
+
+	async getProject(projectId: string, gitUrl?: string): Promise<ApiResponse<{
+		found: boolean;
+		project?: {
+			id: string;
+			name: string;
+			description?: string;
+			goal?: string;
+			status: string;
+			git_url?: string;
+			agent_instructions?: string;
+			tech_stack?: string[];
+			git_workflow?: string;
+			git_main_branch?: string;
+			git_develop_branch?: string;
+			git_auto_branch?: boolean;
+			git_auto_tag?: boolean;
+			deployment_instructions?: string;
+		};
+		active_tasks?: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+		}>;
+		open_blockers?: Array<{
+			id: string;
+			description: string;
+		}>;
+		recent_decisions?: Array<{
+			id: string;
+			title: string;
+			description?: string;
+		}>;
+		message?: string;
+	}>> {
+		const url = gitUrl
+			? `/api/mcp/projects/${projectId}?git_url=${encodeURIComponent(gitUrl)}`
+			: `/api/mcp/projects/${projectId}`;
+		return this.request('GET', url);
+	}
+
+	async updateProject(projectId: string, updates: {
+		name?: string;
+		description?: string;
+		goal?: string;
+		git_url?: string;
+		tech_stack?: string[];
+		status?: string;
+		git_workflow?: string;
+		git_main_branch?: string;
+		git_develop_branch?: string;
+		git_auto_branch?: boolean;
+		git_auto_tag?: boolean;
+		deployment_instructions?: string;
+		agent_instructions?: string;
+		// New project settings columns
+		git_delete_branch_on_merge?: boolean;
+		require_pr_for_validation?: boolean;
+		auto_merge_on_approval?: boolean;
+		validation_required?: boolean;
+		default_task_priority?: number;
+		require_time_estimates?: boolean;
+		fallback_activities_enabled?: boolean;
+		preferred_fallback_activities?: string[];
+	}): Promise<ApiResponse<{
+		success: boolean;
+		project_id: string;
+	}>> {
+		return this.request('PATCH', `/api/mcp/projects/${projectId}`, updates);
+	}
+
+	// Task endpoints
+	async getTasks(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		include_subtasks?: boolean;
+		search_query?: string;
+		include_metadata?: boolean; // When true, returns all task fields; when false (default), only id/title/priority/status
+	}): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+			started_at?: string;
+			completed_at?: string;
+			parent_task_id?: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>> {
+		const queryParams = new URLSearchParams();
+		if (params?.status) queryParams.set('status', params.status);
+		if (params?.limit) queryParams.set('limit', params.limit.toString());
+		if (params?.offset) queryParams.set('offset', params.offset.toString());
+		if (params?.include_subtasks) queryParams.set('include_subtasks', 'true');
+		if (params?.search_query) queryParams.set('search_query', params.search_query);
+		if (params?.include_metadata) queryParams.set('include_metadata', 'true');
+
+		const query = queryParams.toString();
+		const url = `/api/mcp/projects/${projectId}/tasks${query ? `?${query}` : ''}`;
+		return this.request('GET', url);
+	}
+
+	async createTask(projectId: string, params: {
+		title: string;
+		description?: string;
+		priority?: number;
+		estimated_minutes?: number;
+		blocking?: boolean;
+		session_id?: string;
+		task_type?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+		title: string;
+		blocking?: boolean;
+		message?: string;
+	}>> {
+		return this.request('POST', `/api/mcp/projects/${projectId}/tasks`, params);
+	}
+
+	async getNextTask(projectId: string, sessionId?: string): Promise<ApiResponse<{
+		task?: {
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			estimated_minutes?: number;
+			blocking?: boolean;
+		} | null;
+		blocking_task?: boolean;
+		deployment_blocks_tasks?: boolean;
+		deployment?: {
+			id: string;
+			status: string;
+			env: string;
+		};
+		awaiting_validation?: Array<{
+			id: string;
+			title: string;
+		}>;
+		validation_priority?: string;
+		all_claimed?: boolean;
+		is_subtask?: boolean;
+		suggested_activity?: string;
+		directive?: string;
+		message?: string;
+		action?: string;
+	}>> {
+		const url = sessionId
+			? `/api/mcp/projects/${projectId}/next-task?session_id=${sessionId}`
+			: `/api/mcp/projects/${projectId}/next-task`;
+		return this.request('GET', url);
+	}
+
+	async getTask(taskId: string): Promise<ApiResponse<{
+		task: {
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+			started_at?: string;
+			completed_at?: string;
+			git_branch?: string;
+			blocking?: boolean;
+			references?: Array<{ url: string; label?: string }>;
+			parent_task_id?: string;
+			working_agent_session_id?: string;
+		};
+	}>> {
+		return this.request('GET', `/api/mcp/tasks/${taskId}`);
+	}
+
+	/**
+	 * Get a single task by ID with optional subtasks and milestones
+	 */
+	async getTaskById(taskId: string, params?: {
+		include_subtasks?: boolean;
+		include_milestones?: boolean;
+	}): Promise<ApiResponse<{
+		task: {
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+			started_at?: string;
+			completed_at?: string;
+			git_branch?: string;
+			references?: Array<{ url: string; label?: string }>;
+		};
+		subtasks?: Array<{
+			id: string;
+			title: string;
+			status: string;
+			progress_percentage?: number;
+		}>;
+		milestones?: Array<{
+			id: string;
+			title: string;
+			status: string;
+			order_index: number;
+		}>;
+	}>> {
+		return this.proxy('get_task', {
+			task_id: taskId,
+			include_subtasks: params?.include_subtasks,
+			include_milestones: params?.include_milestones,
+		});
+	}
+
+	/**
+	 * Search tasks by text query with pagination
+	 */
+	async searchTasks(projectId: string, params: {
+		query: string;
+		status?: string[];
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			status: string;
+			priority: number;
+			snippet?: string;
+		}>;
+		total_matches: number;
+		hint?: string;
+	}>> {
+		return this.proxy('search_tasks', {
+			project_id: projectId,
+			query: params.query,
+			status: params.status,
+			limit: params.limit,
+			offset: params.offset,
+		});
+	}
+
+	/**
+	 * Get tasks filtered by priority with pagination
+	 */
+	async getTasksByPriority(projectId: string, params?: {
+		priority?: number;
+		priority_max?: number;
+		status?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			priority: number;
+			status: string;
+			estimated_minutes?: number;
+		}>;
+		total_count: number;
+	}>> {
+		return this.proxy('get_tasks_by_priority', {
+			project_id: projectId,
+			priority: params?.priority,
+			priority_max: params?.priority_max,
+			status: params?.status,
+			limit: params?.limit,
+			offset: params?.offset,
+		});
+	}
+
+	/**
+	 * Get recent tasks (newest or oldest) with pagination
+	 */
+	async getRecentTasks(projectId: string, params?: {
+		order?: 'newest' | 'oldest';
+		status?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			status: string;
+			priority: number;
+			created_at: string;
+			age?: string;
+		}>;
+		total_count: number;
+	}>> {
+		return this.proxy('get_recent_tasks', {
+			project_id: projectId,
+			order: params?.order,
+			status: params?.status,
+			limit: params?.limit,
+			offset: params?.offset,
+		});
+	}
+
+	/**
+	 * Get task statistics for a project
+	 */
+	async getTaskStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: {
+			backlog: number;
+			pending: number;
+			in_progress: number;
+			completed: number;
+			cancelled: number;
+		};
+		by_priority: {
+			1: number;
+			2: number;
+			3: number;
+			4: number;
+			5: number;
+		};
+		awaiting_validation: number;
+		oldest_pending_days: number | null;
+	}>> {
+		return this.proxy('get_task_stats', {
+			project_id: projectId,
+		});
+	}
+
+	async updateTask(taskId: string, updates: {
+		title?: string;
+		description?: string;
+		priority?: number;
+		status?: string;
+		progress_percentage?: number;
+		progress_note?: string;
+		estimated_minutes?: number;
+		git_branch?: string;
+		worktree_path?: string;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+		git_workflow?: {
+			workflow: string;
+			base_branch: string;
+			suggested_branch: string;
+			worktree_required: boolean;
+		};
+		worktree_setup?: {
+			message: string;
+			commands: string[];
+			worktree_path: string;
+			branch_name: string;
+			cleanup_command: string;
+		};
+		next_step?: string;
+	}>> {
+		return this.request('PATCH', `/api/mcp/tasks/${taskId}`, updates);
+	}
+
+	async completeTask(taskId: string, params: {
+		summary?: string;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		directive: string;
+		auto_continue: boolean;
+		completed_task_id: string;
+		next_task?: {
+			id: string;
+			title: string;
+			priority: number;
+			estimated_minutes?: number;
+		} | null;
+		context?: {
+			validation?: number;
+			blockers?: number;
+			deployment?: string;
+		};
+		next_action: string;
+		warnings?: string[];
+	}>> {
+		// Use proxy endpoint for consistency - direct endpoint had routing issues on Vercel
+		return this.proxy('complete_task', {
+			task_id: taskId,
+			summary: params.summary,
+		}, params.session_id ? { session_id: params.session_id, persona: null, instance_id: '' } : undefined);
+	}
+
+	async deleteTask(taskId: string): Promise<ApiResponse<{
+		success: boolean;
+		deleted_id: string;
+	}>> {
+		return this.request('DELETE', `/api/mcp/tasks/${taskId}`);
+	}
+
+	// Progress endpoints
+	async logProgress(projectId: string, params: {
+		summary: string;
+		details?: string;
+		task_id?: string;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		progress_id: string;
+	}>> {
+		return this.request('POST', `/api/mcp/projects/${projectId}/progress`, params);
+	}
+
+	// Git workflow endpoint
+	async getGitWorkflow(projectId: string, taskId?: string): Promise<ApiResponse<{
+		workflow: string;
+		main_branch: string;
+		develop_branch?: string | null;
+		auto_branch?: boolean;
+		auto_tag?: boolean;
+		instructions: string[];
+		task?: {
+			id: string;
+			title: string;
+			current_branch?: string;
+			suggested_branch?: string | null;
+		};
+	}>> {
+		const url = taskId
+			? `/api/mcp/projects/${projectId}/git-workflow?task_id=${taskId}`
+			: `/api/mcp/projects/${projectId}/git-workflow`;
+		return this.request('GET', url);
+	}
+
+	// ============================================================================
+	// Proxy endpoint - Generic method for all operations
+	// ============================================================================
+	async proxy<T>(operation: string, args: Record<string, unknown>, sessionContext?: {
+		session_id: string | null;
+		persona: string | null;
+		instance_id: string;
+	}): Promise<ApiResponse<T>> {
+		return this.request('POST', '/api/mcp/proxy', {
+			operation,
+			args,
+			session_context: sessionContext
+		});
+	}
+
+	// ============================================================================
+	// Blocker endpoints
+	// ============================================================================
+	async getBlockers(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		blockers: Array<{
+			id: string;
+			description: string;
+			status: string;
+			resolution_note?: string;
+			created_at: string;
+			resolved_at?: string;
+		}>;
+		total_count?: number;
+		has_more?: boolean;
+	}>> {
+		return this.proxy('get_blockers', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async addBlocker(projectId: string, description: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		blocker_id: string;
+	}>> {
+		return this.proxy('add_blocker', { project_id: projectId, description }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async resolveBlocker(blockerId: string, resolutionNote?: string): Promise<ApiResponse<{
+		success: boolean;
+		blocker_id: string;
+	}>> {
+		return this.proxy('resolve_blocker', {
+			blocker_id: blockerId,
+			resolution_note: resolutionNote
+		});
+	}
+
+	async deleteBlocker(blockerId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_blocker', { blocker_id: blockerId });
+	}
+
+	async getBlockersStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: Record<string, number>;
+	}>> {
+		return this.proxy('get_blockers_stats', {
+			project_id: projectId
+		});
+	}
+
+	// ============================================================================
+	// Decision endpoints
+	// ============================================================================
+	async getDecisions(projectId: string, options?: {
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		decisions: Array<{
+			id: string;
+			title: string;
+			description: string;
+			rationale?: string;
+			alternatives_considered?: string[];
+			created_at: string;
+		}>;
+	}>> {
+		return this.proxy('get_decisions', { project_id: projectId, ...options });
+	}
+
+	async logDecision(projectId: string, params: {
+		title: string;
+		description: string;
+		rationale?: string;
+		alternatives_considered?: string[];
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		decision_id: string;
+	}>> {
+		return this.proxy('log_decision', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async deleteDecision(decisionId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_decision', { decision_id: decisionId });
+	}
+
+	async getDecisionsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+	}>> {
+		return this.proxy('get_decisions_stats', {
+			project_id: projectId
+		});
+	}
+
+	// ============================================================================
+	// Idea endpoints
+	// ============================================================================
+	async getIdeas(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		ideas: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			doc_url?: string;
+			created_at: string;
+		}>;
+	}>> {
+		return this.proxy('get_ideas', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async addIdea(projectId: string, params: {
+		title: string;
+		description?: string;
+		status?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		idea_id: string;
+	}>> {
+		return this.proxy('add_idea', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async updateIdea(ideaId: string, updates: {
+		title?: string;
+		description?: string;
+		status?: string;
+		doc_url?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		idea_id: string;
+	}>> {
+		return this.proxy('update_idea', {
+			idea_id: ideaId,
+			...updates
+		});
+	}
+
+	async deleteIdea(ideaId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_idea', { idea_id: ideaId });
+	}
+
+	async convertIdeaToTask(ideaId: string, params?: {
+		priority?: number;
+		estimated_minutes?: number;
+		update_status?: boolean;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id?: string;
+		task_title?: string;
+		idea_id?: string;
+		idea_status?: string;
+		message?: string;
+		error?: string;
+		existing_task_id?: string;
+	}>> {
+		return this.proxy('convert_idea_to_task', {
+			idea_id: ideaId,
+			...params
+		});
+	}
+
+	// ============================================================================
+	// Finding endpoints
+	// ============================================================================
+	async getFindings(projectId: string, params?: {
+		category?: string;
+		severity?: string;
+		status?: string;
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+		summary_only?: boolean;
+	}): Promise<ApiResponse<{
+		findings: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			category: string;
+			severity: string;
+			status: string;
+			file_path?: string;
+			line_number?: number;
+			resolution_note?: string;
+			created_at: string;
+		}>;
+		total_count?: number;
+		has_more?: boolean;
+	}>> {
+		return this.proxy('get_findings', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getFindingsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: Record<string, number>;
+		by_severity: Record<string, number>;
+		by_category: Record<string, number>;
+	}>> {
+		return this.proxy('get_findings_stats', {
+			project_id: projectId
+		});
+	}
+
+	async addFinding(projectId: string, params: {
+		title: string;
+		description?: string;
+		category?: string;
+		severity?: string;
+		file_path?: string;
+		line_number?: number;
+		related_task_id?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		finding_id: string;
+	}>> {
+		return this.proxy('add_finding', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async updateFinding(findingId: string, updates: {
+		title?: string;
+		description?: string;
+		severity?: string;
+		status?: string;
+		resolution_note?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		finding_id: string;
+	}>> {
+		return this.proxy('update_finding', {
+			finding_id: findingId,
+			...updates
+		});
+	}
+
+	async deleteFinding(findingId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_finding', { finding_id: findingId });
+	}
+
+	// ============================================================================
+	// Milestone endpoints
+	// ============================================================================
+	async getMilestones(taskId: string): Promise<ApiResponse<{
+		milestones: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			order_index: number;
+			created_at: string;
+			completed_at?: string;
+		}>;
+		stats: {
+			total: number;
+			completed: number;
+			progress_percentage: number;
+		};
+	}>> {
+		return this.proxy('get_milestones', { task_id: taskId });
+	}
+
+	async addMilestone(taskId: string, params: {
+		title: string;
+		description?: string;
+		order_index?: number;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		milestone_id: string;
+	}>> {
+		return this.proxy('add_milestone', {
+			task_id: taskId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async updateMilestone(milestoneId: string, updates: {
+		title?: string;
+		description?: string;
+		status?: string;
+		order_index?: number;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		milestone: {
+			id: string;
+			title: string;
+			status: string;
+		};
+	}>> {
+		return this.proxy('update_milestone', {
+			milestone_id: milestoneId,
+			...updates
+		});
+	}
+
+	async completeMilestone(milestoneId: string): Promise<ApiResponse<{
+		success: boolean;
+		milestone: {
+			id: string;
+			title: string;
+			status: string;
+		};
+	}>> {
+		return this.proxy('complete_milestone', { milestone_id: milestoneId });
+	}
+
+	async deleteMilestone(milestoneId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_milestone', { milestone_id: milestoneId });
+	}
+
+	// ============================================================================
+	// Request endpoints
+	// ============================================================================
+	async getPendingRequests(projectId: string, sessionId?: string, limit?: number, offset?: number): Promise<ApiResponse<{
+		requests: Array<{
+			id: string;
+			request_type: string;
+			message: string;
+			created_at: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>> {
+		return this.proxy('get_pending_requests', {
+			project_id: projectId,
+			...(limit !== undefined && { limit }),
+			...(offset !== undefined && { offset }),
+		}, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async acknowledgeRequest(requestId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('acknowledge_request', { request_id: requestId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async answerQuestion(requestId: string, answer: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('answer_question', {
+			request_id: requestId,
+			answer
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	// ============================================================================
+	// Validation endpoints
+	// ============================================================================
+	async getTasksAwaitingValidation(projectId: string): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			completed_at?: string;
+			completed_by_session_id?: string;
+		}>;
+	}>> {
+		return this.proxy('get_tasks_awaiting_validation', { project_id: projectId });
+	}
+
+	async claimValidation(taskId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+	}>> {
+		return this.proxy('claim_validation', { task_id: taskId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async validateTask(taskId: string, params: {
+		approved: boolean;
+		validation_notes?: string;
+		skip_pr_check?: boolean;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		approved: boolean;
+		task_id: string;
+		message?: string;
+		workflow?: string;
+	}>> {
+		return this.proxy('validate_task', {
+			task_id: taskId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	// ============================================================================
+	// Fallback activity endpoints
+	// ============================================================================
+	async startFallbackActivity(projectId: string, activity: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		activity: string;
+		message: string;
+		git_workflow?: {
+			workflow: string;
+			base_branch: string;
+			worktree_recommended: boolean;
+			note: string;
+		};
+		worktree_setup?: {
+			message: string;
+			commands: string[];
+			worktree_path: string;
+			branch_name: string;
+			cleanup_command: string;
+			report_worktree: string;
+		};
+		next_step?: string;
+	}>> {
+		return this.proxy('start_fallback_activity', {
+			project_id: projectId,
+			activity
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async stopFallbackActivity(projectId: string, summary?: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('stop_fallback_activity', {
+			project_id: projectId,
+			summary
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async getActivityHistory(projectId: string, params?: {
+		activity_type?: string;
+		limit?: number;
+	}): Promise<ApiResponse<{
+		history: Array<{
+			id: string;
+			activity_type: string;
+			completed_at: string;
+			summary?: string;
+		}>;
+		latest_by_type: Record<string, unknown>;
+		count: number;
+	}>> {
+		return this.proxy('get_activity_history', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getActivitySchedules(projectId: string, params?: {
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		schedules: Array<{
+			id: string;
+			activity_type: string;
+			schedule_type: string;
+			next_run_at?: string;
+			enabled: boolean;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>> {
+		return this.proxy('get_activity_schedules', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	// ============================================================================
+	// Subtask endpoints
+	// ============================================================================
+	async addSubtask(parentTaskId: string, params: {
+		title: string;
+		description?: string;
+		priority?: number;
+		estimated_minutes?: number;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		subtask_id: string;
+		parent_task_id: string;
+	}>> {
+		return this.proxy('add_subtask', {
+			parent_task_id: parentTaskId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async getSubtasks(parentTaskId: string, status?: string): Promise<ApiResponse<{
+		subtasks: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+		}>;
+		stats: {
+			total: number;
+			completed: number;
+			progress_percentage: number;
+		};
+	}>> {
+		return this.proxy('get_subtasks', {
+			parent_task_id: parentTaskId,
+			status
+		});
+	}
+
+	// ============================================================================
+	// Activity feed endpoint
+	// ============================================================================
+	async getActivityFeed(projectId: string, params?: {
+		limit?: number;
+		since?: string;
+		types?: string[];
+		created_by?: string;
+	}): Promise<ApiResponse<{
+		activities: Array<{
+			type: string;
+			data: unknown;
+			timestamp: string;
+		}>;
+	}>> {
+		return this.proxy('get_activity_feed', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	// ============================================================================
+	// Deployment endpoints
+	// ============================================================================
+	async requestDeployment(projectId: string, params?: {
+		environment?: string;
+		version_bump?: string;
+		git_ref?: string;
+		notes?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		status: string;
+	}>> {
+		return this.proxy('request_deployment', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async checkDeploymentStatus(projectId: string): Promise<ApiResponse<{
+		active_deployment: boolean;
+		deployment?: {
+			id: string;
+			status: string;
+			environment: string;
+			git_ref?: string;
+			created_at: string;
+		};
+	}>> {
+		return this.proxy('check_deployment_status', { project_id: projectId });
+	}
+
+	async claimDeploymentValidation(projectId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		message: string;
+	}>> {
+		return this.proxy('claim_deployment_validation', { project_id: projectId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async reportValidation(projectId: string, params: {
+		build_passed: boolean;
+		tests_passed: boolean;
+		error_message?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		status: string;
+	}>> {
+		return this.proxy('report_validation', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async startDeployment(projectId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		instructions: string;
+	}>> {
+		return this.proxy('start_deployment', { project_id: projectId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async completeDeployment(projectId: string, params: {
+		success: boolean;
+		summary?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		status: string;
+	}>> {
+		return this.proxy('complete_deployment', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async cancelDeployment(projectId: string, reason?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('cancel_deployment', {
+			project_id: projectId,
+			reason
+		});
+	}
+
+	// ============================================================================
+	// Task reference endpoints
+	// ============================================================================
+	async addTaskReference(taskId: string, url: string, label?: string): Promise<ApiResponse<{
+		success: boolean;
+		reference: { url: string; label?: string };
+	}>> {
+		return this.proxy('add_task_reference', {
+			task_id: taskId,
+			url,
+			label
+		});
+	}
+
+	async removeTaskReference(taskId: string, url: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('remove_task_reference', {
+			task_id: taskId,
+			url
+		});
+	}
+
+	// ============================================================================
+	// Knowledge base endpoint
+	// ============================================================================
+	async queryKnowledgeBase(projectId: string, params?: {
+		scope?: 'summary' | 'detailed';
+		categories?: string[];
+		limit?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		findings?: Array<{ id: string; title: string; category: string; severity: string; description?: string }>;
+		decisions?: Array<{ id: string; title: string; description: string; rationale?: string }>;
+		completed_tasks?: Array<{ id: string; title: string; completed_at: string; summary?: string }>;
+		resolved_blockers?: Array<{ id: string; description: string; resolution_note?: string }>;
+		progress?: Array<{ id: string; summary: string; details?: string }>;
+		qa?: Array<{ id: string; question: string; answer: string }>;
+	}>> {
+		return this.proxy('query_knowledge_base', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	// ============================================================================
+	// Session sync endpoint
+	// ============================================================================
+	async syncSession(sessionId: string, params?: {
+		total_tokens?: number;
+		token_breakdown?: Record<string, unknown>;
+		model_usage?: Record<string, unknown>;
+	}): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('sync_session', {
+			session_id: sessionId,
+			...params
+		});
+	}
+
+	/**
+	 * Report actual API token usage for accurate cost tracking.
+	 * This records token usage to the session and attributes cost to the current task.
+	 */
+	async reportTokenUsage(sessionId: string, params: {
+		input_tokens: number;
+		output_tokens: number;
+		model?: 'opus' | 'sonnet' | 'haiku';
+	}): Promise<ApiResponse<{
+		success: boolean;
+		reported: {
+			session_id: string;
+			model: string;
+			input_tokens: number;
+			output_tokens: number;
+			total_tokens: number;
+			estimated_cost_usd: number;
+		};
+		task_attributed: boolean;
+		task_id?: string;
+	}>> {
+		return this.proxy('report_token_usage', {
+			session_id: sessionId,
+			...params
+		});
+	}
+
+	// ============================================================================
+	// Organization endpoints
+	// ============================================================================
+	async listOrganizations(): Promise<ApiResponse<{
+		organizations: Array<{
+			id: string;
+			name: string;
+			slug: string;
+			description?: string;
+			role: string;
+		}>;
+	}>> {
+		return this.proxy('list_organizations', {});
+	}
+
+	async createOrganization(params: {
+		name: string;
+		slug?: string;
+		description?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		organization: { id: string; name: string; slug: string };
+	}>> {
+		return this.proxy('create_organization', params);
+	}
+
+	async updateOrganization(organizationId: string, updates: {
+		name?: string;
+		description?: string;
+		logo_url?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		organization_id: string;
+	}>> {
+		return this.proxy('update_organization', {
+			organization_id: organizationId,
+			...updates
+		});
+	}
+
+	async deleteOrganization(organizationId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_organization', { organization_id: organizationId });
+	}
+
+	async listOrgMembers(organizationId: string): Promise<ApiResponse<{
+		members: Array<{
+			user_id: string;
+			email: string;
+			role: string;
+			joined_at: string;
+		}>;
+	}>> {
+		return this.proxy('list_org_members', { organization_id: organizationId });
+	}
+
+	async inviteMember(organizationId: string, email: string, role?: string): Promise<ApiResponse<{
+		success: boolean;
+		invite_id: string;
+	}>> {
+		return this.proxy('invite_member', {
+			organization_id: organizationId,
+			email,
+			role
+		});
+	}
+
+	async updateMemberRole(organizationId: string, userId: string, role: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('update_member_role', {
+			organization_id: organizationId,
+			user_id: userId,
+			role
+		});
+	}
+
+	async removeMember(organizationId: string, userId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('remove_member', {
+			organization_id: organizationId,
+			user_id: userId
+		});
+	}
+
+	async shareProjectWithOrg(projectId: string, organizationId: string, permission?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('share_project_with_org', {
+			project_id: projectId,
+			organization_id: organizationId,
+			permission
+		});
+	}
+
+	async unshareProject(projectId: string, organizationId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('unshare_project', {
+			project_id: projectId,
+			organization_id: organizationId
+		});
+	}
+
+	async leaveOrganization(organizationId: string): Promise<ApiResponse<{
+		success: boolean;
+		message: string;
+	}>> {
+		return this.proxy('leave_organization', { organization_id: organizationId });
+	}
+
+	async updateProjectShare(projectId: string, organizationId: string, permission: string): Promise<ApiResponse<{
+		success: boolean;
+		share: { permission: string };
+	}>> {
+		return this.proxy('update_project_share', {
+			project_id: projectId,
+			organization_id: organizationId,
+			permission
+		});
+	}
+
+	async listProjectShares(projectId: string): Promise<ApiResponse<{
+		shares: Array<{
+			id: string;
+			permission: string;
+			shared_at: string;
+			organization: { id: string; name: string; slug: string };
+		}>;
+		count: number;
+	}>> {
+		return this.proxy('list_project_shares', { project_id: projectId });
+	}
+
+	// ============================================================================
+	// Body of work endpoints
+	// ============================================================================
+	async createBodyOfWork(projectId: string, params: {
+		title: string;
+		description?: string;
+		auto_deploy_on_completion?: boolean;
+		deploy_environment?: string;
+		deploy_version_bump?: string;
+		deploy_trigger?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		body_of_work_id: string;
+	}>> {
+		return this.proxy('create_body_of_work', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getBodyOfWork(bodyOfWorkId: string): Promise<ApiResponse<{
+		body_of_work: {
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			auto_deploy_on_completion: boolean;
+		};
+		tasks: {
+			pre: Array<{ id: string; title: string; status: string }>;
+			core: Array<{ id: string; title: string; status: string }>;
+			post: Array<{ id: string; title: string; status: string }>;
+		};
+	}>> {
+		return this.proxy('get_body_of_work', { body_of_work_id: bodyOfWorkId });
+	}
+
+	async getBodiesOfWork(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		bodies_of_work: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			task_counts: { pre: number; core: number; post: number };
+		}>;
+	}>> {
+		return this.proxy('get_bodies_of_work', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async updateBodyOfWork(bodyOfWorkId: string, updates: {
+		title?: string;
+		description?: string;
+		auto_deploy_on_completion?: boolean;
+		deploy_environment?: string;
+		deploy_version_bump?: string;
+		deploy_trigger?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('update_body_of_work', {
+			body_of_work_id: bodyOfWorkId,
+			...updates
+		});
+	}
+
+	async deleteBodyOfWork(bodyOfWorkId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_body_of_work', { body_of_work_id: bodyOfWorkId });
+	}
+
+	async addTaskToBodyOfWork(bodyOfWorkId: string, taskId: string, phase?: string, orderIndex?: number): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('add_task_to_body_of_work', {
+			body_of_work_id: bodyOfWorkId,
+			task_id: taskId,
+			phase,
+			order_index: orderIndex
+		});
+	}
+
+	async removeTaskFromBodyOfWork(taskId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('remove_task_from_body_of_work', { task_id: taskId });
+	}
+
+	async activateBodyOfWork(bodyOfWorkId: string): Promise<ApiResponse<{
+		success: boolean;
+		status: string;
+	}>> {
+		return this.proxy('activate_body_of_work', { body_of_work_id: bodyOfWorkId });
+	}
+
+	async addTaskDependency(bodyOfWorkId: string, taskId: string, dependsOnTaskId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('add_task_dependency', {
+			body_of_work_id: bodyOfWorkId,
+			task_id: taskId,
+			depends_on_task_id: dependsOnTaskId
+		});
+	}
+
+	async removeTaskDependency(taskId: string, dependsOnTaskId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('remove_task_dependency', {
+			task_id: taskId,
+			depends_on_task_id: dependsOnTaskId
+		});
+	}
+
+	async getTaskDependencies(params: {
+		body_of_work_id?: string;
+		task_id?: string;
+	}): Promise<ApiResponse<{
+		dependencies: Array<{
+			id: string;
+			task_id: string;
+			depends_on_task_id: string;
+			created_at: string;
+		}>;
+	}>> {
+		return this.proxy('get_task_dependencies', params);
+	}
+
+	async getNextBodyOfWorkTask(bodyOfWorkId: string): Promise<ApiResponse<{
+		task?: {
+			id: string;
+			title: string;
+			priority: number;
+			phase: string;
+		} | null;
+		message?: string;
+	}>> {
+		return this.proxy('get_next_body_of_work_task', { body_of_work_id: bodyOfWorkId });
+	}
+
+	// ============================================================================
+	// Git issues endpoints
+	// ============================================================================
+	async addGitIssue(projectId: string, params: {
+		issue_type: string;
+		branch: string;
+		target_branch?: string;
+		pr_url?: string;
+		conflicting_files?: string[];
+		error_message?: string;
+		task_id?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		git_issue_id: string;
+	}>> {
+		return this.proxy('add_git_issue', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async resolveGitIssue(gitIssueId: string, params?: {
+		resolution_note?: string;
+		auto_resolved?: boolean;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		git_issue_id: string;
+	}>> {
+		return this.proxy('resolve_git_issue', {
+			git_issue_id: gitIssueId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async getGitIssues(projectId: string, params?: {
+		status?: string;
+		issue_type?: string;
+		branch?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		git_issues: Array<{
+			id: string;
+			issue_type: string;
+			branch: string;
+			target_branch?: string;
+			pr_url?: string;
+			conflicting_files?: string[];
+			error_message?: string;
+			status: string;
+			created_at: string;
+			resolved_at?: string;
+		}>;
+	}>> {
+		return this.proxy('get_git_issues', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async deleteGitIssue(gitIssueId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_git_issue', { git_issue_id: gitIssueId });
+	}
+
+	// ============================================================================
+	// Cost tracking endpoints
+	// ============================================================================
+	async getCostSummary(projectId: string, params?: {
+		period?: 'daily' | 'weekly' | 'monthly';
+		limit?: number;
+	}): Promise<ApiResponse<{
+		summaries: Array<{
+			date: string;
+			total_cost: number;
+			input_tokens: number;
+			output_tokens: number;
+		}>;
+	}>> {
+		return this.proxy('get_cost_summary', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getCostAlerts(): Promise<ApiResponse<{
+		alerts: Array<{
+			id: string;
+			threshold_amount: number;
+			threshold_period: string;
+			alert_type: string;
+			enabled: boolean;
+		}>;
+	}>> {
+		return this.proxy('get_cost_alerts', {});
+	}
+
+	async addCostAlert(params: {
+		threshold_amount: number;
+		threshold_period: 'daily' | 'weekly' | 'monthly';
+		alert_type?: 'warning' | 'critical';
+		project_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		alert_id: string;
+	}>> {
+		return this.proxy('add_cost_alert', params);
+	}
+
+	async updateCostAlert(alertId: string, updates: {
+		threshold_amount?: number;
+		threshold_period?: string;
+		alert_type?: string;
+		enabled?: boolean;
+	}): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('update_cost_alert', {
+			alert_id: alertId,
+			...updates
+		});
+	}
+
+	async deleteCostAlert(alertId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_cost_alert', { alert_id: alertId });
+	}
+
+	async getTaskCosts(projectId: string, limit?: number): Promise<ApiResponse<{
+		task_costs: Array<{
+			task_id: string;
+			title: string;
+			total_cost: number;
+			input_tokens: number;
+			output_tokens: number;
+		}>;
+	}>> {
+		return this.proxy('get_task_costs', {
+			project_id: projectId,
+			limit
+		});
+	}
+
+	async getBodyOfWorkCosts(params: {
+		body_of_work_id?: string;
+		project_id?: string;
+	}): Promise<ApiResponse<{
+		bodies_of_work: Array<{
+			body_of_work_id: string;
+			title: string;
+			project_id: string;
+			status: string;
+			task_count: number;
+			total_cost_usd: number;
+			total_tokens: number;
+			pre_phase_cost_usd: number;
+			core_phase_cost_usd: number;
+			post_phase_cost_usd: number;
+			model_breakdown: Record<string, { input: number; output: number }>;
+		}>;
+		count: number;
+		totals: {
+			total_cost_usd: number;
+			total_tokens: number;
+			total_tasks: number;
+		};
+	}>> {
+		return this.proxy('get_body_of_work_costs', params);
+	}
+
+	async getSprintCosts(params: {
+		sprint_id?: string;
+		project_id?: string;
+	}): Promise<ApiResponse<{
+		sprints: Array<{
+			sprint_id: string;
+			title: string;
+			project_id: string;
+			status: string;
+			sprint_number: number;
+			task_count: number;
+			total_cost_usd: number;
+			total_tokens: number;
+			cost_per_story_point: number | null;
+			committed_points: number;
+			velocity_points: number;
+			model_breakdown: Record<string, { input: number; output: number }>;
+		}>;
+		count: number;
+		totals: {
+			total_cost_usd: number;
+			total_tokens: number;
+			total_tasks: number;
+			total_velocity_points: number;
+			avg_cost_per_point: number | null;
+		};
+	}>> {
+		return this.proxy('get_sprint_costs', params);
+	}
+
+	async getTokenUsage(): Promise<ApiResponse<{
+		session_tokens: number;
+		estimated_cost: number;
+	}>> {
+		return this.proxy('get_token_usage', {});
+	}
+
+	// ============================================================================
+	// Batch operation endpoints
+	// ============================================================================
+	async batchUpdateTasks(updates: Array<{
+		task_id: string;
+		status?: string;
+		priority?: number;
+		progress_percentage?: number;
+		progress_note?: string;
+	}>): Promise<ApiResponse<{
+		success: boolean;
+		updated_count: number;
+	}>> {
+		return this.proxy('batch_update_tasks', { updates });
+	}
+
+	async batchCompleteTasks(completions: Array<{
+		task_id: string;
+		summary?: string;
+	}>): Promise<ApiResponse<{
+		success: boolean;
+		completed_count: number;
+		next_task?: { id: string; title: string } | null;
+	}>> {
+		return this.proxy('batch_complete_tasks', { completions });
+	}
+
+	// ============================================================================
+	// Deployment requirements and scheduling endpoints
+	// ============================================================================
+	async addDeploymentRequirement(projectId: string, params: {
+		type: string;
+		title: string;
+		description?: string;
+		file_path?: string;
+		stage?: string;
+		blocking?: boolean;
+		recurring?: boolean;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		requirement_id: string;
+	}>> {
+		return this.proxy('add_deployment_requirement', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getDeploymentRequirements(projectId: string, params?: {
+		status?: string;
+		stage?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		requirements: Array<{
+			id: string;
+			type: string;
+			title: string;
+			description?: string;
+			status: string;
+			stage: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>> {
+		return this.proxy('get_deployment_requirements', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getDeploymentRequirementsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: Record<string, number>;
+		by_stage: Record<string, number>;
+		by_type: Record<string, number>;
+	}>> {
+		return this.proxy('get_deployment_requirements_stats', {
+			project_id: projectId
+		});
+	}
+
+	async completeDeploymentRequirement(requirementId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('complete_deployment_requirement', { requirement_id: requirementId });
+	}
+
+	async scheduleDeployment(projectId: string, params: {
+		scheduled_at: string;
+		schedule_type?: string;
+		environment?: string;
+		version_bump?: string;
+		auto_trigger?: boolean;
+		hours_interval?: number;
+		notes?: string;
+		git_ref?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		schedule_id: string;
+	}>> {
+		return this.proxy('schedule_deployment', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getScheduledDeployments(projectId: string, params?: {
+		includeDisabled?: boolean;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		schedules: Array<{
+			id: string;
+			scheduled_at: string;
+			schedule_type: string;
+			hours_interval: number;
+			environment: string;
+			version_bump: string;
+			auto_trigger: boolean;
+			enabled: boolean;
+			git_ref?: string;
+			notes?: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>> {
+		return this.proxy('get_scheduled_deployments', {
+			project_id: projectId,
+			include_disabled: params?.includeDisabled,
+			limit: params?.limit,
+			offset: params?.offset
+		});
+	}
+
+	async updateScheduledDeployment(scheduleId: string, updates: {
+		scheduled_at?: string;
+		schedule_type?: string;
+		hours_interval?: number;
+		environment?: string;
+		version_bump?: string;
+		auto_trigger?: boolean;
+		enabled?: boolean;
+		git_ref?: string;
+		notes?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		schedule_id: string;
+	}>> {
+		return this.proxy('update_scheduled_deployment', {
+			schedule_id: scheduleId,
+			...updates
+		});
+	}
+
+	async deleteScheduledDeployment(scheduleId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_scheduled_deployment', { schedule_id: scheduleId });
+	}
+
+	async triggerScheduledDeployment(scheduleId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id?: string;
+		schedule_id: string;
+		schedule_type: string;
+		next_scheduled_at?: string;
+		message?: string;
+	}>> {
+		return this.proxy('trigger_scheduled_deployment', { schedule_id: scheduleId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async checkDueDeployments(projectId: string): Promise<ApiResponse<{
+		due_schedules: Array<{
+			id: string;
+			scheduled_at: string;
+			environment: string;
+			version_bump: string;
+			schedule_type: string;
+		}>;
+		count: number;
+	}>> {
+		return this.proxy('check_due_deployments', { project_id: projectId });
+	}
+
+	// ============================================================================
+	// Project README endpoint
+	// ============================================================================
+	async updateProjectReadme(projectId: string, readmeContent: string): Promise<ApiResponse<{
+		success: boolean;
+		project_id: string;
+	}>> {
+		return this.proxy('update_project_readme', {
+			project_id: projectId,
+			readme_content: readmeContent
+		});
+	}
+
+	async getProjectSummary(projectId: string): Promise<ApiResponse<{
+		project: {
+			id: string;
+			name: string;
+			description?: string;
+			goal?: string;
+			status: string;
+			git_url?: string;
+			tech_stack?: string[];
+			git_workflow?: string;
+		};
+		tasks: {
+			total: number;
+			by_status: Record<string, number>;
+		};
+		blockers: {
+			total: number;
+			open: number;
+			resolved: number;
+		};
+		findings: {
+			total: number;
+			by_severity: Record<string, number>;
+			by_status: Record<string, number>;
+		};
+		agents: {
+			active_count: number;
+			total_tokens_this_session: number;
+			total_tool_calls: number;
+		};
+		activity: {
+			tasks_completed_today: number;
+			progress_entries_today: number;
+		};
+		deployment: {
+			active: boolean;
+			status: string | null;
+			last_deployment_at: string | null;
+		};
+		planning: {
+			active_sprints: number;
+			active_bodies_of_work: number;
+			pending_deployment_requirements: number;
+		};
+	}>> {
+		return this.proxy('get_project_summary', { project_id: projectId });
+	}
+
+	// ============================================================================
+	// Help Topics (database-backed)
+	// ============================================================================
+	async getHelpTopic(slug: string): Promise<ApiResponse<{
+		slug: string;
+		title: string;
+		content: string;
+	} | null>> {
+		return this.proxy('get_help_topic', { slug });
+	}
+
+	async getHelpTopics(): Promise<ApiResponse<Array<{
+		slug: string;
+		title: string;
+	}>>> {
+		return this.proxy('get_help_topics', {});
+	}
+
+	// ============================================================================
+	// File Checkout endpoints (multi-agent coordination)
+	// ============================================================================
+	async checkoutFile(projectId: string, filePath: string, reason?: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		checkout_id: string;
+		file_path: string;
+		already_checked_out?: boolean;
+		message: string;
+	}>> {
+		return this.proxy('checkout_file', {
+			project_id: projectId,
+			file_path: filePath,
+			reason
+		}, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async checkinFile(params: {
+		checkout_id?: string;
+		project_id?: string;
+		file_path?: string;
+		summary?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		checkout_id: string;
+		message: string;
+	}>> {
+		return this.proxy('checkin_file', params, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async getFileCheckouts(projectId: string, options?: {
+		status?: string;
+		file_path?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		checkouts: Array<{
+			id: string;
+			file_path: string;
+			status: string;
+			checked_out_at: string;
+			checkout_reason?: string;
+			checked_in_at?: string;
+			checkin_summary?: string;
+			checked_out_by?: string;
+		}>;
+	}>> {
+		return this.proxy('get_file_checkouts', {
+			project_id: projectId,
+			...options
+		});
+	}
+
+	async abandonCheckout(params: {
+		checkout_id?: string;
+		project_id?: string;
+		file_path?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		checkout_id: string;
+		message: string;
+	}>> {
+		return this.proxy('abandon_checkout', params);
+	}
+
+	async getFileCheckoutsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: Record<string, number>;
+	}>> {
+		return this.proxy('get_file_checkouts_stats', { project_id: projectId });
+	}
+
+	// ============================================================================
+	// Worktree Management
+	// ============================================================================
+
+	async getStaleWorktrees(projectId: string, params?: {
+		hostname?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		project_id: string;
+		project_name: string;
+		hostname_filter: string | null;
+		stale_worktrees: Array<{
+			task_id: string;
+			task_title: string;
+			worktree_path: string;
+			worktree_hostname: string | null;
+			git_branch: string | null;
+			status: string;
+			completed_at: string | null;
+			updated_at: string;
+			pr_url: string | null;
+			stale_reason: 'task_finished' | 'potentially_abandoned';
+			can_cleanup_locally: boolean;
+		}>;
+		count: number;
+		local_count: number;
+		remote_count: number;
+		total_count: number;
+		has_more: boolean;
+		cleanup_instructions: string[] | null;
+		remote_worktree_note: string | null;
+	}>> {
+		const queryParams = new URLSearchParams({ project_id: projectId });
+		if (params?.hostname !== undefined) queryParams.set('hostname', params.hostname);
+		if (params?.limit !== undefined) queryParams.set('limit', String(params.limit));
+		if (params?.offset !== undefined) queryParams.set('offset', String(params.offset));
+		return this.request('GET', `/api/mcp/worktrees/stale?${queryParams.toString()}`);
+	}
+
+	async clearWorktreePath(taskId: string): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+	}>> {
+		return this.request('PATCH', `/api/mcp/tasks/${taskId}`, { worktree_path: null });
+	}
+
+	// ============================================================================
+	// Connector endpoints
+	// ============================================================================
+
+	async getConnectors(projectId: string, params?: {
+		type?: string;
+		status?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		connectors: Array<{
+			id: string;
+			name: string;
+			type: string;
+			description?: string;
+			status: string;
+			events: Record<string, boolean>;
+			events_sent: number;
+			last_triggered_at?: string;
+			last_error?: string;
+			last_error_at?: string;
+			created_at: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>> {
+		return this.proxy('get_connectors', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getConnector(connectorId: string): Promise<ApiResponse<{
+		connector: {
+			id: string;
+			name: string;
+			type: string;
+			description?: string;
+			config: Record<string, unknown>;
+			events: Record<string, boolean>;
+			status: string;
+			events_sent: number;
+			last_triggered_at?: string;
+			last_error?: string;
+			last_error_at?: string;
+			created_at: string;
+		};
+	}>> {
+		return this.proxy('get_connector', { connector_id: connectorId });
+	}
+
+	async addConnector(projectId: string, params: {
+		name: string;
+		type: string;
+		description?: string;
+		config?: Record<string, unknown>;
+		events?: Record<string, boolean>;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		connector_id: string;
+	}>> {
+		return this.proxy('add_connector', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async updateConnector(connectorId: string, updates: {
+		name?: string;
+		description?: string;
+		config?: Record<string, unknown>;
+		events?: Record<string, boolean>;
+		status?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		connector_id: string;
+	}>> {
+		return this.proxy('update_connector', {
+			connector_id: connectorId,
+			...updates
+		});
+	}
+
+	async deleteConnector(connectorId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_connector', { connector_id: connectorId });
+	}
+
+	async testConnector(connectorId: string): Promise<ApiResponse<{
+		success: boolean;
+		event_id: string;
+		status?: number;
+		error?: string;
+	}>> {
+		return this.proxy('test_connector', { connector_id: connectorId });
+	}
+
+	async getConnectorEvents(params: {
+		connector_id?: string;
+		project_id?: string;
+		status?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		events: Array<{
+			id: string;
+			connector_id: string;
+			event_type: string;
+			status: string;
+			response_status?: number;
+			error_message?: string;
+			attempts: number;
+			created_at: string;
+			sent_at?: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>> {
+		return this.proxy('get_connector_events', params);
+	}
+
+	// ============================================================================
+	// Agent onboarding endpoints
+	// ============================================================================
+
+	/**
+	 * Confirm that agent setup is complete for a project.
+	 * This marks the agent type as onboarded so future sessions don't receive setup instructions.
+	 */
+	async confirmAgentSetup(projectId: string, agentType: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'): Promise<ApiResponse<{
+		success: boolean;
+		project_id: string;
+		agent_type: string;
+	}>> {
+		return this.proxy('confirm_agent_setup', {
+			project_id: projectId,
+			agent_type: agentType
+		});
+	}
+}
+
+// Singleton instance
+let apiClient: VibescopeApiClient | null = null;
+
+export function getApiClient(): VibescopeApiClient {
+	if (!apiClient) {
+		const apiKey = process.env.VIBESCOPE_API_KEY;
+		if (!apiKey) {
+			throw new Error('VIBESCOPE_API_KEY environment variable is required');
+		}
+		apiClient = new VibescopeApiClient({ apiKey });
+	}
+	return apiClient;
+}
+
+export function initApiClient(config: ApiClientConfig): VibescopeApiClient {
+	apiClient = new VibescopeApiClient(config);
+	return apiClient;
+}