feat: add import API validation and v4.x migration guide

Add comprehensive migration support for v4.x import API changes:

- Runtime validation that rejects deprecated v3.x options with clear errors
- Configurable error verbosity (detailed in dev, concise in prod)
- Complete migration guide (docs/guides/migrating-to-v4.md)
- Enhanced CHANGELOG with breaking changes documentation
- TypeScript type safety using 'never' types for deprecated options
- Comprehensive JSDoc with deprecation warnings and examples

Deprecated v3.x options now throw helpful errors:
- extractRelationships → enableRelationshipInference
- createFileStructure → vfsPath
- autoDetect → (removed - always enabled)
- excelSheets → (removed - all sheets processed)
- pdfExtractTables → (removed - always enabled)

Resolves Workshop team import issues where incorrect option names
disabled all intelligent features, causing generic entity creation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CHANGELOG.md

@@ -223,22 +223,110 @@ $ brainy import ./research-papers --extract-concepts --progress
 
 ### ⚠️ Breaking Changes
 
-**NONE** - v4.0.0 is 100% backward compatible!
+#### 💥 Import API Redesign
 
-All v4.0.0 features are:
+The import API has been redesigned for clarity and better feature control. **Old v3.x option names are no longer recognized** and will throw errors.
+
+**What Changed:**
+
+| v3.x Option | v4.x Option | Action Required |
+|-------------|-------------|-----------------|
+| `extractRelationships` | `enableRelationshipInference` | **Rename option** |
+| `autoDetect` | *(removed)* | **Delete option** (always enabled) |
+| `createFileStructure` | `vfsPath` | **Replace** with VFS path |
+| `excelSheets` | *(removed)* | **Delete option** (all sheets processed) |
+| `pdfExtractTables` | *(removed)* | **Delete option** (always enabled) |
+| - | `enableNeuralExtraction` | **Add option** (new in v4.x) |
+| - | `enableConceptExtraction` | **Add option** (new in v4.x) |
+| - | `preserveSource` | **Add option** (new in v4.x) |
+
+**Why These Changes?**
+
+1. **Clearer option names**: `enableRelationshipInference` explicitly indicates AI-powered relationship inference
+2. **Separation of concerns**: Neural extraction, relationship inference, and VFS are now separate, explicit options
+3. **Better defaults**: Auto-detection and AI features are enabled by default
+4. **Reduced confusion**: Removed redundant options like `autoDetect` and format-specific options
+
+**Migration Examples:**
+
+<details>
+<summary>Example 1: Basic Excel Import</summary>
+
+```typescript
+// v3.x (OLD - Will throw error)
+await brain.import('./glossary.xlsx', {
+  extractRelationships: true,
+  createFileStructure: true
+})
+
+// v4.x (NEW - Use this)
+await brain.import('./glossary.xlsx', {
+  enableRelationshipInference: true,
+  vfsPath: '/imports/glossary'
+})
+```
+</details>
+
+<details>
+<summary>Example 2: Full-Featured Import</summary>
+
+```typescript
+// v3.x (OLD - Will throw error)
+await brain.import('./data.xlsx', {
+  extractRelationships: true,
+  autoDetect: true,
+  createFileStructure: true
+})
+
+// v4.x (NEW - Use this)
+await brain.import('./data.xlsx', {
+  enableNeuralExtraction: true,      // Extract entity names
+  enableRelationshipInference: true, // Infer semantic relationships
+  enableConceptExtraction: true,     // Extract entity types
+  vfsPath: '/imports/data',          // VFS directory
+  preserveSource: true               // Save original file
+})
+```
+</details>
+
+**Error Messages:**
+
+If you use old v3.x options, you'll get a clear error message:
+
+```
+❌ Invalid import options detected (Brainy v4.x breaking changes)
+
+The following v3.x options are no longer supported:
+
+  ❌ extractRelationships
+     → Use: enableRelationshipInference
+     → Why: Option renamed for clarity in v4.x
+
+📖 Migration Guide: https://brainy.dev/docs/guides/migrating-to-v4
+```
+
+**Other v4.0.0 Features (Non-Breaking):**
+
+All other v4.0.0 features are:
 - ✅ Opt-in (lifecycle, compression, batch operations)
 - ✅ Additive (new CLI commands, new methods)
 - ✅ Non-breaking (existing code continues to work)
 
 ### 📝 Migration
 
-**No migration required!** All v4.0.0 features are optional enhancements.
+**Import API migration required** if you use `brain.import()` with the old v3.x option names.
 
-To use new features:
+#### Required Changes:
 1. Update to v4.0.0: `npm install @soulcraft/brainy@4.0.0`
-2. Enable lifecycle policies: `brainy storage lifecycle set`
+2. Update import calls to use new option names (see table above)
-3. Use batch operations: `brainy storage batch-delete entities.txt`
+3. Test your imports - you'll get clear error messages if you use old options
-4. See `docs/MIGRATION-V3-TO-V4.md` for full feature documentation
+
+#### Optional Enhancements:
+- Enable lifecycle policies: `brainy storage lifecycle set`
+- Use batch operations: `brainy storage batch-delete entities.txt`
+- See full migration guide: `docs/guides/migrating-to-v4.md`
+
+**Complete Migration Guide:** [docs/guides/migrating-to-v4.md](./docs/guides/migrating-to-v4.md)
 
 ### 🎓 What This Means
 

docs/guides/migrating-to-v4.md

@@ -0,0 +1,491 @@
+# Migrating from Brainy v3.x to v4.x
+
+**Brainy v4.0.0** introduces breaking changes to the import API for improved clarity, better defaults, and more powerful features.
+
+This guide will help you migrate your code quickly and painlessly.
+
+---
+
+## 🎯 Quick Migration Checklist
+
+If you just want to fix your code fast, here's what to do:
+
+- [ ] Replace `extractRelationships` with `enableRelationshipInference`
+- [ ] Remove `autoDetect` (auto-detection is now always enabled)
+- [ ] Replace `createFileStructure: true` with `vfsPath: '/your/path'`
+- [ ] Remove `excelSheets` (all sheets are now processed automatically)
+- [ ] Remove `pdfExtractTables` (table extraction is now automatic)
+- [ ] Add `enableNeuralExtraction: true` to enable AI entity extraction
+- [ ] Add `preserveSource: true` if you want to keep the original file
+
+---
+
+## 📋 Option Name Changes
+
+### Complete Mapping Table
+
+| v3.x Option | v4.x Option | Action Required |
+|-------------|-------------|-----------------|
+| `extractRelationships` | `enableRelationshipInference` | **Rename option** |
+| `autoDetect` | *(removed)* | **Delete option** (always enabled) |
+| `createFileStructure` | `vfsPath` | **Replace** with VFS directory path |
+| `excelSheets` | *(removed)* | **Delete option** (all sheets processed) |
+| `pdfExtractTables` | *(removed)* | **Delete option** (always enabled) |
+| - | `enableNeuralExtraction` | **Add option** (new in v4.x) |
+| - | `enableConceptExtraction` | **Add option** (new in v4.x) |
+| - | `preserveSource` | **Add option** (new in v4.x) |
+
+---
+
+## 🔄 Migration Examples
+
+### Example 1: Basic Excel Import
+
+**Before (v3.x):**
+```typescript
+const result = await brain.import('./glossary.xlsx', {
+  extractRelationships: true,
+  createFileStructure: true,
+  groupBy: 'type'
+})
+```
+
+**After (v4.x):**
+```typescript
+const result = await brain.import('./glossary.xlsx', {
+  enableRelationshipInference: true,  // ✅ Renamed
+  vfsPath: '/imports/glossary',       // ✅ Replaced createFileStructure
+  groupBy: 'type'                     // ✅ No change
+})
+```
+
+---
+
+### Example 2: Full-Featured Import
+
+**Before (v3.x):**
+```typescript
+const result = await brain.import('./data.xlsx', {
+  extractRelationships: true,
+  autoDetect: true,
+  createFileStructure: true,
+  groupBy: 'type',
+  enableDeduplication: true
+})
+```
+
+**After (v4.x):**
+```typescript
+const result = await brain.import('./data.xlsx', {
+  // AI features
+  enableNeuralExtraction: true,      // ✅ NEW - Extract entity names
+  enableRelationshipInference: true, // ✅ Renamed from extractRelationships
+  enableConceptExtraction: true,     // ✅ NEW - Extract entity types
+
+  // VFS features
+  vfsPath: '/imports/data',          // ✅ Replaced createFileStructure
+  groupBy: 'type',                   // ✅ No change
+  preserveSource: true,              // ✅ NEW - Save original file
+
+  // Performance
+  enableDeduplication: true          // ✅ No change
+})
+```
+
+---
+
+### Example 3: Simple Import (Defaults)
+
+**Before (v3.x):**
+```typescript
+const result = await brain.import('./data.csv', {
+  autoDetect: true,
+  extractRelationships: true
+})
+```
+
+**After (v4.x):**
+```typescript
+// Auto-detection is always enabled now
+// Just enable the features you want
+const result = await brain.import('./data.csv', {
+  enableRelationshipInference: true
+})
+
+// Or use all defaults (AI features enabled)
+const result = await brain.import('./data.csv')
+```
+
+---
+
+### Example 4: PDF Import
+
+**Before (v3.x):**
+```typescript
+const result = await brain.import('./document.pdf', {
+  pdfExtractTables: true,
+  extractRelationships: true,
+  createFileStructure: true
+})
+```
+
+**After (v4.x):**
+```typescript
+const result = await brain.import('./document.pdf', {
+  // pdfExtractTables removed - always enabled
+  enableRelationshipInference: true,
+  vfsPath: '/imports/documents'
+})
+```
+
+---
+
+## 💡 Why These Changes?
+
+### Clearer Option Names
+
+**v3.x naming was ambiguous:**
+- `extractRelationships` → Could mean "create relationships" or "infer relationships"
+- `createFileStructure` → Doesn't explain what structure or where
+
+**v4.x naming is explicit:**
+- `enableRelationshipInference` → Clearly means "use AI to infer semantic relationships"
+- `vfsPath` → Explicitly sets the virtual filesystem directory path
+- `enableNeuralExtraction` → Clearly indicates AI-powered entity extraction
+
+### Separation of Concerns
+
+**v4.x separates import features into clear categories:**
+
+1. **Neural/AI Features:**
+   - `enableNeuralExtraction` - Extract entity names and metadata
+   - `enableRelationshipInference` - Infer semantic relationships
+   - `enableConceptExtraction` - Extract entity types and concepts
+
+2. **VFS Features:**
+   - `vfsPath` - Virtual filesystem directory
+   - `groupBy` - Grouping strategy
+   - `preserveSource` - Keep original file
+
+3. **Performance Features:**
+   - `enableDeduplication` - Merge similar entities
+   - `confidenceThreshold` - AI confidence threshold
+   - `onProgress` - Progress callbacks
+
+### Better Defaults
+
+**v3.x required explicit enabling:**
+```typescript
+// Had to enable everything manually
+await brain.import(file, {
+  autoDetect: true,
+  extractRelationships: true,
+  createFileStructure: true
+})
+```
+
+**v4.x has smart defaults:**
+```typescript
+// Auto-detection and AI features enabled by default
+await brain.import(file)
+
+// Or customize specific features
+await brain.import(file, {
+  vfsPath: '/my/data',
+  confidenceThreshold: 0.8
+})
+```
+
+---
+
+## 🆕 New Features in v4.x
+
+### Neural Entity Extraction
+Extract entity names, types, and metadata using AI:
+
+```typescript
+const result = await brain.import('./glossary.xlsx', {
+  enableNeuralExtraction: true,      // Extract entity names from "Term" column
+  enableConceptExtraction: true,     // Detect entity types (Place, Person, etc.)
+  confidenceThreshold: 0.7           // Minimum AI confidence (0-1)
+})
+
+// Result includes rich entity metadata
+result.entities.forEach(entity => {
+  console.log(`${entity.name} (${entity.type})`)
+  console.log(`Confidence: ${entity.confidence}`)
+})
+```
+
+### VFS Integration
+Imported data is organized in a virtual filesystem:
+
+```typescript
+const result = await brain.import('./data.xlsx', {
+  vfsPath: '/projects/myproject/data',
+  groupBy: 'type',        // Group by entity type
+  preserveSource: true    // Save original .xlsx file
+})
+
+// Access via VFS
+const vfs = brain.vfs()
+const files = await vfs.readdir('/projects/myproject/data')
+// ['Places/', 'Characters/', 'Concepts/', '_source.xlsx', '_metadata.json']
+
+// Read entity file
+const content = await vfs.readFile('/projects/myproject/data/Places/Talifar.json')
+```
+
+### Semantic Relationship Inference
+AI infers relationship types from context:
+
+```typescript
+const result = await brain.import('./glossary.xlsx', {
+  enableRelationshipInference: true
+})
+
+// Instead of generic "contains" relationships,
+// you get semantic verbs like:
+// - "capital_of"
+// - "located_in"
+// - "guards"
+// - "part_of"
+// - "related_to"
+
+const relations = await brain.getRelations({ limit: 100 })
+const types = new Set(relations.map(r => r.label))
+console.log(types)
+// Set { 'capital_of', 'guards', 'located_in', 'related_to' }
+```
+
+---
+
+## 🔍 What Breaks & How to Fix It
+
+### Error: "Invalid import options: 'extractRelationships'"
+
+**Cause:** Using v3.x option name
+
+**Fix:**
+```typescript
+// Before
+await brain.import(file, { extractRelationships: true })
+
+// After
+await brain.import(file, { enableRelationshipInference: true })
+```
+
+---
+
+### Error: "Invalid import options: 'autoDetect'"
+
+**Cause:** Using v3.x option that's been removed
+
+**Fix:**
+```typescript
+// Before
+await brain.import(file, { autoDetect: true })
+
+// After - just remove it (auto-detection always enabled)
+await brain.import(file)
+```
+
+---
+
+### Error: "Invalid import options: 'createFileStructure'"
+
+**Cause:** Using v3.x option name
+
+**Fix:**
+```typescript
+// Before
+await brain.import(file, { createFileStructure: true })
+
+// After - specify VFS path explicitly
+await brain.import(file, { vfsPath: '/imports/mydata' })
+```
+
+---
+
+### Issue: Import succeeds but entities have generic names like "Entity_144"
+
+**Cause:** Neural extraction is disabled
+
+**Fix:**
+```typescript
+// Ensure AI features are enabled
+await brain.import(file, {
+  enableNeuralExtraction: true,      // ✅ Extract entity names
+  enableRelationshipInference: true, // ✅ Infer relationships
+  enableConceptExtraction: true      // ✅ Extract types
+})
+```
+
+---
+
+### Issue: All relationships are type "contains"
+
+**Cause:** Relationship inference is disabled
+
+**Fix:**
+```typescript
+// Enable relationship inference
+await brain.import(file, {
+  enableRelationshipInference: true  // ✅ Use AI to detect semantic relationships
+})
+```
+
+---
+
+### Issue: VFS directory doesn't exist in filesystem
+
+**This is NORMAL!** VFS is virtual - it uses Brainy entities, not physical files.
+
+**How to access VFS:**
+```typescript
+// DON'T do this:
+// ls brainy-data/vfs/  ❌ Won't work
+
+// DO this instead:
+const vfs = brain.vfs()
+await vfs.init()
+const files = await vfs.readdir('/imports')  // ✅ Correct
+```
+
+---
+
+## 📦 TypeScript Users
+
+### Compile-Time Errors
+
+If you're using TypeScript, you'll get compile-time errors when using deprecated options:
+
+```typescript
+// TypeScript will show error:
+// "Type 'true' is not assignable to type 'never'"
+await brain.import(file, {
+  extractRelationships: true  // ❌ Type error
+})
+
+// Fix: Use correct option name
+await brain.import(file, {
+  enableRelationshipInference: true  // ✅ Type correct
+})
+```
+
+### IDE Autocomplete
+
+Your IDE will show deprecation warnings and suggest the correct option names:
+
+```typescript
+await brain.import(file, {
+  extract...  // IDE suggests: enableNeuralExtraction, enableRelationshipInference
+})
+```
+
+---
+
+## 🎓 Best Practices for v4.x
+
+### 1. Enable All AI Features by Default
+
+```typescript
+// Good: Enable all intelligent features
+await brain.import('./data.xlsx', {
+  enableNeuralExtraction: true,
+  enableRelationshipInference: true,
+  enableConceptExtraction: true,
+  vfsPath: '/imports/data'
+})
+```
+
+### 2. Use VFS for Organization
+
+```typescript
+// Good: Organize by project
+await brain.import('./project-A.xlsx', {
+  vfsPath: '/projects/project-a/data'
+})
+
+await brain.import('./project-B.csv', {
+  vfsPath: '/projects/project-b/data'
+})
+```
+
+### 3. Preserve Source Files
+
+```typescript
+// Good: Keep original files for reference
+await brain.import('./important-data.xlsx', {
+  preserveSource: true,  // Saves original .xlsx in VFS
+  vfsPath: '/archives/2025'
+})
+```
+
+### 4. Tune Confidence Threshold
+
+```typescript
+// For high-quality data: Lower threshold
+await brain.import('./curated-glossary.xlsx', {
+  confidenceThreshold: 0.5  // Extract more entities
+})
+
+// For noisy data: Higher threshold
+await brain.import('./scraped-data.csv', {
+  confidenceThreshold: 0.8  // Only high-confidence entities
+})
+```
+
+### 5. Disable Deduplication for Large Imports
+
+```typescript
+// For small imports: Keep deduplication
+await brain.import('./small-data.xlsx', {
+  enableDeduplication: true
+})
+
+// For large imports (>1000 rows): Disable for performance
+await brain.import('./huge-database.csv', {
+  enableDeduplication: false  // Much faster
+})
+```
+
+---
+
+## 🚀 Migration Automation (Future)
+
+We're working on an automated migration tool:
+
+```bash
+# Coming soon
+npx @soulcraft/brainy-migrate
+
+# Will scan your code and automatically update:
+# - Option names
+# - TypeScript types
+# - Import patterns
+```
+
+---
+
+## 📚 Additional Resources
+
+- **API Documentation:** [https://brainy.dev/docs/api/import](https://brainy.dev/docs/api/import)
+- **Examples:** [examples/import-excel/](../../examples/import-excel/)
+- **Changelog:** [CHANGELOG.md](../../CHANGELOG.md)
+- **Support:** [GitHub Issues](https://github.com/soulcraft/brainy/issues)
+
+---
+
+## 💬 Need Help?
+
+If you're stuck migrating:
+
+1. Check the error message - it includes migration hints
+2. Review the examples in this guide
+3. Open an issue on GitHub with your use case
+4. Join our Discord community for real-time help
+
+---
+
+**Happy migrating! 🎉**

src/brainy.ts

@@ -1863,33 +1863,91 @@ export class Brainy<T = any> implements BrainyInterface<T> {
   }
 
   /**
-   * Import files with auto-detection and dual storage (VFS + Knowledge Graph)
+   * Import files with intelligent extraction and dual storage (VFS + Knowledge Graph)
    *
    * Unified import system that:
    * - Auto-detects format (Excel, PDF, CSV, JSON, Markdown)
-   * - Extracts entities and relationships
+   * - Extracts entities with AI-powered name/type detection
+   * - Infers semantic relationships from context
    * - Stores in both VFS (organized files) and Knowledge Graph (connected entities)
    * - Links VFS files to graph entities
    *
-   * @example
+   * @since 4.0.0
-   * // Import from file path
-   * const result = await brain.import('/path/to/file.xlsx')
    *
-   * @example
+   * @example Quick Start (All AI features enabled by default)
-   * // Import from buffer
+   * ```typescript
+   * const result = await brain.import('./glossary.xlsx')
+   * // Auto-detects format, extracts entities, infers relationships
+   * ```
+   *
+   * @example Full-Featured Import (v4.x)
+   * ```typescript
+   * const result = await brain.import('./data.xlsx', {
+   *   // AI features
+   *   enableNeuralExtraction: true,      // Extract entity names/metadata
+   *   enableRelationshipInference: true, // Detect semantic relationships
+   *   enableConceptExtraction: true,     // Extract types/concepts
+   *
+   *   // VFS features
+   *   vfsPath: '/imports/my-data',       // Store in VFS directory
+   *   groupBy: 'type',                   // Organize by entity type
+   *   preserveSource: true,              // Keep original file
+   *
+   *   // Progress tracking
+   *   onProgress: (p) => console.log(p.message)
+   * })
+   * ```
+   *
+   * @example Performance Tuning (Large Files)
+   * ```typescript
+   * const result = await brain.import('./huge-file.csv', {
+   *   enableDeduplication: false,  // Skip dedup for speed
+   *   confidenceThreshold: 0.8,    // Higher threshold = fewer entities
+   *   onProgress: (p) => console.log(`${p.processed}/${p.total}`)
+   * })
+   * ```
+   *
+   * @example Import from Buffer or Object
+   * ```typescript
+   * // From buffer
    * const result = await brain.import(buffer, { format: 'pdf' })
    *
-   * @example
+   * // From object
-   * // Import JSON object
    * const result = await brain.import({ entities: [...] })
+   * ```
    *
-   * @example
+   * @throws {Error} If invalid options are provided (v4.x breaking changes)
-   * // Custom VFS path and grouping
+   *
-   * const result = await brain.import(buffer, {
+   * @see {@link https://brainy.dev/docs/api/import API Documentation}
-   *   vfsPath: '/my-imports/data',
+   * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
-   *   groupBy: 'type',
+   *
-   *   onProgress: (progress) => console.log(progress.message)
+   * @remarks
-   * })
+   * **⚠️ Breaking Changes from v3.x:**
+   *
+   * The import API was redesigned in v4.0.0 for clarity and better feature control.
+   * Old v3.x option names are **no longer recognized** and will throw errors.
+   *
+   * **Option Changes:**
+   * - ❌ `extractRelationships` → ✅ `enableRelationshipInference`
+   * - ❌ `createFileStructure` → ✅ `vfsPath: '/your/path'`
+   * - ❌ `autoDetect` → ✅ *(removed - always enabled)*
+   * - ❌ `excelSheets` → ✅ *(removed - all sheets processed)*
+   * - ❌ `pdfExtractTables` → ✅ *(removed - always enabled)*
+   *
+   * **New Options:**
+   * - ✅ `enableNeuralExtraction` - Extract entity names via AI
+   * - ✅ `enableConceptExtraction` - Extract entity types via AI
+   * - ✅ `preserveSource` - Save original file in VFS
+   *
+   * **If you get an error:**
+   * The error message includes migration instructions and examples.
+   * See the complete migration guide for all details.
+   *
+   * **Why these changes?**
+   * - Clearer option names (explicitly describe what they do)
+   * - Separation of concerns (neural, relationships, VFS are separate)
+   * - Better defaults (AI features enabled by default)
+   * - Reduced confusion (removed redundant options)
    */
   async import(
     source: Buffer | string | object,

src/import/ImportCoordinator.ts

@@ -36,7 +36,10 @@ export interface ImportSource {
   filename?: string
 }
 
-export interface ImportOptions {
+/**
+ * Valid import options for v4.x
+ */
+export interface ValidImportOptions {
   /** Force specific format (skip auto-detection) */
   format?: SupportedFormat
 
@@ -86,6 +89,51 @@ export interface ImportOptions {
   onProgress?: (progress: ImportProgress) => void
 }
 
+/**
+ * Deprecated import options from v3.x
+ * Using these will cause TypeScript compile errors
+ *
+ * @deprecated These options are no longer supported in v4.x
+ * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+ */
+export interface DeprecatedImportOptions {
+  /**
+   * @deprecated Use `enableRelationshipInference` instead
+   * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+   */
+  extractRelationships?: never
+
+  /**
+   * @deprecated Removed in v4.x - auto-detection is now always enabled
+   * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+   */
+  autoDetect?: never
+
+  /**
+   * @deprecated Use `vfsPath` to specify the directory path instead
+   * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+   */
+  createFileStructure?: never
+
+  /**
+   * @deprecated Removed in v4.x - all sheets are now processed automatically
+   * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+   */
+  excelSheets?: never
+
+  /**
+   * @deprecated Removed in v4.x - table extraction is now automatic for PDF imports
+   * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+   */
+  pdfExtractTables?: never
+}
+
+/**
+ * Complete import options interface
+ * Combines valid v4.x options with deprecated v3.x options (which cause TypeScript errors)
+ */
+export type ImportOptions = ValidImportOptions & DeprecatedImportOptions
+
 export interface ImportProgress {
   stage: 'detecting' | 'extracting' | 'storing-vfs' | 'storing-graph' | 'relationships' | 'complete'
   /** Phase of import - extraction or relationship building (v3.49.0) */
@@ -211,6 +259,9 @@ export class ImportCoordinator {
     const startTime = Date.now()
     const importId = uuidv4()
 
+    // Validate options (v4.0.0+: Reject deprecated v3.x options)
+    this.validateOptions(options)
+
     // Normalize source
     const normalizedSource = this.normalizeSource(source, options.format)
 
@@ -800,4 +851,114 @@ export class ImportCoordinator {
     // Fallback: return as-is
     return result
   }
+
+  /**
+   * Validate options and reject deprecated v3.x options (v4.0.0+)
+   * Throws clear errors with migration guidance
+   */
+  private validateOptions(options: any): void {
+    const invalidOptions: Array<{ old: string; new: string; message: string }> = []
+
+    // Check for v3.x deprecated options
+    if ('extractRelationships' in options) {
+      invalidOptions.push({
+        old: 'extractRelationships',
+        new: 'enableRelationshipInference',
+        message: 'Option renamed for clarity in v4.x - explicitly indicates AI-powered relationship inference'
+      })
+    }
+
+    if ('autoDetect' in options) {
+      invalidOptions.push({
+        old: 'autoDetect',
+        new: '(removed)',
+        message: 'Auto-detection is now always enabled - no need to specify this option'
+      })
+    }
+
+    if ('createFileStructure' in options) {
+      invalidOptions.push({
+        old: 'createFileStructure',
+        new: 'vfsPath',
+        message: 'Use vfsPath to explicitly specify the virtual filesystem directory path'
+      })
+    }
+
+    if ('excelSheets' in options) {
+      invalidOptions.push({
+        old: 'excelSheets',
+        new: '(removed)',
+        message: 'All sheets are now processed automatically - no configuration needed'
+      })
+    }
+
+    if ('pdfExtractTables' in options) {
+      invalidOptions.push({
+        old: 'pdfExtractTables',
+        new: '(removed)',
+        message: 'Table extraction is now automatic for PDF imports'
+      })
+    }
+
+    // If invalid options found, throw error with detailed message
+    if (invalidOptions.length > 0) {
+      const errorMessage = this.buildValidationErrorMessage(invalidOptions)
+      throw new Error(errorMessage)
+    }
+  }
+
+  /**
+   * Build detailed error message for invalid options
+   * Respects LOG_LEVEL for verbosity (detailed in dev, concise in prod)
+   */
+  private buildValidationErrorMessage(
+    invalidOptions: Array<{ old: string; new: string; message: string }>
+  ): string {
+    // Check environment for verbosity level
+    const verbose =
+      process.env.LOG_LEVEL === 'debug' ||
+      process.env.LOG_LEVEL === 'verbose' ||
+      process.env.NODE_ENV === 'development' ||
+      process.env.NODE_ENV === 'dev'
+
+    if (verbose) {
+      // DETAILED mode (development)
+      const optionDetails = invalidOptions
+        .map(
+          (opt) => `
+  ❌ ${opt.old}
+     → Use: ${opt.new}
+     → Why: ${opt.message}`
+        )
+        .join('\n')
+
+      return `
+❌ Invalid import options detected (Brainy v4.x breaking changes)
+
+The following v3.x options are no longer supported:
+${optionDetails}
+
+📖 Migration Guide: https://brainy.dev/docs/guides/migrating-to-v4
+💡 Quick Fix Examples:
+
+   Before (v3.x):
+   await brain.import(file, {
+     extractRelationships: true,
+     createFileStructure: true
+   })
+
+   After (v4.x):
+   await brain.import(file, {
+     enableRelationshipInference: true,
+     vfsPath: '/imports/my-data'
+   })
+
+🔗 Full API docs: https://brainy.dev/docs/api/import
+      `.trim()
+    } else {
+      // CONCISE mode (production)
+      const optionsList = invalidOptions.map((o) => `'${o.old}'`).join(', ')
+      return `Invalid import options: ${optionsList}. See https://brainy.dev/docs/guides/migrating-to-v4`
+    }
+  }
 }