---
name: project-ops
description: Access project tasks, stages and progress via Vikunja, and project documentation via Outline. Use for reading/creating/updating tasks, moving tasks between buckets (kanban stages), tracking percent done, and reading/writing docs on the home lab.
compatibility: all pi-agents (sam-4screen-desktop .27, nixos-desktop .13, ubuntu1 .35, machine .51)
---

# Project Ops — Vikunja (tasks/stages/progress) + Outline (documentation)

> The home-lab's project layer for any pi agent. **Vikunja** = tasks, kanban stages/buckets,
> percent-done progress. **Outline** = project documentation.
> These are shared across all four machines; keys are in the environment secrets.

## 1. Secrets (bearer tokens)

Keys are stored in the machine's secrets file. Read them at runtime, never print them:

- **Vikunja** token: `VIKUNJA_TOKEN` in `~/.config/environment.d/10-secrets.conf`
- **Outline** key: `OL_API_KEY` in `~/.config/environment.d/10-secrets.conf`

```bash
VIKUNJA_TOKEN=$(grep "^VIKUNJA_TOKEN=" ~/.config/environment.d/10-secrets.conf | head -1 | cut -d= -f2- | tr -d '"' | tr -d ' ')
OL_API_KEY=$(grep "^OL_API_KEY=" ~/.config/environment.d/10-secrets.conf | head -1 | cut -d= -f2- | tr -d '"' | tr -d ' ')
```

If token 401s: **Vikunja sometimes intermittently rejects a valid token** (transient; observed on LAN). First **retry once** — the same call returning 401 then 200 with an identical token is a known flake, not a wrong value. Only if a retry still 401s: re-source the secrets (new shell/login) so the fresh value is read; if still failing, ask the user to confirm the token was regenerated in Vikunja and re-placed. Outline keys are stable (401 there = genuinely wrong key).
Never commit or echo the token values.

## 2. Vikunja API (tasks, stages, progress)

Base: `https://vikunja.lab.audasmedia.com.au/api/v1`
Auth header: `Authorization: Bearer $VIKUNJA_TOKEN` (plus `Content-Type: application/json` on writes).

### Read
```bash
# all projects
curl -s "$BASE/projects?page=1&per_page=100" -H "Authorization: Bearer $VIKUNJA_TOKEN"

# tasks in a project (project_id from above)
curl -s "$BASE/projects/<project_id>/tasks?page=1&per_page=100" -H "Authorization: Bearer $VIKUNJA_TOKEN"

# a single task (shows bucket_id, percent_done, due_date)
curl -s "$BASE/tasks/<task_id>" -H "Authorization: Bearer $VIKUNJA_TOKEN"
```

### Create a task
```bash
curl -s -X PUT "$BASE/projects/<project_id>/tasks" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"new task","project_id":<project_id>}'
```

### Update task — stage / progress / done
```bash
# move task to a kanban bucket ("stage"). Find bucket ids first:
curl -s "$BASE/projects/<project_id>/buckets" -H "Authorization: Bearer $VIKUNJA_TOKEN"
# then update the task; POST /tasks/<id> with any of: bucket_id, percent_done, done, due_date, priority
curl -s -X POST "$BASE/tasks/<task_id>" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bucket_id":<bucket_id>,"percent_done":50}'
# mark done
curl -s -X POST "$BASE/tasks/<task_id>" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" -d '{"done":true}'
```

## 3. Outline API (documentation)

Base: `https://outline.lab.audasmedia.com.au/api`
Same bearer pattern (`Authorization: Bearer $OL_API_KEY`, `Content-Type: application/json`). Endpoints are **POST**.

> ⚠️ **Known flakiness:** the public (Caddy) endpoint intermittently returns **502** on writes/reads. If you get a 502, **retry once** (often transient). For reliable create/update (e.g. `documents.create`), go **directly to the container**: `POST http://127.0.0.1:3000/api/...` from `.13` (same key).

```bash
# collections (top-level doc groups)
curl -s -X POST "$OL_BASE/collections.list" -H "Authorization: Bearer $OL_API_KEY" \
  -H "Content-Type: application/json" -d '{"limit":50}'

# documents in a collection
curl -s -X POST "$OL_BASE/documents.list" -H "Authorization: Bearer $OL_API_KEY" \
  -H "Content-Type: application/json" -d '{"collectionId":"<id>","limit":50}'

# search docs
curl -s -X POST "$OL_BASE/documents.search" -H "Authorization: Bearer $OL_API_KEY" \
  -H "Content-Type: application/json" -d '{"query":"<search terms>","limit":10}'

# reliable direct create (on .13):
curl -s -X POST "http://127.0.0.1:3000/api/documents.create" -H "Authorization: Bearer $OL_API_KEY" \
  -H "Content-Type: application/json" -d '{"collectionId":"<id>","title":"<T>","text":"<md>","publish":true}'
```

## 4. Guidance

- When a user asks about a project's tasks/progress: use Vikunja. When they want the "what/why/how" documentation: use Outline.
- Keep payloads minimal; fetch then update (don't guess ids). Always confirm the write succeeded and report the outcome concisely (task moved to stage X / created id Y / doc found Z).
- This skill has full scope (create/update/move/delete + docs read/write unless stated otherwise).
- Works on all lab machines; records are shared, so changes appear everywhere.