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:

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>

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

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:

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

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:

Confirm branch state is clean.
Run tests/lint (pytest, ruff).
Merge to main.
Create/push tags (0.x.y + optional v0.x.y).
Create release entry with tea.
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.

2.5 KiB Raw Blame History