fix: merge repo_update — add archived+template, keep default_branch+confirm from main

Adds a repo_update tool exposing PATCH /api/v1/repos/{owner}/{name}
with optional pointer fields (archived, description, private,
website, template). Only fields set by the caller are sent on the
wire, so the server patches exactly what was asked for.

Originally needed to archive ingestion-svc cleanly instead of
leaving a README tombstone, and to flip template-go-{agent,web}
to template=true so create_project_from_template stops failing
the "is not marked as template" guard.

Wire-level enforcement of "at least one field" returns ErrValidation
before any network call, preventing no-op PATCHes.

private=false (making a repo public) is allowed but flagged in the
tool description with a "verify intent before calling" warning.
The earlier issue draft suggested an ntfy confirmation hook for
that path — out of scope for this PR; the warning string is the
minimum that fits inside the tool surface today.

Wires NewRepoUpdate into cmd/gitea-mcp/main.go alongside the rest
of the repo_* family.

Closes #12

.aider.conf.yml

@@ -0,0 +1,2 @@
+read: .aider.conventions.md
+auto-commits: false

.aider.conventions.md

@@ -0,0 +1,250 @@
+# Agent context — Mathias workspace
+
+<!-- Canonical root context for all AI coding agents.
+     Lives at: ~/dev/.context/AGENT.md
+     Applies to every project under ~/dev/ unless overridden.
+     
+     Run `task context:sync` from ~/dev/ to regenerate harness-specific files.
+     Project-level context in .context/PROJECT.md layers on top of this. -->
+
+## Who I am
+
+I'm Mathias, a digital product manager and technology consultant based in Sweden.
+I build software, research emerging tech, and deliver consulting engagements
+for clients under NDA. I work across AI/ML, financial automation, web applications,
+and climate/sustainability tech.
+
+## How I work with agents
+
+- I think like a product manager — I care about *why* before *how*
+- I want agents to be opinionated and push back, not just execute blindly
+- I prefer concise responses; skip ceremony and get to the point
+- When I say "build this", I mean production-quality with tests, not a demo
+- Ask me before making irreversible changes or adding heavy dependencies
+- I work with confidential client data — never send it to cloud APIs unless I explicitly say it's OK
+
+## Behavior rules
+
+These rules apply to every task across every project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Default stack
+
+| Layer | Default | Fallback | Last resort |
+|-------|---------|----------|-------------|
+| Language | Go | Python | TypeScript, Java, C |
+| UI | HTMX + Templ | Server-rendered HTML | React (only if SPA is justified) |
+| Build | Task (taskfile.dev) | Make | — |
+| Containers | Docker Compose (dev), k3s (prod) | — | — |
+| DB | PostgreSQL + sqlc | SQLite | — |
+| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — |
+| Logging | slog (structured) | — | — |
+| Testing | Table-driven, testify | — | — |
+
+Exploratory: Rust, Zig — I'll tell you when I want these.
+
+## Code conventions
+
+- **Go style**: golines, gofumpt, golangci-lint
+- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
+- **Naming**: stdlib conventions, no stuttering
+- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
+- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), one concern per PR, PR describes *why* not *what*
+- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
+- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc are pre-approved; anything else needs justification in the commit message
+
+## Infrastructure
+
+Three machines on Tailscale:
+
+| Machine | Role | Key specs |
+|---------|------|-----------|
+| koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
+| iguana | Services, builds | M2 Ultra Mac |
+| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
+
+- **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
+- **Orchestration**: k3s cluster across all three machines
+- **Networking**: Tailscale mesh
+
+## Project landscape
+
+All development repos live at `~/dev/` (softlink from `~/Documents/local-dev/`).
+
+Organized in thematic folders:
+
+| Folder | Focus | Count |
+|--------|-------|-------|
+| `GO/` | Go web frameworks, API integrations, learning projects | ~10 |
+| `AI/` | ML research, AI frameworks (FinRL, DSPy, crawl4ai) | ~6 |
+| `AGENTS/` | Autonomous agents, coding agents, MCP servers, infra | ~15 |
+| `QKX/` | Invoice processing, financial automation, payment systems | ~13 |
+| `XT/` | Climate data, sustainability (Klimatkollen, Garbo) | ~2 |
+
+See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
+
+### Key active projects
+
+- **super-koala** (`AGENTS/`) — multi-component agent stack with LangGraph, DSPy, MCP
+- **azure-tiger** (`QKX/`) — invoice extraction → ISO 20022 payment instructions
+- **gocrwl** (`AGENTS/`) — Go web crawler with containerized deployment
+- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
+- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
+
+## Knowledge base
+
+When available, agents can query the shared knowledge base:
+
+- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
+- **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
+
+<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
+     name once hyperguild is deployed. Until then, agents that try to
+     reach the knowledge service on a host where it isn't running will
+     get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
+- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
+
+## Client work rules
+
+When working on a project tagged with a client name:
+1. Never send code, data, or context to cloud APIs — use local models only
+2. Never reference other client projects or their data
+3. Keep all artifacts within the client's git org / directory
+4. Treat everything as confidential unless told otherwise
+
+## Harness-agnostic principles
+
+This context is designed to work with any AI coding tool:
+- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
+- Pi Coding Agent, Mistral Vibe, Antigravity
+- Any tool that accepts a system prompt or reads a markdown context file
+
+The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
+Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
+
+## How context propagates
+
+Canonical sources of truth:
+- Universal: `~/dev/.context/AGENT.md` (this file)
+- Project: `<repo>/.context/PROJECT.md` (per-repo)
+
+Derived files (committed, regenerated by `task context:sync`):
+- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
+  `.context/system-prompt.txt`
+
+Workflow:
+1. Edit a canonical file. Run `task context:sync`. Commit canonical and
+   derived together. Push.
+2. On any other host, `git pull` brings both. Claude Code (tree-walking)
+   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
+   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
+3. `task check` runs `context:sync` then asserts `git status --porcelain`
+   is empty over the derived files (catches both modified-tracked drift
+   and missing-untracked adapters). A drift fails the check with a
+   message telling you to stage the regenerated files.
+
+Behavior rules in this file and per-project rules in `PROJECT.md` apply
+unconditionally on every host, every harness.
+
+## Engineering Skills
+
+Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+
+See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+
+Key skills:
+- **TDD**: always write tests first — load `tdd` skill
+- **Code Review**: load `code-review` skill before any review
+- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
+- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+
+---
+
+# Project context
+
+<!-- Canonical project context. Edit this, run `task context:sync`.
+     Root agent context from ~/dev/.context/AGENT.md is automatically
+     prepended for harnesses that don't walk the directory tree. -->
+
+## Identity
+
+- **Name**: gitea-mcp
+- **Owner**: Mathias
+- **Client**: personal
+- **Repo**: https://gitea.d-ma.be/mathias/gitea-mcp
+- **Status**: active
+
+## Stack
+
+- **Primary language**: Go
+- **UI layer**: HTMX + Templ (when applicable)
+- **Fallback languages**: Python, TypeScript (justify in PR if used)
+- **Build**: Task (taskfile.dev), not Make
+- **Containers**: Docker (compose for dev, k3s for deploy)
+- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
+
+## Conventions
+
+### Code style
+- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
+- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
+- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
+- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
+
+### Architecture preferences
+- Prefer standard library over frameworks (net/http over gin/echo)
+- Dependency injection via constructor functions, not containers
+- Configuration via environment variables, parsed at startup into a typed struct
+- Structured logging via `slog`
+
+### Git
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
+- Branch naming: `feat/short-description`, `fix/short-description`
+- PRs: one concern per PR, description explains *why* not *what*
+
+### Security
+- No secrets in code, ever — use env vars or SOPS-encrypted files
+- Client data never leaves local network unless explicitly cleared
+- Dependencies: audit with `govulncheck` before adding
+
+## Knowledge base access
+
+This project can query the shared knowledge base via MCP or HTTP:
+
+- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+- **Scoping**: queries are filtered to collection `personal` + `public`
+
+## Behavior rules
+
+These rules apply to every task in this project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Agent instructions
+
+When acting as a coding agent on this project:
+
+1. Read this file and all `SKILL.md` files in `.skills/` before starting work
+2. Run `task check` before committing (lint + test + vet)
+3. If unsure about a convention, check `DECISIONS.md` or ask
+4. Never modify files outside the project root without explicit permission
+5. When adding a dependency, explain why in the commit message
+6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM

.context/PROJECT.md

@@ -0,0 +1,79 @@
+# Project context
+
+<!-- Canonical project context. Edit this, run `task context:sync`.
+     Root agent context from ~/dev/.context/AGENT.md is automatically
+     prepended for harnesses that don't walk the directory tree. -->
+
+## Identity
+
+- **Name**: gitea-mcp
+- **Owner**: Mathias
+- **Client**: personal
+- **Repo**: https://gitea.d-ma.be/mathias/gitea-mcp
+- **Status**: active
+
+## Stack
+
+- **Primary language**: Go
+- **UI layer**: HTMX + Templ (when applicable)
+- **Fallback languages**: Python, TypeScript (justify in PR if used)
+- **Build**: Task (taskfile.dev), not Make
+- **Containers**: Docker (compose for dev, k3s for deploy)
+- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
+
+## Conventions
+
+### Code style
+- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
+- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
+- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
+- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
+
+### Architecture preferences
+- Prefer standard library over frameworks (net/http over gin/echo)
+- Dependency injection via constructor functions, not containers
+- Configuration via environment variables, parsed at startup into a typed struct
+- Structured logging via `slog`
+
+### Git
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
+- Branch naming: `feat/short-description`, `fix/short-description`
+- PRs: one concern per PR, description explains *why* not *what*
+
+### Security
+- No secrets in code, ever — use env vars or SOPS-encrypted files
+- Client data never leaves local network unless explicitly cleared
+- Dependencies: audit with `govulncheck` before adding
+
+## Knowledge base access
+
+This project can query the shared knowledge base via MCP or HTTP:
+
+- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+- **Scoping**: queries are filtered to collection `personal` + `public`
+
+## Behavior rules
+
+These rules apply to every task in this project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Agent instructions
+
+When acting as a coding agent on this project:
+
+1. Read this file and all `SKILL.md` files in `.skills/` before starting work
+2. Run `task check` before committing (lint + test + vet)
+3. If unsure about a convention, check `DECISIONS.md` or ask
+4. Never modify files outside the project root without explicit permission
+5. When adding a dependency, explain why in the commit message
+6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM

.context/mcp.json

@@ -0,0 +1,22 @@
+{
+  "mcpServers": {
+    "brain": {
+      "type": "http",
+      "url": "https://brain-mcp.d-ma.be/mcp",
+      "headers": {
+        "Authorization": "Bearer ${BRAIN_MCP_TOKEN}"
+      }
+    },
+    "gitea": {
+      "type": "http",
+      "url": "https://git-mcp.d-ma.be/mcp",
+      "headers": {
+        "Authorization": "Bearer ${GITEA_MCP_TOKEN}"
+      }
+    },
+    "infra": {
+      "type": "http",
+      "url": "https://infra-mcp.d-ma.be/mcp"
+    }
+  }
+}

.context/system-prompt.txt

@@ -0,0 +1,257 @@
+You are a coding assistant working on a specific project.
+Follow all conventions from both the root agent context and project context.
+
+---
+
+# Agent context — Mathias workspace
+
+<!-- Canonical root context for all AI coding agents.
+     Lives at: ~/dev/.context/AGENT.md
+     Applies to every project under ~/dev/ unless overridden.
+     
+     Run `task context:sync` from ~/dev/ to regenerate harness-specific files.
+     Project-level context in .context/PROJECT.md layers on top of this. -->
+
+## Who I am
+
+I'm Mathias, a digital product manager and technology consultant based in Sweden.
+I build software, research emerging tech, and deliver consulting engagements
+for clients under NDA. I work across AI/ML, financial automation, web applications,
+and climate/sustainability tech.
+
+## How I work with agents
+
+- I think like a product manager — I care about *why* before *how*
+- I want agents to be opinionated and push back, not just execute blindly
+- I prefer concise responses; skip ceremony and get to the point
+- When I say "build this", I mean production-quality with tests, not a demo
+- Ask me before making irreversible changes or adding heavy dependencies
+- I work with confidential client data — never send it to cloud APIs unless I explicitly say it's OK
+
+## Behavior rules
+
+These rules apply to every task across every project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Default stack
+
+| Layer | Default | Fallback | Last resort |
+|-------|---------|----------|-------------|
+| Language | Go | Python | TypeScript, Java, C |
+| UI | HTMX + Templ | Server-rendered HTML | React (only if SPA is justified) |
+| Build | Task (taskfile.dev) | Make | — |
+| Containers | Docker Compose (dev), k3s (prod) | — | — |
+| DB | PostgreSQL + sqlc | SQLite | — |
+| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — |
+| Logging | slog (structured) | — | — |
+| Testing | Table-driven, testify | — | — |
+
+Exploratory: Rust, Zig — I'll tell you when I want these.
+
+## Code conventions
+
+- **Go style**: golines, gofumpt, golangci-lint
+- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
+- **Naming**: stdlib conventions, no stuttering
+- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
+- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), one concern per PR, PR describes *why* not *what*
+- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
+- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc are pre-approved; anything else needs justification in the commit message
+
+## Infrastructure
+
+Three machines on Tailscale:
+
+| Machine | Role | Key specs |
+|---------|------|-----------|
+| koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
+| iguana | Services, builds | M2 Ultra Mac |
+| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
+
+- **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
+- **Orchestration**: k3s cluster across all three machines
+- **Networking**: Tailscale mesh
+
+## Project landscape
+
+All development repos live at `~/dev/` (softlink from `~/Documents/local-dev/`).
+
+Organized in thematic folders:
+
+| Folder | Focus | Count |
+|--------|-------|-------|
+| `GO/` | Go web frameworks, API integrations, learning projects | ~10 |
+| `AI/` | ML research, AI frameworks (FinRL, DSPy, crawl4ai) | ~6 |
+| `AGENTS/` | Autonomous agents, coding agents, MCP servers, infra | ~15 |
+| `QKX/` | Invoice processing, financial automation, payment systems | ~13 |
+| `XT/` | Climate data, sustainability (Klimatkollen, Garbo) | ~2 |
+
+See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
+
+### Key active projects
+
+- **super-koala** (`AGENTS/`) — multi-component agent stack with LangGraph, DSPy, MCP
+- **azure-tiger** (`QKX/`) — invoice extraction → ISO 20022 payment instructions
+- **gocrwl** (`AGENTS/`) — Go web crawler with containerized deployment
+- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
+- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
+
+## Knowledge base
+
+When available, agents can query the shared knowledge base:
+
+- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
+- **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
+
+<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
+     name once hyperguild is deployed. Until then, agents that try to
+     reach the knowledge service on a host where it isn't running will
+     get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
+- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
+
+## Client work rules
+
+When working on a project tagged with a client name:
+1. Never send code, data, or context to cloud APIs — use local models only
+2. Never reference other client projects or their data
+3. Keep all artifacts within the client's git org / directory
+4. Treat everything as confidential unless told otherwise
+
+## Harness-agnostic principles
+
+This context is designed to work with any AI coding tool:
+- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
+- Pi Coding Agent, Mistral Vibe, Antigravity
+- Any tool that accepts a system prompt or reads a markdown context file
+
+The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
+Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
+
+## How context propagates
+
+Canonical sources of truth:
+- Universal: `~/dev/.context/AGENT.md` (this file)
+- Project: `<repo>/.context/PROJECT.md` (per-repo)
+
+Derived files (committed, regenerated by `task context:sync`):
+- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
+  `.context/system-prompt.txt`
+
+Workflow:
+1. Edit a canonical file. Run `task context:sync`. Commit canonical and
+   derived together. Push.
+2. On any other host, `git pull` brings both. Claude Code (tree-walking)
+   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
+   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
+3. `task check` runs `context:sync` then asserts `git status --porcelain`
+   is empty over the derived files (catches both modified-tracked drift
+   and missing-untracked adapters). A drift fails the check with a
+   message telling you to stage the regenerated files.
+
+Behavior rules in this file and per-project rules in `PROJECT.md` apply
+unconditionally on every host, every harness.
+
+## Engineering Skills
+
+Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+
+See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+
+Key skills:
+- **TDD**: always write tests first — load `tdd` skill
+- **Code Review**: load `code-review` skill before any review
+- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
+- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+
+---
+
+# Project context
+
+<!-- Canonical project context. Edit this, run `task context:sync`.
+     Root agent context from ~/dev/.context/AGENT.md is automatically
+     prepended for harnesses that don't walk the directory tree. -->
+
+## Identity
+
+- **Name**: gitea-mcp
+- **Owner**: Mathias
+- **Client**: personal
+- **Repo**: https://gitea.d-ma.be/mathias/gitea-mcp
+- **Status**: active
+
+## Stack
+
+- **Primary language**: Go
+- **UI layer**: HTMX + Templ (when applicable)
+- **Fallback languages**: Python, TypeScript (justify in PR if used)
+- **Build**: Task (taskfile.dev), not Make
+- **Containers**: Docker (compose for dev, k3s for deploy)
+- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
+
+## Conventions
+
+### Code style
+- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
+- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
+- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
+- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
+
+### Architecture preferences
+- Prefer standard library over frameworks (net/http over gin/echo)
+- Dependency injection via constructor functions, not containers
+- Configuration via environment variables, parsed at startup into a typed struct
+- Structured logging via `slog`
+
+### Git
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
+- Branch naming: `feat/short-description`, `fix/short-description`
+- PRs: one concern per PR, description explains *why* not *what*
+
+### Security
+- No secrets in code, ever — use env vars or SOPS-encrypted files
+- Client data never leaves local network unless explicitly cleared
+- Dependencies: audit with `govulncheck` before adding
+
+## Knowledge base access
+
+This project can query the shared knowledge base via MCP or HTTP:
+
+- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+- **Scoping**: queries are filtered to collection `personal` + `public`
+
+## Behavior rules
+
+These rules apply to every task in this project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Agent instructions
+
+When acting as a coding agent on this project:
+
+1. Read this file and all `SKILL.md` files in `.skills/` before starting work
+2. Run `task check` before committing (lint + test + vet)
+3. If unsure about a convention, check `DECISIONS.md` or ask
+4. Never modify files outside the project root without explicit permission
+5. When adding a dependency, explain why in the commit message
+6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
+
+---

.cursorrules

@@ -0,0 +1,253 @@
+# Cursor rules — auto-generated
+# Do not edit. Run: task context:sync
+
+# Agent context — Mathias workspace
+
+<!-- Canonical root context for all AI coding agents.
+     Lives at: ~/dev/.context/AGENT.md
+     Applies to every project under ~/dev/ unless overridden.
+     
+     Run `task context:sync` from ~/dev/ to regenerate harness-specific files.
+     Project-level context in .context/PROJECT.md layers on top of this. -->
+
+## Who I am
+
+I'm Mathias, a digital product manager and technology consultant based in Sweden.
+I build software, research emerging tech, and deliver consulting engagements
+for clients under NDA. I work across AI/ML, financial automation, web applications,
+and climate/sustainability tech.
+
+## How I work with agents
+
+- I think like a product manager — I care about *why* before *how*
+- I want agents to be opinionated and push back, not just execute blindly
+- I prefer concise responses; skip ceremony and get to the point
+- When I say "build this", I mean production-quality with tests, not a demo
+- Ask me before making irreversible changes or adding heavy dependencies
+- I work with confidential client data — never send it to cloud APIs unless I explicitly say it's OK
+
+## Behavior rules
+
+These rules apply to every task across every project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Default stack
+
+| Layer | Default | Fallback | Last resort |
+|-------|---------|----------|-------------|
+| Language | Go | Python | TypeScript, Java, C |
+| UI | HTMX + Templ | Server-rendered HTML | React (only if SPA is justified) |
+| Build | Task (taskfile.dev) | Make | — |
+| Containers | Docker Compose (dev), k3s (prod) | — | — |
+| DB | PostgreSQL + sqlc | SQLite | — |
+| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — |
+| Logging | slog (structured) | — | — |
+| Testing | Table-driven, testify | — | — |
+
+Exploratory: Rust, Zig — I'll tell you when I want these.
+
+## Code conventions
+
+- **Go style**: golines, gofumpt, golangci-lint
+- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
+- **Naming**: stdlib conventions, no stuttering
+- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
+- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), one concern per PR, PR describes *why* not *what*
+- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
+- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc are pre-approved; anything else needs justification in the commit message
+
+## Infrastructure
+
+Three machines on Tailscale:
+
+| Machine | Role | Key specs |
+|---------|------|-----------|
+| koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
+| iguana | Services, builds | M2 Ultra Mac |
+| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
+
+- **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
+- **Orchestration**: k3s cluster across all three machines
+- **Networking**: Tailscale mesh
+
+## Project landscape
+
+All development repos live at `~/dev/` (softlink from `~/Documents/local-dev/`).
+
+Organized in thematic folders:
+
+| Folder | Focus | Count |
+|--------|-------|-------|
+| `GO/` | Go web frameworks, API integrations, learning projects | ~10 |
+| `AI/` | ML research, AI frameworks (FinRL, DSPy, crawl4ai) | ~6 |
+| `AGENTS/` | Autonomous agents, coding agents, MCP servers, infra | ~15 |
+| `QKX/` | Invoice processing, financial automation, payment systems | ~13 |
+| `XT/` | Climate data, sustainability (Klimatkollen, Garbo) | ~2 |
+
+See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
+
+### Key active projects
+
+- **super-koala** (`AGENTS/`) — multi-component agent stack with LangGraph, DSPy, MCP
+- **azure-tiger** (`QKX/`) — invoice extraction → ISO 20022 payment instructions
+- **gocrwl** (`AGENTS/`) — Go web crawler with containerized deployment
+- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
+- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
+
+## Knowledge base
+
+When available, agents can query the shared knowledge base:
+
+- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
+- **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
+
+<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
+     name once hyperguild is deployed. Until then, agents that try to
+     reach the knowledge service on a host where it isn't running will
+     get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
+- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
+
+## Client work rules
+
+When working on a project tagged with a client name:
+1. Never send code, data, or context to cloud APIs — use local models only
+2. Never reference other client projects or their data
+3. Keep all artifacts within the client's git org / directory
+4. Treat everything as confidential unless told otherwise
+
+## Harness-agnostic principles
+
+This context is designed to work with any AI coding tool:
+- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
+- Pi Coding Agent, Mistral Vibe, Antigravity
+- Any tool that accepts a system prompt or reads a markdown context file
+
+The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
+Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
+
+## How context propagates
+
+Canonical sources of truth:
+- Universal: `~/dev/.context/AGENT.md` (this file)
+- Project: `<repo>/.context/PROJECT.md` (per-repo)
+
+Derived files (committed, regenerated by `task context:sync`):
+- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
+  `.context/system-prompt.txt`
+
+Workflow:
+1. Edit a canonical file. Run `task context:sync`. Commit canonical and
+   derived together. Push.
+2. On any other host, `git pull` brings both. Claude Code (tree-walking)
+   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
+   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
+3. `task check` runs `context:sync` then asserts `git status --porcelain`
+   is empty over the derived files (catches both modified-tracked drift
+   and missing-untracked adapters). A drift fails the check with a
+   message telling you to stage the regenerated files.
+
+Behavior rules in this file and per-project rules in `PROJECT.md` apply
+unconditionally on every host, every harness.
+
+## Engineering Skills
+
+Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+
+See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+
+Key skills:
+- **TDD**: always write tests first — load `tdd` skill
+- **Code Review**: load `code-review` skill before any review
+- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
+- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+
+---
+
+# Project context
+
+<!-- Canonical project context. Edit this, run `task context:sync`.
+     Root agent context from ~/dev/.context/AGENT.md is automatically
+     prepended for harnesses that don't walk the directory tree. -->
+
+## Identity
+
+- **Name**: gitea-mcp
+- **Owner**: Mathias
+- **Client**: personal
+- **Repo**: https://gitea.d-ma.be/mathias/gitea-mcp
+- **Status**: active
+
+## Stack
+
+- **Primary language**: Go
+- **UI layer**: HTMX + Templ (when applicable)
+- **Fallback languages**: Python, TypeScript (justify in PR if used)
+- **Build**: Task (taskfile.dev), not Make
+- **Containers**: Docker (compose for dev, k3s for deploy)
+- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
+
+## Conventions
+
+### Code style
+- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
+- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
+- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
+- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
+
+### Architecture preferences
+- Prefer standard library over frameworks (net/http over gin/echo)
+- Dependency injection via constructor functions, not containers
+- Configuration via environment variables, parsed at startup into a typed struct
+- Structured logging via `slog`
+
+### Git
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
+- Branch naming: `feat/short-description`, `fix/short-description`
+- PRs: one concern per PR, description explains *why* not *what*
+
+### Security
+- No secrets in code, ever — use env vars or SOPS-encrypted files
+- Client data never leaves local network unless explicitly cleared
+- Dependencies: audit with `govulncheck` before adding
+
+## Knowledge base access
+
+This project can query the shared knowledge base via MCP or HTTP:
+
+- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+- **Scoping**: queries are filtered to collection `personal` + `public`
+
+## Behavior rules
+
+These rules apply to every task in this project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Agent instructions
+
+When acting as a coding agent on this project:
+
+1. Read this file and all `SKILL.md` files in `.skills/` before starting work
+2. Run `task check` before committing (lint + test + vet)
+3. If unsure about a convention, check `DECISIONS.md` or ask
+4. Never modify files outside the project root without explicit permission
+5. When adding a dependency, explain why in the commit message
+6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM

.gitea/workflows/cd.yml

@@ -95,6 +95,7 @@ jobs:
     needs: build
     runs-on: self-hosted
     if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    environment: staging
     steps:
       - name: Update image tag in infra repo
         env:

.skills/go-patterns/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: go-patterns
+description: Go project patterns — endpoint checklist, error handling, HTMX responses, dependency policy. Use when writing Go code, adding endpoints, or reviewing Go PRs.
+---
+
+# Go project patterns
+
+## New endpoint checklist
+1. Define request/response types in `types.go`
+2. Write handler in `handlers.go` using `http.HandlerFunc`
+3. Add route in `routes.go`
+4. Write table-driven test in `handlers_test.go`
+5. Run `task check` before committing
+
+## Error handling pattern
+```go
+if err != nil {
+    return fmt.Errorf("descriptiveOperation: %w", err)
+}
+```
+Never log and return — do one or the other.
+
+## HTMX response pattern
+```go
+func (h *Handler) ListItems(w http.ResponseWriter, r *http.Request) {
+    items, err := h.store.List(r.Context())
+    if err != nil {
+        http.Error(w, "failed to list items", http.StatusInternalServerError)
+        return
+    }
+    if r.Header.Get("HX-Request") == "true" {
+        h.templates.Render(w, "items/_list", items)
+        return
+    }
+    h.templates.Render(w, "items/index", items)
+}
+```
+
+## Dependency policy
+- Prefer stdlib: `net/http`, `encoding/json`, `database/sql`
+- Allowed without justification: `testify`, `slog`, `templ`, `sqlc`
+- Needs justification in commit message: anything else

.skills/htmx-patterns/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: htmx-patterns
+description: HTMX conventions — default attributes, form patterns, validation errors, hypermedia-first API design. Use when writing HTMX templates or Go handlers that return HTML fragments.
+---
+
+# HTMX patterns
+
+## Default attributes
+Always include on interactive elements:
+- `hx-indicator` for loading states
+- `hx-swap="innerHTML"` as default (explicit over implicit)
+- `hx-target` pointing to a specific ID, never `this` in production
+
+## Form pattern
+```html
+<form hx-post="/items" hx-target="#item-list" hx-swap="beforeend" hx-indicator="#spinner">
+  <input type="text" name="title" required>
+  <button type="submit">Add</button>
+  <span id="spinner" class="htmx-indicator">...</span>
+</form>
+```
+
+## Server-sent validation errors
+Return 422 with the error fragment, swap into the form's error container:
+```html
+hx-target-422="#form-errors"
+```
+
+## Prefer hypermedia over JSON
+If the endpoint returns data for display, return an HTML fragment.
+Only use JSON for machine-to-machine APIs or when a non-browser client needs it.

AGENTS.md

@@ -0,0 +1,250 @@
+# Agent context — Mathias workspace
+
+<!-- Canonical root context for all AI coding agents.
+     Lives at: ~/dev/.context/AGENT.md
+     Applies to every project under ~/dev/ unless overridden.
+     
+     Run `task context:sync` from ~/dev/ to regenerate harness-specific files.
+     Project-level context in .context/PROJECT.md layers on top of this. -->
+
+## Who I am
+
+I'm Mathias, a digital product manager and technology consultant based in Sweden.
+I build software, research emerging tech, and deliver consulting engagements
+for clients under NDA. I work across AI/ML, financial automation, web applications,
+and climate/sustainability tech.
+
+## How I work with agents
+
+- I think like a product manager — I care about *why* before *how*
+- I want agents to be opinionated and push back, not just execute blindly
+- I prefer concise responses; skip ceremony and get to the point
+- When I say "build this", I mean production-quality with tests, not a demo
+- Ask me before making irreversible changes or adding heavy dependencies
+- I work with confidential client data — never send it to cloud APIs unless I explicitly say it's OK
+
+## Behavior rules
+
+These rules apply to every task across every project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Default stack
+
+| Layer | Default | Fallback | Last resort |
+|-------|---------|----------|-------------|
+| Language | Go | Python | TypeScript, Java, C |
+| UI | HTMX + Templ | Server-rendered HTML | React (only if SPA is justified) |
+| Build | Task (taskfile.dev) | Make | — |
+| Containers | Docker Compose (dev), k3s (prod) | — | — |
+| DB | PostgreSQL + sqlc | SQLite | — |
+| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — |
+| Logging | slog (structured) | — | — |
+| Testing | Table-driven, testify | — | — |
+
+Exploratory: Rust, Zig — I'll tell you when I want these.
+
+## Code conventions
+
+- **Go style**: golines, gofumpt, golangci-lint
+- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
+- **Naming**: stdlib conventions, no stuttering
+- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
+- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), one concern per PR, PR describes *why* not *what*
+- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
+- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc are pre-approved; anything else needs justification in the commit message
+
+## Infrastructure
+
+Three machines on Tailscale:
+
+| Machine | Role | Key specs |
+|---------|------|-----------|
+| koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
+| iguana | Services, builds | M2 Ultra Mac |
+| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
+
+- **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
+- **Orchestration**: k3s cluster across all three machines
+- **Networking**: Tailscale mesh
+
+## Project landscape
+
+All development repos live at `~/dev/` (softlink from `~/Documents/local-dev/`).
+
+Organized in thematic folders:
+
+| Folder | Focus | Count |
+|--------|-------|-------|
+| `GO/` | Go web frameworks, API integrations, learning projects | ~10 |
+| `AI/` | ML research, AI frameworks (FinRL, DSPy, crawl4ai) | ~6 |
+| `AGENTS/` | Autonomous agents, coding agents, MCP servers, infra | ~15 |
+| `QKX/` | Invoice processing, financial automation, payment systems | ~13 |
+| `XT/` | Climate data, sustainability (Klimatkollen, Garbo) | ~2 |
+
+See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
+
+### Key active projects
+
+- **super-koala** (`AGENTS/`) — multi-component agent stack with LangGraph, DSPy, MCP
+- **azure-tiger** (`QKX/`) — invoice extraction → ISO 20022 payment instructions
+- **gocrwl** (`AGENTS/`) — Go web crawler with containerized deployment
+- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
+- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
+
+## Knowledge base
+
+When available, agents can query the shared knowledge base:
+
+- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
+- **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
+
+<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
+     name once hyperguild is deployed. Until then, agents that try to
+     reach the knowledge service on a host where it isn't running will
+     get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
+- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
+
+## Client work rules
+
+When working on a project tagged with a client name:
+1. Never send code, data, or context to cloud APIs — use local models only
+2. Never reference other client projects or their data
+3. Keep all artifacts within the client's git org / directory
+4. Treat everything as confidential unless told otherwise
+
+## Harness-agnostic principles
+
+This context is designed to work with any AI coding tool:
+- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
+- Pi Coding Agent, Mistral Vibe, Antigravity
+- Any tool that accepts a system prompt or reads a markdown context file
+
+The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
+Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
+
+## How context propagates
+
+Canonical sources of truth:
+- Universal: `~/dev/.context/AGENT.md` (this file)
+- Project: `<repo>/.context/PROJECT.md` (per-repo)
+
+Derived files (committed, regenerated by `task context:sync`):
+- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
+  `.context/system-prompt.txt`
+
+Workflow:
+1. Edit a canonical file. Run `task context:sync`. Commit canonical and
+   derived together. Push.
+2. On any other host, `git pull` brings both. Claude Code (tree-walking)
+   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
+   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
+3. `task check` runs `context:sync` then asserts `git status --porcelain`
+   is empty over the derived files (catches both modified-tracked drift
+   and missing-untracked adapters). A drift fails the check with a
+   message telling you to stage the regenerated files.
+
+Behavior rules in this file and per-project rules in `PROJECT.md` apply
+unconditionally on every host, every harness.
+
+## Engineering Skills
+
+Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+
+See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+
+Key skills:
+- **TDD**: always write tests first — load `tdd` skill
+- **Code Review**: load `code-review` skill before any review
+- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
+- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+
+---
+
+# Project context
+
+<!-- Canonical project context. Edit this, run `task context:sync`.
+     Root agent context from ~/dev/.context/AGENT.md is automatically
+     prepended for harnesses that don't walk the directory tree. -->
+
+## Identity
+
+- **Name**: gitea-mcp
+- **Owner**: Mathias
+- **Client**: personal
+- **Repo**: https://gitea.d-ma.be/mathias/gitea-mcp
+- **Status**: active
+
+## Stack
+
+- **Primary language**: Go
+- **UI layer**: HTMX + Templ (when applicable)
+- **Fallback languages**: Python, TypeScript (justify in PR if used)
+- **Build**: Task (taskfile.dev), not Make
+- **Containers**: Docker (compose for dev, k3s for deploy)
+- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
+
+## Conventions
+
+### Code style
+- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
+- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
+- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
+- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
+
+### Architecture preferences
+- Prefer standard library over frameworks (net/http over gin/echo)
+- Dependency injection via constructor functions, not containers
+- Configuration via environment variables, parsed at startup into a typed struct
+- Structured logging via `slog`
+
+### Git
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
+- Branch naming: `feat/short-description`, `fix/short-description`
+- PRs: one concern per PR, description explains *why* not *what*
+
+### Security
+- No secrets in code, ever — use env vars or SOPS-encrypted files
+- Client data never leaves local network unless explicitly cleared
+- Dependencies: audit with `govulncheck` before adding
+
+## Knowledge base access
+
+This project can query the shared knowledge base via MCP or HTTP:
+
+- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+- **Scoping**: queries are filtered to collection `personal` + `public`
+
+## Behavior rules
+
+These rules apply to every task in this project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Agent instructions
+
+When acting as a coding agent on this project:
+
+1. Read this file and all `SKILL.md` files in `.skills/` before starting work
+2. Run `task check` before committing (lint + test + vet)
+3. If unsure about a convention, check `DECISIONS.md` or ask
+4. Never modify files outside the project root without explicit permission
+5. When adding a dependency, explain why in the commit message
+6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM

CLAUDE.md

@@ -0,0 +1,79 @@
+# Project context
+
+<!-- Canonical project context. Edit this, run `task context:sync`.
+     Root agent context from ~/dev/.context/AGENT.md is automatically
+     prepended for harnesses that don't walk the directory tree. -->
+
+## Identity
+
+- **Name**: gitea-mcp
+- **Owner**: Mathias
+- **Client**: personal
+- **Repo**: https://gitea.d-ma.be/mathias/gitea-mcp
+- **Status**: active
+
+## Stack
+
+- **Primary language**: Go
+- **UI layer**: HTMX + Templ (when applicable)
+- **Fallback languages**: Python, TypeScript (justify in PR if used)
+- **Build**: Task (taskfile.dev), not Make
+- **Containers**: Docker (compose for dev, k3s for deploy)
+- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
+
+## Conventions
+
+### Code style
+- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
+- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
+- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
+- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
+
+### Architecture preferences
+- Prefer standard library over frameworks (net/http over gin/echo)
+- Dependency injection via constructor functions, not containers
+- Configuration via environment variables, parsed at startup into a typed struct
+- Structured logging via `slog`
+
+### Git
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
+- Branch naming: `feat/short-description`, `fix/short-description`
+- PRs: one concern per PR, description explains *why* not *what*
+
+### Security
+- No secrets in code, ever — use env vars or SOPS-encrypted files
+- Client data never leaves local network unless explicitly cleared
+- Dependencies: audit with `govulncheck` before adding
+
+## Knowledge base access
+
+This project can query the shared knowledge base via MCP or HTTP:
+
+- **MCP endpoint**: `mcp://localhost:3100/knowledge`
+- **HTTP fallback**: `http://localhost:3100/api/v1/search`
+- **Scoping**: queries are filtered to collection `personal` + `public`
+
+## Behavior rules
+
+These rules apply to every task in this project, regardless of harness.
+
+1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
+   Think before coding; if the problem is unclear, ask or state assumptions before acting.
+2. **Minimum viable code.** Solve with the smallest change that works. Nothing
+   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
+3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
+   files, and formatting alone. Diffs should be small and reviewable.
+4. **Goal-driven execution.** Define clear success criteria up front for every task.
+   Loop — implement, verify, refine — until those criteria are met. Don't claim
+   completion without evidence (tests pass, command output, observed behavior).
+
+## Agent instructions
+
+When acting as a coding agent on this project:
+
+1. Read this file and all `SKILL.md` files in `.skills/` before starting work
+2. Run `task check` before committing (lint + test + vet)
+3. If unsure about a convention, check `DECISIONS.md` or ask
+4. Never modify files outside the project root without explicit permission
+5. When adding a dependency, explain why in the commit message
+6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM

Taskfile.yml

@@ -14,9 +14,42 @@ tasks:
   lint:
     desc: Run golangci-lint
     cmds: [golangci-lint run ./...]
-  check:
-    desc: Lint, vet, and test (used by CI)
+  vet:
     cmds:
-      - golangci-lint run ./...
       - go vet ./...
-      - go test ./... -race -count=1
+      - govulncheck ./... || true
+
+  check:
+    desc: Run all checks (context freshness + lint + test + vet)
+    cmds:
+      - cmd: |
+          if [ -n "${CI:-}" ]; then
+            echo "✓ context sync: skipped in CI"
+          else
+            bash scripts/context-sync.sh
+            drift=$(git status --porcelain -- AGENTS.md CLAUDE.md .cursorrules .aider.conventions.md .context/system-prompt.txt 2>/dev/null)
+            if [ -n "$drift" ]; then
+              echo "ERROR: derived adapters drifted from canonical context." >&2
+              echo "$drift" >&2
+              echo "" >&2
+              echo "Run: git add AGENTS.md CLAUDE.md .cursorrules .aider.conventions.md .context/system-prompt.txt" >&2
+              echo "     git commit -m 'chore: re-sync context adapters'" >&2
+              exit 1
+            fi
+            echo "✓ context: canonical and adapters are in sync"
+          fi
+      - task: lint
+      - task: test
+      - task: vet
+
+  context:sync:
+    desc: Regenerate all harness-specific context files
+    cmds:
+      - bash scripts/context-sync.sh
+
+  context:sync:claude:
+    cmds: [bash scripts/context-sync.sh claude]
+  context:sync:agents:
+    cmds: [bash scripts/context-sync.sh agents]
+  context:sync:cursor:
+    cmds: [bash scripts/context-sync.sh cursor]

cmd/gitea-mcp/main.go

@@ -1,6 +1,8 @@
 package main
 
 import (
+	"context"
+	"encoding/json"
 	"log/slog"
 	"net/http"
 	"os"
@@ -23,25 +25,42 @@ func main() {
 		os.Exit(1)
 	}
 
-	giteaClient := gitea.NewClient(cfg.GiteaBaseURL, cfg.GiteaAPIToken)
+	ctx := context.Background()
+
+	jwtValidator, err := auth.NewJWTValidator(ctx, cfg.DexIssuerURL, cfg.MCPAudience)
+	if err != nil {
+		logger.Warn("jwt validator init failed; JWT auth disabled", "err", err)
+	}
+
+	giteaClient := gitea.NewClient(cfg.GiteaBaseURL, cfg.DefaultToken)
 	ownerAllow := allowlist.New(cfg.AllowedOwners)
 
 	reg := registry.New()
 	reg.Register(tools.NewRepoList(giteaClient, ownerAllow))
 	reg.Register(tools.NewRepoGet(giteaClient, ownerAllow))
+	reg.Register(tools.NewRepoSearch(giteaClient, ownerAllow))
+	reg.Register(tools.NewRepoStatus(giteaClient, ownerAllow))
+	reg.Register(tools.NewRepoUpdate(giteaClient, ownerAllow))
 	reg.Register(tools.NewFileRead(giteaClient, ownerAllow))
 	reg.Register(tools.NewFileWriteBranch(giteaClient, ownerAllow))
+	reg.Register(tools.NewFileDelete(giteaClient, ownerAllow))
+	reg.Register(tools.NewDirList(giteaClient, ownerAllow))
+	reg.Register(tools.NewBranchList(giteaClient, ownerAllow))
+	reg.Register(tools.NewBranchDelete(giteaClient, ownerAllow))
+	reg.Register(tools.NewBranchProtectionGet(giteaClient, ownerAllow))
 	reg.Register(tools.NewPRCreate(giteaClient, ownerAllow))
 	reg.Register(tools.NewPRGet(giteaClient, ownerAllow))
+	reg.Register(tools.NewPRList(giteaClient, ownerAllow))
+	reg.Register(tools.NewPRMerge(giteaClient, ownerAllow))
+	reg.Register(tools.NewPRComment(giteaClient, ownerAllow))
+	reg.Register(tools.NewPRFilesDiff(giteaClient, ownerAllow))
 	reg.Register(tools.NewWorkflowRunTrigger(giteaClient, ownerAllow, cfg.GiteaBaseURL))
 	reg.Register(tools.NewWorkflowRunStatus(giteaClient, ownerAllow))
-	reg.Register(tools.NewRepoSearch(giteaClient, ownerAllow))
 	reg.Register(tools.NewCodeSearch(giteaClient, ownerAllow))
 	reg.Register(tools.NewIssueCreate(giteaClient, ownerAllow))
 	reg.Register(tools.NewIssueComment(giteaClient, ownerAllow))
-	reg.Register(tools.NewPRComment(giteaClient, ownerAllow))
-	reg.Register(tools.NewPRFilesDiff(giteaClient, ownerAllow))
 	reg.Register(tools.NewCreateProjectFromTemplate(giteaClient, ownerAllow, "mathias", "template-go-web"))
+	reg.Register(tools.NewTagCreate(giteaClient, ownerAllow))
 
 	mcpSrv := mcp.NewServer(mcp.ServerOptions{
 		Registry: reg,
@@ -49,11 +68,30 @@ func main() {
 	})
 
 	mux := http.NewServeMux()
-	mux.Handle("/mcp", mcp.OriginAllowlist(cfg.OriginAllowlist)(auth.CallerMiddleware(mcpSrv)))
+	mux.Handle("/mcp", mcp.OriginAllowlist(cfg.OriginAllowlist)(
+		auth.BearerMiddleware(jwtValidator, cfg.StaticToken,
+			auth.CallerMiddleware(mcpSrv),
+		),
+	))
 	mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
 		w.WriteHeader(http.StatusOK)
 		_, _ = w.Write([]byte("ok"))
 	})
+	mux.HandleFunc("/.well-known/oauth-protected-resource", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		payload := map[string]any{
+			"resource":             cfg.MCPResourceURL,
+			"authorization_servers": []string{},
+		}
+		if cfg.DexIssuerURL != "" {
+			payload["authorization_servers"] = []string{cfg.DexIssuerURL}
+		}
+		_ = json.NewEncoder(w).Encode(payload)
+	})
 
 	addr := ":" + cfg.Port
 	logger.Info("gitea-mcp starting", "addr", addr, "version", "0.1.0")

docs/superpowers/specs/2026-05-06-gitops-agent-tools-design.md

@@ -0,0 +1,169 @@
+# GitOps Agent Tools — Design Spec
+
+**Date:** 2026-05-06
+**Status:** Approved
+
+## Goal
+
+Extend the Gitea MCP server with the tools an AI agent needs to drive a full GitOps development loop autonomously — reading repo state, deciding on a branching strategy, making changes, opening and merging PRs, and tagging releases — without any local git tooling.
+
+The agent selects between feature-branch and trunk-based development based on branch protection rules it reads at runtime.
+
+---
+
+## New Tools (9)
+
+All tools follow the existing pattern: one file in `internal/tools/`, one Gitea client method in `internal/gitea/`, allowlist check on `owner`, table-driven tests in both packages.
+
+### `repo_status`
+
+Convenience read tool — returns branch list, open PRs, and protection info for a target branch in a single call. Designed for the agent's first query on any repo so it can decide its strategy.
+
+**Inputs:** `owner`, `name`, `branch` (optional — defaults to repo default branch)
+**Output:** `{ branches: [...], open_prs: [...], protection: { protected, required_approvals, push_whitelist, merge_whitelist } }`
+**Implementation:** calls `ListBranches` + `ListPullRequests(state=open)` + `GetBranchProtection` internally, composes result. No new Gitea API surface.
+
+---
+
+### `branch_list`
+
+**Inputs:** `owner`, `name`, `page` (optional), `limit` (optional, default 30)
+**Output:** array of `{ name, sha }`
+**Gitea endpoint:** `GET /api/v1/repos/{owner}/{repo}/branches`
+
+---
+
+### `branch_delete`
+
+**Inputs:** `owner`, `name`, `branch`
+**Output:** confirmation message
+**Gitea endpoint:** `DELETE /api/v1/repos/{owner}/{repo}/branches/{branch}`
+**Error handling:** 403 from Gitea (protected branch) surfaced as a descriptive error.
+
+---
+
+### `branch_protection_get`
+
+**Inputs:** `owner`, `name`, `branch`
+**Output:** `{ protected, required_approvals, push_whitelist, merge_whitelist }`
+**Gitea endpoint:** `GET /api/v1/repos/{owner}/{repo}/branch_protections/{branch}`
+**Error handling:** 404 → return `{ protected: false }`, not an error. Allows agent to make clean boolean decisions.
+
+---
+
+### `pr_list`
+
+**Inputs:** `owner`, `name`, `state` (`open`/`closed`/`all`, default `open`), `head` (optional branch filter), `page`, `limit`
+**Output:** array of `{ number, title, state, head_branch, base_branch, draft, html_url }`
+**Gitea endpoint:** `GET /api/v1/repos/{owner}/{repo}/pulls`
+
+---
+
+### `pr_merge`
+
+**Inputs:** `owner`, `name`, `index`, `style` (`merge`/`squash`/`rebase`, default `merge`), `merge_message_title` (optional), `merge_message_field` (optional)
+**Output:** `{ merged: true, commit_sha }` — if Gitea returns 204 No Content (some merge styles), output is `{ merged: true }` without `commit_sha`.
+**Gitea endpoint:** `POST /api/v1/repos/{owner}/{repo}/pulls/{index}/merge`
+**Error handling:** 405 (checks failing) and 409 (merge conflict) passed through with the Gitea error message intact so the agent understands why it failed.
+
+---
+
+### `dir_list`
+
+**Inputs:** `owner`, `name`, `path` (empty string = repo root), `ref` (optional branch/tag/SHA)
+**Output:** array of `{ name, path, type (file|dir|symlink), sha, size }`
+**Gitea endpoint:** `GET /api/v1/repos/{owner}/{repo}/contents/{path}`
+**Note:** same endpoint as `file_read` but returns an array when `path` is a directory. Client detects response shape (array vs object). If called on a file path, returns a descriptive error: `"path is a file, not a directory — use file_read"`.
+
+---
+
+### `file_delete`
+
+**Inputs:** `owner`, `name`, `path`, `branch`, `message`, `sha` (required — current blob SHA)
+**Output:** `{ commit_sha, html_url }`
+**Gitea endpoint:** `DELETE /api/v1/repos/{owner}/{repo}/contents/{path}`
+
+---
+
+### `tag_create`
+
+**Inputs:** `owner`, `name`, `tag` (tag name), `target` (branch name or commit SHA), `message` (optional — creates annotated tag if set)
+**Output:** `{ tag, commit_sha, html_url }`
+**Gitea endpoint:** `POST /api/v1/repos/{owner}/{repo}/tags`
+
+---
+
+## Gitea Client Methods
+
+New methods on `gitea.Client`:
+
+| Method | Endpoint | HTTP verb |
+|--------|----------|-----------|
+| `ListBranches(ctx, owner, repo, page, limit)` | `/api/v1/repos/{owner}/{repo}/branches` | GET |
+| `DeleteBranch(ctx, owner, repo, branch)` | `/api/v1/repos/{owner}/{repo}/branches/{branch}` | DELETE |
+| `GetBranchProtection(ctx, owner, repo, branch)` | `/api/v1/repos/{owner}/{repo}/branch_protections/{branch}` | GET |
+| `ListPullRequests(ctx, owner, repo, state, head, page, limit)` | `/api/v1/repos/{owner}/{repo}/pulls` | GET |
+| `MergePullRequest(ctx, owner, repo, index, args)` | `/api/v1/repos/{owner}/{repo}/pulls/{index}/merge` | POST |
+| `ListContents(ctx, owner, repo, path, ref)` | `/api/v1/repos/{owner}/{repo}/contents/{path}` | GET |
+| `DeleteFile(ctx, owner, repo, path, args)` | `/api/v1/repos/{owner}/{repo}/contents/{path}` | DELETE |
+| `CreateTag(ctx, owner, repo, args)` | `/api/v1/repos/{owner}/{repo}/tags` | POST |
+
+---
+
+## Architecture
+
+No structural changes. Each new tool is:
+- One file: `internal/tools/<tool_name>.go` + `internal/tools/<tool_name>_test.go`
+- One client method: `internal/gitea/<domain>.go` (added to existing domain files where logical)
+- Registered in `cmd/gitea-mcp/main.go`
+
+`repo_status` is the only tool with internal composition — it calls three client methods and merges their results. It has no dedicated client method of its own.
+
+New client methods go in existing domain files:
+- Branch methods → `internal/gitea/files.go` (already has `BranchExists`, `CreateBranch`)
+- PR methods → `internal/gitea/pulls.go`
+- Contents (dir_list, file_delete) → `internal/gitea/files.go`
+- Tags → new `internal/gitea/tags.go`
+
+---
+
+## Testing
+
+Pattern: table-driven tests with a `httptest.NewServer` mock, same as `file_write_branch_test.go`.
+
+Each tool covers:
+- Happy path
+- 404 response
+- Allowlist rejection
+- Tool-specific edge cases:
+  - `branch_delete`: 403 protected branch
+  - `branch_protection_get`: 404 → `{protected: false}` not error
+  - `dir_list`: file path → descriptive error
+  - `pr_merge`: 405 checks failing, 409 merge conflict
+  - `repo_status`: any one sub-call failing propagates the error
+
+---
+
+## Agent Decision Flow (Reference)
+
+```
+1. repo_status(owner, name)
+   → if branch.protected && required_approvals > 0:
+       use feature-branch workflow
+   → else:
+       use trunk-based workflow
+
+Feature-branch workflow:
+  file_write_branch (auto-creates branch)
+  → pr_create
+  → [wait for CI via workflow_run_status]
+  → pr_merge
+  → branch_delete
+
+Trunk-based workflow:
+  file_write_branch(branch=main)
+  → [optionally] tag_create
+
+Post-merge (either):
+  → [optionally] tag_create to trigger deployment
+```

go.mod

@@ -2,10 +2,24 @@ module gitea.d-ma.be/mathias/gitea-mcp
 
 go 1.26.2
 
+require (
+	github.com/hashicorp/golang-lru/v2 v2.0.7
+	github.com/lestrrat-go/jwx/v2 v2.1.6
+	github.com/stretchr/testify v1.11.1
+)
+
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
+	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 // indirect
+	github.com/goccy/go-json v0.10.3 // indirect
+	github.com/lestrrat-go/blackmagic v1.0.3 // indirect
+	github.com/lestrrat-go/httpcc v1.0.1 // indirect
+	github.com/lestrrat-go/httprc v1.0.6 // indirect
+	github.com/lestrrat-go/iter v1.0.2 // indirect
+	github.com/lestrrat-go/option v1.0.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/stretchr/testify v1.11.1 // indirect
+	github.com/segmentio/asm v1.2.0 // indirect
+	golang.org/x/crypto v0.32.0 // indirect
+	golang.org/x/sys v0.31.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,11 +1,39 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 h1:NMZiJj8QnKe1LgsbDayM4UoHwbvwDRwnI3hwNaAHRnc=
+github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
+github.com/goccy/go-json v0.10.3 h1:KZ5WoDbxAIgm2HNbYckL0se1fHD6rz5j4ywS6ebzDqA=
+github.com/goccy/go-json v0.10.3/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/lestrrat-go/blackmagic v1.0.3 h1:94HXkVLxkZO9vJI/w2u1T0DAoprShFd13xtnSINtDWs=
+github.com/lestrrat-go/blackmagic v1.0.3/go.mod h1:6AWFyKNNj0zEXQYfTMPfZrAXUWUfTIZ5ECEUEJaijtw=
+github.com/lestrrat-go/httpcc v1.0.1 h1:ydWCStUeJLkpYyjLDHihupbn2tYmZ7m22BGkcvZZrIE=
+github.com/lestrrat-go/httpcc v1.0.1/go.mod h1:qiltp3Mt56+55GPVCbTdM9MlqhvzyuL6W/NMDA8vA5E=
+github.com/lestrrat-go/httprc v1.0.6 h1:qgmgIRhpvBqexMJjA/PmwSvhNk679oqD1RbovdCGW8k=
+github.com/lestrrat-go/httprc v1.0.6/go.mod h1:mwwz3JMTPBjHUkkDv/IGJ39aALInZLrhBp0X7KGUZlo=
+github.com/lestrrat-go/iter v1.0.2 h1:gMXo1q4c2pHmC3dn8LzRhJfP1ceCbgSiT9lUydIzltI=
+github.com/lestrrat-go/iter v1.0.2/go.mod h1:Momfcq3AnRlRjI5b5O8/G5/BvpzrhoFTZcn06fEOPt4=
+github.com/lestrrat-go/jwx/v2 v2.1.6 h1:hxM1gfDILk/l5ylers6BX/Eq1m/pnxe9NBwW6lVfecA=
+github.com/lestrrat-go/jwx/v2 v2.1.6/go.mod h1:Y722kU5r/8mV7fYDifjug0r8FK8mZdw0K0GpJw/l8pU=
+github.com/lestrrat-go/option v1.0.1 h1:oAzP2fvZGQKWkvHa1/SAcFolBEca1oN+mQ7eooNBEYU=
+github.com/lestrrat-go/option v1.0.1/go.mod h1:5ZHFbivi4xwXxhxY9XHDe2FHo6/Z7WWmtT7T5nBBp3I=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/segmentio/asm v1.2.0 h1:9BQrFxC+YOHJlTlHGkTrFWf59nbL3XnCoFLTwDCI7ys=
+github.com/segmentio/asm v1.2.0/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+golang.org/x/crypto v0.32.0 h1:euUpcYgM8WcP71gNpTqQCn6rC2t6ULUPiOzfWaXVVfc=
+golang.org/x/crypto v0.32.0/go.mod h1:ZnnJkOaASj8g0AjIduWNlq2NRxL0PlBrbKVyZ6V/Ugc=
+golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
+golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/auth/bearer.go

@@ -0,0 +1,42 @@
+package auth
+
+import (
+	"crypto/subtle"
+	"net/http"
+	"strings"
+)
+
+// BearerMiddleware authenticates requests via the Authorization header.
+//
+// A request is allowed when:
+//
+//  1. The Bearer token is a valid JWT issued by the configured Dex OIDC server, or
+//  2. The Bearer token matches staticToken (constant-time compare).
+//
+// Any other case — including missing or empty Authorization header — returns 401.
+//
+// The Gitea service PAT is intentionally NOT used to authenticate the caller:
+// it is only used by the Gitea client for upstream API calls. Decoupling the
+// two prevents the MCP endpoint from being reachable anonymously when a service
+// PAT happens to be configured.
+func BearerMiddleware(jwtValidator *JWTValidator, staticToken string, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		bearer, hasBearer := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
+		if !hasBearer || bearer == "" {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+
+		if jwtValidator.Validate(r.Context(), bearer) {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		if staticToken != "" && subtle.ConstantTimeCompare([]byte(bearer), []byte(staticToken)) == 1 {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		http.Error(w, "unauthorized", http.StatusUnauthorized)
+	})
+}

internal/auth/bearer_test.go

@@ -0,0 +1,92 @@
+package auth_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/auth"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func okHandler(called *bool) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		if called != nil {
+			*called = true
+		}
+		w.WriteHeader(http.StatusOK)
+	})
+}
+
+func TestBearerMiddleware_NoAuthHeader(t *testing.T) {
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, "", okHandler(nil)))
+	defer srv.Close()
+
+	resp, err := http.Post(srv.URL+"/mcp", "application/json", nil)
+	require.NoError(t, err)
+	defer func() { _ = resp.Body.Close() }()
+	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+}
+
+func TestBearerMiddleware_NoAuthHeader_RejectsEvenWhenStaticConfigured(t *testing.T) {
+	// A configured staticToken must not allow unauthenticated callers through.
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, "any-static", okHandler(nil)))
+	defer srv.Close()
+
+	resp, err := http.Post(srv.URL+"/mcp", "application/json", nil)
+	require.NoError(t, err)
+	defer func() { _ = resp.Body.Close() }()
+	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+}
+
+func TestBearerMiddleware_EmptyBearer(t *testing.T) {
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, "static", okHandler(nil)))
+	defer srv.Close()
+
+	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/mcp", nil)
+	req.Header.Set("Authorization", "Bearer ")
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer func() { _ = resp.Body.Close() }()
+	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+}
+
+func TestBearerMiddleware_StaticToken_Valid(t *testing.T) {
+	const staticToken = "my-static-token"
+	called := false
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, staticToken, okHandler(&called)))
+	defer srv.Close()
+
+	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/mcp", nil)
+	req.Header.Set("Authorization", "Bearer "+staticToken)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer func() { _ = resp.Body.Close() }()
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+	assert.True(t, called)
+}
+
+func TestBearerMiddleware_StaticToken_Invalid(t *testing.T) {
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, "correct-token", okHandler(nil)))
+	defer srv.Close()
+
+	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/mcp", nil)
+	req.Header.Set("Authorization", "Bearer wrong-token")
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer func() { _ = resp.Body.Close() }()
+	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+}
+
+func TestBearerMiddleware_UnknownBearer_NoStatic_NoJWT(t *testing.T) {
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, "", okHandler(nil)))
+	defer srv.Close()
+
+	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/mcp", nil)
+	req.Header.Set("Authorization", "Bearer random-unknown-token")
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer func() { _ = resp.Body.Close() }()
+	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+}

internal/auth/jwt.go

@@ -0,0 +1,79 @@
+package auth
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/lestrrat-go/jwx/v2/jwk"
+	"github.com/lestrrat-go/jwx/v2/jwt"
+)
+
+// JWTValidator validates bearer tokens as JWTs issued by a Dex OIDC server.
+// A nil JWTValidator always returns false — JWT validation is disabled.
+type JWTValidator struct {
+	issuer  string
+	aud     string
+	cache   *jwk.Cache
+	jwksURI string
+}
+
+// NewJWTValidator creates a validator by fetching the OIDC discovery document
+// from issuerURL. Returns nil, nil when issuerURL is empty (disabled).
+func NewJWTValidator(ctx context.Context, issuerURL, audience string) (*JWTValidator, error) {
+	if issuerURL == "" {
+		return nil, nil
+	}
+
+	resp, err := http.Get(issuerURL + "/.well-known/openid-configuration")
+	if err != nil {
+		return nil, fmt.Errorf("fetch oidc discovery: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	var doc struct {
+		JWKSURI string `json:"jwks_uri"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&doc); err != nil {
+		return nil, fmt.Errorf("decode oidc discovery: %w", err)
+	}
+
+	cache := jwk.NewCache(ctx)
+	if err := cache.Register(doc.JWKSURI, jwk.WithRefreshInterval(time.Hour)); err != nil {
+		return nil, fmt.Errorf("register jwks uri: %w", err)
+	}
+	// warm the cache immediately so first request doesn't block
+	if _, err := cache.Refresh(ctx, doc.JWKSURI); err != nil {
+		return nil, fmt.Errorf("warm jwks cache: %w", err)
+	}
+
+	return &JWTValidator{
+		issuer:  issuerURL,
+		aud:     audience,
+		cache:   cache,
+		jwksURI: doc.JWKSURI,
+	}, nil
+}
+
+// Validate returns true if rawToken is a valid JWT signed by the OIDC server.
+func (v *JWTValidator) Validate(ctx context.Context, rawToken string) bool {
+	if v == nil {
+		return false
+	}
+	keySet, err := v.cache.Get(ctx, v.jwksURI)
+	if err != nil {
+		return false
+	}
+	opts := []jwt.ParseOption{
+		jwt.WithKeySet(keySet),
+		jwt.WithIssuer(v.issuer),
+		jwt.WithValidate(true),
+	}
+	if v.aud != "" {
+		opts = append(opts, jwt.WithAudience(v.aud))
+	}
+	_, err = jwt.Parse([]byte(rawToken), opts...)
+	return err == nil
+}

internal/config/config.go

@@ -8,18 +8,26 @@ import (
 type Config struct {
 	Port            string   // GITEA_MCP_PORT, default 8080
 	GiteaBaseURL    string   // GITEA_BASE_URL, e.g. https://gitea.d-ma.be
-	GiteaAPIToken   string   // GITEA_API_TOKEN — bot user token
+	DefaultToken    string   // GITEA_MCP_DEFAULT_TOKEN, service PAT; used by Gitea client for all upstream calls
+	StaticToken     string   // GITEA_MCP_STATIC_TOKEN, optional static bearer for service-to-service auth
 	AllowedOwners   []string // GITEA_MCP_ALLOWED_OWNERS, comma-separated, default "mathias"
 	OriginAllowlist []string // GITEA_MCP_ORIGIN_ALLOWLIST, comma-separated
+	DexIssuerURL    string   // DEX_ISSUER_URL, e.g. https://auth.d-ma.be; empty disables JWT auth
+	MCPAudience     string   // MCP_AUDIENCE, JWT audience claim to validate, e.g. claude-ai
+	MCPResourceURL  string   // MCP_RESOURCE_URL, this server's public URL for /.well-known metadata
 }
 
 func Load() (Config, error) {
 	cfg := Config{
 		Port:            envOr("GITEA_MCP_PORT", "8080"),
 		GiteaBaseURL:    os.Getenv("GITEA_BASE_URL"),
-		GiteaAPIToken:   os.Getenv("GITEA_API_TOKEN"),
+		DefaultToken:    os.Getenv("GITEA_MCP_DEFAULT_TOKEN"),
+		StaticToken:     os.Getenv("GITEA_MCP_STATIC_TOKEN"),
 		AllowedOwners:   splitCSV(envOr("GITEA_MCP_ALLOWED_OWNERS", "mathias")),
 		OriginAllowlist: splitCSV(os.Getenv("GITEA_MCP_ORIGIN_ALLOWLIST")),
+		DexIssuerURL:    os.Getenv("DEX_ISSUER_URL"),
+		MCPAudience:     os.Getenv("MCP_AUDIENCE"),
+		MCPResourceURL:  os.Getenv("MCP_RESOURCE_URL"),
 	}
 	return cfg, nil
 }

internal/config/config_test.go

@@ -10,7 +10,6 @@ import (
 
 func TestLoadDefaults(t *testing.T) {
 	t.Setenv("GITEA_BASE_URL", "")
-	t.Setenv("GITEA_API_TOKEN", "")
 	t.Setenv("GITEA_MCP_ALLOWED_OWNERS", "")
 	t.Setenv("GITEA_MCP_ORIGIN_ALLOWLIST", "")
 	t.Setenv("GITEA_MCP_PORT", "")
@@ -23,7 +22,6 @@ func TestLoadDefaults(t *testing.T) {
 
 func TestLoadFromEnv(t *testing.T) {
 	t.Setenv("GITEA_BASE_URL", "https://gitea.d-ma.be")
-	t.Setenv("GITEA_API_TOKEN", "test-token")
 	t.Setenv("GITEA_MCP_ALLOWED_OWNERS", "mathias,acme")
 	t.Setenv("GITEA_MCP_ORIGIN_ALLOWLIST", "https://claude.ai,https://api.anthropic.com")
 	t.Setenv("GITEA_MCP_PORT", "9000")
@@ -31,7 +29,6 @@ func TestLoadFromEnv(t *testing.T) {
 	cfg, err := config.Load()
 	require.NoError(t, err)
 	assert.Equal(t, "https://gitea.d-ma.be", cfg.GiteaBaseURL)
-	assert.Equal(t, "test-token", cfg.GiteaAPIToken)
 	assert.Equal(t, []string{"mathias", "acme"}, cfg.AllowedOwners)
 	assert.Equal(t, []string{"https://claude.ai", "https://api.anthropic.com"}, cfg.OriginAllowlist)
 	assert.Equal(t, "9000", cfg.Port)

internal/gitea/client.go

@@ -49,8 +49,9 @@ func (c *Client) doOnce(ctx context.Context, method, path string, body []byte) (
 	if err != nil {
 		return nil, 0, err
 	}
-	if c.token != "" {
-		req.Header.Set("Authorization", "token "+c.token)
+	token := c.token
+	if token != "" {
+		req.Header.Set("Authorization", "token "+token)
 	}
 	if body != nil {
 		req.Header.Set("Content-Type", "application/json")
@@ -95,6 +96,10 @@ func (c *Client) DeleteJSON(ctx context.Context, path string) ([]byte, int, erro
 	return c.do(ctx, http.MethodDelete, path, nil)
 }
 
+func (c *Client) DeleteJSONBody(ctx context.Context, path string, body []byte) ([]byte, int, error) {
+	return c.do(ctx, http.MethodDelete, path, body)
+}
+
 type rawResponse struct {
 	Body    []byte
 	Status  int
@@ -110,8 +115,9 @@ func (c *Client) doRaw(ctx context.Context, method, path string, body []byte) (*
 	if err != nil {
 		return nil, err
 	}
-	if c.token != "" {
-		req.Header.Set("Authorization", "token "+c.token)
+	token := c.token
+	if token != "" {
+		req.Header.Set("Authorization", "token "+token)
 	}
 	if body != nil {
 		req.Header.Set("Content-Type", "application/json")

internal/gitea/files.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/url"
 )
 
 type FileContents struct {
@@ -92,13 +93,138 @@ type FileWriteResult struct {
 	} `json:"commit"`
 }
 
-func (c *Client) UpsertFile(ctx context.Context, owner, repo, path string, args UpsertFileArgs) (*FileWriteResult, error) {
+func (c *Client) ListBranches(ctx context.Context, owner, repo string, page, limit int) ([]Branch, error) {
+	if page < 1 {
+		page = 1
+	}
+	if limit < 1 {
+		limit = 30
+	}
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/branches?page=%d&limit=%d", owner, repo, page, limit)
+	body, status, err := c.GetJSON(ctx, p)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, body); err != nil {
+		return nil, err
+	}
+	var branches []Branch
+	if err := json.Unmarshal(body, &branches); err != nil {
+		return nil, err
+	}
+	return branches, nil
+}
+
+func (c *Client) DeleteBranch(ctx context.Context, owner, repo, branch string) error {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/branches/%s", owner, repo, branch)
+	body, status, err := c.DeleteJSON(ctx, p)
+	if err != nil {
+		return err
+	}
+	return MapStatus(status, body)
+}
+
+type BranchProtection struct {
+	Protected         bool     `json:"-"`
+	RequiredApprovals int64    `json:"required_approvals"`
+	PushWhitelist     []string `json:"push_whitelist_usernames"`
+	MergeWhitelist    []string `json:"merge_whitelist_usernames"`
+}
+
+func (c *Client) GetBranchProtection(ctx context.Context, owner, repo, branch string) (*BranchProtection, error) {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/branch_protections/%s", owner, repo, branch)
+	body, status, err := c.GetJSON(ctx, p)
+	if err != nil {
+		return nil, err
+	}
+	if status == 404 {
+		return &BranchProtection{Protected: false}, nil
+	}
+	if err := MapStatus(status, body); err != nil {
+		return nil, err
+	}
+	var bp BranchProtection
+	if err := json.Unmarshal(body, &bp); err != nil {
+		return nil, err
+	}
+	bp.Protected = true
+	return &bp, nil
+}
+
+type DirEntry struct {
+	Name string `json:"name"`
+	Path string `json:"path"`
+	Type string `json:"type"`
+	Sha  string `json:"sha"`
+	Size int64  `json:"size"`
+}
+
+func (c *Client) ListContents(ctx context.Context, owner, repo, path, ref string) ([]DirEntry, error) {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/contents/%s", owner, repo, path)
+	if ref != "" {
+		p += "?ref=" + url.QueryEscape(ref)
+	}
+	body, status, err := c.GetJSON(ctx, p)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, body); err != nil {
+		return nil, err
+	}
+	if len(body) > 0 && body[0] == '{' {
+		return nil, fmt.Errorf("path is a file, not a directory — use file_read: %w", ErrValidation)
+	}
+	var entries []DirEntry
+	if err := json.Unmarshal(body, &entries); err != nil {
+		return nil, err
+	}
+	return entries, nil
+}
+
+type DeleteFileArgs struct {
+	Branch  string `json:"branch"`
+	Message string `json:"message"`
+	Sha     string `json:"sha"`
+}
+
+func (c *Client) DeleteFile(ctx context.Context, owner, repo, path string, args DeleteFileArgs) (*FileWriteResult, error) {
 	p := fmt.Sprintf("/api/v1/repos/%s/%s/contents/%s", owner, repo, path)
 	payload, err := json.Marshal(args)
 	if err != nil {
 		return nil, err
 	}
-	body, status, err := c.PutJSON(ctx, p, payload)
+	body, status, err := c.DeleteJSONBody(ctx, p, payload)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, body); err != nil {
+		return nil, err
+	}
+	var out FileWriteResult
+	if err := json.Unmarshal(body, &out); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// UpsertFile creates a file when args.Sha is empty (POST) or updates an existing
+// file when args.Sha is set (PUT). Gitea routes both operations by HTTP method on
+// the same /contents/{path} URL, and rejects PUT without a sha.
+func (c *Client) UpsertFile(ctx context.Context, owner, repo, path string, args UpsertFileArgs) (*FileWriteResult, error) {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/contents/%s", owner, repo, path)
+	payload, err := json.Marshal(args)
+	if err != nil {
+		return nil, err
+	}
+	var (
+		body   []byte
+		status int
+	)
+	if args.Sha == "" {
+		body, status, err = c.PostJSON(ctx, p, payload)
+	} else {
+		body, status, err = c.PutJSON(ctx, p, payload)
+	}
 	if err != nil {
 		return nil, err
 	}

internal/gitea/files_test.go

@@ -82,6 +82,28 @@ func TestCreateBranchSendsPayload(t *testing.T) {
 	assert.Equal(t, "main", payload["old_branch_name"])
 }
 
+func TestListBranches(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/branches", r.URL.Path)
+		assert.Equal(t, "1", r.URL.Query().Get("page"))
+		assert.Equal(t, "30", r.URL.Query().Get("limit"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[
+			{"name":"main","commit":{"id":"abc","url":"http://example.com"}},
+			{"name":"feat/x","commit":{"id":"def","url":"http://example.com"}}
+		]`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	branches, err := c.ListBranches(context.Background(), "o", "r", 0, 0)
+	require.NoError(t, err)
+	require.Len(t, branches, 2)
+	assert.Equal(t, "main", branches[0].Name)
+	assert.Equal(t, "abc", branches[0].Commit.ID)
+	assert.Equal(t, "feat/x", branches[1].Name)
+}
+
 func TestUpsertFileSendsPayloadAndDecodesResult(t *testing.T) {
 	var captured []byte
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -116,3 +138,130 @@ func TestUpsertFileSendsPayloadAndDecodesResult(t *testing.T) {
 	assert.Equal(t, "http://example.com/p.md", result.Content.HTMLURL)
 	assert.Equal(t, "abc", result.Commit.Sha)
 }
+
+func TestDeleteBranch(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/branches/feat/x", r.URL.Path)
+		assert.Equal(t, http.MethodDelete, r.Method)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	err := c.DeleteBranch(context.Background(), "o", "r", "feat/x")
+	require.NoError(t, err)
+}
+
+func TestDeleteBranchProtected(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusForbidden)
+		_, _ = w.Write([]byte(`{"message":"branch is protected"}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	err := c.DeleteBranch(context.Background(), "o", "r", "main")
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrPermissionDenied)
+}
+
+func TestGetBranchProtectionFound(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/branch_protections/main", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"required_approvals": 2,
+			"push_whitelist_usernames": ["alice"],
+			"merge_whitelist_usernames": ["bob"]
+		}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	bp, err := c.GetBranchProtection(context.Background(), "o", "r", "main")
+	require.NoError(t, err)
+	assert.True(t, bp.Protected)
+	assert.Equal(t, int64(2), bp.RequiredApprovals)
+	assert.Equal(t, []string{"alice"}, bp.PushWhitelist)
+	assert.Equal(t, []string{"bob"}, bp.MergeWhitelist)
+}
+
+func TestGetBranchProtectionNotFoundReturnsUnprotected(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+		_, _ = w.Write([]byte(`{"message":"not found"}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	bp, err := c.GetBranchProtection(context.Background(), "o", "r", "feat/x")
+	require.NoError(t, err)
+	assert.False(t, bp.Protected)
+}
+
+func TestListContentsDirectory(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/contents/src", r.URL.Path)
+		assert.Equal(t, "main", r.URL.Query().Get("ref"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[
+			{"name":"main.go","path":"src/main.go","type":"file","sha":"abc","size":100},
+			{"name":"lib","path":"src/lib","type":"dir","sha":"def","size":0}
+		]`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	entries, err := c.ListContents(context.Background(), "o", "r", "src", "main")
+	require.NoError(t, err)
+	require.Len(t, entries, 2)
+	assert.Equal(t, "main.go", entries[0].Name)
+	assert.Equal(t, "file", entries[0].Type)
+	assert.Equal(t, "lib", entries[1].Name)
+	assert.Equal(t, "dir", entries[1].Type)
+}
+
+func TestListContentsOnFileReturnsError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"path":"main.go","sha":"abc","size":100,"content":"","encoding":"base64"}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	_, err := c.ListContents(context.Background(), "o", "r", "main.go", "")
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrValidation)
+}
+
+func TestDeleteFile(t *testing.T) {
+	var captured []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/contents/src/old.go", r.URL.Path)
+		assert.Equal(t, http.MethodDelete, r.Method)
+		var err error
+		captured, err = io.ReadAll(r.Body)
+		require.NoError(t, err)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{
+			"content":null,
+			"commit":{"sha":"cmt1","html_url":"http://example.com/commit/cmt1"}
+		}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	result, err := c.DeleteFile(context.Background(), "o", "r", "src/old.go", gitea.DeleteFileArgs{
+		Branch:  "main",
+		Message: "remove old.go",
+		Sha:     "blobsha",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "cmt1", result.Commit.Sha)
+
+	var payload map[string]string
+	require.NoError(t, json.Unmarshal(captured, &payload))
+	assert.Equal(t, "main", payload["branch"])
+	assert.Equal(t, "remove old.go", payload["message"])
+	assert.Equal(t, "blobsha", payload["sha"])
+}

internal/gitea/pulls.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/url"
 )
 
 type PullRequest struct {
@@ -101,3 +102,48 @@ func (c *Client) GetPullRequestDiff(ctx context.Context, owner, repo string, ind
 	}
 	return resp.Body, nil
 }
+
+type MergePRArgs struct {
+	Do    string `json:"Do"`
+	Title string `json:"merge_message_title,omitempty"`
+	Body  string `json:"merge_message_field,omitempty"`
+}
+
+func (c *Client) MergePullRequest(ctx context.Context, owner, repo string, index int, args MergePRArgs) error {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/pulls/%d/merge", owner, repo, index)
+	payload, err := json.Marshal(args)
+	if err != nil {
+		return err
+	}
+	body, status, err := c.PostJSON(ctx, p, payload)
+	if err != nil {
+		return err
+	}
+	return MapStatus(status, body)
+}
+
+func (c *Client) ListPullRequests(ctx context.Context, owner, repo, state, head string, page, limit int) ([]PullRequest, error) {
+	if page < 1 {
+		page = 1
+	}
+	if limit < 1 {
+		limit = 30
+	}
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/pulls?state=%s&page=%d&limit=%d",
+		owner, repo, url.QueryEscape(state), page, limit)
+	if head != "" {
+		p += "&head=" + url.QueryEscape(head)
+	}
+	body, status, err := c.GetJSON(ctx, p)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, body); err != nil {
+		return nil, err
+	}
+	var prs []PullRequest
+	if err := json.Unmarshal(body, &prs); err != nil {
+		return nil, err
+	}
+	return prs, nil
+}

internal/gitea/pulls_test.go

@@ -136,3 +136,55 @@ func TestGetPullRequestDiff(t *testing.T) {
 	require.NoError(t, err)
 	assert.Equal(t, []byte(rawDiff), diff)
 }
+
+func TestListPullRequests(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/pulls", r.URL.Path)
+		assert.Equal(t, "open", r.URL.Query().Get("state"))
+		assert.Equal(t, "feat/x", r.URL.Query().Get("head"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[` + pullFixture + `]`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	prs, err := c.ListPullRequests(context.Background(), "o", "r", "open", "feat/x", 0, 0)
+	require.NoError(t, err)
+	require.Len(t, prs, 1)
+	assert.Equal(t, 7, prs[0].Number)
+	assert.Equal(t, "feat/x", prs[0].Head.Ref)
+}
+
+func TestMergePullRequestSuccess(t *testing.T) {
+	var captured []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/pulls/7/merge", r.URL.Path)
+		assert.Equal(t, http.MethodPost, r.Method)
+		var err error
+		captured, err = io.ReadAll(r.Body)
+		require.NoError(t, err)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	err := c.MergePullRequest(context.Background(), "o", "r", 7, gitea.MergePRArgs{Do: "squash"})
+	require.NoError(t, err)
+
+	var payload map[string]any
+	require.NoError(t, json.Unmarshal(captured, &payload))
+	assert.Equal(t, "squash", payload["Do"])
+}
+
+func TestMergePullRequestConflict(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusConflict)
+		_, _ = w.Write([]byte(`{"message":"merge conflict"}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	err := c.MergePullRequest(context.Background(), "o", "r", 7, gitea.MergePRArgs{Do: "merge"})
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrConflict)
+}

internal/gitea/repos.go

@@ -86,3 +86,34 @@ func (c *Client) GetRepo(ctx context.Context, owner, name string) (*Repo, error)
 	}
 	return &r, nil
 }
+
+// EditRepoArgs carries optional fields for PATCH /api/v1/repos/{owner}/{name}.
+// Pointer fields let the caller omit unset values from the wire payload, so the
+// server only patches what was explicitly requested.
+type EditRepoArgs struct {
+	Archived    *bool   `json:"archived,omitempty"`
+	Description *string `json:"description,omitempty"`
+	Private     *bool   `json:"private,omitempty"`
+	Website     *string `json:"website,omitempty"`
+	Template    *bool   `json:"template,omitempty"`
+}
+
+func (c *Client) EditRepo(ctx context.Context, owner, name string, args EditRepoArgs) (*Repo, error) {
+	body, err := json.Marshal(args)
+	if err != nil {
+		return nil, fmt.Errorf("marshal edit args: %w", err)
+	}
+	path := fmt.Sprintf("/api/v1/repos/%s/%s", owner, name)
+	resp, status, err := c.PatchJSON(ctx, path, body)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, resp); err != nil {
+		return nil, err
+	}
+	var r Repo
+	if err := json.Unmarshal(resp, &r); err != nil {
+		return nil, err
+	}
+	return &r, nil
+}

internal/gitea/tags.go

@@ -0,0 +1,42 @@
+package gitea
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+)
+
+type CreateTagArgs struct {
+	TagName string `json:"tag_name"`
+	Target  string `json:"target"`
+	Message string `json:"message,omitempty"`
+}
+
+type Tag struct {
+	Name    string `json:"name"`
+	ID      string `json:"id"`
+	Message string `json:"message"`
+	Commit  struct {
+		Sha string `json:"sha"`
+	} `json:"commit"`
+}
+
+func (c *Client) CreateTag(ctx context.Context, owner, repo string, args CreateTagArgs) (*Tag, error) {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/tags", owner, repo)
+	payload, err := json.Marshal(args)
+	if err != nil {
+		return nil, err
+	}
+	body, status, err := c.PostJSON(ctx, p, payload)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, body); err != nil {
+		return nil, err
+	}
+	var tag Tag
+	if err := json.Unmarshal(body, &tag); err != nil {
+		return nil, err
+	}
+	return &tag, nil
+}

internal/gitea/tags_test.go

@@ -0,0 +1,49 @@
+package gitea_test
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCreateTag(t *testing.T) {
+	var captured []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/tags", r.URL.Path)
+		assert.Equal(t, http.MethodPost, r.Method)
+		var err error
+		captured, err = io.ReadAll(r.Body)
+		require.NoError(t, err)
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{
+			"name":"v1.0.0",
+			"id":"tagsha",
+			"message":"release",
+			"commit":{"sha":"cmt1","url":"http://example.com/commit/cmt1"}
+		}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	tag, err := c.CreateTag(context.Background(), "o", "r", gitea.CreateTagArgs{
+		TagName: "v1.0.0",
+		Target:  "main",
+		Message: "release",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "v1.0.0", tag.Name)
+	assert.Equal(t, "cmt1", tag.Commit.Sha)
+
+	var payload map[string]string
+	require.NoError(t, json.Unmarshal(captured, &payload))
+	assert.Equal(t, "v1.0.0", payload["tag_name"])
+	assert.Equal(t, "main", payload["target"])
+	assert.Equal(t, "release", payload["message"])
+}

internal/mcp/server.go

@@ -9,7 +9,7 @@ import (
 )
 
 const (
-	ProtocolVersion    = "2025-06-18"
+	ProtocolVersion    = "2025-03-26"
 	maxRequestBodyBytes = 1 << 20 // 1 MiB
 )
 
@@ -31,6 +31,9 @@ func NewServer(opts ServerOptions) *Server {
 
 func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	switch r.Method {
+	case http.MethodHead:
+		w.Header().Set("MCP-Protocol-Version", ProtocolVersion)
+		w.WriteHeader(http.StatusOK)
 	case http.MethodGet:
 		s.handleGET(w, r)
 	case http.MethodPost:
@@ -53,7 +56,6 @@ func (s *Server) handlePOST(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// initialize is the only method allowed without a session.
 	if req.Method == "initialize" {
 		sid := s.opts.Sessions.Issue()
 		w.Header().Set("Mcp-Session-Id", sid)
@@ -65,11 +67,12 @@ func (s *Server) handlePOST(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	sid := r.Header.Get("Mcp-Session-Id")
-	if !s.opts.Sessions.Valid(sid) {
-		http.Error(w, "missing or invalid Mcp-Session-Id", http.StatusBadRequest)
-		return
-	}
+	// Mcp-Session-Id is advisory: we issue one on initialize and accept it back,
+	// but every tool the gitea-mcp server exposes is stateless single-shot, so
+	// we do not gate non-initialize calls on it. The claude.ai connector's
+	// transport proxy is observed to not propagate the session header reliably,
+	// and the spec allows servers to be sessionless. Compare with brain-mcp /
+	// supervisor-mcp, which never required a session at all.
 
 	switch req.Method {
 	case "tools/list":
@@ -108,11 +111,8 @@ func (s *Server) handlePOST(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) handleGET(w http.ResponseWriter, r *http.Request) {
-	sid := r.Header.Get("Mcp-Session-Id")
-	if !s.opts.Sessions.Valid(sid) {
-		http.Error(w, "missing or invalid Mcp-Session-Id", http.StatusBadRequest)
-		return
-	}
+	// Session ID is optional for GET: clients may open the SSE stream before
+	// calling initialize (e.g. claude.ai probes on add). Accept with or without.
 	w.Header().Set("Content-Type", "text/event-stream")
 	w.Header().Set("Cache-Control", "no-cache")
 	w.Header().Set("Connection", "keep-alive")

internal/mcp/server_test.go

@@ -52,19 +52,27 @@ func TestInitialize(t *testing.T) {
 	var resp map[string]any
 	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
 	result := resp["result"].(map[string]any)
-	assert.Equal(t, "2025-06-18", result["protocolVersion"])
+	assert.Equal(t, mcp.ProtocolVersion, result["protocolVersion"])
 	si := result["serverInfo"].(map[string]any)
 	assert.Equal(t, "gitea-mcp", si["name"])
 }
 
-func TestPostWithoutSessionRejected(t *testing.T) {
+func TestPostWithoutSessionAccepted(t *testing.T) {
+	// gitea-mcp tools are stateless single-shot; Mcp-Session-Id is advisory.
+	// claude.ai's MCP transport proxy is observed to not propagate the
+	// session header reliably, so non-initialize calls must work without it.
 	srv := newServer(t)
 	rr := postJSON(t, srv, map[string]any{
 		"jsonrpc": "2.0",
 		"id":      2,
 		"method":  "tools/list",
 	}, "")
-	require.Equal(t, http.StatusBadRequest, rr.Code)
+	require.Equal(t, http.StatusOK, rr.Code)
+
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	result := resp["result"].(map[string]any)
+	assert.Contains(t, result, "tools")
 }
 
 func TestServerWithOriginAllowlistRejectsBadOrigin(t *testing.T) {
@@ -118,6 +126,15 @@ func TestPostBodyTooLarge(t *testing.T) {
 	assert.Equal(t, http.StatusBadRequest, rr.Code)
 }
 
+func TestHEADReturnsMCPProtocolVersionHeader(t *testing.T) {
+	srv := newServer(t)
+	req := httptest.NewRequest(http.MethodHead, "/mcp", nil)
+	rr := httptest.NewRecorder()
+	srv.ServeHTTP(rr, req)
+	require.Equal(t, http.StatusOK, rr.Code)
+	assert.Equal(t, mcp.ProtocolVersion, rr.Header().Get("MCP-Protocol-Version"))
+}
+
 func TestToolsCallToolNotFound(t *testing.T) {
 	srv := newServer(t)
 	// Initialize to get a session ID.

internal/tools/branch_delete.go

@@ -0,0 +1,64 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type BranchDelete struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewBranchDelete(c *gitea.Client, a *allowlist.Allowlist) *BranchDelete {
+	return &BranchDelete{c: c, a: a}
+}
+
+func (t *BranchDelete) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "branch_delete",
+		Description: "Delete a branch from a repository.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"branch":{"type":"string"}
+			},
+			"required":["owner","name","branch"]
+		}`),
+	}
+}
+
+type branchDeleteArgs struct {
+	Owner  string `json:"owner"`
+	Name   string `json:"name"`
+	Branch string `json:"branch"`
+}
+
+func (t *BranchDelete) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args branchDeleteArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+	if args.Branch == "" {
+		return nil, fmt.Errorf("branch is required: %w", gitea.ErrValidation)
+	}
+
+	if err := t.c.DeleteBranch(ctx, args.Owner, args.Name, args.Branch); err != nil {
+		return nil, err
+	}
+
+	return textOK(map[string]any{
+		"deleted": true,
+		"branch":  args.Branch,
+	})
+}

internal/tools/branch_delete_test.go

@@ -0,0 +1,51 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBranchDeleteSuccess(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodDelete, r.Method)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	tool := tools.NewBranchDelete(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","branch":"feat/x"}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Equal(t, true, result["deleted"])
+	assert.Equal(t, "feat/x", result["branch"])
+}
+
+func TestBranchDeleteProtectedReturnsError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusForbidden)
+		_, _ = w.Write([]byte(`{"message":"branch is protected"}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewBranchDelete(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","branch":"main"}`))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrPermissionDenied)
+}
+
+func TestBranchDeleteAllowlistRejects(t *testing.T) {
+	tool := tools.NewBranchDelete(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"repo","branch":"feat/x"}`))
+	require.Error(t, err)
+}

internal/tools/branch_list.go

@@ -0,0 +1,67 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type BranchList struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewBranchList(c *gitea.Client, a *allowlist.Allowlist) *BranchList {
+	return &BranchList{c: c, a: a}
+}
+
+func (t *BranchList) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "branch_list",
+		Description: "List branches in a repository.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"page":{"type":"integer","minimum":1},
+				"limit":{"type":"integer","minimum":1,"maximum":50}
+			},
+			"required":["owner","name"]
+		}`),
+	}
+}
+
+type branchListArgs struct {
+	Owner string `json:"owner"`
+	Name  string `json:"name"`
+	Page  int    `json:"page"`
+	Limit int    `json:"limit"`
+}
+
+func (t *BranchList) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args branchListArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+
+	branches, err := t.c.ListBranches(ctx, args.Owner, args.Name, args.Page, capLimit(args.Limit, 30))
+	if err != nil {
+		return nil, err
+	}
+
+	result := make([]map[string]any, len(branches))
+	for i, b := range branches {
+		result[i] = map[string]any{
+			"name": b.Name,
+			"sha":  b.Commit.ID,
+		}
+	}
+	return textOK(result)
+}

internal/tools/branch_list_test.go

@@ -0,0 +1,43 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBranchListReturnsNames(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[
+			{"name":"main","commit":{"id":"abc","url":""}},
+			{"name":"feat/x","commit":{"id":"def","url":""}}
+		]`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewBranchList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo"}`))
+	require.NoError(t, err)
+
+	var result []map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	require.Len(t, result, 2)
+	assert.Equal(t, "main", result[0]["name"])
+	assert.Equal(t, "abc", result[0]["sha"])
+	assert.Equal(t, "feat/x", result[1]["name"])
+}
+
+func TestBranchListAllowlistRejects(t *testing.T) {
+	tool := tools.NewBranchList(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"repo"}`))
+	require.Error(t, err)
+}

internal/tools/branch_protection_get.go

@@ -0,0 +1,63 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type BranchProtectionGet struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewBranchProtectionGet(c *gitea.Client, a *allowlist.Allowlist) *BranchProtectionGet {
+	return &BranchProtectionGet{c: c, a: a}
+}
+
+func (t *BranchProtectionGet) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "branch_protection_get",
+		Description: "Get branch protection rules. Returns {protected:false} if no rule exists — never returns an error for unprotected branches.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"branch":{"type":"string"}
+			},
+			"required":["owner","name","branch"]
+		}`),
+	}
+}
+
+type branchProtectionGetArgs struct {
+	Owner  string `json:"owner"`
+	Name   string `json:"name"`
+	Branch string `json:"branch"`
+}
+
+func (t *BranchProtectionGet) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args branchProtectionGetArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+
+	bp, err := t.c.GetBranchProtection(ctx, args.Owner, args.Name, args.Branch)
+	if err != nil {
+		return nil, err
+	}
+
+	return textOK(map[string]any{
+		"protected":          bp.Protected,
+		"required_approvals": bp.RequiredApprovals,
+		"push_whitelist":     bp.PushWhitelist,
+		"merge_whitelist":    bp.MergeWhitelist,
+	})
+}

internal/tools/branch_protection_get_test.go

@@ -0,0 +1,54 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBranchProtectionGetProtected(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"required_approvals":1,"push_whitelist_usernames":[],"merge_whitelist_usernames":[]}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewBranchProtectionGet(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","branch":"main"}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Equal(t, true, result["protected"])
+	assert.Equal(t, float64(1), result["required_approvals"])
+}
+
+func TestBranchProtectionGetUnprotected(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+		_, _ = w.Write([]byte(`{"message":"not found"}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewBranchProtectionGet(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","branch":"feat/x"}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Equal(t, false, result["protected"])
+}
+
+func TestBranchProtectionGetAllowlistRejects(t *testing.T) {
+	tool := tools.NewBranchProtectionGet(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"repo","branch":"main"}`))
+	require.Error(t, err)
+}

internal/tools/create_project_from_template.go

@@ -45,14 +45,15 @@ func NewCreateProjectFromTemplate(c *gitea.Client, a *allowlist.Allowlist, tmplO
 func (t *CreateProjectFromTemplate) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "create_project_from_template",
-		Description: "Create a new project repo from the template, applying placeholder substitutions to known files.",
+		Description: "Create a new project repo from a template, applying placeholder substitutions to known files. Defaults to the server-configured template; pass template_name to override (e.g. template-go-agent).",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,38}[a-z0-9]$"},
 				"description":{"type":"string"},
-				"private":{"type":"boolean"}
+				"private":{"type":"boolean"},
+				"template_name":{"type":"string","description":"Template repo name to generate from. Defaults to the server-configured template."}
 			},
 			"required":["owner","name"]
 		}`),
@@ -60,10 +61,11 @@ func (t *CreateProjectFromTemplate) Descriptor() registry.ToolDescriptor {
 }
 
 type createProjectArgs struct {
-	Owner       string `json:"owner"`
-	Name        string `json:"name"`
-	Description string `json:"description"`
-	Private     bool   `json:"private"`
+	Owner        string `json:"owner"`
+	Name         string `json:"name"`
+	Description  string `json:"description"`
+	Private      bool   `json:"private"`
+	TemplateName string `json:"template_name"`
 }
 
 type createProjectResult struct {
@@ -91,13 +93,20 @@ func (t *CreateProjectFromTemplate) Call(ctx context.Context, raw json.RawMessag
 		return nil, fmt.Errorf("name %q does not match pattern %s: %w", args.Name, nameRe.String(), gitea.ErrValidation)
 	}
 
+	// Resolve template: per-call override takes precedence over the
+	// server-configured default. Owner stays server-configured.
+	tmplName := args.TemplateName
+	if tmplName == "" {
+		tmplName = t.templateName
+	}
+
 	// Verify template exists and is marked as a template repo.
-	tmpl, err := t.c.GetRepo(ctx, t.templateOwner, t.templateName)
+	tmpl, err := t.c.GetRepo(ctx, t.templateOwner, tmplName)
 	if err != nil {
 		return nil, fmt.Errorf("template lookup: %w", err)
 	}
 	if !tmpl.Template {
-		return nil, fmt.Errorf("repo %s/%s is not marked as template: %w", t.templateOwner, t.templateName, gitea.ErrValidation)
+		return nil, fmt.Errorf("repo %s/%s is not marked as template: %w", t.templateOwner, tmplName, gitea.ErrValidation)
 	}
 
 	// Verify destination doesn't already exist.
@@ -108,7 +117,7 @@ func (t *CreateProjectFromTemplate) Call(ctx context.Context, raw json.RawMessag
 	}
 
 	// Generate repo from template.
-	newRepo, err := t.c.GenerateFromTemplate(ctx, t.templateOwner, t.templateName, gitea.GenerateFromTemplateArgs{
+	newRepo, err := t.c.GenerateFromTemplate(ctx, t.templateOwner, tmplName, gitea.GenerateFromTemplateArgs{
 		Owner:       args.Owner,
 		Name:        args.Name,
 		Description: args.Description,

internal/tools/create_project_from_template_test.go

@@ -122,6 +122,62 @@ func TestCreateProjectHappyPath(t *testing.T) {
 	assert.Empty(t, out.PartialFailure)
 }
 
+// TestCreateProjectTemplateNameOverride (issue #24): per-call template_name overrides the
+// server-configured default, so the same binary can generate from template-go-web or
+// template-go-agent without restart.
+func TestCreateProjectTemplateNameOverride(t *testing.T) {
+	var templateLookups, generateCalls []string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/template-go-agent":
+			templateLookups = append(templateLookups, "template-go-agent")
+			_, _ = w.Write([]byte(newTemplateRepoJSON("template-go-agent", true)))
+
+		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/template-go-web":
+			templateLookups = append(templateLookups, "template-go-web")
+			_, _ = w.Write([]byte(newTemplateRepoJSON("template-go-web", true)))
+
+		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/new-agent":
+			w.WriteHeader(http.StatusNotFound)
+			_, _ = w.Write([]byte(`{"message":"not found"}`))
+
+		case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/generate"):
+			generateCalls = append(generateCalls, r.URL.Path)
+			w.WriteHeader(http.StatusCreated)
+			_, _ = w.Write([]byte(newGeneratedRepoJSON("new-agent")))
+
+		case r.Method == http.MethodGet && strings.HasPrefix(r.URL.Path, "/api/v1/repos/mathias/new-agent/contents/"):
+			filePath := strings.TrimPrefix(r.URL.Path, "/api/v1/repos/mathias/new-agent/contents/")
+			_, _ = w.Write([]byte(fileContentsJSON(filePath)))
+
+		case r.Method == http.MethodPut && strings.HasPrefix(r.URL.Path, "/api/v1/repos/mathias/new-agent/contents/"):
+			filePath := strings.TrimPrefix(r.URL.Path, "/api/v1/repos/mathias/new-agent/contents/")
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte(fileWriteResultJSON(filePath)))
+
+		default:
+			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	// Server is configured with template-go-web as the default; call overrides to template-go-agent.
+	tool := newCreateProjectTool(srv.URL)
+	_, err := tool.Call(context.Background(), json.RawMessage(
+		`{"owner":"mathias","name":"new-agent","template_name":"template-go-agent"}`,
+	))
+	require.NoError(t, err)
+
+	assert.Equal(t, []string{"template-go-agent"}, templateLookups,
+		"override must direct the template lookup, not the server default")
+	require.Len(t, generateCalls, 1)
+	assert.Equal(t, "/api/v1/repos/mathias/template-go-agent/generate", generateCalls[0],
+		"override must direct the /generate call too")
+}
+
 // TestCreateProjectNameRegexFailure: invalid name returns ErrValidation without hitting network.
 func TestCreateProjectNameRegexFailure(t *testing.T) {
 	tool := tools.NewCreateProjectFromTemplate(

internal/tools/dir_list.go

@@ -0,0 +1,70 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type DirList struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewDirList(c *gitea.Client, a *allowlist.Allowlist) *DirList {
+	return &DirList{c: c, a: a}
+}
+
+func (t *DirList) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "dir_list",
+		Description: "List directory contents in a repository. Use empty path for repo root. Returns name, path, type (file/dir/symlink), sha, size per entry.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"path":{"type":"string"},
+				"ref":{"type":"string"}
+			},
+			"required":["owner","name"]
+		}`),
+	}
+}
+
+type dirListArgs struct {
+	Owner string `json:"owner"`
+	Name  string `json:"name"`
+	Path  string `json:"path"`
+	Ref   string `json:"ref"`
+}
+
+func (t *DirList) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args dirListArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+
+	entries, err := t.c.ListContents(ctx, args.Owner, args.Name, args.Path, args.Ref)
+	if err != nil {
+		return nil, err
+	}
+
+	result := make([]map[string]any, len(entries))
+	for i, e := range entries {
+		result[i] = map[string]any{
+			"name": e.Name,
+			"path": e.Path,
+			"type": e.Type,
+			"sha":  e.Sha,
+			"size": e.Size,
+		}
+	}
+	return textOK(result)
+}

internal/tools/dir_list_test.go

@@ -0,0 +1,75 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestDirListReturnsEntries(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/owner/repo/contents/src", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[
+			{"name":"main.go","path":"src/main.go","type":"file","sha":"abc","size":512},
+			{"name":"util","path":"src/util","type":"dir","sha":"def","size":0}
+		]`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewDirList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","path":"src"}`))
+	require.NoError(t, err)
+
+	var result []map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	require.Len(t, result, 2)
+	assert.Equal(t, "main.go", result[0]["name"])
+	assert.Equal(t, "file", result[0]["type"])
+	assert.Equal(t, "util", result[1]["name"])
+	assert.Equal(t, "dir", result[1]["type"])
+}
+
+func TestDirListRootPath(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/owner/repo/contents/", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[]`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewDirList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","path":""}`))
+	require.NoError(t, err)
+
+	var result []map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Empty(t, result)
+}
+
+func TestDirListOnFileReturnsError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"path":"README.md","sha":"abc","size":10,"content":"","encoding":"base64"}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewDirList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","path":"README.md"}`))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrValidation)
+}
+
+func TestDirListAllowlistRejects(t *testing.T) {
+	tool := tools.NewDirList(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"repo","path":""}`))
+	require.Error(t, err)
+}

internal/tools/file_delete.go

@@ -0,0 +1,78 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type FileDelete struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewFileDelete(c *gitea.Client, a *allowlist.Allowlist) *FileDelete {
+	return &FileDelete{c: c, a: a}
+}
+
+func (t *FileDelete) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "file_delete",
+		Description: "Delete a file from a repository branch. sha is the current blob SHA (from file_read).",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"path":{"type":"string"},
+				"branch":{"type":"string"},
+				"message":{"type":"string"},
+				"sha":{"type":"string"}
+			},
+			"required":["owner","name","path","branch","message","sha"]
+		}`),
+	}
+}
+
+type fileDeleteArgs struct {
+	Owner   string `json:"owner"`
+	Name    string `json:"name"`
+	Path    string `json:"path"`
+	Branch  string `json:"branch"`
+	Message string `json:"message"`
+	Sha     string `json:"sha"`
+}
+
+func (t *FileDelete) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args fileDeleteArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+	if args.Sha == "" {
+		return nil, fmt.Errorf("sha is required: %w", gitea.ErrValidation)
+	}
+	if args.Message == "" {
+		return nil, fmt.Errorf("message is required: %w", gitea.ErrValidation)
+	}
+
+	result, err := t.c.DeleteFile(ctx, args.Owner, args.Name, args.Path, gitea.DeleteFileArgs{
+		Branch:  args.Branch,
+		Message: args.Message,
+		Sha:     args.Sha,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return textOK(map[string]any{
+		"commit_sha": result.Commit.Sha,
+		"html_url":   result.Commit.HTMLURL,
+	})
+}

internal/tools/file_delete_test.go

@@ -0,0 +1,52 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestFileDeleteSuccess(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodDelete, r.Method)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"content":null,"commit":{"sha":"cmt1","html_url":"http://example.com/commit/cmt1"}}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewFileDelete(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{
+		"owner":"owner","name":"repo","path":"src/old.go",
+		"branch":"main","message":"remove old.go","sha":"blobsha"
+	}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Equal(t, "cmt1", result["commit_sha"])
+}
+
+func TestFileDeleteRequiresSha(t *testing.T) {
+	tool := tools.NewFileDelete(gitea.NewClient("http://unused", ""), allowlist.New([]string{"owner"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{
+		"owner":"owner","name":"repo","path":"f.go","branch":"main","message":"rm"
+	}`))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrValidation)
+}
+
+func TestFileDeleteAllowlistRejects(t *testing.T) {
+	tool := tools.NewFileDelete(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{
+		"owner":"evil","name":"repo","path":"f.go","branch":"main","message":"rm","sha":"abc"
+	}`))
+	require.Error(t, err)
+}

internal/tools/file_write_branch_test.go

@@ -39,9 +39,9 @@ func TestFileWriteBranchCreatesBranchAndFile(t *testing.T) {
 		_, _ = w.Write([]byte(createBranchResp))
 	})
 
-	// Upsert file → 201
+	// New file (no sha) → POST to /contents/{path}
 	mux.HandleFunc("/api/v1/repos/owner/myrepo/contents/doc.md", func(w http.ResponseWriter, r *http.Request) {
-		require.Equal(t, http.MethodPut, r.Method)
+		require.Equal(t, http.MethodPost, r.Method)
 		w.WriteHeader(http.StatusCreated)
 		_, _ = w.Write([]byte(upsertFileResp))
 	})
@@ -64,6 +64,39 @@ func TestFileWriteBranchCreatesBranchAndFile(t *testing.T) {
 	assert.Equal(t, "cmt1", result["commit_sha"])
 }
 
+func TestFileWriteBranchUsesPutWhenShaProvided(t *testing.T) {
+	mux := http.NewServeMux()
+
+	// Branch exists
+	mux.HandleFunc("/api/v1/repos/owner/myrepo/branches/feat/existing", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(branchCheckExistsResp))
+	})
+
+	// Existing file (sha provided) → PUT
+	mux.HandleFunc("/api/v1/repos/owner/myrepo/contents/doc.md", func(w http.ResponseWriter, r *http.Request) {
+		require.Equal(t, http.MethodPut, r.Method)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(upsertFileResp))
+	})
+
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+
+	tool := tools.NewFileWriteBranch(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{
+		"owner":"owner","name":"myrepo","path":"doc.md",
+		"content":"hello","branch":"feat/existing",
+		"sha":"oldsha","message":"update doc.md"
+	}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Equal(t, "feat/existing", result["branch"])
+	assert.Equal(t, "cmt1", result["commit_sha"])
+}
+
 func TestFileWriteBranchUsesDefaultBaseWhenBaseEmpty(t *testing.T) {
 	var createBody []byte
 	mux := http.NewServeMux()

internal/tools/pr_files_diff.go

@@ -143,7 +143,13 @@ func splitUnifiedDiff(d []byte) map[string][]byte {
 
 	flush := func() {
 		if currentFile != "" {
-			m[currentFile] = []byte(current.String())
+			// Copy: bytes.Buffer.Bytes() returns the internal slice,
+			// which Reset() then reuses. Without the copy, every map
+			// entry ends up aliased to the last file's data.
+			b := current.Bytes()
+			cp := make([]byte, len(b))
+			copy(cp, b)
+			m[currentFile] = cp
 			current.Reset()
 		}
 	}

internal/tools/pr_files_diff_test.go

@@ -42,11 +42,11 @@ func buildFilesJSON(files []string, additions int) string {
 func newPRFilesDiffServer(t *testing.T, filesJSON, rawDiff string) *httptest.Server {
 	t.Helper()
 	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case r.URL.Path == "/api/v1/repos/o/r/pulls/1/files":
+		switch r.URL.Path {
+		case "/api/v1/repos/o/r/pulls/1/files":
 			w.Header().Set("Content-Type", "application/json")
 			_, _ = w.Write([]byte(filesJSON))
-		case r.URL.Path == "/api/v1/repos/o/r/pulls/1.diff":
+		case "/api/v1/repos/o/r/pulls/1.diff":
 			w.Header().Set("Content-Type", "text/plain")
 			_, _ = w.Write([]byte(rawDiff))
 		default:
@@ -97,6 +97,47 @@ func TestPRFilesDiffSmall(t *testing.T) {
 	assert.ElementsMatch(t, fileNames, paths)
 }
 
+// Regression for issue #25: every file's diff entry must contain its OWN diff,
+// not a shared buffer pointing at the last file. Prior bug: splitUnifiedDiff
+// flushed bytes.Buffer.Bytes() into the map without copying, so every entry
+// aliased the buffer's backing array and showed the last file's content.
+func TestPRFilesDiffPerFileIsolation(t *testing.T) {
+	fileNames := []string{"alpha.go", "beta.go", "gamma.go", "delta.go"}
+	rawDiff := buildDiff(fileNames, 5)
+	filesJSON := buildFilesJSON(fileNames, 5)
+
+	srv := newPRFilesDiffServer(t, filesJSON, rawDiff)
+	defer srv.Close()
+
+	tool := tools.NewPRFilesDiff(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"o"}))
+	result, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"o","name":"r","number":1}`))
+	require.NoError(t, err)
+
+	var out struct {
+		Files []struct {
+			Path string `json:"path"`
+			Diff string `json:"diff"`
+		} `json:"files"`
+	}
+	require.NoError(t, json.Unmarshal(result, &out))
+	require.Len(t, out.Files, len(fileNames))
+
+	for _, f := range out.Files {
+		expected := fmt.Sprintf("diff --git a/%s b/%s", f.Path, f.Path)
+		assert.Contains(t, f.Diff, expected,
+			"file %s diff must contain its own header, got: %.80q", f.Path, f.Diff)
+		// No other file's header should leak in.
+		for _, other := range fileNames {
+			if other == f.Path {
+				continue
+			}
+			otherHeader := fmt.Sprintf("diff --git a/%s b/%s", other, other)
+			assert.NotContains(t, f.Diff, otherHeader,
+				"file %s diff must NOT contain %s's header", f.Path, other)
+		}
+	}
+}
+
 func TestPRFilesDiffPerFileTruncated(t *testing.T) {
 	// One file with a 30KB diff (each "+abcdefghij\n" = 12 bytes; 30KB / 12 ≈ 2560 lines).
 	fileNames := []string{"bigfile.go"}

internal/tools/pr_list.go

@@ -0,0 +1,80 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type PRList struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewPRList(c *gitea.Client, a *allowlist.Allowlist) *PRList {
+	return &PRList{c: c, a: a}
+}
+
+func (t *PRList) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "pr_list",
+		Description: "List pull requests. state: open (default), closed, or all. Optionally filter by head branch.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"state":{"type":"string","enum":["open","closed","all"]},
+				"head":{"type":"string"},
+				"page":{"type":"integer","minimum":1},
+				"limit":{"type":"integer","minimum":1,"maximum":50}
+			},
+			"required":["owner","name"]
+		}`),
+	}
+}
+
+type prListArgs struct {
+	Owner string `json:"owner"`
+	Name  string `json:"name"`
+	State string `json:"state"`
+	Head  string `json:"head"`
+	Page  int    `json:"page"`
+	Limit int    `json:"limit"`
+}
+
+func (t *PRList) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args prListArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+	state := args.State
+	if state == "" {
+		state = "open"
+	}
+
+	prs, err := t.c.ListPullRequests(ctx, args.Owner, args.Name, state, args.Head, args.Page, capLimit(args.Limit, 30))
+	if err != nil {
+		return nil, err
+	}
+
+	result := make([]map[string]any, len(prs))
+	for i, pr := range prs {
+		result[i] = map[string]any{
+			"number":      pr.Number,
+			"title":       pr.Title,
+			"state":       pr.State,
+			"head_branch": pr.Head.Ref,
+			"base_branch": pr.Base.Ref,
+			"draft":       pr.Draft,
+			"html_url":    pr.HTMLURL,
+		}
+	}
+	return textOK(result)
+}

internal/tools/pr_list_test.go

@@ -0,0 +1,62 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPRListReturnsOpenPRs(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "open", r.URL.Query().Get("state"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{
+			"number":7,"title":"Add feature X","html_url":"http://example.com/pulls/7",
+			"state":"open","draft":false,
+			"head":{"ref":"feat/x"},"base":{"ref":"main"}
+		}]`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewPRList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo"}`))
+	require.NoError(t, err)
+
+	var result []map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	require.Len(t, result, 1)
+	assert.Equal(t, float64(7), result[0]["number"])
+	assert.Equal(t, "feat/x", result[0]["head_branch"])
+	assert.Equal(t, "main", result[0]["base_branch"])
+}
+
+func TestPRListDefaultsToOpen(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "open", r.URL.Query().Get("state"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[]`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewPRList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo"}`))
+	require.NoError(t, err)
+
+	var result []map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Empty(t, result)
+}
+
+func TestPRListAllowlistRejects(t *testing.T) {
+	tool := tools.NewPRList(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"repo"}`))
+	require.Error(t, err)
+}

internal/tools/pr_merge.go

@@ -0,0 +1,76 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type PRMerge struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewPRMerge(c *gitea.Client, a *allowlist.Allowlist) *PRMerge {
+	return &PRMerge{c: c, a: a}
+}
+
+func (t *PRMerge) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "pr_merge",
+		Description: "Merge a pull request. style: merge (default), squash, or rebase.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"index":{"type":"integer","minimum":1},
+				"style":{"type":"string","enum":["merge","squash","rebase"]},
+				"merge_message_title":{"type":"string"},
+				"merge_message_field":{"type":"string"}
+			},
+			"required":["owner","name","index"]
+		}`),
+	}
+}
+
+type prMergeArgs struct {
+	Owner string `json:"owner"`
+	Name  string `json:"name"`
+	Index int    `json:"index"`
+	Style string `json:"style"`
+	Title string `json:"merge_message_title"`
+	Body  string `json:"merge_message_field"`
+}
+
+func (t *PRMerge) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args prMergeArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+	if args.Index < 1 {
+		return nil, fmt.Errorf("index must be >= 1: %w", gitea.ErrValidation)
+	}
+
+	style := args.Style
+	if style == "" {
+		style = "merge"
+	}
+
+	if err := t.c.MergePullRequest(ctx, args.Owner, args.Name, args.Index, gitea.MergePRArgs{
+		Do:    style,
+		Title: args.Title,
+		Body:  args.Body,
+	}); err != nil {
+		return nil, err
+	}
+
+	return textOK(map[string]any{"merged": true})
+}

internal/tools/pr_merge_test.go

@@ -0,0 +1,70 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPRMergeSuccess(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/owner/repo/pulls/7/merge", r.URL.Path)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	tool := tools.NewPRMerge(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","index":7}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Equal(t, true, result["merged"])
+}
+
+func TestPRMergeDefaultsToMergeStyle(t *testing.T) {
+	var captured []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var err error
+		captured, err = io.ReadAll(r.Body)
+		require.NoError(t, err)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	tool := tools.NewPRMerge(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","index":7}`))
+	require.NoError(t, err)
+
+	var payload map[string]any
+	require.NoError(t, json.Unmarshal(captured, &payload))
+	assert.Equal(t, "merge", payload["Do"])
+}
+
+func TestPRMergeConflictReturnsError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusConflict)
+		_, _ = w.Write([]byte(`{"message":"merge conflict"}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewPRMerge(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","index":7}`))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrConflict)
+}
+
+func TestPRMergeAllowlistRejects(t *testing.T) {
+	tool := tools.NewPRMerge(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"repo","index":1}`))
+	require.Error(t, err)
+}

internal/tools/repo_status.go

@@ -0,0 +1,104 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type RepoStatus struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewRepoStatus(c *gitea.Client, a *allowlist.Allowlist) *RepoStatus {
+	return &RepoStatus{c: c, a: a}
+}
+
+func (t *RepoStatus) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "repo_status",
+		Description: "Get repo state in one call: all branches, open PRs, and protection rules for a target branch. Use this first to decide whether to use feature-branch or trunk-based development.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"branch":{"type":"string"}
+			},
+			"required":["owner","name"]
+		}`),
+	}
+}
+
+type repoStatusArgs struct {
+	Owner  string `json:"owner"`
+	Name   string `json:"name"`
+	Branch string `json:"branch"`
+}
+
+func (t *RepoStatus) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args repoStatusArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+
+	branch := args.Branch
+	if branch == "" {
+		var err error
+		branch, err = t.c.DefaultBranch(ctx, args.Owner, args.Name)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	branches, err := t.c.ListBranches(ctx, args.Owner, args.Name, 1, 50)
+	if err != nil {
+		return nil, err
+	}
+
+	prs, err := t.c.ListPullRequests(ctx, args.Owner, args.Name, "open", "", 1, 50)
+	if err != nil {
+		return nil, err
+	}
+
+	bp, err := t.c.GetBranchProtection(ctx, args.Owner, args.Name, branch)
+	if err != nil {
+		return nil, err
+	}
+
+	branchList := make([]map[string]any, len(branches))
+	for i, b := range branches {
+		branchList[i] = map[string]any{"name": b.Name, "sha": b.Commit.ID}
+	}
+
+	prList := make([]map[string]any, len(prs))
+	for i, pr := range prs {
+		prList[i] = map[string]any{
+			"number":      pr.Number,
+			"title":       pr.Title,
+			"state":       pr.State,
+			"head_branch": pr.Head.Ref,
+			"base_branch": pr.Base.Ref,
+			"draft":       pr.Draft,
+			"html_url":    pr.HTMLURL,
+		}
+	}
+
+	return textOK(map[string]any{
+		"branches": branchList,
+		"open_prs": prList,
+		"protection": map[string]any{
+			"protected":          bp.Protected,
+			"required_approvals": bp.RequiredApprovals,
+			"push_whitelist":     bp.PushWhitelist,
+			"merge_whitelist":    bp.MergeWhitelist,
+		},
+	})
+}

internal/tools/repo_status_test.go

@@ -0,0 +1,131 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRepoStatusComposesThreeEndpoints(t *testing.T) {
+	mux := http.NewServeMux()
+
+	mux.HandleFunc("/api/v1/repos/owner/repo/branches", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[
+			{"name":"main","commit":{"id":"abc","url":""}},
+			{"name":"feat/x","commit":{"id":"def","url":""}}
+		]`))
+	})
+	mux.HandleFunc("/api/v1/repos/owner/repo/pulls", func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "open", r.URL.Query().Get("state"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{
+			"number":3,"title":"My PR","html_url":"http://example.com/pulls/3",
+			"state":"open","draft":false,
+			"head":{"ref":"feat/x"},"base":{"ref":"main"}
+		}]`))
+	})
+	mux.HandleFunc("/api/v1/repos/owner/repo/branch_protections/main", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"required_approvals":1,"push_whitelist_usernames":[],"merge_whitelist_usernames":[]}`))
+	})
+
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+
+	tool := tools.NewRepoStatus(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","branch":"main"}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+
+	branches := result["branches"].([]any)
+	assert.Len(t, branches, 2)
+
+	openPRs := result["open_prs"].([]any)
+	assert.Len(t, openPRs, 1)
+	assert.Equal(t, float64(3), openPRs[0].(map[string]any)["number"])
+
+	protection := result["protection"].(map[string]any)
+	assert.Equal(t, true, protection["protected"])
+	assert.Equal(t, float64(1), protection["required_approvals"])
+}
+
+func TestRepoStatusUnprotectedBranch(t *testing.T) {
+	mux := http.NewServeMux()
+
+	mux.HandleFunc("/api/v1/repos/owner/repo/branches", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"name":"main","commit":{"id":"abc","url":""}}]`))
+	})
+	mux.HandleFunc("/api/v1/repos/owner/repo/pulls", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[]`))
+	})
+	mux.HandleFunc("/api/v1/repos/owner/repo/branch_protections/main", func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+		_, _ = w.Write([]byte(`{"message":"not found"}`))
+	})
+
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+
+	tool := tools.NewRepoStatus(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","branch":"main"}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	protection := result["protection"].(map[string]any)
+	assert.Equal(t, false, protection["protected"])
+}
+
+func TestRepoStatusAllowlistRejects(t *testing.T) {
+	tool := tools.NewRepoStatus(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"repo","branch":"main"}`))
+	require.Error(t, err)
+}
+
+func TestRepoStatusDefaultsBranchFromRepo(t *testing.T) {
+	mux := http.NewServeMux()
+
+	mux.HandleFunc("/api/v1/repos/owner/repo", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"name":"repo","full_name":"owner/repo","default_branch":"main","description":"","private":false,"clone_url":"","html_url":""}`))
+	})
+	mux.HandleFunc("/api/v1/repos/owner/repo/branches", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"name":"main","commit":{"id":"abc","url":""}}]`))
+	})
+	mux.HandleFunc("/api/v1/repos/owner/repo/pulls", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[]`))
+	})
+	mux.HandleFunc("/api/v1/repos/owner/repo/branch_protections/main", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"required_approvals":0,"push_whitelist_usernames":[],"merge_whitelist_usernames":[]}`))
+	})
+
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+
+	tool := tools.NewRepoStatus(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	// no "branch" field — triggers DefaultBranch fallback
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo"}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.NotNil(t, result["branches"])
+	assert.NotNil(t, result["open_prs"])
+	assert.NotNil(t, result["protection"])
+}

internal/tools/repo_update.go

@@ -0,0 +1,91 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type RepoUpdate struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewRepoUpdate(c *gitea.Client, a *allowlist.Allowlist) *RepoUpdate {
+	return &RepoUpdate{c: c, a: a}
+}
+
+func (t *RepoUpdate) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name: "repo_update",
+		Description: "Update repository metadata (description, visibility, default branch, website, archived, template). " +
+			"Only fields explicitly set in the call are patched. " +
+			"WARNING: private=false exposes the repo publicly — verify intent before calling.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"description":{"type":"string"},
+				"private":{"type":"boolean","description":"Toggle visibility. false makes the repo public."},
+				"website":{"type":"string","description":"Homepage URL"},
+				"default_branch":{"type":"string","description":"Rename the default branch"},
+				"archived":{"type":"boolean","description":"Mark repo as archived (read-only)."},
+				"template":{"type":"boolean","description":"Toggle template-repo flag"},
+				"confirm":{"type":"string","description":"Required when setting private=false. Must equal the repo name."}
+			},
+			"required":["owner","name"]
+		}`),
+	}
+}
+
+type repoUpdateArgs struct {
+	Owner         string  `json:"owner"`
+	Name          string  `json:"name"`
+	Description   *string `json:"description,omitempty"`
+	Private       *bool   `json:"private,omitempty"`
+	Website       *string `json:"website,omitempty"`
+	DefaultBranch *string `json:"default_branch,omitempty"`
+	Archived      *bool   `json:"archived,omitempty"`
+	Template      *bool   `json:"template,omitempty"`
+	Confirm       string  `json:"confirm"`
+}
+
+func (t *RepoUpdate) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args repoUpdateArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+
+	// Making a repo public is a significant action — require explicit confirmation.
+	if args.Private != nil && !*args.Private {
+		if args.Confirm != args.Name {
+			return nil, fmt.Errorf("setting private=false makes the repo public: set confirm=%q to proceed", args.Name)
+		}
+	}
+
+	if args.Description == nil && args.Private == nil && args.Website == nil &&
+		args.DefaultBranch == nil && args.Archived == nil && args.Template == nil {
+		return nil, fmt.Errorf("at least one updatable field must be set: %w", gitea.ErrValidation)
+	}
+
+	r, err := t.c.UpdateRepo(ctx, args.Owner, args.Name, gitea.UpdateRepoArgs{
+		Description:   args.Description,
+		Private:       args.Private,
+		Website:       args.Website,
+		DefaultBranch: args.DefaultBranch,
+		Archived:      args.Archived,
+		Template:      args.Template,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return textOK(r)
+}

internal/tools/repo_update_test.go

@@ -0,0 +1,139 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func newRepoUpdateTool(srvURL string) *tools.RepoUpdate {
+	return tools.NewRepoUpdate(gitea.NewClient(srvURL, "tok"), allowlist.New([]string{"mathias"}))
+}
+
+// TestRepoUpdateArchive: happy path — set archived=true.
+func TestRepoUpdateArchive(t *testing.T) {
+	var patchedBody []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.Equal(t, http.MethodPatch, r.Method)
+		require.Equal(t, "/api/v1/repos/mathias/old-svc", r.URL.Path)
+		patchedBody, _ = io.ReadAll(r.Body)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"name":"old-svc","full_name":"mathias/old-svc","default_branch":"main","template":false,"private":false}`))
+	}))
+	defer srv.Close()
+
+	tool := newRepoUpdateTool(srv.URL)
+	result, err := tool.Call(context.Background(), json.RawMessage(
+		`{"owner":"mathias","name":"old-svc","archived":true}`,
+	))
+	require.NoError(t, err)
+
+	// Wire payload only contains the field that was actually set.
+	var sent map[string]any
+	require.NoError(t, json.Unmarshal(patchedBody, &sent))
+	assert.Equal(t, true, sent["archived"])
+	assert.NotContains(t, sent, "description")
+	assert.NotContains(t, sent, "private")
+	assert.NotContains(t, sent, "website")
+	assert.NotContains(t, sent, "template")
+
+	var repo gitea.Repo
+	require.NoError(t, json.Unmarshal(result, &repo))
+	assert.Equal(t, "mathias/old-svc", repo.FullName)
+}
+
+// TestRepoUpdateMultipleFields: set description + template flag in one call.
+func TestRepoUpdateMultipleFields(t *testing.T) {
+	var patchedBody []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		patchedBody, _ = io.ReadAll(r.Body)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"name":"template-go-agent","full_name":"mathias/template-go-agent","description":"Go agent template","template":true}`))
+	}))
+	defer srv.Close()
+
+	tool := newRepoUpdateTool(srv.URL)
+	_, err := tool.Call(context.Background(), json.RawMessage(
+		`{"owner":"mathias","name":"template-go-agent","description":"Go agent template","template":true}`,
+	))
+	require.NoError(t, err)
+
+	var sent map[string]any
+	require.NoError(t, json.Unmarshal(patchedBody, &sent))
+	assert.Equal(t, "Go agent template", sent["description"])
+	assert.Equal(t, true, sent["template"])
+	assert.NotContains(t, sent, "archived")
+	assert.NotContains(t, sent, "private")
+}
+
+// TestRepoUpdateNoFieldsRejected: zero updatable fields → validation error before network.
+func TestRepoUpdateNoFieldsRejected(t *testing.T) {
+	tool := tools.NewRepoUpdate(
+		gitea.NewClient("http://unused", ""),
+		allowlist.New([]string{"mathias"}),
+	)
+	_, err := tool.Call(context.Background(), json.RawMessage(
+		`{"owner":"mathias","name":"some-repo"}`,
+	))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrValidation)
+}
+
+// TestRepoUpdateMakePublic: explicit private=false is allowed; wire payload carries the false.
+// (The destructive nature is warned about in the tool description, not blocked by the tool.)
+func TestRepoUpdateMakePublic(t *testing.T) {
+	var patchedBody []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		patchedBody, _ = io.ReadAll(r.Body)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"name":"open-repo","full_name":"mathias/open-repo","private":false}`))
+	}))
+	defer srv.Close()
+
+	tool := newRepoUpdateTool(srv.URL)
+	_, err := tool.Call(context.Background(), json.RawMessage(
+		`{"owner":"mathias","name":"open-repo","private":false}`,
+	))
+	require.NoError(t, err)
+
+	var sent map[string]any
+	require.NoError(t, json.Unmarshal(patchedBody, &sent))
+	assert.Equal(t, false, sent["private"])
+}
+
+// TestRepoUpdateAllowlistRejects: owner outside allowlist denied without network call.
+func TestRepoUpdateAllowlistRejects(t *testing.T) {
+	tool := tools.NewRepoUpdate(
+		gitea.NewClient("http://unused", ""),
+		allowlist.New([]string{"mathias"}),
+	)
+	_, err := tool.Call(context.Background(), json.RawMessage(
+		`{"owner":"evil","name":"some-repo","archived":true}`,
+	))
+	require.Error(t, err)
+}
+
+// TestRepoUpdateUpstreamError: server 500 propagates as ErrUpstream.
+func TestRepoUpdateUpstreamError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		_, _ = w.Write([]byte(`{"message":"internal"}`))
+	}))
+	defer srv.Close()
+
+	tool := newRepoUpdateTool(srv.URL)
+	_, err := tool.Call(context.Background(), json.RawMessage(
+		`{"owner":"mathias","name":"some-repo","archived":true}`,
+	))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrUpstream)
+}

internal/tools/tag_create.go

@@ -0,0 +1,76 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
+)
+
+type TagCreate struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewTagCreate(c *gitea.Client, a *allowlist.Allowlist) *TagCreate {
+	return &TagCreate{c: c, a: a}
+}
+
+func (t *TagCreate) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "tag_create",
+		Description: "Create a tag pointing at a branch or commit SHA. Add a message to create an annotated tag.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"tag":{"type":"string"},
+				"target":{"type":"string"},
+				"message":{"type":"string"}
+			},
+			"required":["owner","name","tag","target"]
+		}`),
+	}
+}
+
+type tagCreateArgs struct {
+	Owner   string `json:"owner"`
+	Name    string `json:"name"`
+	Tag     string `json:"tag"`
+	Target  string `json:"target"`
+	Message string `json:"message"`
+}
+
+func (t *TagCreate) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args tagCreateArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+	if args.Tag == "" {
+		return nil, fmt.Errorf("tag is required: %w", gitea.ErrValidation)
+	}
+	if args.Target == "" {
+		return nil, fmt.Errorf("target is required: %w", gitea.ErrValidation)
+	}
+
+	tag, err := t.c.CreateTag(ctx, args.Owner, args.Name, gitea.CreateTagArgs{
+		TagName: args.Tag,
+		Target:  args.Target,
+		Message: args.Message,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return textOK(map[string]any{
+		"tag":        tag.Name,
+		"commit_sha": tag.Commit.Sha,
+	})
+}

internal/tools/tag_create_test.go

@@ -0,0 +1,52 @@
+package tools_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
+	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestTagCreateSuccess(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/owner/repo/tags", r.URL.Path)
+		assert.Equal(t, http.MethodPost, r.Method)
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{
+			"name":"v2.0.0","id":"tagsha",
+			"commit":{"sha":"cmt1","url":""}
+		}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewTagCreate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{
+		"owner":"owner","name":"repo","tag":"v2.0.0","target":"main"
+	}`))
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Equal(t, "v2.0.0", result["tag"])
+	assert.Equal(t, "cmt1", result["commit_sha"])
+}
+
+func TestTagCreateRequiresTag(t *testing.T) {
+	tool := tools.NewTagCreate(gitea.NewClient("http://unused", ""), allowlist.New([]string{"owner"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","target":"main"}`))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrValidation)
+}
+
+func TestTagCreateAllowlistRejects(t *testing.T) {
+	tool := tools.NewTagCreate(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"repo","tag":"v1.0.0","target":"main"}`))
+	require.Error(t, err)
+}

internal/tools/tool.go

@@ -1,7 +1,6 @@
 package tools
 
 import (
-	"context"
 	"encoding/json"
 
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
@@ -21,8 +20,6 @@ func parseArgs(raw json.RawMessage, dst any) error {
 	return json.Unmarshal(raw, dst)
 }
 
-func _ctx(ctx context.Context) context.Context { return ctx } // stub for future hooks
-
 // capLimit returns a sane page size: 0 or negative → def, > 50 → 50.
 func capLimit(in, def int) int {
 	if in <= 0 {

scripts/context-sync.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# Generates harness-specific context files from .context/PROJECT.md
+# Project-level script — run from a project directory.
+#
+# For Claude Code: generates project-only CLAUDE.md (it inherits root via tree walk)
+# For everything else: concatenates root AGENT.md + project PROJECT.md
+#
+# Usage: ./scripts/context-sync.sh [--force] [adapter...]
+# Task:  task context:sync
+#
+# Override root context: ROOT_CONTEXT=~/dev/.context/AGENT.md ./scripts/context-sync.sh
+
+set -euo pipefail
+
+# Parse --force flag and collect adapter names separately
+FORCE=false
+ADAPTERS=()
+for _arg in "$@"; do
+  case "$_arg" in
+    --force) FORCE=true ;;
+    *) ADAPTERS+=("$_arg") ;;
+  esac
+done
+
+PROJECT_FILE=".context/PROJECT.md"
+
+# Walk up to find root .context/AGENT.md
+find_root_context() {
+  local dir
+  dir="$(pwd)"
+  while [ "$dir" != "/" ]; do
+    dir="$(dirname "$dir")"
+    if [ -f "$dir/.context/AGENT.md" ]; then
+      echo "$dir/.context/AGENT.md"
+      return
+    fi
+  done
+  echo ""
+}
+
+ROOT_CONTEXT="${ROOT_CONTEXT:-$(find_root_context)}"
+
+if [ ! -f "$PROJECT_FILE" ]; then
+  echo "Error: $PROJECT_FILE not found. Are you in a project root?"
+  exit 1
+fi
+
+# Pre-flight: reject unfilled {{...}} placeholders unless --force
+if [ "$FORCE" = false ]; then
+  _placeholders=$(grep -n '{{[^}]*}}' "$PROJECT_FILE" 2>/dev/null || true)
+  if [ -n "$_placeholders" ]; then
+    echo "Error: unfilled placeholders in $PROJECT_FILE:" >&2
+    while IFS= read -r _match; do
+      _lineno="${_match%%:*}"
+      _content="${_match#*:}"
+      _token=$(printf '%s' "$_content" | grep -o '{{[^}]*}}' | head -1)
+      echo "  $PROJECT_FILE:$_lineno: unfilled placeholder $_token" >&2
+    done <<< "$_placeholders"
+    echo "" >&2
+    echo "Fill these placeholders, then re-run: task context:sync" >&2
+    echo "To bypass validation: bash scripts/context-sync.sh --force" >&2
+    exit 1
+  fi
+fi
+
+if [ -n "$ROOT_CONTEXT" ] && [ -f "$ROOT_CONTEXT" ]; then
+  echo "  Root context: $ROOT_CONTEXT"
+else
+  echo "  No root AGENT.md found (project context only)"
+fi
+
+# Emit root context + separator
+root_block() {
+  if [ -n "$ROOT_CONTEXT" ] && [ -f "$ROOT_CONTEXT" ]; then
+    cat "$ROOT_CONTEXT"
+    echo ""
+    echo "---"
+    echo ""
+  fi
+}
+
+# ── Claude Code ──────────────────────────────────────────────
+# Claude Code walks up the tree — it finds ~/dev/CLAUDE.md automatically.
+# Project-level CLAUDE.md only needs project-specific context.
+generate_claude() {
+  cat "$PROJECT_FILE" > CLAUDE.md
+  echo "  → CLAUDE.md (project-only; Claude Code inherits root)"
+}
+
+# ── AGENTS.md (Crush, Pi, Antigravity) ──────────────────────
+# These tools read AGENTS.md from cwd but don't walk up.
+# Concatenate root + project.
+generate_agents() {
+  { root_block; cat "$PROJECT_FILE"; } > AGENTS.md
+  echo "  → AGENTS.md (root + project; Crush, Pi, Antigravity)"
+}
+
+# ── Cursor ───────────────────────────────────────────────────
+generate_cursor() {
+  {
+    echo "# Cursor rules — auto-generated"
+    echo "# Do not edit. Run: task context:sync"
+    echo ""
+    root_block
+    cat "$PROJECT_FILE"
+  } > .cursorrules
+  echo "  → .cursorrules (root + project)"
+}
+
+# ── Aider ────────────────────────────────────────────────────
+generate_aider() {
+  { root_block; cat "$PROJECT_FILE"; } > .aider.conventions.md
+  if [ ! -f .aider.conf.yml ]; then
+    cat > .aider.conf.yml << 'YAML'
+read: .aider.conventions.md
+auto-commits: false
+YAML
+  fi
+  echo "  → .aider.conventions.md (root + project)"
+}
+
+# ── Generic system prompt (Open WebUI, Mods, etc.) ──────────
+generate_system_prompt() {
+  {
+    echo "You are a coding assistant working on a specific project."
+    echo "Follow all conventions from both the root agent context and project context."
+    echo ""
+    echo "---"
+    echo ""
+    root_block
+    cat "$PROJECT_FILE"
+    echo ""
+    echo "---"
+  } > .context/system-prompt.txt
+  echo "  → .context/system-prompt.txt (root + project)"
+}
+
+# ── MCP config ───────────────────────────────────────────────
+generate_mcp() {
+  # Ensure baseline file exists with project-specific knowledge server
+  if [ ! -f .context/mcp.json ]; then
+    cat > .context/mcp.json << 'JSON'
+{
+  "mcpServers": {
+    "knowledge": {
+      "url": "http://localhost:3100/mcp",
+      "description": "Project knowledge base — vector + graph retrieval"
+    }
+  }
+}
+JSON
+  fi
+
+  # Merge root mcp-servers.json if found alongside root AGENT.md
+  local root_mcp=""
+  if [ -n "$ROOT_CONTEXT" ] && [ -f "$ROOT_CONTEXT" ]; then
+    local candidate
+    candidate="$(dirname "$ROOT_CONTEXT")/mcp-servers.json"
+    [ -f "$candidate" ] && root_mcp="$candidate"
+  fi
+
+  if [ -z "$root_mcp" ]; then
+    echo "  → .context/mcp.json (exists, no root mcp-servers.json found)"
+    return
+  fi
+
+  # Root servers take precedence over project entries on key conflict
+  local root_servers count updated
+  root_servers=$(jq '.servers' "$root_mcp")
+  count=$(printf '%s' "$root_servers" | jq 'keys | length')
+  updated=$(jq --argjson root "$root_servers" \
+    '.mcpServers = (.mcpServers + $root)' \
+    .context/mcp.json)
+  printf '%s\n' "$updated" > .context/mcp.json
+  echo "  → .context/mcp.json (merged $count root servers)"
+}
+
+echo "Syncing project context from $PROJECT_FILE..."
+
+if [ ${#ADAPTERS[@]} -eq 0 ]; then
+  generate_claude
+  generate_agents
+  generate_cursor
+  generate_aider
+  generate_system_prompt
+  generate_mcp
+else
+  for adapter in "${ADAPTERS[@]}"; do
+    case "$adapter" in
+      claude)  generate_claude ;;
+      agents)  generate_agents ;;
+      cursor)  generate_cursor ;;
+      aider)   generate_aider ;;
+      prompt|system|openwebui|owui|generic) generate_system_prompt ;;
+      mcp)     generate_mcp ;;
+      *) echo "Unknown adapter: $adapter" >&2; exit 1 ;;
+    esac
+  done
+fi
+
+echo "Done."