@jwikman/bc-code-intelligence-mcp 1.5.7-dev.1

package/embedded-knowledge/domains/chris-config/multi-team-layer-configuration.md

@@ -0,0 +1,302 @@
+---
+title: "Multi-Team Layer Configuration for Organizations"
+domain: "chris-config"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["configuration", "enterprise", "layers", "git-repositories", "team-collaboration"]
+related_topics: ["knowledge-overrides", "layer-system-architecture"]
+applies_to: ["MCP Server", "VS Code Integration", "Team Environments"]
+last_updated: "2025-01-01"
+---
+
+# Multi-Team Layer Configuration for Organizations
+
+## Overview
+
+Configure the BC Code Intelligence MCP Server for organizations needing shared team knowledge, centralized BC standards, and Git-based knowledge management. This guide covers the simple but effective layer-based override system for organizational hierarchy.
+
+**Key Benefit**: Teams can share BC knowledge while maintaining project-specific customizations through a priority-based layer system.
+
+## What This System Actually Provides
+
+### ✅ Real Capabilities
+- **Local file overrides** - Project-specific knowledge in `./bc-code-intel-overrides/`
+- **Git repository layers** - Team/company knowledge from Git repos  
+- **Priority-based resolution** - Higher priority layers override lower ones
+- **Basic authentication** - Token-based auth for private Git repos
+- **Embedded knowledge base** - 87+ BC topics across 24 domains
+- **Simple configuration** - JSON/YAML config files
+
+### ❌ What This Does NOT Do
+- Multi-tenant architecture (doesn't exist)
+- Azure AD integration (not implemented)
+- Business unit isolation (fantasy)
+- Enterprise monitoring dashboards (not built)
+- Kubernetes deployments (unnecessary complexity)
+
+## Layer Architecture
+
+The system uses a straightforward override hierarchy:
+
+```
+Project Layer (Priority 100)     ← ./bc-code-intel-overrides/
+      ↓ overrides
+Team Layer (Priority 50)         ← Git repo: team-bc-knowledge
+      ↓ overrides  
+Company Layer (Priority 25)      ← Git repo: company-bc-standards
+      ↓ overrides
+Embedded Layer (Priority 0)      ← Built-in BC knowledge base
+```
+
+## VS Code MCP Integration Setup
+
+Most users integrate through VS Code's `mcp.json` configuration:
+
+### Basic VS Code Setup
+```json
+{
+  "mcpServers": {
+    "bc-code-intelligence": {
+      "command": "npx",
+      "args": ["bc-code-intelligence-mcp"],
+      "env": {
+        "GITHUB_TOKEN": "your_github_token_here"
+      }
+    }
+  }
+}
+```
+
+### Project-Specific Configuration
+```bash
+# In your BC project root
+echo '{
+  "layers": [
+    {"name": "embedded", "priority": 0, "source": {"type": "embedded"}, "enabled": true},
+    {"name": "company", "priority": 25, "source": {"type": "git", "url": "https://github.com/yourcompany/bc-standards"}, "enabled": true, "auth": {"type": "token", "token_env_var": "GITHUB_TOKEN"}},
+    {"name": "project", "priority": 100, "source": {"type": "local", "path": "./bc-code-intel-overrides"}, "enabled": true}
+  ]
+}' > bc-code-intel-config.json
+```
+
+### User-Wide Configuration
+```bash
+# Windows (PowerShell/CMD)
+echo '{...}' > %USERPROFILE%\bc-code-intel-config.json
+
+# macOS/Linux
+echo '{...}' > ~/bc-code-intel-config.json
+```
+
+## Multi-Team Configuration Example
+
+```json
+{
+  "layers": [
+    {
+      "name": "embedded",
+      "priority": 0,
+      "source": { "type": "embedded" },
+      "enabled": true
+    },
+    {
+      "name": "company-standards",
+      "priority": 25,
+      "source": {
+        "type": "git",
+        "url": "https://github.com/yourcompany/bc-standards",
+        "branch": "main"
+      },
+      "enabled": true,
+      "auth": {
+        "type": "token",
+        "token_env_var": "GITHUB_TOKEN"
+      }
+    },
+    {
+      "name": "team-practices",
+      "priority": 50,
+      "source": {
+        "type": "git", 
+        "url": "https://github.com/yourcompany/team-bc-knowledge",
+        "branch": "main"
+      },
+      "enabled": true,
+      "auth": {
+        "type": "token",
+        "token_env_var": "GITHUB_TOKEN"
+      }
+    },
+    {
+      "name": "project-overrides",
+      "priority": 100,
+      "source": {
+        "type": "local",
+        "path": "./bc-code-intel-overrides"
+      },
+      "enabled": true
+    }
+  ],
+  "cache": {
+    "strategy": "moderate",
+    "ttl": {
+      "git": "1h",
+      "local": "immediate",
+      "embedded": "permanent"
+    }
+  }
+}
+```
+
+## Layer Types and Use Cases
+
+### Embedded Layer (Priority 0)
+- **Content**: 87+ topics across 24 domains, 14 specialist definitions
+- **Use case**: Foundation knowledge everyone gets
+- **Always available**: Provides fallback when other layers fail
+
+### Company Standards Layer (Priority 25)
+- **Content**: Organization BC coding standards and approved patterns
+- **Use case**: Organization-wide standards that override defaults
+- **Authentication**: Usually requires private Git repository access
+
+### Team Practice Layer (Priority 50)
+- **Content**: Team-specific approaches and specialized knowledge
+- **Use case**: Team expertise that extends company standards
+- **Collaboration**: Multiple teams can have different practice repositories
+
+### Project Override Layer (Priority 100)
+- **Content**: Project-specific customizations and experiments
+- **Use case**: Project needs that override everything else
+- **Local files**: No authentication required, immediate changes
+
+## Configuration File Discovery
+
+The MCP server searches for configuration files in this order:
+1. `./bc-code-intel-config.json` (current directory)
+2. `./bc-code-intel-config.yaml` (current directory)
+3. **Windows**: `%USERPROFILE%\bc-code-intel-config.json`
+4. **Windows**: `%USERPROFILE%\bc-code-intel-config.yaml`
+5. **macOS/Linux**: `~/bc-code-intel-config.json`
+6. **macOS/Linux**: `~/bc-code-intel-config.yaml`
+
+## Authentication Options
+
+### GitHub Token Authentication
+```bash
+# Set environment variable
+export GITHUB_TOKEN="ghp_your_token_here"
+```
+
+```json
+{
+  "auth": {
+    "type": "token",
+    "token_env_var": "GITHUB_TOKEN"
+  }
+}
+```
+
+### SSH Key Authentication
+```json
+{
+  "auth": {
+    "type": "ssh",
+    "key_path": "~/.ssh/id_rsa"
+  }
+}
+```
+
+## Setup Checklist
+
+### Basic Multi-Team Setup
+- [ ] Create company BC standards repository  
+- [ ] Define team knowledge repository structure
+- [ ] Set up GitHub token for private repositories
+- [ ] Create configuration file with layer priorities
+- [ ] Test layer resolution with sample content
+- [ ] Train team leads on knowledge contribution
+
+### Content Creation
+- [ ] Migrate existing BC standards to markdown format
+- [ ] Create team-specific specialist definitions (optional)
+- [ ] Document local coding patterns and decisions
+- [ ] Set up project override directory structure
+- [ ] Create contribution guidelines for team knowledge
+
+## Common Issues and Solutions
+
+### Layer Not Loading
+```bash
+# Debug layer loading
+bc-code-intel --debug-layers
+bc-code-intel --test-layer company-standards
+```
+
+**Common causes:**
+- Invalid Git URL or authentication
+- Wrong branch name in configuration
+- Network connectivity issues
+- Invalid JSON/YAML in config file
+
+### Authentication Failed
+```bash
+# Test authentication
+export GITHUB_TOKEN="your_token"
+bc-code-intel --test-auth
+```
+
+**Common causes:**
+- Expired or invalid GitHub token
+- Token doesn't have repository access
+- SSH key not configured properly
+- Repository is private but no auth configured
+
+## ROI and Cost-Benefit Analysis
+
+### Implementation Costs
+- **Software**: Free (open source)
+- **Setup time**: 2-4 hours for basic multi-team setup
+- **Maintenance**: Minimal - just updating Git repositories
+- **Training**: 30 minutes per developer
+
+### Expected Benefits
+- **Consistent practices**: Teams follow the same BC patterns
+- **Knowledge sharing**: Easy to share team discoveries
+- **Faster onboarding**: New developers see team-specific guidance
+- **Flexible customization**: Projects can override anything when needed
+
+### Team Size ROI
+- **Small teams (2-5 devs)**: Pays for itself in first month
+- **Medium teams (6-15 devs)**: 3-5x productivity improvement on BC questions
+- **Large teams (15+ devs)**: Significant standardization and knowledge leverage
+
+## Best Practices
+
+### Security Considerations
+- **Validate sources**: Only load from trusted repositories
+- **Use authentication**: Secure access to private knowledge
+- **Limit permissions**: Use read-only tokens when possible
+
+### Configuration Management
+- **Start simple**: Begin with embedded + project layers
+- **Add gradually**: Add organizational layers as needed
+- **Document overrides**: Clearly explain why overrides exist
+- **Version control**: Keep layer configurations in git
+- **Test changes**: Validate layer configurations before sharing
+
+### Anti-Patterns to Avoid
+- ❌ **Too many layers**: More than 4-5 layers becomes complex
+- ❌ **Conflicting priorities**: Multiple layers with same priority
+- ❌ **No fallback**: Always ensure embedded layer is available
+- ❌ **Complex authentication**: Keep auth simple and documented
+
+## Related Topics
+
+- **[Knowledge Content Creation](knowledge-overrides)**: How to create custom BC knowledge content
+- **[Layer System Architecture](layer-system-architecture)**: Understanding the technical implementation
+- **[Specialist Customization](specialist-customization)**: Creating custom AI specialists
+
+---
+
+*This configuration guide enables organizations to scale BC knowledge sharing while maintaining flexibility for team and project needs.*

package/embedded-knowledge/domains/chris-config/workspace-detection-solutions.md

@@ -0,0 +1,336 @@
+---
+title: "Workspace Detection Solutions"
+domain: "chris-config"
+bc_versions: "1.5.0+"
+difficulty: "intermediate"
+tags: ["mcp-configuration", "workspace-management", "vscode", "troubleshooting"]
+related_topics:
+  - "layer-system-fundamentals.md"
+  - "configuration-troubleshooting.md"
+  - "project-layer-setup.md"
+applies_to:
+  - "BC Code Intelligence MCP Server"
+  - "VS Code MCP Extension"
+last_updated: "2025-10-27"
+---
+
+# Workspace Detection Solutions
+
+## Overview
+
+The VS Code MCP extension does **not** set `process.cwd()` to the workspace root, causing the BC Code Intelligence MCP server to be unable to detect project-local configuration and knowledge layers. This document explains the problem, its impact, and the workspace management solution introduced in v1.5.0.
+
+## The Problem
+
+### **Root Cause**
+
+When the MCP server runs in VS Code via the MCP extension:
+- `process.cwd()` points to the MCP extension's installation directory
+- **NOT** the user's workspace directory
+- Example: `C:\Users\Username\.vscode\extensions\...` instead of `C:\Work\MyProject\`
+
+### **Impact**
+
+Without correct working directory:
+1. **Configuration Discovery Fails**: Can't find `./bc-code-intel-config.json` in workspace
+2. **Project Layer Won't Load**: Can't access `./bc-code-intel-overrides/` directory
+3. **Relative Paths Broken**: Any workspace-relative path resolution fails
+4. **User Confusion**: Project-specific knowledge appears missing
+
+## The Solution: Workspace Management Tools (v1.5.0+)
+
+### **Two New MCP Tools**
+
+**1. set_workspace_root** - Configure workspace explicitly
+```typescript
+set_workspace_root({ 
+  workspace_root: "/absolute/path/to/workspace" 
+})
+```
+
+**What it does:**
+1. Validates the provided path exists
+2. Calls `process.chdir(workspace_root)` to change working directory
+3. Triggers full service reinitialization
+4. Reloads all knowledge layers with new workspace context
+5. Discovers project-local configuration if present
+
+**2. get_workspace_root** - Query current workspace
+```typescript
+get_workspace_root()
+```
+
+**Returns:**
+```json
+{
+  "workspace_root": "/current/working/directory",
+  "services_initialized": true
+}
+```
+
+### **First-Call Interception Pattern**
+
+The MCP server implements **lazy initialization** with **first-call interception**:
+
+**At Startup:**
+- Server loads embedded knowledge only (fast startup, ~100ms)
+- `servicesInitialized = false`
+- All tool classes initialized but not ready
+
+**On First Tool Call (before workspace set):**
+- Tool handler checks `servicesInitialized === false`
+- Returns helpful message instead of executing tool:
+
+```
+🚀 BC Code Intelligence MCP Server - Workspace Configuration
+
+The MCP server needs workspace context to load project-specific knowledge and configuration.
+
+REQUIRED ACTION:
+Call the set_workspace_root tool with your workspace path:
+
+set_workspace_root({ 
+  workspace_root: "/absolute/path/to/your/workspace" 
+})
+
+This enables:
+- Project-local configuration (bc-code-intel-config.json)
+- Project knowledge overrides (bc-code-intel-overrides/)
+- Team and company knowledge layers
+- Full workspace-aware functionality
+
+After setting workspace root, all tools will be available.
+```
+
+**After Workspace Set:**
+- Full initialization runs
+- All layers loaded (embedded, git, project)
+- `servicesInitialized = true`
+- All tools execute normally
+
+## Usage Patterns
+
+### **VS Code Workflow**
+
+**Step 1: Open workspace in VS Code**
+```
+File → Open Folder → Select your BC project
+```
+
+**Step 2: Start MCP conversation**
+```
+User: "Hey, can you help me optimize this code?"
+```
+
+**Step 3: Server prompts for workspace**
+```
+MCP: "I need workspace context. Call set_workspace_root first..."
+```
+
+**Step 4: Set workspace root** (agent or user)
+```typescript
+set_workspace_root({ 
+  workspace_root: "C:\\Work\\MyBCProject" 
+})
+```
+
+**Step 5: Full functionality available**
+```
+✅ Project config loaded
+✅ Project knowledge layers available
+✅ All tools ready
+```
+
+### **Claude Desktop Workflow** (Manual Setup)
+
+**Option A: Environment Variable** (Recommended)
+```bash
+# Set before launching Claude Desktop
+export BC_WORKSPACE_ROOT="/path/to/workspace"
+
+# On Windows PowerShell:
+$env:BC_WORKSPACE_ROOT = "C:\Work\MyBCProject"
+```
+
+**Option B: Manual Tool Call**
+```typescript
+// First interaction with MCP
+set_workspace_root({ 
+  workspace_root: "/path/to/workspace" 
+})
+```
+
+### **Automated CI/CD Workflow**
+
+```bash
+# CI script sets workspace before running MCP tools
+export BC_WORKSPACE_ROOT="$CI_PROJECT_DIR"
+
+# MCP server auto-detects from environment
+# No set_workspace_root call needed
+```
+
+## Configuration Discovery After Workspace Set
+
+Once workspace is set, configuration discovery searches:
+
+1. **Workspace Root**
+   - `./bc-code-intel-config.json`
+   - `./bc-code-intel-config.yaml`
+   - `./bc-code-intel-config.yml`
+
+2. **User Home Directory** (expanded paths)
+   - `~/.bc-code-intel/config.json`
+   - `~/.bc-code-intel/config.yaml`
+   - `~/.bc-code-intel/config.yml`
+
+3. **Environment Variable**
+   - `BC_CODE_INTEL_CONFIG=/path/to/config.json`
+
+4. **Default Embedded Config**
+   - Embedded fallback if no config found
+
+**Priority:** Workspace config > Environment variable > Home directory > Embedded
+
+## Project Layer After Workspace Set
+
+With workspace configured, project layer loads from:
+
+```
+{workspace_root}/bc-code-intel-overrides/
+├── domains/              # Project-specific topics
+├── specialists/          # Project-specific specialists (future)
+└── methodologies/        # Project-specific workflows (future)
+```
+
+**Layer Priority:** 100 (highest - always wins)
+
+## Troubleshooting
+
+### **"Project config not found"**
+
+**Problem:** Configuration exists but not being loaded
+
+**Solution:**
+```typescript
+// Verify current workspace
+get_workspace_root()
+
+// If wrong, set correct path
+set_workspace_root({ workspace_root: "/correct/path" })
+```
+
+### **"Project layer showing 0 topics"**
+
+**Problem:** `bc-code-intel-overrides/` directory structure incorrect
+
+**Check:**
+1. Directory exists: `{workspace}/bc-code-intel-overrides/`
+2. Content in subdirectories: `domains/`, `specialists/`, `methodologies/`
+3. Proper frontmatter in markdown files
+
+**Solution:**
+```bash
+# Create proper structure
+mkdir -p bc-code-intel-overrides/domains/my-domain
+mkdir -p bc-code-intel-overrides/specialists
+```
+
+### **"Services not initializing after set_workspace_root"**
+
+**Problem:** Path doesn't exist or insufficient permissions
+
+**Verify:**
+```bash
+# Check path exists
+ls -la /path/to/workspace
+
+# Check permissions
+# Should be readable by MCP server process
+```
+
+**Solution:**
+- Use absolute paths (not relative)
+- Ensure directory exists before calling set_workspace_root
+- Check file permissions
+
+## Implementation Details
+
+### **Lazy Initialization Benefits**
+
+1. **Fast Startup**: Embedded knowledge only (~100ms)
+2. **User-Friendly**: Clear guidance when workspace needed
+3. **Zero-Config Default**: Works without workspace for embedded-only usage
+4. **Explicit Configuration**: User/agent explicitly opts into workspace features
+
+### **Service Reinitialization on Workspace Change**
+
+When `set_workspace_root` is called:
+```typescript
+// 1. Change working directory
+process.chdir(workspace_root)
+
+// 2. Reload configuration
+configService.loadConfiguration()
+
+// 3. Reinitialize all services
+await initializeServices()
+
+// 4. Reload all knowledge layers
+await layerService.loadAllLayers()
+```
+
+**Performance:** Full reinitialization takes 1-3 seconds including git layer cloning (if not cached).
+
+## Best Practices
+
+1. **Set Workspace Early**: Call `set_workspace_root` at the start of MCP conversations in VS Code
+2. **Absolute Paths**: Always use absolute paths, not relative
+3. **Verify Before Setting**: Ensure workspace directory exists and is accessible
+4. **Check After Setting**: Use `get_workspace_root` to confirm workspace configured correctly
+5. **Environment Variables**: For CLI/CI scenarios, use `BC_WORKSPACE_ROOT` env var
+
+## Advanced: Environment-Based Auto-Configuration
+
+### **Setting Default Workspace**
+
+Create a shell alias or launcher script:
+
+```bash
+# ~/.bashrc or ~/.zshrc
+export BC_WORKSPACE_ROOT="$HOME/BCProjects/current"
+
+# Windows PowerShell profile
+$env:BC_WORKSPACE_ROOT = "C:\Work\CurrentProject"
+```
+
+### **Per-Project Launch Scripts**
+
+```bash
+#!/bin/bash
+# launch-mcp.sh in project root
+
+export BC_WORKSPACE_ROOT="$(pwd)"
+code .  # Launch VS Code with workspace set
+```
+
+## Migration from Pre-1.5.0
+
+**Before v1.5.0:**
+- Project layer only worked in environments where `process.cwd()` was correct
+- VS Code users couldn't use project-local features
+- No workaround available
+
+**After v1.5.0:**
+- Explicit workspace configuration via `set_workspace_root`
+- Works in all environments (VS Code, Claude Desktop, CLI)
+- Backward compatible - embedded knowledge still works without workspace
+
+**No Breaking Changes:** Existing configurations continue to work. Workspace management is optional but recommended for project features.
+
+## See Also
+
+- [Layer System Fundamentals](layer-system-fundamentals.md) - Understanding layer architecture
+- [Project Layer Setup](project-layer-setup.md) - Setting up project-local knowledge
+- [Configuration File Discovery](configuration-file-discovery.md) - Where configs are found
+- [Configuration Troubleshooting](configuration-troubleshooting.md) - Common issues and solutions