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

package/embedded-knowledge/domains/dean-debug/table-key-requirements.md

@@ -0,0 +1,79 @@
+---
+title: "API Page Source Table Key Requirements"
+domain: "dean-debug"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["api-pages", "table-keys", "performance"]
+samples: "samples/table-key-requirements.md"
+---
+# API Page Source Table Key Requirements
+
+## Overview
+
+API Pages require specific table key configurations to ensure optimal OData query performance and proper data access patterns. Understanding these requirements is critical for high-performance API implementations that scale effectively under production loads.
+
+The BC platform automatically generates OData endpoints based on table key structures, making key design decisions directly impact API query performance. Poor key design can result in full table scans and timeout errors in API consumers.
+
+## Primary Key Requirements
+
+API Pages must have a well-defined primary key that serves as the unique identifier for OData operations. The primary key becomes the basis for individual record retrieval operations through the API endpoint.
+
+Single-field primary keys perform better than composite keys for API operations. The SystemId field, when available, provides optimal performance as it's a GUID field with guaranteed uniqueness and efficient indexing characteristics.
+
+Composite primary keys require careful consideration of field ordering to ensure the most selective fields appear first in the key definition. This ordering directly impacts query performance when API consumers filter on subset of key fields.
+
+## Secondary Key Performance Impact
+
+Secondary keys on API Page source tables significantly impact OData query performance. Each secondary key becomes a potential filter path for API consumers, and poorly designed keys can create performance bottlenecks.
+
+Keys supporting common API query patterns should be prioritized. Consider the typical filtering, sorting, and grouping requirements of API consumers when designing secondary keys for optimal query execution.
+
+The BC platform may automatically select keys for query execution based on OData filter parameters. Understanding this selection logic helps predict and optimize actual query performance under different usage patterns.
+
+## Key Field Selection Criteria
+
+Choose key fields based on query selectivity and data distribution. Fields with high cardinality and even distribution provide better performance than fields with skewed data patterns or low selectivity.
+
+Avoid including large text fields or blob fields in key definitions as these impact both storage requirements and query performance. Keys should focus on efficient identifier and categorization fields.
+
+Consider the impact of key fields on data modification operations. Fields that change frequently should be avoided in secondary keys as this requires key maintenance overhead during data updates.
+
+## OData Query Optimization
+
+API Page key design directly influences OData query compilation and execution. The BC platform analyzes available keys when translating OData filters into SQL query patterns.
+
+Complex OData queries may require specific key combinations to avoid performance issues. Understanding common API consumer query patterns helps identify required key structures during design phase.
+
+Query performance monitoring should include analysis of key usage patterns to identify optimization opportunities. Unused keys consume storage and maintenance overhead without providing performance benefits.
+
+## Multi-Tenancy Considerations
+
+In multi-tenant environments, key design must consider tenant isolation requirements. Keys may need to include tenant-specific fields to ensure proper data segregation and performance isolation.
+
+DataPerCompany table property affects key performance characteristics. Tables with DataPerCompany = false require additional consideration for key design to maintain performance across tenant boundaries.
+
+Global tables require careful key design to prevent cross-tenant data access issues while maintaining query performance for legitimate multi-tenant scenarios.
+
+## Performance Monitoring
+
+Monitor API Page query performance through BC telemetry and database performance metrics. Key performance indicators include query execution time, index usage patterns, and resource consumption.
+
+Identify queries that result in table scans or inefficient key usage. These represent optimization opportunities through key design improvements or query pattern adjustments.
+
+Regular performance analysis should include review of key effectiveness and identification of missing key requirements based on actual usage patterns.
+
+## Common Implementation Issues
+
+Missing or inappropriate primary keys result in poor OData query performance and potential data consistency issues. Ensure every API Page source table has an appropriate primary key definition.
+
+Excessive secondary keys can impact data modification performance without providing corresponding query benefits. Focus key design on actual API consumer requirements rather than theoretical optimization.
+
+Key field data type mismatches between related tables can prevent efficient join operations in complex OData queries. Maintain consistent data types across related table key fields.
+
+## Best Practices
+
+Design keys based on actual API consumer requirements rather than generic optimization principles. Understanding real-world usage patterns drives effective key design decisions.
+
+Balance query performance requirements with data modification overhead. Keys provide query benefits but incur maintenance costs during data updates.
+
+Document key design decisions and performance assumptions for future optimization efforts. This documentation helps maintain design consistency and supports performance troubleshooting.

package/embedded-knowledge/domains/dean-debug/telemetry-error-correlation.md

@@ -0,0 +1,78 @@
+---
+title: "Telemetry Error Correlation"
+domain: "dean-debug"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["telemetry", "debugging", "correlation", "troubleshooting"]
+prerequisites: ["bc-session-logmessage-methods"]
+samples: "samples/error-correlation.md"
+---
+# Telemetry Error Correlation
+
+## Overview
+
+Error correlation links related telemetry events across different system components to provide complete context for troubleshooting. Effective correlation enables rapid root cause analysis by connecting error symptoms with underlying causes across complex business processes.
+
+Business Central's telemetry correlation mechanisms support both automatic session-based correlation and custom correlation identifiers that span multiple sessions or system boundaries.
+
+## Correlation Mechanisms
+
+### Session-Based Correlation
+Business Central automatically correlates telemetry events within the same user session using system-generated session identifiers. This automatic correlation links events from the same user interaction across different codeunits and operations.
+
+Session correlation works effectively for single-user operations but has limitations for background processes, integration scenarios, or operations that span multiple sessions.
+
+### Custom Correlation Identifiers
+Custom correlation identifiers enable linking related events across session boundaries. These identifiers can represent business processes, document workflows, or integration operations that span multiple system interactions.
+
+Implement custom correlation using consistent identifier generation and inclusion in custom dimensions across all related telemetry events. Choose correlation identifiers that meaningfully represent business processes or technical operations.
+
+### Operation Context Correlation
+Operation-level correlation links events within specific business operations like document posting, report generation, or integration processing. This correlation level bridges the gap between session correlation and business process correlation.
+
+## Implementation Patterns
+
+### Error Event Design
+Structure error telemetry events to include comprehensive context for troubleshooting. Include business context (document numbers, customer identifiers), technical context (component names, operation types), and correlation context (session, operation, process identifiers).
+
+Design error events to capture both immediate error conditions and related context that supports root cause analysis. Consider including preceding events or system state information that helps explain error conditions.
+
+### Correlation Propagation
+Propagate correlation identifiers consistently across all components involved in business processes. Ensure correlation identifiers flow through integration boundaries, background job execution, and external system interactions.
+
+Use parameter passing, global variables, or context objects to maintain correlation identifiers throughout business process execution. Design correlation propagation to be resilient to error conditions and system boundaries.
+
+### Multi-Level Correlation
+Implement multiple correlation levels to support different troubleshooting scenarios. Combine session-level, operation-level, and business process-level correlation to enable both detailed technical analysis and high-level business impact assessment.
+
+## Troubleshooting Applications
+
+### Root Cause Analysis
+Use correlation identifiers to trace error conditions back to their originating causes. Link error symptoms visible to users with underlying technical issues across multiple system components.
+
+Correlation enables analysis of error cascades where initial problems trigger subsequent failures across related components or business processes.
+
+### Integration Debugging
+Correlation is essential for debugging integration scenarios where errors may occur in external systems but manifest as Business Central issues. Link Business Central telemetry with external system logs using shared correlation identifiers.
+
+### Performance Issue Investigation
+Use correlation to link performance symptoms with underlying causes. Correlate user-reported performance issues with system resource utilization, database performance, or integration latency across multiple components.
+
+## Advanced Correlation Patterns
+
+### Hierarchical Correlation
+Implement hierarchical correlation structures that represent complex business processes with multiple sub-operations. Use parent-child correlation relationships to organize telemetry events into logical groupings.
+
+### Cross-System Correlation
+Extend correlation across system boundaries to link Business Central events with external system activities. Include shared correlation identifiers in integration messages and API calls to enable comprehensive troubleshooting.
+
+### Temporal Correlation
+Consider time-based correlation patterns that link events occurring within specific time windows. This approach helps identify related issues that may not share explicit correlation identifiers.
+
+## Analysis and Tooling
+
+### Correlation Queries
+Design Application Insights queries that leverage correlation identifiers for effective troubleshooting analysis. Create saved queries and dashboards that utilize correlation patterns for routine troubleshooting tasks.
+
+### Automated Correlation Analysis
+Consider implementing automated analysis that identifies correlation patterns and potential root causes. Use correlation data to build troubleshooting decision trees and diagnostic workflows.

package/embedded-knowledge/domains/dean-debug/telemetry-performance-considerations.md

@@ -0,0 +1,83 @@
+---
+title: "Telemetry Performance Considerations"
+domain: "dean-debug"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["telemetry", "performance", "optimization", "monitoring"]
+prerequisites: ["bc-session-logmessage-methods", "custom-dimensions-best-practices"]
+samples: "samples/telemetry-performance.md"
+---
+# Telemetry Performance Considerations
+
+## Overview
+
+Telemetry implementation significantly impacts system performance through CPU utilization, memory consumption, and network overhead. Understanding these performance characteristics enables effective telemetry design that balances diagnostic capability with system efficiency.
+
+Telemetry overhead scales with event frequency, custom dimension complexity, and verbosity levels. High-volume telemetry scenarios require careful optimization to prevent performance degradation in production environments.
+
+## CPU Performance Impact
+
+### Message Formatting Overhead
+LogMessage calls incur CPU overhead for message string formatting regardless of verbosity filtering. Complex message formatting with string concatenation or expensive calculations impacts performance even when events are ultimately filtered.
+
+Optimize message formatting by using simple string operations and pre-calculating expensive values. Consider lazy evaluation patterns for complex message content that may not be needed in all scenarios.
+
+### Custom Dimension Processing
+Custom dimension serialization consumes CPU resources proportional to dimension count and value complexity. Large dimension collections or complex dimension values can significantly impact telemetry performance.
+
+Minimize dimension processing overhead by pre-formatting dimension values, reusing dimension collections, and avoiding expensive calculations within dimension generation code.
+
+### Frequency Impact
+Telemetry performance impact scales directly with event frequency. High-frequency telemetry in performance-critical code paths can measurably impact overall system performance.
+
+Consider telemetry frequency when implementing logging in loops, frequent business operations, or real-time processing scenarios. Use sampling strategies to reduce event volume while preserving analytical value.
+
+## Memory Utilization
+
+### Event Buffering
+The telemetry system buffers events before transmission, consuming memory proportional to event volume and buffering duration. High-volume telemetry can increase memory pressure, particularly in memory-constrained environments.
+
+Monitor telemetry memory utilization and consider event volume in memory capacity planning. Implement backpressure mechanisms if telemetry volume threatens system memory stability.
+
+### Custom Dimension Storage
+Custom dimensions consume memory for key-value pair storage and serialization. Large dimension collections or string-heavy dimension values can contribute significantly to overall memory utilization.
+
+Optimize dimension memory usage by using efficient data types, minimizing string allocations, and reusing dimension objects where possible.
+
+### Correlation Data
+Correlation mechanisms may maintain in-memory state to link related telemetry events across time. Long-running correlations or high-cardinality correlation scenarios can impact memory utilization.
+
+## Network and I/O Considerations
+
+### Transmission Overhead
+Telemetry events consume network bandwidth for transmission to monitoring systems. High-volume telemetry can impact network performance, particularly in bandwidth-constrained environments.
+
+Consider telemetry network impact in overall network capacity planning. Implement local buffering and batch transmission strategies to optimize network utilization efficiency.
+
+### Monitoring System Impact
+Large telemetry volumes can overwhelm monitoring systems and impact query performance in Application Insights or other telemetry backends. Consider backend capacity when designing telemetry volume strategies.
+
+### Storage and Retention
+Telemetry events consume storage space in monitoring systems with associated cost implications. Balance diagnostic capability with storage costs and retention requirements.
+
+## Optimization Strategies
+
+### Strategic Verbosity Management
+Use verbosity levels strategically to control telemetry volume in production environments. Filter high-verbosity events in production while maintaining essential diagnostic capability.
+
+### Sampling Implementation
+Implement telemetry sampling for high-volume scenarios to reduce data volume while preserving statistical significance. Consider business-aware sampling that maintains critical event capture.
+
+### Conditional Telemetry
+Implement conditional telemetry patterns that enable detailed logging during specific scenarios without permanent performance overhead. Use feature flags or configuration settings to control telemetry behavior.
+
+### Batch Processing
+Group telemetry events into batches where possible to optimize transmission efficiency and reduce per-event overhead. Balance batching benefits with real-time monitoring requirements.
+
+## Performance Monitoring
+
+### Telemetry System Monitoring
+Monitor telemetry system performance including event volume, processing latency, and resource utilization. Telemetry overhead should be measured and tracked as part of overall system performance.
+
+### Impact Analysis
+Regularly analyze telemetry performance impact through load testing and production monitoring. Understand telemetry overhead trends and optimize configurations based on actual impact measurements.

package/embedded-knowledge/domains/dean-debug/telemetry-verbosity-strategy.md

@@ -0,0 +1,76 @@
+---
+title: "Telemetry Verbosity Strategy"
+domain: "dean-debug"
+difficulty: "beginner"
+bc_versions: "14+"
+tags: ["telemetry", "verbosity", "production", "diagnostics"]
+prerequisites: ["bc-session-logmessage-methods"]
+samples: "samples/verbosity-strategy.md"
+---
+# Telemetry Verbosity Strategy
+
+## Overview
+
+Telemetry verbosity controls determine which events are captured and transmitted to monitoring systems. Effective verbosity strategy balances diagnostic capability with system performance and storage costs.
+
+Business Central provides five verbosity levels from Critical (1) to Verbose (5). Production environments typically filter higher verbosity levels to reduce telemetry volume while preserving essential diagnostic information.
+
+## Verbosity Levels
+
+### Critical (Level 1)
+Critical events indicate system failures or conditions that prevent normal operation. These events should always be captured and typically trigger immediate alerting in production environments.
+
+Use Critical verbosity for unrecoverable errors, system component failures, and conditions that impact business continuity. Critical events warrant immediate attention and investigation.
+
+### Error (Level 2)
+Error events indicate recoverable problems that impact specific operations but don't prevent overall system function. These events should be captured in production for troubleshooting and trend analysis.
+
+Use Error verbosity for operation failures, data validation issues, and integration problems that affect individual transactions or users.
+
+### Warning (Level 3)
+Warning events indicate potential problems or unusual conditions that don't immediately impact operations. These events help identify emerging issues before they become critical problems.
+
+Use Warning verbosity for performance degradation, configuration issues, and deprecated functionality usage that may require attention.
+
+### Normal (Level 4)
+Normal events capture significant business operations and system activities for operational monitoring and business intelligence. These events provide insight into system usage and business process execution.
+
+Use Normal verbosity for successful business transactions, user actions, and integration activities that support operational analysis.
+
+### Verbose (Level 5)
+Verbose events provide detailed diagnostic information for troubleshooting and development scenarios. These events are typically filtered in production environments due to volume considerations.
+
+Use Verbose verbosity for detailed execution traces, debugging information, and granular operational details needed for development and testing scenarios.
+
+## Production Strategy
+
+### Baseline Configuration
+Establish production verbosity baselines that capture essential diagnostic information without overwhelming monitoring systems. Typical production configurations capture Critical through Normal levels.
+
+Consider business requirements, troubleshooting needs, and storage capacity when establishing baseline verbosity levels. Adjust baselines based on operational experience and incident analysis needs.
+
+### Dynamic Adjustment
+Implement capabilities to adjust verbosity levels dynamically during incident investigation or troubleshooting scenarios. Temporary verbosity increases can provide additional diagnostic information without permanent overhead.
+
+Consider implementing verbosity level controls that can be adjusted per component or business process to focus additional telemetry on specific problem areas.
+
+## Development Strategy
+
+### Testing and Development
+Use higher verbosity levels during development and testing to capture detailed execution information. Verbose telemetry supports debugging, performance analysis, and integration testing scenarios.
+
+Consider separate verbosity configurations for different environments to optimize telemetry capture for each environment's specific needs.
+
+### Performance Testing
+Include telemetry verbosity impact in performance testing scenarios. High verbosity levels can significantly impact system performance and should be considered in capacity planning.
+
+## Implementation Considerations
+
+### Performance Impact
+Higher verbosity levels increase CPU, memory, and network utilization for telemetry processing and transmission. Consider telemetry overhead in overall system performance planning.
+
+### Storage and Cost Management
+Telemetry volume directly impacts monitoring system storage requirements and costs. Balance diagnostic capability with storage capacity and cost constraints.
+
+### Filtering and Sampling
+Consider implementing telemetry sampling strategies for high-volume scenarios to reduce data volume while preserving statistical significance for analysis.

package/embedded-knowledge/domains/dean-debug/testfield-performance.md

@@ -0,0 +1,104 @@
+---
+title: "TestField Performance Optimization"
+domain: "dean-debug"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["performance", "validation", "optimization", "best-practices"]
+prerequisites: ["testfield-basic-syntax", "performance-fundamentals"]
+---
+# TestField Performance Optimization
+
+## Overview
+
+TestField operations are lightweight but can impact performance when used extensively in loops or batch processing. Understanding TestField performance characteristics enables optimal validation strategies for high-volume scenarios.
+
+**Performance Principle**: TestField has minimal overhead for individual calls but cumulative impact in high-volume operations requires optimization strategies.
+
+## Performance Characteristics
+
+### Individual Call Performance
+Single TestField calls have negligible performance impact. The method performs simple null/empty checks without database operations.
+
+### Batch Processing Impact
+In loops processing hundreds or thousands of records, cumulative TestField overhead becomes measurable and should be optimized.
+
+### Error Handling Overhead
+TestField errors trigger exception handling mechanisms. In scenarios with frequent validation failures, this overhead can be significant.
+
+## Optimization Strategies
+
+### Conditional Validation
+Apply validation intensity based on processing context. Critical validations always execute while optional validations run only when required, reducing overhead in performance-sensitive scenarios.
+
+### Early Exit Patterns
+Perform lightweight data checks before expensive TestField calls. Exit processing early when data fails simple validation tests, avoiding unnecessary validation overhead.
+
+### Grouped Validation
+Pre-validate multiple fields using simple checks before calling TestField. Only invoke TestField for final validation with proper error messages after confirming basic data validity.
+
+## High-Volume Scenarios
+
+### Batch Import Optimization
+Combine pre-validation checks with TryFunction patterns to handle validation failures gracefully in batch processing. Prevents single validation failures from terminating entire batch operations.
+
+### Loop Processing Optimization
+Use record filters to exclude obviously invalid records before processing loops. Combine with TryFunction patterns to track processing success rates and continue batch processing despite individual record failures.
+
+## Memory and Resource Considerations
+
+### Temporary Record Usage
+Use temporary records for batch validation scenarios to minimize database locks and improve overall performance.
+
+### SetRange Before Validation
+Apply appropriate filters before validation loops to reduce record set size and improve processing efficiency.
+
+### Transaction Management
+Group validation operations within appropriate transaction boundaries to minimize database round trips.
+
+## Performance Testing Patterns
+
+### Baseline Measurement
+```al
+procedure MeasureValidationPerformance(RecordCount: Integer)
+var
+    Customer: Record Customer;
+    StartTime: Time;
+    EndTime: Time;
+    Duration: Duration;
+begin
+    StartTime := Time();
+    
+    if Customer.FindSet() then
+        repeat
+            Customer.Name.TestField();
+            Customer."Customer Posting Group".TestField();
+        until (Customer.Next() = 0) or (Customer.Count >= RecordCount);
+    
+    EndTime := Time();
+    Duration := EndTime - StartTime;
+    Message('Validation time for %1 records: %2', RecordCount, Duration);
+end;
+```
+
+### Comparative Analysis
+Compare TestField performance against manual validation approaches to identify optimal patterns for specific scenarios.
+
+## Integration with Other Performance Patterns
+
+### SIFT Integration
+TestField validation combined with SIFT-optimized queries provides efficient data validation patterns.
+
+### Caching Strategies
+Cache frequently validated lookup data to minimize database access during intensive validation scenarios.
+
+### Parallel Processing
+Consider parallel processing patterns for independent record validation in high-volume scenarios.
+
+## Monitoring and Diagnostics
+
+### Performance Counter Integration
+Monitor TestField usage patterns in production environments to identify performance bottlenecks.
+
+### Error Rate Analysis
+Track validation error rates to optimize validation logic and improve user experience.
+

package/embedded-knowledge/domains/eva-errors/codeunit-run-pattern.md

@@ -0,0 +1,159 @@
+---
+title: "Codeunit.Run() Error Handling Pattern"
+domain: "eva-errors"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["codeunit-run", "error-handling", "transactions", "commit", "isolation"]
+samples: "samples/codeunit-run-pattern.md"
+related_topics:
+  - "try-function-usage.md"
+  - "testfield-error-handling.md"
+---
+# Codeunit.Run() Error Handling Pattern
+
+## Overview
+
+The `if Codeunit.Run() then` pattern is a fundamental error handling mechanism in Business Central that enables transaction isolation and error recovery. Unlike try functions, this pattern allows write operations within its scope, making it essential for robust business process implementation.
+
+**Core Principle**: Capturing the boolean result from Codeunit.Run() fundamentally changes its behavior—enabling isolated transactions with error suppression and recovery.
+
+## How It Works
+
+### Standard Codeunit.Run()
+When you call `Codeunit.Run(CodeunitID)` without capturing the result:
+- Executes in the current transaction context
+- Errors propagate up and terminate execution
+- No special transaction handling occurs
+
+### Captured Result Pattern
+When you call `if Codeunit.Run(CodeunitID) then`:
+- A **new transaction** is started for the codeunit execution
+- If the codeunit succeeds, the transaction is committed
+- If the codeunit fails, the transaction is rolled back
+- Errors are **suppressed**—they don't terminate execution
+- The calling code continues regardless of success or failure
+- The developer must capture errors using GetLastErrorText()
+
+## Transaction Behavior
+
+### Transaction Isolation
+The captured Codeunit.Run() creates a transaction boundary:
+- All database operations inside the codeunit are isolated
+- Success commits all changes atomically
+- Failure rolls back all changes completely
+- The calling transaction is unaffected by the codeunit's outcome
+
+### Critical Requirement: Commit Before Run
+**Any open transaction MUST be committed before calling Codeunit.Run() with result capture.**
+
+This is required because:
+- The new transaction cannot begin while another is pending
+- Uncommitted changes from the caller would be in an undefined state
+- The runtime requires a clean transaction state
+
+Failure to commit first will result in a runtime error.
+
+## Implementation Guidelines
+
+### Proper Placement
+Use this pattern at logical boundaries in your processes:
+- Between major process phases
+- At the start of independent operations
+- When calling potentially failing external integrations
+- For batch processing individual records
+
+### Avoid Mid-Process Usage
+Do NOT use this pattern in the middle of a transaction sequence:
+- Commit() has permanent effects—it cannot be undone
+- Partial commits can leave data in inconsistent states
+- Plan your process flow to have clean commit points
+
+### Error Capture
+Always capture and handle errors when using this pattern:
+- Check the boolean result immediately
+- Use GetLastErrorText() to get error details
+- Log, notify, or take corrective action as appropriate
+
+## Use Cases
+
+### Batch Processing
+Process multiple records where individual failures shouldn't stop the entire batch:
+```
+// Conceptual pattern:
+foreach record in batch do begin
+    Commit();  // Clean slate for each record
+    if Codeunit.Run(ProcessorCodeunit, record) then
+        SuccessCount += 1
+    else begin
+        LogError(record, GetLastErrorText());
+        FailureCount += 1;
+    end;
+end;
+```
+
+### External Integration Points
+Isolate external system calls that include database updates:
+- Prepare staging data
+- Commit current transaction
+- Run integration codeunit with capture
+- Handle success or failure appropriately
+
+### Optional Processing Steps
+For process steps that should not block the main flow:
+- Archive operations
+- Notification sending
+- Audit logging to external systems
+
+## Comparison with Try Functions
+
+| Aspect | Try Function | Codeunit.Run() Pattern |
+|--------|--------------|------------------------|
+| Write Operations | NOT allowed in call stack | Fully allowed |
+| Transaction | Same transaction | New isolated transaction |
+| Error Behavior | Caught, rolled back | Caught, isolated rollback |
+| Commit Required | No | Yes, before the call |
+| Use Case | External calls, validation | Business processes, batch |
+
+## Best Practices
+
+### Plan Transaction Boundaries
+Design your process to have natural commit points before using this pattern. Don't force commits just to use Codeunit.Run().
+
+### Create Dedicated Codeunits
+Build codeunits specifically designed to be called with result capture:
+- Self-contained logic
+- Clear success/failure semantics
+- Appropriate error messaging
+
+### Document the Pattern
+When using Codeunit.Run() with capture, add comments explaining:
+- Why isolation is needed
+- What the commit point means
+- How failures are handled
+
+### Error Handling is Mandatory
+Never ignore the return value. The pattern's power comes from handling both success and failure cases appropriately.
+
+## Common Mistakes
+
+### Forgetting the Commit
+Calling Codeunit.Run() with capture while a transaction is open causes runtime errors. Always commit first.
+
+### Using Mid-Transaction
+Forcing a Commit() in the middle of a logical transaction to use this pattern leads to data integrity issues.
+
+### Ignoring Failures
+Capturing the result but not acting on failures defeats the purpose and hides problems.
+
+### Overusing the Pattern
+Not every codeunit call needs isolation. Use this pattern when you specifically need independent transaction handling.
+
+## Summary
+
+The Codeunit.Run() pattern with result capture is essential for:
+- Enabling error handling with database operations
+- Isolating transactions for failure recovery
+- Building robust batch and integration processes
+
+Remember: **Commit() before, capture the result, handle errors explicitly.**
+