From 3bc9d63b93f514f9db5982712cecf9145482d6ab Mon Sep 17 00:00:00 2001
From: "M.V. Hutz" <git@maximhutz.me>
Date: Sat, 4 Jul 2026 19:46:36 -0400
Subject: [PATCH] docs: add link to branch with previous work

---
 AGENTS.md                         | 48 +++++++++++++++++++++++++++++++
 docs/adr/001_design_principles.md |  1 +
 2 files changed, 49 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8d990ca
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,48 @@
+# AGENTS.md
+
+## Git hosting: this is Gitea, not GitHub
+
+`go-cuckoo` is hosted on a self-hosted Gitea instance, not GitHub. `gh` will
+not work against it — use the `tea` CLI instead.
+
+- Remote: `git@git.maximhutz.com:tools/go-cuckoo.git`
+- Repo slug for `tea`: `tools/go-cuckoo`
+- PR URLs look like `https://git.maximhutz.com/tools/go-cuckoo/pulls/<N>`
+  (path is `pulls`, matching `tea`'s `pulls` command — not `pull`).
+
+## Inspecting a PR
+
+Get metadata as JSON:
+
+```sh
+tea pulls --repo tools/go-cuckoo -o json \
+  -f "index,title,state,author,base,head,body,labels" <PR#>
+```
+
+Non-interactive sessions print a one-line `NOTE: no gitea login detected,
+falling back to login '<name>'` on stderr before the JSON — expected, not an
+error.
+
+Useful fields from the JSON: `base` / `head` (branch names), `headSha`,
+`diffUrl` (`<pr-url>.diff`, fetchable without auth via plain `curl`/`WebFetch`
+for a public repo).
+
+**`-f diff` and `-f patch` are listed in `tea pulls --help` but are silently
+dropped from JSON output — verified empirically, don't rely on them.** To get
+the actual diff:
+
+```sh
+git fetch origin <base>
+git diff origin/<base>...HEAD    # only valid if local HEAD == PR's headSha
+```
+
+Check local `HEAD` against the PR's `headSha` first (`git rev-parse HEAD`) —
+if they differ, the checkout isn't the PR branch and this diff is wrong.
+Otherwise fall back to fetching `diffUrl` directly.
+
+## Other `tea` subcommands that exist
+
+`tea pulls list|checkout|create|review|approve|reject|merge|review-comments`,
+plus top-level `tea issues`, `tea releases`, `tea labels`. Run
+`tea <noun> --help` before assuming GitHub-shaped flags carry over — Gitea's
+CLI has its own field names and defaults (e.g. `--state` defaults to `open`).
diff --git a/docs/adr/001_design_principles.md b/docs/adr/001_design_principles.md
index 43dd41f..5c7bc46 100644
--- a/docs/adr/001_design_principles.md
+++ b/docs/adr/001_design_principles.md
@@ -33,6 +33,7 @@ Do not equate them.
    - [ ] Update the `README.md` and `doc.go` to reflect these principles.
    - [ ] Update the contributing guide and pull request template to require these principles are met.
 2. The repository should contain a living document, describing the interface differences between `go-cuckoo` and `map`.
+   (I already started work on branch `docs/interface-congruency-analysis`.)
    I should prioritize limiting any incongruencies.
    - [ ] Produce the first draft to uncover any current incongruencies.
    - [ ] Link the document to the `README.md`.