95 lines
4.9 KiB
Markdown
95 lines
4.9 KiB
Markdown
---
|
|
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. |