bc-code-intelligence-mcp 1.3.4 → 1.3.6

package/embedded-knowledge/AGENTS.md

@@ -0,0 +1,178 @@
+# AGENTS.md - Repository Context for AI Assistants
+
+## Repository Purpose
+This is the **knowledge content repository** for the BC Code Intelligence (bc-code-intel) system.
+
+## What This Repo Contains
+- **BC Domain Knowledge**: 87+ atomic topics across 24 domains (performance, API design, security, etc.)
+- **Methodology Frameworks**: Step-by-step AI workflow guidance for systematic optimization
+- **Specialists Definitions**: 14 AI persona configurations with domain expertise and behavioral constraints
+- **Strategic Prompts**: High-level prompts for common BC development scenarios
+- **Pure Markdown Content**: No code whatsoever - only knowledge content with YAML frontmatter
+
+## What This Repo Does NOT Contain
+- TypeScript/JavaScript code (that's in bc-code-intelligence-mcp repository)
+- MCP server implementation or protocol handling
+- Build processes, dependencies, or package.json files
+- Compiled or generated content
+
+## Repository Structure
+```
+domains/                    # BC knowledge organized by domain
+├── performance/           # Performance optimization patterns
+├── api-design/           # REST/OData API best practices
+├── data-architecture/    # Table design and relationships
+├── security/             # Authentication and authorization
+└── [20 other domains]/
+
+methodologies/            # AI workflow frameworks
+├── phases/              # Systematic analysis phases
+└── workflows/           # Complete optimization workflows
+
+specialists/             # AI persona definitions
+├── alex-architect.md        # Strategic Planning & Architecture
+├── casey-copilot.md         # AI-Enhanced Development Coach
+├── dean-debug.md            # Performance & Troubleshooting
+├── eva-errors.md            # Error Handling & Exception Management
+├── jordan-bridge.md         # Systems Connection & Event-Driven Design
+├── logan-legacy.md          # Legacy Code & Version Migration
+├── maya-mentor.md           # Learning & Skill Development
+├── morgan-market.md         # AppSource & ISV Business Expert
+├── quinn-tester.md          # Quality Validation & Test Design
+├── roger-reviewer.md        # Code Quality & Review Standards
+├── sam-coder.md             # Efficient Implementation Expert
+├── seth-security.md         # Security & Permission Management
+├── taylor-docs.md           # Documentation & Knowledge Management
+└── uma-ux.md                # User Experience & Interface Design
+
+prompts/                # Strategic prompts
+├── analyze-performance.md
+├── review-architecture.md
+└── [other prompts]/
+```
+
+## Content Standards
+- **Atomic Topics**: One focused concept per markdown file
+- **YAML Frontmatter**: Rich metadata for AI consumption including:
+  - BC version compatibility (`bc_versions: "14+"`)
+  - Difficulty level, tags, domain classification
+  - Cross-references to related topics
+- **Version Awareness**: All content specifies BC version compatibility
+- **Consistent Structure**: Follow established patterns for headings, examples, cross-references
+
+## AI Assistant Guidelines When Working With This Repo
+1. **Content Focus**: Maintain accuracy of BC technical information
+2. **Structure Integrity**: Preserve YAML frontmatter completeness and consistency
+3. **Version Compatibility**: Always specify BC version ranges for patterns/features
+4. **Cross-References**: Maintain accurate links between related topics
+5. **Atomic Principle**: Keep each file focused on one specific concept
+6. **NO CODE**: This repository contains NO executable code - knowledge only
+7. **Link Integrity**: Ensure internal topic references remain valid
+
+## GitHub Copilot Coding Agent Guidelines
+
+### Content Creation Patterns
+When creating new knowledge topics, ALWAYS use this YAML frontmatter template:
+```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:
+  - "path/to/related/topic.md"
+  - "another/related/topic.md"
+applies_to:
+  - "AL Language"
+  - "Business Central Server"
+  - "Web Client"
+last_updated: "2025-01-01"
+---
+```
+
+### File Naming Conventions
+- Use kebab-case for all filenames: `api-pagination-patterns.md`
+- Include domain prefix when needed: `performance-caching-strategies.md`
+- Keep names descriptive but concise (max 50 characters)
+- Avoid abbreviations unless universally understood
+
+### Content Structure Requirements
+1. **H1 Title**: Must match YAML frontmatter title exactly
+2. **Overview Section**: 2-3 sentence summary of the concept
+3. **Implementation Details**: Step-by-step guidance with BC code examples
+4. **Best Practices**: Bulleted list of key recommendations
+5. **Common Pitfalls**: What to avoid with explanations
+6. **Version Notes**: BC version-specific considerations
+7. **See Also**: Cross-references to related topics
+
+### Cross-Reference Validation
+- Use relative paths: `../performance/caching-strategies.md`
+- Verify target files exist before creating references
+- Update both directions when creating new relationships
+- Use descriptive link text: `[API Pagination Patterns](../api-design/pagination-patterns.md)`
+
+### Domain Organization Rules
+```
+domains/
+├── performance/          # Speed, memory, resource optimization
+├── api-design/          # REST, OData, integration patterns
+├── security/            # Authentication, authorization, data protection
+├── data-architecture/   # Table design, relationships, normalization
+├── error-handling/      # Exception management, validation
+├── testing/            # Unit, integration, performance testing
+└── [other domains]/    # Maintain alphabetical order
+```
+
+### Validation Checklist
+Before committing new content, verify:
+- [ ] YAML frontmatter is complete and valid
+- [ ] BC version compatibility is specified
+- [ ] Cross-references use relative paths and exist
+- [ ] Content is atomic (one focused concept)
+- [ ] No executable code is included
+- [ ] Examples use realistic BC scenarios
+- [ ] Tags are consistent with existing taxonomy
+
+### Common Anti-Patterns to Avoid
+- ❌ **Code Repositories**: Never include .cs, .al, .js, or executable files
+- ❌ **Generic Examples**: Avoid "MyTable" - use realistic BC entities
+- ❌ **Version Ambiguity**: Never omit BC version compatibility
+- ❌ **Broken Cross-References**: Always validate links before committing
+- ❌ **Topic Drift**: Keep each file focused on ONE concept
+- ❌ **Outdated Information**: Update last_updated when making changes
+
+## Common Tasks
+- Adding new BC knowledge topics with proper frontmatter and validation
+- Updating existing topics for new BC versions with migration notes
+- Creating bidirectional cross-references between related topics
+- Validating YAML frontmatter structure and consistency
+- Organizing content within domain hierarchies and maintaining taxonomy
+- Performing content audits for accuracy and BC version compatibility
+
+## GitHub Copilot Integration Workflows
+
+### New Topic Creation Workflow
+1. **Domain Classification**: Determine primary domain from existing taxonomy
+2. **Version Research**: Identify minimum BC version and any version-specific notes
+3. **Template Application**: Use YAML frontmatter template with all required fields
+4. **Content Development**: Follow structure requirements for consistency
+5. **Cross-Reference Integration**: Add to related topics and update existing references
+6. **Validation**: Run through validation checklist before committing
+
+### Content Update Workflow
+1. **Impact Assessment**: Identify which BC versions are affected
+2. **Cross-Reference Review**: Check if related topics need updates
+3. **Version Compatibility**: Update bc_versions field if needed
+4. **Last Updated**: Always update timestamp when making changes
+5. **Validation**: Ensure all links and references remain valid
+
+### Quality Assurance Patterns
+- **Atomic Content Principle**: Each file covers exactly one BC concept
+- **Consistent Terminology**: Use official Microsoft BC terminology
+- **Practical Examples**: Include realistic Business Central scenarios
+- **Version Awareness**: Every pattern specifies BC version compatibility
+- **Link Validation**: Cross-references must be bidirectional and accurate
+
+## Integration
+This repository is consumed by the MCP server via git submodule as the embedded knowledge layer (Layer 0).

package/embedded-knowledge/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to Business Central Knowledge Base
+
+## Overview
+This repository contains pure knowledge content for Business Central best practices. All content is markdown with YAML frontmatter.
+
+## Content Standards
+
+### File Structure
+Each knowledge topic follows this structure:
+```markdown
+---
+title: "Topic Title"
+domain: "performance"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["sift", "optimization", "database"]
+related_topics: ["topic-id-1", "topic-id-2"]
+---
+
+# Topic Title
+
+Content here following established patterns...
+```
+
+### Quality Requirements
+- **Atomic Focus**: One concept per file
+- **BC Version Compatibility**: Always specify version ranges
+- **Complete Frontmatter**: All required YAML fields present
+- **Cross-References**: Link to related topics where appropriate
+- **Consistent Formatting**: Follow existing markdown patterns
+
+## Submission Process
+1. Fork the repository
+2. Create content following established patterns in appropriate domain directory
+3. Ensure YAML frontmatter is complete and valid
+4. Test that internal links work correctly
+5. Submit pull request with clear description of the knowledge added/updated
+
+## Content Validation
+Pull requests are automatically validated for:
+- YAML frontmatter completeness
+- BC version compatibility format
+- Internal link integrity
+- Proper domain/directory placement
+- Markdown formatting consistency
+
+## Domain Organization
+Place content in appropriate domain directories:
+- `domains/performance/` - Performance optimization
+- `domains/api-design/` - REST/OData patterns
+- `domains/security/` - Authentication/authorization
+- `domains/data-architecture/` - Table design
+- [See full domain list in repository structure]
+
+## Getting Help
+- Review existing topics for patterns
+- Check AGENTS.md for AI assistant guidance
+- Open issues for questions about content organization

package/embedded-knowledge/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Business Central Knowledge Base
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/embedded-knowledge/README.md

@@ -0,0 +1,32 @@
+# BC Code Intelligence Knowledge Base
+
+Pure knowledge content repository for Business Central best practices, methodologies, and domain expertise.
+
+## Structure
+- `/domains/` - 24 BC domains with 87+ atomic knowledge topics
+- `/methodologies/` - AI workflow frameworks for systematic optimization
+- `/specialists/` - 14 AI persona definitions for focused expertise
+- `/prompts/` - Strategic prompts for common BC scenarios
+
+## Specialists
+Complete roster of 14 BC development specialists:
+- **Alex Architect** - Strategic Planning & Architecture
+- **Casey Copilot** - AI-Enhanced Development Coach  
+- **Dean Debug** - Performance & Troubleshooting
+- **Eva Errors** - Error Handling & Exception Management
+- **Jordan Bridge** - Systems Connection & Event-Driven Design
+- **Logan Legacy** - Legacy Code & Version Migration
+- **Maya Mentor** - Learning & Skill Development
+- **Morgan Market** - AppSource & ISV Business Expert
+- **Quinn Tester** - Quality Validation & Test Design
+- **Roger Reviewer** - Code Quality & Review Standards
+- **Sam Coder** - Efficient Implementation Expert
+- **Seth Security** - Security & Permission Management
+- **Taylor Docs** - Documentation & Knowledge Management
+- **Uma UX** - User Experience & Interface Design
+
+## Usage
+This repository is consumed by the BC Code Intelligence MCP server via git submodule. Content is pure markdown with YAML frontmatter.
+
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md) for content standards and submission process.

package/embedded-knowledge/domains/alex-architect/api-delegate-operation-pattern.md

@@ -0,0 +1,90 @@
+---
+title: "API Delegate Operation Pattern"
+domain: "alex-architect"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["api-delegates", "operation-delegation", "api-patterns", "extensibility"]
+prerequisites: ["api-basics", "interface-implementation", "event-handling"]
+samples: "samples/api-delegate-operation.md"
+related_topics: ["api-interface-design-patterns", "event-bridge-pattern-al"]
+---
+
+# API Delegate Operation Pattern
+
+## Overview
+
+The API Delegate Operation Pattern enables flexible API architectures by delegating specific operations to external handlers while maintaining consistent API contracts. This pattern is essential for building extensible APIs that can be enhanced by different modules without modifying core API logic.
+
+**Key Benefit**: Provides extensibility points in APIs while maintaining backward compatibility and clear separation of concerns.
+
+## Strategic Framework
+
+### Delegation Architecture
+Design APIs with explicit delegation points where external modules can register operation handlers, enabling customization without API modification.
+
+### Contract Preservation
+Maintain consistent API contracts while allowing internal operation logic to be delegated to specialized handlers based on context or configuration.
+
+### Dynamic Handler Selection
+Implement runtime handler selection mechanisms that choose appropriate delegates based on operation parameters, user context, or system configuration.
+
+## Core Implementation Patterns
+
+### Operation Delegate Interface
+Define clear interfaces for operation delegates that specify input parameters, expected outputs, and error handling contracts.
+
+### Delegate Registry Pattern
+Implement registration systems where modules can register their operation delegates, enabling discovery and selection at runtime.
+
+### Chain of Responsibility Integration
+Combine delegation with chain of responsibility patterns to enable multiple delegates to process operations in sequence.
+
+## Advanced Delegation Strategies
+
+### Contextual Delegation
+Use operation context (user, company, feature flags) to determine which delegate should handle specific operations.
+
+### Fallback Delegate Chains
+Implement fallback mechanisms where multiple delegates can be attempted if primary delegates fail or are unavailable.
+
+### Composite Operation Delegation
+Design delegates that can compose multiple sub-operations, enabling complex operation workflows through delegation.
+
+## Performance Considerations
+
+### Delegate Caching
+Cache delegate instances and registration information to minimize lookup overhead during high-frequency API operations.
+
+### Lazy Delegate Loading
+Implement lazy loading patterns for delegates to avoid unnecessary initialization overhead for unused operation paths.
+
+### Operation Profiling
+Monitor delegate operation performance to identify bottlenecks and optimize critical delegation paths.
+
+## Best Practices
+
+### Design Principles
+- Define clear delegate contracts with explicit input/output specifications
+- Implement robust error handling for delegate failures
+- Use dependency injection for delegate registration and discovery
+- Document delegation points and available extension mechanisms
+
+### Security Considerations
+- Validate delegate operations for security compliance
+- Implement authorization checks for delegate registration
+- Ensure delegate operations respect user permissions and data access rules
+
+## Common Pitfalls
+
+### Over-Delegation
+Avoid creating too many delegation points that make API behavior unpredictable or difficult to debug.
+
+### Delegate Coupling
+Prevent tight coupling between API logic and specific delegate implementations that reduces flexibility.
+
+### Performance Overhead
+Be mindful of delegation overhead in performance-critical scenarios where direct operation execution might be more appropriate.
+
+*Complete delegation implementation: samples/api-delegate-operation.md*
+*API design patterns: api-interface-design-patterns.md*
+*Event-driven delegation: event-bridge-pattern-al.md*

package/embedded-knowledge/domains/alex-architect/api-fieldset-registration-pattern.md

@@ -0,0 +1,113 @@
+---
+title: "API Fieldset Registration Pattern"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["api-fieldsets", "field-registration", "api-extensibility", "metadata-driven"]
+prerequisites: ["api-basics", "fieldset-concepts", "registration-patterns"]
+samples: "samples/api-fieldset-registration.md"
+related_topics: ["api-interface-design-patterns", "api-delegate-operation-pattern"]
+---
+
+# API Fieldset Registration Pattern
+
+## Overview
+
+The API Fieldset Registration Pattern enables dynamic field management in APIs by allowing modules to register field definitions that can be included in API responses. This pattern supports extensible APIs where different modules can contribute fields without modifying core API logic.
+
+**Key Benefit**: Enables flexible, extensible APIs where field availability can be determined dynamically based on installed modules and user permissions.
+
+## Strategic Framework
+
+### Dynamic Field Discovery
+Implement registration mechanisms where modules can register field definitions that become available for API consumption based on runtime conditions.
+
+### Metadata-Driven Selection
+Use metadata to describe field characteristics, enabling intelligent field selection based on client requirements and system capabilities.
+
+### Permission-Aware Fields
+Integrate field registration with permission systems to ensure only authorized fields are exposed through API responses.
+
+## Core Registration Patterns
+
+### Module-Based Registration
+Enable modules to register their field contributions during initialization, allowing for modular field extension without core API changes.
+
+### Conditional Field Registration
+Implement registration logic that considers system configuration, feature flags, and user context to determine field availability.
+
+### Hierarchical Field Organization
+Organize registered fields in hierarchical structures that support grouping, categorization, and efficient lookup operations.
+
+## Implementation Strategies
+
+### Registry Architecture
+Design field registries that support efficient lookup, validation, and metadata management for dynamic field selection.
+
+### Field Metadata Management
+Implement comprehensive field metadata including data types, validation rules, permission requirements, and display characteristics.
+
+### Selection Optimization
+Optimize field selection algorithms to minimize performance impact when processing large numbers of registered fields.
+
+## Advanced Registration Features
+
+### Field Dependency Management
+Implement dependency tracking between fields to ensure required fields are included when dependent fields are selected.
+
+### Field Transformation Pipelines
+Design transformation pipelines that can modify field values during API response generation based on registration metadata.
+
+### Caching Strategies
+Implement caching for field registration data to improve API response performance for frequently accessed field sets.
+
+## Performance Considerations
+
+### Registration Overhead
+Minimize registration overhead through efficient storage and indexing of field metadata and registration information.
+
+### Selection Performance
+Optimize field selection algorithms to support high-frequency API operations without significant performance degradation.
+
+### Memory Management
+Implement efficient memory management for field registration data to prevent memory leaks and excessive resource usage.
+
+## Security and Validation
+
+### Permission Integration
+- Integrate field registration with permission systems
+- Validate user authorization for specific field access
+- Implement field-level security policies
+- Support dynamic permission evaluation
+
+### Data Validation
+- Validate registered field definitions for correctness
+- Implement runtime validation of field values
+- Support custom validation rules per registered field
+- Ensure data type consistency across registrations
+
+## Best Practices
+
+### Registration Design
+- Use strongly-typed field registration interfaces
+- Implement clear naming conventions for registered fields
+- Provide comprehensive metadata for each registered field
+- Support registration validation and error reporting
+
+### API Integration
+- Design consistent field selection patterns across API endpoints
+- Implement clear documentation for available fields
+- Support field discovery mechanisms for API consumers
+- Provide examples of field selection usage
+
+## Common Pitfalls
+
+### Over-Registration
+Avoid registering too many fields that can overwhelm API consumers and impact performance through excessive selection overhead.
+
+### Inconsistent Metadata
+Prevent inconsistent field metadata that can lead to unpredictable API behavior and difficult debugging scenarios.
+
+*Complete fieldset registration examples: samples/api-fieldset-registration.md*
+*API interface patterns: api-interface-design-patterns.md*
+*Dynamic API patterns: api-delegate-operation-pattern.md*

package/embedded-knowledge/domains/alex-architect/api-interface-design-patterns.md

@@ -0,0 +1,101 @@
+---
+title: "API Interface Design Patterns"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["api-interfaces", "contract-design", "api-patterns", "interface-segregation"]
+prerequisites: ["interface-basics", "api-fundamentals", "contract-design"]
+samples: "samples/api-interface-design.md"
+related_topics: ["api-delegate-operation-pattern", "api-fieldset-registration-pattern"]
+---
+
+# API Interface Design Patterns
+
+## Overview
+
+API Interface Design Patterns provide proven approaches for creating maintainable, extensible, and user-friendly API contracts. These patterns ensure APIs remain stable while supporting evolution and provide clear contracts for consumers.
+
+**Key Benefit**: Creates predictable, maintainable API contracts that support long-term evolution without breaking existing consumers.
+
+## Core Design Principles
+
+### Interface Segregation
+Design focused interfaces that serve specific purposes rather than monolithic interfaces that attempt to handle all scenarios.
+
+### Contract Stability
+Maintain backward compatibility through careful interface evolution strategies and versioning approaches.
+
+### Consumer-Centric Design
+Design interfaces from the consumer perspective, optimizing for common usage patterns and developer experience.
+
+## Essential Interface Patterns
+
+### Command-Query Separation
+Separate interfaces for operations that modify state (commands) from those that retrieve data (queries), enabling clearer contracts and better optimization opportunities.
+
+### Fluent Interface Pattern
+Design method chaining interfaces that enable expressive, readable API usage while maintaining type safety and clear operation sequencing.
+
+### Builder Interface Pattern
+Implement builder-style interfaces for complex object construction scenarios where multiple optional parameters need to be specified.
+
+## Versioning and Evolution Strategies
+
+### Additive Interface Evolution
+Design interfaces to support evolution through additive changes that don't break existing consumers while enabling new functionality.
+
+### Interface Composition
+Use interface composition to build complex API contracts from smaller, focused interface components that can evolve independently.
+
+### Deprecation Patterns
+Implement clear deprecation strategies that provide migration paths for consumers while enabling interface evolution.
+
+## Advanced Interface Patterns
+
+### Contextual Interface Adaptation
+Design interfaces that adapt their behavior based on context (user permissions, feature flags, system configuration) while maintaining consistent contracts.
+
+### Generic Interface Patterns
+Use generic interfaces to provide type-safe operations across different data types while maintaining consistent operation patterns.
+
+### Callback Interface Integration
+Integrate callback interfaces for asynchronous operations and event handling while maintaining clear contract boundaries.
+
+## Implementation Guidelines
+
+### Parameter Design
+- Use strongly-typed parameters with clear naming conventions
+- Implement validation at interface boundaries
+- Provide clear documentation for parameter requirements and constraints
+- Consider parameter object patterns for complex method signatures
+
+### Return Value Patterns
+- Design consistent return value patterns across interface methods
+- Use result objects for operations that can fail with detailed error information
+- Implement null object patterns where appropriate to avoid null reference issues
+
+## Best Practices
+
+### Documentation Standards
+- Provide comprehensive interface documentation with examples
+- Document expected behaviors, side effects, and error conditions
+- Include performance characteristics and usage guidelines
+- Maintain versioning documentation for interface evolution
+
+### Error Handling Design
+- Design consistent error handling patterns across all interface methods
+- Use typed exceptions or result objects for error communication
+- Provide actionable error messages for consumers
+- Implement proper error recovery guidance
+
+## Common Pitfalls
+
+### Interface Bloat
+Avoid creating large interfaces that try to handle too many scenarios, making them difficult to implement and maintain.
+
+### Breaking Changes
+Prevent accidental breaking changes through careful interface evolution planning and comprehensive testing strategies.
+
+*Complete interface design examples: samples/api-interface-design.md*
+*Delegation patterns: api-delegate-operation-pattern.md*
+*Registration patterns: api-fieldset-registration-pattern.md*