docs: require tea for agent gitea workflows

AGENTS.md

@@ -0,0 +1,91 @@
+# 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.