docs: Complete import.orphan_handling documentation (bd-9cdc)

Added comprehensive documentation for import orphan handling configuration
across all relevant documentation files:

- AGENTS.md: Added "Import Configuration" section with detailed mode
  explanations and usage guidance
- README.md: Documented orphan handling in Export/Import section with
  examples of all four modes
- TROUBLESHOOTING.md: Added "Import fails with missing parent errors"
  troubleshooting section with resurrection examples and prevention tips
- CLI_REFERENCE.md: Expanded Import/Export section with --orphan-handling
  flag documentation and cross-references

Documented resurrection behavior:
- Tombstone creation (Status=Closed, Priority=4)
- JSONL history search for deleted parents
- Best-effort dependency resurrection
- Hierarchical ancestor chain handling

Closes bd-9cdc

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

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

docs/CLI_REFERENCE.md

@@ -341,14 +341,32 @@ bd import -i .beads/issues.jsonl --dry-run      # Preview changes
 bd import -i .beads/issues.jsonl                # Import and update issues
 bd import -i .beads/issues.jsonl --dedupe-after # Import + detect duplicates
 
-# Note: Import automatically handles missing parents!
-# - If a hierarchical child's parent is missing (e.g., bd-abc.1 but no bd-abc)
-# - bd will search the JSONL history for the parent
-# - If found, creates a tombstone placeholder (Status=Closed, Priority=4)
-# - Dependencies are also resurrected on best-effort basis
-# - This prevents import failures after parent deletion
+# Handle missing parents during import
+bd import -i issues.jsonl --orphan-handling allow      # Default: import orphans without validation
+bd import -i issues.jsonl --orphan-handling resurrect  # Auto-resurrect deleted parents as tombstones
+bd import -i issues.jsonl --orphan-handling skip       # Skip orphans with warning
+bd import -i issues.jsonl --orphan-handling strict     # Fail if parent is missing
+
+# Configure default orphan handling behavior
+bd config set import.orphan_handling "resurrect"
+bd sync  # Now uses resurrect mode by default
 ```
 
+**Orphan handling modes:**
+
+- **`allow` (default)** - Import orphaned children without parent validation. Most permissive, ensures no data loss even if hierarchy is temporarily broken.
+- **`resurrect`** - Search JSONL history for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis.
+- **`skip`** - Skip orphaned children with warning. Partial import succeeds but some issues are excluded.
+- **`strict`** - Fail import immediately if a child's parent is missing. Use when database integrity is critical.
+
+**When to use:**
+- Use `allow` (default) for daily imports and auto-sync
+- Use `resurrect` when importing from databases with deleted parents
+- Use `strict` for controlled imports requiring guaranteed parent existence
+- Use `skip` rarely - only for selective imports
+
+See [CONFIG.md](CONFIG.md#example-import-orphan-handling) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md#import-fails-with-missing-parent-errors) for more details.
+
 ### Migration
 
 ```bash

docs/TROUBLESHOOTING.md

@@ -160,6 +160,57 @@ rm .beads/*.db
 bd import -i .beads/issues.jsonl
 ```
 
+### Import fails with missing parent errors
+
+If you see errors like `parent issue bd-abc does not exist` when importing hierarchical issues (e.g., `bd-abc.1`, `bd-abc.2`), this means the parent issue was deleted but children still reference it.
+
+**Quick fix using resurrection:**
+
+```bash
+# Auto-resurrect deleted parents from JSONL history
+bd import -i issues.jsonl --orphan-handling resurrect
+
+# Or set as default behavior
+bd config set import.orphan_handling "resurrect"
+bd sync  # Now uses resurrect mode
+```
+
+**What resurrection does:**
+
+1. Searches the full JSONL file for the missing parent issue
+2. Recreates it as a tombstone (Status=Closed, Priority=4)
+3. Preserves the parent's original title and description
+4. Maintains referential integrity for hierarchical children
+5. Also resurrects dependencies on best-effort basis
+
+**Other handling modes:**
+
+```bash
+# Allow orphans (default) - import without validation
+bd config set import.orphan_handling "allow"
+
+# Skip orphans - partial import with warnings
+bd config set import.orphan_handling "skip"
+
+# Strict - fail fast on missing parents
+bd config set import.orphan_handling "strict"
+```
+
+**When this happens:**
+
+- Parent issue was deleted using `bd delete`
+- Branch merge where one side deleted the parent
+- Manual JSONL editing that removed parent entries
+- Database corruption or incomplete import
+
+**Prevention:**
+
+- Use `bd delete --cascade` to also delete children
+- Check for orphans before cleanup: `bd list --id bd-abc.*`
+- Review impact before deleting epic/parent issues
+
+See [docs/CONFIG.md](docs/CONFIG.md#example-import-orphan-handling) for complete configuration documentation.
+
 ### Database corruption
 
 **Important**: Distinguish between **logical consistency issues** (ID collisions, wrong prefixes) and **physical SQLite corruption**.