# Story 5.1: Multi-Instance Configuration System

**Epic:** Epic 5 - Multi-Instance Architecture
**Story Points:** 8
**Priority:** High
**Status:** Completed
**Estimated Page Count:** 14-18 pages

---

## User Story

**As a** developer managing multiple n8n environments (production, staging, development)
**I want** a unified configuration system that supports multiple instances
**So that** I can manage different n8n environments from a single MCP server installation

---

## Story Description

### Current System

The n8n MCP server originally supported single-instance configuration through `.env` files:

```bash
N8N_HOST=https://n8n.example.com
N8N_API_KEY=your_api_key_here
```

**Limitations:**
- Only one n8n instance per MCP server installation
- No environment separation (production vs staging vs development)
- Requires multiple MCP server installations for multiple instances
- Configuration changes require server restart
- No default environment concept

### Enhancement

Implement multi-instance configuration system that:
- Supports multiple named environments in single `.config.json` file
- Maintains backward compatibility with `.env` single-instance setup
- Provides default environment fallback
- Enables instance-specific routing for all MCP tools
- Validates configuration on server startup
- Supports environment-specific API key management

**Configuration Priority:**
1. `.config.json` (multi-instance) - Primary
2. `.env` (single-instance) - Fallback for backward compatibility

### Context from Previous Epics

**Epic 1 (URL Configuration):**
- URL normalization applies to all instances in multi-instance setup
- Each instance validates `/api/v1/` suffix removal independently

**Epic 2 (API Implementation):**
- All 23 API methods support optional `instance` parameter
- Performance optimizations apply per-instance

**Epic 4 (Tools Reference):**
- All 17 MCP tools document multi-instance usage patterns
- Resources support `?instance=name` query parameter

---

## Acceptance Criteria

### AC1: Multi-Instance Configuration File Format
**Given** a developer with multiple n8n environments
**When** they create a `.config.json` file
**Then** they should use this structure:

#### 1.1 Configuration Schema

**File:** `.config.json` (root directory)

```json
{
  "environments": {
    "production": {
      "n8n_host": "https://prod.app.n8n.cloud",
      "n8n_api_key": "n8n_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "staging": {
      "n8n_host": "https://staging.app.n8n.cloud",
      "n8n_api_key": "n8n_api_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
    },
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "n8n_api_zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"
    }
  },
  "defaultEnv": "staging"
}
```

**TypeScript Interface:**
```typescript
interface EnvironmentConfig {
  n8n_host: string;
  n8n_api_key: string;
}

interface MultiInstanceConfig {
  environments: {
    [key: string]: EnvironmentConfig;
  };
  defaultEnv: string;
}
```

#### 1.2 Configuration Rules

**Environment Names:**
- **Allowed Characters:** Alphanumeric, hyphens, underscores (`[a-zA-Z0-9_-]+`)
- **Case Sensitive:** Yes (`Production` ≠ `production`)
- **Reserved Names:** None (any string allowed)
- **Examples:** `production`, `prod`, `staging-us-east`, `dev_local`, `test-123`

**Environment Fields:**
- `n8n_host` (required): Base n8n instance URL without `/api/v1/` suffix
- `n8n_api_key` (required): n8n API key for the instance
- **Validation:** Both fields must be non-empty strings

**Default Environment:**
- `defaultEnv` (required): Must match one of the environment names
- Used when no `instance` parameter provided in tool calls
- **Best Practice:** Set to safest environment (e.g., `staging` or `development`)

**Example with Comments:**
```jsonc
{
  "environments": {
    // Production - US Region
    "production-us": {
      "n8n_host": "https://us-prod.n8n.cloud",
      "n8n_api_key": "n8n_api_prod_us_key"
    },

    // Production - EU Region
    "production-eu": {
      "n8n_host": "https://eu-prod.n8n.cloud",
      "n8n_api_key": "n8n_api_prod_eu_key"
    },

    // Staging Environment
    "staging": {
      "n8n_host": "https://staging.n8n.cloud",
      "n8n_api_key": "n8n_api_staging_key"
    },

    // Local Development
    "local": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "n8n_api_local_key"
    }
  },

  // Default to staging for safety
  "defaultEnv": "staging"
}
```

#### 1.3 Validation Requirements

**Startup Validation:**
```typescript
class ConfigValidator {
  static validate(config: MultiInstanceConfig): void {
    // 1. Validate structure
    if (!config.environments || typeof config.environments !== 'object') {
      throw new Error('Configuration must have "environments" object');
    }

    if (!config.defaultEnv || typeof config.defaultEnv !== 'string') {
      throw new Error('Configuration must have "defaultEnv" string');
    }

    // 2. Validate at least one environment
    const envNames = Object.keys(config.environments);
    if (envNames.length === 0) {
      throw new Error('Configuration must have at least one environment');
    }

    // 3. Validate default environment exists
    if (!config.environments[config.defaultEnv]) {
      throw new Error(
        `Default environment "${config.defaultEnv}" not found in environments. ` +
        `Available: ${envNames.join(', ')}`
      );
    }

    // 4. Validate each environment
    for (const [name, env] of Object.entries(config.environments)) {
      // Check required fields
      if (!env.n8n_host) {
        throw new Error(`Environment "${name}" missing required field: n8n_host`);
      }
      if (!env.n8n_api_key) {
        throw new Error(`Environment "${name}" missing required field: n8n_api_key`);
      }

      // Validate URL format (from Epic 1)
      if (env.n8n_host.includes('/api/v1')) {
        throw new Error(
          `Environment "${name}": n8n_host must not include /api/v1 suffix. ` +
          `Use base URL only (e.g., https://n8n.example.com)`
        );
      }

      if (!env.n8n_host.startsWith('http://') && !env.n8n_host.startsWith('https://')) {
        throw new Error(
          `Environment "${name}": n8n_host must include protocol (http:// or https://)`
        );
      }

      // Warn about localhost in production default
      if (config.defaultEnv === name && env.n8n_host.includes('localhost')) {
        console.warn(
          `⚠️  Default environment "${name}" uses localhost. ` +
          `Consider using staging/development as default.`
        );
      }
    }

    console.log(`✅ Configuration validated: ${envNames.length} environments`);
    console.log(`   Default: ${config.defaultEnv}`);
    console.log(`   Available: ${envNames.join(', ')}`);
  }
}
```

### AC2: Backward Compatibility with .env
**Given** an existing single-instance `.env` configuration
**When** the server starts without `.config.json`
**Then** it should fall back to `.env` format:

#### 2.1 .env Format Support

**File:** `.env` (root directory)

```bash
N8N_HOST=https://n8n.example.com
N8N_API_KEY=n8n_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Priority Logic:**
```typescript
class ConfigLoader {
  static load(): MultiInstanceConfig | SingleInstanceConfig {
    // Priority 1: Check for .config.json
    if (fs.existsSync('.config.json')) {
      console.log('Loading multi-instance configuration from .config.json');
      const config = JSON.parse(fs.readFileSync('.config.json', 'utf-8'));
      ConfigValidator.validate(config);
      return config;
    }

    // Priority 2: Check for .env
    if (fs.existsSync('.env')) {
      console.log('Loading single-instance configuration from .env');
      return this.loadEnvFile();
    }

    throw new Error(
      'No configuration found. Please create .config.json or .env file. ' +
      'See documentation for setup instructions.'
    );
  }

  private static loadEnvFile(): SingleInstanceConfig {
    const dotenv = require('dotenv');
    dotenv.config();

    const n8n_host = process.env.N8N_HOST;
    const n8n_api_key = process.env.N8N_API_KEY;

    if (!n8n_host || !n8n_api_key) {
      throw new Error(
        'Invalid .env configuration. Required: N8N_HOST, N8N_API_KEY'
      );
    }

    // Validate URL format (Epic 1)
    if (n8n_host.includes('/api/v1')) {
      throw new Error(
        'N8N_HOST must not include /api/v1 suffix. Use base URL only.'
      );
    }

    return {
      type: 'single-instance',
      n8n_host,
      n8n_api_key
    };
  }
}
```

#### 2.2 Migration Guide

**From .env to .config.json:**
```bash
# Current .env file
N8N_HOST=https://n8n.example.com
N8N_API_KEY=n8n_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Convert to .config.json
cat > .config.json << 'EOF'
{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "n8n_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "defaultEnv": "production"
}
EOF

# Remove .env file (optional, but recommended)
rm .env
```

**Migration Script:**
```typescript
// migrate-to-multi-instance.ts
import * as fs from 'fs';
import * as dotenv from 'dotenv';

function migrateToMultiInstance(): void {
  // Check for .env
  if (!fs.existsSync('.env')) {
    console.error('No .env file found');
    return;
  }

  // Load .env
  dotenv.config();
  const n8n_host = process.env.N8N_HOST;
  const n8n_api_key = process.env.N8N_API_KEY;

  if (!n8n_host || !n8n_api_key) {
    console.error('Invalid .env: missing N8N_HOST or N8N_API_KEY');
    return;
  }

  // Create .config.json
  const config = {
    environments: {
      production: {
        n8n_host,
        n8n_api_key
      }
    },
    defaultEnv: 'production'
  };

  fs.writeFileSync('.config.json', JSON.stringify(config, null, 2));
  console.log('✅ Created .config.json from .env');
  console.log('   You can now add more environments to .config.json');
  console.log('   Consider removing .env file');
}

migrateToMultiInstance();
```

### AC3: Configuration Loading and Caching
**Given** a multi-instance configuration
**When** the server initializes
**Then** it should load and cache configuration:

#### 3.1 ConfigLoader Implementation

**File:** `src/config/configLoader.ts`

```typescript
import * as fs from 'fs';
import * as path from 'path';
import * as dotenv from 'dotenv';

export interface EnvironmentConfig {
  n8n_host: string;
  n8n_api_key: string;
}

export interface MultiInstanceConfig {
  environments: {
    [key: string]: EnvironmentConfig;
  };
  defaultEnv: string;
}

export interface SingleInstanceConfig {
  type: 'single-instance';
  n8n_host: string;
  n8n_api_key: string;
}

export type Config = MultiInstanceConfig | SingleInstanceConfig;

export class ConfigLoader {
  private static instance: ConfigLoader;
  private config: Config;

  private constructor() {
    this.config = this.loadConfiguration();
  }

  public static getInstance(): ConfigLoader {
    if (!ConfigLoader.instance) {
      ConfigLoader.instance = new ConfigLoader();
    }
    return ConfigLoader.instance;
  }

  private loadConfiguration(): Config {
    const configPath = path.join(process.cwd(), '.config.json');
    const envPath = path.join(process.cwd(), '.env');

    // Priority 1: .config.json
    if (fs.existsSync(configPath)) {
      return this.loadMultiInstanceConfig(configPath);
    }

    // Priority 2: .env
    if (fs.existsSync(envPath)) {
      return this.loadSingleInstanceConfig(envPath);
    }

    throw new Error(
      'No configuration found. Please create one of:\n' +
      '  1. .config.json (multi-instance, recommended)\n' +
      '  2. .env (single-instance, backward compatibility)\n\n' +
      'See documentation: https://github.com/your-org/mcp-n8n-workflow-builder#configuration'
    );
  }

  private loadMultiInstanceConfig(configPath: string): MultiInstanceConfig {
    try {
      const rawConfig = fs.readFileSync(configPath, 'utf-8');
      const config = JSON.parse(rawConfig) as MultiInstanceConfig;

      // Validate configuration
      this.validateMultiInstanceConfig(config);

      console.error('[ConfigLoader] Multi-instance configuration loaded');
      console.error(`  Environments: ${Object.keys(config.environments).join(', ')}`);
      console.error(`  Default: ${config.defaultEnv}`);

      return config;
    } catch (error) {
      throw new Error(
        `Failed to load .config.json: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

  private loadSingleInstanceConfig(envPath: string): SingleInstanceConfig {
    dotenv.config({ path: envPath });

    const n8n_host = process.env.N8N_HOST;
    const n8n_api_key = process.env.N8N_API_KEY;

    if (!n8n_host || !n8n_api_key) {
      throw new Error(
        'Invalid .env configuration. Required variables:\n' +
        '  - N8N_HOST\n' +
        '  - N8N_API_KEY'
      );
    }

    // Validate URL (Epic 1)
    if (n8n_host.endsWith('/api/v1/') || n8n_host.endsWith('/api/v1')) {
      throw new Error(
        'N8N_HOST must not include /api/v1 suffix.\n' +
        'Use base URL only (e.g., https://n8n.example.com)'
      );
    }

    console.error('[ConfigLoader] Single-instance configuration loaded (.env)');
    console.error(`  Host: ${n8n_host}`);

    return {
      type: 'single-instance',
      n8n_host,
      n8n_api_key
    };
  }

  private validateMultiInstanceConfig(config: MultiInstanceConfig): void {
    // Validate structure
    if (!config.environments || typeof config.environments !== 'object') {
      throw new Error('Configuration must have "environments" object');
    }

    if (!config.defaultEnv || typeof config.defaultEnv !== 'string') {
      throw new Error('Configuration must have "defaultEnv" string');
    }

    // Validate at least one environment
    const envNames = Object.keys(config.environments);
    if (envNames.length === 0) {
      throw new Error('Configuration must have at least one environment');
    }

    // Validate default environment exists
    if (!config.environments[config.defaultEnv]) {
      throw new Error(
        `Default environment "${config.defaultEnv}" not found. ` +
        `Available: ${envNames.join(', ')}`
      );
    }

    // Validate each environment
    for (const [name, env] of Object.entries(config.environments)) {
      if (!env.n8n_host) {
        throw new Error(`Environment "${name}" missing: n8n_host`);
      }
      if (!env.n8n_api_key) {
        throw new Error(`Environment "${name}" missing: n8n_api_key`);
      }

      // Validate URL format (Epic 1)
      if (env.n8n_host.includes('/api/v1')) {
        throw new Error(
          `Environment "${name}": Remove /api/v1 from n8n_host. ` +
          `Use base URL only.`
        );
      }

      if (!env.n8n_host.startsWith('http://') && !env.n8n_host.startsWith('https://')) {
        throw new Error(
          `Environment "${name}": n8n_host must include protocol ` +
          `(http:// or https://)`
        );
      }
    }
  }

  public getConfig(): Config {
    return this.config;
  }

  public isMultiInstance(): boolean {
    return 'environments' in this.config;
  }

  public listEnvironments(): string[] {
    if (this.isMultiInstance()) {
      return Object.keys((this.config as MultiInstanceConfig).environments);
    }
    return ['default'];
  }

  public getDefaultEnvironment(): string {
    if (this.isMultiInstance()) {
      return (this.config as MultiInstanceConfig).defaultEnv;
    }
    return 'default';
  }

  public getEnvironmentConfig(name?: string): EnvironmentConfig {
    if (!this.isMultiInstance()) {
      const singleConfig = this.config as SingleInstanceConfig;
      return {
        n8n_host: singleConfig.n8n_host,
        n8n_api_key: singleConfig.n8n_api_key
      };
    }

    const multiConfig = this.config as MultiInstanceConfig;
    const envName = name || multiConfig.defaultEnv;

    if (!multiConfig.environments[envName]) {
      throw new Error(
        `Instance "${envName}" not found. ` +
        `Available: ${Object.keys(multiConfig.environments).join(', ')}`
      );
    }

    return multiConfig.environments[envName];
  }
}
```

#### 3.2 Singleton Pattern

**Purpose:** Single source of truth for configuration across entire application

**Benefits:**
- Configuration loaded once on startup
- Consistent configuration access
- Memory efficient (single instance)
- Thread-safe configuration reads

**Usage Pattern:**
```typescript
// Anywhere in the application
import { ConfigLoader } from './config/configLoader';

const loader = ConfigLoader.getInstance(); // Always same instance

// Check configuration type
if (loader.isMultiInstance()) {
  console.log('Running in multi-instance mode');
  console.log('Environments:', loader.listEnvironments());
}

// Get environment configuration
const prodConfig = loader.getEnvironmentConfig('production');
console.log('Production host:', prodConfig.n8n_host);

// Get default environment
const defaultEnv = loader.getDefaultEnvironment();
const defaultConfig = loader.getEnvironmentConfig(); // Uses default
```

### AC4: Environment Variable Override Support
**Given** a deployment scenario requiring environment variable overrides
**When** environment variables are set
**Then** they should override `.config.json` values:

#### 4.1 Override Pattern

**Priority (Highest to Lowest):**
1. Environment variables (runtime override)
2. `.config.json` (multi-instance configuration)
3. `.env` (single-instance fallback)

**Environment Variable Format:**
```bash
# Override specific environment
N8N_PRODUCTION_HOST=https://prod-override.n8n.cloud
N8N_PRODUCTION_API_KEY=override_key_here

# Override staging
N8N_STAGING_HOST=https://staging-override.n8n.cloud
N8N_STAGING_API_KEY=staging_override_key

# Override default environment
N8N_DEFAULT_ENV=staging
```

**Implementation:**
```typescript
private loadMultiInstanceConfig(configPath: string): MultiInstanceConfig {
  const rawConfig = fs.readFileSync(configPath, 'utf-8');
  const config = JSON.parse(rawConfig) as MultiInstanceConfig;

  // Apply environment variable overrides
  for (const envName of Object.keys(config.environments)) {
    const hostVar = `N8N_${envName.toUpperCase().replace(/-/g, '_')}_HOST`;
    const keyVar = `N8N_${envName.toUpperCase().replace(/-/g, '_')}_API_KEY`;

    if (process.env[hostVar]) {
      console.error(`  Override: ${envName}.n8n_host from ${hostVar}`);
      config.environments[envName].n8n_host = process.env[hostVar]!;
    }

    if (process.env[keyVar]) {
      console.error(`  Override: ${envName}.n8n_api_key from ${keyVar}`);
      config.environments[envName].n8n_api_key = process.env[keyVar]!;
    }
  }

  // Override default environment
  if (process.env.N8N_DEFAULT_ENV) {
    console.error(`  Override: defaultEnv from N8N_DEFAULT_ENV`);
    config.defaultEnv = process.env.N8N_DEFAULT_ENV;
  }

  this.validateMultiInstanceConfig(config);
  return config;
}
```

**Use Case - Docker Deployment:**
```yaml
# docker-compose.yml
services:
  mcp-n8n:
    image: mcp-n8n-workflow-builder
    environment:
      # Override production to use Docker network
      - N8N_PRODUCTION_HOST=http://n8n-prod:5678
      - N8N_PRODUCTION_API_KEY=${PROD_API_KEY}

      # Override staging
      - N8N_STAGING_HOST=http://n8n-staging:5678
      - N8N_STAGING_API_KEY=${STAGING_API_KEY}

      # Set default to staging in Docker
      - N8N_DEFAULT_ENV=staging
    volumes:
      - ./config.json:/app/.config.json
```

**Use Case - CI/CD Pipeline:**
```bash
#!/bin/bash
# deploy.sh

# Set environment-specific overrides
export N8N_PRODUCTION_HOST="https://prod.n8n.cloud"
export N8N_PRODUCTION_API_KEY="${PROD_API_KEY_SECRET}"
export N8N_DEFAULT_ENV="production"

# Start MCP server (uses overrides)
npm start
```

### AC5: Configuration Security Best Practices
**Given** sensitive API keys in configuration
**When** setting up multi-instance configuration
**Then** developers should follow security best practices:

#### 5.1 Security Checklist

**✅ DO:**
1. **Keep .config.json out of version control:**
   ```bash
   # .gitignore
   .config.json
   .env
   *.local.json
   ```

2. **Use environment variables for secrets:**
   ```json
   {
     "environments": {
       "production": {
         "n8n_host": "${PROD_HOST}",
         "n8n_api_key": "${PROD_API_KEY}"
       }
     }
   }
   ```

3. **Store secrets in secure vault:**
   - AWS Secrets Manager
   - HashiCorp Vault
   - Azure Key Vault
   - GitHub Secrets (CI/CD)

4. **Use separate API keys per environment:**
   - Each environment has unique API key
   - Easy to rotate keys per environment
   - Limit blast radius if key compromised

5. **Restrict file permissions:**
   ```bash
   # Only owner can read/write
   chmod 600 .config.json
   ```

6. **Template for version control:**
   ```json
   // .config.template.json (safe to commit)
   {
     "environments": {
       "production": {
         "n8n_host": "https://YOUR_PRODUCTION_HOST",
         "n8n_api_key": "YOUR_PRODUCTION_API_KEY"
       },
       "staging": {
         "n8n_host": "https://YOUR_STAGING_HOST",
         "n8n_api_key": "YOUR_STAGING_API_KEY"
       }
     },
     "defaultEnv": "staging"
   }
   ```

**❌ DON'T:**
1. **Commit .config.json with real keys**
2. **Use same API key for all environments**
3. **Store API keys in plain text in CI/CD logs**
4. **Share .config.json files via email/chat**
5. **Use production as default environment**

#### 5.2 Secret Management Pattern

**Using Environment Variables:**
```typescript
// scripts/load-secrets.ts
import * as fs from 'fs';

interface SecretsMap {
  [key: string]: string;
}

function loadSecretsFromVault(): SecretsMap {
  // Example: Load from AWS Secrets Manager
  // const secrets = await secretsManager.getSecretValue(...);

  return {
    PROD_HOST: process.env.PROD_HOST || '',
    PROD_API_KEY: process.env.PROD_API_KEY || '',
    STAGING_HOST: process.env.STAGING_HOST || '',
    STAGING_API_KEY: process.env.STAGING_API_KEY || ''
  };
}

function generateConfigFromSecrets(secrets: SecretsMap): void {
  const config = {
    environments: {
      production: {
        n8n_host: secrets.PROD_HOST,
        n8n_api_key: secrets.PROD_API_KEY
      },
      staging: {
        n8n_host: secrets.STAGING_HOST,
        n8n_api_key: secrets.STAGING_API_KEY
      }
    },
    defaultEnv: 'staging'
  };

  fs.writeFileSync('.config.json', JSON.stringify(config, null, 2));
  console.log('✅ Configuration generated from secrets');
}

// Usage in deployment
const secrets = loadSecretsFromVault();
generateConfigFromSecrets(secrets);
```

**GitHub Actions Example:**
```yaml
# .github/workflows/deploy.yml
name: Deploy MCP Server

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Generate configuration
        env:
          PROD_HOST: ${{ secrets.PROD_N8N_HOST }}
          PROD_API_KEY: ${{ secrets.PROD_N8N_API_KEY }}
          STAGING_HOST: ${{ secrets.STAGING_N8N_HOST }}
          STAGING_API_KEY: ${{ secrets.STAGING_N8N_API_KEY }}
        run: |
          cat > .config.json << EOF
          {
            "environments": {
              "production": {
                "n8n_host": "${PROD_HOST}",
                "n8n_api_key": "${PROD_API_KEY}"
              },
              "staging": {
                "n8n_host": "${STAGING_HOST}",
                "n8n_api_key": "${STAGING_API_KEY}"
              }
            },
            "defaultEnv": "staging"
          }
          EOF

      - name: Deploy
        run: npm run deploy
```

---

## Technical Implementation Notes

### Implementation Files

**Created Files:**
- `src/config/configLoader.ts` - Configuration loading and validation
- `.config.template.json` - Template for developers
- `scripts/migrate-to-multi-instance.ts` - Migration utility

**Modified Files:**
- `src/index.ts` - Use ConfigLoader on startup
- `README.md` - Document multi-instance setup
- `.gitignore` - Add .config.json

### Implementation Sequence

1. **Create ConfigLoader class** with singleton pattern
2. **Implement validation** for multi-instance config
3. **Add backward compatibility** for .env
4. **Add environment variable overrides** support
5. **Create migration script** from .env to .config.json
6. **Update documentation** with examples
7. **Add security guidelines** to README

### Error Handling

**Configuration Errors:**
```typescript
try {
  const loader = ConfigLoader.getInstance();
} catch (error) {
  console.error('Configuration error:', error.message);
  console.error('\nSetup instructions:');
  console.error('  1. Create .config.json (recommended)');
  console.error('  2. Or create .env (single-instance)');
  console.error('  See: https://github.com/.../README.md#configuration');
  process.exit(1);
}
```

**Runtime Validation:**
```typescript
// Validate instance before API call
const loader = ConfigLoader.getInstance();
const instanceName = params.instance || loader.getDefaultEnvironment();

try {
  const config = loader.getEnvironmentConfig(instanceName);
  // Proceed with API call
} catch (error) {
  throw new Error(
    `Invalid instance "${instanceName}". ` +
    `Available: ${loader.listEnvironments().join(', ')}`
  );
}
```

---

## Dependencies

### Upstream Dependencies
- Epic 1 Story 1.1 (URL Configuration) - URL validation logic reused
- None (foundational feature)

### Downstream Dependencies
- **Story 5.2** (EnvironmentManager) - Uses ConfigLoader
- **Story 5.3** (Instance Routing) - Uses environment configuration
- **Story 5.4** (Testing) - Validates multi-instance behavior
- All Epic 4 Stories - Document instance parameter usage

### External Dependencies
```json
{
  "dependencies": {
    "dotenv": "^16.0.0"
  }
}
```

---

## Definition of Done

### Implementation Completeness
- [x] ConfigLoader class implemented with singleton pattern
- [x] Multi-instance .config.json support
- [x] Backward compatibility with .env
- [x] Configuration validation on startup
- [x] Environment variable override support
- [x] Migration script from .env to .config.json

### Documentation
- [x] Configuration format documented
- [x] Migration guide created
- [x] Security best practices documented
- [x] Template file provided (.config.template.json)
- [x] Examples for Docker, CI/CD deployments

### Testing
- [ ] Unit tests for ConfigLoader
- [ ] Validation tests for invalid configurations
- [ ] .env fallback tests
- [ ] Environment variable override tests
- [ ] Migration script tests

### Code Quality
- [x] TypeScript interfaces defined
- [x] Error messages are clear and actionable
- [x] Console logging uses stderr (MCP protocol compliance)
- [x] Singleton pattern correctly implemented

---

## Estimation Breakdown

**Story Points:** 8

**Effort Distribution:**
- ConfigLoader Implementation: 2 SP
- Validation Logic: 1.5 SP
- Backward Compatibility (.env): 1 SP
- Environment Variable Overrides: 1 SP
- Migration Script: 0.5 SP
- Documentation & Examples: 1.5 SP
- Testing: 0.5 SP

**Page Count:** 14-18 pages
- Configuration Format: 2-3 pages
- ConfigLoader Implementation: 3-4 pages
- Validation & Error Handling: 2-3 pages
- Security Best Practices: 2-3 pages
- Migration Guide: 2 pages
- Examples & Use Cases: 3-4 pages

**Estimated Duration:** 4-5 days (1 developer)

---

## Notes

### Success Metrics
- 100% of multi-environment teams adopt .config.json
- Zero configuration errors in production deployments
- 90%+ developers use template for initial setup
- Migration from .env takes <5 minutes

### Common Mistakes to Avoid
- ❌ Including /api/v1/ in n8n_host
- ❌ Committing .config.json to version control
- ❌ Using production as defaultEnv
- ❌ Same API key for all environments
- ❌ Not validating configuration on startup

### Best Practices
- ✅ Use staging/development as defaultEnv
- ✅ Separate API keys per environment
- ✅ Store secrets in environment variables
- ✅ Template file in version control
- ✅ Validate configuration on startup

### Related Documentation
- Epic 1 Story 1.1: URL Configuration (validation patterns)
- Story 5.2: EnvironmentManager (uses ConfigLoader)
- Epic 4 All Stories: Instance parameter usage

---

**Status:** Implemented in version 0.8.0
**Related Files:**
- `src/config/configLoader.ts`
- `.config.template.json`
- `docs/multi-instance-architecture.md`