From e4c69efd1234e89c29d1b531d2b23bdcd3315ec3 Mon Sep 17 00:00:00 2001
From: Claude <claude@local>
Date: Mon, 19 Jan 2026 22:49:07 +0100
Subject: [PATCH] Add import tool documentation to CLAUDE.md

- Usage examples and CLI options
- Import modes (collection-per-folder, single)
- Import flow explanation
- Output example with tree visualization
- Duplicate handling and error handling reference

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7385a7c..0d50a02 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -92,3 +92,115 @@ Settings are in `settings.json`:
 
 ### Document Counting
 The navigation tree (`/api/collections.documents`) is the source of truth for document hierarchy. Document counting is recursive to include all nested children.
+
+---
+
+## Import Tool
+
+The import script restores exported markdown files back into Outline, preserving the full document hierarchy.
+
+### Usage
+
+```bash
+# Import all collections from outline_export/
+./import_to_outline.sh
+
+# Preview what would be imported (no changes made)
+./import_to_outline.sh --dry-run
+
+# Import into a single timestamped collection
+./import_to_outline.sh --single
+
+# Import from a different directory
+./import_to_outline.sh -d exports/
+
+# Overwrite existing collections
+./import_to_outline.sh --force
+```
+
+### CLI Options
+```
+-s, --single        Import all into single timestamped collection
+-n, --dry-run       Preview operations without making changes
+-d, --source DIR    Source directory (default: outline_export)
+-v, --verbose       Increase verbosity (-vv for debug)
+-f, --force         Overwrite existing collections (instead of skip)
+--settings FILE     Path to settings file (default: settings.json)
+-h, --help          Show help message
+```
+
+### Import Modes
+
+**Collection-per-Folder (Default)**
+Each subdirectory becomes a separate collection:
+```
+outline_export/
+├── Bewerbungen/     → Creates "Bewerbungen" collection
+├── Projekte/        → Creates "Projekte" collection
+└── Privat/          → Creates "Privat" collection
+```
+
+**Single Collection (`--single`)**
+All content goes into one timestamped collection:
+```
+outline_export/
+├── Bewerbungen/     → Becomes parent doc "Bewerbungen"
+├── Projekte/        → Becomes parent doc "Projekte"
+└── Privat/          → Becomes parent doc "Privat"
+
+All imported into: "import_20260119_143052" collection
+```
+
+### Import Flow
+1. Load `_collection_metadata.json` from each collection directory
+2. Build document tree maintaining parent-child relationships
+3. Create collections via `/api/collections.create`
+4. Create documents via `/api/documents.create` with proper `parentDocumentId`
+5. Map old IDs to new IDs to maintain hierarchy
+6. Display tree-style progress with status indicators
+
+### Key Files
+- `import_to_outline.sh` - Bash wrapper with Docker execution
+- `outline_import.py` - Core import logic with `OutlineImporter` class
+
+### Output Example
+```
+════════════════════════════════════════════════════════════
+  OUTLINE IMPORT
+════════════════════════════════════════════════════════════
+
+Source:  outline_export/
+Target:  http://outline:3000
+Mode:    Collection per folder
+
+Checking API connectivity... ✓
+
+Bewerbungen/ (11 documents)
+  Creating collection... ✓ (id: 7f3a...)
+  ├── CV.md                              ✓ created
+  ├── Tipico.md                          ✓ created
+  │   ├── Pitch Tipico.md                ✓ created
+  │   └── Fragen 3. Runde.md             ✓ created
+  └── Ihre PVS.md                        ✓ created
+
+════════════════════════════════════════════════════════════
+SUMMARY
+════════════════════════════════════════════════════════════
+  Collections:  1 created, 0 skipped, 0 errors
+  Documents:   11 created, 0 skipped, 0 errors
+  Duration:     2.3 seconds
+════════════════════════════════════════════════════════════
+```
+
+### Duplicate Handling
+| Scenario | Default | With `--force` |
+|----------|---------|----------------|
+| Collection exists | Skip entire collection | Delete and recreate |
+| Document exists | Skip document | Update document |
+
+### Error Handling
+- **API connection failure**: Abort with error message
+- **Collection creation fails**: Abort that collection, continue others
+- **Document creation fails**: Log error, continue with siblings
+- **Missing markdown file**: Log warning, skip document
+- **Parent not found**: Create as root-level document