@grafema/core 0.2.4-beta → 0.2.5-beta

package/src/core/toposort.ts

@@ -0,0 +1,160 @@
+/**
+ * Topological sort for plugin dependency ordering (REG-367).
+ *
+ * Uses Kahn's algorithm (BFS-based) to sort items by their declared dependencies.
+ * Dependencies not present in the input set are silently ignored (cross-phase deps).
+ * When multiple items have zero in-degree, they are emitted in input order
+ * (registration order tiebreaker).
+ *
+ * Time complexity:  O(V + E)
+ * Space complexity: O(V + E)
+ */
+
+/**
+ * Thrown when a dependency cycle is detected during topological sort.
+ */
+export class CycleError extends Error {
+  readonly cycle: string[];
+
+  constructor(cycle: string[]) {
+    super(`Dependency cycle detected: ${cycle.join(' -> ')}`);
+    this.name = 'CycleError';
+    this.cycle = cycle;
+  }
+}
+
+/**
+ * Input item for topological sort.
+ */
+export interface ToposortItem {
+  id: string;
+  dependencies: string[];
+}
+
+/**
+ * Topologically sort items by their dependencies using Kahn's algorithm.
+ *
+ * Dependencies not present in the input set are silently ignored (cross-phase).
+ * Throws CycleError if a dependency cycle exists among the items.
+ * Items with no dependency relationship are emitted in their original input order.
+ *
+ * @param items - Array of items with id and dependencies
+ * @returns Array of IDs in topological order (dependencies first)
+ * @throws CycleError if a dependency cycle exists
+ */
+export function toposort(items: ToposortItem[]): string[] {
+  if (items.length === 0) return [];
+
+  // Build the set of known IDs for filtering cross-phase deps
+  const knownIds = new Set(items.map(item => item.id));
+
+  // adjacency: dep -> list of items that depend on it (successors)
+  const successors = new Map<string, string[]>();
+  const inDegree = new Map<string, number>();
+
+  // Initialize
+  for (const item of items) {
+    successors.set(item.id, []);
+    inDegree.set(item.id, 0);
+  }
+
+  // Build edges: for each item's dependency that is in the same set,
+  // add edge from dependency -> item (dependency must execute first)
+  for (const item of items) {
+    for (const dep of item.dependencies) {
+      if (!knownIds.has(dep)) continue; // cross-phase, ignore
+      successors.get(dep)!.push(item.id);
+      inDegree.set(item.id, inDegree.get(item.id)! + 1);
+    }
+  }
+
+  // Initialize queue with all zero-in-degree items, preserving input order
+  const queue: string[] = [];
+  for (const item of items) {
+    if (inDegree.get(item.id) === 0) {
+      queue.push(item.id);
+    }
+  }
+
+  // Process queue (FIFO for registration-order tiebreaker)
+  const result: string[] = [];
+  let head = 0;
+
+  while (head < queue.length) {
+    const current = queue[head++];
+    result.push(current);
+
+    for (const successor of successors.get(current)!) {
+      const newDegree = inDegree.get(successor)! - 1;
+      inDegree.set(successor, newDegree);
+      if (newDegree === 0) {
+        queue.push(successor);
+      }
+    }
+  }
+
+  // If not all items were processed, there's a cycle
+  if (result.length < items.length) {
+    const cycle = findCycle(items, knownIds, result);
+    throw new CycleError(cycle);
+  }
+
+  return result;
+}
+
+/**
+ * Find a cycle among unprocessed items using DFS.
+ * Returns the cycle as an array of IDs ending with a repeat of the first.
+ */
+function findCycle(items: ToposortItem[], knownIds: Set<string>, processed: string[]): string[] {
+  const processedSet = new Set(processed);
+  const unprocessed = items.filter(item => !processedSet.has(item.id));
+
+  // Build adjacency for unprocessed items only
+  const deps = new Map<string, string[]>();
+  for (const item of unprocessed) {
+    deps.set(item.id, item.dependencies.filter(d => knownIds.has(d) && !processedSet.has(d)));
+  }
+
+  // DFS to find cycle
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const path: string[] = [];
+
+  for (const item of unprocessed) {
+    const cycle = dfs(item.id, deps, visiting, visited, path);
+    if (cycle) return cycle;
+  }
+
+  // Fallback: shouldn't reach here, but return the unprocessed IDs
+  return [...unprocessed.map(i => i.id), unprocessed[0].id];
+}
+
+function dfs(
+  node: string,
+  deps: Map<string, string[]>,
+  visiting: Set<string>,
+  visited: Set<string>,
+  path: string[]
+): string[] | null {
+  if (visited.has(node)) return null;
+
+  if (visiting.has(node)) {
+    // Found cycle — extract it from path
+    const cycleStart = path.indexOf(node);
+    return [...path.slice(cycleStart), node];
+  }
+
+  visiting.add(node);
+  path.push(node);
+
+  for (const dep of deps.get(node) ?? []) {
+    const cycle = dfs(dep, deps, visiting, visited, path);
+    if (cycle) return cycle;
+  }
+
+  path.pop();
+  visiting.delete(node);
+  visited.add(node);
+  return null;
+}

package/src/diagnostics/DiagnosticCollector.ts

@@ -17,7 +17,7 @@
  */
 
 import type { PluginPhase, PluginResult } from '@grafema/types';
-import { GrafemaError } from '../errors/GrafemaError.js';
+import { GrafemaError, type ResolutionStep, type ResolutionFailureReason } from '../errors/GrafemaError.js';
 
 /**
  * Diagnostic entry - unified format for all errors/warnings
@@ -32,6 +32,10 @@ export interface Diagnostic {
   plugin: string;
   timestamp: number;
   suggestion?: string;
+  /** Resolution chain for context (REG-332) */
+  resolutionChain?: ResolutionStep[];
+  /** Failure reason for context-aware suggestions (REG-332) */
+  failureReason?: ResolutionFailureReason;
 }
 
 /**
@@ -63,6 +67,9 @@ export class DiagnosticCollector {
           phase,
           plugin,
           suggestion: error.suggestion,
+          // REG-332: Pass through resolution context
+          resolutionChain: error.context.resolutionChain as ResolutionStep[] | undefined,
+          failureReason: error.context.failureReason as ResolutionFailureReason | undefined,
         });
       } else {
         // Plain Error - treat as generic error

package/src/diagnostics/DiagnosticReporter.ts

@@ -13,21 +13,7 @@
  */
 
 import type { Diagnostic, DiagnosticCollector } from './DiagnosticCollector.js';
-
-/**
- * Mapping from diagnostic codes to category information
- */
-const DIAGNOSTIC_CODE_CATEGORIES: Record<string, { name: string; checkCommand: string }> = {
-  'ERR_DISCONNECTED_NODES': { name: 'disconnected nodes', checkCommand: 'grafema check connectivity' },
-  'ERR_DISCONNECTED_NODE': { name: 'disconnected nodes', checkCommand: 'grafema check connectivity' },
-  'ERR_UNRESOLVED_CALL': { name: 'unresolved calls', checkCommand: 'grafema check calls' },
-  'ERR_MISSING_ASSIGNMENT': { name: 'missing assignments', checkCommand: 'grafema check dataflow' },
-  'ERR_BROKEN_REFERENCE': { name: 'broken references', checkCommand: 'grafema check dataflow' },
-  'ERR_NO_LEAF_NODE': { name: 'incomplete traces', checkCommand: 'grafema check dataflow' },
-  'DISCONNECTED_NODES': { name: 'disconnected nodes', checkCommand: 'grafema check connectivity' },
-  'UNRESOLVED_FUNCTION_CALL': { name: 'unresolved calls', checkCommand: 'grafema check calls' },
-  'MISSING_ASSIGNMENT': { name: 'missing assignments', checkCommand: 'grafema check dataflow' },
-};
+import { CODE_TO_CATEGORY } from './categories.js';
 
 /**
  * Report output options
@@ -38,6 +24,16 @@ export interface ReportOptions {
   includeTrace?: boolean;
 }
 
+/**
+ * Options for strict mode formatting (REG-332)
+ */
+export interface StrictFormatOptions {
+  /** Show resolution chain (hybrid: auto-show for ≤3 errors, hide for more) */
+  verbose?: boolean;
+  /** REG-332: Number of errors suppressed by grafema-ignore comments */
+  suppressedCount?: number;
+}
+
 /**
  * Summary statistics
  */
@@ -196,7 +192,7 @@ export class DiagnosticReporter {
     // Convert to CategoryCount array with metadata
     const byCode: CategoryCount[] = [];
     for (const [code, count] of codeMap.entries()) {
-      const category = DIAGNOSTIC_CODE_CATEGORIES[code];
+      const category = CODE_TO_CATEGORY[code];
       byCode.push({
         code,
         count,
@@ -214,6 +210,81 @@ export class DiagnosticReporter {
     };
   }
 
+  /**
+   * Format strict mode errors with enhanced context (REG-332).
+   * Shows resolution chain and context-aware suggestions.
+   *
+   * Uses hybrid progressive disclosure:
+   * - ≤3 errors: show chain by default
+   * - >3 errors: hide chain unless verbose=true
+   *
+   * @param diagnostics - The fatal diagnostics from strict mode
+   * @param options - Formatting options
+   * @returns Formatted string for CLI output
+   */
+  formatStrict(diagnostics: Diagnostic[], options: StrictFormatOptions = {}): string {
+    const lines: string[] = [];
+    // Hybrid: show chain for ≤3 errors unless explicitly set
+    const showChain = options.verbose ?? diagnostics.length <= 3;
+
+    for (const diag of diagnostics) {
+      // Header: CODE file:line
+      const location = diag.file
+        ? diag.line
+          ? `${diag.file}:${diag.line}`
+          : diag.file
+        : '';
+      lines.push(`${diag.code} ${location}`);
+      lines.push('');
+
+      // Message
+      lines.push(`  ${diag.message}`);
+
+      // Resolution chain (if showing and present)
+      if (showChain && diag.resolutionChain && diag.resolutionChain.length > 0) {
+        lines.push('');
+        lines.push('  Resolution chain:');
+        for (const step of diag.resolutionChain) {
+          const stepLocation = step.file
+            ? step.line
+              ? ` (${step.file}:${step.line})`
+              : ` (${step.file})`
+            : '';
+          lines.push(`    ${step.step} -> ${step.result}${stepLocation}`);
+        }
+      }
+
+      // Suggestion (if present)
+      if (diag.suggestion) {
+        lines.push('');
+        lines.push(`  Suggestion: ${diag.suggestion}`);
+      }
+
+      lines.push('');
+      lines.push('---');
+      lines.push('');
+    }
+
+    // Remove trailing separator
+    if (lines.length > 0) {
+      lines.splice(-3);
+    }
+
+    // Add hint about verbose mode if chain hidden
+    if (!showChain && diagnostics.some(d => d.resolutionChain && d.resolutionChain.length > 0)) {
+      lines.push('');
+      lines.push('  Run with --verbose to see resolution chains.');
+    }
+
+    // REG-332: Show suppression summary if any errors were suppressed
+    if (options.suppressedCount && options.suppressedCount > 0) {
+      lines.push('');
+      lines.push(`  ${options.suppressedCount} error(s) suppressed by grafema-ignore comments.`);
+    }
+
+    return lines.join('\n');
+  }
+
   /**
    * Generate human-readable text report.
    */

package/src/diagnostics/categories.ts

@@ -0,0 +1,104 @@
+/**
+ * Diagnostic Categories - Single source of truth for category/code mappings
+ *
+ * This module defines diagnostic categories once and derives both mapping
+ * directions:
+ * - DIAGNOSTIC_CATEGORIES: category → codes (used by CLI check command)
+ * - CODE_TO_CATEGORY: code → category metadata (used by DiagnosticReporter)
+ *
+ * Adding a new diagnostic code requires updating only this file.
+ */
+
+/**
+ * Category definition with human-readable metadata and associated codes
+ */
+export interface DiagnosticCategory {
+  /** Human-readable name for display */
+  readonly name: string;
+  /** Description of what this category checks */
+  readonly description: string;
+  /** Diagnostic codes that belong to this category */
+  readonly codes: readonly string[];
+}
+
+/**
+ * Valid category keys
+ */
+export type DiagnosticCategoryKey = 'connectivity' | 'calls' | 'dataflow' | 'imports';
+
+/**
+ * Canonical definition of all diagnostic categories
+ *
+ * This is the SINGLE SOURCE OF TRUTH for category mappings.
+ * Both CLI and DiagnosticReporter derive their mappings from this.
+ */
+export const DIAGNOSTIC_CATEGORIES: Record<DiagnosticCategoryKey, DiagnosticCategory> = {
+  connectivity: {
+    name: 'Graph Connectivity',
+    description: 'Check for disconnected nodes in the graph',
+    codes: ['ERR_DISCONNECTED_NODES', 'ERR_DISCONNECTED_NODE'],
+  },
+  calls: {
+    name: 'Call Resolution',
+    description: 'Check for unresolved function calls',
+    codes: ['ERR_UNRESOLVED_CALL'],
+  },
+  dataflow: {
+    name: 'Data Flow',
+    description: 'Check for missing assignments and broken references',
+    codes: ['ERR_MISSING_ASSIGNMENT', 'ERR_BROKEN_REFERENCE', 'ERR_NO_LEAF_NODE'],
+  },
+  imports: {
+    name: 'Import Validation',
+    description: 'Check for broken imports and undefined symbols',
+    codes: ['ERR_BROKEN_IMPORT', 'ERR_UNDEFINED_SYMBOL'],
+  },
+};
+
+/**
+ * Metadata for code-to-category lookup (used by DiagnosticReporter)
+ */
+export interface CodeCategoryInfo {
+  /** Human-readable name for the issue type */
+  name: string;
+  /** CLI command to check this category */
+  checkCommand: string;
+}
+
+/**
+ * Derived mapping: code → category metadata
+ *
+ * Auto-generated from DIAGNOSTIC_CATEGORIES.
+ * Used by DiagnosticReporter to show actionable commands.
+ */
+export const CODE_TO_CATEGORY: Record<string, CodeCategoryInfo> = (() => {
+  const result: Record<string, CodeCategoryInfo> = {};
+
+  for (const [categoryKey, category] of Object.entries(DIAGNOSTIC_CATEGORIES)) {
+    // Generate human-readable name from category name (lowercase, plural)
+    const issueName = category.name.toLowerCase().replace('graph ', '');
+
+    for (const code of category.codes) {
+      result[code] = {
+        name: issueName,
+        checkCommand: `grafema check ${categoryKey}`,
+      };
+    }
+  }
+
+  return result;
+})();
+
+/**
+ * Get category for a diagnostic code
+ */
+export function getCategoryForCode(code: string): CodeCategoryInfo | undefined {
+  return CODE_TO_CATEGORY[code];
+}
+
+/**
+ * Get all codes for a category
+ */
+export function getCodesForCategory(category: DiagnosticCategoryKey): readonly string[] {
+  return DIAGNOSTIC_CATEGORIES[category].codes;
+}

package/src/diagnostics/index.ts

@@ -5,6 +5,7 @@
  * - DiagnosticCollector: Collects errors from plugin execution
  * - DiagnosticReporter: Formats diagnostics for output (text/json/csv)
  * - DiagnosticWriter: Writes diagnostics.log file
+ * - categories: Single source of truth for diagnostic category mappings
  */
 
 export { DiagnosticCollector } from './DiagnosticCollector.js';
@@ -14,3 +15,16 @@ export { DiagnosticReporter } from './DiagnosticReporter.js';
 export type { ReportOptions, SummaryStats, CategoryCount, CategorizedSummaryStats } from './DiagnosticReporter.js';
 
 export { DiagnosticWriter } from './DiagnosticWriter.js';
+
+// Category mappings (single source of truth)
+export {
+  DIAGNOSTIC_CATEGORIES,
+  CODE_TO_CATEGORY,
+  getCategoryForCode,
+  getCodesForCategory,
+} from './categories.js';
+export type {
+  DiagnosticCategory,
+  DiagnosticCategoryKey,
+  CodeCategoryInfo,
+} from './categories.js';

package/src/errors/GrafemaError.ts

@@ -14,6 +14,7 @@
  */
 
 import type { PluginPhase } from '@grafema/types';
+import type { Diagnostic } from '../diagnostics/DiagnosticCollector.js';
 
 /**
  * Context for error reporting
@@ -237,3 +238,60 @@ export class StrictModeError extends GrafemaError {
     this.code = code;
   }
 }
+
+/**
+ * A step in the resolution chain showing what was resolved before failure.
+ * Used by StrictModeError to provide context-aware error messages (REG-332).
+ */
+export interface ResolutionStep {
+  /** Description of what was resolved, e.g., "getUser() return" */
+  step: string;
+  /** Result of resolution, e.g., "unknown" or "User class" */
+  result: string;
+  /** File where this step occurred */
+  file?: string;
+  /** Line number */
+  line?: number;
+}
+
+/**
+ * Reasons why resolution can fail.
+ * Used by StrictModeError for context-aware suggestions (REG-332).
+ */
+export type ResolutionFailureReason =
+  | 'unknown_object_type'      // getUser() return unknown
+  | 'class_not_imported'       // User class not in scope
+  | 'method_not_found'         // Class exists but no such method
+  | 'external_dependency'      // From node_modules
+  | 'circular_reference'       // Alias chain too deep
+  | 'builtin_method'           // Built-in prototype method (not an error)
+  | 'unknown';                 // Catch-all
+
+/**
+ * StrictModeFailure - thrown when strict mode stops analysis due to fatal errors.
+ *
+ * Unlike other errors, this carries a reference to the fatal diagnostic(s)
+ * rather than duplicating the message. The CLI formats output from
+ * the diagnostic, not from error.message.
+ *
+ * This prevents the duplication issue where both error.message and
+ * DiagnosticReporter show the same error (REG-332).
+ */
+export class StrictModeFailure extends Error {
+  /** The fatal diagnostics that caused the failure */
+  readonly diagnostics: Diagnostic[];
+  /** Error count for summary */
+  readonly count: number;
+  /** REG-332: Number of errors suppressed by grafema-ignore comments */
+  readonly suppressedCount: number;
+
+  constructor(diagnostics: Diagnostic[], suppressedCount: number = 0) {
+    // Keep message minimal - CLI will format from diagnostics
+    super(`Strict mode: ${diagnostics.length} unresolved reference(s) found`);
+    this.name = 'StrictModeFailure';
+    this.diagnostics = diagnostics;
+    this.count = diagnostics.length;
+    this.suppressedCount = suppressedCount;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/index.ts

@@ -13,21 +13,39 @@ export {
   AnalysisError,
   ValidationError,
   StrictModeError,
+  StrictModeFailure,
+} from './errors/GrafemaError.js';
+export type {
+  ErrorContext,
+  GrafemaErrorJSON,
+  ResolutionStep,
+  ResolutionFailureReason,
 } from './errors/GrafemaError.js';
-export type { ErrorContext, GrafemaErrorJSON } from './errors/GrafemaError.js';
 
 // Logging
-export { Logger, ConsoleLogger, createLogger } from './logging/Logger.js';
-export type { LogLevel } from './logging/Logger.js';
+export { ConsoleLogger, FileLogger, MultiLogger, createLogger } from './logging/Logger.js';
+export type { Logger, LogLevel } from './logging/Logger.js';
 
 // Diagnostics
 export { DiagnosticCollector, DiagnosticReporter, DiagnosticWriter } from './diagnostics/index.js';
 export type { Diagnostic, DiagnosticInput, ReportOptions, SummaryStats } from './diagnostics/index.js';
+// Diagnostic categories (single source of truth)
+export { DIAGNOSTIC_CATEGORIES, CODE_TO_CATEGORY, getCategoryForCode, getCodesForCategory } from './diagnostics/index.js';
+export type { DiagnosticCategory, DiagnosticCategoryKey, CodeCategoryInfo } from './diagnostics/index.js';
 
 // Config
-export { loadConfig, DEFAULT_CONFIG } from './config/index.js';
+export {
+  loadConfig,
+  DEFAULT_CONFIG,
+  validateServices,
+  validatePatterns,
+  validateWorkspace,
+} from './config/index.js';
 export type { GrafemaConfig } from './config/index.js';
 
+// Instructions (for AI agents)
+export { getOnboardingInstruction } from './instructions/index.js';
+
 // Main orchestrator
 export { Orchestrator } from './Orchestrator.js';
 export type {
@@ -52,8 +70,6 @@ export type { Node, Edge, EdgeType, AttrQuery, GraphStats, GraphExport } from '.
 // RFDB
 export { RFDBClient } from '@grafema/rfdb-client';
 export { RFDBServerBackend } from './storage/backends/RFDBServerBackend.js';
-export { findRfdbBinary, getPlatformDir, getBinaryNotFoundMessage } from './utils/findRfdbBinary.js';
-export type { FindBinaryOptions } from './utils/findRfdbBinary.js';
 
 // Core utilities
 export { NodeFactory } from './core/NodeFactory.js';
@@ -76,6 +92,8 @@ export { AnalysisQueue } from './core/AnalysisQueue.js';
 export { ASTWorkerPool, type ModuleInfo as ASTModuleInfo, type ParseResult, type ASTWorkerPoolStats } from './core/ASTWorkerPool.js';
 export { GuaranteeManager } from './core/GuaranteeManager.js';
 export type { GuaranteeGraph } from './core/GuaranteeManager.js';
+export { toposort, CycleError } from './core/toposort.js';
+export type { ToposortItem } from './core/toposort.js';
 export { clearFileNodesIfNeeded, clearServiceNodeIfExists } from './core/FileNodeManager.js';
 export { CoverageAnalyzer } from './core/CoverageAnalyzer.js';
 export type { CoverageResult } from './core/CoverageAnalyzer.js';
@@ -85,6 +103,16 @@ export type { FileExplainResult, EnhancedNode } from './core/FileExplainer.js';
 // Hash utilities
 export { calculateFileHash, calculateFileHashAsync, calculateContentHash } from './core/HashUtils.js';
 
+// Module resolution utilities (REG-320)
+export {
+  resolveModulePath,
+  isRelativeImport,
+  resolveRelativeSpecifier,
+  DEFAULT_EXTENSIONS,
+  DEFAULT_INDEX_FILES
+} from './utils/moduleResolution.js';
+export type { ModuleResolutionOptions } from './utils/moduleResolution.js';
+
 // Type validation and path validation
 export {
   levenshtein,
@@ -111,11 +139,25 @@ export { GuaranteeAPI } from './api/GuaranteeAPI.js';
 export type { GuaranteeGraphBackend } from './api/GuaranteeAPI.js';
 
 // Node kinds
-export { isGuaranteeType } from './core/nodes/NodeKind.js';
+export { isGuaranteeType, isGrafemaType } from './core/nodes/NodeKind.js';
 
 // Issue nodes (detected problems)
 export { IssueNode, type IssueNodeRecord, type IssueSeverity, type IssueType } from './core/nodes/IssueNode.js';
 
+// Plugin nodes (self-describing pipeline)
+export { PluginNode } from './core/nodes/PluginNode.js';
+export type { PluginNodeRecord, PluginNodeOptions } from './core/nodes/PluginNode.js';
+
+// Guarantee nodes (contract-based)
+export { GuaranteeNode } from './core/nodes/GuaranteeNode.js';
+export type {
+  GuaranteeNodeRecord,
+  GuaranteeNodeOptions,
+  GuaranteePriority,
+  GuaranteeStatus,
+  GuaranteeType,
+} from './core/nodes/GuaranteeNode.js';
+
 // Node contracts
 export { FunctionNode } from './core/nodes/FunctionNode.js';
 export { CallSiteNode } from './core/nodes/CallSiteNode.js';
@@ -188,7 +230,8 @@ export { SystemDbAnalyzer } from './plugins/analysis/SystemDbAnalyzer.js';
 export { IncrementalAnalysisPlugin } from './plugins/analysis/IncrementalAnalysisPlugin.js';
 
 // Enrichment plugins
-export { MethodCallResolver } from './plugins/enrichment/MethodCallResolver.js';
+export { MethodCallResolver, LIBRARY_SEMANTIC_GROUPS } from './plugins/enrichment/MethodCallResolver.js';
+export type { LibraryCallStats } from './plugins/enrichment/MethodCallResolver.js';
 export { ArgumentParameterLinker } from './plugins/enrichment/ArgumentParameterLinker.js';
 export { AliasTracker } from './plugins/enrichment/AliasTracker.js';
 export { ValueDomainAnalyzer } from './plugins/enrichment/ValueDomainAnalyzer.js';
@@ -202,6 +245,8 @@ export { RustFFIEnricher } from './plugins/enrichment/RustFFIEnricher.js';
 export { NodejsBuiltinsResolver } from './plugins/enrichment/NodejsBuiltinsResolver.js';
 export { ExternalCallResolver } from './plugins/enrichment/ExternalCallResolver.js';
 export { ClosureCaptureEnricher } from './plugins/enrichment/ClosureCaptureEnricher.js';
+export { ExpressHandlerLinker } from './plugins/enrichment/ExpressHandlerLinker.js';
+export { RejectionPropagationEnricher } from './plugins/enrichment/RejectionPropagationEnricher.js';
 
 // Builtin registry
 export { BuiltinRegistry } from './data/builtins/index.js';
@@ -218,7 +263,6 @@ export { ShadowingDetector } from './plugins/validation/ShadowingDetector.js';
 export { GraphConnectivityValidator } from './plugins/validation/GraphConnectivityValidator.js';
 export { DataFlowValidator } from './plugins/validation/DataFlowValidator.js';
 export { TypeScriptDeadCodeValidator } from './plugins/validation/TypeScriptDeadCodeValidator.js';
-export { NodeCreationValidator } from './plugins/validation/NodeCreationValidator.js';
 export { BrokenImportValidator } from './plugins/validation/BrokenImportValidator.js';
 
 // Discovery plugins

package/src/instructions/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Grafema instruction documents for AI agents.
+ *
+ * Instructions are markdown documents that guide agent behavior.
+ * They are read at runtime from the installed package.
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Get the onboarding instruction document.
+ *
+ * Returns the full markdown text of the onboarding procedure
+ * that guides an AI agent through project study and configuration.
+ */
+export function getOnboardingInstruction(): string {
+  return readFileSync(join(__dirname, 'onboarding.md'), 'utf-8');
+}