Vikunja Kanban

SKILL.md

# Vikunja Kanban Skill

Manage a Vikunja kanban board via API. Read status, create/move/complete tasks, and integrate with heartbeat and triage crons.

## Config

Credentials stored in `secrets/vikunja.env`:
```
VIKUNJA_URL=https://your-vikunja-instance
VIKUNJA_TOKEN=${VIKUNJA_TOKEN}
VIKUNJA_PROJECT_ID=1
VIKUNJA_VIEW_ID=4
```

## Authentication

All scripts use a **long-lived API token** (expires 2030-01-01). No JWT login needed.
- Permissions: tasks (read_all, update, create, delete), projects (read_all, update, create)
- JWT login credentials kept in `secrets/vikunja.env` for reference only

## Bucket IDs

| ID | Name | Purpose |
|----|------|---------|
| 1 | 🔴 Urgent | Needs immediate attention |
| 2 | ⏳ Waiting On | Sent/requested, awaiting reply |
| 7 | ⚠️ System Issues | Infra/system problems |
| 8 | 🚧 Active Projects | In progress |
| 9 | 📅 Upcoming | Scheduled/future |
| 10 | 📥 Inbox | New items, untriaged |
| 3 | ✅ Done | Completed |

## Scripts

All scripts are in the skill's `scripts/` directory. Run from the skill root.

### Read the board
```bash
bash scripts/vikunja-status.sh              # All buckets
bash scripts/vikunja-status.sh "Urgent"     # Filter by bucket name
```

### Add a task
```bash
bash scripts/vikunja-add-task.sh "Title" "Description" BUCKET_ID [PRIORITY]
# Priority: 0=unset, 1=low, 2=medium, 3=high, 4=urgent
# Example: bash scripts/vikunja-add-task.sh "Fix DNS" "Check records" 1 4
```

### Move a task between buckets
```bash
bash scripts/vikunja-move-task.sh TASK_ID BUCKET_ID
# Example: bash scripts/vikunja-move-task.sh 15 3  # Move to Done
```

### Complete a task
```bash
bash scripts/vikunja-complete-task.sh TASK_ID
```

## Heartbeat Integration

The heartbeat cron reads from Vikunja:
```bash
bash scripts/vikunja-status.sh
```
- Check 🔴 Urgent for items aging >1h
- If Vikunja unreachable, fall back to `scripts/nc-status-board.sh read`

## Email Triage Integration

Email triage adds Action Required items to the Inbox bucket:
```bash
bash scripts/vikunja-add-task.sh "Email subject" "Brief description" 10 3
```

## API Reference

- **Base URL:** https://your-vikunja-instance/api/v1
- **Auth:** POST /login with username/password → JWT token (short-lived)
- **Tasks:** PUT /projects/{id}/tasks (create), POST /tasks/{id} (update)
- **Buckets:** POST /projects/{id}/views/{view}/buckets/{bucket}/tasks (move task)
- **Views:** GET /projects/{id}/views/{view}/tasks (list tasks by bucket)
- **Projects:** POST /projects/{id} (update title/settings), GET /projects (list all)
- **Sharing:** PUT /projects/{id}/users `{"username":"...", "right":N}` (add user)
- **Users:** GET /users?s=query (search), POST /user/password (self-service password change)

## Known API Bugs & Gotchas

### Sharing permissions ignored on creation
`PUT /projects/{id}/users` ignores the `right` field — always creates with permission=0 (read-only).
**Workaround:** Set permission directly in PostgreSQL:
```sql
UPDATE users_projects SET permission = 2 WHERE user_id = X AND project_id = Y;
```
Permission values: 0=read-only, 1=read+write, 2=admin

### Default Inbox project cannot be deleted
Every new user gets an auto-created "Inbox" project. `DELETE /projects/{id}` returns error 3012.
**Workaround:** Rename it: `POST /projects/{id}` with `{"title":"New Name"}`

### Password change is self-service only
No admin endpoint to change another user's password. Must login as the target user:
`POST /api/v1/user/password` with `{"old_password":"...", "new_password":"..."}`

### API token creation needs both tasks AND projects permissions
Tokens with only `tasks` permissions cannot read kanban views (returns 401).
Must include: `"permissions":{"tasks":["read_all","update","create","delete"],"projects":["read_all","update","create"]}`

### Token creation endpoint
`PUT /api/v1/tokens` to create, `GET /api/v1/tokens` to list, `DELETE /api/v1/tokens/{id}` to remove.
Required fields: `title`, `expires_at` (ISO-8601), `permissions` (object with permission groups).

## Notes

- **Long-lived API token** used (expires 2030) — no JWT login overhead
- Vikunja uses PUT for creation, POST for updates (unusual)
- Bucket IDs are specific to the Kanban view (view_id=4)
- Project name: "Kit Operations" (renamed from default "Inbox")
- Project shared: Kit (id:1, admin/owner), Alex (id:2, admin via DB fix)
- Token has tasks + projects permissions; covers all kanban operations
- Each user gets a default project that can't be deleted — rename to avoid confusion