@ketrics/ketrics-cli 0.2.3 → 0.4.0

package/README.md

@@ -1,746 +1,762 @@
 # Ketrics CLI
 
-Command-line interface for scaffolding, building, and deploying applications to the Ketrics platform.
+A command-line tool for creating, building, validating, and deploying applications to the Ketrics serverless platform.
 
-## 1. Overview
+## Overview
 
-### Purpose
-
-The Ketrics CLI (`@ketrics/ketrics-cli`) is a developer tool that streamlines the full lifecycle of Ketrics tenant applications—from project scaffolding to production deployment. It abstracts the complexity of packaging frontend and backend code into deployment bundles and handles authentication with the Ketrics Tenant API API.
-
-### Architecture Position
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                     Developer Workstation                        │
-│  ┌─────────────┐     ┌────────────────┐     ┌────────────────┐  │
-│  │ Application │────▶│  Ketrics CLI   │────▶│ Tenant API  │  │
-│  │   Source    │     │ (build & zip)  │     │     API        │  │
-│  └─────────────┘     └────────────────┘     └────────────────┘  │
-└──────────────────────────────────────────────────────────────────┘
-                                │
-                                │ Presigned URL
-                                ▼
-                         ┌──────────────┐
-                         │     S3       │
-                         │ (code-bundle)│
-                         └──────────────┘
-                                │
-                                │ S3 Event Trigger
-                                ▼
-                         ┌──────────────┐     ┌──────────────┐
-                         │  Deployment  │────▶│     EFS      │
-                         │   Lambda     │     │  (extracted) │
-                         └──────────────┘     └──────────────┘
-                                                     │
-                                                     ▼
-                                              ┌──────────────┐
-                                              │  Data Plane  │
-                                              │   (runtime)  │
-                                              └──────────────┘
-```
-
-The CLI sits at the beginning of the deployment pipeline:
-
-1. Developers write frontend (React) and backend (TypeScript handlers) code
-2. CLI builds both, packages them into a single ZIP archive
-3. CLI uploads the ZIP to S3 via a presigned URL obtained from Tenant API API
-4. Downstream systems (Deployment Lambda) extract the bundle to EFS for Data Plane execution
+The Ketrics CLI (`@ketrics/ketrics-cli`) is a TypeScript-based command-line interface that enables developers to manage their Ketrics applications across the complete application lifecycle. It fits into the Ketrics platform ecosystem as the primary interface for local development and deployment workflows.
 
 ### Key Responsibilities
 
-- **Project scaffolding**: Generate new applications from bundled templates
-- **Configuration validation**: Validate `ketrics.config.json` and `.env` files using Zod schemas
-- **Build orchestration**: Execute `npm run build` for both frontend and backend
-- **Deployment packaging**: Create ZIP archives with frontend/backend in a flat structure
-- **API communication**: Authenticate with Tenant API and obtain presigned upload URLs
-- **S3 upload**: Push deployment bundles to the platform
-- **Runtime testing**: Execute API requests against deployed applications via `ketrics run`
-
-### Boundaries
-
-The CLI does **not**:
-
-- Execute application code (that's the Data Plane's role)
-- Manage infrastructure (handled by Terraform)
-- Handle tenant/user management (Tenant API API's domain)
-- Extract bundles to EFS (Deployment Lambda's responsibility)
-
----
-
-## 2. Business Logic
-
-### Problem Statement
-
-Developers building Ketrics applications need a consistent, reliable way to:
-
-1. Bootstrap new projects with correct structure and configuration
-2. Build and package both frontend and backend code
-3. Deploy code bundles to the platform with proper authentication
-4. Test deployed functions without building custom HTTP clients
-
-### Core Workflows
-
-#### Scaffold Workflow (`ketrics create`)
-
-```
-1. Validate app name (alphanumeric, starts with letter)
-2. Check destination directory doesn't exist
-3. List available templates from bundled /templates directory
-4. Interactive template selection (or use --template flag)
-5. Copy template files to new directory
-6. Update app name in ketrics.config.json, frontend/package.json, backend/package.json
-```
-
-#### Build Workflow (`ketrics build`)
-
-```
-1. Validate frontend/ directory exists with node_modules
-2. Validate backend/ directory exists with node_modules
-3. Run `npm run build` in frontend/ (expects dist/ output)
-4. Run `npm run build` in backend/ (expects dist/ output)
-5. Verify both dist/ directories were created
-```
-
-#### Deploy Workflow (`ketrics deploy`)
-
-```
-1. Load .env file and validate required KETRICS_* variables
-2. Validate deployment token format (must start with "ktd_")
-3. Execute full build workflow (frontend + backend)
-4. Create ZIP archive:
-   - frontend/ folder containing frontend/dist/* contents
-   - backend/ folder containing backend/dist/* contents
-5. Call Tenant API API: POST /tenants/{tenantId}/applications/{appId}/deploy
-6. Receive presigned S3 URL with deploymentId
-7. PUT ZIP buffer to presigned URL
-8. Display success with deploymentId, file count, size, duration
-```
-
-#### Validate Workflow (`ketrics validate`)
-
-```
-1. Check ketrics.config.json exists and is valid JSON
-2. Validate against ketricsConfigSchema (Zod)
-3. Check .env file exists
-4. Validate KETRICS_* variables against envConfigSchema
-5. Report errors and warnings (e.g., token format, empty exclude patterns)
-```
-
-#### Run Workflow (`ketrics run <json-file>`)
-
-```
-1. Load .env file (requires KETRICS_AUTH_TOKEN and KETRICS_RUNTIME_URL)
-2. Parse JSON file against runFileSchema
-3. Interpolate template variables: {{tenantId}}, {{applicationId}}, {{token}}
-4. Construct full URL: KETRICS_RUNTIME_URL + interpolated endpoint
-5. Execute HTTP request (GET/POST/PUT/DELETE/PATCH)
-6. Display formatted response with status and body
-```
-
-### Business Rules
-
-| Rule                                       | Implementation                                  |
-| ------------------------------------------ | ----------------------------------------------- |
-| App names must be valid identifiers        | Regex: `^[a-zA-Z][a-zA-Z0-9_-]*$`               |
-| Deployment tokens must have correct prefix | Token must start with `ktd_`                    |
-| Tenant/Application IDs must be UUIDs       | Zod `.uuid()` validation                        |
-| API URL must be valid HTTPS URL            | Zod `.url()` validation                         |
-| Both frontend and backend must build       | Both `dist/` directories must exist after build |
-| Templates must have ketrics.config.json    | Templates without config are skipped            |
-
-### Input/Output Expectations
-
-**Deploy Input:**
-
-- `.env` file with `KETRICS_TOKEN`, `KETRICS_API_URL`, `KETRICS_TENANT_ID`, `KETRICS_APPLICATION_ID`
-- `frontend/` directory with `package.json` and `node_modules`
-- `backend/` directory with `package.json` and `node_modules`
-
-**Deploy Output:**
-
-- ZIP file uploaded to S3 with structure:
-  ```
-  bundle.zip
-  ├── frontend/
-  │   ├── index.html
-  │   └── assets/
-  │       ├── index-*.js
-  │       └── index-*.css
-  └── backend/
-      ├── index.js
-      └── index.d.ts
-  ```
-
-### Edge Cases Handled
+- **Application Creation**: Bootstrap new projects from predefined templates
+- **Build Orchestration**: Compile frontend and backend applications before deployment
+- **Configuration Management**: Load and validate project configuration and environment variables
+- **Package Bundling**: Create optimized ZIP archives with proper file structure and compression
+- **Deployment Automation**: Coordinate the deploy process including API communication and S3 uploads
+- **Configuration Validation**: Verify configuration files and environment setup before operations
+- **Request Execution**: Execute HTTP API requests with variable interpolation and templating
 
-- **Destination folder exists**: `ketrics create` fails early with clear error
-- **node_modules missing**: Build command detects and prompts user to run `npm install`
-- **Empty dist directories**: Error thrown if no files found after build
-- **Network failures**: Axios timeout (30s API, 5min upload) with specific error messages
-- **Expired presigned URL**: Clear error message on 403/400 from S3
-- **Invalid JSON in config files**: Parse errors with file path and position
+### Architecture Boundaries
 
----
+This component operates as a standalone CLI tool that:
+- Does NOT handle cloud infrastructure provisioning (delegated to Ketrics backend)
+- Does NOT manage authentication beyond token validation (relies on KETRICS_TOKEN format)
+- Does NOT execute or monitor running applications (delegated to Ketrics platform)
+- Focuses exclusively on local operations and integration with Ketrics deployment APIs
 
-## 3. Technical Details
-
-### Technology Stack
-
-| Component             | Technology        | Version  |
-| --------------------- | ----------------- | -------- |
-| Runtime               | Node.js           | >=24.0.0 |
-| Language              | TypeScript        | ^5.3.3   |
-| CLI Framework         | Commander.js      | ^12.0.0  |
-| HTTP Client           | Axios             | ^1.6.0   |
-| Schema Validation     | Zod               | ^3.22.4  |
-| ZIP Creation          | Archiver          | ^6.0.1   |
-| File Patterns         | glob              | ^10.3.0  |
-| Interactive Prompts   | @inquirer/prompts | ^7.10.1  |
-| Console Styling       | Chalk             | ^4.1.2   |
-| Loading Spinners      | ora               | ^5.4.1   |
-| Environment Variables | dotenv            | ^16.3.1  |
-
-### File Structure
+### Project Structure
 
 ```
 ketrics-cli/
 ├── bin/
-│   └── ketrics.ts              # CLI entry point (shebang executable)
+│   └── ketrics.ts              # CLI entry point
 ├── src/
-│   ├── cli.ts                  # Commander program setup, command registration
-│   ├── index.ts                # Programmatic exports for library usage
+│   ├── cli.ts                  # Commander.js setup and command definitions
+│   ├── index.ts                # Public API exports
+│   ├── version.ts              # Auto-generated version
+│   ├── types/
+│   │   └── index.ts            # Zod schemas and TypeScript interfaces
 │   ├── commands/
-│   │   ├── create.ts           # ketrics create - project scaffolding
-│   │   ├── build.ts            # ketrics build - compile without deploy
-│   │   ├── deploy.ts           # ketrics deploy - build + package + upload
-│   │   ├── validate.ts         # ketrics validate - config validation
-│   │   └── run.ts              # ketrics run - execute API requests
+│   │   ├── create.ts           # Bootstrap new project from template
+│   │   ├── build.ts            # Build frontend/backend
+│   │   ├── deploy.ts           # Deploy application
+│   │   ├── validate.ts         # Validate configuration
+│   │   └── run.ts              # Execute API requests
 │   ├── services/
-│   │   ├── api-client.ts       # HTTP client for Tenant API API
-│   │   ├── build-service.ts    # npm build execution and validation
 │   │   ├── config-service.ts   # Load/validate ketrics.config.json and .env
-│   │   ├── template-service.ts # Template discovery, copying, name updates
-│   │   ├── upload-service.ts   # S3 presigned URL upload
-│   │   └── zip-service.ts      # ZIP archive creation from dist directories
-│   ├── types/
-│   │   └── index.ts            # Zod schemas and TypeScript interfaces
+│   │   ├── build-service.ts    # Orchestrate npm build for frontend/backend
+│   │   ├── api-client.ts       # HTTP communication with Ketrics API
+│   │   ├── zip-service.ts      # ZIP archive creation and compression
+│   │   ├── upload-service.ts   # S3 upload via presigned URLs
+│   │   └── template-service.ts # Template discovery and copying
 │   └── utils/
-│       ├── logger.ts           # Colored console output (chalk wrapper)
-│       └── spinner.ts          # Loading spinner wrapper (ora)
+│       ├── logger.ts           # Colored console output
+│       └── spinner.ts          # Loading indicators
 ├── templates/
-│   └── ketrics-app-v1/         # Bundled project template
-│       ├── ketrics.config.json
-│       ├── frontend/           # React + Vite starter
-│       ├── backend/            # TypeScript handlers starter
-│       └── tests/              # Sample run files for ketrics run
-├── package.json
-└── tsconfig.json
+│   └── HelloWorld/             # Example template for project scaffolding
+├── package.json                # NPM package configuration
+├── tsconfig.json               # TypeScript configuration
+└── dist/                       # Compiled JavaScript (generated)
 ```
 
-### Key Functions and Classes
-
-#### `src/cli.ts`
+## Business Logic
 
-```typescript
-export function createCLI(): Command;
-```
+### Problem Statement
 
-Creates the Commander program with all commands registered. Each command is defined with options, descriptions, and action handlers.
+Developers need a consistent way to:
+1. Create new Ketrics applications with proper structure
+2. Build applications locally before deployment
+3. Package and upload applications to Ketrics infrastructure
+4. Test API integrations without manual HTTP requests
+5. Validate configuration before attempting deployments
 
-#### `src/services/config-service.ts`
+### Core Workflows
 
-```typescript
-export function loadKetricsConfig(configPath?: string): KetricsConfig;
-```
+#### 1. Application Creation (`ketrics create`)
+
+**Inputs**: Application name, optional template name
+**Process**:
+1. Validate app name (alphanumeric, hyphens, underscores; must start with letter)
+2. Discover available templates from the `templates/` directory
+3. Prompt for template selection (interactive or via `--template` flag)
+4. Create application directory
+5. Copy template files recursively
+6. Update app name in `ketrics.config.json`, `frontend/package.json`, and `backend/package.json`
+
+**Outputs**: New project directory with template structure
+**Exit on Error**: Name validation failure, template not found, directory exists
+
+#### 2. Build Process (`ketrics build`)
+
+**Inputs**: Current working directory must contain `frontend/` and `backend/` subdirectories
+**Process**:
+1. Validate both directories exist with `node_modules` installed
+2. Execute `npm run build` in `frontend/` directory
+3. Validate `frontend/dist/` was created
+4. Execute `npm run build` in `backend/` directory
+5. Validate `backend/dist/` was created
+6. Report dist paths to user
+
+**Outputs**: Built artifacts in `frontend/dist/` and `backend/dist/`
+**Exit on Error**: Missing directories, missing node_modules, build failure, missing dist output
+
+#### 3. Deployment Process (`ketrics deploy`)
+
+**Inputs**: Working directory with built `frontend/dist/` and `backend/dist/`, `.env` with credentials
+**Process**:
+1. Load and validate environment configuration
+2. Validate token format (must start with `ktd_`)
+3. Build frontend and backend (calls buildAll)
+4. Collect files from both dist directories into a structured ZIP
+5. Create presigned S3 URL via Ketrics API (`POST /tenants/{id}/applications/{id}/deploy`)
+6. Upload ZIP buffer to S3 via presigned URL
+7. Return deployment ID and summary
+
+**Outputs**: Deployment confirmation with ID, file count, and timing
+**Special Mode - Dry Run** (`--dry-run`): Shows files to be deployed without uploading
+**Exit on Error**: Config loading failure, token validation, build failure, API error, upload failure
+
+#### 4. Configuration Validation (`ketrics validate`)
+
+**Inputs**: Optional paths to `ketrics.config.json` and `.env`
+**Process**:
+1. Check file existence
+2. Parse JSON and validate against schemas
+3. Check token format (warning only)
+4. Collect all errors and warnings
+5. Report validation results
+
+**Outputs**: List of errors (blocking) and warnings (informational)
+**Exit on Error**: Any validation errors present
+
+#### 5. API Request Execution (`ketrics run`)
+
+**Inputs**: JSON configuration file with endpoint, method, headers, body
+**Process**:
+1. Load environment configuration (requires `KETRICS_AUTH_TOKEN` and `KETRICS_RUNTIME_URL`)
+2. Parse JSON run file (validates schema)
+3. Create variable map from environment (tenantId, applicationId, token)
+4. Interpolate all template variables: `{{tenantId}}`, `{{applicationId}}`, `{{token}}`
+5. Construct full URL from runtime URL + interpolated endpoint
+6. Execute HTTP request with interpolated headers/body
+7. Display request and response details
+
+**Outputs**: HTTP response status and body
+**Exit on Error**: Missing env vars, invalid JSON, connection refused, timeout
 
-Loads and validates `ketrics.config.json` against the Zod schema. Throws descriptive errors for missing files or validation failures.
+### Business Rules
 
-```typescript
-export function loadEnvConfig(envPath?: string): EnvConfig;
-```
+- **Token Format**: Deployment tokens must start with `ktd_` (validated before API calls)
+- **App Name Format**: Must start with letter, contain only alphanumeric/hyphens/underscores
+- **Build Prerequisites**: Both frontend and backend must have `node_modules` before building
+- **Dist Structure**: Frontend builds to `frontend/dist/`, backend builds to `backend/dist/`
+- **File Patterns**: Include/exclude patterns use glob syntax for flexible file selection
+- **ZIP Compression**: Level 9 compression (maximum) used for all deployments
+- **Request Timeout**: API calls timeout at 30 seconds, S3 uploads at 5 minutes
+- **Variable Interpolation**: All string values in run JSON are scanned for `{{varName}}` patterns
 
-Loads `.env` file using dotenv, extracts `KETRICS_*` variables, and validates against schema.
+### Input/Output Expectations
 
-```typescript
-export function validateConfig(configPath?: string, envPath?: string): ValidationResult;
-```
+**Configuration Files**:
+- `ketrics.config.json`: JSON with name, version, actions, entry, include/exclude patterns
+- `.env`: Key=value format with KETRICS_* variables
+- Run JSON: POST/PUT/DELETE/PATCH/GET requests with endpoint, headers, body
 
-Non-throwing validation that returns `{ valid: boolean, errors: string[], warnings: string[] }`.
+**Exit Codes**:
+- `0`: Successful execution
+- `1`: Any error condition (validation failure, build failure, API error, etc.)
 
-#### `src/services/build-service.ts`
+## Technical Details
 
-```typescript
-export function buildAll(projectDir: string): BuildResult;
-```
+### Technology Stack
 
-Orchestrates building both frontend and backend. Returns paths to both `dist/` directories. Executes `npm run build` via `child_process.execSync` with `stdio: 'inherit'` to show build output.
+- **Runtime**: Node.js 24.0.0+ (specified in package.json engines)
+- **Language**: TypeScript 5.3.3 with strict type checking
+- **CLI Framework**: Commander.js 12.0.0 (argument parsing and command structure)
+- **HTTP Client**: Axios 1.6.0 (with timeout and error handling)
+- **Validation**: Zod 3.22.4 (schema validation for configs and responses)
+- **UI/UX**:
+  - Chalk 4.1.2 (colored terminal output)
+  - Ora 5.4.1 (loading spinners)
+  - @inquirer/prompts 7.10.1 (interactive prompts)
+- **File Operations**: Native Node.js fs and path modules
+- **Compression**: Archiver 6.0.1 (ZIP creation with streaming)
+- **Pattern Matching**: Glob 10.3.0 (file selection with include/exclude)
+- **Environment Loading**: dotenv 16.3.1 (.env file parsing)
+- **Process Execution**: Native Node.js child_process (execSync for npm commands)
+
+### Dependencies Analysis
 
-```typescript
-export function validateBuildDirectory(dir: string, name: string): BuildValidation;
+```json
+{
+  "core-cli": ["commander@12.0.0"],
+  "validation": ["zod@3.22.4"],
+  "http": ["axios@1.6.0"],
+  "compression": ["archiver@6.0.1"],
+  "file-patterns": ["glob@10.3.0"],
+  "environment": ["dotenv@16.3.1"],
+  "ui": ["chalk@4.1.2", "ora@5.4.1", "@inquirer/prompts@7.10.1"],
+  "dev-dependencies": ["typescript@5.3.3", "ts-node@1.7.1", "@types/*"]
+}
 ```
 
-Checks that a directory exists, has `node_modules`, and has `package.json`.
-
-#### `src/services/zip-service.ts`
-
-```typescript
-export async function createDeploymentZipBundle(
-  frontendDistPath: string,
-  backendDistPath: string,
-): Promise<{ buffer: Buffer; files: FileInfo[]; totalSourceSize: number; zipSize: number }>;
-```
+### File Descriptions
 
-Creates a ZIP buffer from frontend and backend dist directories. Uses archiver with `zlib: { level: 9 }` for maximum compression. Files are organized under `frontend/` and `backend/` prefixes.
+**bin/ketrics.ts**
+- Entry point executable (shebang for direct CLI usage)
+- Instantiates CLI via `createCLI()` and parses process.argv
+- Results in `dist/bin/ketrics.js` which is referenced in package.json bin field
 
-#### `src/services/api-client.ts`
+**src/cli.ts**
+- Configures Commander.js program with CLI name, version, and help text
+- Defines 5 commands: create, build, deploy, validate, run
+- Maps command arguments/options to handler functions
+- Exported as `createCLI()` function
 
-```typescript
-export async function initiateDeploy(envConfig: EnvConfig): Promise<DeployResponse>;
-```
+**src/commands/*.ts**
+- Each file exports single command handler function
+- Validates inputs, orchestrates service layer calls
+- Handles errors and formats output via logger
+- No business logic—purely orchestration and user interaction
 
-Calls `POST /tenants/{tenantId}/applications/{appId}/deploy` with Bearer token authentication. Returns presigned URL, deploymentId, and S3 key. Handles 401/403/404 with user-friendly error messages.
+**src/services/*.ts**
 
-#### `src/services/upload-service.ts`
+- **config-service.ts**: Zod validation, dotenv parsing, schema enforcement. Functions: `loadEnvConfig()`, `loadKetricsConfig()`, `validateConfig()`
+- **build-service.ts**: npm script execution via child_process. Functions: `buildAll()`, `runBuild()`, `validateBuildDirectory()`, `validateDistDirectory()`
+- **api-client.ts**: Axios POST to `/tenants/{id}/applications/{id}/deploy`. Returns presigned URL and deployment ID. Error handling for 401/403/404 status codes.
+- **zip-service.ts**: Archiver for ZIP creation, glob for file collection, streaming compression. Dual functions for config-based and directory-based bundling.
+- **upload-service.ts**: Axios PUT to S3 presigned URL with binary data. 5-minute timeout for large uploads. Error handling for 400/403/413 status codes.
+- **template-service.ts**: Directory traversal to discover templates, recursive copying, JSON field updates. Functions: `getAvailableTemplates()`, `copyTemplate()`, `updateAppName()`
 
-```typescript
-export async function uploadToS3(presignedUrl: string, zipBuffer: Buffer): Promise<void>;
-```
+**src/types/index.ts**
+- Zod schemas for runtime validation: `ketricsConfigSchema`, `envConfigSchema`, `runFileSchema`, `runEnvConfigSchema`
+- TypeScript interfaces derived from schemas via `z.infer<T>`
+- API response types: `DeployResponse` (presigned URL data)
+- Supporting types: `FileInfo`, `ValidationResult`, `TemplateInfo`
 
-Uploads ZIP buffer to S3 via presigned URL using PUT with `Content-Type: application/zip`. 5-minute timeout for large uploads.
+**src/utils/logger.ts**
+- Singleton object with named methods: `info()`, `success()`, `warn()`, `error()`, `log()`, `newline()`, `header()`, `keyValue()`, `indent()`, `file()`, `box()`
+- Uses chalk for ANSI color codes
+- Replaces raw `console.log()` throughout codebase
 
-#### `src/services/template-service.ts`
+**src/utils/spinner.ts**
+- `createSpinner(text)`: Ora spinner instance
+- `withSpinner<T>(text, operation, successText)`: Wraps async operation with spinner, handles errors, returns result
+- Provides visual feedback for long-running operations
 
-```typescript
-export function getAvailableTemplates(): TemplateInfo[];
-```
+**src/version.ts**
+- Single auto-generated export: `VERSION = "0.2.3"`
+- Generated by `scripts/generate-version.js` during build
+- Referenced in cli.ts for `--version` flag
 
-Scans the `templates/` directory for subdirectories containing `ketrics.config.json`.
+### Configuration Options and Environment Variables
 
+**ketrics.config.json Schema** (Zod validation):
 ```typescript
-export function copyTemplate(template: TemplateInfo, destDir: string): void;
+{
+  name: string,              // Project name (required, min 1 char)
+  version: string,           // Semver format e.g. "1.0.0" (required)
+  description?: string,      // Optional project description
+  runtime: "nodejs18" | "nodejs20" | "static", // Default: "nodejs18"
+  actions: string[],         // At least 1 action name (required)
+  entry: string,             // Entry point file (required)
+  include: string[],         // Glob patterns to include (required, min 1)
+  exclude: string[]          // Glob patterns to exclude (default: [])
+}
 ```
 
-Recursively copies template files to destination directory.
-
-```typescript
-export function updateAppName(projectDir: string, appName: string): void;
+**Environment Variables** (loaded from .env):
 ```
-
-Updates the `name` field in `ketrics.config.json`, `frontend/package.json`, and `backend/package.json`.
-
-### Configuration Options
-
-#### `ketrics.config.json` Schema
-
-```typescript
-const ketricsConfigSchema = z.object({
-  name: z.string().min(1),
-  version: z.string().regex(/^\d+\.\d+\.\d+$/), // semver
-  description: z.string().optional(),
-  runtime: z.enum(["nodejs18", "nodejs20", "static"]).default("nodejs18"),
-  actions: z.array(z.string()).min(1),
-  entry: z.string().min(1),
-  include: z.array(z.string()).min(1),
-  exclude: z.array(z.string()).default([]),
-});
+KETRICS_TOKEN              # Deploy token starting with "ktd_" (required)
+KETRICS_API_URL            # Ketrics API base URL (required, must be valid URL)
+KETRICS_TENANT_ID          # Tenant UUID (required, UUID format)
+KETRICS_APPLICATION_ID     # Application UUID (required, UUID format)
+KETRICS_AUTH_TOKEN         # Runtime auth token (optional, required for run command)
+KETRICS_RUNTIME_URL        # Runtime API URL (optional, required for run command, must be URL)
 ```
 
-#### Environment Variables
-
-| Variable                 | Required  | Description                                                   |
-| ------------------------ | --------- | ------------------------------------------------------------- |
-| `KETRICS_TOKEN`          | Yes       | Deployment token (format: `ktd_{id}_{secret}`)                |
-| `KETRICS_API_URL`        | Yes       | Tenant API API URL (e.g., `https://api.ketrics.io/api/v1`) |
-| `KETRICS_TENANT_ID`      | Yes       | Tenant UUID                                                   |
-| `KETRICS_APPLICATION_ID` | Yes       | Application UUID                                              |
-| `KETRICS_AUTH_TOKEN`     | For `run` | User auth token for runtime API calls                         |
-| `KETRICS_RUNTIME_URL`    | For `run` | Data Plane runtime URL                                        |
-
 ### External Integrations
 
-1. **Tenant API API**:
-   - Endpoint: `POST /tenants/{tenantId}/applications/{applicationId}/deploy`
-   - Auth: Bearer token (`KETRICS_TOKEN`)
-   - Response: Presigned S3 URL, deployment ID
-
-2. **AWS S3**:
-   - Upload method: HTTP PUT to presigned URL
-   - Content-Type: `application/zip`
-   - Max upload timeout: 5 minutes
-
-3. **Data Plane API** (via `ketrics run`):
-   - Endpoint: User-defined in JSON config files
-   - Auth: Bearer token (`KETRICS_AUTH_TOKEN`)
-
----
-
-## 4. Data Flow
-
-### Create Command Flow
-
-```
-User Input (app name)
-        │
-        ▼
-┌───────────────────┐
-│  Validate Name    │ ── Invalid ──▶ Exit with error
-└───────────────────┘
-        │ Valid
-        ▼
-┌───────────────────┐
-│ Check Dest Dir    │ ── Exists ──▶ Exit with error
-└───────────────────┘
-        │ OK
-        ▼
-┌───────────────────┐
-│ List Templates    │ ◀── Scan templates/ directory
-└───────────────────┘
-        │
-        ▼
-┌───────────────────┐
-│ Select Template   │ ◀── Interactive prompt or --template flag
-└───────────────────┘
-        │
-        ▼
-┌───────────────────┐
-│ Copy Files        │ ── Recursive copy to dest dir
-└───────────────────┘
-        │
-        ▼
-┌───────────────────┐
-│ Update App Name   │ ── Modify JSON files in-place
-└───────────────────┘
-        │
-        ▼
-Success message with next steps
-```
-
-### Deploy Command Flow
+**Ketrics Tenant API**
+- Endpoint: `POST /tenants/{KETRICS_TENANT_ID}/applications/{KETRICS_APPLICATION_ID}/deploy`
+- Authentication: Bearer token (KETRICS_TOKEN)
+- Request: Empty POST body
+- Response: `{ success: boolean, data: { uploadUrl, deploymentId, s3Key, expiresAt, expiresInSeconds } }`
+- Errors: 401 (bad token), 403 (no access), 404 (app not found)
+
+**AWS S3** (via presigned URL)
+- Method: PUT request to presigned URL from deploy response
+- Headers: `Content-Type: application/zip`, `Content-Length: <bytes>`
+- Body: Raw ZIP buffer (binary)
+- Timeout: 300 seconds (5 minutes)
+- Errors: 400 (expired URL), 403 (URL reused), 413 (file too large)
+
+**Ketrics Runtime API** (for run command)
+- Base URL: KETRICS_RUNTIME_URL from .env
+- Endpoint: User-specified path in run JSON
+- Authentication: Bearer token (KETRICS_AUTH_TOKEN in Authorization header)
+- Methods: GET, POST, PUT, DELETE, PATCH
+- Timeout: 30 seconds
+- Response: Any JSON/text (no validation)
+
+## Data Flow
+
+### Deploy Command Data Flow
+
+```
+User Input (--env flag, working directory)
+    ↓
+Load .env → dotenv.parse() → Zod validation → EnvConfig object
+    ↓
+Build frontend → execSync('npm run build') → frontend/dist/
+    ↓
+Build backend → execSync('npm run build') → backend/dist/
+    ↓
+Collect files → fs.readdirSync() recursive → FileInfo[] array
+    ↓
+Create ZIP → Archiver stream + glob + compression → Buffer
+    ↓
+API Call → axios.post() → Ketrics /deploy endpoint → DeployResponse
+    ↓
+S3 Upload → axios.put() → presigned URL + ZIP buffer → AWS S3
+    ↓
+Result → logger.box() → Deployment ID displayed to user
+```
+
+### Create Command Data Flow
+
+```
+User Input (app name, optional --template)
+    ↓
+Validate name → Regex check → boolean result
+    ↓
+Discover templates → fs.readdirSync(templates/) → TemplateInfo[]
+    ↓
+Prompt selection → inquirer.select() → User choice or --template flag
+    ↓
+Copy template → Recursive fs.copyFileSync() → New directory tree
+    ↓
+Update names → JSON.parse/stringify → Update name field in 3 files
+    ↓
+Result → logger.success() → Next steps printed to user
+```
+
+### Run Command Data Flow
+
+```
+User Input (JSON file path, optional --env flag)
+    ↓
+Load .env → dotenv.parse() → EnvConfig validation
+    ↓
+Load JSON file → fs.readFileSync() → JSON.parse() → Zod validation → RunFileConfig
+    ↓
+Create variables → Map EnvConfig to VariableMap { tenantId, applicationId, token }
+    ↓
+Interpolate strings → Regex replace {{varName}} → Fully resolved endpoint/headers/body
+    ↓
+Build full URL → KETRICS_RUNTIME_URL + endpoint → Full HTTP URL
+    ↓
+HTTP Request → axios() → Method/headers/body from interpolated config → AxiosResponse
+    ↓
+Display response → JSON.stringify(response.data) → Pretty-printed to console
+```
+
+### Configuration Validation Data Flow
+
+```
+User Input (optional --config and --env paths)
+    ↓
+Read ketrics.config.json → fs.readFileSync() → JSON.parse() → Zod parse
+    ↓
+Collect errors/warnings → Zod error messages + custom checks
+    ↓
+Read .env → dotenv.config() → Extract KETRICS_* vars → Zod parse
+    ↓
+Token format check → Regex /^ktd_/ → Warning if doesn't match
+    ↓
+Return ValidationResult → { valid: boolean, errors: [], warnings: [] }
+    ↓
+Display results → logger.error() or logger.success()
+```
+
+## Error Handling
+
+### Error Scenarios and Handling
+
+**Configuration Loading Errors**
+- File not found: "Configuration file not found: {path}\nRun 'ketrics init' to create one."
+- Invalid JSON: "Invalid JSON in configuration file: {path}"
+- Zod validation: Field-by-field error messages with paths
+- Recovery: Exit with code 1, display errors before exit
+
+**Build Errors**
+- Directory missing: "frontend/ directory not found"
+- Missing node_modules: "Missing node_modules in {name}/. Run 'cd {name} && npm install' first."
+- Build command failure: "{name} build failed. Check the output above for errors."
+- Missing dist: "{name} build did not produce dist/ directory"
+- Recovery: execSync() inherits stdio (shows npm output), thrown Error caught by command handler
+
+**API/Network Errors**
+- 401 Unauthorized: "Authentication failed: Invalid or expired deployment token.\nPlease check your KETRICS_TOKEN in the .env file."
+- 403 Forbidden: "Authorization failed: Token does not have access to this application.\nPlease verify KETRICS_TENANT_ID and KETRICS_APPLICATION_ID."
+- 404 Not Found: "Application not found. Please verify KETRICS_APPLICATION_ID."
+- Network unreachable: "Network error: Could not connect to {url}\nPlease check your internet connection and KETRICS_API_URL."
+- S3 upload 400: "Upload failed: Invalid request. The presigned URL may have expired."
+- S3 upload 403: "Upload failed: Access denied. The presigned URL may have expired or been used."
+- S3 upload 413: "Upload failed: File too large. Maximum upload size exceeded."
+- Recovery: Error message logged, process exit(1)
+
+**Input Validation Errors**
+- Invalid app name: "App name must start with a letter and contain only letters, numbers, hyphens, and underscores"
+- Missing template: "Template not found: {name}" with list of available templates
+- Directory exists: "Folder '{appName}' already exists."
+- Invalid run JSON: "Invalid run file format:" with detailed Zod path and message
+- Recovery: Error logged, process exit(1)
 
-```
-.env file
-    │
-    ▼
-┌───────────────────┐
-│  Load & Validate  │ ── Invalid ──▶ Exit with error
-│    Environment    │
-└───────────────────┘
-    │
-    ▼
-┌───────────────────┐
-│ Validate Token    │ ── Not ktd_ ──▶ Exit with error
-└───────────────────┘
-    │
-    ▼
-┌───────────────────────────────────────────┐
-│          Build Phase                       │
-│  ┌─────────────────┐  ┌─────────────────┐ │
-│  │ npm run build   │  │ npm run build   │ │
-│  │   (frontend)    │  │   (backend)     │ │
-│  └────────┬────────┘  └────────┬────────┘ │
-│           │                    │          │
-│           ▼                    ▼          │
-│    frontend/dist/        backend/dist/    │
-└───────────────────────────────────────────┘
-    │
-    ▼
-┌───────────────────┐
-│  Create ZIP       │
-│  - frontend/*     │
-│  - backend/*      │
-│  (level 9 zlib)   │
-└───────────────────┘
-    │ Buffer
-    ▼
-┌───────────────────┐                    ┌───────────────────┐
-│ Tenant API API │ ──────────────────▶│  DeployResponse   │
-│ POST .../deploy   │                    │  - uploadUrl      │
-│ Bearer ktd_...    │                    │  - deploymentId   │
-└───────────────────┘                    │  - s3Key          │
-                                         └───────────────────┘
-    │ uploadUrl
-    ▼
-┌───────────────────┐
-│  PUT to S3        │
-│  presigned URL    │
-│  Content-Type:    │
-│  application/zip  │
-└───────────────────┘
-    │
-    ▼
-Success box with deploymentId
-```
-
-### Run Command Flow
-
-```
-JSON config file (e.g., test.greet.json)
-    │
-    │  {
-    │    "endpoint": "/tenants/{{tenantId}}/apps/{{appId}}/functions/greet",
-    │    "method": "POST",
-    │    "headers": { "Authorization": "Bearer {{token}}" },
-    │    "body": { "name": "World" }
-    │  }
-    │
-    ▼
-┌───────────────────┐
-│ Load .env         │
-│ (KETRICS_AUTH_    │
-│  TOKEN required)  │
-└───────────────────┘
-    │
-    ▼
-┌───────────────────┐
-│ Parse & Validate  │ ── Zod runFileSchema
-│    JSON File      │
-└───────────────────┘
-    │
-    ▼
-┌───────────────────┐
-│ Interpolate Vars  │ ── Replace {{tenantId}}, {{applicationId}}, {{token}}
-└───────────────────┘
-    │
-    ▼
-┌───────────────────┐
-│ Execute Request   │ ── axios({ method, url, headers, data })
-│ KETRICS_RUNTIME_  │
-│ URL + endpoint    │
-└───────────────────┘
-    │
-    ▼
-Formatted response (status + JSON body)
-```
+### Retry Logic
 
----
-
-## 5. Error Handling
-
-### Error Scenarios
-
-| Scenario               | Detection                        | User Message                                                                                    |
-| ---------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
-| Missing .env file      | `fs.existsSync()` check          | "Environment file not found: {path}"                                                            |
-| Invalid JSON in config | JSON.parse throws                | "Invalid JSON in configuration file: {path}"                                                    |
-| Zod validation failure | `safeParse().success === false`  | "Invalid configuration:\n - {field}: {message}"                                                 |
-| Invalid token format   | String prefix check              | "Invalid token format. Token should start with 'ktd\_'"                                         |
-| Missing node_modules   | Directory check                  | "Missing node_modules in {dir}/. Run 'cd {dir} && npm install' first."                          |
-| Build failure          | execSync throws                  | "{name} build failed. Check the output above for errors."                                       |
-| No dist directory      | Post-build directory check       | "{name} build did not produce dist/ directory"                                                  |
-| API 401                | HTTP status check                | "Authentication failed: Invalid or expired deployment token."                                   |
-| API 403                | HTTP status check                | "Authorization failed: Token does not have access to this application."                         |
-| API 404                | HTTP status check                | "Application not found. Please verify KETRICS_APPLICATION_ID."                                  |
-| Network error          | axios.isAxiosError + no response | "Network error: Could not connect to {url}"                                                     |
-| S3 upload 403          | HTTP status check                | "Upload failed: Access denied. The presigned URL may have expired or been used."                |
-| S3 upload 413          | HTTP status check                | "Upload failed: File too large. Maximum upload size exceeded."                                  |
-| Upload timeout         | axios timeout                    | "Upload failed: Network error. Please check your internet connection."                          |
-| Folder already exists  | `fs.existsSync()`                | "Folder '{name}' already exists."                                                               |
-| Invalid app name       | Regex test                       | "App name must start with a letter and contain only letters, numbers, hyphens, and underscores" |
+- **Explicit Retries**: None implemented—all operations are single-attempt
+- **Presigned URL Expiration**: 15 minutes (expiresInSeconds from API response)
+- **Timeout Handling**:
+  - API calls: 30 second timeout
+  - S3 uploads: 300 second timeout (5 minutes)
+  - User can re-run command if timeout occurs
 
-### Retry Logic
+### Fallback Mechanisms
 
-The CLI does **not** implement automatic retry for API calls. Network failures result in immediate error and process exit. This is intentional—deployments are explicit actions where the developer should understand and resolve any connectivity issues before retrying.
+- **Template Selection**: If multiple templates exist, interactive selection via inquirer; if one template exists, auto-select; if none exist, error with instructions
+- **Build Validation**: Checks for node_modules and package.json before running npm build
+- **Token Format**: Validates token format (`ktd_` prefix) before API call, providing early feedback
+- **Variable Interpolation**: Unknown variables in run JSON remain as-is with warning logged
 
 ### Logging Approach
 
-All user-facing output goes through `src/utils/logger.ts`:
-
-```typescript
-logger.info(message)    // Blue ℹ prefix
-logger.success(message) // Green ✔ prefix
-logger.warn(message)    // Yellow ⚠ prefix
-logger.error(message)   // Red ✖ prefix
-logger.keyValue(k, v)   // Formatted key: value pairs
-logger.file(path, size) // Cyan file path with optional size
-logger.box(title, [...])// Green success box with details
-```
+**Logger Levels** (not severity-based, visual categorization):
+- `info()`: Blue "ℹ" icon + message (informational)
+- `success()`: Green "✔" icon + message (operation succeeded)
+- `warn()`: Yellow "⚠" icon + message (non-blocking issues)
+- `error()`: Red "✖" icon + message (operation failed)
+- `log()`: Plain text (neutral output)
+- `header()`: Bold text with newlines (section markers)
+- `keyValue()`: Gray key + value (structured data)
+- `box()`: Green checkmark box (success summary)
 
-Long-running operations use spinners (`src/utils/spinner.ts`):
+**Log Points**:
+1. Command start: `logger.header()` with command name
+2. Major operation start: `withSpinner()` text
+3. Operation completion: `spinner.succeed()` text
+4. Data summaries: `logger.keyValue()` for important values
+5. Errors: `logger.error()` before exit or throw
+6. Success: `logger.box()` or `logger.success()` at end
 
-```typescript
-await withSpinner(
-  "Loading environment configuration", // Shown during operation
-  async () => loadEnvConfig(options.env),
-  "Loaded environment configuration", // Shown on success
-);
+**Example Deploy Logging**:
+```
+Ketrics CLI v1.0.0          [header]
+ℹ Loading environment...    [spinner start]
+✔ Loaded environment        [spinner succeed]
+Building frontend...        [info]
+Building backend...         [info]
+✔ Build completed           [success]
+Frontend dist: ...          [keyValue]
 ```
 
-Build output is passed through to the terminal via `stdio: 'inherit'` in `execSync`, so developers see native npm/Vite/TypeScript output.
-
----
-
-## 6. Usage
+## Usage
 
-### Installation
+### Installation and Setup
 
 ```bash
-# Global installation
+# Install globally
 npm install -g @ketrics/ketrics-cli
 
-# Or run directly with npx
-npx @ketrics/ketrics-cli deploy
+# Or use as dev dependency
+npm install --save-dev @ketrics/ketrics-cli
 
-# Development installation (from source)
-cd ketrics-cli
-npm install
-npm run build
-npm link
+# Verify installation
+ketrics --version
 ```
 
-### Commands
+### Running Commands
 
-#### Create New Application
+#### Create a New Application
 
 ```bash
 # Interactive template selection
 ketrics create my-app
 
-# Use specific template
-ketrics create my-app --template ketrics-app-v1
+# Specify template directly
+ketrics create my-app --template HelloWorld
 ```
 
-#### Build Without Deploying
+**Output**:
+- New directory `my-app/` with template structure
+- Console instructions for next steps
+- Pre-configured `ketrics.config.json` and package.json files
+
+**Prerequisites**: None (discovers templates from bundled templates/)
+
+#### Build Application
 
 ```bash
+cd my-app
 ketrics build
 ```
 
-#### Deploy to Platform
+**Output**:
+- Compiled `frontend/dist/` directory
+- Compiled `backend/dist/` directory
+- Console summary with paths
+
+**Prerequisites**:
+- Current directory contains `frontend/` and `backend/` subdirectories
+- Both directories have `node_modules/` installed
+- Both directories have `package.json` with `build` script
+
+#### Deploy Application
 
 ```bash
 # Standard deployment
 ketrics deploy
 
-# Use specific .env file
-ketrics deploy --env /path/to/.env
+# Custom .env path
+ketrics deploy --env ./config/.env.production
 
-# Preview what would be deployed (no upload)
+# Dry run (see what would deploy without uploading)
 ketrics deploy --dry-run
 ```
 
+**Output**:
+- Deployment ID
+- File count and total size
+- Processing confirmation
+
+**Prerequisites**:
+- `.env` file with KETRICS_TOKEN, KETRICS_API_URL, KETRICS_TENANT_ID, KETRICS_APPLICATION_ID
+- Built `frontend/dist/` and `backend/dist/` directories
+- Valid deployment token (starts with `ktd_`)
+
 #### Validate Configuration
 
 ```bash
-# Validate default files
+# Validate with defaults
 ketrics validate
 
-# Validate specific files
-ketrics validate --config ./custom.config.json --env ./custom.env
+# Custom paths
+ketrics validate --config ./config/ketrics.config.json --env ./.env.staging
 ```
 
-#### Execute API Request
-
-```bash
-# Run test request from JSON file
-ketrics run tests/test.greet.json
-
-# With custom .env and verbose output
-ketrics run tests/test.echo.json --env .env.local --verbose
-```
+**Output**:
+- List of errors (if any)
+- List of warnings (if any)
+- Success/failure status
 
-### Example Run File
+**Prerequisites**: None (creates validation report even if files don't exist)
 
-`tests/test.greet.json`:
+#### Execute API Requests
 
-```json
+```bash
+# Create request file: request.json
 {
-  "endpoint": "/tenants/{{tenantId}}/applications/{{applicationId}}/functions/greet",
-  "method": "POST",
+  "endpoint": "/users/{{tenantId}}/profile",
+  "method": "GET",
   "headers": {
-    "Authorization": "Bearer {{token}}",
-    "Content-Type": "application/json"
-  },
-  "body": {
-    "name": "World"
+    "Authorization": "Bearer {{token}}"
   }
 }
+
+# Execute request
+ketrics run request.json
+
+# Verbose output
+ketrics run request.json --verbose
+
+# Custom .env
+ketrics run request.json --env ./.env.dev
 ```
 
-### Development Commands
+**Output**:
+- Formatted HTTP request (method, URL, headers, body)
+- Formatted HTTP response (status, body)
+- Duration in seconds
+
+**Prerequisites**:
+- `.env` file with KETRICS_AUTH_TOKEN and KETRICS_RUNTIME_URL
+- Valid JSON request file
 
+### Example Invocations
+
+**Full Deployment Workflow**:
 ```bash
-# Build TypeScript to dist/
-npm run build
+# Create new project
+ketrics create my-todo-app --template HelloWorld
 
-# Run CLI in development mode (ts-node)
-npm run dev -- create my-app
-npm run dev -- deploy --dry-run
+# Navigate to project
+cd my-todo-app
 
-# Clean build artifacts
-npm run clean
-```
+# Install dependencies
+cd frontend && npm install
+cd ../backend && npm install
+cd ..
 
-### Testing Approach
+# Copy .env from template
+cp .env.example .env
+# Edit .env with your credentials
 
-The CLI does not include automated tests in the current implementation. Testing is performed manually:
+# Validate configuration
+ketrics validate
 
-1. **Unit testing config validation**: Create various `.env` and `ketrics.config.json` files with valid/invalid data, run `ketrics validate`
-2. **Integration testing deployment**:
-   - `ketrics create test-app`
-   - `cd test-app/frontend && npm install && cd ../backend && npm install`
-   - Configure `.env` with real credentials
-   - `ketrics deploy --dry-run` to verify packaging
-   - `ketrics deploy` to test full flow
-3. **Runtime testing**: Use `ketrics run tests/test.*.json` against deployed application
+# Build application
+ketrics build
 
-### Example Session
+# Deploy to Ketrics
+ketrics deploy
+```
 
+**Testing API Endpoints**:
 ```bash
-# Create a new application
-$ ketrics create hello-world
+# Create .env with runtime credentials
+cat > .env.test << EOF
+KETRICS_TENANT_ID=12345678-1234-1234-1234-123456789012
+KETRICS_APPLICATION_ID=87654321-4321-4321-4321-210987654321
+KETRICS_AUTH_TOKEN=your_runtime_token_here
+KETRICS_RUNTIME_URL=https://api.runtime.ketrics.io
+EOF
+
+# Create request file
+cat > api-test.json << EOF
+{
+  "endpoint": "/health",
+  "method": "GET",
+  "headers": {
+    "Authorization": "Bearer {{token}}"
+  }
+}
+EOF
 
-Creating 'hello-world' with template: ketrics-app-v1
+# Execute
+ketrics run api-test.json --env .env.test
+```
 
-Files to create:
-    hello-world/ketrics.config.json
-    hello-world/frontend/package.json
-    hello-world/backend/package.json
-    ...
+### Testing Approach
 
-✔ Created 'hello-world' successfully!
+**Unit Testing** (not included in code):
+- Would test individual service functions: `loadEnvConfig()`, `buildAll()`, `collectFiles()`, etc.
+- Mock file system, axios, child_process
+- Verify schema validation with valid/invalid inputs
+- Test error handling paths
+
+**Integration Testing** (not included in code):
+- Test complete command workflows
+- Use temporary directories and files
+- Mock Ketrics API responses
+- Verify file structure creation and modification
+
+**Manual Testing** (recommended):
+1. Create test project with `ketrics create test-app`
+2. Modify `.env` with test credentials
+3. Run `ketrics validate` to verify setup
+4. Run `ketrics build` to verify npm scripts exist
+5. Run `ketrics deploy --dry-run` to verify packaging
+6. Run `ketrics run` with test request to verify runtime access
+7. Full `ketrics deploy` to staging environment
+
+**Testing Checklist**:
+- Create command with interactive and flag-based template selection
+- Build command with missing node_modules, missing dist directories
+- Deploy command with invalid token format, network errors, S3 failures
+- Validate command with missing files, invalid JSON, schema violations
+- Run command with missing variables, malformed JSON, API errors
+- Edge cases: empty directories, very large files, special characters in names
+
+## Advanced Topics
+
+### Custom Configuration Patterns
+
+The `include`/`exclude` patterns in `ketrics.config.json` use glob syntax:
 
-Next steps:
-  1. cd hello-world
-  2. cd frontend && npm install
-  3. cd ../backend && npm install
-  4. Copy .env.example to .env and add your credentials
-  5. Run 'ketrics deploy' to deploy your application
+```json
+{
+  "include": [
+    "frontend/dist/**/*",
+    "backend/dist/**/*"
+  ],
+  "exclude": [
+    "**/*.map",
+    "**/node_modules/**",
+    "**/.git/**"
+  ]
+}
+```
 
-# Install dependencies
-$ cd hello-world
-$ cd frontend && npm install && cd ../backend && npm install
+### Programmatic Usage
 
-# Configure credentials
-$ cp .env.example .env
-$ vim .env  # Add your KETRICS_TOKEN, etc.
+The CLI exports services for use in other Node.js applications:
 
-# Deploy
-$ ketrics deploy
+```typescript
+import {
+  loadEnvConfig,
+  buildAll,
+  createDeploymentZipBundle,
+  uploadToS3,
+  initiateDeploy
+} from '@ketrics/ketrics-cli';
+
+// Load config
+const config = loadEnvConfig('/path/to/.env');
+
+// Build application
+const buildResult = buildAll(process.cwd());
+
+// Create ZIP
+const zip = await createDeploymentZipBundle(
+  buildResult.frontendDistPath,
+  buildResult.backendDistPath
+);
 
-Ketrics CLI v1.0.0
+// Upload
+await uploadToS3(presignedUrl, zip.buffer);
+```
+
+### Environment-Specific Deployments
 
-✔ Loaded environment configuration
-✔ Validated deployment token
+Use different `.env` files for different environments:
 
-Building frontend and backend...
+```bash
+# Staging
+ketrics deploy --env .env.staging
+
+# Production
+ketrics deploy --env .env.production
+```
 
-> hello-world@1.0.0 build
-> vite build
-...
+### Debugging
 
-✔ Frontend and backend built successfully
-✔ Created deployment ZIP archive
-✔ ZIP archive: 45.2 KB from 6 files
-✔ Initiated deployment
-✔ Uploaded to S3
+Enable verbose output where available:
 
-  ✅ Deployment successful!
+```bash
+# Run command with verbose flag
+ketrics run request.json --verbose
 
-  Deployment ID: 550e8400-e29b-41d4-a716-446655440002
-  Files:         6
-  Size:          45.2 KB
-  Duration:      4.1s
+# Build process inherits stdio (shows npm output)
+ketrics build  # Shows all npm build output
 
-  Your deployment is being processed by Ketrics.
+# API client logs URL before request
+# (Search for "console.log" in api-client.ts for debug points)
 ```
+
+## Version Information
+
+- **CLI Version**: 0.2.3 (auto-generated in `src/version.ts`)
+- **Node.js Requirement**: 24.0.0 or later
+- **TypeScript**: 5.3.3
+- **Last Updated**: 2024-2025
+
+## Contributing
+
+When modifying the CLI:
+1. Follow TypeScript strict mode (tsconfig.json)
+2. Export types and services from `src/index.ts`
+3. Add Zod schemas for new configuration options
+4. Use logger utility instead of console.log
+5. Wrap async operations with withSpinner for UX
+6. Run `npm run build` before testing (generates version.ts)
+7. Test all command paths, especially error scenarios