# 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.

## 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.