diff --git a/knowledge-base/hermes-gitea-ecosystem-manual.md b/knowledge-base/hermes-gitea-ecosystem-manual.md
new file mode 100644
index 0000000..64487ed
--- /dev/null
+++ b/knowledge-base/hermes-gitea-ecosystem-manual.md
@@ -0,0 +1,107 @@
+# Hermes Gitea & Agent Development Ecosystem Manual
+
+**Version 1.0 | June 21, 2026**
+
+This manual documents the full Hermes AI Agent Development setup on Gitea. It covers repositories, the role-based multi-agent system, workflows, the critical verified operations protocol, and how to work within it. Maintained as part of your personal-agent-os knowledge base.
+
+## 1. Introduction & Philosophy
+
+The Hermes ecosystem uses layered repositories for clear separation of concerns:
+
+- **core-planning (Ty_Tech)**: Strategic HQ. High-level planning, task decomposition, ADRs, research synthesis, team guidelines, KANBAN workflows. *Read-only for you now.*
+- **template-app (Ty_Tech)**: Reusable starter template with agent role files (`agents/HA_*.md`), issue/PR templates. Fork for new feature projects. *Read-only.*
+- **hermes-agent-development (Ty_Tech)**: Active implementation hub (new repo). Core Hermes code, orchestration, persistent agent OS, skills hub, integrations. *Read-only.*
+- **personal-agent-os (Tony_tech)**: Your private git-backed external brain. Knowledge base, project tracking, automation patterns, agent configs. *Writable.*
+- **research (Ty_Tech)**: Informal research capture. *Read-only.*
+
+**Philosophy**: Planning-first. Durable Kanban coordination. Role specialization with clear handoffs. Verified SHA-based operations for all mutations (no hallucinations). Traceability from plans to code. Small atomic commits.
+
+## 2. Accessing Gitea
+
+- **Web**: https://gitea.vps1.afterthedemo.com/ (Ty_Tech org and your Tony_tech repos)
+- **Git**: Clone via HTTPS or SSH. Use existing PuTTY SSH tunnels for secure access from local/VPS.
+- **MCP Tools**: TonyTechMCP connector provides `tonytechmcp___*` tools for programmatic access.
+
+**Important**: You specified read-only on Ty_Tech org repos. All writes go through Tony_tech/personal-agent-os or other personal scopes.
+
+## 3. The Role-Based Multi-Agent System
+
+Agents have specialized roles for efficient, traceable collaboration (defined in template-app/agents/):
+
+| Role | Agent Name | Primary Responsibility | Key Outputs |
+|------|------------|------------------------|-------------|
+| Planner | HA_Planner | Task decomposition, planning, prioritization | Issues, plans, roadmaps, status reports |
+| Architect | HA_Architect | System design, technical decisions | ADRs, architecture docs |
+| Coder | HA_Coder | Feature/fix implementation | Code, branches, PRs |
+| Reviewer | HA_Reviewer | Quality, security, best practices | PR feedback |
+| Tester | HA_Tester | Test creation & validation | Test results, bugs |
+| Orchestrator | HA_Orchestrator | Workflow coordination, routing, unblocking | Task handoffs, Kanban management |
+| DevOps | HA_DevOps | CI/CD, infrastructure, deployments | Pipelines, environments |
+
+## 4. Core Workflows
+
+### Planning-First
+All major work starts with planning/decomposition in core-planning (read the docs there for details).
+
+### Starting New Projects
+Use template-app as base. For core Hermes work, extend hermes-agent-development (read-only for now; plan changes via issues).
+
+### Kanban Coordination
+Use Hermes Kanban for multi-agent or human-overseen work (durable audit trail).
+
+**Recommended statuses** (from core-planning docs):
+- triage → todo → ready → running → blocked/done/archived
+
+**Task updates**: Use SCRUM format (What I did / Doing next / Blockers). Escalate to human only for external dependencies, strategic conflicts, major decisions, or prolonged blockers.
+
+### Branching & PRs
+- `main` protected.
+- Feature branches + PRs.
+- Reference planning issues.
+- PRs reviewed by HA_Reviewer.
+
+### Human Role
+Strategic overseer: set direction, review aggregated reports, handle qualified escalations.
+
+## 5. Verified Gitea Operations Protocol (Mandatory for Writes)
+
+**Never** mutate without this. Enforced by gitea-mcp-verified-ops skill.
+
+1. **Pre-verify**: Read current state/SHA (e.g., `tonytechmcp___get_file_contents`, list_branches, get_tree).
+2. **Mutate**: Use exact SHA for updates/deletes in create_or_update_file (or other write tools). For new files, omit SHA after confirming absence.
+3. **Post-verify**: Immediately re-read and confirm new SHA/content matches intent.
+4. Abort/report on mismatches.
+
+This applies to Tony_tech writes. Always use fresh reads before asserting state.
+
+**Key tools** (TonyTechMCP):
+- Read: get_file_contents, get_repository_tree, list_org_repos (Ty_Tech read OK), list_my_repos
+- Write: create_or_update_file (with SHA), create_repo (in Tony_tech OK), fork_repo, etc.
+
+## 6. Personal-Agent-OS Structure (Your Writable Layer)
+
+- `knowledge-base/` — Research, patterns, manuals (this manual lives here)
+- `projects/hermes-persistent-os/` — Specific Hermes OS work
+- `agent-config/`, `agent-comms/`, `templates/`, `_meta/decision-log.md`
+
+**How to include docs**: Add/edit Markdown files here (e.g., this manual). Regenerate PDFs as needed via scripts.
+
+## 7. Best Practices
+
+- Plan in core-planning (read).
+- Use Kanban for coordination.
+- Verified protocol for all writes (in Tony_tech).
+- Small commits, explicit handoffs, traceability.
+- Treat docs as living (update this manual as processes evolve).
+
+## Quick Reference
+
+- Gitea URL: https://gitea.vps1.afterthedemo.com/Tony_tech/personal-agent-os (and Ty_Tech read-only)
+- New manual PDF: See artifacts or regenerate via Python script in personal-agent-os.
+- For questions: Use agent-comms/grok-inbox/ or decision-log.
+
+*This manual was synthesized from your Gitea state. Update it here in personal-agent-os as needed. No writes performed to Ty_Tech.*
+
+---
+
+**End of Manual**
\ No newline at end of file