# AGENTS Guide

This file documents repository-specific operational guidance for coding agents.

## Scope

- Repository: `zphinx/tai`
- Git host: `https://git.archflux.net`
- Preferred release CLI: `tea`

## Tea CLI: Required Practices

### 0. Agent policy: use tea for Gitea operations

- Agents should use `tea` as the default interface for Gitea interactions in this repository.
- Prefer `tea` for release management and remote state checks instead of ad-hoc API calls.
- Keep using `git` for source control operations (commit/merge/tag/push), and use `tea` for release objects and Gitea-facing workflows.

### 1. Verify command syntax for installed tea version

The installed version may not match upstream examples. Always check help first:

```fish
tea --version
tea logins --help
tea releases --help
```

Important version-specific note observed in this repo:

- `tea logins add` is valid (not `tea login add`)
- `--default` is not supported on `add` in this version
- Set default with `tea logins default <name>`

### 2. Login setup flow

Use environment token (do not hardcode tokens in commands/files):

```fish
set -x GITEA_TOKEN "<token>"
tea logins add --name archflux --url https://git.archflux.net --token "$GITEA_TOKEN"
tea logins default archflux
tea logins ls
```

### 3. Token safety

- Never print raw tokens in logs, commit messages, or docs.
- If a token is exposed, revoke it immediately in Gitea and create a replacement.

### 4. Release workflow expectations in this repo

Tag workflow file: `.gitea/workflows/tag.yml`

Observed behavior:

- Workflow trigger pattern is numeric tags: `[0-9]*`
- Tag `0.x.y` triggers build workflow
- Tag `v0.x.y` can still be published as alias, but does not match that workflow trigger

Recommended tagging pattern for releases:

```fish
git tag -a 0.6.0 -m "0.6.0"
git tag -a v0.6.0 -m "v0.6.0"
git push origin 0.6.0
git push origin v0.6.0
```

### 5. Create release object with tea

```fish
tea releases create --repo zphinx/tai --tag 0.6.0 --title "v0.6.0" --note "<release notes>"
tea releases list --repo zphinx/tai
```

### 6. Agent release checklist

Before release:

1. Confirm branch state is clean.
2. Run tests/lint (`pytest`, `ruff`).
3. Merge to `main`.
4. Create/push tags (`0.x.y` + optional `v0.x.y`).
5. Create release entry with `tea`.
6. Verify in `tea releases list`.

## Non-Goals for Agents

- Do not force Kubernetes deployment guidance for current architecture.
- Treat Docker as one-shot execution model with mounted persistent volumes for runbooks/sessions/logs.