# Story 5.5: Multi-Instance Documentation & Examples

**Epic:** Epic 5 - Multi-Instance Architecture
**Story Points:** 4
**Priority:** Medium
**Status:** Ready for Implementation
**Estimated Page Count:** 8-10 pages

---

## User Story

**As a** user or developer setting up the n8n MCP server
**I want** comprehensive documentation and practical examples for multi-instance configuration
**So that** I can quickly set up and manage multiple n8n environments with confidence

---

## Story Description

### Current System

With Stories 5.1-5.4 implemented:
- ✅ Multi-instance configuration system functional
- ✅ EnvironmentManager and routing working
- ✅ All tools support instance parameter
- ✅ Testing and validation tools available
- ❌ No centralized user documentation
- ❌ No practical setup examples
- ❌ No troubleshooting guide
- ❌ No best practices documented

### Enhancement

Create comprehensive documentation covering:
- **Quick Start Guide:** Get multi-instance setup running in <10 minutes
- **Configuration Examples:** Production, staging, development setups
- **Deployment Patterns:** Docker, Kubernetes, serverless, local development
- **Migration Guide:** Step-by-step migration from single to multi-instance
- **Troubleshooting:** Common issues and solutions
- **Best Practices:** Security, performance, organization

---

## Acceptance Criteria

### AC1: Quick Start Guide
**Given** a new user wanting multi-instance setup
**When** following the quick start guide
**Then** they should have working configuration in <10 minutes:

#### 1.1 10-Minute Quick Start

**Document:** `docs/quick-start-multi-instance.md`

```markdown
# Multi-Instance Quick Start (10 Minutes)

Get started with multiple n8n environments in under 10 minutes.

## Prerequisites

- Node.js 18+ and npm 7+
- Access to 2+ n8n instances
- n8n API keys for each instance

## Step 1: Install (1 minute)

\`\`\`bash
npm install -g @bmad-labs/mcp-n8n-workflow-builder
\`\`\`

## Step 2: Generate API Keys (2 minutes)

For each n8n instance:

1. Open n8n UI
2. Go to **Settings** → **API**
3. Click **Generate API Key**
4. Copy the key (starts with `n8n_api_...`)

## Step 3: Create Configuration (2 minutes)

Create `.config.json` in your project directory:

\`\`\`json
{
  "environments": {
    "production": {
      "n8n_host": "https://your-prod-instance.app.n8n.cloud",
      "n8n_api_key": "n8n_api_YOUR_PROD_KEY_HERE"
    },
    "staging": {
      "n8n_host": "https://your-staging-instance.app.n8n.cloud",
      "n8n_api_key": "n8n_api_YOUR_STAGING_KEY_HERE"
    }
  },
  "defaultEnv": "staging"
}
\`\`\`

**Important:**
- Use base URL only (no `/api/v1/` suffix)
- Set `defaultEnv` to safest environment (staging/development)
- Keep this file out of version control

## Step 4: Add to .gitignore (1 minute)

\`\`\`bash
echo ".config.json" >> .gitignore
\`\`\`

## Step 5: Validate Configuration (1 minute)

\`\`\`bash
npx @bmad-labs/mcp-n8n-workflow-builder validate
\`\`\`

Expected output:
\`\`\`
✅ Configuration is valid
ℹ️  2 environments configured: production, staging
ℹ️  Default: staging
✓ production: Connected successfully
✓ staging: Connected successfully
\`\`\`

## Step 6: Configure Claude Desktop (3 minutes)

Add to Claude Desktop config:

**macOS/Linux:** `~/.config/claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

\`\`\`json
{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@bmad-labs/mcp-n8n-workflow-builder"]
    }
  }
}
\`\`\`

## Step 7: Restart Claude Desktop

Restart Claude Desktop to load the MCP server.

## Step 8: Test It! (<1 minute)

In Claude Desktop:

\`\`\`
You: "List workflows from staging"

Claude: I'll list workflows from the staging environment.
[Lists staging workflows]

You: "Now list workflows from production"

Claude: I'll list workflows from production.
[Lists production workflows]
\`\`\`

✅ **Done!** You're now managing multiple n8n environments from Claude Desktop.

## Next Steps

- [Configuration Examples](./configuration-examples.md)
- [Deployment Patterns](./deployment-patterns.md)
- [Best Practices](./best-practices.md)
```

### AC2: Configuration Examples
**Given** different deployment scenarios
**When** users need configuration examples
**Then** they should have templates for common setups:

#### 2.1 Configuration Template Library

**Document:** `docs/configuration-examples.md`

```markdown
# Multi-Instance Configuration Examples

## Example 1: Production + Staging

Classic two-environment setup for safe testing before production deployment.

\`\`\`json
{
  "environments": {
    "production": {
      "n8n_host": "https://prod.company.com",
      "n8n_api_key": "n8n_api_prod_xxxxxxxxx"
    },
    "staging": {
      "n8n_host": "https://staging.company.com",
      "n8n_api_key": "n8n_api_staging_xxxxxxxxx"
    }
  },
  "defaultEnv": "staging"
}
\`\`\`

**Use Case:** Test workflows in staging before deploying to production

**Workflow:**
1. Create workflow in staging
2. Test thoroughly
3. Export from staging
4. Import to production
5. Activate in production

---

## Example 2: Multi-Region Production

Different n8n instances per geographic region.

\`\`\`json
{
  "environments": {
    "production-us-east": {
      "n8n_host": "https://us-east.n8n.company.com",
      "n8n_api_key": "n8n_api_us_east_xxxxxxxxx"
    },
    "production-eu-west": {
      "n8n_host": "https://eu-west.n8n.company.com",
      "n8n_api_key": "n8n_api_eu_west_xxxxxxxxx"
    },
    "production-ap-southeast": {
      "n8n_host": "https://ap-southeast.n8n.company.com",
      "n8n_api_key": "n8n_api_ap_southeast_xxxxxxxxx"
    }
  },
  "defaultEnv": "production-us-east"
}
\`\`\`

**Use Case:** Manage region-specific workflows and comply with data residency

---

## Example 3: Development → Staging → Production

Full DTAP (Development, Testing, Acceptance, Production) pipeline.

\`\`\`json
{
  "environments": {
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "n8n_api_dev_local_xxxxxxxxx"
    },
    "testing": {
      "n8n_host": "https://test.company.com",
      "n8n_api_key": "n8n_api_test_xxxxxxxxx"
    },
    "staging": {
      "n8n_host": "https://staging.company.com",
      "n8n_api_key": "n8n_api_staging_xxxxxxxxx"
    },
    "production": {
      "n8n_host": "https://prod.company.com",
      "n8n_api_key": "n8n_api_prod_xxxxxxxxx"
    }
  },
  "defaultEnv": "development"
}
\`\`\`

**Promotion Workflow:**
```
Development → Testing → Staging → Production
   (local)     (auto)    (manual)   (approved)
```

---

## Example 4: Customer-Specific Instances

Separate n8n instance per customer (multi-tenant SaaS).

\`\`\`json
{
  "environments": {
    "customer-acme": {
      "n8n_host": "https://acme.workflows.company.com",
      "n8n_api_key": "n8n_api_acme_xxxxxxxxx"
    },
    "customer-globex": {
      "n8n_host": "https://globex.workflows.company.com",
      "n8n_api_key": "n8n_api_globex_xxxxxxxxx"
    },
    "customer-initech": {
      "n8n_host": "https://initech.workflows.company.com",
      "n8n_api_key": "n8n_api_initech_xxxxxxxxx"
    }
  },
  "defaultEnv": "customer-acme"
}
\`\`\`

**Use Case:** Manage customer-specific workflows and maintain data isolation

---

## Example 5: Environment Variables (Secrets Management)

Configuration with environment variable overrides for CI/CD.

**.config.json (template committed to git):**
\`\`\`json
{
  "environments": {
    "production": {
      "n8n_host": "https://prod.company.com",
      "n8n_api_key": "will_be_overridden_by_env_var"
    },
    "staging": {
      "n8n_host": "https://staging.company.com",
      "n8n_api_key": "will_be_overridden_by_env_var"
    }
  },
  "defaultEnv": "staging"
}
\`\`\`

**Environment Variables (secrets vault):**
\`\`\`bash
export N8N_PRODUCTION_API_KEY="n8n_api_prod_secret_from_vault"
export N8N_STAGING_API_KEY="n8n_api_staging_secret_from_vault"
\`\`\`

**Use Case:** Keep secrets out of configuration files in version control
```

### AC3: Deployment Patterns Documentation
**Given** different deployment environments
**When** users deploy the MCP server
**Then** they should have deployment pattern examples:

#### 3.1 Deployment Patterns Guide

**Document:** `docs/deployment-patterns.md`

```markdown
# Multi-Instance Deployment Patterns

## Pattern 1: Docker Compose

Perfect for local development and small deployments.

**docker-compose.yml:**
\`\`\`yaml
version: '3.8'

services:
  mcp-n8n-server:
    image: node:18
    working_dir: /app
    command: npx @bmad-labs/mcp-n8n-workflow-builder
    environment:
      # Override configuration via environment variables
      N8N_PRODUCTION_HOST: http://n8n-prod:5678
      N8N_PRODUCTION_API_KEY: \${PROD_API_KEY}
      N8N_STAGING_HOST: http://n8n-staging:5678
      N8N_STAGING_API_KEY: \${STAGING_API_KEY}
      N8N_DEFAULT_ENV: staging
    volumes:
      - ./config.json:/app/.config.json:ro
    networks:
      - n8n-network

  n8n-prod:
    image: n8nio/n8n
    environment:
      N8N_PORT: 5678
    networks:
      - n8n-network

  n8n-staging:
    image: n8nio/n8n
    environment:
      N8N_PORT: 5678
    networks:
      - n8n-network

networks:
  n8n-network:
    driver: bridge
\`\`\`

**.env file:**
\`\`\`bash
PROD_API_KEY=n8n_api_prod_xxxxxxxxx
STAGING_API_KEY=n8n_api_staging_xxxxxxxxx
\`\`\`

**Start:**
\`\`\`bash
docker-compose up -d
\`\`\`

---

## Pattern 2: Kubernetes

Production-grade deployment with secrets management.

**configmap.yaml:**
\`\`\`yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: n8n-mcp-config
data:
  config.json: |
    {
      "environments": {
        "production": {
          "n8n_host": "http://n8n-prod-service:5678",
          "n8n_api_key": "placeholder"
        },
        "staging": {
          "n8n_host": "http://n8n-staging-service:5678",
          "n8n_api_key": "placeholder"
        }
      },
      "defaultEnv": "staging"
    }
\`\`\`

**secret.yaml:**
\`\`\`yaml
apiVersion: v1
kind: Secret
metadata:
  name: n8n-api-keys
type: Opaque
stringData:
  prod-key: "n8n_api_prod_xxxxxxxxx"
  staging-key: "n8n_api_staging_xxxxxxxxx"
\`\`\`

**deployment.yaml:**
\`\`\`yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: n8n-mcp-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: n8n-mcp-server
  template:
    metadata:
      labels:
        app: n8n-mcp-server
    spec:
      containers:
      - name: mcp-server
        image: node:18
        command: ["npx", "@bmad-labs/mcp-n8n-workflow-builder"]
        env:
        - name: N8N_PRODUCTION_API_KEY
          valueFrom:
            secretKeyRef:
              name: n8n-api-keys
              key: prod-key
        - name: N8N_STAGING_API_KEY
          valueFrom:
            secretKeyRef:
              name: n8n-api-keys
              key: staging-key
        volumeMounts:
        - name: config
          mountPath: /app/.config.json
          subPath: config.json
      volumes:
      - name: config
        configMap:
          name: n8n-mcp-config
\`\`\`

---

## Pattern 3: AWS Lambda (Serverless)

Serverless deployment with AWS Secrets Manager.

**handler.js:**
\`\`\`javascript
const { SecretsManagerClient, GetSecretValueCommand } = require("@aws-sdk/client-secrets-manager");
const fs = require('fs');

async function loadConfigFromSecrets() {
  const client = new SecretsManagerClient({ region: 'us-east-1' });

  // Load secrets
  const prodSecretResponse = await client.send(
    new GetSecretValueCommand({ SecretId: 'n8n-mcp/production' })
  );
  const stagingSecretResponse = await client.send(
    new GetSecretValueCommand({ SecretId: 'n8n-mcp/staging' })
  );

  const prodSecret = JSON.parse(prodSecretResponse.SecretString);
  const stagingSecret = JSON.parse(stagingSecretResponse.SecretString);

  // Generate config
  const config = {
    environments: {
      production: {
        n8n_host: prodSecret.host,
        n8n_api_key: prodSecret.api_key
      },
      staging: {
        n8n_host: stagingSecret.host,
        n8n_api_key: stagingSecret.api_key
      }
    },
    defaultEnv: 'staging'
  };

  // Write to /tmp (Lambda writeable directory)
  fs.writeFileSync('/tmp/.config.json', JSON.stringify(config));
  process.chdir('/tmp');
}

exports.handler = async (event) => {
  await loadConfigFromSecrets();

  // Start MCP server
  const { startMCPServer } = require('@bmad-labs/mcp-n8n-workflow-builder');
  return await startMCPServer(event);
};
\`\`\`

---

## Pattern 4: Local Development

Simple setup for development with local n8n instance.

**.config.json:**
\`\`\`json
{
  "environments": {
    "local": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "n8n_api_local_dev_key"
    },
    "staging": {
      "n8n_host": "https://staging.company.com",
      "n8n_api_key": "n8n_api_staging_xxxxxxxxx"
    }
  },
  "defaultEnv": "local"
}
\`\`\`

**Start local n8n:**
\`\`\`bash
docker run -it --rm \\
  --name n8n \\
  -p 5678:5678 \\
  -v ~/.n8n:/home/node/.n8n \\
  n8nio/n8n
\`\`\`

**Start MCP server:**
\`\`\`bash
npm start
\`\`\`

---

## Choosing a Deployment Pattern

| Pattern | Best For | Complexity | Scalability |
|---------|----------|------------|-------------|
| Docker Compose | Local dev, small teams | Low | Low |
| Kubernetes | Production, large scale | High | High |
| AWS Lambda | Serverless, event-driven | Medium | Auto |
| Local Development | Testing, experimentation | Very Low | N/A |
```

### AC4: Migration Guide
**Given** existing single-instance users
**When** migrating to multi-instance
**Then** they should have step-by-step migration guide:

#### 4.1 Migration Guide

**Document:** `docs/migration-single-to-multi.md`

```markdown
# Migrating from Single to Multi-Instance

Step-by-step guide to migrate from `.env` to `.config.json` multi-instance setup.

## Prerequisites

- Existing working `.env` configuration
- Backup of current `.env` file
- Access to additional n8n instances (if adding more environments)

## Step 1: Backup Current Configuration (1 minute)

\`\`\`bash
# Backup .env file
cp .env .env.backup

# Verify MCP server works
npm start
# (Ctrl+C to stop after verification)
\`\`\`

## Step 2: Generate .config.json from .env (2 minutes)

**Option A: Automatic Migration Script**

\`\`\`bash
npx @bmad-labs/mcp-n8n-workflow-builder migrate
\`\`\`

This creates `.config.json` from your `.env` file automatically.

**Option B: Manual Migration**

1. Read your `.env` file:
\`\`\`bash
cat .env
# N8N_HOST=https://n8n.example.com
# N8N_API_KEY=n8n_api_xxxxxxxxx
\`\`\`

2. Create `.config.json`:
\`\`\`json
{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "n8n_api_xxxxxxxxx"
    }
  },
  "defaultEnv": "production"
}
\`\`\`

## Step 3: Validate New Configuration (1 minute)

\`\`\`bash
npm run validate-config
\`\`\`

Expected output:
\`\`\`
✅ Configuration is valid
ℹ️  1 environment configured: production
✓ production: Connected successfully
\`\`\`

## Step 4: Test MCP Server (2 minutes)

\`\`\`bash
npm start
\`\`\`

In Claude Desktop, test:
\`\`\`
You: "List workflows"

Claude: I'll list workflows from production (default).
[Should show same workflows as before]
\`\`\`

## Step 5: Add Additional Environments (Optional, 3 minutes)

Add staging or development environments:

\`\`\`json
{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "n8n_api_prod_xxxxxxxxx"
    },
    "staging": {
      "n8n_host": "https://staging.example.com",
      "n8n_api_key": "n8n_api_staging_xxxxxxxxx"
    }
  },
  "defaultEnv": "staging"
}
\`\`\`

## Step 6: Update .gitignore (1 minute)

\`\`\`bash
# Add .config.json to .gitignore
echo ".config.json" >> .gitignore

# Verify
cat .gitignore | grep .config.json
\`\`\`

## Step 7: Remove .env (Optional)

Once `.config.json` works correctly:

\`\`\`bash
# Keep backup
mv .env .env.backup

# Or remove completely
# rm .env
\`\`\`

## Step 8: Update Documentation

Update your team documentation to reference `.config.json` instead of `.env`.

## Rollback (If Needed)

If something goes wrong:

\`\`\`bash
# Restore .env
cp .env.backup .env

# Remove .config.json
rm .config.json

# Restart MCP server
npm start
\`\`\`

## Troubleshooting

**Issue:** Configuration not loading

**Solution:** Ensure `.config.json` has correct JSON syntax:
\`\`\`bash
cat .config.json | json_pp
\`\`\`

**Issue:** API key not working

**Solution:** Verify API key copied correctly from n8n UI

**Issue:** /api/v1 error

**Solution:** Remove `/api/v1` from `n8n_host` in `.config.json`

---

## Migration Checklist

- [ ] Backup `.env` file
- [ ] Create `.config.json` (auto or manual)
- [ ] Validate configuration
- [ ] Test MCP server
- [ ] Add additional environments (optional)
- [ ] Update `.gitignore`
- [ ] Update team documentation
- [ ] Remove old `.env` file
```

### AC5: Troubleshooting Guide
**Given** common multi-instance issues
**When** users encounter problems
**Then** they should have solutions:

#### 5.1 Troubleshooting Guide

**Document:** `docs/troubleshooting-multi-instance.md`

```markdown
# Multi-Instance Troubleshooting Guide

## Issue: Configuration Not Found

**Symptoms:**
\`\`\`
Error: No configuration found. Please create .config.json or .env file
\`\`\`

**Solutions:**

1. **Check file exists:**
\`\`\`bash
ls -la | grep -E '\.config\.json|\.env'
\`\`\`

2. **Check working directory:**
\`\`\`bash
pwd
# Should be project root with .config.json
\`\`\`

3. **Create configuration:**
\`\`\`bash
# Use template
cp .config.template.json .config.json
# Edit with your values
\`\`\`

---

## Issue: Instance Not Found

**Symptoms:**
\`\`\`
Error: Instance "production" not found. Available: staging, development
\`\`\`

**Solutions:**

1. **Check instance name spelling:**
\`\`\`json
// Correct
{ "instance": "production" }

// Incorrect (typo)
{ "instance": "proudction" }
\`\`\`

2. **List available instances:**
\`\`\`bash
npm run validate-config
# Shows: Available instances: production, staging
\`\`\`

3. **Add missing instance to .config.json:**
\`\`\`json
{
  "environments": {
    "production": { ... }  // Add this
  }
}
\`\`\`

---

## Issue: API Connection Failed

**Symptoms:**
\`\`\`
Error: API call failed for instance "production": Request timeout
\`\`\`

**Solutions:**

1. **Test n8n instance directly:**
\`\`\`bash
curl https://your-n8n.com/api/v1/workflows?limit=1 \\
  -H "X-N8N-API-KEY: your_key"
\`\`\`

2. **Check n8n is running:**
- Open n8n UI in browser
- Verify accessible at configured URL

3. **Verify API key:**
- Generate new API key in n8n UI
- Update .config.json with new key

4. **Check network/firewall:**
- VPN required?
- Firewall blocking requests?
- Proxy configuration needed?

---

## Issue: Wrong Instance Used

**Symptoms:**
\`\`\`
Expected production data but got staging data
\`\`\`

**Solutions:**

1. **Check default environment:**
\`\`\`json
{
  "defaultEnv": "staging"  // ← This is used when instance not specified
}
\`\`\`

2. **Explicitly specify instance:**
\`\`\`json
{
  "instance": "production",  // Always specify for clarity
  ...
}
\`\`\`

3. **Verify instance in response:**
Look for instance indicator in MCP responses:
\`\`\`
✅ list_workflows successful
Instance: staging (default)  // ← Shows which instance was used
\`\`\`

---

## Issue: Configuration Validation Errors

**Symptoms:**
\`\`\`
Error: Environment "production" missing: n8n_host
\`\`\`

**Solutions:**

Check for common JSON errors:

\`\`\`json
// ❌ Missing comma
{
  "n8n_host": "https://n8n.com"
  "n8n_api_key": "key"  // Missing comma above!
}

// ✅ Correct
{
  "n8n_host": "https://n8n.com",
  "n8n_api_key": "key"
}

// ❌ Trailing comma
{
  "environments": {
    "production": {...},  // Trailing comma not allowed
  }
}

// ✅ Correct
{
  "environments": {
    "production": {...}  // No trailing comma
  }
}
\`\`\`

**Validate JSON syntax:**
\`\`\`bash
cat .config.json | json_pp
\`\`\`

---

## Issue: /api/v1 URL Error

**Symptoms:**
\`\`\`
Error: n8n_host must not include /api/v1 suffix
\`\`\`

**Solution:**

\`\`\`json
// ❌ Incorrect
{
  "n8n_host": "https://n8n.example.com/api/v1/"
}

// ✅ Correct
{
  "n8n_host": "https://n8n.example.com"
}
\`\`\`

The MCP server automatically appends `/api/v1` internally.

---

## Getting Help

1. **Run validation:**
\`\`\`bash
npm run validate-config
\`\`\`

2. **Check logs:**
MCP server logs to stderr (visible in Claude Desktop developer tools)

3. **Report issue:**
https://github.com/your-org/mcp-n8n-workflow-builder/issues

Include:
- `.config.json` (redact API keys!)
- Error messages
- MCP server version
- n8n version
```

---

## Technical Implementation Notes

### Documentation Structure

```
docs/
├── quick-start-multi-instance.md
├── configuration-examples.md
├── deployment-patterns.md
├── migration-single-to-multi.md
├── troubleshooting-multi-instance.md
└── best-practices-multi-instance.md
```

### Documentation Standards

- **Clarity:** Step-by-step instructions
- **Examples:** Real code, not pseudo-code
- **Completeness:** Cover common scenarios
- **Searchability:** Clear headers and keywords
- **Maintainability:** Version-specific notes

---

## Dependencies

### Upstream Dependencies
- Stories 5.1-5.4 (All multi-instance features)
- Epic 4 (Tools documentation for reference)

### Downstream Dependencies
- Epic 6 (Examples & Tutorials) - Uses these docs as foundation
- Epic 8 (Deployment) - References deployment patterns

---

## Definition of Done

### Documentation Completeness
- [ ] Quick Start Guide (<10 minutes to working setup)
- [ ] 5+ configuration examples for common scenarios
- [ ] 4+ deployment pattern examples
- [ ] Step-by-step migration guide
- [ ] Troubleshooting guide with 10+ common issues

### Quality Standards
- [ ] Technical review by development team
- [ ] User testing with new users (<10 min completion)
- [ ] All code examples tested and verified
- [ ] Screenshots and diagrams where helpful

### Publication
- [ ] Published to GitHub Pages
- [ ] Linked from main README
- [ ] Search engine optimized
- [ ] Version-controlled

---

## Estimation Breakdown

**Story Points:** 4

**Effort Distribution:**
- Quick Start Guide: 0.5 SP
- Configuration Examples: 0.75 SP
- Deployment Patterns: 1 SP
- Migration Guide: 0.75 SP
- Troubleshooting Guide: 1 SP

**Page Count:** 8-10 pages

**Estimated Duration:** 2 days (1 technical writer or developer)

---

## Notes

### Success Metrics
- 90%+ users complete quick start in <10 minutes
- 80%+ find solutions in troubleshooting guide
- Migration guide used successfully by 95%+ users
- Deployment pattern examples work without modification

### Best Practices
- ✅ Test all examples before publishing
- ✅ Keep documentation version-specific
- ✅ Include troubleshooting for every feature
- ✅ Provide copy-paste-ready examples
- ✅ Link related documentation sections

---

**Status:** Ready for Implementation
**Related Files:**
- `docs/quick-start-multi-instance.md`
- `docs/configuration-examples.md`
- `docs/deployment-patterns.md`
- `docs/migration-single-to-multi.md`
- `docs/troubleshooting-multi-instance.md`