docs: Add comprehensive JSDoc docstrings to settings module (80% coverage)

This commit addresses CodeRabbit feedback from PR #186 by adding detailed
documentation to all public APIs in the settings module:

**Server-side documentation:**
- SettingsService class: 12 public methods with parameter and return types
- Settings types (settings.ts): All type aliases, interfaces, and constants
  documented with usage context
- Route handlers (8 endpoints): Complete endpoint documentation with request/response
  schemas
- Automaker paths utilities: All 13 path resolution functions fully documented

**Client-side documentation:**
- useSettingsMigration hook: Migration flow and state documented
- Sync functions: Three sync helpers (settings, credentials, project) with usage guidelines
- localStorage constants: Clear documentation of migration keys and cleanup strategy

All docstrings follow JSDoc format with:
- Purpose and behavior description
- Parameter documentation with types
- Return value documentation
- Usage examples where applicable
- Cross-references between related functions

This improves code maintainability, IDE autocomplete, and developer onboarding.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

apps/server/src/lib/automaker-paths.ts

@@ -1,15 +1,25 @@
 /**
  * Automaker Paths - Utilities for managing automaker data storage
  *
- * Stores project data inside the project directory at {projectPath}/.automaker/
+ * Provides functions to construct paths for:
+ * - Project-level data stored in {projectPath}/.automaker/
+ * - Global user data stored in app userData directory
+ *
+ * All returned paths are absolute and ready to use with fs module.
+ * Directory creation is handled separately by ensure* functions.
  */
 
 import fs from "fs/promises";
 import path from "path";
 
 /**
- * Get the automaker data directory for a project
- * This is stored inside the project at .automaker/
+ * Get the automaker data directory root for a project
+ *
+ * All project-specific automaker data is stored under {projectPath}/.automaker/
+ * This directory is created when needed via ensureAutomakerDir().
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Absolute path to {projectPath}/.automaker
  */
 export function getAutomakerDir(projectPath: string): string {
   return path.join(projectPath, ".automaker");
@@ -17,6 +27,11 @@ export function getAutomakerDir(projectPath: string): string {
 
 /**
  * Get the features directory for a project
+ *
+ * Contains subdirectories for each feature, keyed by featureId.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Absolute path to {projectPath}/.automaker/features
  */
 export function getFeaturesDir(projectPath: string): string {
   return path.join(getAutomakerDir(projectPath), "features");
@@ -24,6 +39,12 @@ export function getFeaturesDir(projectPath: string): string {
 
 /**
  * Get the directory for a specific feature
+ *
+ * Contains feature-specific data like generated code, tests, and logs.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @param featureId - Feature identifier
+ * @returns Absolute path to {projectPath}/.automaker/features/{featureId}
  */
 export function getFeatureDir(projectPath: string, featureId: string): string {
   return path.join(getFeaturesDir(projectPath), featureId);
@@ -31,6 +52,12 @@ export function getFeatureDir(projectPath: string, featureId: string): string {
 
 /**
  * Get the images directory for a feature
+ *
+ * Stores screenshots, diagrams, or other images related to the feature.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @param featureId - Feature identifier
+ * @returns Absolute path to {projectPath}/.automaker/features/{featureId}/images
  */
 export function getFeatureImagesDir(
   projectPath: string,
@@ -40,21 +67,36 @@ export function getFeatureImagesDir(
 }
 
 /**
- * Get the board directory for a project (board backgrounds, etc.)
+ * Get the board directory for a project
+ *
+ * Contains board-related data like background images and customization files.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Absolute path to {projectPath}/.automaker/board
  */
 export function getBoardDir(projectPath: string): string {
   return path.join(getAutomakerDir(projectPath), "board");
 }
 
 /**
- * Get the images directory for a project (general images)
+ * Get the general images directory for a project
+ *
+ * Stores project-level images like background images or shared assets.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Absolute path to {projectPath}/.automaker/images
  */
 export function getImagesDir(projectPath: string): string {
   return path.join(getAutomakerDir(projectPath), "images");
 }
 
 /**
- * Get the context files directory for a project (user-added context files)
+ * Get the context files directory for a project
+ *
+ * Stores user-uploaded context files for reference during generation.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Absolute path to {projectPath}/.automaker/context
  */
 export function getContextDir(projectPath: string): string {
   return path.join(getAutomakerDir(projectPath), "context");
@@ -62,6 +104,11 @@ export function getContextDir(projectPath: string): string {
 
 /**
  * Get the worktrees metadata directory for a project
+ *
+ * Stores information about git worktrees associated with the project.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Absolute path to {projectPath}/.automaker/worktrees
  */
 export function getWorktreesDir(projectPath: string): string {
   return path.join(getAutomakerDir(projectPath), "worktrees");
@@ -69,6 +116,11 @@ export function getWorktreesDir(projectPath: string): string {
 
 /**
  * Get the app spec file path for a project
+ *
+ * Stores the application specification document used for generation.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Absolute path to {projectPath}/.automaker/app_spec.txt
  */
 export function getAppSpecPath(projectPath: string): string {
   return path.join(getAutomakerDir(projectPath), "app_spec.txt");
@@ -76,13 +128,24 @@ export function getAppSpecPath(projectPath: string): string {
 
 /**
  * Get the branch tracking file path for a project
+ *
+ * Stores JSON metadata about active git branches and worktrees.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Absolute path to {projectPath}/.automaker/active-branches.json
  */
 export function getBranchTrackingPath(projectPath: string): string {
   return path.join(getAutomakerDir(projectPath), "active-branches.json");
 }
 
 /**
- * Ensure the automaker directory structure exists for a project
+ * Create the automaker directory structure for a project if it doesn't exist
+ *
+ * Creates {projectPath}/.automaker with all subdirectories recursively.
+ * Safe to call multiple times - uses recursive: true.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Promise resolving to the created automaker directory path
  */
 export async function ensureAutomakerDir(projectPath: string): Promise<string> {
   const automakerDir = getAutomakerDir(projectPath);
@@ -96,29 +159,56 @@ export async function ensureAutomakerDir(projectPath: string): Promise<string> {
 
 /**
  * Get the global settings file path
- * DATA_DIR is typically ~/Library/Application Support/automaker (macOS)
- * or %APPDATA%\automaker (Windows) or ~/.config/automaker (Linux)
+ *
+ * Stores user preferences, keyboard shortcuts, AI profiles, and project history.
+ * Located in the platform-specific userData directory.
+ *
+ * Default locations:
+ * - macOS: ~/Library/Application Support/automaker
+ * - Windows: %APPDATA%\automaker
+ * - Linux: ~/.config/automaker
+ *
+ * @param dataDir - User data directory (from app.getPath('userData'))
+ * @returns Absolute path to {dataDir}/settings.json
  */
 export function getGlobalSettingsPath(dataDir: string): string {
   return path.join(dataDir, "settings.json");
 }
 
 /**
- * Get the credentials file path (separate from settings for security)
+ * Get the credentials file path
+ *
+ * Stores sensitive API keys separately from other settings for security.
+ * Located in the platform-specific userData directory.
+ *
+ * @param dataDir - User data directory (from app.getPath('userData'))
+ * @returns Absolute path to {dataDir}/credentials.json
  */
 export function getCredentialsPath(dataDir: string): string {
   return path.join(dataDir, "credentials.json");
 }
 
 /**
- * Get the project settings file path within a project's .automaker directory
+ * Get the project settings file path
+ *
+ * Stores project-specific settings that override global settings.
+ * Located within the project's .automaker directory.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Absolute path to {projectPath}/.automaker/settings.json
  */
 export function getProjectSettingsPath(projectPath: string): string {
   return path.join(getAutomakerDir(projectPath), "settings.json");
 }
 
 /**
- * Ensure the global data directory exists
+ * Create the global data directory if it doesn't exist
+ *
+ * Creates the userData directory for storing global settings and credentials.
+ * Safe to call multiple times - uses recursive: true.
+ *
+ * @param dataDir - User data directory path to create
+ * @returns Promise resolving to the created data directory path
  */
 export async function ensureDataDir(dataDir: string): Promise<string> {
   await fs.mkdir(dataDir, { recursive: true });