# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a tool for exporting Outline wiki data via API. The script runs inside a Docker container on the `domnet` network to bypass Authentik SSO authentication and access the internal Outline API directly (`http://outline:3000`).

## Usage

```bash
# Run the export with tree visualization
./export_with_trees.sh

# Preview without exporting (dry run)
./export_with_trees.sh --dry-run

# Run with verbose output
./export_with_trees.sh -v
```

### CLI Options
```
--dry-run, -n       Preview what would be exported without writing files
--output, -o DIR    Output directory (overrides settings.json)
--verbose, -v       Increase verbosity (-vv for debug)
--skip-verify       Skip post-export verification
--skip-health-check Skip pre-export health check
--settings FILE     Path to settings file (default: settings.json)
```

### Running the Python Export Directly
```bash
docker run --rm --network domnet \
    -v "$(pwd):/work" \
    -w /work \
    python:3.11-slim \
    bash -c "pip install -q requests tqdm && python3 outline_export_fixed.py"

# With options
docker run --rm --network domnet \
    -v "$(pwd):/work" \
    -w /work \
    python:3.11-slim \
    bash -c "pip install -q requests tqdm && python3 outline_export_fixed.py --dry-run"
```

## Architecture

### Docker Network Integration
- Script runs in Docker container attached to `domnet` bridge network
- Direct API access to `http://outline:3000` (internal) bypasses SSO
- Uses `python:3.11-slim` image with `requests` and `tqdm` dependencies

### Export Flow
1. Fetch collections via `/api/collections.list`
2. Get navigation tree via `/api/collections.documents` (source of truth for hierarchy)
3. Fetch full document content via `/api/documents.info` (with caching)
4. Export recursively maintaining parent-child structure
5. Save metadata (`_collection_metadata.json`) per collection
6. Generate manifest with checksums for verification

### Key Files
- `export_with_trees.sh` - Main export script with tree visualization
- `outline_export_fixed.py` - Core export logic with `OutlineExporter` class
- `settings.json` - API URL and token configuration (contains secrets)
- `outline_export/` - Output directory with markdown files and metadata
- `outline_backup_*.tar.gz` - Timestamped compressed backups

### Configuration
Settings are in `settings.json`:
- `source.url` - Internal Docker URL (`http://outline:3000`)
- `source.token` - Outline API token
- `export.output_directory` - Output path (default: `outline_export`)
- `advanced.max_hierarchy_depth` - Prevent infinite recursion (default: 100)

## Important Notes

### Security
- `settings.json` contains API token - never commit to git
- Backup files may contain sensitive wiki content

### Backup System
- Each export automatically backs up previous exports to `outline_backup_YYYYMMDD_HHMMSS.tar.gz`
- Old uncompressed export directory is deleted after backup
- Backups achieve 90%+ compression on markdown content

### Reliability Features
- **Health check**: Verifies API connectivity before export
- **Retry logic**: Failed API requests retry up to 3 times with exponential backoff
- **Logging**: Structured logging with configurable verbosity levels

### 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.