## Problem Statement

Coding agents that need to drive a Gitea-hosted workflow (issues, pull requests, labels) today have two poor options.
The official `tea` CLI is human-oriented: it has no token-efficiency, no contextual guidance, and no agent-facing error conventions.
Gitea's MCP servers expose the full API surface (dozens of tools) rather than being tuned for token or turn efficiency.
There is no Gitea-focused tool built to the same "agent ergonomics" standard that `gh-axi` established for GitHub.

## Solution

Build `gitea-axi`: a thin TypeScript CLI that calls the Gitea REST API directly via `gitea-js`, reshaping its output according to all 10 AXI (Agent eXperience Interface) principles.
The canonical principle text at https://axi.md/ is the design authority.
The `gh-axi` reference implementation is a non-binding shape reference for concrete interface details (block names, flag names, field extractors), departed from freely — with each deliberate departure documented in place.
It gives coding agents an ergonomic, low-token way to drive issues and pull requests on any Gitea instance.
It ships as both an installable npm CLI and a bundled Agent Skill, so any agent session can adopt it with one install step.

## User Stories

1. As a coding agent, I want to create a Gitea issue with a title, body, and labels, so that I can record work items for later retrieval.
2. As a coding agent, I want to find issues by label and state, so that I can locate relevant work without already knowing its issue number.
3. As a coding agent, I want to read an issue's full body, labels, and comments, so that I can load its context into a session.
4. As a coding agent, I want to add and remove labels on an existing issue, so that I can reflect state transitions as work progresses.
5. As a coding agent, I want to create a pull request from the current branch, so that completed work becomes reviewable.
6. As a coding agent, I want to fetch a pull request's metadata and diff, so that review tooling can operate on it without re-deriving it from git.
7. As a coding agent, I want to post a comment on a pull request, so that findings or notes are visible as a permanent reference on the PR itself.
8. As a coding agent, I want command output in TOON format with minimal default fields and truncated large fields, so that repeated calls across a long-running session don't consume excessive context.
9. As a coding agent, I want pre-computed aggregates in list and read output, so that I don't need follow-up calls just to derive obvious derived fields.
10. As a coding agent, I want explicit empty-state output when a query returns nothing, so that "no results" is never ambiguous with an error or a hang.
11. As a coding agent, I want structured errors with actionable suggestions and meaningful exit codes instead of prose failures, so that I can self-correct without the operator's help.
12. As a coding agent, I want mutations to be idempotent and to never prompt interactively, so that unattended, scripted use never stalls or double-applies.
13. As a coding agent, I want contextual next-step suggestions appended after output, so that I know what to call next without being taught the tool from scratch every session.
14. As a coding agent, I want a consistent per-subcommand `--help`, so that I can discover the interface on demand rather than needing it pre-loaded in context.
15. As an operator, I want `gitea-axi` run with no arguments to show live, actionable repository state instead of a help screen, so that I get immediate value without memorizing flags.
16. As an operator, I want `gitea-axi` to reuse my existing `tea` login configuration, so that I don't manage a second set of credentials.
17. As an operator, I want `gitea-axi`'s command surface to stay generic, with no workflow-specific behavior baked in, so that it's useful across different projects without code changes.
18. As an operator, I want `gitea-axi` published to npm and as an installable Agent Skill, so that I (and others) can adopt it with a single install command plus an explicit one-time `gitea-axi setup`.
19. As an operator, I want an optional `gitea-axi setup hooks` command that injects the dashboard into my agent sessions at session start, so that my agent begins each session already aware of the repository's live state.

## Implementation Decisions

### Language and Runtime

TypeScript on Node 20+, matching the `gh-axi` reference implementation.
ESM module format.

### Implementation Strategy

Call the Gitea REST API directly via `gitea-js` (the official TypeScript client generated from Gitea's OpenAPI spec).
This is not a subprocess wrapper — it is a direct HTTP API client.

Tea was evaluated as a subprocess target and rejected during design (see ADR 0002).
The short version: tea's create commands have no `--output json` flag, its PR list has no head-branch filter, it exposes no review or total counts in JSON, and diff content requires a direct HTTP GET regardless — making a tea wrapper a patchwork of subprocess calls and text parsing rather than a clean pipeline.

`gitea-js` gives clean typed responses, `X-Total-Count` headers for pagination, review counts, and immediate JSON from create operations.

### Auth

gitea-axi reads credentials from tea's login store via `tea login list --output json`.
It requires `tea` to be installed and at least one login configured via `tea login add`.
At startup, it detects the current repository's Gitea hostname (see Repository Context Detection), finds the matching login entry, and extracts the token for all subsequent API calls.
Tea is used only for credential discovery — no commands are dispatched through the tea subprocess.

### Command Surface

#### Dashboard

`gitea-axi` (no args): a two-tier home view showing live repository state, preceded by the `bin:` + `description:` header from `axi-sdk-js`, followed by next-step suggestions (see ADR 0012).

The short tier (no flags — also what the SessionStart hook runs) matches gh-axi's home shape:
up to 3 open issues (`number`, `title`, `state`, `author`) and up to 3 open PRs (`number`, `title`, `author`, `review`), fetched in parallel with `limit=3`.
The `review` field is computed client-side via the same parallel review fetch as `pr list` (see ADR 0006) — at most 3 extra HTTP calls.
The short tier's `help:` block always includes a hint pointing at `--full`.

The full tier (`gitea-axi --full`): open PRs as a TOON table and open issue counts grouped by label (a label→count record).
Full-tier PR table default fields: `number`, `title`, `author` (plucked from `user.login`), `labels` (joined label names), `review` (same client-side computation).
The full-tier PR table is capped at 20 rows with a standard count line (`count: 20 of T total`).
Full-tier issue aggregation fetches all pages of open issues up to a hard cap of 1000 (page size 50, 20 pages max); if the cap is hit, label counts are suffixed with `+`.
`--full` here selects the full tier — an intentional overload of the flag that elsewhere suppresses truncation.

Output blocks (both tiers): a `repo: owner/name` line, then `prs:` and `issues:`.
Empty states are explicit and match gh-axi's home: `prs: 0 open` / `issues: 0 open` (raw strings; list commands keep their `<noun>[0]: (none)` convention).
Issue fetching passes `type=issues` so PRs never pollute the issue block (see Issue/PR Type Guard).
Outside a recognizable Gitea repo the dashboard errors with `REPO_NOT_FOUND` (help: use `-R` + `--login`) — login selection requires a hostname.
This holds even when invoked by the SessionStart hook; error noise in non-Gitea sessions is an accepted consequence (see ADR 0009).

#### Issue Commands

**`issue list [flags]`**
`--state <open|closed|all>` (default open);
`--label <name>` (API-supported — Gitea issue list accepts comma-separated label names);
`--assignee <login>` (API-supported — maps to `assigned_by` param);
`--author <login>` (API-supported — maps to `created_by` param);
`--milestone <name>` (API-supported — maps to `milestones` param);
`--sort <created|updated|comments>` (client-side — Gitea issue list has no sort param; always descending, matching gh-axi);
`--limit <n>` (default 30);
`--fields <a,b,c>`.
`--search` is explicitly forbidden (VALIDATION_ERROR).
Always passes `type=issues` — Gitea's issue endpoints also serve PRs, which must never appear in issue lists (see Issue/PR Type Guard).
Client-side `--sort` reorders without changing membership, so the standard `count: N of T total` line is kept (see ADR 0005); full pagination still precedes sorting.
Default output fields (matching gh-axi): `number`, `title`, `state` (lowercased), `author` (plucked from `user.login`), `created` (relative time).
Extra fields via `--fields`: `body` (raw), `closedAt` (relative time, as `closed_at`), `labels` (joined names), `milestone` (title), `updatedAt` (relative time, as `updated_at`), `url`.
No `type` field in output — Gitea has no issue types.

**`issue view <n> [flags]`**
`--comments` (expand full comments — renders all comments with no count cap, each body truncated at 800 chars with cleanBody applied);
`--full` (suppress all truncation in the output — issue body and comment bodies alike).
Default output fields (matching gh-axi, minus `type`): `number`, `title`, `state`, `author`, `created`, `body` (truncated at 500), plus `comment_count`.
Type guard: if `<n>` is a pull request, fails with `VALIDATION_ERROR` ("issue #N is a pull request") and a `pr view <n>` help line (see Issue/PR Type Guard).
No `type` field in output (Gitea has no issue types).
No sub-issue augmentation (Gitea does not model issue hierarchies; use `issue blocks` and `issue blocked-by` for dependency relationships).

**`issue create [flags]`**
`--title <text>` (required);
`--body <text>` or `--body-file <path>`;
`--assignee <login>`;
`--label <name>` (repeatable; resolved to label ID via `GET /labels`, case-insensitive — `VALIDATION_ERROR` if not found);
`--milestone <name>` (resolved to milestone ID via `GET /milestones?name=<name>` — `VALIDATION_ERROR` if not found).
`--project` is excluded (Gitea has no projects REST API).
`--type` is excluded (Gitea has no issue types).
Output schema: `issue: { number, title, state, url }` (where `url` = `html_url`).
Extra fields available via `--fields`: `labels`, `assignees`, `milestone`, `body`.

**`issue edit <n> [flags]`**
`--title`;
`--body <text>` or `--body-file <path>`;
`--add-label <name>`;
`--remove-label <name>`;
`--add-assignee <login>`;
`--remove-assignee <login>`;
`--milestone <name>` (resolved to milestone ID via `GET /milestones?name=<name>` — `VALIDATION_ERROR` if not found).
Label mutations use Gitea's dedicated additive/removal label endpoints (idempotent).
`--add-label` passes the name directly via `POST /issues/{index}/labels` (Gitea accepts names here — no lookup needed).
`--remove-label` requires an ID: resolved via case-insensitive label lookup; `VALIDATION_ERROR` if the label name does not exist in the repo; if the label exists but is not applied to this issue, Gitea's 404 on `DELETE /labels/{id}` is treated as silent success.
Assignee mutations use fetch-then-patch: the current assignee list is read first, the addition or removal applied in-process, then the full resulting list is sent in a single PATCH (see ADR 0007).

**`issue close <n> [flags]`**
`--comment <text>`.
Closing sets `state: "closed"` via PATCH on the issue.
`--reason` is excluded (Gitea has no `state_reason` concept).
When `--comment` is provided, two API calls are made: PATCH to close, then POST to create the comment.
If the PATCH succeeds but the POST fails, the error is surfaced — the issue remains closed but the failure is reported rather than silently swallowed.
Idempotent: returns early with `message: "Already closed"` if already closed.

**`issue reopen <n>`**
Sets `state: "open"` via PATCH.
Idempotent: returns early with `message: "Already open"` if already open.

**`issue comment <n> [flags]`**
`--body <text>` or `--body-file <path>` (required).
Gitea's `POST /issues/{index}/comments` returns the created `Comment` object directly.
Output block: `comment: { number, author, created, body }` (body truncated at 800 chars).
`number` is the issue number the comment was posted to; the comment's own id is not output (nothing in the command surface consumes comment ids).

**`issue delete <n>`**
Hard-deletes the issue via `DELETE /issues/{index}` (requires admin or owner permissions).
Not idempotent: a nonexistent issue errors with `ISSUE_NOT_FOUND` rather than reporting success (see ADR 0010).
Output: `issue: { number, status: "deleted" }`.

**`issue pin <n>`**
`POST /issues/{index}/pin`.
Idempotent: returns early with `message: "Already pinned"` if already pinned.
Output: `issue: { number, state, pinned }`.

**`issue unpin <n>`**
`DELETE /issues/{index}/pin`.
Idempotent: returns early with `message: "Already unpinned"` if already unpinned.
Output: `issue: { number, state, pinned }`.

**`issue blocks <list|add|remove>` (Gitea-specific)**
Manages the set of issues that this issue blocks (downstream dependents that cannot proceed until this issue is resolved).
`issue blocks list <n>` — lists issues blocked by `<n>`; output block `blocked_issues`.
`issue blocks add <n> <target>` — makes `<n>` block `<target>`; output `blocks: { issue: n, blocks: target }`.
`issue blocks remove <n> <target>` — removes the blocking relationship.
Idempotent: `add` of an existing relationship returns `already: true` (fetch-first check against the current list); `remove` of a nonexistent relationship is silent success; self-reference and cycle errors still surface as `VALIDATION_ERROR` via the 422 mapping.
Gitea API: `GET/POST/DELETE /repos/{owner}/{repo}/issues/{index}/blocks`.
No gh-axi equivalent.

**`issue blocked-by <list|add|remove>` (Gitea-specific)**
Manages the set of issues that block this issue (upstream blockers that must be resolved before this issue can proceed).
`issue blocked-by list <n>` — lists issues that block `<n>`; output block `blocking_issues`.
`issue blocked-by add <n> <blocker>` — makes `<n>` depend on `<blocker>`; output `blocked_by: { issue: n, blocked_by: blocker }`.
`issue blocked-by remove <n> <blocker>` — removes the dependency.
Same idempotency rules as `issue blocks`.
Gitea API: `GET/POST/DELETE /repos/{owner}/{repo}/issues/{index}/dependencies`.
No gh-axi equivalent.

#### Excluded Issue Commands

`issue lock` / `issue unlock` — excluded: Gitea exposes `is_locked` as a readable field but has no lock/unlock API endpoint.
`issue transfer` — excluded: no Gitea equivalent.
`issue subissue` — excluded: GitHub-specific hierarchy model; Gitea uses blocking/dependency relationships instead (see `issue blocks` and `issue blocked-by`).

#### PR Commands

**`pr list [flags]`**
`--state <open|closed|all>` (default open);
`--label <name>` (requires name→ID lookup — Gitea PR list takes `labels: number[]`; see label name lookup in CONTEXT.md);
`--label-id <id>` (Gitea-specific shortcut — bypasses the name→ID lookup and passes the ID directly);
`--assignee <login>` (client-side filter — Gitea PR list has no assignee param);
`--author <login>` (API-supported — maps to `poster` param);
`--base <branch>` (client-side filter — no API param);
`--head <branch>` (client-side filter — no API param);
`--draft` (client-side filter — no API param);
`--sort <oldest|recentupdate|leastupdate|mostcomment|leastcomment|priority>` (Gitea-specific extension — maps directly to the API `sort` param);
`--limit <n>` (default 30);
`--fields <a,b,c>`.
`--search` is explicitly forbidden (VALIDATION_ERROR).
Default output fields (matching gh-axi): `number`, `title`, `state` (lowercased), `author` (plucked from `user.login`), `draft` (bool→yes/no), `review` (`reviewDecision` mapped: APPROVED→approved, CHANGES_REQUESTED→changes_requested, REVIEW_REQUIRED→required).
Extra fields via `--fields`: `body` (raw), `createdAt` (relative time, as `created`), `labels` (joined names), `milestone` (title), `mergedAt` (relative time, as `merged_at`), `url`.
`reviewDecision` is computed client-side by fetching reviews for each PR in parallel (one extra HTTP call per PR; see ADR 0006).
When any client-side filter is active, the count line shows `count: N of T total` with `T` computed from the in-memory filtered result set (see ADR 0005).

**`pr view <n> [flags]`**
`--comments` (renders all comments with no count cap, each body truncated at 800 chars with cleanBody applied);
`--reviews`;
`--full` (suppress all truncation in the output — PR body and comment bodies alike).
Default output fields (matching gh-axi): `number`, `title`, `state`, `author`, `draft`, `merged`, `checks`, `body` (truncated at 500), plus `comment_count` and `review_count`.
The `checks` field is populated from Gitea commit statuses via `GET /commits/{sha}/status` using the PR head SHA.
It renders as `"N passed, N failed[, N skipped][, N pending], N total"`, or `"0 passed, 0 failed — this PR has no CI checks configured"` when no statuses exist.
Commit status states map to gh-axi's four-value classification: `success`→`pass`; `failure`/`error`/`warning`→`fail` (matching Gitea's own combine logic, which treats `warning` as failure); `skipped`→`skip`; `pending`→`pending`.
Older Gitea instances never emit `skipped`, so the `skip` bucket is simply absent there.
`pr view` always makes three API calls: the PR fetch and `GET /pulls/{index}/reviews` are issued in parallel, then the combined-status fetch runs once the head SHA is known — so `review_count` and `checks` are always in the default output without requiring `--reviews`.
When `--reviews` is passed, additionally fetches per-review inline comments (`GET /pulls/{index}/reviews/{id}/comments` for each review).
Gitea-specific fields exposed on review objects when `--reviews` is passed: `official` (whether the review counts toward required approvals) and `stale` (whether the PR head has moved since review submission).

**`pr create [flags]`**
`--title <text>` (required);
`--body <text>` or `--body-file <path>`;
`--base <branch>`;
`--head <branch>`;
`--assignee <login>`;
`--reviewer <login>`;
`--label <name>` (repeatable; resolved to label ID via `GET /labels`, case-insensitive — `VALIDATION_ERROR` if not found);
`--milestone <name>` (resolved to milestone ID via `GET /milestones?name=<name>` — `VALIDATION_ERROR` if not found).
`--draft` is excluded (Gitea cannot create draft PRs via API).
`--project` is excluded (Gitea has no projects REST API).
When `--head` is not specified, defaults to the current local branch (via `git rev-parse --abbrev-ref HEAD`).
When `--base` is not specified, the repository's default branch is used (fetched via `GET /repos/{owner}/{repo}`).
Idempotent: before creating, checks `GET /pulls/{base}/{head}` for an existing open PR for the same branch pair.
If found, returns `pull_request: { number, url, already: true }` without creating a duplicate.
Output on success: `created: { number, url }` — completing gh-axi's action-block/entity-block pattern (action-named block when the mutation ran, entity-named block when it was a no-op).

**`pr edit <n> [flags]`**
`--title`;
`--body <text>` or `--body-file <path>`;
`--add-label <name>`;
`--remove-label <name>`;
`--add-assignee <login>`;
`--remove-assignee <login>`;
`--add-reviewer <login>`;
`--remove-reviewer <login>`;
`--milestone <name>` (resolved to milestone ID via `GET /milestones?name=<name>` — `VALIDATION_ERROR` if not found);
`--base <branch>`.
Assignee and reviewer mutations use fetch-then-patch (see ADR 0007).
Output: `edited: { number, status: "ok" }`.

**`pr close <n> [flags]`**
`--comment <text>`.
Idempotent: returns `pull_request: { number, state, already: true }` if already closed or merged.
Output on success: `closed: { number, status: "ok" }`.

**`pr merge <n> [flags]`**
`--method <merge|squash|rebase|rebase-merge|fast-forward-only|manually-merged>`;
`--merge`, `--squash`, `--rebase` (shorthands for the three common methods);
`--auto`;
`--delete-branch`;
`--body <text>` or `--body-file <path>`;
`--subject <text>`;
`--merge-commit-id <sha>` (required when `--method manually-merged`; VALIDATION_ERROR if omitted; VALIDATION_ERROR if provided with any other method).
Gitea-specific methods not in gh-axi: `rebase-merge` (rebase + explicit merge commit), `fast-forward-only`, `manually-merged` (records an out-of-band merge without actually merging).
Idempotent: if already merged, returns `pull_request: { number, state: "merged", merged_by, merged_at }` without calling the API.
Output on success: `merged: { number, status: "ok", method }`.

**`pr review <n> [flags]`**
`--approve`;
`--request-changes`;
`--comment`;
`--body <text>` or `--body-file <path>`.
Exactly one of the three action flags is required; zero or multiple → `VALIDATION_ERROR` before any API call (mirroring the `pr merge` shorthand-conflict rule).
Body requirements are not pre-validated locally: if Gitea rejects a body-less review event, its 422 surfaces as `VALIDATION_ERROR` with the server's message.
Output: `review: { number, action }`.

**`pr checks <n>`**
Fetches combined commit status for the PR head SHA via `GET /commits/{sha}/status`.
Output matches gh-axi: a `summary` line (`N passed, N failed[, N skipped][, N pending], N total`) followed by a `checks` list of `{ name, conclusion }`.
Conclusions: `pass`, `fail`, `skip`, or `pending`, using the same state mapping as `pr view` (`skipped`→`skip`; `warning`→`fail`).
When no statuses are configured: `checks: "0 passed, 0 failed — this PR has no CI checks configured"`.

**`pr diff <n> [flags]`**
`--full`.
Fetches raw diff from `GET /pulls/{index}.diff`.
Truncation limit: 4000 chars.
Output: `pr_diff: { number, diff[, truncated, original_length] }`.

**`pr checkout <n>`**
Fetches the PR head branch name from `GET /pulls/{index}` (`head.ref` field), then runs in the current working directory:
1. `git fetch origin pull/<n>/head:<branch>`
2. `git checkout <branch>`
Fetching `refs/pull/{index}/head` from the base repo works uniformly for same-repo and fork PRs — the head branch itself may live in a fork that is not a configured remote (see ADR 0011).
Git subprocess failures (dirty worktree, network) map to `GIT_ERROR`, carrying git's first stderr line and a remediation help line.
Output: `checkout: { number, branch, status: "ok" }`.

**`pr reopen <n>`**
Idempotent: returns `pull_request: { number, state: "open", already: true }` if already open.
Output on success: `reopened: { number, status: "ok" }`.

**`pr comment <n> [flags]`**
`--body <text>` or `--body-file <path>` (required).
PRs share the issue comment endpoint in Gitea (`POST /issues/{index}/comments`), which returns the created `Comment` object directly.
Output block: `comment: { number, author, created, body }` (body truncated at 800 chars).
`number` is the PR number the comment was posted to; the comment's own id is not output.
This diverges from gh-axi's `commented: { number, status: "ok" }` — returning the created comment eliminates the need for a follow-up view call (AXI Principle 4; see ADR 0008).

**`pr update-branch <n> [flags]`**
`--style <merge|rebase>` (Gitea-specific; default `merge`).
Merges the base branch into the PR head branch via `POST /pulls/{index}/update?style=<style>`.
Output: `updated: { number, status: "ok" }`.

#### Excluded PR Commands

`pr ready` — excluded: Gitea has no API to convert a draft PR to ready for review.
`pr revert` — excluded: Gitea has no revert PR endpoint.

#### Label Commands

**`label list [flags]`**
`--limit <n>` (default 500).
Output: count line followed by `labels: [ { name } ]`.

**`label create [flags]`**
`--name <text>` (required);
`--color <hex>` (required, without `#`).
The `#` prefix is automatically prepended before calling the Gitea API (which requires it in `CreateLabelOption.color`).
`--description <text>`.
Idempotent: checks for an existing label with the same name (case-insensitive) before creating.
If found: `create: already_exists`, `label: <existing-name>`.
Output on success: `created: ok`, `label: <name>`.

**`label edit <name> [flags]`**
`--name <new-name>`;
`--color <hex>`;
`--description <text>`.
`<name>` is resolved via the standard case-insensitive label lookup; `VALIDATION_ERROR` if not found.
Output: `edit: ok`, `label: <new-name-or-original-name>`.

**`label delete <name>`**
`<name>` is resolved via the standard case-insensitive label lookup.
Not idempotent: a nonexistent label errors with `VALIDATION_ERROR` rather than reporting success (see ADR 0010).
Output: `delete: ok`, `label: <name>`.

#### Setup Command

**`setup`**
Installs the bundled Agent Skill markdown into `~/.claude/skills/` (see ADR 0009).
This is gitea-axi's primary fulfillment of AXI Principle 7 (Ambient context): an explicit setup command, matching gh-axi's `setup`.
Idempotent: re-running reports already-installed/updated rather than failing.
Output: `setup: { skill, path, status: <installed|updated|unchanged> }`.

**`setup hooks`**
Opt-in: installs a SessionStart hook via axi-sdk-js's `installSessionStartHooks()` into Claude Code (`~/.claude/settings.json`), Codex (`~/.codex/hooks.json` plus `config.toml`), and OpenCode (ambient plugin) — see ADR 0009.
The hook runs the bare `gitea-axi` binary (the short dashboard tier) in the session's working directory at session start and injects its output as ambient context.
Idempotent: managed entries are updated in place by the SDK.
Output mirrors gh-axi: `hooks: { status: installed, integrations: Claude Code, Codex, OpenCode }`, with a help line to restart the agent session.

#### Shadowed Built-in Commands

`update` — axi-sdk-js ships a built-in self-update command (checks npmjs.org and updates the install) with its own `UPDATE_ERROR` code; gitea-axi shadows it (see ADR 0013).
`gitea-axi update` fails with `VALIDATION_ERROR` and a help line: `` Run `npm install -g gitea-axi@latest` to update ``.
This keeps the command surface and the ten-code error list exactly as specified here.

### Name-to-ID Resolution

Some Gitea API endpoints require integer IDs where gitea-axi accepts human-readable names.

**Milestone names** (`--milestone <name>` on `issue create`, `issue edit`, `pr create`, `pr edit`):
Resolved via `GET /repos/{owner}/{repo}/milestones?name=<name>`.
`VALIDATION_ERROR` if no milestone with that name exists.

**Label names for `pr list --label`**:
Resolved via `GET /repos/{owner}/{repo}/labels`, matched case-insensitively.
`VALIDATION_ERROR` if not found.
`--label-id <id>` bypasses this lookup.

**Label names for `issue create` and `pr create` (`--label <name>`)**:
Same case-insensitive label lookup.
`VALIDATION_ERROR` if not found.

**Label names for `issue edit` / `pr edit` `--add-label`**:
Not resolved — the label name is passed directly in the POST body; Gitea's label endpoint accepts names.

**Label names for `issue edit` / `pr edit` `--remove-label`**:
Resolved via case-insensitive label lookup.
`VALIDATION_ERROR` if the label name does not exist in the repo.
If the label exists but is not applied to the issue/PR, Gitea's 404 on `DELETE /labels/{id}` is treated as silent success.

**Label names for `label edit <name>` / `label delete <name>`**:
Resolved via the same case-insensitive label lookup.
`VALIDATION_ERROR` if not found.

### Client-Side Filtering Policy

When a filter flag has no corresponding Gitea API query parameter, gitea-axi paginates all results (`limit=50` per page until exhausted) and filters in-process (see ADR 0005).
Known client-side filters for the current surface: `pr list --assignee`, `pr list --base`, `pr list --head`, `pr list --draft`.
When any client-side filter is active, the count line shows `count: N of T total`, where `T` is the true filtered total computed from the in-memory result set; the `X-Total-Count` header (which reflects the unfiltered total) is ignored as misleading.
Client-side *sort* (`issue list --sort`) is not a filter: it reorders without changing membership, so `T` comes from the `X-Total-Count` header as usual; full pagination still precedes sorting.

### Issue/PR Type Guard

Gitea's issue endpoints also serve pull requests (`Issue.pull_request` is non-null for PRs).
Every issues-list call passes `type=issues` — `issue list`, the dashboard's issue aggregation, and any client-side-filter pagination.
Issue commands invoked with a PR number fail with `VALIDATION_ERROR` ("issue #N is a pull request") and a `pr view <n>` help line, detected via the fetched object's `pull_request` field.
Exception: `issue comment` stays permissive — PRs genuinely share the comment endpoint.

### reviewDecision Computation

Gitea has no aggregated `reviewDecision` field on the PR object.
gitea-axi computes it client-side from the reviews list (see ADR 0006).
Logic: `APPROVED` if at least one review has `official=true`, `stale=false`, `dismissed=false` and no non-dismissed `REQUEST_CHANGES` exists; `CHANGES_REQUESTED` if any non-dismissed `REQUEST_CHANGES` exists; `REVIEW_REQUIRED` otherwise.
On `pr list`, reviews for each PR are fetched in parallel (one extra HTTP call per PR in the list).

### Context Override Flags

gitea-axi accepts two top-level context override flags and two matching environment variables, mirroring gh-axi's design (`GH_REPO`):

- `-R` / `--repo <OWNER/NAME>` — overrides the repository detected from the git remote; env equivalent `GITEA_AXI_REPO`.
- `--login <name>` — selects a specific tea login profile, overriding the one matched from the git remote's hostname; env equivalent `GITEA_AXI_LOGIN`.

Resolution priority: flag > environment variable > auto-detection (git remote / hostname match).
Both flags are accepted anywhere on the command line, before or after the command — more permissive than gh-axi, which rejects them before the command; next-step suggestions always render them after the command.
These overrides are injected into next-step suggestions only when the context came from a flag or environment variable, not when it was auto-detected from the git remote (because the agent's next call will be in the same working directory and will auto-detect the same context).

### Output — The 10 AXI Principles

**Principle 1 — TOON output.**
All structured output uses the `@toon-format/toon` `encode()` function, wrapped in `renderList()` and `renderDetail()` helpers that handle the list/detail shape distinction.

**Principle 2 — Minimal default schemas.**
Each command exposes a small default field set (5–6 fields per list row), enumerated per command in the Command Surface section.
This is a deliberate, documented departure from the canonical 3–4-field guidance: each extra field (`state`, `created`, `draft`, `review`) answers a routine triage question that would otherwise cost a follow-up call.
Additional fields are opt-in via `--fields`.
Field extraction uses a `FieldDef` type system with typed extractors: nested pluck, array join, enum map, bool-to-text, and relative time formatting — matching gh-axi's internal architecture.

**Principle 3 — Content truncation.**
Body text is truncated at **500 characters** in all contexts (list and detail alike), matching gh-axi.
Comment bodies truncate at 800 characters wherever they appear (comment-post output and `--comments` view blocks), with cleanBody applied.
Diff content is truncated at 4000 characters.
When body truncation occurs, a hint is appended inline: `"... (truncated, N chars total - use --full to see complete body)"`.
When diff truncation occurs, `truncated: true` and `original_length: N` are added as separate fields, and a next-step suggestion to use `--full` is prepended.
`--full` on `issue view` and `pr view` suppresses all truncation in the command's output (entity body and comment bodies alike); `--full` on `pr diff` suppresses diff truncation.
Before truncation, a `cleanBody` step is applied **only when the raw body exceeds the truncation limit**.
`cleanBody` normalizes Gitea issue/PR URLs using the detected hostname (`https://<host>/<owner>/<repo>/issues/N` → `Issue#N`; `.../pulls/N` → `PR#N`), strips markdown image embeds, removes long URLs in markdown links and standalone text, and collapses email-style quoted blocks — matching gh-axi's transforms plus Gitea-specific URL normalization.
If cleaning brings the body within the limit, the cleaned body is returned with an appended note; if it still exceeds the limit, the cleaned body is truncated.

**Principle 4 — Pre-computed aggregates.**
List output leads with a `formatCountLine()`: `"count: N of T total"`, with `T` from the `X-Total-Count` response header, or computed from the in-memory filtered set when a client-side filter is active; `"count: N (showing first N)"` when at the request limit and no total is available.
The bare `count: N` form does not exist — the total is always reported (canonical Principle 4).
Detail output for issues includes `comment_count`; for PRs includes `review_count` and `comment_count`.
The review decision (`review` field) is a default on `pr list` and the dashboard PR table, computed client-side from parallel review fetches.
The full-tier dashboard's issue-by-label counts are computed by fetching all pages of open issues and aggregating in-process.
Both `issue comment` and `pr comment` return the created comment object directly from the POST response, eliminating the need for a follow-up view call.

**Principle 5 — Definitive empty states.**
When a list command returns no results it emits `<noun>[0]: (none)` followed by a relevant next-step suggestion.
The dashboard's empty states are `prs: 0 open` / `issues: 0 open` (raw strings, matching gh-axi's home view).
Empty output is never silent.

**Principle 6 — Structured errors, exit codes, idempotent mutations, no prompts.**
Errors are represented as a typed `AxiError` with one of ten named codes: `REPO_NOT_FOUND`, `ISSUE_NOT_FOUND`, `PR_NOT_FOUND`, `AUTH_REQUIRED`, `FORBIDDEN`, `RATE_LIMITED`, `TEA_NOT_INSTALLED`, `VALIDATION_ERROR`, `GIT_ERROR`, `UNKNOWN`.
The `ISSUE_NOT_FOUND`/`PR_NOT_FOUND` split (vs gh-axi's single `NOT_FOUND`) is a deliberate divergence enabled by path-based 404 classification.
API error responses are classified by HTTP status code and calling context:

| HTTP status | Context | Error code |
|---|---|---|
| 401 | any | `AUTH_REQUIRED` |
| 403 | any | `FORBIDDEN` |
| 404 | called on `/repos/{owner}/{repo}` itself | `REPO_NOT_FOUND` |
| 404 | called on `/repos/.../issues/{index}` | `ISSUE_NOT_FOUND` |
| 404 | called on `/repos/.../pulls/{index}` | `PR_NOT_FOUND` |
| 404 | other paths | `UNKNOWN` |
| 422 | any | `VALIDATION_ERROR` (body message surfaced) |
| 429 | any | `RATE_LIMITED` (help: wait and retry, or reduce `--limit`) |
| other | any | `UNKNOWN` |

`TEA_NOT_INSTALLED` is emitted if the tea binary is not found during credential discovery.
`AUTH_REQUIRED` is also emitted when tea is installed but no login matches the detected hostname (help: `` Run `tea login add --url <host>` ``, or pass `--login <name>`).
A `--login` value naming a nonexistent profile is `VALIDATION_ERROR`, listing the available profile names.
`GIT_ERROR` classifies non-zero git subprocess exits (currently only `pr checkout`), carrying git's first stderr line.
Error output is TOON-encoded to stdout (not stderr): `error: <message>`, `code: <CODE>`, and optionally `help[N]:` with suggestion lines.
The suggestions field is named `help`, not `hint`.
Exit codes: 0 success, 1 error, 2 for `VALIDATION_ERROR` — covering unknown flags, missing required inputs, and server-side 422 rejections alike (the `axi-sdk-js` `exitCodeForError` mapping; see ADR 0004).
This deliberately broadens the canonical "exit 2 for unknown flags" wording: exit 2 uniformly means "the input was invalid — fix the call and retry".

Mutations are idempotent, and no command ever prompts:
`pr create` checks for an existing open PR before creating; if one exists, returns its details with `already: true` rather than creating a duplicate.
`issue edit --add-label` / `--remove-label` uses Gitea's dedicated additive label endpoints, which are idempotent.
`issue close`, `issue reopen`, `pr close`, `pr reopen`, `pr merge`, `issue pin`, `issue unpin`, `issue blocks add/remove`, `issue blocked-by add/remove`, and `setup` all check current state before mutating and return early if already in the target state.
Hard deletes (`issue delete`, `label delete`) deliberately refuse missing targets instead of reporting idempotent success (see ADR 0010).
All required inputs are flags — missing ones cause an immediate `error:` exit.

**Principle 7 — Ambient context.**
Fulfilled primarily by the `setup` command, which installs the bundled Agent Skill into `~/.claude/skills/` (see ADR 0009).
The skill surfaces gitea-axi to the agent at session start whenever it is relevant, without a per-session hook cost.
The canonical principle's primary mechanism — SessionStart hooks that inject the dashboard as initial context — is offered as the opt-in `setup hooks`, not the default.
There is no postinstall script — skill and hook installation are always explicit user actions, matching the canonical principle wording ("from an explicit setup command") and gh-axi's own `setup` command.

**Principle 8 — Content first.**
Running `gitea-axi` with no arguments shows live repository state, not a help screen, preceded by the SDK's `bin:` + `description:` header (executable path and one-sentence description, per the canonical principle).
The short tier makes two parallel API calls — 3 open issues, 3 open PRs — plus up to 3 parallel review fetches.
The full tier (`--full`) additionally aggregates open issue counts by label: open issues are paginated with `limit=50` and `type=issues`, up to a hard cap of 1000 issues (20 pages max); if the cap is hit, label counts are suffixed with `+`.
Each issue contributes to all of its labels; unlabeled issues appear as a separate `unlabeled` row only when non-zero.

**Principle 9 — Contextual next-step suggestions.**
Every command appends semi-dynamic suggestions to its output, rendered as a `help[N]:` block — the same block name used for error suggestions, matching gh-axi and the canonical principle text.
Runtime values are hybrid: list output keeps placeholders (`` `gitea-axi issue view <number>` ``) since the agent must choose which result it cares about; single-entity output fills the actual id (`` `gitea-axi issue view 42` ``) since it is unambiguous — matching the canonical "leave runtime values parameterized" guidance while carrying forward known ids.
Every command emits at least one suggestion; there are no empty `help:` blocks (a departure from gh-axi, which omits suggestions on `pr view` and emits empty blocks on `pr checkout`).
Every suggestion auto-includes `-R`/`--repo` and `--login` flags when the context was not auto-detected from the git remote — matching gh-axi's suggestion normalization approach.

**Principle 10 — Consistent `--help`.**
Every subcommand responds to `--help` with a concise flag reference.
Unknown flags exit with code 2.
No subcommand ever prompts interactively.

### Repository Context Detection

Repo owner, name, and hostname are detected from the git `origin` remote URL of the current directory.
Both SSH (`git@host:owner/repo.git`) and HTTPS (`https://host/owner/repo.git`) remote formats are supported.
If no recognizable Gitea remote URL is found on `origin`, gitea-axi exits with `REPO_NOT_FOUND` and a hint to configure the remote.
The detected hostname is used to select the matching tea login profile for auth.

### Distribution

Published to npm as `gitea-axi` (unscoped).
Binary name: `gitea-axi`.
The Agent Skill markdown file is bundled inside the npm package.
There is no postinstall script: `npm install -g gitea-axi` delivers the CLI binary, and a one-time explicit `gitea-axi setup` installs the skill into `~/.claude/skills/` (see ADR 0009).
The dashboard suggestion table hints at `setup` so the skill install is discoverable.

## Testing Decisions

Good tests exercise the actual command-line interface (argv in, stdout/exit-code/stderr out) — the one seam every caller depends on.
They do not test internal functions in isolation, and they do not mock individual API calls in a way that only proves gitea-axi issued the right HTTP request.
Instead, tests verify that gitea-axi correctly reshapes real API responses into correct TOON, correct error lines, and correct exit codes.

**Test seam:** Three environment variables together activate test mode:
- `GITEA_AXI_API_URL` — overrides the API base URL to point at the fixture server; also signals test mode, suppressing both the git remote subprocess and the tea credential subprocess.
- `GITEA_AXI_TOKEN` — supplies the auth token directly, bypassing `tea login list`.
- `GITEA_AXI_REPO` — supplies the repository context as `OWNER/NAME`, equivalent to `-R`; required in test mode since git remote detection is suppressed.

`GITEA_AXI_REPO` and `GITEA_AXI_LOGIN` are general context overrides (see Context Override Flags), not test-mode-specific; test mode merely relies on them.

In tests, `GITEA_AXI_API_URL` points to a local HTTP fixture server that maps incoming request paths and methods to pre-recorded Gitea API JSON response files stored in `fixtures/`.
This means tests exercise the full reshaping pipeline — JSON parse, field extraction, TOON encoding, truncation, suggestion generation, error classification — without a live Gitea instance.

**Two-tier test strategy:**
- Local / unit tier: the fixture server runs fast with no external dependencies.
  Used for all command-level assertions.
- CI integration tier: a live disposable Gitea instance serves real API responses end-to-end, verifying that fixture recordings remain accurate and that the full HTTP pipeline works correctly.

**Test runner:** Vitest.

## Out of Scope

- Any workflow-specific commands or hardcoded label/state semantics.
- Inline per-line PR review comments (a possible future addition; the primitive here is a plain PR comment).
- Multi-instance orchestration beyond what `tea`'s own login profiles already provide.
- A repo-level config file for dashboard customization (deferred post-MVP).
- A `dot` or any other host CLI's subcommand wrapping this tool — it is a standalone, independently distributed tool.
- Gitea Projects (kanban boards) — no REST API exists as of gitea-js v1.23.

## Further Notes

- AXI ("Agent eXperience Interface"): https://axi.md/ and https://github.com/kunchenguid/axi.
  Its reference implementation, `gh-axi` (https://github.com/kunchenguid/gh-axi), wraps GitHub's `gh` CLI.
  The canonical principle text is authoritative for gitea-axi; gh-axi is a non-binding shape reference.
  gitea-axi adopts gh-axi's `FieldDef` type system, `renderList()`/`renderDetail()` output helpers, typed `AxiError` classification, and suggestion normalization, and documents each deliberate departure in place.
- TOON format spec: https://toonformat.dev/.
  The official TypeScript library is `@toon-format/toon`; no Go library exists, which was a decisive factor in the TypeScript language choice.
- `gitea-js` is the official TypeScript client for the Gitea API, generated from Gitea's OpenAPI spec.
  It is the sole HTTP layer; no raw `fetch` calls are made outside of it.
- Tea's login store (`~/.config/tea/config.yml`) is read indirectly via `tea login list --output json`.
  gitea-axi does not parse the YAML config file directly, to avoid coupling to tea's internal storage format.
- Tea was evaluated as the primary implementation strategy (subprocess wrapping with `--output json`) and rejected — see ADR 0002.
  Tea improvements relevant to the gaps found (JSON output on create commands, non-interactive comment expansion) may be contributed upstream as separate PRs.
- The Gitea Go SDK (`gitea.dev/sdk`) was evaluated as an alternative to `gitea-js`.
  It was rejected because it requires Go compilation, adding cross-compilation complexity for npm distribution.
- `gitea-axi` is unclaimed on npm and GitHub as of 2026-07-09.
- Developed against the operator's personal Gitea instance at `git.alexion.dev`; push-mirrored to GitHub for npm publishing and public discoverability.