# Yurii's Gitea CLI Workflow

**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`

---

## Setup (One-time)

```bash
# Login to Gitea server
tea login add --name clavitor --url https://git.clavitor.ai --token 775a12730a65cbaf1673da048b7d01859b8b58e0

# Verify
tea whoami
# Should show: johan (admin)
```

---

## Yurii's Daily Workflow

### Step 1: Audit Code (Read-only)

```bash
# Clone repo for analysis (local copy, no changes)
cd /tmp
tea repos clone johan/clavis-telemetry

# Or analyze existing checkout
cd /home/johan/dev/clavitor/clavis/clavis-telemetry

# Run audit per CLAVITOR-AGENT-HANDBOOK.md Section II
grep -rn "return nil" --include="*.go" | head -20
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/clavitor \
  --title "Yurii: Missing unique error codes (Cardinal Rule #1)" \
  --description "$(cat <<'EOF'
## Violation
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
- Priority: Medium
EOF
)" \
  --assignees hans \
  --label "security,violation"

# Issue #2: Silent DB errors (CRITICAL)
tea issues create --repo johan/clavis-telemetry \
  --title "CRITICAL: Silent database error in updateSpan()" \
  --description "$(cat <<'EOF'
## Violation
File: 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
- Review by: Yurii (after fix)
EOF
)" \
  --assignee hans \
  --label "security,critical,cardinal-rule-1"

# Issue #3: Kuma silent failure (CRITICAL)
tea issues create --repo johan/clavis-telemetry \
  --title "CRITICAL: Silent failure in Kuma push" \
  --description "Violates Cardinal Rule #1. See kuma.go line 34." \
  --assignee hans \
  --label "security,critical"

# Issue #4: Tarpit flush error
tea issues create --repo johan/clavis-telemetry \
  --title "Yurii: Unchecked flush error in tarpit" \
  --description "main.go unchecked error. Add handling or explicit ignore with comment." \
  --assignee hans \
  --label "violation"
```

### Step 3: Track Issues

```bash
# List all issues created by Yurii
tea issues list --repo johan/clavis-telemetry --assignee hans

# Check status
tea issues view <issue-number>
```

### Step 4: Review Engineer PRs (After Hans Fixes)

```bash
# List open PRs
tea pulls list --repo johan/clavis-telemetry

# Review a specific PR
tea pulls view <pr-number>

# Comment on PR (requesting changes)
tea pulls comment <pr-number> --message "✓ Fixes Issue #2. ✗ Missing test coverage. Add test before merge."

# Approve PR (when ready)
tea pulls comment <pr-number> --message "✓ All issues addressed. Approved."
```

---

## Yurii's Rules (From Handbook)

| Can Do | Cannot Do |
|--------|-----------|
| `tea issues create` | `tea pulls create` (no code) |
| `tea pulls comment` | `tea pushes` (no commits) |
| `tea repos clone` (read) | `tea merges` (no merging) |
| `grep, audit, analyze` | SSH to prod to fix |

**Violation = Process Failure:** If Yurii pushes code instead of creating Issue → restart, assign to engineer.

---

## 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 (use --assignees, not --assignee)
tea issues create --repo johan/clavitor \
  --title "Title" \
  --description "Body" \
  --assignees hans  # ← plural!

# 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 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
tea pulls --help
```

---

## Example: Complete Yurii Session

```bash
# 1. Audit
cd /home/johan/dev/clavitor/clavis/clavis-telemetry
grep -n "return nil" clavis/clavis-telemetry/main.go
# Found: line 187 silent error

# 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/clavitor
tea pulls view 5
tea pulls comment 5 --message "✓ Fixes Issue #2. Approved."

---

**Yurii's output:** Issues in Gitea  
**Hans' input:** Issues assigned to him  
**Result:** Clean separation of audit and implementation