trading_bot_v4/docs/NEXTCLOUD_DECK_SYNC.md

# 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 |
|------------|----------------|---------|
| 📥 Backlog | FUTURE | Backlog items, ideas, future phases |
| 📋 Planning | PENDING | Ready to implement, needs detailed specs |
| 🚀 In Progress | IN PROGRESS (🔄) | Currently working on |
| ✅ Complete | 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 with stacks (no cards included)
- `GET /boards/{boardId}/stacks/{stackId}` - Get stack with cards (this works!)
- `POST /boards/{boardId}/stacks/{stackId}/cards` - Create card
- `PUT /boards/{boardId}/stacks/{stackId}` - Rename stack

**Note:** Many endpoints return 405 Method Not Allowed:
- `GET /boards/{boardId}/stacks/{stackId}/cards` - Not supported
- `DELETE /boards/{boardId}/cards/{cardId}` - Not supported
- `GET /boards/{boardId}/cards/{cardId}` - Not supported

## Known Limitations

1. **No Duplicate Detection**: The Deck API v1.0 doesn't support listing cards by stack, so:
   - Running `--init` multiple times creates duplicate cards
   - Delete duplicates manually from the Nextcloud Deck UI
   - Always use `--dry-run` first to preview changes

2. **No Card Deletion API**: The DELETE endpoint returns 405, so:
   - Test cards must be deleted manually from the web UI
   - No automated cleanup possible

3. **Limited GET Support**: Most card-level GET endpoints return 405:
   - Cannot verify card creation without checking full stack
   - Use `GET /boards/{boardId}/stacks/{stackId}` to view cards

4. **No Bidirectional Sync**: Card position changes in Deck don't update markdown files

5. **Initiative-Level Only**: Currently only syncs high-level initiatives, not individual phases

## 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"**
- Normal for most GET/DELETE card endpoints
- Use stack endpoint instead: `GET /boards/{boardId}/stacks/{stackId}`
- Check Nextcloud Deck API documentation for your version

**"Cards not showing in board"**
- Cards ARE created but not visible in `GET /boards/{boardId}` response
- Use `GET /boards/{boardId}/stacks/{stackId}` to view cards properly
- Or check the Nextcloud Deck web UI

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

**"Duplicate cards"**
- This is expected - API doesn't support duplicate checking
- Delete extras manually from Nextcloud Deck UI
- Always run `--dry-run` before `--init`

## 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 Progress',
    'YOUR_STATUS': '📋 Your Stack',  # Add here (with emoji)
}
```