berget 2.0.3 → 2.0.4

package/src/commands/code.ts

@@ -11,39 +11,13 @@ import path from 'path'
 import { spawn } from 'child_process'
 import { updateEnvFile } from '../utils/env-manager'
 import { createAuthenticatedClient } from '../client'
-
-// Centralized model configuration
-const MODEL_CONFIG = {
-  // Model names used in agent configurations (with provider prefix)
-  AGENT_MODELS: {
-    primary: 'berget/deepseek-r1',
-    small: 'berget/gpt-oss',
-  },
-  // Model definitions in provider configuration (without prefix)
-  PROVIDER_MODELS: {
-    'deepseek-r1': {
-      name: 'GLM-4.6',
-      limit: {
-        output: 4000,
-        context: 90000,
-      },
-    },
-    'gpt-oss': {
-      name: 'GPT-OSS',
-      limit: {
-        output: 4000,
-        context: 128000,
-      },
-    },
-    'llama-8b': {
-      name: 'llama-3.1-8b',
-      limit: {
-        output: 4000,
-        context: 128000,
-      },
-    },
-  },
-}
+import { 
+  getConfigLoader, 
+  getModelConfig, 
+  getProviderModels,
+  type OpenCodeConfig,
+  type AgentConfig 
+} from '../utils/config-loader'
 
 /**
  * Check if current directory has git
@@ -65,6 +39,7 @@ async function mergeConfigurations(
 ): Promise<any> {
   try {
     const client = createAuthenticatedClient()
+    const modelConfig = getModelConfig()
 
     console.log(chalk.blue('🤖 Using AI to merge configurations...'))
 
@@ -87,7 +62,7 @@ Return ONLY the merged JSON configuration, no explanations.`
 
     const response = await client.POST('/v1/chat/completions', {
       body: {
-        model: MODEL_CONFIG.AGENT_MODELS.primary,
+        model: modelConfig.primary,
         messages: [
           {
             role: 'user',
@@ -297,6 +272,21 @@ function getProjectName(): string {
   return path.basename(process.cwd())
 }
 
+/**
+ * Load the latest agent configuration from opencode.json
+ */
+async function loadLatestAgentConfig(): Promise<any> {
+  try {
+    const configPath = path.join(__dirname, '../../opencode.json')
+    const configContent = await readFile(configPath, 'utf8')
+    const config = JSON.parse(configContent)
+    return config.agent || {}
+  } catch (error) {
+    console.warn(chalk.yellow('⚠️  Could not load latest agent config, using fallback'))
+    return {}
+  }
+}
+
 /**
  * Check if opencode is installed
  */
@@ -640,6 +630,10 @@ export function registerCodeCommands(program: Command): void {
         // Prepare .env file path for safe update
         const envPath = path.join(process.cwd(), '.env')
 
+        // Load latest agent configuration to ensure consistency
+        const latestAgentConfig = await loadLatestAgentConfig()
+        const modelConfig = getModelConfig()
+
         // Create opencode.json config with optimized agent-based format
         const config = {
           $schema: 'https://opencode.ai/config.json',
@@ -647,11 +641,11 @@ export function registerCodeCommands(program: Command): void {
           theme: 'berget-dark',
           share: 'manual',
           autoupdate: true,
-          model: MODEL_CONFIG.AGENT_MODELS.primary,
-          small_model: MODEL_CONFIG.AGENT_MODELS.small,
+          model: modelConfig.primary,
+          small_model: modelConfig.small,
           agent: {
             fullstack: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.3,
               top_p: 0.9,
               mode: 'primary',
@@ -662,7 +656,7 @@ export function registerCodeCommands(program: Command): void {
                 'Voice: Scandinavian calm—precise, concise, confident; no fluff. You are Berget Code Fullstack agent. Act as a router and coordinator in a monorepo. Bottom-up schema: database → OpenAPI → generated types. Top-down types: API → UI → components. Use openapi-fetch and Zod at every boundary; compile-time errors are desired when contracts change. Routing rules: if task/paths match /apps/frontend or React (.tsx) → use frontend; if /apps/app or Expo/React Native → app; if /infra, /k8s, flux-system, kustomization.yaml, Helm values → devops; if /services, Koa routers, services/adapters/domain → backend. If ambiguous, remain fullstack and outline the end-to-end plan, then delegate subtasks to the right persona. Security: validate inputs; secrets via FluxCD SOPS/Sealed Secrets. Documentation is generated from code—never duplicated. CRITICAL: When all implementation tasks are complete and ready for merge, ALWAYS invoke @quality subagent to handle testing, building, and complete PR management including URL provision.',
             },
             frontend: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.4,
               top_p: 0.9,
               mode: 'primary',
@@ -674,7 +668,7 @@ export function registerCodeCommands(program: Command): void {
                 'You are Berget Code Frontend agent. Voice: Scandinavian calm—precise, concise, confident. React 18 + TypeScript. Tailwind + Shadcn UI only via the design system (index.css, tailwind.config.ts). Use semantic tokens for color/spacing/typography/motion; never ad-hoc classes or inline colors. Components are pure and responsive; props-first data; minimal global state (Zustand/Jotai). Accessibility and keyboard navigation mandatory. Mock data only at init under /data via typed hooks (e.g., useProducts() reading /data/products.json). Design: minimal, balanced, quiet motion. CRITICAL: When all frontend implementation tasks are complete and ready for merge, ALWAYS invoke @quality subagent to handle testing, building, and complete PR management including URL provision.',
             },
             backend: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.3,
               top_p: 0.9,
               mode: 'primary',
@@ -684,8 +678,9 @@ export function registerCodeCommands(program: Command): void {
               prompt:
                 'You are Berget Code Backend agent. Voice: Scandinavian calm—precise, concise, confident. TypeScript + Koa. Prefer many small pure functions; avoid big try/catch blocks. Routes thin; logic in services/adapters/domain. Validate with Zod; auto-generate OpenAPI. Adapters isolate external systems; domain never depends on framework. Test with supertest; idempotent and stateless by default. Each microservice emits an OpenAPI contract; changes propagate upward to types. Code Quality & Refactoring Principles: Apply Single Responsibility Principle, fail fast with explicit errors, eliminate code duplication, remove nested complexity, use descriptive error codes, keep functions under 30 lines. Always leave code cleaner and more readable than you found it. CRITICAL: When all backend implementation tasks are complete and ready for merge, ALWAYS invoke @quality subagent to handle testing, building, and complete PR management including URL provision.',
             },
-            devops: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+            // Use centralized devops configuration with Helm guidelines
+            devops: latestAgentConfig.devops || {
+              model: modelConfig.primary,
               temperature: 0.3,
               top_p: 0.8,
               mode: 'primary',
@@ -696,7 +691,7 @@ export function registerCodeCommands(program: Command): void {
                 'You are Berget Code DevOps agent. Voice: Scandinavian calm—precise, concise, confident. Start simple: k8s/{deployment,service,ingress}. Add FluxCD sync to repo and image automation. Use Kustomize bases/overlays (staging, production). Add dependencies via Helm from upstream sources; prefer native operators when available (CloudNativePG, cert-manager, external-dns). SemVer with -rc tags keeps CI environments current. Observability with Prometheus/Grafana. No manual kubectl in production—Git is the source of truth.',
             },
             app: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.4,
               top_p: 0.9,
               mode: 'primary',
@@ -708,7 +703,7 @@ export function registerCodeCommands(program: Command): void {
                 'You are Berget Code App agent. Voice: Scandinavian calm—precise, concise, confident. Expo + React Native + TypeScript. Structure by components/hooks/services/navigation. Components are pure; data via props; refactor shared logic into hooks/stores. Share tokens with frontend. Mock data in /data via typed hooks; later replace with live APIs. Offline via SQLite/MMKV; notifications via Expo. Request permissions only when needed. Subtle, meaningful motion; light/dark parity.',
             },
             security: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.2,
               top_p: 0.8,
               mode: 'subagent',
@@ -719,7 +714,7 @@ export function registerCodeCommands(program: Command): void {
                 'Voice: Scandinavian calm—precise, concise, confident. You are Berget Code Security agent. Expert in application security, penetration testing, and OWASP standards. Core responsibilities: Conduct security assessments and penetration tests, Validate OWASP Top 10 compliance, Review code for security vulnerabilities, Implement security headers and Content Security Policy (CSP), Audit API security, Check for sensitive data exposure, Validate input sanitization and output encoding, Assess dependency security and supply chain risks. Tools and techniques: OWASP ZAP, Burp Suite, security linters, dependency scanners, manual code review. Always provide specific, actionable security recommendations with priority levels.',
             },
             quality: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.1,
               top_p: 0.9,
               mode: 'subagent',
@@ -781,7 +776,7 @@ export function registerCodeCommands(program: Command): void {
                 baseURL: 'https://api.berget.ai/v1',
                 apiKey: '{env:BERGET_API_KEY}',
               },
-              models: MODEL_CONFIG.PROVIDER_MODELS,
+              models: getProviderModels(),
             },
           },
         }
@@ -908,6 +903,12 @@ Declarative GitOps infrastructure with FluxCD, Kustomize, Helm, and operators.
 - Operator-first approach
 - SemVer with release candidates
 
+**Helm Values Configuration Process:**
+1. Documentation First Approach: Always fetch official documentation from Artifact Hub/GitHub for the specific chart version before writing values. Search Artifact Hub for exact chart version documentation, check the chart's GitHub repository for official docs and examples, verify the exact version being used in the deployment.
+2. Validation Requirements: Check for available validation schemas before committing YAML files. Use Helm's built-in validation tools (helm lint, helm template). Validate against JSON schema if available for the chart. Ensure YAML syntax correctness with linters.
+3. Standard Workflow: Identify chart name and exact version. Fetch official documentation from Artifact Hub/GitHub. Check for available schemas and validation tools. Write values according to official documentation. Validate against schema (if available). Test with helm template or helm lint. Commit validated YAML files.
+4. Quality Assurance: Never commit unvalidated Helm values. Use helm dependency update when adding new charts. Test rendering with helm template --dry-run before deployment. Document any custom values with comments referencing official docs.
+
 #### app
 Expo + React Native applications with props-first architecture and offline awareness.
 
@@ -1103,7 +1104,6 @@ All agents follow these principles:
 
         // Set environment variables for opencode
         const env = { ...process.env }
-        env.OPENCODE_API_KEY = config.apiKey
 
         // Prepare opencode command
         const opencodeArgs: string[] = []
@@ -1146,6 +1146,56 @@ All agents follow these principles:
       }
     })
 
+  code
+    .command(SUBCOMMANDS.CODE.SERVE)
+    .description('Start OpenCode web server')
+    .option('-p, --port <port>', 'Port to run the server on (default: 3000)')
+    .option('-h, --host <host>', 'Host to bind the server to (default: localhost)')
+    .option(
+      '-y, --yes',
+      'Automatically answer yes to all prompts (for automation)',
+    )
+    .action(async (options) => {
+      try {
+        // Ensure opencode is installed
+        if (!(await ensureOpencodeInstalled(options.yes))) {
+          return
+        }
+
+        console.log(chalk.cyan('🚀 Starting OpenCode web server...'))
+
+        // Prepare opencode serve command
+        const serveArgs: string[] = ['serve']
+
+        if (options.port) {
+          serveArgs.push('--port', options.port)
+        }
+
+        if (options.host) {
+          serveArgs.push('--host', options.host)
+        }
+
+        // Spawn opencode serve process
+        const opencode = spawn('opencode', serveArgs, {
+          stdio: 'inherit',
+          shell: true,
+        })
+
+        opencode.on('close', (code) => {
+          if (code !== 0) {
+            console.log(chalk.red(`OpenCode server exited with code ${code}`))
+          }
+        })
+
+        opencode.on('error', (error) => {
+          console.error(chalk.red('Failed to start OpenCode server:'))
+          console.error(error.message)
+        })
+      } catch (error) {
+        handleError('Failed to start OpenCode server', error)
+      }
+    })
+
   code
     .command(SUBCOMMANDS.CODE.UPDATE)
     .description('Update OpenCode and agents to latest versions')
@@ -1196,6 +1246,10 @@ All agents follow these principles:
           ),
         )
 
+        // Load latest agent configuration to ensure consistency
+        const latestAgentConfig = await loadLatestAgentConfig()
+        const modelConfig = getModelConfig()
+
         // Create latest configuration with all improvements
         const latestConfig = {
           $schema: 'https://opencode.ai/config.json',
@@ -1203,11 +1257,11 @@ All agents follow these principles:
           theme: 'berget-dark',
           share: 'manual',
           autoupdate: true,
-          model: MODEL_CONFIG.AGENT_MODELS.primary,
-          small_model: MODEL_CONFIG.AGENT_MODELS.small,
+          model: modelConfig.primary,
+          small_model: modelConfig.small,
           agent: {
             fullstack: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.3,
               top_p: 0.9,
               mode: 'primary',
@@ -1218,7 +1272,7 @@ All agents follow these principles:
                 'Voice: Scandinavian calm—precise, concise, confident; no fluff. You are Berget Code Fullstack agent. Act as a router and coordinator in a monorepo. Bottom-up schema: database → OpenAPI → generated types. Top-down types: API → UI → components. Use openapi-fetch and Zod at every boundary; compile-time errors are desired when contracts change. Routing rules: if task/paths match /apps/frontend or React (.tsx) → use frontend; if /apps/app or Expo/React Native → app; if /infra, /k8s, flux-system, kustomization.yaml, Helm values → devops; if /services, Koa routers, services/adapters/domain → backend. If ambiguous, remain fullstack and outline the end-to-end plan, then delegate subtasks to the right persona. Security: validate inputs; secrets via FluxCD SOPS/Sealed Secrets. Documentation is generated from code—never duplicated. CRITICAL: When all implementation tasks are complete and ready for merge, ALWAYS invoke @quality subagent to handle testing, building, and complete PR management including URL provision.',
             },
             frontend: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.4,
               top_p: 0.9,
               mode: 'primary',
@@ -1230,7 +1284,7 @@ All agents follow these principles:
                 'You are Berget Code Frontend agent. Voice: Scandinavian calm—precise, concise, confident. React 18 + TypeScript. Tailwind + Shadcn UI only via the design system (index.css, tailwind.config.ts). Use semantic tokens for color/spacing/typography/motion; never ad-hoc classes or inline colors. Components are pure and responsive; props-first data; minimal global state (Zustand/Jotai). Accessibility and keyboard navigation mandatory. Mock data only at init under /data via typed hooks (e.g., useProducts() reading /data/products.json). Design: minimal, balanced, quiet motion. CRITICAL: When all frontend implementation tasks are complete and ready for merge, ALWAYS invoke @quality subagent to handle testing, building, and complete PR management including URL provision.',
             },
             backend: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.3,
               top_p: 0.9,
               mode: 'primary',
@@ -1240,8 +1294,9 @@ All agents follow these principles:
               prompt:
                 'You are Berget Code Backend agent. Voice: Scandinavian calm—precise, concise, confident. TypeScript + Koa. Prefer many small pure functions; avoid big try/catch blocks. Routes thin; logic in services/adapters/domain. Validate with Zod; auto-generate OpenAPI. Adapters isolate external systems; domain never depends on framework. Test with supertest; idempotent and stateless by default. Each microservice emits an OpenAPI contract; changes propagate upward to types. Code Quality & Refactoring Principles: Apply Single Responsibility Principle, fail fast with explicit errors, eliminate code duplication, remove nested complexity, use descriptive error codes, keep functions under 30 lines. Always leave code cleaner and more readable than you found it. CRITICAL: When all backend implementation tasks are complete and ready for merge, ALWAYS invoke @quality subagent to handle testing, building, and complete PR management including URL provision.',
             },
-            devops: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+            // Use centralized devops configuration with Helm guidelines
+            devops: latestAgentConfig.devops || {
+              model: modelConfig.primary,
               temperature: 0.3,
               top_p: 0.8,
               mode: 'primary',
@@ -1252,7 +1307,7 @@ All agents follow these principles:
                 'You are Berget Code DevOps agent. Voice: Scandinavian calm—precise, concise, confident. Start simple: k8s/{deployment,service,ingress}. Add FluxCD sync to repo and image automation. Use Kustomize bases/overlays (staging, production). Add dependencies via Helm from upstream sources; prefer native operators when available (CloudNativePG, cert-manager, external-dns). SemVer with -rc tags keeps CI environments current. Observability with Prometheus/Grafana. No manual kubectl in production—Git is the source of truth. For testing, building, and PR management, use @quality subagent.',
             },
             app: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.4,
               top_p: 0.9,
               mode: 'primary',
@@ -1264,7 +1319,7 @@ All agents follow these principles:
                 'You are Berget Code App agent. Voice: Scandinavian calm—precise, concise, confident. Expo + React Native + TypeScript. Structure by components/hooks/services/navigation. Components are pure; data via props; refactor shared logic into hooks/stores. Share tokens with frontend. Mock data in /data via typed hooks; later replace with live APIs. Offline via SQLite/MMKV; notifications via Expo. Request permissions only when needed. Subtle, meaningful motion; light/dark parity. For testing, building, and PR management, use @quality subagent.',
             },
             security: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.2,
               top_p: 0.8,
               mode: 'subagent',
@@ -1275,7 +1330,7 @@ All agents follow these principles:
                 'Voice: Scandinavian calm—precise, concise, confident. You are Berget Code Security agent. Expert in application security, penetration testing, and OWASP standards. Core responsibilities: Conduct security assessments and penetration tests, Validate OWASP Top 10 compliance, Review code for security vulnerabilities, Implement security headers and Content Security Policy (CSP), Audit API security, Check for sensitive data exposure, Validate input sanitization and output encoding, Assess dependency security and supply chain risks. Tools and techniques: OWASP ZAP, Burp Suite, security linters, dependency scanners, manual code review. Always provide specific, actionable security recommendations with priority levels. Workflow: Always follow branch_strategy and commit_convention from workflow section. Never work directly in main. Agent awareness: Review code from all personas (frontend, backend, app, devops). If implementation changes are needed, suggest <tab> to switch to appropriate persona after security assessment.',
             },
             quality: {
-              model: MODEL_CONFIG.AGENT_MODELS.primary,
+              model: modelConfig.primary,
               temperature: 0.1,
               top_p: 0.9,
               mode: 'subagent',
@@ -1343,7 +1398,7 @@ All agents follow these principles:
                 baseURL: 'https://api.berget.ai/v1',
                 apiKey: '{env:BERGET_API_KEY}',
               },
-              models: MODEL_CONFIG.PROVIDER_MODELS,
+              models: getProviderModels(),
             },
           },
         }
@@ -1389,7 +1444,7 @@ All agents follow these principles:
 
           // Check for GLM-4.6 optimizations
           if (
-            !currentConfig.provider?.berget?.models?.[MODEL_CONFIG.AGENT_MODELS.primary.replace('berget/', '')]?.limit?.context
+            !currentConfig.provider?.berget?.models?.[modelConfig.primary.replace('berget/', '')]?.limit?.context
           ) {
             console.log(
               chalk.cyan('  • GLM-4.6 token limits and auto-compaction'),
@@ -1556,6 +1611,12 @@ Declarative GitOps infrastructure with FluxCD, Kustomize, Helm, and operators.
 - Operator-first approach
 - SemVer with release candidates
 
+**Helm Values Configuration Process:**
+1. Documentation First Approach: Always fetch official documentation from Artifact Hub/GitHub for the specific chart version before writing values. Search Artifact Hub for exact chart version documentation, check the chart's GitHub repository for official docs and examples, verify the exact version being used in the deployment.
+2. Validation Requirements: Check for available validation schemas before committing YAML files. Use Helm's built-in validation tools (helm lint, helm template). Validate against JSON schema if available for the chart. Ensure YAML syntax correctness with linters.
+3. Standard Workflow: Identify chart name and exact version. Fetch official documentation from Artifact Hub/GitHub. Check for available schemas and validation tools. Write values according to official documentation. Validate against schema (if available). Test with helm template or helm lint. Commit validated YAML files.
+4. Quality Assurance: Never commit unvalidated Helm values. Use helm dependency update when adding new charts. Test rendering with helm template --dry-run before deployment. Document any custom values with comments referencing official docs.
+
 #### app
 Expo + React Native applications with props-first architecture and offline awareness.
 

package/src/constants/command-structure.ts

@@ -39,6 +39,7 @@ export const SUBCOMMANDS = {
     INIT: 'init',
     RUN: 'run',
     UPDATE: 'update',
+    SERVE: 'serve',
   },
 
   // API Keys commands
@@ -233,6 +234,7 @@ export const COMMAND_DESCRIPTIONS = {
   [`${COMMAND_GROUPS.CODE} ${SUBCOMMANDS.CODE.INIT}`]:
     'Initialize project for AI coding assistant',
   [`${COMMAND_GROUPS.CODE} ${SUBCOMMANDS.CODE.RUN}`]: 'Run AI coding assistant',
+  [`${COMMAND_GROUPS.CODE} ${SUBCOMMANDS.CODE.SERVE}`]: 'Start OpenCode web server',
   [`${COMMAND_GROUPS.CODE} ${SUBCOMMANDS.CODE.UPDATE}`]:
     'Update OpenCode and agents to latest versions',
 }

package/src/services/api-key-service.ts

@@ -70,13 +70,111 @@ export class ApiKeyService {
    */
   public async create(options: CreateApiKeyOptions): Promise<ApiKeyResponse> {
     try {
+      // Validate input before sending request
+      if (!options.name || options.name.trim().length === 0) {
+        throw new Error('API key name is required and cannot be empty')
+      }
+
+      if (options.name.length > 100) {
+        throw new Error('API key name must be 100 characters or less')
+      }
+
+      if (options.description && options.description.length > 500) {
+        throw new Error('API key description must be 500 characters or less')
+      }
+
       const { data, error } = await this.client.POST('/v1/api-keys', {
         body: options,
       })
-      if (error) throw new Error(JSON.stringify(error))
-      return data!
+
+      if (error) {
+        // Enhanced error handling with specific troubleshooting
+
+        // Handle specific error cases
+        if (typeof error === 'object' && error !== null) {
+          const errorObj = error as any
+
+          if (errorObj.error?.code === 'API_KEY_CREATION_FAILED') {
+            let detailedMessage =
+              'Failed to create API key. This could be due to:\n'
+            detailedMessage += '• Account limits or quota restrictions\n'
+            detailedMessage +=
+              '• Insufficient permissions for API key creation\n'
+            detailedMessage += '• Temporary server issues\n'
+            detailedMessage += '• Billing or subscription issues\n\n'
+            detailedMessage += 'Troubleshooting steps:\n'
+            detailedMessage +=
+              '1. Check if you have reached your API key limit\n'
+            detailedMessage +=
+              '2. Verify your account has API key creation permissions\n'
+            detailedMessage += '3. Check your billing status and subscription\n'
+            detailedMessage +=
+              '4. Try again in a few minutes if this is a temporary issue\n'
+            detailedMessage += '5. Contact support if the problem persists'
+
+            throw new Error(detailedMessage)
+          }
+
+          if (errorObj.error?.code === 'QUOTA_EXCEEDED') {
+            throw new Error(
+              'You have reached your API key limit. Please delete existing keys or contact support to increase your quota.',
+            )
+          }
+
+          if (errorObj.error?.code === 'INSUFFICIENT_PERMISSIONS') {
+            throw new Error(
+              'Your account does not have permission to create API keys. Please contact your administrator.',
+            )
+          }
+
+          if (errorObj.error?.code === 'BILLING_REQUIRED') {
+            throw new Error(
+              'A valid billing method is required to create API keys. Please add a payment method.',
+            )
+          }
+        }
+
+        throw new Error(JSON.stringify(error))
+      }
+
+      if (!data) {
+        throw new Error('No data received from server')
+      }
+
+      return data
     } catch (error) {
       console.error('Failed to create API key:', error)
+
+      // Add additional context for common issues
+      if (error instanceof Error) {
+        if (error.message.includes('ECONNREFUSED')) {
+          throw new Error(
+            'Cannot connect to Berget API. Please check your internet connection.',
+          )
+        }
+
+        if (error.message.includes('ENOTFOUND')) {
+          throw new Error(
+            'Cannot resolve Berget API hostname. Please check your DNS settings.',
+          )
+        }
+
+        if (
+          error.message.includes('401') ||
+          error.message.includes('Unauthorized')
+        ) {
+          throw new Error(
+            'Authentication failed. Please run `berget auth login` to log in again.',
+          )
+        }
+
+        if (error.message.includes('403')) {
+          throw new Error(
+            'Access forbidden. Your account may not have permission to create API keys.',
+          )
+        }
+      }
+
       throw error
     }
   }