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>

AGENTS.md

@@ -213,6 +213,40 @@ bd sync  # Force immediate export/commit/push
 
 **For comprehensive CLI documentation**, see [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md).
 
+### Import Configuration
+
+bd provides configuration for handling edge cases during import, especially when dealing with hierarchical issues and deleted parents:
+
+```bash
+# Configure orphan handling for imports
+bd config set import.orphan_handling "allow"      # Default: import orphans without validation
+bd config set import.orphan_handling "resurrect"  # Auto-resurrect deleted parents as tombstones
+bd config set import.orphan_handling "skip"       # Skip orphaned children with warning
+bd config set import.orphan_handling "strict"     # Fail if parent is missing
+```
+
+**Modes explained:**
+
+- **`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.
+- **`skip`** - Skip orphaned children with a 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 each mode:**
+
+- Use `allow` (default) for daily imports and auto-sync - ensures no data loss
+- Use `resurrect` when importing from another database that had parent deletions
+- Use `strict` only for controlled imports where you need to guarantee parent existence
+- Use `skip` rarely - only when you want to selectively import a subset
+
+**Override per command:**
+```bash
+bd import -i issues.jsonl --orphan-handling resurrect  # One-time override
+bd sync  # Uses import.orphan_handling config setting
+```
+
+See [docs/CONFIG.md](docs/CONFIG.md) for complete configuration documentation.
+
 ### Managing Daemons
 
 bd runs a background daemon per workspace for auto-sync and RPC operations:

README.md

@@ -663,10 +663,28 @@ bd export -o issues.jsonl
 # Import from JSONL (automatic when JSONL is newer)
 bd import -i issues.jsonl
 
+# Handle missing parents during import
+bd import -i issues.jsonl --orphan-handling resurrect  # Auto-recreate deleted parents
+bd import -i issues.jsonl --orphan-handling skip       # Skip orphans with warning
+bd import -i issues.jsonl --orphan-handling strict     # Fail on missing parents
+
 # Manual sync
 bd sync
 ```
 
+**Import Orphan Handling:**
+
+When importing hierarchical issues (e.g., `bd-abc.1`, `bd-abc.2`), bd needs to handle cases where the parent (`bd-abc`) has been deleted:
+
+- **`allow` (default)** - Import orphans without validation. Most permissive, ensures no data loss.
+- **`resurrect`** - Search JSONL history for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy.
+- **`skip`** - Skip orphaned children with warning. Partial import.
+- **`strict`** - Fail import if parent is missing.
+
+Configure default behavior: `bd config set import.orphan_handling resurrect`
+
+See [docs/CONFIG.md](docs/CONFIG.md) for complete configuration documentation.
+
 **Note:** Auto-sync is enabled by default. Manual export/import is rarely needed.
 
 ### Managing Daemons

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!
+# Handle missing parents during import
-# - If a hierarchical child's parent is missing (e.g., bd-abc.1 but no bd-abc)
+bd import -i issues.jsonl --orphan-handling allow      # Default: import orphans without validation
-# - bd will search the JSONL history for the parent
+bd import -i issues.jsonl --orphan-handling resurrect  # Auto-resurrect deleted parents as tombstones
-# - If found, creates a tombstone placeholder (Status=Closed, Priority=4)
+bd import -i issues.jsonl --orphan-handling skip       # Skip orphans with warning
-# - Dependencies are also resurrected on best-effort basis
+bd import -i issues.jsonl --orphan-handling strict     # Fail if parent is missing
-# - This prevents import failures after parent deletion
+
+# 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**.