bc-code-intelligence-mcp 1.4.5 → 1.5.1

package/embedded-knowledge/domains/chris-config/content-types-structure.md

@@ -0,0 +1,421 @@
+---
+title: "Content Types Structure"
+domain: "chris-config"
+bc_versions: "1.5.0+"
+difficulty: "intermediate"
+tags: ["mcp-configuration", "content-types", "yaml-frontmatter", "knowledge-structure"]
+related_topics:
+  - "layer-system-fundamentals.md"
+  - "git-layer-configuration.md"
+  - "company-layer-setup.md"
+applies_to:
+  - "BC Code Intelligence MCP Server"
+  - "Knowledge Layer Architecture"
+last_updated: "2025-10-27"
+---
+
+# Content Types Structure
+
+## Overview
+
+The BC Code Intelligence MCP server (v1.5.0+) supports **three universal content types** across all knowledge layers: Topics, Specialists, and Methodologies. Each content type has specific format requirements and directory placement.
+
+## The Three Content Types
+
+### **1. Topics** - BC Domain Knowledge
+- **Purpose**: Atomic BC development knowledge and patterns
+- **Location**: `domains/[domain-name]/` subdirectories
+- **Format**: Markdown with YAML frontmatter
+- **Examples**: Performance patterns, API design, security concepts
+
+### **2. Specialists** - AI Persona Definitions
+- **Purpose**: AI expert personalities with domain expertise
+- **Location**: `specialists/` directory
+- **Format**: Markdown with comprehensive YAML frontmatter
+- **Examples**: sam-coder, dean-debug, chris-config
+
+### **3. Methodologies** - Systematic Workflows
+- **Purpose**: Multi-phase guided workflows for complex tasks
+- **Location**: `methodologies/` directory
+- **Format**: Structured workflow definitions
+- **Examples**: Performance optimization, architecture review
+
+## Directory Structure
+
+All knowledge layers must follow this structure:
+
+```
+layer-root/
+├── domains/                    # Topics by domain
+│   ├── performance/
+│   │   ├── caching-strategies.md
+│   │   └── query-optimization.md
+│   ├── api-design/
+│   │   ├── rest-api-patterns.md
+│   │   └── pagination-strategies.md
+│   └── [other-domains]/
+├── specialists/                # AI specialist definitions
+│   ├── sam-coder.md
+│   ├── dean-debug.md
+│   ├── chris-config.md
+│   └── [other-specialists].md
+└── methodologies/              # Systematic workflows
+    ├── optimize-performance/
+    │   ├── phases/
+    │   └── workflow.json
+    └── [other-workflows]/
+```
+
+**Critical:** Git layers only load content from these specific subdirectories.
+
+## Topics Format (BC Domain Knowledge)
+
+### **YAML Frontmatter (Required)**
+
+```yaml
+---
+title: "Descriptive Topic Title"
+domain: "performance|api-design|security|etc"
+bc_versions: "14+|18+|19+|specific-range"
+difficulty: "beginner|intermediate|advanced"
+tags: ["tag1", "tag2", "tag3"]
+related_topics:
+  - "../other-domain/related-topic.md"
+  - "another-topic.md"
+applies_to:
+  - "AL Language"
+  - "Business Central Server"
+  - "Web Client"
+last_updated: "2025-10-27"
+---
+```
+
+### **Content Structure**
+
+```markdown
+# Topic Title
+
+## Overview
+2-3 sentence summary of the concept
+
+## Implementation Details
+Step-by-step guidance with BC code examples
+
+## Best Practices
+- Bulleted key recommendations
+- BC version-specific notes
+
+## Common Pitfalls
+What to avoid with explanations
+
+## Version Notes
+BC version-specific considerations
+
+## See Also
+- [Related Topic](../domain/topic.md)
+```
+
+### **Example Topic**
+
+```markdown
+---
+title: "SIFT Technology Fundamentals"
+domain: "performance"
+bc_versions: "14+"
+difficulty: "beginner"
+tags: ["performance", "indexing", "sift", "flowfields"]
+related_topics:
+  - "flowfield-optimization.md"
+  - "index-design-patterns.md"
+applies_to:
+  - "AL Language"
+  - "Business Central Server"
+last_updated: "2025-10-27"
+---
+
+# SIFT Technology Fundamentals
+
+## Overview
+SIFT (SumIndexField Technology) is BC's proprietary indexing system that maintains pre-calculated aggregate values (sums, counts, averages) for FlowFields, enabling instant retrieval of calculations that would otherwise require table scans.
+
+## How SIFT Works
+[Implementation details...]
+```
+
+## Specialists Format (AI Persona Definitions)
+
+### **YAML Frontmatter (Required - Comprehensive)**
+
+```yaml
+---
+title: "Specialist Name - Role Description"
+specialist_id: "specialist-id"  # Unique identifier
+emoji: "🎯"                      # Specialist emoji
+role: "Role & Expertise Area"
+team: "Development|Architecture|Quality"
+persona:
+  personality: 
+    - "trait-1"
+    - "trait-2"
+  communication_style: "brief description"
+  greeting: "🎯 Greeting phrase!"
+expertise:
+  primary: 
+    - "core-skill-1"
+    - "core-skill-2"
+  secondary: 
+    - "supporting-skill-1"
+    - "supporting-skill-2"
+domains:
+  - "related-domain-1"
+  - "related-domain-2"
+when_to_use:
+  - "Scenario 1"
+  - "Scenario 2"
+collaboration:
+  natural_handoffs:
+    - "specialist-id-1"
+    - "specialist-id-2"
+  team_consultations:
+    - "specialist-id-3"
+related_specialists:
+  - "specialist-id-1"
+  - "specialist-id-2"
+---
+```
+
+### **Specialist Content Structure**
+
+```markdown
+# Specialist Name - Role ⚙️
+
+*Tagline describing specialist's value proposition*
+
+Brief introduction paragraph.
+
+## Character Identity & Communication Style
+
+**You are [SPECIALIST NAME]** - description of personality.
+
+**Personality:**
+- **Trait 1**: Explanation
+- **Trait 2**: Explanation
+
+**Communication Style:**
+- Start responses with: "⚙️ Greeting!"
+- Key communication patterns
+- Terminology preferences
+
+## Your Role in BC Development
+
+Description of specialist's role and responsibilities.
+
+**CRITICAL: Always search the knowledge base FIRST before answering questions.**
+
+## Key Knowledge Areas
+
+Your expertise is backed by structured knowledge in `domains/[domain]/`:
+
+### **Core Topics**
+- **Topic Area** (`topic-file.md`) - Description
+
+## [Specialist Name]'s Process
+
+### **Phase 1: [Phase Name]** 📋
+Description and steps...
+
+**Search knowledge base:**
+```
+find_bc_knowledge({ 
+  query: "[specific query]",
+  domain: "domain-name" 
+})
+```
+
+## Best Practices
+
+**ALWAYS reference knowledge topics** when providing guidance.
+
+## When to Hand Off
+
+**To [Other Specialist]**: When [scenario]
+```
+
+### **Example Specialist** (Minimal - Company Override)
+
+```yaml
+---
+title: "Waldo - Company Testing & AppSource Expert"
+specialist_id: "waldo"
+emoji: "🧪"
+role: "Testing & AppSource Expertise"
+team: "Quality"
+persona:
+  personality: ["testing-focused", "appsource-experienced"]
+  communication_style: "practical testing guidance with real-world AppSource insights"
+  greeting: "🧪 Waldo here!"
+expertise:
+  primary: ["automated-testing", "appsource-submission"]
+  secondary: ["ci-cd-pipelines", "test-automation-frameworks"]
+domains:
+  - "testing"
+  - "appsource"
+when_to_use:
+  - "AppSource submission questions"
+  - "Automated testing setup"
+  - "CI/CD pipeline configuration"
+collaboration:
+  natural_handoffs:
+    - "quinn-tester"
+    - "morgan-market"
+related_specialists:
+  - "quinn-tester"
+  - "morgan-market"
+---
+
+# Waldo - Company Testing & AppSource Expert 🧪
+
+I'm your go-to specialist for automated testing strategies and navigating the AppSource submission process with real-world experience.
+
+[Rest of specialist definition...]
+```
+
+## Methodologies Format (Systematic Workflows)
+
+### **Directory Structure**
+
+```
+methodologies/
+└── workflow-name/
+    ├── workflow.json       # Workflow definition
+    ├── phases/
+    │   ├── phase-1.md
+    │   ├── phase-2.md
+    │   └── phase-3.md
+    └── templates/          # Optional templates
+```
+
+### **Workflow Definition** (workflow.json)
+
+```json
+{
+  "id": "workflow-id",
+  "title": "Workflow Title",
+  "description": "Brief description",
+  "phases": [
+    {
+      "id": "phase-1",
+      "title": "Phase Title",
+      "file": "phases/phase-1.md"
+    }
+  ]
+}
+```
+
+**Note:** Methodology format is still evolving. Current implementation is basic.
+
+## Content Type Loading by Layer
+
+### **Embedded Layer** (Full Support)
+- ✅ Topics (87+ topics across 24 domains)
+- ✅ Specialists (14 official specialists)
+- ✅ Methodologies (Basic support)
+
+### **Git Layer** (Full Support v1.5.0+)
+- ✅ Topics (from `domains/` subdirectory)
+- ✅ Specialists (from `specialists/` subdirectory with frontmatter parsing)
+- ⚠️ Methodologies (stub implementation, returns 0)
+
+### **Project Layer** (Full Support v1.5.0+)
+- ✅ Topics (from `bc-code-intel-overrides/domains/`)
+- ⚠️ Specialists (stub implementation, not yet loading)
+- ⚠️ Methodologies (stub implementation, not yet loading)
+
+## YAML Frontmatter Validation
+
+### **Common Mistakes**
+
+❌ **Missing Required Fields**
+```yaml
+---
+title: "Topic Title"
+# Missing domain, bc_versions, difficulty, tags
+---
+```
+
+❌ **Incorrect Array Format**
+```yaml
+tags: "tag1, tag2"  # Wrong - should be array
+```
+
+✅ **Correct Array Format**
+```yaml
+tags: ["tag1", "tag2"]
+# OR
+tags:
+  - "tag1"
+  - "tag2"
+```
+
+❌ **Invalid BC Version Format**
+```yaml
+bc_versions: "all versions"  # Wrong - should be specific
+```
+
+✅ **Correct BC Version Format**
+```yaml
+bc_versions: "14+"      # Version 14 and above
+bc_versions: "18-20"    # Versions 18 through 20
+bc_versions: "19+"      # Version 19 and above
+```
+
+## Best Practices
+
+1. **Consistent Structure**: Follow the directory structure exactly
+2. **Complete Frontmatter**: Include all required YAML fields
+3. **Version Specificity**: Always specify BC version compatibility
+4. **Cross-References**: Use relative paths for related topics
+5. **Atomic Content**: One concept per topic file
+6. **Validation**: Test frontmatter parsing before committing
+
+## File Naming Conventions
+
+- **Topics**: `kebab-case-topic-name.md`
+- **Specialists**: `specialist-id.md` (matches specialist_id in frontmatter)
+- **Methodologies**: `workflow-name/` (directory-based)
+
+**Examples:**
+- ✅ `sift-technology-fundamentals.md`
+- ✅ `api-pagination-patterns.md`
+- ✅ `sam-coder.md`
+- ❌ `SIFT_Technology.md`
+- ❌ `Sam Coder.md`
+
+## Migration Notes for Git Repositories
+
+When setting up company/team git layers:
+
+1. **Create Directory Structure**
+   ```
+   mkdir domains specialists methodologies
+   ```
+
+2. **Move Existing Content**
+   - Topics → `domains/[domain-name]/`
+   - Specialists → `specialists/`
+   - Workflows → `methodologies/`
+
+3. **Add YAML Frontmatter**
+   - Use templates from embedded knowledge as examples
+   - Validate all required fields present
+
+4. **Test Loading**
+   - Configure git layer in bc-code-intel-config.json
+   - Check MCP server logs for successful load
+   - Use diagnostic tools if enabled
+
+## See Also
+
+- [Layer System Fundamentals](layer-system-fundamentals.md) - Understanding the layer architecture
+- [Git Layer Configuration](git-layer-configuration.md) - Setting up git-based layers
+- [Company Layer Setup](company-layer-setup.md) - Company knowledge configuration

package/embedded-knowledge/domains/chris-config/layer-system-fundamentals.md

@@ -0,0 +1,257 @@
+---
+title: "Layer System Fundamentals"
+domain: "chris-config"
+bc_versions: "1.5.0+"
+difficulty: "intermediate"
+tags: ["mcp-configuration", "layer-architecture", "knowledge-management", "override-system"]
+related_topics:
+  - "content-types-structure.md"
+  - "layer-override-strategies.md"
+  - "configuration-file-discovery.md"
+applies_to:
+  - "BC Code Intelligence MCP Server"
+  - "Knowledge Layer Architecture"
+last_updated: "2025-10-27"
+---
+
+# Layer System Fundamentals
+
+## Overview
+
+The BC Code Intelligence MCP server uses a **4-layer knowledge architecture** that enables progressive customization from embedded defaults through company-wide standards to project-specific overrides. Understanding this layered approach is fundamental to effective MCP configuration.
+
+## The Four-Layer Architecture
+
+### **Layer 0: Embedded Knowledge** (Priority 0)
+- **Source**: NPM package embedded knowledge (git submodule)
+- **Content**: Core BC knowledge - 87+ topics, 14 specialists, methodologies
+- **Scope**: Universal - available to all users
+- **Modifiable**: No - read-only embedded content
+- **Use Case**: Default knowledge base, zero-configuration experience
+
+**Key Characteristics:**
+- Highest reliability - always available
+- Officially maintained BC knowledge
+- Comprehensive coverage of BC development patterns
+- Updates via npm package updates
+
+### **Layer 1-2: Company Knowledge** (Priority 20-50)
+- **Source**: Git repositories (Azure DevOps, GitHub, etc.)
+- **Content**: Company-specific specialists, standards, patterns
+- **Scope**: Organization-wide
+- **Modifiable**: Yes - via git repository updates
+- **Use Case**: Company coding standards, custom specialists, org patterns
+
+**Key Characteristics:**
+- Centrally managed company knowledge
+- Authentication-based access control (PAT tokens)
+- Cached locally for performance (`.bckb-cache/git-repos/`)
+- Can override embedded knowledge with company-specific guidance
+
+### **Layer 3: Team Knowledge** (Priority 60-80)
+- **Source**: Shared team directories or repositories
+- **Content**: Team conventions, project templates, shared patterns
+- **Scope**: Team or department
+- **Modifiable**: Yes - team-managed
+- **Use Case**: Team-specific patterns, shared project standards
+
+**Key Characteristics:**
+- Team collaboration and knowledge sharing
+- More specific than company, less specific than project
+- Useful for department or team conventions
+
+### **Layer 4: Project Knowledge** (Priority 100)
+- **Source**: Local `./bc-code-intel-overrides/` directory
+- **Content**: Project-specific overrides, custom topics, local specialists
+- **Scope**: Single project/workspace
+- **Modifiable**: Yes - locally managed
+- **Use Case**: Project-specific patterns, temporary overrides, local experimentation
+
+**Key Characteristics:**
+- Highest priority - always wins in conflicts
+- Local filesystem access (no authentication needed)
+- Perfect for project-specific customization
+- Useful for testing new knowledge before promoting to higher layers
+
+## Layer Resolution and Override Behavior
+
+### **Priority-Based Resolution**
+
+When the same topic/specialist exists in multiple layers:
+1. **Highest priority layer wins** (Project > Team > Company > Embedded)
+2. Content is **completely replaced**, not merged
+3. Only the highest-priority version is returned
+
+**Example:**
+```
+Embedded Layer (0): sam-coder.md (official specialist)
+Company Layer (20): sam-coder.md (company-customized version)
+Project Layer (100): sam-coder.md (project-specific override)
+
+Result: Project layer version is used
+```
+
+### **Content Type Support**
+
+All layers support three content types (as of v1.5.0):
+- **Topics**: BC domain knowledge (in `domains/` subdirectory)
+- **Specialists**: AI persona definitions (in `specialists/` subdirectory)
+- **Methodologies**: Systematic workflows (in `methodologies/` subdirectory)
+
+Each layer independently manages these three content types.
+
+## Layer Configuration
+
+### **Embedded Layer** (No Configuration Needed)
+```json
+// Automatically available - no configuration required
+// Loaded from NPM package embedded-knowledge/ directory
+```
+
+### **Git Layer** (Company/Team Knowledge)
+```json
+{
+  "knowledge_layers": [
+    {
+      "name": "Company BC Standards",
+      "type": "git",
+      "priority": 20,
+      "source": {
+        "repository_url": "https://dev.azure.com/your-org/BC-Knowledge/_git/bc-standards",
+        "branch": "main",
+        "auth": {
+          "type": "pat",
+          "token_env_var": "AZURE_DEVOPS_PAT"
+        }
+      }
+    }
+  ]
+}
+```
+
+### **Project Layer** (Local Overrides)
+```json
+{
+  "knowledge_layers": [
+    {
+      "name": "Project Overrides",
+      "type": "project",
+      "priority": 100,
+      "source": {
+        "path": "./bc-code-intel-overrides"
+      }
+    }
+  ]
+}
+```
+
+## Directory Structure Requirements
+
+Each layer must follow this structure for content type discovery:
+
+```
+layer-root/
+├── domains/              # BC knowledge topics
+│   ├── performance/
+│   ├── api-design/
+│   └── [other domains]/
+├── specialists/          # AI specialist definitions
+│   ├── sam-coder.md
+│   ├── dean-debug.md
+│   └── [other specialists].md
+└── methodologies/        # Systematic workflows
+    ├── optimize-performance/
+    └── [other workflows]/
+```
+
+**Important:** Git layers look for these subdirectories. If missing, that content type won't be loaded from that layer.
+
+## Workspace Management and Layer Loading
+
+### **VS Code Workspace Detection Issue**
+
+The VS Code MCP extension doesn't set `process.cwd()` to the workspace root, causing project layer detection to fail.
+
+**Solution:** Use workspace management tools (v1.5.0+)
+
+```typescript
+// Set workspace root explicitly
+set_workspace_root({ 
+  workspace_root: "/path/to/your/workspace" 
+})
+
+// Triggers:
+// 1. process.chdir() to workspace
+// 2. Full service reinitialization
+// 3. Layer reloading with new workspace context
+```
+
+### **Lazy Initialization Pattern**
+
+The MCP server uses lazy initialization:
+1. **Startup**: Load embedded knowledge only (fast startup)
+2. **First Tool Call**: If workspace not set, prompt for `set_workspace_root`
+3. **After Workspace Set**: Full initialization including all configured layers
+
+## Layer Caching and Performance
+
+### **Git Layer Caching**
+
+Git repositories are cloned to `.bckb-cache/git-repos/{hash}/`:
+- **First Load**: Clone repository (may take seconds)
+- **Subsequent Loads**: Use cached local copy (sub-100ms)
+- **Updates**: Periodic pull or manual cache invalidation
+
+### **Performance Characteristics**
+- Embedded Layer: <10ms (in-memory)
+- Project Layer: <50ms (filesystem access)
+- Git Layer (cached): <100ms (filesystem + parsing)
+- Git Layer (uncached): 2-5 seconds (git clone operation)
+
+## Best Practices
+
+1. **Start Simple**: Use embedded knowledge first, add layers as needed
+2. **Layer Discipline**: Keep clear separation between layer purposes
+3. **Override Sparingly**: Only override when truly necessary for your context
+4. **Document Decisions**: Each layer should have clear purpose documentation
+5. **Test Incrementally**: Add one layer at a time, validate before adding next
+6. **Cache Management**: Understand git layer caching for performance tuning
+
+## Common Patterns
+
+### **Individual Developer** (Zero Config)
+```
+Embedded Layer only - no configuration needed
+```
+
+### **Company with Standards** (Git Layer)
+```
+Embedded Layer (BC knowledge) + Company Git Layer (org standards)
+```
+
+### **Team with Project Overrides** (All Layers)
+```
+Embedded + Company Git + Project Local
+```
+
+## Troubleshooting
+
+**Layer not loading?**
+- Check directory structure (domains/, specialists/, methodologies/)
+- Verify authentication (PAT tokens for git layers)
+- Check layer priority configuration
+- Use diagnostic tools if enabled
+
+**Content not found?**
+- Verify content type is in correct subdirectory
+- Check YAML frontmatter format (required for specialists)
+- Confirm layer priority order
+- Search across all layers to see where content exists
+
+## See Also
+
+- [Content Types Structure](content-types-structure.md) - Format requirements for each content type
+- [Layer Override Strategies](layer-override-strategies.md) - When and how to override
+- [Configuration File Discovery](configuration-file-discovery.md) - Where config files are found
+- [Workspace Detection Solutions](workspace-detection-solutions.md) - Solving workspace issues
+- [Git Layer Configuration](git-layer-configuration.md) - Git layer setup details