# Nextcloud Deck Roadmap Sync

Bidirectional sync system between trading bot roadmaps (markdown files) and Nextcloud Deck kanban board.

## Setup

### 1. Discover Board Configuration

First time setup - find your Nextcloud Deck board and stack IDs:

```bash
./scripts/discover-deck-ids.sh
```

This creates `/tmp/deck-config.json` with your board configuration.

### 2. Initialize Deck with Roadmap Cards

Create Deck cards from current roadmap:

```bash
python3 scripts/sync-roadmap-to-deck.py --init
```

This will:
- Parse all roadmap files (OPTIMIZATION_MASTER_ROADMAP.md, etc.)
- Create cards for each initiative/phase
- Place cards in appropriate stacks based on status
- Set due dates based on timelines

## Stack Mapping

| Deck Stack | Roadmap Status | Purpose |
|------------|----------------|---------|
| `eingang` (inbox) | FUTURE | Backlog items, ideas, future phases |
| `in planung` (planning) | PENDING | Ready to implement, needs detailed specs |
| `in arbeit` (in progress) | IN PROGRESS (🔄) | Currently working on |
| `erledigt` (done) | COMPLETE (✅) | Finished and verified |

## Usage

### Creating Roadmap Cards

**Option 1: Update markdown, sync to Deck**
1. Edit roadmap markdown files
2. Run: `python3 scripts/sync-roadmap-to-deck.py --init`
3. New initiatives/phases appear as Deck cards

**Option 2: Create card in Deck (future feature)**
1. Create card in Deck "eingang" stack
2. Title format: `[ROADMAP] Initiative Name`
3. Script will parse and add to appropriate roadmap file

### Updating Status

**Current:** Manual sync
- Move cards between stacks in Deck to reflect progress
- Update markdown roadmap files with status emoji (🔄, ✅, etc.)
- Re-sync to align

**Future:** Automatic bidirectional sync
- Script will update roadmap files based on card positions
- Cron job could run sync every hour

## Files

- `scripts/discover-deck-ids.sh` - Find board/stack IDs
- `scripts/sync-roadmap-to-deck.py` - Main sync script
- `/tmp/deck-config.json` - Nextcloud configuration (auto-generated)

## Configuration

Edit `/tmp/deck-config.json` or set environment variables:

```bash
export NEXTCLOUD_URL="http://10.0.0.48:8089"
export NEXTCLOUD_USER="robert.wiegand"
export NEXTCLOUD_PASSWORD="your-password"
```

## Roadmap Files

Currently syncs:
- `OPTIMIZATION_MASTER_ROADMAP.md` - Main overview
- `SIGNAL_QUALITY_OPTIMIZATION_ROADMAP.md` - Initiative 1
- `POSITION_SCALING_ROADMAP.md` - Initiative 2
- `ATR_BASED_TP_ROADMAP.md` - Initiative 3

## Future Features

- [ ] Bidirectional sync (Deck → Roadmap updates)
- [ ] Manual card creation → roadmap entry
- [ ] Automated sync via cron
- [ ] Phase-level cards (not just initiative-level)
- [ ] Label management (optimization, data-collection, analysis)
- [ ] Due date calculations from timeline estimates
- [ ] Progress tracking from card checklists

## API Reference

Nextcloud Deck API: `/index.php/apps/deck/api/v1.0`

Key endpoints used:
- `GET /boards` - List all boards
- `GET /boards/{boardId}` - Get board details
- `GET /boards/{boardId}/stacks` - Get stacks
- `POST /boards/{boardId}/stacks/{stackId}/cards` - Create card

## Troubleshooting

**"Board not found"**
- Run `discover-deck-ids.sh` first
- Check board exists in Nextcloud Deck
- Verify name contains "trader" (case insensitive)

**"405 Method Not Allowed"**
- Nextcloud Deck version may have different API
- Check Nextcloud Deck version in settings
- Some GET endpoints may not be available

**"Cards not syncing"**
- Check `/tmp/deck-config.json` exists
- Verify credentials in config
- Run with `--dry-run` first to test

## Development

**Adding new roadmap files:**

Edit `sync-roadmap-to-deck.py`:
```python
ROADMAP_FILES = [
    'OPTIMIZATION_MASTER_ROADMAP.md',
    'YOUR_NEW_ROADMAP.md',  # Add here
]
```

**Customizing status mapping:**

Edit `STATUS_TO_STACK` dict:
```python
STATUS_TO_STACK = {
    'IN PROGRESS': 'in arbeit',
    'YOUR_STATUS': 'your_stack',  # Add here
}
```