tai/AGENTS.md

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>

2. Login setup flow

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:

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.

CI Pipeline: Man-Page Validation

The man-page drift detection is automatically integrated into .gitea/workflows/ci.yml:

• Test name: test_man_page_covers_cli_long_options() in tests/test_cli.py
• Trigger: Runs on every push and pull request (as part of the Test step)
• Behavior: Extracts all long options from tai --help and verifies each is documented in docs/tai.1
• Failure mode: CI fails if any long option in CLI is missing from man page; prevents merge of undocumented options

How to Fix Failed Man-Page Validation

1. Identify missing options: CI output shows "Missing options in docs/tai.1: ..."
2. Update docs/tai.1: Add the missing option to the appropriate section (command or global options)
3. Re-run tests locally: python -m pytest tests/test_cli.py::test_man_page_covers_cli_long_options -v
4. Push to trigger CI: Once local test passes, push the update to trigger CI validation

Man-Page Maintenance Workflow

• When adding CLI options: Add to src/tai/cli.py and immediately update docs/tai.1 in the same commit
• When removing CLI options: Remove from src/tai/cli.py and update docs/tai.1 in the same commit
• When renaming CLI options: Update both CLI code and docs/tai.1 in one commit
• When changing option behavior/defaults: Update the option description in docs/tai.1 to reflect new behavior

Documentation Maintenance

• When adding or changing CLI commands/options, update docs/tai.1 in the same change.
• Keep README.md and docs/tai.1 aligned for user-facing flags and examples.