diff --git a/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md b/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md
index 4f34833e..f1d6d16e 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md
+++ b/backend/src/main/java/org/raddatz/familienarchiv/tag/README.md
@@ -7,6 +7,13 @@ Hierarchical document categories. Tags form a tree via a self-referencing `paren
 Entity: `Tag` (self-referencing `parent_id` tree).
 Features: tag CRUD, hierarchical deletion (cascade to descendants), tag typeahead, admin tag management (rename, reparent, merge).
 
+## Tag tree counts (`getTagTree`)
+
+`GET /api/tags/tree` returns each node with **two** document counts, from two aggregate queries (no N+1):
+
+- `documentCount` — documents tagged with that **exact** tag (direct). Read by the admin surfaces (sidebar tree, merge preview, delete-impact guard), which describe direct-document operations.
+- `subtreeDocumentCount` — **distinct** documents tagged with that tag **or any descendant** (subtree rollup, recursive-CTE closure, depth guard ≤50). Read by the reader surfaces (`/themen` page, dashboard `ThemenWidget`) so the box number matches what `/documents?tag=X` actually finds.
+
 ## What this domain does NOT own
 
 - Documents — the `document_tags` join table is on the document side. `Tag` does not hold document references.