diff --git a/AGENTS.md b/AGENTS.md
index 5061e9a5..e207230a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,7 +88,7 @@ cli/
 │   │   │   └── index.ts
 │   │   ├── consts.ts             # Pure constants (NO imports from other core modules)
 │   │   ├── config.ts             # Path helpers (global dir, templates, API URL)
-│   │   ├── errors.ts             # Error classes
+│   │   ├── errors.ts             # CLIError hierarchy (UserError, SystemError, etc.)
 │   │   └── index.ts              # Barrel export for all core modules
 │   └── cli/
 │       ├── program.ts            # createProgram(context) factory
@@ -416,6 +416,128 @@ import { entityResource } from "@/core/resources/entity/index.js";
 import { base44Client } from "@/core/api/index.js";
 ```
 
+## Error Handling
+
+The CLI uses a structured error hierarchy to provide clear, actionable error messages with hints for users and AI agents.
+
+### Error Hierarchy
+
+```
+CLIError (abstract base class)
+├── UserError (user did something wrong - fixable by user)
+│   ├── AuthRequiredError      # Not logged in
+│   ├── AuthExpiredError       # Token expired
+│   ├── ConfigNotFoundError    # No project found
+│   ├── ConfigInvalidError     # Invalid config syntax/structure
+│   ├── ConfigExistsError      # Project already exists
+│   ├── SchemaValidationError  # Zod validation failed
+│   └── InvalidInputError      # Bad user input (template not found, etc.)
+│
+└── SystemError (something broke - needs investigation)
+    ├── ApiError               # HTTP/network failures
+    ├── FileNotFoundError      # File doesn't exist
+    ├── FileReadError          # Can't read file
+    └── InternalError          # Unexpected errors
+```
+
+### Error Properties
+
+All errors extend `CLIError` and have these properties:
+
+```typescript
+interface CLIError {
+  code: string;           // e.g., "AUTH_REQUIRED", "CONFIG_NOT_FOUND"
+  isUserError: boolean;   // true for UserError, false for SystemError
+  hints: ErrorHint[];     // Actionable suggestions
+  cause?: Error;          // Original error for stack traces
+}
+
+interface ErrorHint {
+  message: string;        // Human-readable hint
+  command?: string;       // Optional command to run (for AI agents)
+}
+```
+
+### Throwing Errors
+
+Import errors from `@/core/errors.js`:
+
+```typescript
+import {
+  ConfigNotFoundError,
+  ConfigExistsError,
+  SchemaValidationError,
+  ApiError,
+  InvalidInputError,
+} from "@/core/errors.js";
+
+// User errors - provide helpful hints
+throw new ConfigNotFoundError();  // Has default hints for create/link
+
+throw new ConfigExistsError("Project already exists at /path/to/config.jsonc");
+
+throw new InvalidInputError(`Template "${templateId}" not found`, {
+  hints: [
+    { message: `Use one of: ${validIds}` },
+  ],
+});
+
+// API errors - include status code for automatic hint generation
+throw new ApiError("Failed to sync entities", { statusCode: response.status });
+// 401 → hints to run `base44 login`
+// 404 → hints about resource not found
+// Other → hints to check network
+```
+
+### SchemaValidationError with Zod
+
+`SchemaValidationError` requires a context message and a `ZodError`. It formats the error automatically using `z.prettifyError()`:
+
+```typescript
+import { SchemaValidationError } from "@/core/errors.js";
+
+const result = EntitySchema.safeParse(parsed);
+
+if (!result.success) {
+  // Pass context message + ZodError - formatting is handled automatically
+  throw new SchemaValidationError("Invalid entity file at " + entityPath, result.error);
+}
+
+// Output:
+// Invalid entity file at /path/to/entity.jsonc:
+// ✖ Invalid input: expected string, received number
+//   → at name
+```
+
+**Important**: Do NOT manually call `z.prettifyError()` - the class does this internally.
+
+### Error Code Reference
+
+| Code               | Class                   | When to use                           |
+| ------------------ | ----------------------- | ------------------------------------- |
+| `AUTH_REQUIRED`    | `AuthRequiredError`     | User not logged in                    |
+| `AUTH_EXPIRED`     | `AuthExpiredError`      | Token expired, needs re-login         |
+| `CONFIG_NOT_FOUND` | `ConfigNotFoundError`   | No project/config file found          |
+| `CONFIG_INVALID`   | `ConfigInvalidError`    | Config file has invalid content       |
+| `CONFIG_EXISTS`    | `ConfigExistsError`     | Project already exists at location    |
+| `SCHEMA_INVALID`   | `SchemaValidationError` | Zod validation failed                 |
+| `INVALID_INPUT`    | `InvalidInputError`     | User provided invalid input           |
+| `API_ERROR`        | `ApiError`              | API request failed                    |
+| `FILE_NOT_FOUND`   | `FileNotFoundError`     | File doesn't exist                    |
+| `FILE_READ_ERROR`  | `FileReadError`         | Can't read/write file                 |
+| `INTERNAL_ERROR`   | `InternalError`         | Unexpected error                      |
+
+### CLIExitError (Special Case)
+
+`CLIExitError` in `src/cli/errors.ts` is for controlled exits (e.g., user cancellation). It's NOT reported to telemetry:
+
+```typescript
+import { CLIExitError } from "@/cli/errors.js";
+
+// User cancelled a prompt
+throw new CLIExitError(0);  // Exit code 0 = success (user chose to cancel)
+```
+
 ## Telemetry & Error Reporting
 
 The CLI reports errors to PostHog for monitoring. This is handled by the `ErrorReporter` class.
@@ -463,6 +585,7 @@ Set the environment variable: `BASE44_DISABLE_TELEMETRY=1`
 - App ID (if in a project)
 - System info (Node version, OS, platform)
 - Error stack traces
+- Error code and isUserError (for CLIError instances)
 
 ## Important Rules
 
@@ -480,7 +603,9 @@ Set the environment variable: `BASE44_DISABLE_TELEMETRY=1`
 12. **Use theme for styling** - Never use `chalk` directly in commands; import `theme` from utils and use semantic color/style names
 13. **Use fs.ts utilities** - Always use `@/core/utils/fs.js` for file operations
 14. **No direct process.exit()** - Throw `CLIExitError` instead; entry points handle the actual exit
-15. **No dynamic imports** - Avoid `await import()` inside functions; use static imports at top of file 
+15. **Use structured errors** - Never `throw new Error()`; use specific error classes from `@/core/errors.js` with appropriate hints
+16. **SchemaValidationError requires ZodError** - Always pass `ZodError`: `new SchemaValidationError("context", result.error)` - don't call `z.prettifyError()` manually
+17. **No dynamic imports** - Avoid `await import()` inside functions; use static imports at top of file
 
 ## Development
 
diff --git a/bin/dev.js b/bin/dev.js
index 6d6c99a3..a4cea9c2 100755
--- a/bin/dev.js
+++ b/bin/dev.js
@@ -1,5 +1,5 @@
 #!/usr/bin/env tsx
-import { createProgram, runCLI } from "../src/cli/index.ts";
+import { runCLI } from "../src/cli/index.ts";
 
 // Disable Clack spinners and animations in non-interactive environments.
 // Clack only checks the CI env var, so we set it when stdin/stdout aren't TTYs.
diff --git a/bin/run.js b/bin/run.js
index 220a2665..daa3a38d 100755
--- a/bin/run.js
+++ b/bin/run.js
@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { createProgram, runCLI } from "../dist/index.js";
+import { runCLI } from "../dist/index.js";
 
 // Disable Clack spinners and animations in non-interactive environments.
 // Clack only checks the CI env var, so we set it when stdin/stdout aren't TTYs.
diff --git a/package-lock.json b/package-lock.json
index cefc27dd..6d9c3c5f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -933,9 +933,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-x64-gnu": {
-      "version": "4.56.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.56.0.tgz",
-      "integrity": "sha512-MVC6UDp16ZSH7x4rtuJPAEoE1RwS8N4oK9DLHy3FTEdFoUTCFVzMfJl/BVJ330C+hx8FfprA5Wqx4FhZXkj2Kw==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.57.1.tgz",
+      "integrity": "sha512-ABca4ceT4N+Tv/GtotnWAeXZUZuM/9AQyCyKYyKnpk4yoA7QIAuBt6Hkgpw8kActYlew2mvckXkvx0FfoInnLg==",
       "cpu": [
         "x64"
       ],
diff --git a/src/cli/commands/functions/deploy.ts b/src/cli/commands/functions/deploy.ts
index 2886aa82..718bbe30 100644
--- a/src/cli/commands/functions/deploy.ts
+++ b/src/cli/commands/functions/deploy.ts
@@ -3,6 +3,7 @@ import { log } from "@clack/prompts";
 import type { CLIContext } from "@/cli/types.js";
 import { pushFunctions } from "@/core/resources/function/index.js";
 import { readProjectConfig } from "@/core/index.js";
+import { ApiError } from "@/core/errors.js";
 import { runCommand, runTask } from "@/cli/utils/index.js";
 import type { RunCommandResult } from "@/cli/utils/runCommand.js";
 
@@ -41,7 +42,12 @@ async function deployFunctionsAction(): Promise<RunCommandResult> {
     const errorMessages = result.errors
       .map((e) => `'${e.name}' function: ${e.message}`)
       .join("\n");
-    throw new Error(`Function deployment errors:\n${errorMessages}`);
+    throw new ApiError(`Function deployment errors:\n${errorMessages}`, {
+      hints: [
+        { message: "Check the function code for syntax errors" },
+        { message: "Ensure all imports are valid" },
+      ],
+    });
   }
 
   return { outroMessage: "Functions deployed to Base44" };
diff --git a/src/cli/commands/project/create.ts b/src/cli/commands/project/create.ts
index 764e50d2..33cc690d 100644
--- a/src/cli/commands/project/create.ts
+++ b/src/cli/commands/project/create.ts
@@ -8,6 +8,7 @@ import type { CLIContext } from "@/cli/types.js";
 import { createProjectFiles, listTemplates, readProjectConfig, setAppConfig } from "@/core/project/index.js";
 import type { Template } from "@/core/project/index.js";
 import { deploySite, isDirEmpty, pushEntities } from "@/core/index.js";
+import { InvalidInputError } from "@/core/errors.js";
 import {
   runCommand,
   runTask,
@@ -32,7 +33,14 @@ async function getTemplateById(templateId: string): Promise<Template> {
   const template = templates.find((t) => t.id === templateId);
   if (!template) {
     const validIds = templates.map((t) => t.id).join(", ");
-    throw new Error(`Template "${templateId}" not found. Available templates: ${validIds}`);
+    throw new InvalidInputError(
+      `Template "${templateId}" not found.`,
+      {
+        hints: [
+          { message: `Use one of: ${validIds}` },
+        ],
+      }
+    );
   }
   return template;
 }
diff --git a/src/cli/commands/project/link.ts b/src/cli/commands/project/link.ts
index 8358800e..fdad9793 100644
--- a/src/cli/commands/project/link.ts
+++ b/src/cli/commands/project/link.ts
@@ -12,6 +12,7 @@ import {
   listProjects,
 } from "@/core/project/index.js";
 import type { Project } from "@/core/project/index.js";
+import { ConfigNotFoundError, ConfigExistsError, InvalidInputError } from "@/core/errors.js";
 import {
   runCommand,
   runTask,
@@ -124,14 +125,19 @@ async function link(options: LinkOptions): Promise<RunCommandResult> {
   const projectRoot = await findProjectRoot();
 
   if (!projectRoot) {
-    throw new Error(
+    throw new ConfigNotFoundError(
       "No Base44 project found. Run this command from a project directory with a config.jsonc file."
     );
   }
 
   if (await appConfigExists(projectRoot.root)) {
-    throw new Error(
-      "Project is already linked. An .app.jsonc file with the appId already exists."
+    throw new ConfigExistsError(
+      "Project is already linked. An .app.jsonc file with the appId already exists.",
+      {
+        hints: [
+          { message: "If you want to re-link, delete the existing .app.jsonc file first" },
+        ],
+      }
     );
   }
 
@@ -160,8 +166,14 @@ async function link(options: LinkOptions): Promise<RunCommandResult> {
       // Validate that the provided project ID exists and is linkable
       const project = linkableProjects.find((p) => p.id === options.projectId);
       if (!project) {
-        throw new Error(
-          `Project with ID "${options.projectId}" not found or not available for linking.`
+        throw new InvalidInputError(
+          `Project with ID "${options.projectId}" not found or not available for linking.`,
+          {
+            hints: [
+              { message: "Check the project ID is correct" },
+              { message: "Use 'base44 link' without --projectId to see available projects" },
+            ],
+          }
         );
       }
       projectId = options.projectId;
diff --git a/src/cli/commands/site/deploy.ts b/src/cli/commands/site/deploy.ts
index 0b6a4fe5..b33efa6b 100644
--- a/src/cli/commands/site/deploy.ts
+++ b/src/cli/commands/site/deploy.ts
@@ -4,6 +4,7 @@ import { confirm, isCancel } from "@clack/prompts";
 import type { CLIContext } from "@/cli/types.js";
 import { readProjectConfig } from "@/core/project/index.js";
 import { deploySite } from "@/core/site/index.js";
+import { ConfigNotFoundError } from "@/core/errors.js";
 import { runCommand, runTask } from "@/cli/utils/index.js";
 import type { RunCommandResult } from "@/cli/utils/runCommand.js";
 
@@ -15,8 +16,13 @@ async function deployAction(options: DeployOptions): Promise<RunCommandResult> {
   const { project } = await readProjectConfig();
 
   if (!project.site?.outputDirectory) {
-    throw new Error(
-      "No site configuration found. Please add 'site.outputDirectory' to your config.jsonc"
+    throw new ConfigNotFoundError(
+      "No site configuration found.",
+      {
+        hints: [
+          { message: "Add 'site.outputDirectory' to your config.jsonc (e.g., \"site\": { \"outputDirectory\": \"dist\" })" },
+        ],
+      }
     );
   }
 
diff --git a/src/cli/telemetry/error-reporter.ts b/src/cli/telemetry/error-reporter.ts
index df7aa2de..451547ca 100644
--- a/src/cli/telemetry/error-reporter.ts
+++ b/src/cli/telemetry/error-reporter.ts
@@ -2,6 +2,7 @@ import { release, type } from "node:os";
 import { nanoid } from "nanoid";
 import { determineAgent } from "@vercel/detect-agent";
 import { getPostHogClient, isTelemetryEnabled } from "./posthog.js";
+import { isCLIError, isUserError } from "@/core/errors.js";
 import packageJson from "../../../package.json";
 
 /**
@@ -58,9 +59,13 @@ export class ErrorReporter {
     return this.context.user?.email ?? `anon-${this.sessionId}`;
   }
 
-  private buildProperties(): Record<string, unknown> {
+  private buildProperties(error?: Error): Record<string, unknown> {
     const { user, command, appId, api } = this.context;
 
+    // Extract CLIError-specific properties if applicable
+    const errorCode = error && isCLIError(error) ? error.code : undefined;
+    const userError = error ? isUserError(error) : undefined;
+
     return {
       // Session
       session_id: this.sessionId,
@@ -78,6 +83,12 @@ export class ErrorReporter {
       // App
       app_id: appId,
 
+      // Error context (from CLIError)
+      ...(errorCode !== undefined && {
+        error_code: errorCode,
+        is_user_error: userError,
+      }),
+
       // API error
       api_status_code: api?.statusCode,
       api_error_body: api?.errorBody,
@@ -100,6 +111,11 @@ export class ErrorReporter {
     };
   }
 
+  /**
+   * Capture an exception and report it to PostHog.
+   * Includes error code and isUserError for CLIError instances.
+   * Safe to call - never throws, logs errors to console.
+   */
   captureException(error: Error): void {
     if (!isTelemetryEnabled()) {
       return;
@@ -107,7 +123,7 @@ export class ErrorReporter {
 
     try {
       const client = getPostHogClient();
-      client?.captureException(error, this.getDistinctId(), this.buildProperties());
+      client?.captureException(error, this.getDistinctId(), this.buildProperties(error));
     } catch {
       // Silent - don't let error reporting break the CLI
     }
diff --git a/src/core/auth/api.ts b/src/core/auth/api.ts
index e9b923b8..19f4fdae 100644
--- a/src/core/auth/api.ts
+++ b/src/core/auth/api.ts
@@ -1,4 +1,4 @@
-import { AuthApiError, AuthValidationError } from "@/core/errors.js";
+import { ApiError, SchemaValidationError } from "@/core/errors.js";
 import {
   DeviceCodeResponseSchema,
   TokenResponseSchema,
@@ -23,17 +23,16 @@ export async function generateDeviceCode(): Promise<DeviceCodeResponse> {
   });
 
   if (!response.ok) {
-    throw new AuthApiError(
-      `Failed to generate device code: ${response.status} ${response.statusText}`
+    throw new ApiError(
+      `Failed to generate device code: ${response.status} ${response.statusText}`,
+      { statusCode: response.status }
     );
   }
 
   const result = DeviceCodeResponseSchema.safeParse(await response.json());
 
   if (!result.success) {
-    throw new AuthValidationError(
-      `Invalid device code response from server: ${result.error.message}`
-    );
+    throw new SchemaValidationError("Invalid device code response from server", result.error);
   }
 
   return result.data;
@@ -64,9 +63,7 @@ export async function getTokenFromDeviceCode(
     const errorResult = OAuthErrorSchema.safeParse(json);
 
     if (!errorResult.success) {
-      throw new AuthValidationError(
-        `Token request failed: ${errorResult.error.message}`
-      );
+      throw new SchemaValidationError("Token request failed", errorResult.error);
     }
 
     const { error, error_description } = errorResult.data;
@@ -77,15 +74,15 @@ export async function getTokenFromDeviceCode(
     }
 
     // Actual errors
-    throw new AuthApiError(error_description ?? `OAuth error: ${error}`);
+    throw new ApiError(error_description ?? `OAuth error: ${error}`, {
+      statusCode: response.status,
+    });
   }
 
   const result = TokenResponseSchema.safeParse(json);
 
   if (!result.success) {
-    throw new AuthValidationError(
-      `Invalid token response from server: ${result.error.message}`
-    );
+    throw new SchemaValidationError("Invalid token response from server", result.error);
   }
 
   return result.data;
@@ -113,19 +110,21 @@ export async function renewAccessToken(
     const errorResult = OAuthErrorSchema.safeParse(json);
 
     if (!errorResult.success) {
-      throw new AuthApiError(`Token refresh failed: ${response.statusText}`);
+      throw new ApiError(`Token refresh failed: ${response.statusText}`, {
+        statusCode: response.status,
+      });
     }
 
     const { error, error_description } = errorResult.data;
-    throw new AuthApiError(error_description ?? `OAuth error: ${error}`);
+    throw new ApiError(error_description ?? `OAuth error: ${error}`, {
+      statusCode: response.status,
+    });
   }
 
   const result = TokenResponseSchema.safeParse(json);
 
   if (!result.success) {
-    throw new AuthValidationError(
-      `Invalid token response from server: ${result.error.message}`
-    );
+    throw new SchemaValidationError("Invalid token response from server", result.error);
   }
 
   return result.data;
@@ -139,15 +138,15 @@ export async function getUserInfo(
   });
 
   if (!response.ok) {
-    throw new AuthApiError(`Failed to fetch user info: ${response.status}`);
+    throw new ApiError(`Failed to fetch user info: ${response.status}`, {
+      statusCode: response.status,
+    });
   }
 
   const result = UserInfoSchema.safeParse(await response.json());
 
   if (!result.success) {
-    throw new AuthValidationError(
-      `Invalid UserInfo response from server: ${result.error.message}`
-    );
+    throw new SchemaValidationError("Invalid UserInfo response from server", result.error);
   }
 
   return result.data;
diff --git a/src/core/auth/config.ts b/src/core/auth/config.ts
index e23d7625..e08731ec 100644
--- a/src/core/auth/config.ts
+++ b/src/core/auth/config.ts
@@ -3,6 +3,11 @@ import { readJsonFile, writeJsonFile, deleteFile } from "@/core/utils/fs.js";
 import { renewAccessToken } from "@/core/auth/api.js";
 import { AuthDataSchema } from "@/core/auth/schema.js";
 import type { AuthData } from "@/core/auth/schema.js";
+import {
+  AuthRequiredError,
+  SchemaValidationError,
+  FileReadError,
+} from "@/core/errors.js";
 
 // Buffer time before expiration to trigger proactive refresh (60 seconds)
 const TOKEN_REFRESH_BUFFER_MS = 60 * 1000;
@@ -26,19 +31,19 @@ export async function readAuth(): Promise<AuthData> {
     const result = AuthDataSchema.safeParse(parsed);
 
     if (!result.success) {
-      throw new Error(
-        `Invalid authentication data: ${result.error.issues
-          .map((e) => e.message)
-          .join(", ")}`
-      );
+      throw new SchemaValidationError("Invalid authentication data", result.error);
     }
 
     return result.data;
   } catch (error) {
-    throw new Error(
+    if (error instanceof SchemaValidationError) {
+      throw error;
+    }
+    throw new FileReadError(
       `Failed to read authentication file: ${
         error instanceof Error ? error.message : "Unknown error"
-      }`
+      }`,
+      { cause: error instanceof Error ? error : undefined }
     );
   }
 }
@@ -47,20 +52,17 @@ export async function writeAuth(authData: AuthData): Promise<void> {
   const result = AuthDataSchema.safeParse(authData);
 
   if (!result.success) {
-    throw new Error(
-      `Invalid authentication data: ${result.error.issues
-        .map((e) => e.message)
-        .join(", ")}`
-    );
+    throw new SchemaValidationError("Invalid authentication data", result.error);
   }
 
   try {
     await writeJsonFile(getAuthFilePath(), result.data);
   } catch (error) {
-    throw new Error(
+    throw new FileReadError(
       `Failed to write authentication file: ${
         error instanceof Error ? error.message : "Unknown error"
-      }`
+      }`,
+      { cause: error instanceof Error ? error : undefined }
     );
   }
 }
@@ -69,10 +71,11 @@ export async function deleteAuth(): Promise<void> {
   try {
     await deleteFile(getAuthFilePath());
   } catch (error) {
-    throw new Error(
+    throw new FileReadError(
       `Failed to delete authentication file: ${
         error instanceof Error ? error.message : "Unknown error"
-      }`
+      }`,
+      { cause: error instanceof Error ? error : undefined }
     );
   }
 }
@@ -136,7 +139,7 @@ export async function isLoggedIn(): Promise<boolean> {
 /**
  * Ensures the user is logged in before proceeding.
  *
- * @throws {Error} If the user is not logged in.
+ * @throws {AuthRequiredError} If the user is not logged in.
  *
  * @example
  * await requireAuth();
@@ -144,6 +147,6 @@ export async function isLoggedIn(): Promise<boolean> {
  */
 export async function requireAuth(): Promise<void> {
   if (!(await isLoggedIn())) {
-    throw new Error("Not logged in. Please run 'base44 login' first.");
+    throw new AuthRequiredError("Not logged in. Please run 'base44 login' first.");
   }
 }
diff --git a/src/core/errors.ts b/src/core/errors.ts
index c9a64640..a88d8b60 100644
--- a/src/core/errors.ts
+++ b/src/core/errors.ts
@@ -1,13 +1,277 @@
-export class AuthApiError extends Error {
-  constructor(message: string, public readonly cause?: unknown) {
+/**
+ * CLI Error System
+ *
+ * Error hierarchy:
+ * - CLIError (base class)
+ *   - UserError (user did something wrong - fixable by user)
+ *   - SystemError (something broke - needs investigation)
+ *
+ * All errors support hints for actionable next steps.
+ */
+
+import { z } from "zod";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ErrorHint {
+  message: string;
+  command?: string; // Optional command to run
+}
+
+export interface CLIErrorOptions {
+  hints?: ErrorHint[];
+  cause?: Error;
+}
+
+// ============================================================================
+// Base Classes
+// ============================================================================
+
+/**
+ * Base class for all CLI errors.
+ * Provides structured error data with code, hints, and cause tracking.
+ */
+export abstract class CLIError extends Error {
+  abstract readonly code: string;
+  readonly hints: ErrorHint[];
+  override readonly cause?: Error;
+
+  constructor(message: string, options?: CLIErrorOptions) {
     super(message);
-    this.name = "AuthApiError";
+    this.name = this.constructor.name;
+    this.hints = options?.hints ?? [];
+    this.cause = options?.cause;
+
+    // Maintain proper stack trace in V8 environments (Node.js)
+    Error.captureStackTrace(this, this.constructor);
   }
 }
 
-export class AuthValidationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "AuthValidationError";
+/**
+ * User errors - the user did something wrong that they can fix.
+ * Examples: not logged in, invalid config, missing project
+ */
+export abstract class UserError extends CLIError {}
+
+/**
+ * System errors - something broke that needs investigation.
+ * Examples: API failures, network issues, file system errors
+ */
+export abstract class SystemError extends CLIError {}
+
+// ============================================================================
+// User Errors
+// ============================================================================
+
+/**
+ * Thrown when the user is not authenticated.
+ */
+export class AuthRequiredError extends UserError {
+  readonly code = "AUTH_REQUIRED";
+
+  constructor(message = "Authentication required", options?: CLIErrorOptions) {
+    super(message, {
+      hints: options?.hints ?? [
+        { message: "Run 'base44 login' to authenticate", command: "base44 login" },
+      ],
+      cause: options?.cause,
+    });
   }
 }
+
+/**
+ * Thrown when authentication has expired.
+ */
+export class AuthExpiredError extends UserError {
+  readonly code = "AUTH_EXPIRED";
+
+  constructor(message = "Authentication has expired", options?: CLIErrorOptions) {
+    super(message, {
+      hints: options?.hints ?? [
+        { message: "Run 'base44 login' to re-authenticate", command: "base44 login" },
+      ],
+      cause: options?.cause,
+    });
+  }
+}
+
+/**
+ * Thrown when a required config file is not found.
+ */
+export class ConfigNotFoundError extends UserError {
+  readonly code = "CONFIG_NOT_FOUND";
+
+  constructor(message = "No Base44 project found in this directory", options?: CLIErrorOptions) {
+    super(message, {
+      hints: options?.hints ?? [
+        { message: "Run 'base44 create' to create a new project", command: "base44 create" },
+        { message: "Or run 'base44 link' to link an existing project", command: "base44 link" },
+      ],
+      cause: options?.cause,
+    });
+  }
+}
+
+/**
+ * Thrown when a config file has invalid syntax or structure.
+ */
+export class ConfigInvalidError extends UserError {
+  readonly code = "CONFIG_INVALID";
+
+  constructor(message: string, options?: CLIErrorOptions) {
+    super(message, {
+      hints: options?.hints ?? [
+        { message: "Check config.jsonc syntax and fix any errors" },
+      ],
+      cause: options?.cause,
+    });
+  }
+}
+
+/**
+ * Thrown when trying to create a project that already exists.
+ */
+export class ConfigExistsError extends UserError {
+  readonly code = "CONFIG_EXISTS";
+
+  constructor(message: string, options?: CLIErrorOptions) {
+    super(message, {
+      hints: options?.hints ?? [
+        { message: "Choose a different location or remove the existing project" },
+      ],
+      cause: options?.cause,
+    });
+  }
+}
+
+/**
+ * Thrown when Zod/schema validation fails (data structure is wrong).
+ *
+ * @example
+ * const result = schema.safeParse(data);
+ * if (!result.success) {
+ *   throw new SchemaValidationError("Invalid entity file", result.error);
+ * }
+ */
+export class SchemaValidationError extends UserError {
+  readonly code = "SCHEMA_INVALID";
+
+  constructor(context: string, zodError: z.ZodError) {
+    super(`${context}:\n${z.prettifyError(zodError)}`, {
+      hints: [{ message: "Fix the schema/data structure errors above" }],
+    });
+  }
+}
+
+/**
+ * Thrown when user input is invalid (e.g., template not found, project ID not found).
+ */
+export class InvalidInputError extends UserError {
+  readonly code = "INVALID_INPUT";
+
+  constructor(message: string, options?: CLIErrorOptions) {
+    super(message, options);
+  }
+}
+
+// ============================================================================
+// System Errors
+// ============================================================================
+
+/**
+ * Thrown when an API request fails.
+ */
+export class ApiError extends SystemError {
+  readonly code = "API_ERROR";
+  readonly statusCode?: number;
+
+  constructor(message: string, options?: CLIErrorOptions & { statusCode?: number }) {
+    const hints = options?.hints ?? ApiError.getDefaultHints(options?.statusCode);
+    super(message, { hints, cause: options?.cause });
+    this.statusCode = options?.statusCode;
+  }
+
+  private static getDefaultHints(statusCode?: number): ErrorHint[] {
+    if (statusCode === 401) {
+      return [{ message: "Try logging in again", command: "base44 login" }];
+    }
+    if (statusCode === 403) {
+      return [{ message: "You don't have permission to perform this action" }];
+    }
+    if (statusCode === 404) {
+      return [{ message: "The requested resource was not found" }];
+    }
+    return [{ message: "Check your network connection and try again" }];
+  }
+}
+
+/**
+ * Thrown when a file is not found.
+ */
+export class FileNotFoundError extends SystemError {
+  readonly code = "FILE_NOT_FOUND";
+
+  constructor(message: string, options?: CLIErrorOptions) {
+    super(message, {
+      hints: options?.hints ?? [{ message: "Check the file path and try again" }],
+      cause: options?.cause,
+    });
+  }
+}
+
+/**
+ * Thrown when a file cannot be read.
+ */
+export class FileReadError extends SystemError {
+  readonly code = "FILE_READ_ERROR";
+
+  constructor(message: string, options?: CLIErrorOptions) {
+    super(message, {
+      hints: options?.hints ?? [{ message: "Check file permissions and try again" }],
+      cause: options?.cause,
+    });
+  }
+}
+
+/**
+ * Thrown for unexpected internal errors.
+ */
+export class InternalError extends SystemError {
+  readonly code = "INTERNAL_ERROR";
+
+  constructor(message: string, options?: CLIErrorOptions) {
+    super(message, {
+      hints: options?.hints ?? [
+        { message: "This is an unexpected error. Please report it if it persists." },
+      ],
+      cause: options?.cause,
+    });
+  }
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Check if an error is a CLIError (has code and hints).
+ */
+export function isCLIError(error: unknown): error is CLIError {
+  return error instanceof CLIError;
+}
+
+/**
+ * Check if an error is a UserError.
+ */
+export function isUserError(error: unknown): error is UserError {
+  return error instanceof UserError;
+}
+
+/**
+ * Check if an error is a SystemError.
+ */
+export function isSystemError(error: unknown): error is SystemError {
+  return error instanceof SystemError;
+}
diff --git a/src/core/project/api.ts b/src/core/project/api.ts
index eaeab5e0..07e0e523 100644
--- a/src/core/project/api.ts
+++ b/src/core/project/api.ts
@@ -1,6 +1,7 @@
 import { base44Client } from "@/core/clients/index.js";
 import { CreateProjectResponseSchema, ProjectsResponseSchema } from "@/core/project/schema.js";
 import type { ProjectsResponse } from "@/core/project/schema.js";
+import { SchemaValidationError } from "@/core/errors.js";
 
 export async function createProject(projectName: string, description?: string) {
   const response = await base44Client.post("api/apps", {
@@ -12,10 +13,14 @@ export async function createProject(projectName: string, description?: string) {
     },
   });
 
-  const result = CreateProjectResponseSchema.parse(await response.json());
+  const result = CreateProjectResponseSchema.safeParse(await response.json());
+
+  if (!result.success) {
+    throw new SchemaValidationError("Invalid response from server", result.error);
+  }
 
   return {
-    projectId: result.id,
+    projectId: result.data.id,
   };
 }
 
@@ -27,7 +32,11 @@ export async function listProjects(): Promise<ProjectsResponse> {
     }
   });
 
-  const projects = ProjectsResponseSchema.parse(await response.json());
+  const result = ProjectsResponseSchema.safeParse(await response.json());
+
+  if (!result.success) {
+    throw new SchemaValidationError("Invalid response from server", result.error);
+  }
 
-  return projects;
+  return result.data;
 }
diff --git a/src/core/project/app-config.ts b/src/core/project/app-config.ts
index c27b97a9..c9be8398 100644
--- a/src/core/project/app-config.ts
+++ b/src/core/project/app-config.ts
@@ -5,6 +5,11 @@ import { APP_CONFIG_PATTERN } from "@/core/consts.js";
 import { AppConfigSchema } from "@/core/project/schema.js";
 import type { AppConfig } from "@/core/project/schema.js";
 import { findProjectRoot } from "@/core/project/config.js";
+import {
+  ConfigNotFoundError,
+  ConfigInvalidError,
+  SchemaValidationError,
+} from "@/core/errors.js";
 
 export interface CachedAppConfig {
   id: string;
@@ -53,15 +58,20 @@ export async function initAppConfig(): Promise<CachedAppConfig> {
 
   const projectRoot = await findProjectRoot();
   if (!projectRoot) {
-    throw new Error(
+    throw new ConfigNotFoundError(
       "No Base44 project found. Run this command from a project directory with a config.jsonc file."
     );
   }
 
   const config = await readAppConfig(projectRoot.root);
   if (!config?.id) {
-    throw new Error(
-      "App not configured. Create a .app.jsonc file or run 'base44 link' to link this project."
+    throw new ConfigInvalidError(
+      "App not configured. Create a .app.jsonc file or run 'base44 link' to link this project.",
+      {
+        hints: [
+          { message: "Run 'base44 link' to link this project to a Base44 app", command: "base44 link" },
+        ],
+      }
     );
   }
 
@@ -71,11 +81,11 @@ export async function initAppConfig(): Promise<CachedAppConfig> {
 
 /**
  * Get the cached app config.
- * @throws Error if not initialized - call initAppConfig() or setAppConfig() first
+ * @throws ConfigInvalidError if not initialized - call initAppConfig() or setAppConfig() first
  */
 export function getAppConfig(): CachedAppConfig {
   if (!cache) {
-    throw new Error(
+    throw new ConfigInvalidError(
       "App config not initialized. Ensure the command uses requireAppConfig option."
     );
   }
@@ -134,7 +144,7 @@ async function readAppConfig(
   const result = AppConfigSchema.safeParse(parsed);
 
   if (!result.success) {
-    throw new Error(`Invalid app configuration: ${result.error.message}`);
+    throw new SchemaValidationError("Invalid app configuration", result.error);
   }
 
   return result.data;
diff --git a/src/core/project/config.ts b/src/core/project/config.ts
index 8457d695..e2847267 100644
--- a/src/core/project/config.ts
+++ b/src/core/project/config.ts
@@ -7,6 +7,7 @@ import { functionResource } from "@/core/resources/function/index.js";
 import { agentResource } from "@/core/resources/agent/index.js";
 import type { ProjectData, ProjectRoot } from "@/core/project/types.js";
 import { ProjectConfigSchema } from "@/core/project/schema.js";
+import { ConfigNotFoundError, SchemaValidationError } from "@/core/errors.js";
 
 async function findConfigInDir(dir: string): Promise<string | null> {
   const files = await globby(PROJECT_CONFIG_PATTERNS, {
@@ -69,7 +70,7 @@ export async function readProjectConfig(
   }
 
   if (!found) {
-    throw new Error(
+    throw new ConfigNotFoundError(
       `Project root not found. Please ensure config.jsonc or config.json exists in the project directory or ${PROJECT_SUBDIR}/ subdirectory.`
     );
   }
@@ -80,7 +81,7 @@ export async function readProjectConfig(
   const result = ProjectConfigSchema.safeParse(parsed);
 
   if (!result.success) {
-    throw new Error(`Invalid project configuration: ${result.error.message}`);
+    throw new SchemaValidationError("Invalid project configuration", result.error);
   }
 
   const project = result.data;
diff --git a/src/core/project/create.ts b/src/core/project/create.ts
index 1fdb3b2b..3257e11e 100644
--- a/src/core/project/create.ts
+++ b/src/core/project/create.ts
@@ -3,6 +3,7 @@ import { PROJECT_CONFIG_PATTERNS } from "@/core/consts.js";
 import { createProject } from "@/core/project/api.js";
 import { renderTemplate } from "@/core/project/template.js";
 import type { Template } from "@/core/project/schema.js";
+import { ConfigExistsError } from "@/core/errors.js";
 
 export interface CreateProjectOptions {
   name: string;
@@ -28,7 +29,7 @@ export async function createProjectFiles(
   });
 
   if (existingConfigs.length > 0) {
-    throw new Error(
+    throw new ConfigExistsError(
       `A Base44 project already exists at ${existingConfigs[0]}. Please choose a different location.`
     );
   }
diff --git a/src/core/project/template.ts b/src/core/project/template.ts
index e417c22c..dd888d66 100644
--- a/src/core/project/template.ts
+++ b/src/core/project/template.ts
@@ -6,6 +6,7 @@ import { getTemplatesDir, getTemplatesIndexPath } from "@/core/config.js";
 import { readJsonFile, writeFile, copyFile } from "@/core/utils/fs.js";
 import { TemplatesConfigSchema } from "@/core/project/schema.js";
 import type { Template } from "@/core/project/schema.js";
+import { SchemaValidationError } from "@/core/errors.js";
 
 export interface TemplateData {
   name: string;
@@ -19,8 +20,13 @@ interface TemplateFrontmatter {
 
 export async function listTemplates(): Promise<Template[]> {
   const parsed = await readJsonFile(getTemplatesIndexPath());
-  const result = TemplatesConfigSchema.parse(parsed);
-  return result.templates;
+  const result = TemplatesConfigSchema.safeParse(parsed);
+
+  if (!result.success) {
+    throw new SchemaValidationError("Invalid templates configuration", result.error);
+  }
+
+  return result.data.templates;
 }
 
 /**
diff --git a/src/core/resources/agent/api.ts b/src/core/resources/agent/api.ts
index f6678c34..0c572fa0 100644
--- a/src/core/resources/agent/api.ts
+++ b/src/core/resources/agent/api.ts
@@ -1,6 +1,7 @@
 import { getAppClient, formatApiError } from "@/core/clients/index.js";
 import { SyncAgentsResponseSchema, ListAgentsResponseSchema } from "./schema.js";
 import type { SyncAgentsResponse, AgentConfig, ListAgentsResponse } from "./schema.js";
+import { ApiError, SchemaValidationError } from "@/core/errors.js";
 
 export async function pushAgents(
   agents: AgentConfig[]
@@ -18,10 +19,18 @@ export async function pushAgents(
 
   if (!response.ok) {
     const errorJson: unknown = await response.json();
-    throw new Error(`Error occurred while syncing agents: ${formatApiError(errorJson)}`);
+    throw new ApiError(`Error occurred while syncing agents: ${formatApiError(errorJson)}`, {
+      statusCode: response.status,
+    });
   }
 
-  return SyncAgentsResponseSchema.parse(await response.json());
+  const result = SyncAgentsResponseSchema.safeParse(await response.json());
+
+  if (!result.success) {
+    throw new SchemaValidationError("Invalid response from server", result.error);
+  }
+
+  return result.data;
 }
 
 export async function fetchAgents(): Promise<ListAgentsResponse> {
@@ -32,8 +41,16 @@ export async function fetchAgents(): Promise<ListAgentsResponse> {
 
   if (!response.ok) {
     const errorJson: unknown = await response.json();
-    throw new Error(`Error occurred while fetching agents: ${formatApiError(errorJson)}`);
+    throw new ApiError(`Error occurred while fetching agents: ${formatApiError(errorJson)}`, {
+      statusCode: response.status,
+    });
+  }
+
+  const result = ListAgentsResponseSchema.safeParse(await response.json());
+
+  if (!result.success) {
+    throw new SchemaValidationError("Invalid response from server", result.error);
   }
 
-  return ListAgentsResponseSchema.parse(await response.json());
+  return result.data;
 }
diff --git a/src/core/resources/agent/config.ts b/src/core/resources/agent/config.ts
index abb01f88..048507cd 100644
--- a/src/core/resources/agent/config.ts
+++ b/src/core/resources/agent/config.ts
@@ -4,6 +4,7 @@ import { readJsonFile, pathExists, writeJsonFile, deleteFile } from "../../utils
 import { AgentConfigSchema } from "./schema.js";
 import type { AgentConfig, AgentConfigApiResponse } from "./schema.js";
 import { CONFIG_FILE_EXTENSION_GLOB, CONFIG_FILE_EXTENSION } from "../../consts.js";
+import { SchemaValidationError } from "@/core/errors.js";
 
 export function generateAgentConfigContent(name: string): string {
   return `// Base44 Agent Configuration
@@ -29,9 +30,7 @@ async function readAgentFile(agentPath: string): Promise<AgentConfig> {
   const result = AgentConfigSchema.safeParse(parsed);
 
   if (!result.success) {
-    throw new Error(
-      `Invalid agent config in ${agentPath}: ${result.error.message}`
-    );
+    throw new SchemaValidationError(`Invalid agent file at ${agentPath}`, result.error);
   }
 
   return result.data;
diff --git a/src/core/resources/entity/api.ts b/src/core/resources/entity/api.ts
index 52e43c16..033d5339 100644
--- a/src/core/resources/entity/api.ts
+++ b/src/core/resources/entity/api.ts
@@ -1,6 +1,7 @@
 import { getAppClient, formatApiError } from "@/core/clients/index.js";
 import { SyncEntitiesResponseSchema } from "@/core/resources/entity/schema.js";
 import type { SyncEntitiesResponse, Entity } from "@/core/resources/entity/schema.js";
+import { ApiError, SchemaValidationError } from "@/core/errors.js";
 
 export async function syncEntities(
   entities: Entity[]
@@ -20,15 +21,22 @@ export async function syncEntities(
   if (!response.ok) {
     const errorJson: unknown = await response.json();
     if (response.status === 428) {
-      throw new Error(`Failed to delete entity: ${formatApiError(errorJson)}`);
+      throw new ApiError(`Failed to delete entity: ${formatApiError(errorJson)}`, {
+        statusCode: response.status,
+      });
     }
 
-    throw new Error(
-      `Error occurred while syncing entities: ${formatApiError(errorJson)}`
+    throw new ApiError(
+      `Error occurred while syncing entities: ${formatApiError(errorJson)}`,
+      { statusCode: response.status }
     );
   }
 
-  const result = SyncEntitiesResponseSchema.parse(await response.json());
+  const result = SyncEntitiesResponseSchema.safeParse(await response.json());
 
-  return result;
+  if (!result.success) {
+    throw new SchemaValidationError("Invalid response from server", result.error);
+  }
+
+  return result.data;
 }
diff --git a/src/core/resources/entity/config.ts b/src/core/resources/entity/config.ts
index eacf7213..70f62435 100644
--- a/src/core/resources/entity/config.ts
+++ b/src/core/resources/entity/config.ts
@@ -3,15 +3,14 @@ import { readJsonFile, pathExists } from "@/core/utils/fs.js";
 import { EntitySchema } from "@/core/resources/entity/schema.js";
 import type { Entity } from "@/core/resources/entity/schema.js";
 import { CONFIG_FILE_EXTENSION_GLOB } from "@/core/consts.js";
+import { SchemaValidationError } from "@/core/errors.js";
 
 async function readEntityFile(entityPath: string): Promise<Entity> {
   const parsed = await readJsonFile(entityPath);
   const result = EntitySchema.safeParse(parsed);
 
   if (!result.success) {
-    throw new Error(
-      `Invalid entity in ${entityPath}: ${result.error.message}`
-    );
+    throw new SchemaValidationError(`Invalid entity file at ${entityPath}`, result.error);
   }
 
   return result.data;
diff --git a/src/core/resources/function/api.ts b/src/core/resources/function/api.ts
index d3f6cec4..39b531ea 100644
--- a/src/core/resources/function/api.ts
+++ b/src/core/resources/function/api.ts
@@ -1,6 +1,7 @@
 import { getAppClient } from "@/core/clients/index.js";
 import { DeployFunctionsResponseSchema } from "@/core/resources/function/schema.js";
 import type { FunctionWithCode, DeployFunctionsResponse } from "@/core/resources/function/schema.js";
+import { SchemaValidationError } from "@/core/errors.js";
 
 function toDeployPayloadItem(fn: FunctionWithCode) {
   return {
@@ -23,6 +24,11 @@ export async function deployFunctions(
     timeout: 120_000
   });
 
-  const result = DeployFunctionsResponseSchema.parse(await response.json());
-  return result;
+  const result = DeployFunctionsResponseSchema.safeParse(await response.json());
+
+  if (!result.success) {
+    throw new SchemaValidationError("Invalid response from server", result.error);
+  }
+
+  return result.data;
 }
diff --git a/src/core/resources/function/config.ts b/src/core/resources/function/config.ts
index 13f8193d..c47de2aa 100644
--- a/src/core/resources/function/config.ts
+++ b/src/core/resources/function/config.ts
@@ -4,6 +4,7 @@ import { FUNCTION_CONFIG_FILE } from "@/core/consts.js";
 import { readJsonFile, pathExists } from "@/core/utils/fs.js";
 import { FunctionConfigSchema, FunctionSchema } from "@/core/resources/function/schema.js";
 import type { FunctionConfig, Function } from "@/core/resources/function/schema.js";
+import { SchemaValidationError, FileNotFoundError } from "@/core/errors.js";
 
 export async function readFunctionConfig(
   configPath: string
@@ -12,9 +13,7 @@ export async function readFunctionConfig(
   const result = FunctionConfigSchema.safeParse(parsed);
 
   if (!result.success) {
-    throw new Error(
-      `Invalid function configuration in ${configPath}: ${result.error.message}`
-    );
+    throw new SchemaValidationError(`Invalid function configuration in ${configPath}`, result.error);
   }
 
   return result.data;
@@ -26,7 +25,7 @@ export async function readFunction(configPath: string): Promise<Function> {
   const entryPath = join(functionDir, config.entry);
 
   if (!(await pathExists(entryPath))) {
-    throw new Error(
+    throw new FileNotFoundError(
       `Function entry file not found: ${entryPath} (referenced in ${configPath})`
     );
   }
@@ -39,9 +38,7 @@ export async function readFunction(configPath: string): Promise<Function> {
   const functionData = { ...config, entryPath, files };
   const result = FunctionSchema.safeParse(functionData);
   if (!result.success) {
-    throw new Error(
-      `Invalid function in ${configPath}: ${result.error.message}`
-    );
+    throw new SchemaValidationError(`Invalid function in ${configPath}`, result.error);
   }
 
   return result.data;
diff --git a/src/core/site/api.ts b/src/core/site/api.ts
index 98cfc4ac..2fdd8a17 100644
--- a/src/core/site/api.ts
+++ b/src/core/site/api.ts
@@ -2,6 +2,7 @@ import { getAppClient } from "@/core/clients/index.js";
 import { readFile } from "@/core/utils/fs.js";
 import { DeployResponseSchema } from "@/core/site/schema.js";
 import type { DeployResponse } from "@/core/site/schema.js";
+import { SchemaValidationError } from "@/core/errors.js";
 
 /**
  * Uploads a tar.gz archive file to the Base44 hosting API.
@@ -21,7 +22,11 @@ export async function uploadSite(archivePath: string): Promise<DeployResponse> {
     body: formData,
   });
 
-  const result = DeployResponseSchema.parse(await response.json());
+  const result = DeployResponseSchema.safeParse(await response.json());
 
-  return result;
+  if (!result.success) {
+    throw new SchemaValidationError("There was an issue deploying your site", result.error);
+  }
+
+  return result.data;
 }
diff --git a/src/core/site/deploy.ts b/src/core/site/deploy.ts
index 891d14ff..76ef73aa 100644
--- a/src/core/site/deploy.ts
+++ b/src/core/site/deploy.ts
@@ -6,20 +6,31 @@ import type { DeployResponse } from "@/core/site/schema.js";
 import { getSiteFilePaths } from "@/core/site/config.js";
 import { uploadSite } from "@/core/site/api.js";
 import { pathExists, deleteFile } from "@/core/utils/fs.js";
+import { FileNotFoundError, ConfigInvalidError } from "@/core/errors.js";
 
 export async function deploySite(
   siteOutputDir: string
 ): Promise<DeployResponse> {
   if (!(await pathExists(siteOutputDir))) {
-    throw new Error(
-      `Output directory does not exist: ${siteOutputDir}. Make sure to build your project first.`
+    throw new FileNotFoundError(
+      `Output directory does not exist: ${siteOutputDir}. Make sure to build your project first.`,
+      {
+        hints: [
+          { message: "Run your build command (e.g., 'npm run build') first" },
+        ],
+      }
     );
   }
 
   const filePaths = await getSiteFilePaths(siteOutputDir);
   if (filePaths.length === 0) {
-    throw new Error(
-      `No files found in output directory: ${siteOutputDir}. Make sure to build your project first.`
+    throw new ConfigInvalidError(
+      `No files found in output directory: ${siteOutputDir}. Make sure to build your project first.`,
+      {
+        hints: [
+          { message: "Run your build command (e.g., 'npm run build') first" },
+        ],
+      }
     );
   }
 
diff --git a/src/core/utils/fs.ts b/src/core/utils/fs.ts
index b296f983..22bdb69a 100644
--- a/src/core/utils/fs.ts
+++ b/src/core/utils/fs.ts
@@ -9,6 +9,7 @@ import {
 } from "node:fs/promises";
 import { dirname } from "node:path";
 import JSON5 from "json5";
+import { FileNotFoundError, FileReadError, ConfigInvalidError } from "@/core/errors.js";
 
 export async function pathExists(path: string): Promise<boolean> {
   try {
@@ -40,39 +41,41 @@ export async function copyFile(src: string, dest: string): Promise<void> {
 
 export async function readFile(filePath: string): Promise<Buffer> {
   if (!(await pathExists(filePath))) {
-    throw new Error(`File not found: ${filePath}`);
+    throw new FileNotFoundError(`File not found: ${filePath}`);
   }
 
   try {
     return await fsReadFile(filePath);
   } catch (error) {
-    throw new Error(
+    throw new FileReadError(
       `Failed to read file ${filePath}: ${
         error instanceof Error ? error.message : "Unknown error"
-      }`
+      }`,
+      { cause: error instanceof Error ? error : undefined }
     );
   }
 }
 
 export async function readTextFile(filePath: string): Promise<string> {
   if (!(await pathExists(filePath))) {
-    throw new Error(`File not found: ${filePath}`);
+    throw new FileNotFoundError(`File not found: ${filePath}`);
   }
 
   try {
     return await fsReadFile(filePath, "utf-8");
   } catch (error) {
-    throw new Error(
+    throw new FileReadError(
       `Failed to read file ${filePath}: ${
         error instanceof Error ? error.message : "Unknown error"
-      }`
+      }`,
+      { cause: error instanceof Error ? error : undefined }
     );
   }
 }
 
 export async function readJsonFile(filePath: string): Promise<unknown> {
   if (!(await pathExists(filePath))) {
-    throw new Error(`File not found: ${filePath}`);
+    throw new FileNotFoundError(`File not found: ${filePath}`);
   }
 
   try {
@@ -80,12 +83,15 @@ export async function readJsonFile(filePath: string): Promise<unknown> {
     return JSON5.parse(fileContent);
   } catch (error) {
     if (error instanceof SyntaxError) {
-      throw new Error(`File contains invalid JSON: ${filePath} (${error.message})`);
+      throw new ConfigInvalidError(`File contains invalid JSON: ${filePath} (${error.message})`, {
+        cause: error,
+      });
     }
-    throw new Error(
+    throw new FileReadError(
       `Failed to read file ${filePath}: ${
         error instanceof Error ? error.message : "Unknown error"
-      }`
+      }`,
+      { cause: error instanceof Error ? error : undefined }
     );
   }
 }
diff --git a/tests/core/errors.spec.ts b/tests/core/errors.spec.ts
index a42b73fe..9a6f5390 100644
--- a/tests/core/errors.spec.ts
+++ b/tests/core/errors.spec.ts
@@ -1,5 +1,166 @@
 import { describe, it, expect } from "vitest";
 import { formatApiError } from "../../src/core/clients/index.js";
+import {
+  AuthRequiredError,
+  AuthExpiredError,
+  ConfigNotFoundError,
+  ConfigInvalidError,
+  ConfigExistsError,
+  SchemaValidationError,
+  InvalidInputError,
+  ApiError,
+  FileNotFoundError,
+  FileReadError,
+  InternalError,
+  isCLIError,
+  isUserError,
+  isSystemError,
+} from "../../src/core/errors.js";
+
+describe("CLIError base class", () => {
+  it("has correct properties on UserError subclass", () => {
+    const error = new AuthRequiredError();
+    expect(error.code).toBe("AUTH_REQUIRED");
+    expect(isUserError(error)).toBe(true);
+    expect(error.hints.length).toBeGreaterThan(0);
+    expect(error.message).toContain("Authentication required");
+  });
+
+  it("has correct properties on SystemError subclass", () => {
+    const error = new ApiError("Test API error", { statusCode: 500 });
+    expect(error.code).toBe("API_ERROR");
+    expect(isUserError(error)).toBe(false);
+    expect(error.statusCode).toBe(500);
+    expect(error.hints.length).toBeGreaterThan(0);
+  });
+
+  it("preserves cause when provided", () => {
+    const cause = new Error("Original error");
+    const error = new ApiError("Wrapped error", { cause });
+    expect(error.cause).toBe(cause);
+  });
+
+  it("allows custom hints", () => {
+    const customHints = [{ message: "Custom hint", command: "base44 help" }];
+    const error = new InvalidInputError("Invalid input", { hints: customHints });
+    expect(error.hints).toEqual(customHints);
+  });
+});
+
+describe("UserError subclasses", () => {
+  it("AuthRequiredError has correct defaults", () => {
+    const error = new AuthRequiredError();
+    expect(error.code).toBe("AUTH_REQUIRED");
+    expect(isUserError(error)).toBe(true);
+    expect(error.hints.some(h => h.command === "base44 login")).toBe(true);
+  });
+
+  it("AuthExpiredError has correct defaults", () => {
+    const error = new AuthExpiredError();
+    expect(error.code).toBe("AUTH_EXPIRED");
+    expect(isUserError(error)).toBe(true);
+  });
+
+  it("ConfigNotFoundError has correct defaults", () => {
+    const error = new ConfigNotFoundError();
+    expect(error.code).toBe("CONFIG_NOT_FOUND");
+    expect(isUserError(error)).toBe(true);
+    expect(error.hints.some(h => h.command === "base44 create")).toBe(true);
+    expect(error.hints.some(h => h.command === "base44 link")).toBe(true);
+  });
+
+  it("ConfigInvalidError accepts custom message", () => {
+    const error = new ConfigInvalidError("Custom invalid config message");
+    expect(error.code).toBe("CONFIG_INVALID");
+    expect(error.message).toBe("Custom invalid config message");
+  });
+
+  it("ConfigExistsError accepts custom message", () => {
+    const error = new ConfigExistsError("Project already exists");
+    expect(error.code).toBe("CONFIG_EXISTS");
+    expect(error.message).toBe("Project already exists");
+  });
+
+  it("SchemaValidationError formats ZodError automatically", async () => {
+    const { z } = await import("zod");
+    const schema = z.object({ name: z.string() });
+    const result = schema.safeParse({ name: 123 });
+
+    if (!result.success) {
+      const error = new SchemaValidationError("Invalid config", result.error);
+      expect(error.code).toBe("SCHEMA_INVALID");
+      expect(error.message).toContain("Invalid config");
+      // Zod prettifyError uses lowercase
+      expect(error.message).toContain("expected string");
+      expect(error.message).toContain("name");
+    } else {
+      throw new Error("Expected parse to fail");
+    }
+  });
+
+  it("InvalidInputError has no default hints", () => {
+    const error = new InvalidInputError("Bad input");
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error.hints).toEqual([]);
+  });
+});
+
+describe("SystemError subclasses", () => {
+  it("ApiError provides default hints based on status code", () => {
+    const error401 = new ApiError("Unauthorized", { statusCode: 401 });
+    expect(error401.hints.some(h => h.command === "base44 login")).toBe(true);
+
+    const error403 = new ApiError("Forbidden", { statusCode: 403 });
+    expect(error403.hints.some(h => h.message.includes("permission"))).toBe(true);
+
+    const error404 = new ApiError("Not found", { statusCode: 404 });
+    expect(error404.hints.some(h => h.message.includes("not found"))).toBe(true);
+
+    const error500 = new ApiError("Server error", { statusCode: 500 });
+    expect(error500.hints.some(h => h.message.includes("network"))).toBe(true);
+  });
+
+  it("FileNotFoundError has correct defaults", () => {
+    const error = new FileNotFoundError("File not found: /path/to/file");
+    expect(error.code).toBe("FILE_NOT_FOUND");
+    expect(isSystemError(error)).toBe(true);
+  });
+
+  it("FileReadError has correct defaults", () => {
+    const error = new FileReadError("Cannot read file");
+    expect(error.code).toBe("FILE_READ_ERROR");
+    expect(isSystemError(error)).toBe(true);
+  });
+
+  it("InternalError has correct defaults", () => {
+    const error = new InternalError("Unexpected error");
+    expect(error.code).toBe("INTERNAL_ERROR");
+    expect(isSystemError(error)).toBe(true);
+  });
+});
+
+describe("Type guards", () => {
+  it("isCLIError identifies CLIError instances", () => {
+    expect(isCLIError(new AuthRequiredError())).toBe(true);
+    expect(isCLIError(new ApiError("test"))).toBe(true);
+    expect(isCLIError(new Error("regular error"))).toBe(false);
+    expect(isCLIError("not an error")).toBe(false);
+  });
+
+  it("isUserError identifies UserError instances", () => {
+    expect(isUserError(new AuthRequiredError())).toBe(true);
+    expect(isUserError(new ConfigNotFoundError())).toBe(true);
+    expect(isUserError(new ApiError("test"))).toBe(false);
+    expect(isUserError(new Error("regular error"))).toBe(false);
+  });
+
+  it("isSystemError identifies SystemError instances", () => {
+    expect(isSystemError(new ApiError("test"))).toBe(true);
+    expect(isSystemError(new FileNotFoundError("test"))).toBe(true);
+    expect(isSystemError(new AuthRequiredError())).toBe(false);
+    expect(isSystemError(new Error("regular error"))).toBe(false);
+  });
+});
 
 describe("formatApiError", () => {
   it("returns message when present", () => {