AGENTS.md

@@ -39,6 +39,11 @@ repository intentionally keeps its configuration inside `work_item/.work-item.ym
 Do not change its repository identity, required tests, allow list, deny list, size
 limit, or CI policy merely to bypass a workflow failure.
 
+Story stage is tracked by `status/*` labels and issue open/close, which serve as the
+board; `work-item` does not move cards between Gitea project-board columns (Gitea's API
+cannot move cards). Use label-filtered issue views instead — see
+`work_item/README.md` → "Kanban / project board position".
+
 Workflow state is local at `.git/work-item-state.json` and must never be committed.
 `claim` is resume-aware:
 

work_item/README.md

@@ -187,6 +187,37 @@ shown above.
 `--test` is repeatable. Configured `required_tests` are always included, and duplicate
 commands are run only once.
 
+## Kanban / project board position
+
+`work-item` tracks each story's stage with the `status/*` **labels**
+(`status/backlog` → `status/in-progress` → `status/review` → `status/done`, plus
+`status/blocked`) and by opening/closing the issue. **These labels are the board.**
+
+It does **not** move cards between columns of a Gitea *project* (Kanban) board, and
+this is a Gitea limitation rather than a gap in the helper:
+
+- Gitea's REST API (checked against 1.25) exposes **no** project/column/board
+  endpoints — the swagger spec has none, and `tea` has no project command.
+- Card movement uses Gitea's internal *web* endpoints, which require a logged-in
+  browser session (session cookie + CSRF). An **API token authenticates only
+  `/api/*`, not web routes** (a token request to a web page redirects to
+  `/user/login`), so the helper — which is token-only by design — cannot reach them.
+- Gitea does not auto-move a closed issue into a "Done" column either. A closed story
+  keeps whichever column it was in.
+
+**Recommended: use the labels as the board.** Filter the issue list by label to get an
+equivalent view without touching the unreachable board, e.g.:
+
+```text
+/domverse/photoanalyzer/issues?labels=status/in-progress
+/domverse/photoanalyzer/issues?labels=status/review
+/domverse/photoanalyzer/issues?q=&type=all&labels=status/done&state=closed
+```
+
+If a project board must show card positions, move the cards manually in the web UI, or
+drive the web endpoints from a real browser session (out of scope for this token-only
+helper). Do not store web login credentials in the helper to work around this.
+
 ## Safety model
 
 Before submission, the helper: