docs: Update handover and add lessons learned

- Update HANDOVER.md with AI agent skill section, API gotchas, session log
- Add lessons-learned.md with Gitea API findings and debugging insights

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

HANDOVER.md

@@ -203,6 +203,66 @@ To update Gitea to a new version:
 
 See `MIRRORING-GUIDE.md` for bidirectional GitHub ↔ Gitea mirroring setup.
 
+## AI Agent Skill (Gitea Task Management)
+
+Added 2026-02-18. Provides AI agents with project and task management via Gitea API.
+
+### Architecture
+
+Dual-mode: gitea-mcp (75+ tools for standard CRUD) + curl/jq shell helpers (milestones, workflow labels, dependencies -- areas where gitea-mcp has gaps).
+
+### Key Constraint
+
+Gitea 1.22.6 has NO project board REST API. Milestones serve as project containers with built-in progress tracking.
+
+### Files
+
+| File | Description |
+|------|-------------|
+| `.agents/skills/gitea/SKILL.md` | Agent skill document with all helpers |
+| `.agents/skills/gitea/setup-labels.sh` | Idempotent repo + 12 label creation |
+| `.agents/skills/gitea/test-gitea-skill.sh` | 10 integration tests (26 assertions) |
+| `.docs/RESEARCH-gitea-agent-skill.md` | Phase 1 research (verified against live) |
+| `.docs/DESIGN-gitea-agent-skill.md` | Phase 2 design document |
+
+### Default Task Repository
+
+`terraphim/agent-tasks` -- overridable via `GITEA_OWNER` and `GITEA_REPO` env vars.
+
+### Authentication
+
+```bash
+source ~/op_zesticai_non_prod.sh
+export GITEA_TOKEN=$(op read "op://TerraphimPlatform/git.terraphim.cloud-admin-token/credential")
+```
+
+### Workflow Labels
+
+12 scoped labels across 3 scopes (workflow, priority, type). Workflow state machine: `ready -> in-progress -> blocked -> done`.
+
+### Running Tests
+
+```bash
+source ~/op_zesticai_non_prod.sh
+export GITEA_TOKEN=$(op read "op://TerraphimPlatform/git.terraphim.cloud-admin-token/credential")
+.agents/skills/gitea/test-gitea-skill.sh
+```
+
+All 26 assertions pass against live Gitea 1.22.6 as of 2026-02-18.
+
+### Critical API Gotchas
+
+1. **Label exclusivity is UI-only** -- API POST `/labels` just appends. Must use PUT with label swap pattern (get current, filter `workflow:*`, add new, PUT all).
+2. **Assignees** -- Use `PATCH /issues/{index}` with `{"assignees": [...]}`. The `POST /issues/{index}/assignees` endpoint does not exist in 1.22.6.
+3. **Issue dependencies** -- Body uses `IssueMeta` format: `{"owner": "...", "repo": "...", "index": N}` (NOT `{"depends_on_id": N}`).
+
+## Pre-commit Hooks
+
+Added `.pre-commit-config.yaml` with:
+- Trailing whitespace, end-of-file fixer, YAML/JSON check
+- Merge conflict and private key detection
+- Secret detection via `detect-secrets` (baseline at `.secrets.baseline`)
+
 ## Key Files
 
 | File | Description |
@@ -213,6 +273,31 @@ See `MIRRORING-GUIDE.md` for bidirectional GitHub ↔ Gitea mirroring setup.
 | `s3_config.json.template` | SeaweedFS S3 config template |
 | `prometheus/prometheus.yml` | Prometheus scrape config |
 | `.github/workflows/*.yml` | GitHub Actions for mirroring |
+| `.agents/skills/gitea/SKILL.md` | AI agent Gitea skill |
+| `.agents/skills/gitea/setup-labels.sh` | Label setup script |
+| `.agents/skills/gitea/test-gitea-skill.sh` | Integration tests |
+| `.pre-commit-config.yaml` | Pre-commit hook config |
+
+## Session Log (2026-02-18)
+
+### Completed
+- Rewrote Gitea agent skill with verified API patterns (milestones, workflow labels, dependencies)
+- Created setup-labels.sh for idempotent repo + label creation
+- Created test-gitea-skill.sh with 10 tests (26 assertions), all passing
+- Found and fixed 3 API behavior bugs (label exclusivity, assignee endpoint, dependency format)
+- Added pre-commit hooks and fixed trailing whitespace across 15 files
+- Conducted disciplined research and design phases with live API verification
+
+### Commits (unpushed)
+- `b67284e` chore: Fix trailing whitespace across project files
+- `66b305d` feat(gitea-skill): Add integration tests and fix workflow label swap
+- `1fd202d` feat(gitea-skill): Rewrite Gitea agent skill with verified API patterns
+
+### Next Steps
+1. Push 3 commits to origin/main
+2. Consider adding gitea-mcp or forgejo-mcp as MCP server for Claude Code (see SKILL.md MCP Integration section)
+3. Create first real milestone and tasks in `terraphim/agent-tasks` for a project
+4. Consider Phase 4 (disciplined-verification) if more rigorous validation is needed
 
 ## Contacts