diff --git a/scripts/check-project-structure.ts b/scripts/check-project-structure.ts
index a88aa9c..f9f2ab5 100644
--- a/scripts/check-project-structure.ts
+++ b/scripts/check-project-structure.ts
@@ -14,6 +14,12 @@ type CheckResult = {
   errors: string[];
 };
 
+/**
+ * Validate that a scaffolded project path exists, is a directory, and contains a file named `package.json`.
+ *
+ * @param projectPath - Filesystem path to the project directory to validate
+ * @returns A `CheckResult` where `passed` is `true` if all checks succeed; otherwise `passed` is `false` and `errors` contains descriptive failure messages
+ */
 export function checkProjectStructure(projectPath: string): CheckResult {
   const errors: string[] = [];
 
@@ -79,4 +85,3 @@ if (require.main === module) {
     process.exit(1);
   }
 }
-
diff --git a/scripts/functional-tests/api-endpoint-tester.ts b/scripts/functional-tests/api-endpoint-tester.ts
index b408e7a..2e5c89e 100644
--- a/scripts/functional-tests/api-endpoint-tester.ts
+++ b/scripts/functional-tests/api-endpoint-tester.ts
@@ -11,6 +11,21 @@ export type APIEndpointResult = {
   warnings: string[];
 };
 
+/**
+ * Performs API endpoint checks against a scaffolded project.
+ *
+ * The function attempts to validate the project's HTTP endpoints given a running server. Currently the implementation is a placeholder that records informational warnings about incomplete testing and the need for a reachable server.
+ *
+ * @param _projectPath - Filesystem path to the project whose endpoints should be tested
+ * @param _serverUrl - Base URL of the running server to test against (e.g., `http://localhost:3000`)
+ * @param _config - Optional test configuration:
+ *   - `authProvider`: name of the authentication provider to consider when selecting auth-related checks
+ *   - `frontends`: list of frontend identifiers (for example `['react','vue']`) to guide frontend-specific route checks
+ * @returns An object describing the results:
+ *   - `passed`: `true` if all executed checks passed, `false` otherwise
+ *   - `errors`: array of failure messages for checks that did not pass
+ *   - `warnings`: array of informational messages or reminders (currently includes placeholders about incomplete implementation and server availability)
+ */
 export async function testAPIEndpoints(
   _projectPath: string,
   _serverUrl: string = 'http://localhost:3000',
@@ -70,4 +85,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/auth-test-runner.ts b/scripts/functional-tests/auth-test-runner.ts
index 0ce264b..22b0e9d 100644
--- a/scripts/functional-tests/auth-test-runner.ts
+++ b/scripts/functional-tests/auth-test-runner.ts
@@ -32,6 +32,12 @@ type AuthTestResult = {
 
 const SUPPORTED_DATABASE_ENGINES = new Set(['sqlite', 'mongodb']);
 
+/**
+ * Constructs a deterministic, filesystem-safe project name for a scaffolded auth test from a test matrix entry.
+ *
+ * @param config - Configuration entry describing frontend, database engine, ORM, database host, and tailwind usage
+ * @returns A normalized project name of the form `test-auth-<frontend>-<databaseEngine>-<orm>-<databaseHostLabel>-<tw|notw>`
+ */
 function buildProjectName(config: TestMatrixEntry): string {
   const hostLabel = config.databaseHost === 'none' ? 'local' : config.databaseHost;
   const tailwindLabel = config.useTailwind ? 'tw' : 'notw';
@@ -41,6 +47,13 @@ function buildProjectName(config: TestMatrixEntry): string {
     .replace(/-+/g, '-');
 }
 
+/**
+ * Build the Bun CLI argument list to scaffold a project that matches the provided test configuration.
+ *
+ * @param projectName - Target project name used by the scaffold command
+ * @param config - Test matrix entry whose fields determine which CLI flags are appended
+ * @returns An array of command arguments for invoking the scaffold script (base command plus flags that reflect frontend, database engine, ORM, database host, auth provider, code quality tool, Tailwind usage, and directory configuration)
+ */
 function buildScaffoldCommand(
   projectName: string,
   config: TestMatrixEntry
@@ -90,6 +103,12 @@ function buildScaffoldCommand(
   return cmd;
 }
 
+/**
+ * Scaffolds a project for the given test configuration, runs dependency installation and auth validation, and aggregates results.
+ *
+ * @param config - A test matrix entry describing the project configuration to scaffold and validate (frontend, databaseEngine, orm, databaseHost, authProvider, codeQualityTool, useTailwind, directoryConfig).
+ * @returns An AuthTestResult describing the evaluated configuration, whether validation passed, collected error and warning messages, and the total test duration in milliseconds (`testTime`).
+ */
 async function scaffoldAndTestAuth(
   config: TestMatrixEntry
 ): Promise<AuthTestResult> {
@@ -264,6 +283,14 @@ async function scaffoldAndTestAuth(
   }
 }
 
+/**
+ * Runs auth validation across a matrix of test configurations and exits the process with a success or failure code.
+ *
+ * Reads the JSON matrix from `matrixFile`, filters entries to those with an auth provider and a supported database engine, and (optionally) limits the set to the first `testSubset` entries. For each configuration it scaffolds, installs, and validates the project, printing per-config progress and a final summary. If any configuration fails validation, the process exits with code `1`; if all pass, the process exits with code `0`.
+ *
+ * @param matrixFile - Path to the JSON test matrix file (defaults to 'test-matrix.json')
+ * @param testSubset - Optional maximum number of configurations from the filtered set to test
+ */
 async function runAuthTests(
   matrixFile: string = 'test-matrix.json',
   testSubset?: number
@@ -340,4 +367,3 @@ if (require.main === module) {
   });
 }
 
-
diff --git a/scripts/functional-tests/auth-validator.ts b/scripts/functional-tests/auth-validator.ts
index 6d03a63..7f56b9a 100644
--- a/scripts/functional-tests/auth-validator.ts
+++ b/scripts/functional-tests/auth-validator.ts
@@ -40,6 +40,23 @@ const relationalEngines = new Set([
   'mysql'
 ]);
 
+/**
+ * Validates that a scaffolded project's authentication configuration and wiring are present and correct.
+ *
+ * Performs checks for a user handler, database schema (engine- and ORM-aware), server plugin wiring, and
+ * presence of the `@absolutejs/auth` dependency, then optionally runs shared functional tests and aggregates results.
+ *
+ * @param projectPath - Filesystem path to the project root to validate
+ * @param packageManager - Package manager to use when running functional tests (`bun`, `npm`, `pnpm`, or `yarn`)
+ * @param config - Validator configuration: may include `databaseEngine` (e.g., 'sqlite', 'postgresql', 'mysql', 'mongodb', or 'none'), `orm` (e.g., 'drizzle'), and `authProvider`
+ * @param options - Runtime options to alter test behavior; supports `skipDependencies`, `skipBuild`, and `skipServer` flags
+ * @returns An AuthValidationResult containing:
+ *  - `passed`: `true` if all required checks and (if run) functional tests passed, `false` otherwise;
+ *  - `errors`: list of failure messages observed during validation;
+ *  - `warnings`: list of non-fatal observations or coverage gaps;
+ *  - `functionalTestResults` (optional): aggregated results from the shared functional test suite when executed;
+ *  - `authSpecific`: object with boolean flags `handlerExists`, `schemaIncludesUsers`, `serverUsesAuth`, and `packageHasAuthDependency` indicating individual check outcomes.
+ */
 export async function validateAuthConfiguration(
   projectPath: string,
   packageManager: 'bun' | 'npm' | 'pnpm' | 'yarn' = 'bun',
@@ -273,4 +290,3 @@ if (require.main === module) {
     });
 }
 
-
diff --git a/scripts/functional-tests/build-validator.ts b/scripts/functional-tests/build-validator.ts
index 91d3df2..59962dd 100644
--- a/scripts/functional-tests/build-validator.ts
+++ b/scripts/functional-tests/build-validator.ts
@@ -13,7 +13,13 @@ export type BuildResult = {
   compileTime?: number;
 };
 
-const COMPILE_TIMEOUT = 60000; // 60 seconds
+const COMPILE_TIMEOUT = 60000; /**
+ * Validates that a scaffolded project compiles by checking for tsconfig.json, ensuring package.json has a `typecheck` script, and running that script.
+ *
+ * @param projectPath - Path to the project directory to validate
+ * @param packageManager - Package manager to run the `typecheck` script with (`'bun' | 'npm' | 'pnpm' | 'yarn'`); defaults to `'bun'`
+ * @returns A BuildResult where `passed` is `true` when compilation succeeds, `errors` contains failure messages when present, and `compileTime` (milliseconds) is included when a compilation attempt was performed
+ */
 
 export async function validateBuild(
   projectPath: string,
@@ -137,4 +143,3 @@ if (import.meta.main) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/cloud-provider-test-runner.ts b/scripts/functional-tests/cloud-provider-test-runner.ts
index e06a0c6..ccc23bb 100644
--- a/scripts/functional-tests/cloud-provider-test-runner.ts
+++ b/scripts/functional-tests/cloud-provider-test-runner.ts
@@ -30,6 +30,12 @@ type CloudProviderTestResult = {
   testTime?: number;
 };
 
+/**
+ * Scaffolds a deterministic test project for the given matrix entry, installs dependencies, runs cloud-provider validation, cleans up artifacts, and returns the aggregated test result.
+ *
+ * @param config - Test matrix entry describing frontend, databaseEngine, orm, databaseHost, authProvider, and related test options used to build and validate the project
+ * @returns A CloudProviderTestResult containing the original `config`, a `passed` flag, collected `errors` and `warnings`, and `testTime` in milliseconds
+ */
 async function scaffoldAndTestCloudProvider(
   config: TestMatrixEntry
 ): Promise<CloudProviderTestResult> {
@@ -289,6 +295,14 @@ async function scaffoldAndTestCloudProvider(
   }
 }
 
+/**
+ * Orchestrates cloud provider validation across a set of test matrix entries and exits with a non-zero code if any configuration fails.
+ *
+ * Reads a JSON test matrix, filters entries for supported cloud-provider combinations, optionally limits the run to a subset, and for each configuration scaffolds a project, installs dependencies, runs validation, and aggregates results into a summary grouped by provider.
+ *
+ * @param matrixFile - Path to the JSON test matrix file (defaults to "test-matrix.json")
+ * @param testSubset - Optional maximum number of configurations to test (if provided, runs only the first N matching entries)
+ */
 async function runCloudProviderTests(
   matrixFile: string = 'test-matrix.json',
   testSubset?: number
@@ -399,4 +413,3 @@ async function runCloudProviderTests(
 if (require.main === module) {
   runCloudProviderTests().catch(console.error);
 }
-
diff --git a/scripts/functional-tests/cloud-provider-validator.ts b/scripts/functional-tests/cloud-provider-validator.ts
index d42d108..cf794c5 100644
--- a/scripts/functional-tests/cloud-provider-validator.ts
+++ b/scripts/functional-tests/cloud-provider-validator.ts
@@ -23,6 +23,26 @@ export type CloudProviderValidationResult = {
   };
 };
 
+/**
+ * Validates a project's cloud database provider setup (Neon, PlanetScale, or Turso), verifies provider-specific code, imports and dependencies, checks environment configuration and Docker usage, and runs functional tests.
+ *
+ * @param projectPath - Path to the project root being validated.
+ * @param packageManager - Package manager to use when running functional tests (`bun` | `npm` | `pnpm` | `yarn`).
+ * @param config - Optional configuration that influences validation:
+ *   - `databaseHost`: provider identifier (`neon`, `planetscale`, or `turso`) used to select provider-specific checks.
+ *   - `orm`: ORM in use (e.g., `drizzle`) which adjusts Neon connection/import expectations.
+ *   - `databaseEngine` and `authProvider` are accepted but not required for provider selection.
+ * @param options - Execution options forwarded to the functional test runner:
+ *   - `skipDependencies`: skip dependency installation step.
+ *   - `skipBuild`: skip build step.
+ *   - `skipServer`: skip starting the server for runtime checks.
+ * @returns The CloudProviderValidationResult containing:
+ *   - `passed`: whether the validation succeeded,
+ *   - `errors`: array of error messages,
+ *   - `warnings`: array of warnings,
+ *   - `functionalTestResults` (when available),
+ *   - `cloudSpecific`: detailed booleans for connection code, imports, dependencies, Docker presence, and env configuration.
+ */
 export async function validateCloudProvider(
   projectPath: string,
   packageManager: 'bun' | 'npm' | 'pnpm' | 'yarn' = 'bun',
@@ -301,4 +321,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/database-connection-tester.ts b/scripts/functional-tests/database-connection-tester.ts
index 4e52100..4855754 100644
--- a/scripts/functional-tests/database-connection-tester.ts
+++ b/scripts/functional-tests/database-connection-tester.ts
@@ -17,6 +17,23 @@ export type DatabaseConnectionResult = {
   warnings: string[];
 };
 
+/**
+ * Performs basic checks to validate a project's database setup and returns structured results.
+ *
+ * The function verifies whether a database is configured, checks for a `db` directory under the project path,
+ * and performs an ORM-specific check for a Drizzle schema (`db/schema.ts`). It also emits warnings that the
+ * connection tests are not fully implemented and may require Docker or cloud credentials.
+ *
+ * @param projectPath - Filesystem path to the project root where the `db` directory is expected
+ * @param config - Optional configuration for the check:
+ *   - `databaseEngine`: name of the configured database engine or `'none'` to indicate no DB
+ *   - `databaseHost`: hostname for the database (unused by this basic tester)
+ *   - `orm`: ORM in use; when `'drizzle'`, the presence of `db/schema.ts` is validated
+ * @returns An object with:
+ *   - `passed`: `true` if checks completed without errors, `false` if one or more errors were found
+ *   - `errors`: list of error messages describing failing checks
+ *   - `warnings`: list of informational warnings (for example, when database testing is not implemented or when no DB is configured)
+ */
 export async function testDatabaseConnection(
   projectPath: string,
   config: {
@@ -95,4 +112,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/dependency-cache.ts b/scripts/functional-tests/dependency-cache.ts
index a21a096..b573f21 100644
--- a/scripts/functional-tests/dependency-cache.ts
+++ b/scripts/functional-tests/dependency-cache.ts
@@ -19,8 +19,10 @@ type DependencyFingerprint = {
 };
 
 /**
- * Generate a unique cache key based on dependencies
- * Configs with same dependencies will share the same cache
+ * Produce a stable fingerprint string for a dependency configuration.
+ *
+ * @param config - Dependency fields that affect installed packages; fields considered include `frontend`, `databaseEngine`, `orm`, `databaseHost`, `authProvider`, `useTailwind`, and `codeQualityTool`.
+ * @returns A 16-character hexadecimal fingerprint identifying the provided dependency configuration.
  */
 function getDependencyFingerprint(config: DependencyFingerprint): string {
   // Normalize the config to create a stable fingerprint
@@ -41,14 +43,20 @@ function getDependencyFingerprint(config: DependencyFingerprint): string {
 const CACHE_DIR = join(process.cwd(), '.test-dependency-cache');
 
 /**
- * Get the cache path for a dependency fingerprint
+ * Return the cache directory path for a given dependency fingerprint.
+ *
+ * @param fingerprint - The fingerprint identifying a dependency configuration
+ * @returns The filesystem path to the cache directory for `fingerprint`
  */
 function getCachePath(fingerprint: string): string {
   return join(CACHE_DIR, fingerprint);
 }
 
 /**
- * Check if a cached node_modules exists for this fingerprint
+ * Determine whether a cached node_modules directory exists for the given dependency fingerprint.
+ *
+ * @param config - Dependency fingerprint describing the dependencies and configuration that affect installed packages
+ * @returns `true` if a cached `node_modules` directory exists for the fingerprint, `false` otherwise
  */
 export function hasCachedDependencies(config: DependencyFingerprint): boolean {
   const fingerprint = getDependencyFingerprint(config);
@@ -59,7 +67,14 @@ export function hasCachedDependencies(config: DependencyFingerprint): boolean {
 }
 
 /**
- * Get cached node_modules or install and cache them
+ * Ensure the project has a populated `node_modules` directory by restoring from a fingerprinted cache when available, otherwise installing dependencies and storing them in the cache.
+ *
+ * @param projectPath - Filesystem path to the project where `node_modules` will be placed
+ * @param config - Dependency fingerprint describing the dependency/configuration set used to derive the cache key
+ * @param packageJsonPath - Path to the project's `package.json`; when present it is copied into the cache for reference
+ * @returns An object with `cached` set to `true` if dependencies were restored from the cache (otherwise `false`), and `installTime` representing the operation duration in milliseconds
+ * @throws Error if dependency installation times out after 300 seconds
+ * @throws Error if the dependency installer exits with a non-zero exit code
  */
 export async function getOrInstallDependencies(
   projectPath: string,
@@ -126,7 +141,11 @@ export async function getOrInstallDependencies(
 }
 
 /**
- * Clean up old cache entries (optional - can be called periodically)
+ * Remove cached dependency entries older than the given number of days.
+ *
+ * This is a placeholder implementation that currently performs no deletions.
+ *
+ * @param maxAgeDays - Maximum age in days for cache entries before they are removed (default: 7)
  */
 export function cleanupCache(maxAgeDays: number = 7): void {
   if (!existsSync(CACHE_DIR)) {
@@ -139,4 +158,3 @@ export function cleanupCache(maxAgeDays: number = 7): void {
   // This would require reading directory entries - simplified for now
   // In production, you might want to add cache metadata files with timestamps
 }
-
diff --git a/scripts/functional-tests/dependency-installer-tester.ts b/scripts/functional-tests/dependency-installer-tester.ts
index 88a722f..8d45cba 100644
--- a/scripts/functional-tests/dependency-installer-tester.ts
+++ b/scripts/functional-tests/dependency-installer-tester.ts
@@ -13,7 +13,19 @@ export type DependencyInstallResult = {
   installTime?: number;
 };
 
-const INSTALL_TIMEOUT = 120000; // 2 minutes for dependency installation
+const INSTALL_TIMEOUT = 120000; /**
+ * Tests whether dependencies in a scaffolded project can be installed with the specified package manager.
+ *
+ * Attempts to parse the project's package.json, skip installation if no dependencies are declared, run the appropriate
+ * install command (within a 2-minute timeout), and verify that node_modules is created.
+ *
+ * @param projectPath - Path to the project directory containing package.json
+ * @param packageManager - Package manager to use for installation: 'bun', 'npm', 'pnpm', or 'yarn' (default: 'bun')
+ * @returns An object describing the result:
+ *          - `passed`: `true` when installation succeeded or no dependencies were present, `false` otherwise.
+ *          - `errors`: Array of human-readable error messages collected during checks or installation.
+ *          - `installTime` (optional): Time in milliseconds the installation process took when an install was attempted.
+ */
 
 export async function testDependencyInstallation(
   projectPath: string,
@@ -157,4 +169,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/frontend-renderer-tester.ts b/scripts/functional-tests/frontend-renderer-tester.ts
index ef7a4de..4799633 100644
--- a/scripts/functional-tests/frontend-renderer-tester.ts
+++ b/scripts/functional-tests/frontend-renderer-tester.ts
@@ -15,6 +15,15 @@ export type FrontendRendererResult = {
   warnings: string[];
 };
 
+/**
+ * Runs a placeholder frontend rendering test for the specified project and collects warnings about unimplemented checks.
+ *
+ * @param projectPath - Path to the project's root directory to inspect and test
+ * @param serverUrl - Base URL of the running application to target (defaults to `http://localhost:3000`)
+ * @param config - Optional configuration for the test
+ * @param config.frontends - Optional list of frontend frameworks (e.g., `['react','vue']`) to focus testing on
+ * @returns A FrontendRendererResult where `passed` is `true` if no errors were recorded, `errors` contains error messages, and `warnings` contains informational warnings about incomplete or skipped checks
+ */
 export async function testFrontendRendering(
   projectPath: string,
   serverUrl: string = 'http://localhost:3000',
@@ -76,4 +85,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/functional-test-runner.ts b/scripts/functional-tests/functional-test-runner.ts
index 170b3f7..f72036e 100644
--- a/scripts/functional-tests/functional-test-runner.ts
+++ b/scripts/functional-tests/functional-test-runner.ts
@@ -21,6 +21,23 @@ export type FunctionalTestResult = {
   totalTime?: number;
 };
 
+/**
+ * Runs a sequence of functional tests (project structure, dependency installation, build validation, and server startup) for the given project and aggregates the results.
+ *
+ * The dependency installation, build, and server startup tests can be individually skipped via the `options` flags. Results include per-step pass/fail and timing where applicable, along with collected errors and warnings.
+ *
+ * @param projectPath - Filesystem path to the project to test
+ * @param packageManager - Package manager to use (`'bun' | 'npm' | 'pnpm' | 'yarn'`)
+ * @param options.skipDependencies - When true, skips the dependency installation test
+ * @param options.skipBuild - When true, skips the build validation test
+ * @param options.skipServer - When true, skips the server startup validation test
+ * @returns The consolidated functional test result containing:
+ * - `passed`: `true` if no errors were recorded, `false` otherwise
+ * - `errors`: array of error messages collected from failing steps
+ * - `warnings`: array of warnings (including notifications for skipped tests)
+ * - `results`: per-step results with optional timing fields (`installTime`, `compileTime`)
+ * - `totalTime`: total duration in milliseconds for the entire run
+ */
 export async function runFunctionalTests(
   projectPath: string,
   packageManager: 'bun' | 'npm' | 'pnpm' | 'yarn' = 'bun',
@@ -185,4 +202,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/html-test-runner.ts b/scripts/functional-tests/html-test-runner.ts
index 0912f08..fee45b1 100644
--- a/scripts/functional-tests/html-test-runner.ts
+++ b/scripts/functional-tests/html-test-runner.ts
@@ -33,6 +33,14 @@ type HTMLTestResult = {
 const SUPPORTED_DATABASE_ENGINES = new Set(['none', 'sqlite', 'mongodb']);
 const SUPPORTED_ORMS = new Set(['none', 'drizzle']);
 
+/**
+ * Scaffolds an HTML project for the given test configuration, runs dependency installation and framework validation, and returns the aggregated test result.
+ *
+ * Attempts to scaffold a project using Bun with flags derived from `config`, installs dependencies (using a cache when available), runs HTML framework validation with dependency checks skipped, cleans up the scaffolded project, and collects any errors and warnings encountered during the process.
+ *
+ * @param config - TestMatrixEntry describing the test configuration (frontend, databaseEngine, orm, databaseHost, authProvider, optional codeQualityTool, useTailwind, and directoryConfig) used to determine scaffold flags and validation options
+ * @returns An HTMLTestResult containing the original `config`, `passed` indicating validation success, `errors` and `warnings` arrays with any messages collected, and `testTime` as the total elapsed time in milliseconds for the test run
+ */
 async function scaffoldAndTestHTML(
   config: TestMatrixEntry
 ): Promise<HTMLTestResult> {
@@ -291,6 +299,15 @@ async function scaffoldAndTestHTML(
   }
 }
 
+/**
+ * Runs HTML framework validation for configurations from a test matrix file and exits with status 0 on success or 1 on any failure.
+ *
+ * Reads and parses `matrixFile`, filters entries for the HTML frontend and supported database/ORM combinations, optionally limits execution to the first `testSubset` entries, and runs each configuration sequentially via `scaffoldAndTestHTML`. Prints per-run progress and a final summary; the process exits with code 0 if all tests passed or 1 if any failed.
+ *
+ * @param matrixFile - Path to the JSON test matrix (defaults to 'test-matrix.json')
+ * @param maxConcurrent - Maximum concurrent tests (currently unused; tests run sequentially)
+ * @param testSubset - If provided, limit execution to the first N matching configurations
+ */
 async function runHTMLTests(
   matrixFile: string = 'test-matrix.json',
   maxConcurrent: number = 2,
@@ -366,4 +383,3 @@ if (require.main === module) {
     process.exit(1);
   });
 }
-
diff --git a/scripts/functional-tests/html-validator.ts b/scripts/functional-tests/html-validator.ts
index deeddca..29f87f0 100644
--- a/scripts/functional-tests/html-validator.ts
+++ b/scripts/functional-tests/html-validator.ts
@@ -21,6 +21,25 @@ export type HTMLValidationResult = {
   };
 };
 
+/**
+ * Validates an application's HTML frontend and related backend wiring, and aggregates functional test results.
+ *
+ * Performs filesystem checks for required HTML assets, verifies script references when `config.useHTMLScripts` is enabled,
+ * inspects src/backend/server.ts for HTML imports and route configuration, performs basic HTML content checks (doctype, title, CSS link),
+ * and runs the project's functional tests to collect build/server results.
+ *
+ * @param projectPath - Root path of the project to validate
+ * @param packageManager - Package manager to use when running functional tests (`'bun' | 'npm' | 'pnpm' | 'yarn'`)
+ * @param config - Optional project features that affect validation:
+ *   - `useTailwind`: whether Tailwind CSS is expected
+ *   - `useHTMLScripts`: whether HTML pages should reference the TypeScript example script
+ *   - other fields (databaseEngine, orm, authProvider, codeQualityTool, isMultiFrontend) are accepted but only affect contextual checks
+ * @param options - Flags to skip parts of functional testing:
+ *   - `skipDependencies`: skip dependency installation
+ *   - `skipBuild`: skip the build step
+ *   - `skipServer`: skip starting the server
+ * @returns An object describing the validation outcome: `passed` boolean, arrays of `errors` and `warnings`, optional `functionalTestResults`, and `htmlSpecific` flags (`filesExist`, `routesConfigured`, `importsCorrect`)
+ */
 export async function validateHTMLFramework(
   projectPath: string,
   packageManager: 'bun' | 'npm' | 'pnpm' | 'yarn' = 'bun',
@@ -247,4 +266,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/htmx-test-runner.ts b/scripts/functional-tests/htmx-test-runner.ts
index 70d00e2..01902e6 100644
--- a/scripts/functional-tests/htmx-test-runner.ts
+++ b/scripts/functional-tests/htmx-test-runner.ts
@@ -32,6 +32,12 @@ type HTMXTestResult = {
 const SUPPORTED_DATABASE_ENGINES = new Set(['none', 'sqlite', 'mongodb']);
 const SUPPORTED_ORMS = new Set(['none', 'drizzle']);
 
+/**
+ * Scaffolds a project for the given HTMX test configuration, installs dependencies, runs HTMX validation, and returns the aggregated test result.
+ *
+ * @param config - Test matrix entry describing the project configuration (frontend, databaseEngine, orm, databaseHost, authProvider, optional codeQualityTool, useTailwind, directoryConfig)
+ * @returns HTMXTestResult containing the supplied `config`, a `passed` flag indicating whether validation succeeded, collected `errors` and `warnings`, and the total `testTime` in milliseconds
+ */
 async function scaffoldAndTestHTMX(
   config: TestMatrixEntry
 ): Promise<HTMXTestResult> {
@@ -251,6 +257,15 @@ async function scaffoldAndTestHTMX(
   }
 }
 
+/**
+ * Orchestrates HTMX configuration tests defined in a matrix JSON file and exits the process with a status code reflecting overall success.
+ *
+ * Reads and parses the specified matrix file, filters entries for HTMX-compatible configurations, and runs scaffold-and-validate tests for each selected configuration (currently sequential). After all tests complete, prints a summary with totals, pass/fail counts, and a success rate; if any test fails the process exits with code 1, otherwise exits with code 0.
+ *
+ * @param matrixFile - Path to the JSON test matrix file (an array of TestMatrixEntry objects)
+ * @param maxConcurrent - Maximum number of concurrent tests to run (reserved for future parallel execution; currently tests run sequentially)
+ * @param testSubset - Optional limit to the number of HTMX configurations to test (takes the first N eligible entries)
+ */
 async function runHTMXTests(
   matrixFile: string = 'test-matrix.json',
   maxConcurrent: number = 2,
@@ -326,4 +341,3 @@ if (require.main === module) {
     process.exit(1);
   });
 }
-
diff --git a/scripts/functional-tests/htmx-validator.ts b/scripts/functional-tests/htmx-validator.ts
index a09677f..1e0b2aa 100644
--- a/scripts/functional-tests/htmx-validator.ts
+++ b/scripts/functional-tests/htmx-validator.ts
@@ -21,6 +21,15 @@ export type HTMXValidationResult = {
   };
 };
 
+/**
+ * Validate that an HTMX example is present and correctly wired in a project and run associated functional tests.
+ *
+ * @param projectPath - Path to the project root to validate
+ * @param packageManager - Package manager to use when running functional tests (`bun`, `npm`, `pnpm`, or `yarn`)
+ * @param config - Optional project configuration hints (databaseEngine, orm, authProvider, useTailwind, codeQualityTool, isMultiFrontend)
+ * @param options - Optional execution flags; use `skipDependencies`, `skipBuild`, or `skipServer` to skip corresponding functional-test phases
+ * @returns An HTMXValidationResult containing overall pass/fail, aggregated `errors` and `warnings`, optional `functionalTestResults`, and HTMX-specific flags (`filesExist`, `routesConfigured`, `importsCorrect`)
+ */
 export async function validateHTMXFramework(
   projectPath: string,
   packageManager: 'bun' | 'npm' | 'pnpm' | 'yarn' = 'bun',
@@ -241,4 +250,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/mongodb-test-runner.ts b/scripts/functional-tests/mongodb-test-runner.ts
index a299420..1df0fc7 100644
--- a/scripts/functional-tests/mongodb-test-runner.ts
+++ b/scripts/functional-tests/mongodb-test-runner.ts
@@ -31,6 +31,12 @@ type MongoDBTestResult = {
   testTime?: number;
 };
 
+/**
+ * Scaffolds a project from the provided test-matrix configuration, runs dependency installation, executes functional tests and MongoDB-specific validation, and returns the aggregated results.
+ *
+ * @param config - Test matrix entry specifying frontend, ORM, database host, auth provider, and other options used to generate and run the test project
+ * @returns An object describing the test outcome: `config` (the input configuration), `passed` (`true` if MongoDB validation passed and functional tests passed when present, `false` otherwise), `errors` (collected error messages), `warnings` (collected warnings), and `testTime` (total elapsed time in milliseconds for the entire operation)
+ */
 async function scaffoldAndTestMongoDB(
   config: TestMatrixEntry
 ): Promise<MongoDBTestResult> {
@@ -294,6 +300,16 @@ async function scaffoldAndTestMongoDB(
   }
 }
 
+/**
+ * Run MongoDB-focused functional tests for configurations defined in a test matrix.
+ *
+ * Reads the JSON test matrix from `matrixFile`, filters entries where `databaseEngine` is `"mongodb"`,
+ * and executes scaffold + functional test + MongoDB validation for each selected configuration.
+ * Results are summarized to the console and the process exits with code `1` if any configuration fails.
+ *
+ * @param matrixFile - Path to the JSON test matrix (defaults to "test-matrix.json")
+ * @param testSubset - If provided, limit testing to the first `testSubset` MongoDB configurations
+ */
 async function runMongoDBTests(
   matrixFile: string = 'test-matrix.json',
   maxConcurrent: number = 2,
@@ -376,4 +392,3 @@ if (require.main === module) {
     process.exit(1);
   });
 }
-
diff --git a/scripts/functional-tests/mongodb-validator.ts b/scripts/functional-tests/mongodb-validator.ts
index ee2b0c4..aec8909 100644
--- a/scripts/functional-tests/mongodb-validator.ts
+++ b/scripts/functional-tests/mongodb-validator.ts
@@ -19,6 +19,24 @@ export type MongoDBValidationResult = {
   };
 };
 
+/**
+ * Validates a project's MongoDB setup and connectivity, returning a structured result.
+ *
+ * Performs checks including presence of the db directory, local Docker compose file (for local setups),
+ * optional startup and readiness checks of a local MongoDB container, basic query verification, and
+ * presence of the expected backend handler file.
+ *
+ * @param projectPath - Path to the project root directory (where `db` and `src` are located)
+ * @param config - Optional configuration:
+ *   - orm: ORM in use (if any)
+ *   - authProvider: authentication provider; when provided and not `'none'` the validator looks for user-related handlers and queries
+ *   - databaseHost: set to `'none'` or omitted for local Docker-based validation; any other value treats MongoDB as remote
+ * @returns The validation result containing:
+ *   - `passed`: `true` if all required checks succeeded
+ *   - `errors`: collected error messages
+ *   - `warnings`: collected warning messages
+ *   - `mongodbSpecific`: object with booleans `dockerComposeExists`, `connectionWorks`, and `queriesWork` indicating MongoDB-specific check outcomes
+ */
 export async function validateMongoDBDatabase(
   projectPath: string,
   config: {
@@ -209,4 +227,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/mysql-test-runner.ts b/scripts/functional-tests/mysql-test-runner.ts
index 4b0d20d..52b2137 100644
--- a/scripts/functional-tests/mysql-test-runner.ts
+++ b/scripts/functional-tests/mysql-test-runner.ts
@@ -30,6 +30,13 @@ type MySQLTestResult = {
   testTime?: number;
 };
 
+/**
+ * Scaffolds a project for the given MySQL test configuration, runs dependency installation,
+ * executes functional tests and MySQL-specific validation, performs cleanup, and aggregates results.
+ *
+ * @param config - Test matrix entry that specifies frontend, ORM, database host, auth provider, and other options used to scaffold and test the project
+ * @returns A MySQLTestResult containing the original `config`, `passed` (true if validation and functional tests passed), arrays of `errors` and `warnings`, and `testTime` (milliseconds elapsed for the entire operation)
+ */
 async function scaffoldAndTestMySQL(
   config: TestMatrixEntry
 ): Promise<MySQLTestResult> {
@@ -285,6 +292,15 @@ async function scaffoldAndTestMySQL(
   }
 }
 
+/**
+ * Orchestrates MySQL-focused functional tests defined in a test matrix file and exits the process with status indicating success or failure.
+ *
+ * Reads the provided JSON test matrix, filters entries for MySQL (excluding PlanetScale hosts), optionally limits the set, and runs each configuration through the scaffoldAndTestMySQL workflow. Prints per-configuration progress and a final summary; exits with code 0 if all tests passed or 1 if any failed.
+ *
+ * @param matrixFile - Path to the JSON file containing an array of TestMatrixEntry objects (default: 'test-matrix.json')
+ * @param maxConcurrent - Maximum number of concurrent test workers to allow (currently tests run sequentially; parameter reserved for future concurrency control)
+ * @param testSubset - Optional limit to run only the first N matching configurations from the matrix
+ */
 async function runMySQLTests(
   matrixFile: string = 'test-matrix.json',
   maxConcurrent: number = 2,
@@ -370,4 +386,3 @@ if (require.main === module) {
     process.exit(1);
   });
 }
-
diff --git a/scripts/functional-tests/mysql-validator.ts b/scripts/functional-tests/mysql-validator.ts
index 929224c..469a48c 100644
--- a/scripts/functional-tests/mysql-validator.ts
+++ b/scripts/functional-tests/mysql-validator.ts
@@ -20,6 +20,24 @@ export type MySQLValidationResult = {
   };
 };
 
+/**
+ * Validates a project's MySQL setup and returns a structured result of checks and issues.
+ *
+ * Performs filesystem and runtime checks (db directory, Docker compose file for local setups,
+ * ORM schema presence when using Drizzle, attempt to start and query a local MySQL container,
+ * and required backend handler files). Records errors, warnings, and per-check booleans in the result.
+ *
+ * @param projectPath - Path to the project root to validate
+ * @param config - Optional validation flags:
+ *   - orm: if set to 'drizzle', verifies presence of a Drizzle schema file
+ *   - authProvider: when present, expects authentication-related tables/handlers (e.g., `users`)
+ *   - databaseHost: 'planetscale' to treat database as remote; 'none' or omitted to test local Docker MySQL
+ * @returns A MySQLValidationResult containing:
+ *   - `passed`: whether all required checks succeeded,
+ *   - `errors`: array of error messages found during validation,
+ *   - `warnings`: non-fatal warnings encountered,
+ *   - `mysqlSpecific`: object with booleans for `dockerComposeExists`, `schemaFileExists`, `connectionWorks`, and `queriesWork`
+ */
 export async function validateMySQLDatabase(
   projectPath: string,
   config: {
@@ -238,4 +256,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/postgresql-test-runner.ts b/scripts/functional-tests/postgresql-test-runner.ts
index d9fa4f9..8406d52 100644
--- a/scripts/functional-tests/postgresql-test-runner.ts
+++ b/scripts/functional-tests/postgresql-test-runner.ts
@@ -30,6 +30,12 @@ type PostgreSQLTestResult = {
   testTime?: number;
 };
 
+/**
+ * Orchestrates scaffolding a project from the given test-matrix configuration, installs dependencies (using a cache when available), runs functional tests, performs PostgreSQL-specific validation, attempts cleanup, and returns a summarized test result.
+ *
+ * @param config - Test matrix entry specifying frontend, ORM, auth provider, database host, and other scaffold options
+ * @returns A PostgreSQLTestResult containing the original `config`, `passed` status, arrays of `errors` and `warnings`, and total `testTime` in milliseconds
+ */
 async function scaffoldAndTestPostgreSQL(
   config: TestMatrixEntry
 ): Promise<PostgreSQLTestResult> {
@@ -284,6 +290,18 @@ async function scaffoldAndTestPostgreSQL(
   }
 }
 
+/**
+ * Run the PostgreSQL-focused scaffold-and-test pipeline for entries in a test matrix file.
+ *
+ * Reads the provided JSON matrix, filters to PostgreSQL configurations (excluding PlanetScale),
+ * optionally limits to a subset, and executes scaffold-and-test runs sequentially for each selected
+ * configuration. Prints per-configuration progress and a final summary, and exits the process with
+ * code 0 when all configurations pass or 1 if any fail.
+ *
+ * @param matrixFile - Path to the test matrix JSON file (defaults to "test-matrix.json")
+ * @param maxConcurrent - Maximum concurrency placeholder (currently tests run sequentially)
+ * @param testSubset - Optional limit to the first N PostgreSQL configurations to test
+ */
 async function runPostgreSQLTests(
   matrixFile: string = 'test-matrix.json',
   maxConcurrent: number = 2,
@@ -368,4 +386,3 @@ if (require.main === module) {
     process.exit(1);
   });
 }
-
diff --git a/scripts/functional-tests/postgresql-validator.ts b/scripts/functional-tests/postgresql-validator.ts
index 4cc633f..9e56926 100644
--- a/scripts/functional-tests/postgresql-validator.ts
+++ b/scripts/functional-tests/postgresql-validator.ts
@@ -20,6 +20,16 @@ export type PostgreSQLValidationResult = {
   };
 };
 
+/**
+ * Validate a project's PostgreSQL setup including local Docker files, schema presence, connectivity, and presence of expected tables and handler files.
+ *
+ * @param projectPath - Root path of the project to validate
+ * @param config - Optional validation configuration
+ * @param config.orm - ORM in use; when set to `'drizzle'` the validator requires `db/schema.ts`
+ * @param config.authProvider - Authentication provider; when present the validator checks for a `users` table and `userHandlers.ts`, otherwise it checks for `count_history` and `countHistoryHandlers.ts`
+ * @param config.databaseHost - Database host mode: `'none'` or omitted runs local Docker checks, `'neon'` skips local Docker and connection tests
+ * @returns The validation result containing `passed`, `errors`, `warnings`, and `postgresqlSpecific` flags (`dockerComposeExists`, `schemaFileExists`, `connectionWorks`, `queriesWork`)
+ */
 export async function validatePostgreSQLDatabase(
   projectPath: string,
   config: {
@@ -238,4 +248,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/react-test-runner.ts b/scripts/functional-tests/react-test-runner.ts
index 45c392f..73bd100 100644
--- a/scripts/functional-tests/react-test-runner.ts
+++ b/scripts/functional-tests/react-test-runner.ts
@@ -32,6 +32,12 @@ type ReactTestResult = {
 const SUPPORTED_DATABASE_ENGINES = new Set(['none', 'sqlite', 'mongodb']);
 const SUPPORTED_ORMS = new Set(['none', 'drizzle']);
 
+/**
+ * Scaffolds a React test project for the given configuration, installs dependencies (with caching), runs framework validation, cleans up the project directory, and returns the test outcome.
+ *
+ * @param config - Test matrix entry describing the test configuration (frontend, databaseEngine, orm, databaseHost, authProvider, optional codeQualityTool, useTailwind, and directoryConfig)
+ * @returns `ReactTestResult` containing the original `config`, a `passed` boolean, collected `errors` and `warnings`, and `testTime` in milliseconds
+ */
 async function scaffoldAndTestReact(
   config: TestMatrixEntry
 ): Promise<ReactTestResult> {
@@ -252,6 +258,18 @@ async function scaffoldAndTestReact(
   }
 }
 
+/**
+ * Runs React tests described in a test matrix file, executes each matching configuration, and prints a summary.
+ *
+ * Reads and parses the specified test matrix, filters entries for React with supported database engines and ORMs,
+ * optionally limits the number of configurations tested, and runs each configuration through the scaffold-and-test workflow.
+ * Prints per-configuration progress and a final summary of totals, pass/fail counts, and success rate.
+ *
+ * @param matrixFile - Path to the JSON test matrix file (default: "test-matrix.json")
+ * @param maxConcurrent - Maximum number of concurrent tests to run (currently tests run sequentially; defaults to 2)
+ * @param testSubset - Optional limit to the first N matching configurations to test
+ *
+ * Note: This function exits the process with code 0 if all tests pass or 1 if any test fails.
 async function runReactTests(
   matrixFile: string = 'test-matrix.json',
   maxConcurrent: number = 2,
@@ -327,4 +345,3 @@ if (require.main === module) {
     process.exit(1);
   });
 }
-
diff --git a/scripts/functional-tests/react-validator.ts b/scripts/functional-tests/react-validator.ts
index 9563f1d..fbceee0 100644
--- a/scripts/functional-tests/react-validator.ts
+++ b/scripts/functional-tests/react-validator.ts
@@ -21,6 +21,23 @@ export type ReactValidationResult = {
   };
 };
 
+/**
+ * Validates a project's React integration and runs functional tests to assess React-specific readiness.
+ *
+ * Performs checks for required React files, server route and import configuration, presence of React dependencies,
+ * and executes the functional test suite; aggregates errors, warnings, functional test results, and React-specific flags.
+ *
+ * @param projectPath - Filesystem path to the root of the project to validate
+ * @param packageManager - Package manager to use when running functional tests (`bun`, `npm`, `pnpm`, or `yarn`)
+ * @param config - Optional project configuration hints (databaseEngine, orm, authProvider, useTailwind, codeQualityTool, isMultiFrontend)
+ * @param options - Execution options to skip steps: `skipDependencies`, `skipBuild`, `skipServer`
+ * @returns The validation result containing:
+ * - `passed`: `true` if no errors were found and all React-specific checks (filesExist, routesConfigured, importsCorrect) passed, `false` otherwise.
+ * - `errors`: array of error messages discovered during validation.
+ * - `warnings`: array of non-fatal issues or parse/read warnings.
+ * - `functionalTestResults`: optional detailed results from the functional test runner.
+ * - `reactSpecific`: object with boolean flags `filesExist`, `routesConfigured`, and `importsCorrect`.
+ */
 export async function validateReactFramework(
   projectPath: string,
   packageManager: 'bun' | 'npm' | 'pnpm' | 'yarn' = 'bun',
@@ -200,4 +217,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/server-startup-validator.ts b/scripts/functional-tests/server-startup-validator.ts
index d9602ba..72297b6 100644
--- a/scripts/functional-tests/server-startup-validator.ts
+++ b/scripts/functional-tests/server-startup-validator.ts
@@ -15,7 +15,19 @@ export type ServerStartupResult = {
   compileTime?: number;
 };
 
-const COMPILE_TIMEOUT = 60000; // 60 seconds for TypeScript compilation
+const COMPILE_TIMEOUT = 60000; /**
+ * Validates that a scaffolded project contains a basic Elysia server structure and, when configured, that TypeScript compiles successfully.
+ *
+ * Performs these checks: verifies src/backend/server.ts exists and contains an Elysia initialization, ensures package.json exists with a `dev` script, and if tsconfig.json is present runs the project's `typecheck` script via the specified package manager (subject to a timeout).
+ *
+ * @param projectPath - Filesystem path to the root of the scaffolded project to validate
+ * @param packageManager - Package manager to use when invoking the `typecheck` script (`'bun' | 'npm' | 'pnpm' | 'yarn'`)
+ * @returns An object with:
+ *  - `passed`: `true` when all required checks (and optional compilation) succeed, `false` otherwise.
+ *  - `errors`: an array of error messages describing failed checks.
+ *  - `warnings`: an array of warning messages (for non-fatal issues such as missing tsconfig.json).
+ *  - `compileTime` (optional): compilation duration in milliseconds when a typecheck was performed.
+ */
 
 export async function validateServerStartup(
   projectPath: string,
@@ -167,4 +179,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/sqlite-test-runner.ts b/scripts/functional-tests/sqlite-test-runner.ts
index b26d086..4752278 100644
--- a/scripts/functional-tests/sqlite-test-runner.ts
+++ b/scripts/functional-tests/sqlite-test-runner.ts
@@ -30,6 +30,12 @@ type SQLiteTestResult = {
   testTime?: number;
 };
 
+/**
+ * Scaffolds a project for the given test configuration, installs dependencies (with caching), runs functional tests and SQLite-specific validation, and returns an aggregated test result.
+ *
+ * @param config - Test matrix entry that controls scaffold options (frontend, ORM, auth, database host, Tailwind, code-quality tool, and directory layout)
+ * @returns An object describing the test outcome: `config` (the input configuration), `passed` (`true` if SQLite validation and — when run — functional tests passed, `false` otherwise), `errors` (collected error messages), `warnings` (collected warnings), and `testTime` (total elapsed time in milliseconds)
+ */
 async function scaffoldAndTestSQLite(
   config: TestMatrixEntry
 ): Promise<SQLiteTestResult> {
@@ -274,6 +280,15 @@ async function scaffoldAndTestSQLite(
   }
 }
 
+/**
+ * Run SQLite-focused tests defined in a test matrix file, print progress and a summary, and exit with status 0 on success or 1 on failure.
+ *
+ * Reads the JSON test matrix from `matrixFile`, filters entries where `databaseEngine` is `'sqlite'`, optionally limits to the first `testSubset` entries, runs the scaffold-and-test routine for each configuration sequentially, and prints per-test results and an overall summary to stdout before exiting the process with a non-zero code if any tests failed.
+ *
+ * @param matrixFile - Path to the JSON test matrix file (defaults to `"test-matrix.json"`).
+ * @param maxConcurrent - Maximum number of concurrent test runs (present for compatibility; this runner executes tests sequentially).
+ * @param testSubset - If provided, limits execution to the first `testSubset` SQLite configurations from the matrix.
+ */
 async function runSQLiteTests(
   matrixFile: string = 'test-matrix.json',
   maxConcurrent: number = 2,
@@ -345,4 +360,3 @@ if (require.main === module) {
     process.exit(1);
   });
 }
-
diff --git a/scripts/functional-tests/sqlite-validator.ts b/scripts/functional-tests/sqlite-validator.ts
index df0b54e..7113daa 100644
--- a/scripts/functional-tests/sqlite-validator.ts
+++ b/scripts/functional-tests/sqlite-validator.ts
@@ -20,6 +20,22 @@ export type SQLiteValidationResult = {
   };
 };
 
+/**
+ * Validates a project's SQLite setup, schema, connection, and related handler presence.
+ *
+ * Performs a sequence of checks against the project's db directory:
+ * - Verifies the db directory and (for local SQLite) the database file exist.
+ * - Ensures the expected schema file exists (Drizzle -> schema.ts, otherwise -> schema.sql).
+ * - For local SQLite, runs sqlite3 queries to confirm the database is reachable and required tables
+ *   (users or count_history) are present; for Turso, skips live checks and issues warnings.
+ * - Verifies the appropriate backend handler file exists based on the auth provider.
+ *
+ * @param projectPath - Root path of the project to validate.
+ * @param config.orm - ORM in use; when set to "drizzle" the validator expects db/schema.ts, otherwise db/schema.sql.
+ * @param config.authProvider - Authentication provider; when provided and not "none", the validator expects a `users` table and userHandlers.ts; otherwise it expects a `count_history` table and countHistoryHandlers.ts.
+ * @param config.databaseHost - Database host descriptor; "none" or omitted means local SQLite (expects db/database.sqlite and performs sqlite3 checks); "turso" skips local file and live checks and emits warnings.
+ * @returns The aggregated validation result containing pass/fail status, any errors and warnings, and detailed booleans for database file, schema file, connection, and query checks.
+ */
 export async function validateSQLiteDatabase(
   projectPath: string,
   config: {
@@ -197,4 +213,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/svelte-test-runner.ts b/scripts/functional-tests/svelte-test-runner.ts
index 9ba3004..20e205e 100644
--- a/scripts/functional-tests/svelte-test-runner.ts
+++ b/scripts/functional-tests/svelte-test-runner.ts
@@ -32,6 +32,12 @@ type SvelteTestResult = {
 const SUPPORTED_DATABASE_ENGINES = new Set(['none', 'sqlite', 'mongodb']);
 const SUPPORTED_ORMS = new Set(['none', 'drizzle']);
 
+/**
+ * Scaffolds a Svelte project from the provided test configuration, installs dependencies, runs framework validation, cleans up the generated project, and returns the aggregated result.
+ *
+ * @param config - Test matrix entry describing the project options to scaffold and test
+ * @returns A SvelteTestResult containing the original `config`, `passed` (validation outcome), collected `errors` and `warnings`, and `testTime` in milliseconds
+ */
 async function scaffoldAndTestSvelte(
   config: TestMatrixEntry
 ): Promise<SvelteTestResult> {
@@ -251,6 +257,13 @@ async function scaffoldAndTestSvelte(
   }
 }
 
+/**
+ * Execute the Svelte test matrix defined in a JSON file and print a per-config and aggregated summary.
+ *
+ * @param matrixFile - Path to a JSON file containing an array of TestMatrixEntry objects (defaults to 'test-matrix.json').
+ * @param maxConcurrent - Maximum number of tests to run concurrently (controls parallelism; tests currently run sequentially).
+ * @param testSubset - If provided, limit execution to the first `testSubset` matching Svelte configurations.
+ */
 async function runSvelteTests(
   matrixFile: string = 'test-matrix.json',
   maxConcurrent: number = 2,
@@ -326,4 +339,3 @@ if (require.main === module) {
     process.exit(1);
   });
 }
-
diff --git a/scripts/functional-tests/svelte-validator.ts b/scripts/functional-tests/svelte-validator.ts
index 71c7616..71cee96 100644
--- a/scripts/functional-tests/svelte-validator.ts
+++ b/scripts/functional-tests/svelte-validator.ts
@@ -21,6 +21,17 @@ export type SvelteValidationResult = {
   };
 };
 
+/**
+ * Validates that a backend project is correctly configured to serve a Svelte frontend and runs related functional tests.
+ *
+ * Performs checks for expected Svelte files, server route and import configuration, presence of Svelte in package.json, and delegates build/server checks to the functional test runner. Aggregates findings into errors, warnings, functional test results, and Svelte-specific flags.
+ *
+ * @param projectPath - Path to the root of the project to validate
+ * @param packageManager - Package manager used to run functional tests and scripts (`bun`, `npm`, `pnpm`, or `yarn`)
+ * @param config - Optional Svelte-related configuration hints (databaseEngine, orm, authProvider, useTailwind, codeQualityTool, isMultiFrontend)
+ * @param options - Optional flags to skip parts of the validation: `skipDependencies`, `skipBuild`, `skipServer`
+ * @returns An object describing whether validation passed, collected `errors` and `warnings`, optional `functionalTestResults`, and `svelteSpecific` flags (`filesExist`, `routesConfigured`, `importsCorrect`)
+ */
 export async function validateSvelteFramework(
   projectPath: string,
   packageManager: 'bun' | 'npm' | 'pnpm' | 'yarn' = 'bun',
@@ -222,4 +233,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/functional-tests/test-utils.ts b/scripts/functional-tests/test-utils.ts
index 97a5bbe..be8880c 100644
--- a/scripts/functional-tests/test-utils.ts
+++ b/scripts/functional-tests/test-utils.ts
@@ -1,8 +1,12 @@
 import { existsSync, rmSync } from 'fs';
 
 /**
- * Removes a previously generated project directory if it exists.
- * This prevents scaffolding commands from failing with "directory already exists".
+ * Remove a generated project directory if it exists.
+ *
+ * Attempts to remove `projectPath` recursively and forcibly; if removal fails the error is caught
+ * and a warning is logged containing the path and the error message.
+ *
+ * @param projectPath - Filesystem path of the project directory to remove
  */
 export function cleanupProjectDirectory(projectPath: string): void {
   try {
@@ -18,4 +22,3 @@ export function cleanupProjectDirectory(projectPath: string): void {
   }
 }
 
-
diff --git a/scripts/functional-tests/vue-test-runner.ts b/scripts/functional-tests/vue-test-runner.ts
index 95c7036..0af4ab0 100644
--- a/scripts/functional-tests/vue-test-runner.ts
+++ b/scripts/functional-tests/vue-test-runner.ts
@@ -32,6 +32,14 @@ type VueTestResult = {
 const SUPPORTED_DATABASE_ENGINES = new Set(['none', 'sqlite', 'mongodb']);
 const SUPPORTED_ORMS = new Set(['none', 'drizzle']);
 
+/**
+ * Scaffolds a Vue project for the given test configuration, runs dependency installation and framework validation, and aggregates the results.
+ *
+ * This function creates a temporary project directory (named from the provided configuration), attempts to scaffold the project, install dependencies, run framework validation, and then removes the project directory. Any scaffold, install, or validation errors and warnings are collected and returned in the result.
+ *
+ * @param config - Test matrix entry describing the frontend, database engine, ORM, auth provider, tailwind and code-quality options to use when scaffolding and validating the project
+ * @returns A VueTestResult containing the original `config`, a `passed` boolean indicating validation success, an `errors` array of failure messages, a `warnings` array of non-fatal notices, and `testTime` with the total elapsed time in milliseconds for the test run
+ */
 async function scaffoldAndTestVue(
   config: TestMatrixEntry
 ): Promise<VueTestResult> {
@@ -251,6 +259,19 @@ async function scaffoldAndTestVue(
   }
 }
 
+/**
+ * Orchestrates Vue framework tests from a test matrix: filters relevant Vue configurations,
+ * scaffolds and validates each configuration, prints a summary, and exits the process with
+ * a non-zero code if any test failed.
+ *
+ * The function filters entries for frontend === 'vue' and supported database engines/ORMs,
+ * optionally limits the number of tested entries, runs each configuration sequentially,
+ * and reports per-test and aggregate results to stdout.
+ *
+ * @param matrixFile - Path to the JSON test matrix file
+ * @param maxConcurrent - Maximum number of concurrent tests (currently tests run sequentially)
+ * @param testSubset - If provided, limits testing to the first `testSubset` matching configurations
+ */
 async function runVueTests(
   matrixFile: string = 'test-matrix.json',
   maxConcurrent: number = 2,
@@ -326,4 +347,3 @@ if (require.main === module) {
     process.exit(1);
   });
 }
-
diff --git a/scripts/functional-tests/vue-validator.ts b/scripts/functional-tests/vue-validator.ts
index 839a2cb..0e966e1 100644
--- a/scripts/functional-tests/vue-validator.ts
+++ b/scripts/functional-tests/vue-validator.ts
@@ -21,6 +21,21 @@ export type VueValidationResult = {
   };
 };
 
+/**
+ * Validates that a project at the given path is configured to use Vue and runs related functional tests.
+ *
+ * Performs file presence checks for key Vue files and assets, inspects server.ts for Vue imports and route configuration,
+ * verifies that package.json lists Vue as a dependency, and executes functional tests to validate build/server behavior.
+ *
+ * @param projectPath - Path to the project root to validate
+ * @param packageManager - Package manager to use when running functional tests (`bun`, `npm`, `pnpm`, or `yarn`)
+ * @param config - Optional project configuration hints; recognized keys: `databaseEngine`, `orm`, `authProvider`, `useTailwind`, `codeQualityTool`, `isMultiFrontend`
+ * @param options - Optional execution flags:
+ *   - `skipDependencies` — skip dependency installation during functional tests
+ *   - `skipBuild` — skip the build step during functional tests
+ *   - `skipServer` — skip starting the server during functional tests
+ * @returns A VueValidationResult describing whether validation passed, arrays of `errors` and `warnings`, any `functionalTestResults`, and `vueSpecific` boolean flags for `filesExist`, `routesConfigured`, and `importsCorrect`
+ */
 export async function validateVueFramework(
   projectPath: string,
   packageManager: 'bun' | 'npm' | 'pnpm' | 'yarn' = 'bun',
@@ -220,4 +235,3 @@ if (require.main === module) {
       process.exit(1);
     });
 }
-
diff --git a/scripts/generate-test-matrix.ts b/scripts/generate-test-matrix.ts
index 7101983..116de27 100644
--- a/scripts/generate-test-matrix.ts
+++ b/scripts/generate-test-matrix.ts
@@ -52,6 +52,17 @@ const hostConstraints: Record<Exclude<DatabaseHost, 'none'>, DatabaseEngine[] |
   planetscale: ['postgresql', 'mysql'] // planetscale supports postgres or mysql
 };
 
+/**
+ * Determine whether a CLI configuration satisfies supported database, ORM, and host constraints.
+ *
+ * The following compatibility rules are enforced:
+ * - If `orm` is `'drizzle'`, `databaseEngine` must be one of the engines listed in `drizzleCompatible`.
+ * - If `databaseEngine` is `'none'`, then `orm` must be `'none'` and `databaseHost` must be `'none'`.
+ * - If `databaseHost` is not `'none'`, the host's allowed engines (from `hostConstraints`) must include `databaseEngine`.
+ *
+ * @param config - The configuration to validate
+ * @returns `true` if the configuration satisfies all compatibility rules, `false` otherwise.
+ */
 function isValid(config: Config): boolean {
   const { databaseEngine, orm, databaseHost } = config;
 
@@ -77,6 +88,11 @@ function isValid(config: Config): boolean {
   return true;
 }
 
+/**
+ * Generate all possible CLI configuration combinations and filter them by the compatibility rules.
+ *
+ * @returns An array of `Config` objects representing every valid configuration combination produced from the Cartesian product of available options and filtered by `isValid`
+ */
 function generate(): Config[] {
   const results: Config[] = [];
   for (const frontend of frontends) {
@@ -109,6 +125,12 @@ function generate(): Config[] {
   return results;
 }
 
+/**
+ * Build the matrix of valid CLI configurations, write it to test-matrix.json, and log the result.
+ *
+ * Writes a pretty-printed JSON file named `test-matrix.json` containing all valid configurations
+ * and prints the number of combinations generated and the save path to stdout.
+ */
 function main() {
   const matrix = generate();
   const outputPath = 'test-matrix.json';
@@ -120,4 +142,3 @@ function main() {
 
 main();
 
-
diff --git a/scripts/verify-test-matrix.ts b/scripts/verify-test-matrix.ts
index 7d6b302..ce73d81 100644
--- a/scripts/verify-test-matrix.ts
+++ b/scripts/verify-test-matrix.ts
@@ -29,10 +29,28 @@ const hostConstraints: Record<Exclude<DatabaseHost, 'none'>, DatabaseEngine[]> =
   planetscale: ['postgresql', 'mysql']
 };
 
+/**
+ * Ensures a condition is met and throws an Error when it is not.
+ *
+ * @param condition - The condition to assert.
+ * @param message - The error message to throw when the assertion fails.
+ * @throws Error if `condition` is false.
+ */
 function assert(condition: boolean, message: string) {
   if (!condition) throw new Error(message);
 }
 
+/**
+ * Validates a single Config entry from the test matrix.
+ *
+ * Performs enumeration checks for frontend, orm, databaseHost, databaseEngine, authProvider, and codeQualityTool;
+ * enforces ORM/engine compatibility (e.g., `drizzle` requires a compatible engine), requires `orm` and `databaseHost` to be `none` when `databaseEngine` is `none`,
+ * and enforces host-specific engine constraints.
+ *
+ * @param cfg - The configuration entry to validate
+ * @param idx - Index of the entry in the matrix; used to produce contextual error messages
+ * @throws Error If any validation rule fails; the thrown message includes the entry index and the failing constraint
+ */
 function validateEntry(cfg: Config, idx: number) {
   // Enumerations safety
   assert(['react','html','svelte','vue','htmx'].includes(cfg.frontend), `[${idx}] invalid frontend ${cfg.frontend}`);
@@ -63,6 +81,13 @@ function validateEntry(cfg: Config, idx: number) {
   }
 }
 
+/**
+ * Validate test-matrix.json contents against the project's matrix constraints.
+ *
+ * Reads the local test-matrix.json, verifies it is a non-empty array, validates each entry with the project's rules, and performs additional spot-checks for excluded values.
+ *
+ * @throws Error if test-matrix.json is missing, empty, any entry fails validation, or excluded values (e.g., `biome`, `prisma`) are present.
+ */
 function main() {
   const fs = require('fs');
   const path = 'test-matrix.json';
@@ -83,4 +108,3 @@ function main() {
 
 main();
 
-