diff --git a/.gitea/workflows/ai-agent.yml b/.gitea/workflows/ai-agent.yml
new file mode 100644
index 0000000..34cb039
--- /dev/null
+++ b/.gitea/workflows/ai-agent.yml
@@ -0,0 +1,10 @@
+name: ai-agent
+# Thin caller so the agents work on THIS repo too (their own workflow). Same shared logic.
+# @mention an agent in a comment to start; creating an issue does not auto-start anyone.
+on:
+  issue_comment:
+    types: [created]
+jobs:
+  agent:
+    uses: ffaerber/agents/.gitea/workflows/agent.yml@main
+    secrets: inherit
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d6c8856
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,36 @@
+# AGENTS.md — how changes are made in this repo
+
+Read by AI agents (via opencode) **and** humans. Follow it.
+
+## What this repo is
+The **shared AI-agent workflow** (`.gitea/workflows/agent.yml`, reusable via `workflow_call`) used by
+every other repo through a thin caller. **Changes here affect ALL repos that call it** — so be
+extra careful, keep changes small and independently mergeable, and never break the trigger gate or
+the loop guards.
+
+## Golden rules
+- You may edit **any file**. **NEVER push to `main`, NEVER merge a PR** — all work goes on a branch
+  and becomes a PR a human reviews and merges.
+- **Never print, exfiltrate, or invent secret values.**
+- Keep changes **minimal** and match the conventions already in the file you're editing.
+- Do the work on a **branch** — never paste code or diffs into the issue thread.
+
+## Branches & pull requests
+Start on `ai/issue-<N>`. Split independent changes into separate branches (one PR each). Commit and
+push incrementally. Do NOT open PRs yourself (automated). End your reply with the PR description
+block:
+
+```
+BEGIN_PR_DESCRIPTION
+## Summary
+<what changed and why>
+## Changes
+<short bullet list>
+END_PR_DESCRIPTION
+```
+
+## Understanding the "why"
+`git log` / `git show <commit>` / `git blame` — history is the changelog.
+
+## When unsure
+Make **no** changes and reply with specific questions instead.