@geekmidas/cli 0.45.0 → 0.47.0

package/src/workspace/types.ts

@@ -11,23 +11,78 @@ import type {
 
 /**
  * Deploy target for an app.
- * Currently only 'dokploy' is supported.
- * Future: 'vercel' | 'cloudflare'
+ *
+ * Specifies where the app will be deployed.
+ *
+ * @example
+ * ```ts
+ * // Currently supported
+ * deploy: 'dokploy'
+ *
+ * // Future support (not yet implemented)
+ * deploy: 'vercel'
+ * deploy: 'cloudflare'
+ * ```
  */
 export type DeployTarget = 'dokploy' | 'vercel' | 'cloudflare';
 
 /**
  * Backend framework types for apps that don't use gkm routes.
+ *
+ * Used with `entry` to specify the framework for proper Docker builds.
+ *
+ * @example
+ * ```ts
+ * // Better Auth server
+ * {
+ *   entry: './src/index.ts',
+ *   framework: 'better-auth',
+ *   port: 3001,
+ * }
+ *
+ * // Hono app without gkm routes
+ * {
+ *   entry: './src/server.ts',
+ *   framework: 'hono',
+ *   port: 3000,
+ * }
+ * ```
  */
 export type BackendFramework = 'hono' | 'better-auth' | 'express' | 'fastify';
 
 /**
  * Frontend framework types.
+ *
+ * @example
+ * ```ts
+ * // Next.js app
+ * {
+ *   type: 'frontend',
+ *   framework: 'nextjs',
+ *   port: 3000,
+ * }
+ *
+ * // Vite SPA
+ * {
+ *   type: 'frontend',
+ *   framework: 'vite',
+ *   port: 5173,
+ * }
+ * ```
  */
 export type FrontendFramework = 'nextjs' | 'remix' | 'vite';
 
 /**
  * Service image configuration for custom Docker images.
+ *
+ * @example
+ * ```ts
+ * // Use specific version
+ * db: { version: '16-alpine' }
+ *
+ * // Use custom image
+ * db: { image: 'timescale/timescaledb:latest-pg16' }
+ * ```
  */
 export interface ServiceImageConfig {
 	/** Docker image version/tag (e.g., '18-alpine') */
@@ -38,6 +93,23 @@ export interface ServiceImageConfig {
 
 /**
  * Mail service configuration.
+ *
+ * In development, uses Mailpit for email testing.
+ * In production, uses SMTP configuration.
+ *
+ * @example
+ * ```ts
+ * services: {
+ *   mail: {
+ *     smtp: {
+ *       host: 'smtp.sendgrid.net',
+ *       port: 587,
+ *       user: 'apikey',
+ *       pass: process.env.SENDGRID_API_KEY,
+ *     }
+ *   }
+ * }
+ * ```
  */
 export interface MailServiceConfig extends ServiceImageConfig {
 	/** SMTP configuration for production */
@@ -51,6 +123,36 @@ export interface MailServiceConfig extends ServiceImageConfig {
 
 /**
  * Development services configuration.
+ *
+ * Configures shared infrastructure services like databases and caches.
+ * These are automatically provisioned in Dokploy during deployment.
+ *
+ * @example
+ * ```ts
+ * // Enable with defaults
+ * services: {
+ *   db: true,      // postgres:18-alpine
+ *   cache: true,   // redis:8-alpine
+ * }
+ *
+ * // Custom versions
+ * services: {
+ *   db: { version: '16-alpine' },
+ *   cache: { version: '7-alpine' },
+ * }
+ *
+ * // Custom images
+ * services: {
+ *   db: { image: 'timescale/timescaledb:latest-pg16' },
+ * }
+ *
+ * // With mail service
+ * services: {
+ *   db: true,
+ *   cache: true,
+ *   mail: true,  // Mailpit in dev
+ * }
+ * ```
  */
 export interface ServicesConfig {
 	/** PostgreSQL database (default: postgres:18-alpine) */
@@ -63,57 +165,201 @@ export interface ServicesConfig {
 
 /**
  * Stage-based domain configuration.
- * Maps deployment stages to base domains.
- * @example { development: 'dev.myapp.com', production: 'myapp.com' }
+ *
+ * Maps deployment stages to base domains. The main frontend app
+ * gets the base domain, other apps get `{appName}.{baseDomain}`.
+ *
+ * @example
+ * ```ts
+ * domains: {
+ *   development: 'dev.myapp.com',
+ *   staging: 'staging.myapp.com',
+ *   production: 'myapp.com',
+ * }
+ *
+ * // Result for production stage:
+ * // - web (main frontend): myapp.com
+ * // - api: api.myapp.com
+ * // - auth: auth.myapp.com
+ * ```
  */
 export type DokployDomainsConfig = Record<string, string>;
 
 /**
  * Per-app domain override configuration.
- * Can be a single domain string or stage-specific domains.
- * @example 'api.custom.com' or { production: 'api.custom.com', staging: 'api.staging.com' }
+ *
+ * Can be a single domain string (used for all stages) or
+ * stage-specific domains.
+ *
+ * @example
+ * ```ts
+ * // Single domain for all stages
+ * domain: 'api.custom.com'
+ *
+ * // Stage-specific domains
+ * domain: {
+ *   development: 'api.dev.custom.com',
+ *   staging: 'api.staging.custom.com',
+ *   production: 'api.custom.com',
+ * }
+ * ```
  */
 export type AppDomainConfig = string | Record<string, string>;
 
 /**
  * Dokploy workspace deployment configuration.
+ *
+ * Configures how the workspace is deployed to a Dokploy server.
+ * One workspace maps to one Dokploy project with stage-based environments.
+ *
+ * @example
+ * ```ts
+ * deploy: {
+ *   default: 'dokploy',
+ *   dokploy: {
+ *     endpoint: 'https://dokploy.myserver.com',
+ *     projectId: 'proj_abc123',
+ *     registry: 'ghcr.io/myorg',
+ *     domains: {
+ *       development: 'dev.myapp.com',
+ *       production: 'myapp.com',
+ *     },
+ *   },
+ * }
+ * ```
  */
 export interface DokployWorkspaceConfig {
-	/** Dokploy API endpoint */
+	/** Dokploy API endpoint (e.g., 'https://dokploy.myserver.com') */
 	endpoint: string;
-	/** Project ID (1 workspace = 1 project) */
+	/** Project ID in Dokploy (auto-created on first deploy) */
 	projectId: string;
-	/** Container registry for images */
+	/** Container registry for Docker images (e.g., 'ghcr.io/myorg') */
 	registry?: string;
-	/** Registry ID in Dokploy */
+	/** Registry ID in Dokploy (auto-configured) */
 	registryId?: string;
 	/**
 	 * Stage-based domain configuration.
 	 * The main frontend app gets the base domain.
 	 * Other apps get {appName}.{baseDomain} by default.
-	 * @example { development: 'dev.myapp.com', production: 'myapp.com' }
 	 */
 	domains?: DokployDomainsConfig;
 }
 
+/**
+ * DNS provider types for automatic DNS record creation.
+ */
+export type DnsProvider = 'hostinger' | 'cloudflare' | 'manual';
+
+/**
+ * DNS configuration for automatic record creation during deployment.
+ *
+ * When configured, the deploy command will automatically create DNS
+ * A records pointing to your Dokploy server for each app's domain.
+ *
+ * @example
+ * ```ts
+ * // Auto-create DNS records at Hostinger
+ * dns: {
+ *   provider: 'hostinger',
+ *   domain: 'traflabs.io',
+ *   autoCreate: true,
+ * }
+ *
+ * // Manual mode - just print required records
+ * dns: {
+ *   provider: 'manual',
+ *   domain: 'traflabs.io',
+ * }
+ * ```
+ */
+export interface DnsConfig {
+	/**
+	 * DNS provider for automatic record creation.
+	 * - 'hostinger': Use Hostinger DNS API
+	 * - 'cloudflare': Use Cloudflare DNS API (future)
+	 * - 'manual': Don't create records, just print required records
+	 */
+	provider: DnsProvider;
+
+	/**
+	 * Root domain where records will be created.
+	 * @example 'traflabs.io', 'example.com'
+	 */
+	domain: string;
+
+	/**
+	 * Automatically create DNS records during deploy.
+	 * If false, only prints required records for manual setup.
+	 * @default true
+	 */
+	autoCreate?: boolean;
+
+	/**
+	 * TTL for created DNS records in seconds.
+	 * @default 300 (5 minutes)
+	 */
+	ttl?: number;
+}
+
 /**
  * Deployment configuration for the workspace.
+ *
+ * @example
+ * ```ts
+ * // Minimal - just set default target
+ * deploy: {
+ *   default: 'dokploy',
+ * }
+ *
+ * // Full configuration with DNS
+ * deploy: {
+ *   default: 'dokploy',
+ *   dokploy: {
+ *     endpoint: 'https://dokploy.myserver.com',
+ *     projectId: 'proj_abc123',
+ *     registry: 'ghcr.io/myorg',
+ *     domains: {
+ *       production: 'myapp.com',
+ *     },
+ *   },
+ *   dns: {
+ *     provider: 'hostinger',
+ *     domain: 'myapp.com',
+ *     autoCreate: true,
+ *   },
+ * }
+ * ```
  */
 export interface DeployConfig {
-	/** Default deploy target for all apps */
+	/** Default deploy target for all apps (default: 'dokploy') */
 	default?: DeployTarget;
 	/** Dokploy-specific configuration */
 	dokploy?: DokployWorkspaceConfig;
+	/** DNS configuration for automatic record creation */
+	dns?: DnsConfig;
 }
 
 /**
  * Models package configuration for shared schemas.
+ *
+ * Configures a shared models package containing Zod schemas
+ * that can be used across backend and frontend apps.
+ *
+ * @example
+ * ```ts
+ * shared: {
+ *   models: {
+ *     path: 'packages/models',
+ *     schema: 'zod',
+ *   },
+ * }
+ * ```
  */
 export interface ModelsConfig {
-	/** Path to models package (default: packages/models) */
+	/** Path to models package relative to workspace root (default: 'packages/models') */
 	path?: string;
 	/**
-	 * Schema library to use.
+	 * Schema library to use (default: 'zod').
 	 * Currently only 'zod' is supported.
 	 * Future: any StandardSchema-compatible library
 	 */
@@ -122,6 +368,20 @@ export interface ModelsConfig {
 
 /**
  * Shared packages configuration.
+ *
+ * Configures shared packages in the monorepo that are
+ * used by multiple apps.
+ *
+ * @example
+ * ```ts
+ * shared: {
+ *   packages: ['packages/*', 'libs/*'],
+ *   models: {
+ *     path: 'packages/models',
+ *     schema: 'zod',
+ *   },
+ * }
+ * ```
  */
 export interface SharedConfig {
 	/** Glob patterns for shared packages (default: ['packages/*']) */
@@ -132,18 +392,46 @@ export interface SharedConfig {
 
 /**
  * Secrets encryption configuration.
+ *
+ * Configures how secrets are encrypted for deployment.
+ * Secrets are stored encrypted in `.gkm/secrets/{stage}.json`
+ * with keys stored separately in `~/.gkm/{project}/{stage}.key`.
+ *
+ * @example
+ * ```ts
+ * secrets: {
+ *   enabled: true,
+ *   algorithm: 'aes-256-gcm',
+ *   kdf: 'scrypt',
+ * }
+ * ```
  */
 export interface SecretsConfig {
-	/** Enable encrypted secrets */
+	/** Enable encrypted secrets (default: true) */
 	enabled?: boolean;
-	/** Encryption algorithm (default: aes-256-gcm) */
+	/** Encryption algorithm (default: 'aes-256-gcm') */
 	algorithm?: string;
-	/** Key derivation function (default: scrypt) */
+	/** Key derivation function (default: 'scrypt') */
 	kdf?: 'scrypt' | 'pbkdf2';
 }
 
 /**
  * Client generation configuration for frontend apps.
+ *
+ * Configures automatic API client generation from OpenAPI specs.
+ *
+ * @example
+ * ```ts
+ * // In a frontend app config
+ * {
+ *   type: 'frontend',
+ *   framework: 'nextjs',
+ *   dependencies: ['api'],
+ *   client: {
+ *     output: './src/lib/api',
+ *   },
+ * }
+ * ```
  */
 export interface ClientConfig {
 	/** Output directory for generated client (relative to app path) */
@@ -152,81 +440,242 @@ export interface ClientConfig {
 
 /**
  * Base app configuration properties (shared between input and normalized).
+ *
+ * @example
+ * ```ts
+ * // Backend app with gkm routes
+ * api: {
+ *   type: 'backend',
+ *   path: 'apps/api',
+ *   port: 3000,
+ *   routes: './src/endpoints/**\/*.ts',
+ *   envParser: './src/config/env',
+ *   logger: './src/config/logger',
+ * }
+ *
+ * // Backend app with entry point (e.g., Better Auth)
+ * auth: {
+ *   type: 'backend',
+ *   path: 'apps/auth',
+ *   port: 3001,
+ *   entry: './src/index.ts',
+ *   framework: 'better-auth',
+ *   requiredEnv: ['DATABASE_URL', 'BETTER_AUTH_SECRET'],
+ * }
+ *
+ * // Frontend app
+ * web: {
+ *   type: 'frontend',
+ *   path: 'apps/web',
+ *   port: 3002,
+ *   framework: 'nextjs',
+ *   dependencies: ['api', 'auth'],
+ * }
+ * ```
  */
 interface AppConfigBase {
-	/** App type (default: 'backend') */
+	/**
+	 * App type.
+	 * - 'backend': Server-side app (API, auth service, etc.)
+	 * - 'frontend': Client-side app (Next.js, Vite, etc.)
+	 * @default 'backend'
+	 */
 	type?: 'backend' | 'frontend';
 
-	/** Path relative to workspace root */
+	/**
+	 * Path to the app relative to workspace root.
+	 * @example 'apps/api', 'apps/web', 'services/auth'
+	 */
 	path: string;
 
-	/** Dev server port */
+	/**
+	 * Development server port.
+	 * Must be unique across all apps in the workspace.
+	 * @example 3000, 3001, 3002
+	 */
 	port: number;
 
-	/** Per-app deploy target override */
+	/**
+	 * Per-app deploy target override.
+	 * Overrides `deploy.default` for this specific app.
+	 * @example 'dokploy', 'vercel'
+	 */
 	deploy?: DeployTarget;
 
-	// Backend-specific (from GkmConfig)
-	/** Routes glob pattern */
+	// ─────────────────────────────────────────────────────────────────
+	// Backend-specific (gkm routes mode)
+	// ─────────────────────────────────────────────────────────────────
+
+	/**
+	 * Routes glob pattern for gkm endpoints.
+	 * @example './src/endpoints/**\/*.ts'
+	 */
 	routes?: Routes;
-	/** Functions glob pattern */
+
+	/**
+	 * Functions glob pattern for Lambda functions.
+	 * @example './src/functions/**\/*.ts'
+	 */
 	functions?: Routes;
-	/** Crons glob pattern */
+
+	/**
+	 * Crons glob pattern for scheduled tasks.
+	 * @example './src/crons/**\/*.ts'
+	 */
 	crons?: Routes;
-	/** Subscribers glob pattern */
+
+	/**
+	 * Subscribers glob pattern for event handlers.
+	 * @example './src/subscribers/**\/*.ts'
+	 */
 	subscribers?: Routes;
-	/** Path to environment parser module */
+
+	/**
+	 * Path to environment parser module.
+	 * @example './src/config/env'
+	 */
 	envParser?: string;
-	/** Path to logger module */
+
+	/**
+	 * Path to logger module.
+	 * @example './src/config/logger'
+	 */
 	logger?: string;
-	/** Provider configuration */
+
+	/** Provider configuration (AWS, Docker, etc.) */
 	providers?: ProvidersConfig;
-	/** Server lifecycle hooks */
+
+	/**
+	 * Server lifecycle hooks.
+	 * @example { beforeSetup: './src/hooks/setup.ts' }
+	 */
 	hooks?: HooksConfig;
-	/** Telescope configuration */
+
+	/**
+	 * Telescope debugging dashboard configuration.
+	 * @example true, './src/config/telescope', { enabled: true, path: '/__telescope' }
+	 */
 	telescope?: string | boolean | TelescopeConfig;
-	/** Studio configuration */
+
+	/**
+	 * Studio admin panel configuration.
+	 * @example true, './src/config/studio'
+	 */
 	studio?: string | boolean | StudioConfig;
-	/** OpenAPI configuration */
+
+	/**
+	 * OpenAPI documentation configuration.
+	 * @example true, { output: './src/openapi.ts' }
+	 */
 	openapi?: boolean | OpenApiConfig;
-	/** Runtime (node or bun) */
+
+	/**
+	 * Runtime environment.
+	 * @default 'node'
+	 */
 	runtime?: Runtime;
-	/** Environment file(s) to load */
+
+	/**
+	 * Environment file(s) to load during development.
+	 * @example '.env', ['.env', '.env.local']
+	 */
 	env?: string | string[];
 
-	// Entry point for non-gkm apps
+	// ─────────────────────────────────────────────────────────────────
+	// Entry point mode (non-gkm apps)
+	// ─────────────────────────────────────────────────────────────────
+
 	/**
 	 * Entry file path for apps that don't use gkm routes.
-	 * Used by both `gkm dev` (runs with tsx) and Docker builds (bundles with tsdown).
-	 * @example './src/index.ts'
+	 *
+	 * When specified, the app is run directly with tsx in development
+	 * and bundled with esbuild for production Docker builds.
+	 *
+	 * Use this for:
+	 * - Better Auth servers
+	 * - Custom Hono/Express apps
+	 * - Any backend that doesn't use gkm's endpoint builder
+	 *
+	 * @example './src/index.ts', './src/server.ts'
 	 */
 	entry?: string;
 
+	// ─────────────────────────────────────────────────────────────────
 	// Frontend-specific
-	/** Framework for the app (frontend or backend without gkm routes) */
+	// ─────────────────────────────────────────────────────────────────
+
+	/**
+	 * Framework for the app.
+	 *
+	 * Backend frameworks: 'hono', 'better-auth', 'express', 'fastify'
+	 * Frontend frameworks: 'nextjs', 'remix', 'vite'
+	 *
+	 * @example 'nextjs', 'better-auth', 'hono'
+	 */
 	framework?: BackendFramework | FrontendFramework;
-	/** Client generation configuration */
+
+	/**
+	 * Client generation configuration.
+	 * Generates typed API client from backend dependencies.
+	 */
 	client?: ClientConfig;
 
+	// ─────────────────────────────────────────────────────────────────
 	// Deployment
+	// ─────────────────────────────────────────────────────────────────
+
 	/**
-	 * Override domain for this app (per-stage or single value).
-	 * @example 'api.custom.com' or { production: 'api.custom.com', staging: 'api.staging.com' }
+	 * Override domain for this app.
+	 *
+	 * By default, apps get `{appName}.{baseDomain}` (or just `{baseDomain}`
+	 * for the main frontend). Use this to specify a custom domain.
+	 *
+	 * @example
+	 * ```ts
+	 * // Single domain for all stages
+	 * domain: 'api.custom.com'
+	 *
+	 * // Stage-specific domains
+	 * domain: {
+	 *   production: 'api.custom.com',
+	 *   staging: 'api.staging.custom.com',
+	 * }
+	 * ```
 	 */
 	domain?: AppDomainConfig;
 
 	/**
 	 * Required environment variables for entry-based apps.
+	 *
 	 * Use this instead of envParser for apps that don't use gkm routes.
-	 * The deploy command uses this to filter which secrets to embed.
-	 * @example ['DATABASE_URL', 'BETTER_AUTH_SECRET']
+	 * The deploy command uses this list to filter which secrets to embed
+	 * in the Docker image.
+	 *
+	 * @example ['DATABASE_URL', 'BETTER_AUTH_SECRET', 'REDIS_URL']
 	 */
 	requiredEnv?: string[];
 }
 
 /**
  * App configuration input with type-safe dependencies.
- * @template TAppNames - Union of valid app names in the workspace
+ *
+ * @template TAppNames - Union of valid app names in the workspace (auto-inferred)
+ *
+ * @example
+ * ```ts
+ * // Dependencies are type-checked against app names
+ * apps: {
+ *   api: { path: 'apps/api', port: 3000 },
+ *   auth: { path: 'apps/auth', port: 3001 },
+ *   web: {
+ *     path: 'apps/web',
+ *     port: 3002,
+ *     type: 'frontend',
+ *     dependencies: ['api', 'auth'],  // ✓ Valid
+ *     // dependencies: ['invalid'],   // ✗ Type error
+ *   },
+ * }
+ * ```
  */
 export interface AppConfigInput<TAppNames extends string = string>
 	extends AppConfigBase {
@@ -267,13 +716,49 @@ export type ConstrainedApps<TApps extends AppsRecord> = {
 
 /**
  * Full workspace input type with constrained dependencies.
+ *
+ * @example
+ * ```ts
+ * import { defineWorkspace } from '@geekmidas/cli';
+ *
+ * export default defineWorkspace({
+ *   name: 'my-app',
+ *   apps: {
+ *     api: {
+ *       path: 'apps/api',
+ *       port: 3000,
+ *       routes: './src/endpoints/**\/*.ts',
+ *     },
+ *     web: {
+ *       type: 'frontend',
+ *       path: 'apps/web',
+ *       port: 3001,
+ *       framework: 'nextjs',
+ *       dependencies: ['api'],
+ *     },
+ *   },
+ *   services: {
+ *     db: true,
+ *     cache: true,
+ *   },
+ *   deploy: {
+ *     default: 'dokploy',
+ *   },
+ * });
+ * ```
  */
 export type WorkspaceInput<TApps extends AppsRecord> = {
+	/** Workspace name (defaults to root package.json name) */
 	name?: string;
+	/** App definitions */
 	apps: ConstrainedApps<TApps>;
+	/** Shared packages configuration */
 	shared?: SharedConfig;
+	/** Deployment configuration */
 	deploy?: DeployConfig;
+	/** Development services (db, cache, mail) */
 	services?: ServicesConfig;
+	/** Encrypted secrets configuration */
 	secrets?: SecretsConfig;
 };
 
@@ -315,8 +800,79 @@ export type WorkspaceConfigInput<
 > = WorkspaceInput<T['apps']>;
 
 /**
- * Workspace configuration for multi-app monorepos (legacy).
- * @deprecated Use WorkspaceConfigInput with defineWorkspace for type inference
+ * Workspace configuration for multi-app monorepos.
+ *
+ * Use `defineWorkspace()` helper for type-safe configuration with
+ * auto-completion and dependency validation.
+ *
+ * @example
+ * ```ts
+ * // gkm.config.ts
+ * import { defineWorkspace } from '@geekmidas/cli';
+ *
+ * export default defineWorkspace({
+ *   name: 'my-saas',
+ *
+ *   // App definitions
+ *   apps: {
+ *     // Backend API with gkm routes
+ *     api: {
+ *       path: 'apps/api',
+ *       port: 3000,
+ *       routes: './src/endpoints/**\/*.ts',
+ *       envParser: './src/config/env',
+ *       logger: './src/config/logger',
+ *       telescope: true,
+ *     },
+ *
+ *     // Better Auth service
+ *     auth: {
+ *       path: 'apps/auth',
+ *       port: 3001,
+ *       entry: './src/index.ts',
+ *       framework: 'better-auth',
+ *       requiredEnv: ['DATABASE_URL', 'BETTER_AUTH_SECRET'],
+ *     },
+ *
+ *     // Next.js frontend
+ *     web: {
+ *       type: 'frontend',
+ *       path: 'apps/web',
+ *       port: 3002,
+ *       framework: 'nextjs',
+ *       dependencies: ['api', 'auth'],
+ *     },
+ *   },
+ *
+ *   // Infrastructure services
+ *   services: {
+ *     db: true,      // PostgreSQL
+ *     cache: true,   // Redis
+ *   },
+ *
+ *   // Deployment configuration
+ *   deploy: {
+ *     default: 'dokploy',
+ *     dokploy: {
+ *       endpoint: 'https://dokploy.myserver.com',
+ *       projectId: 'proj_abc123',
+ *       registry: 'ghcr.io/myorg',
+ *       domains: {
+ *         production: 'myapp.com',
+ *         staging: 'staging.myapp.com',
+ *       },
+ *     },
+ *   },
+ *
+ *   // Shared packages
+ *   shared: {
+ *     packages: ['packages/*'],
+ *     models: { path: 'packages/models' },
+ *   },
+ * });
+ * ```
+ *
+ * @deprecated Use WorkspaceInput with defineWorkspace for type inference
  */
 export interface WorkspaceConfig {
 	/** Workspace name (defaults to root package.json name) */
@@ -340,11 +896,18 @@ export interface WorkspaceConfig {
 
 /**
  * Normalized app configuration with resolved defaults.
+ *
+ * This is the internal representation after processing user input.
+ * All optional fields have been resolved to their defaults.
  */
 export interface NormalizedAppConfig extends Omit<AppConfigBase, 'type'> {
+	/** App type (always defined after normalization) */
 	type: 'backend' | 'frontend';
+	/** Path to the app */
 	path: string;
+	/** Development server port */
 	port: number;
+	/** Resolved dependencies array (empty array if none) */
 	dependencies: string[];
 	/** Resolved deploy target (app.deploy > deploy.default > 'dokploy') */
 	resolvedDeployTarget: DeployTarget;
@@ -360,14 +923,24 @@ export interface NormalizedAppConfig extends Omit<AppConfigBase, 'type'> {
 
 /**
  * Normalized workspace configuration with resolved defaults.
+ *
+ * This is the internal representation after processing user input.
+ * All optional fields have been resolved to their defaults.
  */
 export interface NormalizedWorkspace {
+	/** Workspace name (resolved from package.json if not specified) */
 	name: string;
+	/** Absolute path to workspace root */
 	root: string;
+	/** Normalized app configurations */
 	apps: Record<string, NormalizedAppConfig>;
+	/** Services configuration (empty object if not specified) */
 	services: ServicesConfig;
+	/** Deploy configuration (empty object if not specified) */
 	deploy: DeployConfig;
+	/** Shared packages configuration (empty object if not specified) */
 	shared: SharedConfig;
+	/** Secrets configuration (empty object if not specified) */
 	secrets: SecretsConfig;
 }
 
@@ -385,6 +958,15 @@ export interface LoadedConfig {
 
 /**
  * Type guard to check if a config is a WorkspaceConfig.
+ *
+ * @example
+ * ```ts
+ * const config = await loadConfig();
+ * if (isWorkspaceConfig(config)) {
+ *   // config.apps is available
+ *   console.log(Object.keys(config.apps));
+ * }
+ * ```
  */
 export function isWorkspaceConfig(
 	config: GkmConfig | WorkspaceConfig,