# UQ Planner — guide for LLMs and AI coding tools

UQ Planner is a project tracker (boards, epics, tasks, bugs, docs). You can read and update a
project's tasks over HTTP or with the `uqplanner` CLI, acting as the person whose API key you use.

- Web app: https://planner.uniqtech.dev
- API base: https://planner.uniqtech.dev/api
- This page: https://planner.uniqtech.dev/llms.txt (also https://planner.uniqtech.dev/llm, https://planner.uniqtech.dev/.llm)

## 1. Get access (ask the user)

1. The user signs in at https://planner.uniqtech.dev and opens **Account → API key** (https://planner.uniqtech.dev/account/api-keys).
2. They copy the key (`uqp_…`) — or click **Copy prompt for AI**, which gives you a personal
   version of this guide with their key, organizations and project keys filled in.
3. Never print the key back in full, commit it, or put it in shared files. Store it in an env var
   (e.g. `UQP_API_KEY`) or the CLI login below.

Every request sends:

```
Authorization: Bearer <uqp_… key>
X-Organization-Id: <org id>        # optional when the user belongs to one organization
```

Check it works: `GET https://planner.uniqtech.dev/api/auth/me` → the user and their organization memberships.
Personal guide (orgs, project keys): `GET https://planner.uniqtech.dev/api/me/api-guide`.

## 2. Option A — the CLI (recommended inside a code repo)

```bash
curl -fsSL https://planner.uniqtech.dev/api/cli/install | bash          # Windows: irm https://planner.uniqtech.dev/api/cli/install.ps1 | iex
uqplanner login uqp_xxxxxxxx                  # verifies the key, saves ~/.config/uqplanner/auth.json
uqplanner org                                  # list organizations; switch: uqplanner org use "<name>"
uqplanner projects                             # list projects (key, id, name)
uqplanner link <projectId>                     # pin this repo to a project (.uqplanner.json)
```

Then:

| Command | What it does |
|---|---|
| `uqplanner next [--limit 5] [--all]` | Your open tasks, best first, with full context → `.uqplanner/queue.md` |
| `uqplanner tasks [--mine] [--status "In Progress"]` | Task table |
| `uqplanner task pull PRO-13` | Task as Markdown → `.uqplanner/tasks/PRO-13.md` |
| `uqplanner task push PRO-13` | Send your edits back (fields, description, subtasks, new comments) |
| `uqplanner task new draft.md` | Create a task from a Markdown document |
| `uqplanner upload PRO-13 ./shot.png` | Attach a file (screenshot, video, log) |

Add `.uqplanner/` to the repo's `.gitignore`.

## 3. Option B — plain HTTP

| What | Request |
|---|---|
| What to work on next | `GET https://planner.uniqtech.dev/api/user-tasks/queue?project=PRO&limit=5` (Markdown; `&format=json` for JSON; `&assignee=any` for the whole team) |
| List tasks | `GET https://planner.uniqtech.dev/api/user-tasks/markdown?project=PRO&status=In%20Progress&assignee=me&type=BUG` |
| Read a task | `GET https://planner.uniqtech.dev/api/user-tasks/PRO-13/markdown` |
| Update a task | `PUT https://planner.uniqtech.dev/api/user-tasks/PRO-13/markdown` — body: the edited document, `Content-Type: text/markdown` |
| Create a task | `POST https://planner.uniqtech.dev/api/user-tasks/markdown` — body: a document without `key` (set `project:`) |
| Linked work items | `GET https://planner.uniqtech.dev/api/user-tasks/<taskId>/links`; add: `POST` same path `{"kind":"relates_to"|"is_blocked_by","taskId":"<other id>"}`; remove: `DELETE …/links/<linkId>` |
| Labels in use | `GET https://planner.uniqtech.dev/api/user-tasks/labels` |
| Attach a file | `POST https://planner.uniqtech.dev/api/files/upload` (multipart: `file`, `entityType=task`, `entityId=<taskId>`) |
| Docs page tree / page / search | `GET https://planner.uniqtech.dev/api/docs/<projectId>/tree`, `…/pages/<pageId>`, `…/search?q=` |

Tasks are addressed by key (`PRO-13`) or id. Errors are JSON `{ statusCode, message }`.

## 4. The task document

```markdown
---
key: PRO-13                 # read-only
project: PRO                # read-only on update; required on create
type: TASK                  # EPIC | TASK | BUG | SUBTASK
status: In Progress         # one of the project's workflow columns (see the queue's "Workflow" section)
parent: PRO-11              # epic for a TASK/BUG; task or bug for a SUBTASK
blockedBy: [PRO-9]          # read-only (links) — also: blocks, relatesTo
assignees: [dev@example.com]
labels: [frontend]
reporter: lead@example.com
reviewer:
start: 2026-10-01
due: 2026-10-08             # within 10 years of today; not before start
fields: {}                  # template custom fields by name (e.g. Priority: High)
updatedAt: 2026-10-03T14:20:00.000Z   # keep as received — used for conflict detection
---
# Title

Description in Markdown (tables, code, links, images).

<!-- planner:subtasks -->
## Subtasks
- [ ] PRO-21 Close on Escape        # tick [x] to move it to Done; a line without a key creates one

<!-- planner:comments -->
## Comments
### Dev · 2026-10-03 14:20 UTC
<!-- comment:cm… -->
Existing comments are read-only.

### Done
A new ### section at the end (no comment marker) is posted as a new comment.
```

Rules:
- Send the whole document back; only what you changed is applied (people by email or name,
  status matched to a column, parent by key).
- **409** = someone changed the same field since your `updatedAt` — fetch again, redo the edit.
- **400** explains what's wrong (unknown status, unknown person, bad date, wrong parent type).
- Hierarchy: EPIC → TASK | BUG → SUBTASK.

## 5. How to work on a task

1. `GET /user-tasks/queue` (or `uqplanner next`) and take task 1. It lists why it's first, the epic, docs
   pages that mention it, attachments, and the full task document.
2. Move it to an in-progress column (edit `status:`, PUT the document).
3. Read the description, epic, linked docs pages and comments — newer comments override the description.
   Check `blockedBy:` before starting.
4. Do the work in the repo. Tick subtasks as you finish them; add missing steps as `- [ ] …` lines.
5. When done: add a `### Done` comment (what changed, how you tested it), upload evidence
   (screenshots, test output) with `/files/upload`, and move `status:` to the review / next column.
6. Don't change assignees, epics or other people's comments unless the user asks.

## 6. Docs (git)

Each project has a documentation space stored as a git repository of Markdown pages.
The user adds an SSH key in **Account → SSH keys**; `GET https://planner.uniqtech.dev/api/docs/<projectId>/repo` returns the clone URL
(`ssh://git@<host>:2222/<org>/<project>.git`). Clone, edit Markdown, push. Reading over HTTP works too (section 3).
Mention a task in a page by its URL (`https://planner.uniqtech.dev/projects/<projectId>?modal=task&taskId=<id>`) — the task then
lists the page under "Linked pages".