# Issue tracker: Gitea (via `tea`)

Issues and specs for this repo live as **Gitea** issues at
<https://gitlab.hive-brain.de/RDietermann/dionotes-client>.

> The host is named `gitlab.hive-brain.de`, but the server is **Gitea 1.25.5**, not GitLab.
> `glab` will not work. Use the [`tea`](https://gitea.com/gitea/tea) CLI (v0.15 installed).

Run `tea` from inside the clone — it resolves owner/repo from `git remote`. It prints
`NOTE: no login matched this repository, falling back to login 'hive'` on every call;
that is harmless. Add `--login hive` to silence ambiguity, or `--repo RDietermann/dionotes-client`
when running from outside the clone.

## Conventions

- **Create an issue**: `tea issues create --title "..." --description "..." --labels "a,b"`.
  Use a heredoc piped through a shell variable for multi-line descriptions — `--description`
  takes a single string, there is no `-F file` flag.
- **Read one issue**: `tea issues <index>`. For machine-readable output or fields the CLI
  omits, use `tea api repos/RDietermann/dionotes-client/issues/<index>`.
- **List issues**: `tea issues ls --output json --fields index,title,state,labels,assignees,body`
  with `--labels`, `--assignee`, `--state` filters as needed.
- **Read comments**: `tea comments ls <index>`.
- **Comment on an issue**: `tea comments add <index> --description "..."`.
  (The subcommand is `add`, not `create`.)
- **Apply / remove labels**: `tea issues edit <index> --add-labels "a,b"` / `--remove-labels "a"`.
- **Assign**: `tea issues edit <index> --add-assignees RDietermann`.
- **Close**: `tea issues close <index>`. It takes no closing comment, so post the explanation
  first with `tea comments add`, then close.
- **Create a label** (they are not auto-created): `tea labels create --name "..." --color "#rrggbb"`.
- **Escape hatch**: `tea api <path>` makes an authenticated call against the Gitea API for
  anything the CLI does not model. `--method POST -d '<json>'` for writes.

The auth token carries `write:issue,write:repository,write:user` — but **not**
`write:organization`. Creating repos or issues under an org will fail; personal-account
operations work.

## Pull requests as a triage surface

**PRs as a request surface: no.** _(Set to `yes` if this repo treats external pull requests as
feature requests; `/triage` reads this flag.)_

When set to `yes`, PRs run through the same labels and states as issues, using `tea pulls ls`,
`tea pulls <index>`, and the same `tea comments` / `tea issues edit` commands — in Gitea, PRs
share the issue index space, so `#42` is either an issue or a PR, never both.

## When a skill says "publish to the issue tracker"

Create a Gitea issue.

## When a skill says "fetch the relevant ticket"

Run `tea issues <index>` plus `tea comments ls <index>`.

## Wayfinding operations

Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.

- **Map**: an issue labelled `wayfinder:map`, holding the Destination / Notes /
  Decisions-so-far / Not-yet-specified / Out-of-scope body.
  `tea issues create --title "..." --labels wayfinder:map --description "..."`.
- **Child ticket**: an issue carrying `Part of #<map>` as the first line of its description,
  plus a `wayfinder:<type>` label (`research` / `prototype` / `grilling` / `task`).
  Gitea 1.24+ has native sub-issues, but `tea` does not expose them — the `Part of #<map>`
  line is the convention here, and Gitea renders it as a cross-reference on the map.
- **Blocking**: Gitea has **native issue dependencies**, which is what renders the frontier in
  the web UI. `tea` does not wrap them, so use the API:
  `tea api --method POST repos/RDietermann/dionotes-client/issues/<child>/dependencies -d '{"index": <blocker>}'`.
  Read them back with `tea api repos/RDietermann/dionotes-client/issues/<child>/dependencies`.
  **Unverified** — the first session to wire a blocking edge should confirm this endpoint
  works and fix this line. If it does not, fall back to a `Blocked by: #<n>, #<n>` line at the
  top of the description. A ticket is unblocked when every blocker is closed.
- **Frontier query**: `tea issues ls --output json --labels wayfinder:grilling,wayfinder:research,wayfinder:prototype,wayfinder:task`,
  keep those whose body says `Part of #<map>`, drop any with an assignee (claimed) or an open
  blocker; first in map order wins.
- **Claim**: `tea issues edit <index> --add-assignees RDietermann` — the session's first write.
- **Resolve**: `tea comments add <index> --description "<answer>"`, then
  `tea issues close <index>`, then append a context pointer (gist + link) to the map's
  Decisions-so-far.