89 lines
4.0 KiB
Markdown
89 lines
4.0 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 -oE 'VIKUNJA_TOKEN=[A-Za-z0-9]+' ~/.config/environment.d/10-secrets.conf | cut -d= -f2)
|
|
OL_API_KEY=$(grep -oE 'OL_API_KEY=[A-Za-z0-9]+' ~/.config/environment.d/10-secrets.conf | cut -d= -f2)
|
|
```
|
|
|
|
If token 401s: re-source or confirm the machine's secrets were pulled (`git -C ~/.agents pull`).
|
|
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**.
|
|
|
|
```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}'
|
|
```
|
|
|
|
## 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. |