# Issue tracker: Forgejo (forgejo-cli)
Issues and PRDs for this repo live as **Forgejo issues** at
`code.cosmicrose.dev/rosa/lucre`. Forgejo is not GitHub or GitLab, so the
`gh` / `glab` CLIs do **not** apply here. Drive everything through the
[forgejo-cli](https://codeberg.org/Cyborus/forgejo-cli), whose binary is `fj`.
`fj` operates on the repo behind a local git remote, so run it from inside this
clone. It targets `origin` by default; pass `-R <remote>` to override.
## Setup
`fj` must be authenticated against the instance before any command works
(`fj whoami` returns "not logged in" otherwise). This is an interactive,
one-time step the user runs:
```sh
fj auth login # follow the prompts for https://code.cosmicrose.dev
```
If a command fails with an auth error, stop and ask the user to log in rather
than falling back to raw API calls.
## Conventions
- **Create an issue**: `fj issue create "Title here" --body "..."`. For
multi-line markdown bodies, write the body to a file and pass
`--body-file <path>` (omitting both `--body` and `--body-file` opens an
editor, which won't work non-interactively).
- **Read an issue**: `fj issue view <id>` for the title and body;
`fj issue view <id> comments` to list every comment;
`fj issue view <id> comment <comment-id>` for a single one.
- **List / search issues**: `fj issue search [QUERY]`. Filter with
`-l/--labels <labels>`, `-s/--state <open|closed|all>` (default `open`),
`-c/--creator <user>`, `-a/--assignee <user>`. Output is plain text; piping
forces `--style minimal` automatically.
- **Comment on an issue**: `fj issue comment <id> "body"` (or `--body-file`).
- **Apply / remove labels**: `fj issue edit <id> labels --add <name>` and
`--rm <name>`. Labels are referenced by **name**, not ID. If a triage label
doesn't exist in the repo yet, create it first in the Forgejo web UI (Issues →
Labels); see `triage-labels.md` for the role → label-name mapping.
- **Edit title / body**: `fj issue edit <id> title "..."` /
`fj issue edit <id> body "..."`.
- **Close**: `fj issue close <id> --with-msg "explanation"`. The `--with-msg`
flag posts the comment before closing, so no separate comment call is needed.
## Pull requests as a triage surface
**PRs as a request surface: no.** External pull requests are **not** pulled into
the triage queue; `/triage` operates on issues only. (To turn this on later,
change this line to `yes` — `/triage` would then enumerate PRs via
`fj pr search`, keep only those whose author is not a repo collaborator, and run
them through the same labels/states as issues using the `fj pr` subcommands:
`view`, `comment`, `edit`, `close`.)
## When a skill says "publish to the issue tracker"
Create a Forgejo issue with `fj issue create`.
## When a skill says "fetch the relevant ticket"
`fj issue view <id>` (add `comments` for the discussion). The user will normally
pass the issue number directly.