commit all of this

AGENTS.md

@@ -89,3 +89,31 @@ Before release:
 
 - 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.