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

package/embedded-knowledge/domains/chris-config/knowledge-content-creation.md

@@ -0,0 +1,437 @@
+---
+title: "Creating Custom BC Knowledge Content"
+domain: "chris-config"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["knowledge-creation", "content-authoring", "yaml-frontmatter", "markdown", "overrides"]
+related_topics: ["multi-team-layer-configuration", "content-quality-standards"]
+applies_to: ["Knowledge Base", "Team Documentation", "Project Customization"]
+last_updated: "2025-01-01"
+---
+
+# Creating Custom BC Knowledge Content
+
+## Overview
+
+Learn to create high-quality BC knowledge content that perfectly fits your organization's needs. This guide covers writing, structuring, and maintaining knowledge overrides that enhance the embedded knowledge base through the layer system.
+
+**Key Benefit**: Custom knowledge content allows teams to capture specialized patterns, company standards, and project-specific requirements while maintaining compatibility with the broader BC knowledge ecosystem.
+
+## Knowledge Topic Structure
+
+Every knowledge topic follows a consistent structure with YAML frontmatter and organized markdown content:
+
+```yaml
+---
+# Required Metadata
+title: "Descriptive Topic Title"
+domain: "performance|api-design|security|etc"
+bc_versions: "20+"
+difficulty: "beginner|intermediate|advanced|expert"
+tags: ["tag1", "tag2", "tag3"]
+
+# Override Configuration (if applicable)
+overrides: ["embedded-topic-id"]
+merge_strategy: "replace|overlay|smart|append"
+
+# Organization Context
+organization_level: "company|team|project"
+author: "your.email@company.com"
+created: "2025-01-15"
+last_modified: "2025-01-20"
+
+# Cross-References
+related_topics: ["topic-id-1", "topic-id-2"]
+prerequisites: ["prerequisite-topic-id"]
+---
+
+# Topic Title
+
+Brief introduction explaining what this topic covers and why it matters.
+
+## Overview
+Clear explanation of the concept, pattern, or practice including:
+- What it is and when to use it
+- Why it's important
+- Key benefits for BC development
+
+## Business Central Context
+BC-specific considerations:
+- Platform integration points
+- Version compatibility notes
+- Related BC features or modules
+
+## Implementation
+Step-by-step guidance with clear instructions:
+
+### Prerequisites
+- Required setup or dependencies
+- Assumed knowledge or skills
+
+### Step-by-Step Guide
+1. **Step 1**: Detailed instruction
+   ```al
+   // Clear, compilable AL code example
+   table 50100 ExampleTable
+   {
+       DataClassification = CustomerContent;
+       
+       fields
+       {
+           field(1; "Entry No."; Integer)
+           {
+               AutoIncrement = true;
+           }
+       }
+   }
+   ```
+
+## Best Practices
+Proven recommendations:
+- ✅ Use clear, descriptive naming conventions
+- ✅ Implement proper error handling
+- ✅ Follow BC coding standards
+- ❌ Avoid hard-coded values
+- ❌ Don't skip validation
+
+## Version Considerations
+BC version compatibility and migration notes
+
+## Troubleshooting
+Common issues and solutions
+
+## Related Topics
+Links to related knowledge content
+```
+
+## YAML Frontmatter Reference
+
+### Required Fields
+```yaml
+---
+title: "Descriptive Topic Title"        # Clear, specific title
+domain: "performance"                   # Domain classification
+bc_versions: "20+"                     # Version compatibility
+difficulty: "intermediate"             # Complexity level
+tags: ["tag1", "tag2"]                # Minimum 2 descriptive tags
+---
+```
+
+### Domain Classifications
+Choose the most appropriate domain for your content:
+
+```yaml
+# Technical domains
+domain: "performance"        # Optimization, SIFT, query tuning
+domain: "api-design"        # REST, OData, authentication
+domain: "security"          # Access control, data protection
+domain: "architecture"      # System design, patterns
+domain: "data-architecture" # Tables, relationships
+domain: "debugging"         # Troubleshooting, diagnostics
+
+# Process domains
+domain: "best-practices"    # General guidelines
+domain: "error-handling"    # Exception management
+domain: "testing"          # Quality assurance
+domain: "deployment"       # Release management
+
+# Specialist domains
+domain: "alex-architect"    # Architecture and design
+domain: "dean-debug"       # Performance and debugging
+domain: "sam-coder"        # Implementation patterns
+domain: "chris-config"     # Configuration and customization
+```
+
+### Difficulty Level Guidelines
+```yaml
+difficulty: "beginner"      # Basic concepts, getting started
+# - Assumes minimal BC knowledge
+# - Step-by-step instructions
+# - Explains basic concepts
+
+difficulty: "intermediate"  # Practical implementation
+# - Assumes basic BC development knowledge
+# - Real-world scenarios
+# - Best practices focus
+
+difficulty: "advanced"      # Complex patterns, optimization
+# - Assumes solid BC experience
+# - Performance considerations
+# - Integration challenges
+
+difficulty: "expert"        # Cutting-edge, specialized
+# - Assumes deep BC expertise
+# - Advanced patterns
+# - Platform limitations
+```
+
+### Effective Tagging Strategy
+```yaml
+# Performance-related tags
+tags: ["sift", "optimization", "query-performance", "memory-management"]
+
+# API and integration tags  
+tags: ["rest", "odata", "authentication", "integration", "webhooks"]
+
+# Architecture and design tags
+tags: ["design-patterns", "microservices", "event-driven", "scalability"]
+
+# Development process tags
+tags: ["testing", "debugging", "devops", "code-review"]
+
+# Business domain tags
+tags: ["manufacturing", "retail", "financial", "healthcare"]
+```
+
+## Override Configuration
+
+### Simple Content Override
+Replace embedded content completely:
+```yaml
+---
+title: "Company SIFT Optimization Standards"
+domain: "performance"
+overrides: ["sift-technology-fundamentals"]
+merge_strategy: "replace"
+organization_level: "company"
+---
+```
+
+### Content Enhancement
+Add to existing embedded content:
+```yaml
+---
+title: "Team-Specific API Authentication Patterns"
+domain: "api-design"
+overrides: ["api-authentication-patterns"]
+merge_strategy: "append"
+organization_level: "team"
+sections_to_enhance: ["implementation", "examples"]
+---
+```
+
+### Conditional Overrides
+Apply overrides based on conditions:
+```yaml
+---
+title: "Production Environment Security Standards"
+domain: "security"
+override_conditions:
+  environment: ["production"]
+  bc_version: "23+"
+---
+```
+
+## Code Example Standards
+
+### AL Code Examples
+```al
+// Always include context comments
+table 50100 "Customer Analytics"
+{
+    // Purpose: Store customer performance metrics
+    DataClassification = CustomerContent;
+    
+    fields
+    {
+        field(1; "Customer No."; Code[20])
+        {
+            // Links to standard Customer table
+            TableRelation = Customer."No.";
+            Caption = 'Customer No.';
+        }
+        
+        field(10; "Total Sales Amount"; Decimal)
+        {
+            // Calculated via SIFT for performance
+            FieldClass = FlowField;
+            CalcFormula = Sum("Sales Line".Amount WHERE("Sell-to Customer No." = FIELD("Customer No.")));
+            Caption = 'Total Sales Amount';
+        }
+    }
+    
+    keys
+    {
+        key(PK; "Customer No.")
+        {
+            Clustered = true;
+        }
+        
+        // SIFT key for aggregation performance
+        key(SalesAnalysis; "Customer No.")
+        {
+            SumIndexFields = "Total Sales Amount";
+        }
+    }
+}
+```
+
+### Configuration Examples
+```json
+// JSON configuration with explanatory comments
+{
+  "performance_settings": {
+    "enable_sift": true,           // Enables SIFT optimization
+    "max_records": 10000,         // Prevents memory issues
+    "timeout_seconds": 30         // Query timeout protection
+  },
+  "cache_settings": {
+    "enabled": true,
+    "ttl_minutes": 15            // Cache expiration time
+  }
+}
+```
+
+## Content Development Workflow
+
+### 1. Planning Phase
+```markdown
+## Topic Planning Checklist
+- [ ] Identify knowledge gap or override need
+- [ ] Define target audience and use case
+- [ ] Research existing related topics
+- [ ] Plan topic scope and depth
+- [ ] Choose appropriate domain and tags
+- [ ] Determine BC version compatibility
+```
+
+### 2. Content Creation Phase
+```markdown
+## Content Creation Checklist
+- [ ] Write compelling title and overview
+- [ ] Create YAML frontmatter with required fields
+- [ ] Develop step-by-step implementation guide
+- [ ] Include practical, compilable code examples
+- [ ] Add best practices and anti-patterns
+- [ ] Write troubleshooting section
+- [ ] Add cross-references to related topics
+```
+
+### 3. Quality Assurance Phase
+```markdown
+## Quality Review Checklist
+- [ ] YAML frontmatter syntax is valid
+- [ ] Markdown renders correctly
+- [ ] Code examples compile successfully
+- [ ] Cross-references resolve correctly
+- [ ] Content accuracy verified
+- [ ] Writing clarity and flow reviewed
+- [ ] Version compatibility confirmed
+```
+
+## Layer Integration
+
+### Project-Level Overrides
+Create content in your project's override directory:
+```
+bc-code-intel-overrides/
+├── domains/
+│   ├── performance/
+│   │   └── our-sift-standards.md
+│   ├── security/
+│   │   └── company-auth-patterns.md
+│   └── chris-config/
+│       └── project-specific-config.md
+└── specialists/
+    └── company-reviewer.md
+```
+
+### Team Git Repository
+Structure team knowledge in a Git repository:
+```
+team-bc-knowledge/
+├── domains/
+│   ├── performance/
+│   │   ├── team-optimization-patterns.md
+│   │   └── performance-testing-standards.md
+│   ├── api-design/
+│   │   └── team-integration-patterns.md
+│   └── shared/
+│       └── team-coding-conventions.md
+├── specialists/
+│   └── team-specialist-config.md
+└── methodologies/
+    └── team-code-review-process.md
+```
+
+### Company Standards Repository
+Maintain organization-wide standards:
+```
+company-bc-standards/
+├── domains/
+│   ├── security/
+│   │   ├── corporate-security-standards.md
+│   │   └── data-classification-requirements.md
+│   ├── architecture/
+│   │   └── enterprise-integration-patterns.md
+│   └── best-practices/
+│       └── corporate-coding-standards.md
+└── policies/
+    ├── approval-requirements.md
+    └── review-processes.md
+```
+
+## Quality Standards
+
+### Content Quality Metrics
+- **Completeness**: All required sections present
+- **Clarity**: Clear, actionable instructions
+- **Examples**: Working, realistic code samples
+- **Currency**: Up-to-date with current BC versions
+- **Cross-references**: Proper links to related content
+
+### Maintenance Standards
+```yaml
+# Quality gates for topic updates
+quality_standards:
+  minimum_completeness: 80
+  required_sections: ["overview", "implementation", "best-practices"]
+  code_example_requirement: true
+  cross_reference_minimum: 3
+  version_compatibility_current: true
+```
+
+## Best Practices
+
+### Content Writing
+- **Be specific**: Focus on actionable guidance
+- **Use examples**: Include working AL code samples
+- **Link appropriately**: Reference related topics
+- **Update regularly**: Keep content current with BC versions
+- **Test thoroughly**: Verify all code examples compile
+
+### Organization
+- **Consistent structure**: Follow established patterns
+- **Clear taxonomy**: Use appropriate domains and tags
+- **Logical progression**: Order content from basic to advanced
+- **Proper versioning**: Clearly indicate BC compatibility
+
+### Collaboration
+- **Document decisions**: Explain why overrides exist
+- **Review processes**: Establish content quality gates
+- **Version control**: Track changes and contributors
+- **Training**: Help team members contribute effectively
+
+## Common Anti-Patterns
+
+### Content Issues
+- ❌ **Vague titles**: "Performance Tips" instead of specific guidance
+- ❌ **Missing context**: Code without explanation
+- ❌ **Outdated examples**: Using deprecated BC features
+- ❌ **Broken references**: Links to non-existent topics
+
+### Organizational Issues
+- ❌ **Too many overrides**: Overriding everything instead of selective enhancement
+- ❌ **Conflicting content**: Multiple teams providing contradictory guidance
+- ❌ **No maintenance**: Creating content without ongoing updates
+- ❌ **Poor governance**: No review or approval processes
+
+## Related Topics
+
+- **[Multi-Team Layer Configuration](multi-team-layer-configuration)**: Setting up organizational knowledge layers
+- **[Content Quality Standards](content-quality-standards)**: Maintaining high-quality knowledge
+- **[Specialist Customization](specialist-customization)**: Creating custom AI specialists
+
+---
+
+*Master content creation to build a comprehensive BC knowledge base that serves your organization's specific needs while maintaining compatibility with the broader ecosystem.*

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