diff --git a/docs/YURII-GITEA-CLI.md b/docs/YURII-GITEA-CLI.md
index 8352207..dbf9ee7 100644
--- a/docs/YURII-GITEA-CLI.md
+++ b/docs/YURII-GITEA-CLI.md
@@ -3,6 +3,18 @@
 **Tool:** `tea` — Gitea command line interface  
 **Installed:** `/usr/local/bin/tea`  
 **Gitea Server:** https://git.clavitor.ai
+**Repository Structure:** Monorepo (`johan/clavitor`) — all issues go here, not sub-repos
+
+## ⚠️ Important: Monorepo Pattern
+
+Clavitor uses a **monorepo** — one repository contains all subprojects:
+- `clavis-vault/` → Issues in `johan/clavitor`
+- `clavis-telemetry/` → Issues in `johan/clavitor`  
+- `clavitor.ai/` → Issues in `johan/clavitor`
+
+**Never create issues in `johan/clavis-*` repos** — those are mirrors only.
+
+**Always use:** `--repo johan/clavitor`
 
 ---
 
@@ -39,23 +51,26 @@ grep -rn "catch.*{" --include="*.js" | head -10
 ### Step 2: Create Issues (Never Code)
 
 ```bash
+# ⚠️ IMPORTANT: Use --repo johan/clavitor (monorepo)
+# NOT --repo johan/clavis-telemetry (that repo has no issues enabled)
+
 # Issue #1: Missing error codes
-tea issues create --repo johan/clavis-telemetry \
+tea issues create --repo johan/clavitor \
   --title "Yurii: Missing unique error codes (Cardinal Rule #1)" \
   --description "$(cat <<'EOF'
 ## Violation
-File: main.go:45
+File: clavis/clavis-telemetry/main.go:45
 Current: Generic error without ERR-XXXXX code
 
 ## Required
 Per Section II: All errors must have unique codes
 
 ## Assignment
-- Fix by: Hans
+- Fix by: @hans
 - Priority: Medium
 EOF
 )" \
-  --assignee hans \
+  --assignees hans \
   --label "security,violation"
 
 # Issue #2: Silent DB errors (CRITICAL)
@@ -137,26 +152,60 @@ tea pulls comment <pr-number> --message "✓ All issues addressed. Approved."
 
 ---
 
+## Known CLI Limitations & Workarounds
+
+### 1. Labels Don't Show in List View (Bug)
+**Problem:** `tea issues list` shows empty LABELS column even when labels exist.  
+**Workaround:** View individual issue to see labels:
+```bash
+tea issues view <number>  # Shows labels properly
+```
+**Status:** Gitea CLI bug — labels ARE saved, just not displayed in list.
+
+### 2. User Discovery is Hard
+**Problem:** Can't find valid usernames for `--assignees`.  
+**Workaround:** Use these known agent usernames:
+```
+sarah, charles, maria, james, xiao, emma, arthur, victoria,
+luna, thomas, hugo, hans, george, shakib, yurii
+```
+**Or check web UI:** https://git.clavitor.ai/johan/clavitor/settings/collaboration
+
+### 3. "No gitea login detected" Noise
+**Problem:** Every command shows: `NOTE: no gitea login detected, falling back to login 'clavitor'`  
+**Workaround:** Ignore it — it's just noise, commands still work.
+
+### 4. --assignees Flag (Plural, Not --assignee)
+**Correct:** `--assignees hans`  
+**Incorrect:** `--assignee hans` (this fails silently)
+
+---
+
 ## Quick Reference
 
 ```bash
-# Create issue
-tea issues create --repo owner/repo --title "Title" --description "Body" --assignee username
+# Create issue (use --assignees, not --assignee)
+tea issues create --repo johan/clavitor \
+  --title "Title" \
+  --description "Body" \
+  --assignees hans  # ← plural!
 
-# List issues
-tea issues list --repo owner/repo
+# List issues (labels won't show — use view for details)
+tea issues list --repo johan/clavitor
+
+# View specific (shows labels correctly)
+tea issues view <number>
 
 # List PRs
-tea pulls list --repo owner/repo
-
-# View specific
-tea issues view <number>
-tea pulls view <number>
+tea pulls list --repo johan/clavitor
 
 # Comment
 tea issues comment <number> --message "text"
 tea pulls comment <number> --message "text"
 
+# List labels (if you need to check)
+curl -s https://git.clavitor.ai/api/v1/repos/johan/clavitor/labels | grep name
+
 # Help
 tea --help
 tea issues --help
@@ -170,22 +219,36 @@ tea pulls --help
 ```bash
 # 1. Audit
 cd /home/johan/dev/clavitor/clavis/clavis-telemetry
-grep -n "return nil" main.go
+grep -n "return nil" clavis/clavis-telemetry/main.go
 # Found: line 187 silent error
 
-# 2. Create issue
-tea issues create --repo johan/clavis-telemetry \
-  --title "CRITICAL: Silent error at main.go:187" \
-  --description "Violates Cardinal Rule #1. Must return ERR-50004." \
-  --assignee hans
+# 2. Create issue (NOTE: use johan/clavitor, NOT clavis-telemetry)
+tea issues create --repo johan/clavitor \
+  --title "CRITICAL: Silent error in telemetry at main.go:187" \
+  --description "$(cat <<'EOF'
+## Violation
+File: clavis/clavis-telemetry/main.go:187
+Current: `if err != nil { return nil }` — silent failure
+
+## Threat
+Operational blindness during incidents. No forensic trail.
+
+## Required
+Per Cardinal Rule #1: Return explicit error with ERR-50004
+
+## Assignment
+- Fix by: @hans
+- Priority: Critical
+EOF
+)" \
+  --assignees hans
 
 # 3. Done. Hans gets notification, creates fix PR.
 
 # 4. Later: Review Hans' PR
-tea pulls list --repo johan/clavis-telemetry
+tea pulls list --repo johan/clavitor
 tea pulls view 5
-tea pulls comment 5 --message "Approved. Fixes issue."
-```
+tea pulls comment 5 --message "✓ Fixes Issue #2. Approved."
 
 ---