From 6f73a31e08f34d16a3a84740013e2c10a5e71ab4 Mon Sep 17 00:00:00 2001
From: Cameron Cordes <cameronc.dev@gmail.com>
Date: Fri, 25 Sep 2026 16:13:28 -0400
Subject: [PATCH] docs(tracker): correct the Gitea native-dependency API call

The wayfinding doc pointed at a .../dependencies/blocked_by subpath
that 404s, and the working call needs the blocker's owner+repo in the
JSON body (omitting them 404s with 'repository does not exist').
Verified against Gitea 1.27: POST/DELETE .../issues/<child>/dependencies
with {"index", "owner", "repo"}.
---
 docs/agents/issue-tracker.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
index 6e9919f..6a63ea0 100644
--- a/docs/agents/issue-tracker.md
+++ b/docs/agents/issue-tracker.md
@@ -68,12 +68,19 @@ as tickets.
   dev.
 - **Blocking**: Gitea's **native issue dependencies** (enabled on this
   server), the canonical, UI-visible representation. Add an edge with
-  `tea api --method POST repos/{owner}/{repo}/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-issue-index>`
-  (the Gitea dependencies API takes the issue index, i.e. the visible
-  `#number`, not an internal database id). Where dependencies aren't
-  available, fall back to a `Blocked by: #<n>, #<n>` line at the top of
-  the child description. A ticket is unblocked when every blocker is
-  closed.
+  `tea api --method POST repos/{owner}/{repo}/issues/<child>/dependencies -d '{"index": <blocker-index>, "owner": "<owner>", "repo": "<repo>"}'`
+  (201 on success). Gotchas, verified against Gitea 1.27:
+  - The route is `.../dependencies` — there is **no** `blocked_by`
+    subpath (that 404s).
+  - The JSON body **must** name the blocker's repo (`owner` + `repo`);
+    omitting them yields a misleading `404 repository does not exist`
+    even though the child's path is correct.
+  - `index` is the visible `#number`, not an internal database id.
+  Verify with `tea api repos/{owner}/{repo}/issues/<child>/dependencies`
+  (lists blockers); remove with `--method DELETE` and the same body.
+  Where dependencies aren't available, fall back to a
+  `Blocked by: #<n>, #<n>` line at the top of the child description.
+  A ticket is unblocked when every blocker is closed.
 - **Frontier query**: list the map's open children (issues whose
   description carries `Part of #<map>`), drop any with an open blocker
   (dependency or `Blocked by` line) or an assignee; first in map order wins.