docs/agents/issue-tracker.md

@@ -7,7 +7,8 @@ Issues and specs for this repo live as issues on Gitea
 
 - **Create an issue**: `tea issues create --title "..." --description-file -`
   (read the body from a heredoc on stdin), or `--description "..."` for a
-  one-liner. Add labels at creation with `--labels "..."`.
+  one-liner. Add labels at creation with `--labels "..."` (the labels
+  must already exist — see below).
 - **Read an issue**: `tea issues <index> --comments`. Use
   `tea issues list -f index,title,body,labels,comments -o json` for
   machine-readable output.
@@ -16,8 +17,16 @@ Issues and specs for this repo live as issues on Gitea
 - **Comment on an issue**: `tea comments add <index> "..."` (alias:
   `tea comments <index> "..."`).
 - **Apply / remove labels**: `tea issues edit <index> --add-labels "..."` /
-  `--remove-labels "..."`. Labels that don't exist yet are created by the
-  server on first use.
+  `--remove-labels "..."`.
+- **Labels must exist first.** Neither `issues create --labels` nor
+  `issues edit --add-labels` creates a missing label: an unknown name is
+  **silently dropped** — the command succeeds and the issue ends up
+  unlabelled (verified against this server, tea 0.16). Check with
+  `tea labels list`; create with
+  `tea labels create --name "..." --color "#rrggbb" --description "..."`,
+  then apply. After labelling, confirm it stuck (`tea issues <index>`).
+  The triage labels (`triage-labels.md`) exist; the `wayfinder:*` labels
+  below must be created before first use.
 - **Close**: `tea issues close <index>`. It does not accept a closing
   comment, so post the explanation first with
   `tea comments add <index> "..."`, then close.