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

package/embedded-knowledge/domains/alex-architect/subscriber-codeunit-size-optimization.md

@@ -0,0 +1,66 @@
+---
+title: "Subscriber Codeunit Size and Organization"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["codeunit-design", "organization", "maintainability", "performance"]
+prerequisites: ["codeunit-basics", "event-subscriber-patterns"]
+samples: "samples/subscriber-organization.md"
+---
+# Subscriber Codeunit Size and Organization
+
+## Overview
+
+Subscriber codeunit size and organization significantly impact maintainability, performance, and development workflow. Proper subscriber architecture balances functional cohesion with practical constraints around codeunit compilation, deployment, and runtime performance.
+
+Large monolithic subscriber codeunits create maintenance challenges and compilation overhead, while excessive fragmentation leads to deployment complexity and runtime inefficiencies. Optimal subscriber organization requires understanding both technical constraints and business domain boundaries.
+
+The architectural decisions around subscriber codeunit size affect development team productivity, system performance, and long-term maintainability. Strategic organization patterns prevent common pitfalls while enabling scalable event-driven architectures.
+
+## Size Impact on Development
+
+Large subscriber codeunits slow development cycles through increased compilation time and complex merge conflict resolution. When multiple developers work on the same subscriber codeunit, coordination overhead increases significantly.
+
+Oversized codeunits make specific subscriber logic harder to locate and modify, reducing development velocity. Navigation through hundreds of procedures to find specific event handling logic creates unnecessary friction.
+
+Version control systems struggle with large files, making code review processes more difficult and increasing the likelihood of merge conflicts during parallel development efforts.
+
+## Functional Cohesion Principles
+
+Subscriber codeunits should group related event handling logic based on business domain or functional area rather than purely technical organization. Domain-driven organization improves maintainability and understanding.
+
+Event subscribers addressing the same business process or data entity naturally belong together, enabling shared utility functions and consistent business rule implementation across related events.
+
+Cross-cutting concerns like logging, audit trails, or security enforcement may warrant separate subscriber codeunits despite spanning multiple business domains, maintaining clean separation of concerns.
+
+## Performance Considerations
+
+Codeunit initialization overhead affects performance when subscribers are distributed across many small codeunits. Each codeunit requires separate loading and initialization, creating cumulative startup costs.
+
+Memory usage patterns differ between large consolidated codeunits and distributed smaller ones. SingleInstance subscribers particularly benefit from consolidation to minimize per-instance memory overhead.
+
+Runtime performance characteristics vary based on subscriber organization, with consolidated codeunits providing better CPU cache locality while distributed codeunits enable more granular memory management.
+
+## Deployment and Versioning
+
+Subscriber codeunit organization affects deployment granularity and rollback capabilities. Smaller codeunits enable more precise deployment control but increase deployment complexity and coordination requirements.
+
+Version management becomes more complex with highly distributed subscriber architectures, requiring careful dependency tracking and coordinated updates across multiple related codeunits.
+
+Extension development scenarios benefit from smaller, focused subscriber codeunits that minimize conflicts with base application changes and other extensions.
+
+## Maintenance Strategies
+
+Subscriber codeunits require regular refactoring to maintain optimal size as functionality grows. Established size thresholds and refactoring triggers prevent architectural degradation over time.
+
+Documentation and naming conventions become increasingly important as subscriber codeunit count grows. Clear organization patterns enable developers to quickly locate relevant event handling logic.
+
+Code analysis tools and metrics help monitor subscriber codeunit size and complexity trends, providing objective data for refactoring decisions and architectural improvements.
+
+## Organization Patterns
+
+Domain-based organization groups subscribers by business functionality, creating natural boundaries for related event handling logic and shared business rules implementation.
+
+Layer-based organization separates subscribers by architectural concerns such as data validation, business logic, and integration logic, providing clear separation of responsibilities.
+
+Hybrid organization combines domain and layer approaches, grouping related business functionality while maintaining separation between different types of event processing logic.

package/embedded-knowledge/domains/alex-architect/systemid-integration.md

@@ -0,0 +1,115 @@
+---
+title: "SystemId Integration in API Pages"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["systemid", "data-modeling", "entity-relationships"]
+samples: "samples/systemid-integration.md"
+---
+# SystemId Integration in API Pages
+
+## Overview
+
+SystemId provides a universal unique identifier for records in Business Central tables, offering significant advantages for API Page implementations. Understanding SystemId integration patterns enables robust API designs that support efficient data synchronization and external system integration.
+
+SystemId is a GUID field automatically maintained by the BC platform for most tables. This field provides stable, unique identification that remains consistent across system operations, making it ideal for external system references and API operations.
+
+Proper SystemId integration supports advanced API scenarios including optimistic concurrency control, efficient data synchronization, and reliable external system integration patterns.
+
+## SystemId Characteristics
+
+SystemId values are automatically generated and maintained by the BC platform, ensuring uniqueness across all records in the database. These values remain stable throughout the record lifecycle unless explicitly regenerated.
+
+The SystemId field is of type GUID, providing 128-bit unique identifiers that are virtually guaranteed to be unique across systems and time. This makes SystemId ideal for distributed system integration scenarios.
+
+SystemId values are immutable under normal circumstances, providing reliable external references that don't change due to business data modifications or system operations.
+
+## API Page Integration Patterns
+
+Use SystemId as the primary key or unique identifier for API Page implementations when stable external references are required. This provides consistent identification for API consumers regardless of business key changes.
+
+SystemId enables efficient OData query operations through unique record identification. API consumers can reliably reference specific records using SystemId values without depending on complex business key combinations.
+
+Consider exposing SystemId alongside business keys to provide flexible identification options for different API consumer scenarios and integration requirements.
+
+## External System Integration
+
+SystemId provides excellent external system reference capabilities, allowing external systems to maintain stable references to BC records without depending on business data that might change.
+
+External systems can store SystemId values as foreign keys or reference identifiers, enabling reliable record lookups and data synchronization operations across system boundaries.
+
+SystemId-based integration patterns support incremental synchronization scenarios where external systems need to track changes to specific BC records over time.
+
+## Data Synchronization Benefits
+
+SystemId enables efficient change tracking and synchronization operations by providing stable record identification that persists across data modifications and system operations.
+
+Synchronization processes can use SystemId values to identify specific records for update operations, avoiding complex business key matching logic that may be unreliable or inefficient.
+
+Consider implementing timestamp fields alongside SystemId for efficient change detection and synchronization optimization in high-volume scenarios.
+
+## Relationship Modeling
+
+SystemId can be used in related table structures to create stable relationships that don't depend on business key values. This provides more robust relationship models for complex data structures.
+
+Foreign key relationships using SystemId values remain valid even when business keys change, reducing the complexity of maintaining referential integrity across related tables.
+
+Consider the performance implications of SystemId-based relationships, as GUID comparisons may have different performance characteristics compared to integer-based keys.
+
+## Query Performance Considerations
+
+SystemId is typically indexed by the BC platform, providing efficient query performance for unique record lookups and equality comparisons in API operations.
+
+GUID-based queries may have different performance characteristics compared to integer or string-based queries. Consider these differences when designing high-performance API implementations.
+
+Range queries or sorting operations on SystemId fields may be less efficient than similar operations on business keys with more meaningful sort orders.
+
+## OData Integration Patterns
+
+SystemId integrates seamlessly with OData operations, providing reliable record identification for GET, PATCH, PUT, and DELETE operations through API Pages.
+
+Use SystemId in OData key segments to enable efficient record access patterns that don't depend on complex business key combinations or field ordering requirements.
+
+SystemId values work well with OData expansion operations, providing stable relationship navigation that remains consistent across API requests and system operations.
+
+## Concurrency Control Integration
+
+SystemId can be combined with ETag implementations to provide robust optimistic concurrency control in API scenarios. This combination enables reliable conflict detection and resolution.
+
+The stability of SystemId values supports long-running API operations where record identification must remain consistent across extended time periods or multiple API interactions.
+
+Consider using SystemId in combination with timestamp fields for advanced concurrency control scenarios that require both unique identification and change detection.
+
+## Migration and Data Import Scenarios
+
+SystemId values can be preserved during data migration operations, maintaining external system references and integration consistency across system transitions.
+
+Data import processes should consider SystemId handling requirements, especially when maintaining references from external systems or preserving integration relationships.
+
+Plan for SystemId regeneration scenarios that might be required during major system upgrades or data restructuring operations that affect external system integration.
+
+## Security and Access Control
+
+SystemId values are generally safe to expose through API interfaces as they don't reveal sensitive business information while providing unique identification capabilities.
+
+Consider SystemId exposure in security models, as these values provide persistent record identification that could be used in unauthorized access attempts over extended time periods.
+
+SystemId-based access control patterns can provide more granular security implementations compared to business key-based approaches, especially in multi-tenant scenarios.
+
+## Testing and Validation
+
+Implement proper testing for SystemId-based API operations, including validation of unique identification, relationship consistency, and external system integration scenarios.
+
+Test SystemId behavior across different BC operations including record creation, modification, deletion, and restoration to ensure consistent integration behavior.
+
+Validate SystemId performance characteristics under realistic data volumes and query patterns to ensure scalable API implementations.
+
+## Best Practices
+
+Use SystemId for external system integration scenarios where stable, unique identification is required across system boundaries and extended time periods.
+
+Consider combining SystemId with business keys to provide flexible identification options that support different API consumer requirements and usage patterns.
+
+Document SystemId integration decisions and patterns for API implementations to ensure consistent approaches and support ongoing maintenance requirements.
+
+Plan for SystemId lifecycle management in scenarios involving data archiving, system migrations, or major structural changes that might affect external system integration.

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

@@ -0,0 +1,77 @@
+---
+title: "Designing Code for Testability in Isolation"
+domain: "alex-architect"
+difficulty: "advanced"
+bc_versions: "18+"
+tags: ["testability", "dependency-injection", "interfaces", "decoupling", "architecture", "design-patterns"]
+samples: "samples/testability-design-patterns.md"
+related_topics:
+  - "../quinn-tester/isolation-testing-patterns.md"
+  - "../roger-reviewer/testability-code-smells.md"
+  - "api-interface-design-patterns.md"
+source: "Adapted from Vjeko.com: Testing in isolation (Dec 2023)"
+---
+# Designing Code for Testability in Isolation
+
+## Overview
+
+Testing in isolation means testing each component independently from its dependencies. This requires intentional architectural decisions—code that "just works" often cannot be tested in isolation because dependencies are tightly coupled.
+
+**Core Principle**: If you can imagine substituting a component with an alternative implementation, that component is a dependency that should be abstracted.
+
+## The Tight Coupling Problem
+
+Typical BC code directly references base app tables, system functions, or external services. To test such code, you must set up all those dependencies—creating records, configuring exchange rates, etc.
+
+**The real problem**: You end up testing Microsoft's code (or external systems), not YOUR business logic. Tests become complex setups of dependencies irrelevant to what you're actually validating.
+
+## Recognizing Dependencies
+
+A dependency is any component your code relies on that could theoretically be substituted. Ask: "Could I imagine using a different implementation?"
+
+**Common BC Dependencies**:
+- Base app tables (Currency, Customer, Item)
+- System app functions (date calculations, formatting)
+- External services (APIs, file systems, HTTP)
+- BC standard routines (posting, conversion, calculation)
+
+**Your Own Dependencies**:
+- Permission/authorization checks
+- Logging/auditing
+- Notification systems
+- Configuration lookups
+
+## The Interface Abstraction Pattern
+
+The only clean way to decouple in AL is through interfaces. The pattern has four steps:
+
+1. **Define the abstraction** - Create an interface describing WHAT, not HOW
+2. **Create production implementation** - Wrap the real dependency
+3. **Inject the dependency** - Pass interfaces to business logic
+4. **Provide backward compatibility** - Overloads for existing callers
+
+This allows substituting test doubles during testing while maintaining production behavior for real callers.
+
+## Multi-Dependency Architecture
+
+Real business logic often has multiple dependencies. A process might need permission checking, core calculation, and logging. Each becomes an interface, and business logic becomes clean orchestration of those abstractions.
+
+## Benefits
+
+- **Testability**: Test business logic without database setup
+- **Flexibility**: Swap implementations without changing business logic
+- **Maintainability**: Clear separation of concerns
+- **Robustness**: Tests don't break when dependencies change
+
+## Common Anti-Pattern: The Setup Switch
+
+Configuration-driven branching (`case Setup.Type of...`) is NOT decoupling—it's MORE coupling. You now have two tight dependencies instead of one, and tests still must choose a path. Use interfaces instead.
+
+## Design Guidelines
+
+**Abstract**: External calls, BC base app functionality, cross-cutting concerns, anything with alternative implementations.
+
+**Don't Abstract**: Simple value assignments, basic AL features, trivial calculations.
+
+See samples for complete implementation examples with interfaces, production implementations, and backward-compatible overloads.
+

package/embedded-knowledge/domains/casey-copilot/long-running-session-instructions.md

@@ -0,0 +1,263 @@
+---
+title: "Effective Instructions for Long-Running AI Sessions"
+domain: "casey-copilot"
+difficulty: "intermediate"
+bc_versions: "18+"
+tags: ["ai-development", "instructions", "prompts", "agentic-coding", "context-management", "best-practices"]
+samples: "samples/long-running-session-instructions.md"
+related_topics:
+  - "project-context-files.md"
+  - "incremental-development-patterns.md"
+source: "Adapted from Anthropic Engineering: Effective harnesses for long-running agents (Nov 2025)"
+---
+# Effective Instructions for Long-Running AI Sessions
+
+## Overview
+
+AI coding agents face a fundamental challenge: each new session starts with no memory of previous work. This topic provides guidance for writing instructions that help AI agents work effectively across multiple sessions on BC development projects.
+
+**Core Insight**: The same practices that make human developers effective on shift-based projects—clear handoffs, incremental progress, documented state—make AI agents effective across context windows.
+
+## The Long-Running Agent Problem
+
+When AI agents work on complex BC projects that span multiple sessions, two failure patterns emerge:
+
+1. **One-Shot Overreach**: The agent tries to implement too much at once, runs out of context mid-implementation, and leaves features half-built and undocumented.
+
+2. **Premature Victory**: After some progress, the agent sees existing work and declares the job done, missing remaining requirements.
+
+**Solution**: Structure your instructions to enforce incremental progress with clean handoffs between sessions.
+
+## Key Instruction Components
+
+### 1. Environment Orientation
+
+Start every session with instructions that help the agent understand the current state:
+
+```
+Before starting work:
+1. Read PROGRESS.md to understand what was recently completed
+2. Check the current git status and recent commits
+3. Review any open issues or TODO items
+4. Run the existing tests to verify the baseline works
+```
+
+**Why This Works**: Agents can quickly identify if the app is broken and fix it before adding new features—rather than making problems worse.
+
+### 2. Feature Lists Over Vague Goals
+
+Instead of "build a customer integration," provide structured requirements:
+
+```
+## Features to Implement
+
+- [ ] Customer lookup by external ID returns matching BC customer
+- [ ] New external customers create BC customer record with defaults
+- [ ] Customer updates sync specific fields: Name, Address, Phone
+- [ ] Failed syncs log to Integration Log table with error details
+- [ ] Retry mechanism attempts failed syncs every 15 minutes
+```
+
+**Why This Works**: 
+- Agents have clear scope boundaries
+- Progress is measurable
+- No ambiguity about what "done" means
+- Prevents both overreach and premature victory
+
+### 3. Incremental Progress Requirements
+
+Explicitly instruct agents to work one feature at a time:
+
+```
+## Working Pattern
+
+1. Choose ONE feature from the list that's not yet complete
+2. Implement that single feature fully
+3. Test the feature works end-to-end
+4. Commit with a descriptive message
+5. Update PROGRESS.md with what was done
+6. Mark the feature as complete in the checklist
+7. STOP and wait for next session
+
+Do NOT attempt to implement multiple features in one session.
+```
+
+**Why This Works**: Each session ends with the codebase in a clean, mergeable state rather than mid-implementation chaos.
+
+### 4. Clean State Requirements
+
+Require agents to leave the environment ready for the next session:
+
+```
+## End of Session Checklist
+
+Before ending work:
+- [ ] All code compiles without errors
+- [ ] New code has been committed with descriptive message
+- [ ] PROGRESS.md updated with session summary
+- [ ] Any known issues documented in ISSUES.md
+- [ ] Development server can start successfully
+- [ ] Basic functionality still works (quick smoke test)
+
+It is unacceptable to leave the codebase in a broken state.
+```
+
+**Why This Works**: The next session (or human developer) can start immediately without cleanup work.
+
+### 5. Progress Tracking Files
+
+Create dedicated files for state that persists across sessions:
+
+**PROGRESS.md** - What's been done:
+```markdown
+# Project Progress
+
+## Completed Features
+- 2024-01-15: Customer lookup by external ID (commit abc123)
+- 2024-01-15: Customer creation with defaults (commit def456)
+
+## Current Status
+Working on: Customer update sync
+Last session ended: Mid-implementation of field mapping
+
+## Known Issues
+- Phone number formatting needs attention (logged, not blocking)
+```
+
+**FEATURES.json** - What needs to be done (JSON is harder for AI to accidentally modify):
+```json
+{
+  "features": [
+    { "id": 1, "description": "Customer lookup by external ID", "passes": true },
+    { "id": 2, "description": "Customer creation with defaults", "passes": true },
+    { "id": 3, "description": "Customer update field sync", "passes": false }
+  ]
+}
+```
+
+### 6. Testing Requirements
+
+Require verification, not just implementation:
+
+```
+## Verification Requirements
+
+A feature is NOT complete until:
+1. Unit tests pass for the new code
+2. Integration tests verify end-to-end behavior
+3. Manual verification confirms it works as expected
+4. The feature is tested in context of existing functionality
+
+Do NOT mark a feature as passing based on code review alone.
+You must actually run and verify the feature works.
+```
+
+**Why This Works**: Prevents the common failure of marking features complete without proper testing.
+
+## BC-Specific Instruction Patterns
+
+### For Extension Development
+
+```
+## BC Extension Context
+
+This is a Business Central extension project.
+- app.json defines the extension metadata and dependencies
+- src/ contains AL source files organized by object type
+- test/ contains test codeunits
+
+Before making changes:
+1. Verify the extension compiles (Ctrl+Shift+B)
+2. Run existing tests to confirm baseline
+3. Check app.json for BC version requirements
+
+After making changes:
+1. Ensure extension still compiles
+2. Run all tests, not just new ones
+3. Commit with BC-standard commit message format
+```
+
+### For Multi-Object Features
+
+```
+## Multi-Object Feature Implementation
+
+When implementing features that span multiple AL objects:
+1. Implement table changes first (schema)
+2. Add codeunit logic second (business rules)
+3. Create/update page last (UI)
+4. Write tests alongside each object
+
+Do NOT create all objects at once and hope they work together.
+Build incrementally and verify each layer.
+```
+
+### For Integration Projects
+
+```
+## Integration Development Pattern
+
+External system integrations must be:
+1. Wrapped in Try functions for error handling
+2. Logged via custom telemetry for production support
+3. Tested with mock responses before live testing
+4. Documented with expected request/response formats
+
+Use Codeunit.Run() with result capture for operations 
+that include database writes after external calls.
+```
+
+## Anti-Patterns to Avoid in Instructions
+
+### ❌ Vague Goals
+```
+Build the customer sync feature.
+```
+
+### ✅ Specific Deliverables
+```
+Implement customer sync with these behaviors:
+1. Lookup existing customer by external ID
+2. Create new customer if not found
+3. Update specified fields if found
+4. Log all operations to Integration Log
+```
+
+### ❌ No State Management
+```
+Continue working on the project.
+```
+
+### ✅ Explicit State Reading
+```
+1. Read PROGRESS.md for recent session summaries
+2. Check git log for latest commits
+3. Review FEATURES.json for completion status
+4. Run tests to verify current state
+```
+
+### ❌ Unlimited Scope
+```
+Implement as many features as you can.
+```
+
+### ✅ Bounded Scope
+```
+Implement exactly ONE feature from the uncompleted list.
+Commit, document, and stop.
+```
+
+## Summary: The Effective Instructions Checklist
+
+When writing instructions for long-running AI sessions:
+
+- [ ] **Orientation**: How does the agent understand current state?
+- [ ] **Scope**: What specific features/tasks are in scope?
+- [ ] **Boundaries**: What should the agent NOT attempt?
+- [ ] **Progress Tracking**: Where is state recorded between sessions?
+- [ ] **Verification**: How must features be tested before completion?
+- [ ] **Clean Exit**: What must be true before the session ends?
+- [ ] **Handoff**: What does the next session need to know?
+
+The goal is simple: **Each session should leave the project better than it found it, with clear documentation of what happened and what comes next.**
+