Merge pull request 'feat(tools): repo_tree, repo_topics_update, file_read dir fix (#14, #15, #18)' (#22) from feat/repo-ux into main

repo_tree: GET /git/trees/{ref}?recursive=1 — full recursive file tree
repo_topics_update: PUT /repos/{owner}/{repo}/topics — replace topic list
file_read: detect array response and return descriptive error for dir paths

.aider.conf.yml

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

.aider.conventions.md

@@ -0,0 +1,318 @@
+# 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).
+5. **Branch-per-task for multi-agent repos.** When another agent may be active on
+   the same repo, create a branch (`agent/<description>`), commit there, and open a
+   PR. Do not merge without explicit instruction from Mathias.
+
+## 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 | — | — |
+| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — |
+
+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, google.golang.org/adk (agent projects only) 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
+
+## Current sprint — gitea-mcp v0.2 (2026-05-14)
+
+### Context
+This sprint implements new MCP tools needed for `hyperguild new-project` —
+the automated project creation flow triggered from claude.ai. See brain knowledge
+nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
+for full background.
+
+### Issues to implement (priority order)
+
+**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
+| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
+| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
+
+**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
+| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
+| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
+
+**Batch 3 — can wait**
+
+| Issue | Tool | Note |
+|-------|------|------|
+| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
+| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
+
+### How to add a tool (pattern)
+
+Every tool = 4 files following `internal/tools/repo_get.go` exactly:
+
+1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
+2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
+3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
+4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
+
+Key rules:
+- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
+- Use `textOK(result)` for success output
+- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
+- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
+
+### Token permissions needed
+
+New tools require these additional Gitea token scopes:
+- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
+- `delete_repo` — repo_delete
+
+Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
+If scopes are missing, update token in Gitea settings before running tests.
+
+### Definition of done
+
+- `task check` passes (all tools, all batches)
+- Each new tool manually callable via `claude mcp call`
+- PR #1 (batch 1) merged before starting batch 2
+- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed

.context/PROJECT.md

@@ -0,0 +1,143 @@
+# 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
+
+## Current sprint — gitea-mcp v0.2 (2026-05-14)
+
+### Context
+This sprint implements new MCP tools needed for `hyperguild new-project` —
+the automated project creation flow triggered from claude.ai. See brain knowledge
+nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
+for full background.
+
+### Issues to implement (priority order)
+
+**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
+| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
+| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
+
+**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
+| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
+| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
+
+**Batch 3 — can wait**
+
+| Issue | Tool | Note |
+|-------|------|------|
+| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
+| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
+
+### How to add a tool (pattern)
+
+Every tool = 4 files following `internal/tools/repo_get.go` exactly:
+
+1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
+2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
+3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
+4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
+
+Key rules:
+- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
+- Use `textOK(result)` for success output
+- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
+- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
+
+### Token permissions needed
+
+New tools require these additional Gitea token scopes:
+- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
+- `delete_repo` — repo_delete
+
+Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
+If scopes are missing, update token in Gitea settings before running tests.
+
+### Definition of done
+
+- `task check` passes (all tools, all batches)
+- Each new tool manually callable via `claude mcp call`
+- PR #1 (batch 1) merged before starting batch 2
+- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed

.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,325 @@
+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).
+5. **Branch-per-task for multi-agent repos.** When another agent may be active on
+   the same repo, create a branch (`agent/<description>`), commit there, and open a
+   PR. Do not merge without explicit instruction from Mathias.
+
+## 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 | — | — |
+| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — |
+
+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, google.golang.org/adk (agent projects only) 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
+
+## Current sprint — gitea-mcp v0.2 (2026-05-14)
+
+### Context
+This sprint implements new MCP tools needed for `hyperguild new-project` —
+the automated project creation flow triggered from claude.ai. See brain knowledge
+nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
+for full background.
+
+### Issues to implement (priority order)
+
+**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
+| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
+| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
+
+**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
+| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
+| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
+
+**Batch 3 — can wait**
+
+| Issue | Tool | Note |
+|-------|------|------|
+| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
+| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
+
+### How to add a tool (pattern)
+
+Every tool = 4 files following `internal/tools/repo_get.go` exactly:
+
+1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
+2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
+3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
+4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
+
+Key rules:
+- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
+- Use `textOK(result)` for success output
+- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
+- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
+
+### Token permissions needed
+
+New tools require these additional Gitea token scopes:
+- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
+- `delete_repo` — repo_delete
+
+Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
+If scopes are missing, update token in Gitea settings before running tests.
+
+### Definition of done
+
+- `task check` passes (all tools, all batches)
+- Each new tool manually callable via `claude mcp call`
+- PR #1 (batch 1) merged before starting batch 2
+- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed
+
+---

.cursorrules

@@ -0,0 +1,321 @@
+# 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).
+5. **Branch-per-task for multi-agent repos.** When another agent may be active on
+   the same repo, create a branch (`agent/<description>`), commit there, and open a
+   PR. Do not merge without explicit instruction from Mathias.
+
+## 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 | — | — |
+| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — |
+
+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, google.golang.org/adk (agent projects only) 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
+
+## Current sprint — gitea-mcp v0.2 (2026-05-14)
+
+### Context
+This sprint implements new MCP tools needed for `hyperguild new-project` —
+the automated project creation flow triggered from claude.ai. See brain knowledge
+nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
+for full background.
+
+### Issues to implement (priority order)
+
+**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
+| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
+| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
+
+**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
+| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
+| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
+
+**Batch 3 — can wait**
+
+| Issue | Tool | Note |
+|-------|------|------|
+| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
+| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
+
+### How to add a tool (pattern)
+
+Every tool = 4 files following `internal/tools/repo_get.go` exactly:
+
+1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
+2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
+3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
+4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
+
+Key rules:
+- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
+- Use `textOK(result)` for success output
+- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
+- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
+
+### Token permissions needed
+
+New tools require these additional Gitea token scopes:
+- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
+- `delete_repo` — repo_delete
+
+Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
+If scopes are missing, update token in Gitea settings before running tests.
+
+### Definition of done
+
+- `task check` passes (all tools, all batches)
+- Each new tool manually callable via `claude mcp call`
+- PR #1 (batch 1) merged before starting batch 2
+- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed

.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,318 @@
+# 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).
+5. **Branch-per-task for multi-agent repos.** When another agent may be active on
+   the same repo, create a branch (`agent/<description>`), commit there, and open a
+   PR. Do not merge without explicit instruction from Mathias.
+
+## 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 | — | — |
+| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — |
+
+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, google.golang.org/adk (agent projects only) 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
+
+## Current sprint — gitea-mcp v0.2 (2026-05-14)
+
+### Context
+This sprint implements new MCP tools needed for `hyperguild new-project` —
+the automated project creation flow triggered from claude.ai. See brain knowledge
+nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
+for full background.
+
+### Issues to implement (priority order)
+
+**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
+| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
+| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
+
+**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
+| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
+| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
+
+**Batch 3 — can wait**
+
+| Issue | Tool | Note |
+|-------|------|------|
+| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
+| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
+
+### How to add a tool (pattern)
+
+Every tool = 4 files following `internal/tools/repo_get.go` exactly:
+
+1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
+2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
+3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
+4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
+
+Key rules:
+- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
+- Use `textOK(result)` for success output
+- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
+- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
+
+### Token permissions needed
+
+New tools require these additional Gitea token scopes:
+- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
+- `delete_repo` — repo_delete
+
+Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
+If scopes are missing, update token in Gitea settings before running tests.
+
+### Definition of done
+
+- `task check` passes (all tools, all batches)
+- Each new tool manually callable via `claude mcp call`
+- PR #1 (batch 1) merged before starting batch 2
+- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed

CLAUDE.md

@@ -0,0 +1,143 @@
+# 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
+
+## Current sprint — gitea-mcp v0.2 (2026-05-14)
+
+### Context
+This sprint implements new MCP tools needed for `hyperguild new-project` —
+the automated project creation flow triggered from claude.ai. See brain knowledge
+nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
+for full background.
+
+### Issues to implement (priority order)
+
+**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
+| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
+| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
+
+**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
+
+| Issue | Tool | Gitea API |
+|-------|------|-----------|
+| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
+| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
+| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
+
+**Batch 3 — can wait**
+
+| Issue | Tool | Note |
+|-------|------|------|
+| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
+| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
+
+### How to add a tool (pattern)
+
+Every tool = 4 files following `internal/tools/repo_get.go` exactly:
+
+1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
+2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
+3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
+4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
+
+Key rules:
+- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
+- Use `textOK(result)` for success output
+- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
+- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
+
+### Token permissions needed
+
+New tools require these additional Gitea token scopes:
+- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
+- `delete_repo` — repo_delete
+
+Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
+If scopes are missing, update token in Gitea settings before running tests.
+
+### Definition of done
+
+- `task check` passes (all tools, all batches)
+- Each new tool manually callable via `claude mcp call`
+- PR #1 (batch 1) merged before starting batch 2
+- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed

Taskfile.yml

@@ -14,9 +14,42 @@ tasks:
   lint:
     desc: Run golangci-lint
     cmds: [golangci-lint run ./...]
-  check:
+  vet:
-    desc: Lint, vet, and test (used by CI)
     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,7 +25,14 @@ func main() {
 		os.Exit(1)
 	}
 
-	giteaClient := gitea.NewClient(cfg.GiteaBaseURL, "")
+	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()
@@ -51,6 +60,11 @@ func main() {
 	reg.Register(tools.NewIssueComment(giteaClient, ownerAllow))
 	reg.Register(tools.NewCreateProjectFromTemplate(giteaClient, ownerAllow, "mathias", "template-go-web"))
 	reg.Register(tools.NewTagCreate(giteaClient, ownerAllow))
+	reg.Register(tools.NewRepoCreate(giteaClient, ownerAllow))
+	reg.Register(tools.NewRepoUpdate(giteaClient, ownerAllow))
+	reg.Register(tools.NewRepoMirrorPush(giteaClient, ownerAllow))
+	reg.Register(tools.NewRepoTree(giteaClient, ownerAllow))
+	reg.Register(tools.NewRepoTopicsUpdate(giteaClient, ownerAllow))
 
 	mcpSrv := mcp.NewServer(mcp.ServerOptions{
 		Registry: reg,
@@ -59,7 +73,7 @@ func main() {
 
 	mux := http.NewServeMux()
 	mux.Handle("/mcp", mcp.OriginAllowlist(cfg.OriginAllowlist)(
-		auth.BearerMiddleware(cfg.GiteaBaseURL,
+		auth.BearerMiddleware(jwtValidator, cfg.StaticToken,
 			auth.CallerMiddleware(mcpSrv),
 		),
 	))
@@ -73,11 +87,14 @@ func main() {
 			return
 		}
 		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusOK)
+		payload := map[string]any{
-		_, _ = w.Write([]byte(`{"authorization_servers":[]}`))
+			"resource":             cfg.MCPResourceURL,
-	})
+			"authorization_servers": []string{},
-	mux.HandleFunc("/.well-known/oauth-authorization-server", func(w http.ResponseWriter, r *http.Request) {
+		}
-		http.NotFound(w, r)
+		if cfg.DexIssuerURL != "" {
+			payload["authorization_servers"] = []string{cfg.DexIssuerURL}
+		}
+		_ = json.NewEncoder(w).Encode(payload)
 	})
 
 	addr := ":" + cfg.Port

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

@@ -1,49 +1,42 @@
 package auth
 
 import (
-	"context"
+	"crypto/subtle"
 	"net/http"
 	"strings"
-	"time"
 )
 
-type tokenKey struct{}
+// BearerMiddleware authenticates requests via the Authorization header.
-
+//
-// BearerMiddleware validates the incoming bearer token as a Gitea PAT by
+// A request is allowed when:
-// calling GET /api/v1/user. The validated token is stored in context for
+//
-// downstream use by the Gitea client.
+//  1. The Bearer token is a valid JWT issued by the configured Dex OIDC server, or
-func BearerMiddleware(giteaBaseURL string, next http.Handler) http.Handler {
+//  2. The Bearer token matches staticToken (constant-time compare).
-	hc := &http.Client{Timeout: 5 * time.Second}
+//
+// 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) {
-		token, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
+		bearer, hasBearer := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
-		if !ok || token == "" {
+		if !hasBearer || bearer == "" {
 			http.Error(w, "unauthorized", http.StatusUnauthorized)
 			return
 		}
-		req, err := http.NewRequestWithContext(r.Context(), http.MethodGet, giteaBaseURL+"/api/v1/user", nil)
+
-		if err != nil {
+		if jwtValidator.Validate(r.Context(), bearer) {
-			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			next.ServeHTTP(w, r)
 			return
 		}
-		req.Header.Set("Authorization", "token "+token)
+
-		resp, err := hc.Do(req)
+		if staticToken != "" && subtle.ConstantTimeCompare([]byte(bearer), []byte(staticToken)) == 1 {
-		if err != nil || resp.StatusCode != http.StatusOK {
+			next.ServeHTTP(w, r)
-			if resp != nil {
-				_ = resp.Body.Close()
-			}
-			http.Error(w, "unauthorized", http.StatusUnauthorized)
 			return
 		}
-		_ = resp.Body.Close()
+
-		ctx := context.WithValue(r.Context(), tokenKey{}, token)
+		http.Error(w, "unauthorized", http.StatusUnauthorized)
-		next.ServeHTTP(w, r.WithContext(ctx))
 	})
 }
-
-// TokenFromContext returns the validated Gitea PAT stored by BearerMiddleware.
-func TokenFromContext(ctx context.Context) string {
-	if v, ok := ctx.Value(tokenKey{}).(string); ok {
-		return v
-	}
-	return ""
-}

internal/auth/bearer_test.go

@@ -10,73 +10,83 @@ import (
 	"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("https://gitea.example.com",
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, "", okHandler(nil)))
-		http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-			w.WriteHeader(http.StatusOK)
-		}),
-	))
 	defer srv.Close()
 
 	resp, err := http.Post(srv.URL+"/mcp", "application/json", nil)
 	require.NoError(t, err)
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
 }
 
-func TestBearerMiddleware_InvalidToken(t *testing.T) {
+func TestBearerMiddleware_NoAuthHeader_RejectsEvenWhenStaticConfigured(t *testing.T) {
-	// Mock Gitea that rejects the token
+	// A configured staticToken must not allow unauthenticated callers through.
-	giteaMock := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, "any-static", okHandler(nil)))
-		w.WriteHeader(http.StatusUnauthorized)
+	defer srv.Close()
-	}))
-	defer giteaMock.Close()
 
-	srv := httptest.NewServer(auth.BearerMiddleware(giteaMock.URL,
+	resp, err := http.Post(srv.URL+"/mcp", "application/json", nil)
-		http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+	require.NoError(t, err)
-			w.WriteHeader(http.StatusOK)
+	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 bad-token")
+	req.Header.Set("Authorization", "Bearer ")
 	resp, err := http.DefaultClient.Do(req)
 	require.NoError(t, err)
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
 }
 
-func TestBearerMiddleware_ValidToken(t *testing.T) {
+func TestBearerMiddleware_StaticToken_Valid(t *testing.T) {
-	const token = "valid-pat"
+	const staticToken = "my-static-token"
-
-	// Mock Gitea that accepts the token and returns a user
-	giteaMock := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		assert.Equal(t, "token "+token, r.Header.Get("Authorization"))
-		w.WriteHeader(http.StatusOK)
-	}))
-	defer giteaMock.Close()
-
 	called := false
-	srv := httptest.NewServer(auth.BearerMiddleware(giteaMock.URL,
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, staticToken, okHandler(&called)))
-		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			called = true
-			// Token must be available in context for downstream Gitea client
-			assert.Equal(t, token, auth.TokenFromContext(r.Context()))
-			w.WriteHeader(http.StatusOK)
-		}),
-	))
 	defer srv.Close()
 
 	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/mcp", nil)
-	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("Authorization", "Bearer "+staticToken)
 	resp, err := http.DefaultClient.Do(req)
 	require.NoError(t, err)
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 	assert.Equal(t, http.StatusOK, resp.StatusCode)
 	assert.True(t, called)
 }
 
-func TestTokenFromContext_Empty(t *testing.T) {
+func TestBearerMiddleware_StaticToken_Invalid(t *testing.T) {
-	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	srv := httptest.NewServer(auth.BearerMiddleware(nil, "correct-token", okHandler(nil)))
-	assert.Equal(t, "", auth.TokenFromContext(req.Context()))
+	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,16 +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
+	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"),
+		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/gitea/client.go

@@ -7,7 +7,6 @@ import (
 	"net/http"
 	"time"
 
-	"gitea.d-ma.be/mathias/gitea-mcp/internal/auth"
 	"github.com/hashicorp/golang-lru/v2/expirable"
 )
 
@@ -50,10 +49,7 @@ func (c *Client) doOnce(ctx context.Context, method, path string, body []byte) (
 	if err != nil {
 		return nil, 0, err
 	}
-	token := auth.TokenFromContext(ctx)
+	token := c.token
-	if token == "" {
-		token = c.token
-	}
 	if token != "" {
 		req.Header.Set("Authorization", "token "+token)
 	}
@@ -119,10 +115,7 @@ func (c *Client) doRaw(ctx context.Context, method, path string, body []byte) (*
 	if err != nil {
 		return nil, err
 	}
-	token := auth.TokenFromContext(ctx)
+	token := c.token
-	if token == "" {
-		token = c.token
-	}
 	if token != "" {
 		req.Header.Set("Authorization", "token "+token)
 	}

internal/gitea/files.go

@@ -27,6 +27,10 @@ func (c *Client) GetFileContents(ctx context.Context, owner, repo, path, ref str
 	if err := MapStatus(status, body); err != nil {
 		return nil, err
 	}
+	// Array response means path is a directory — guide caller to dir_list.
+	if len(body) > 0 && body[0] == '[' {
+		return nil, fmt.Errorf("%w: path %q is a directory, not a file — use dir_list", ErrValidation, path)
+	}
 	var fc FileContents
 	if err := json.Unmarshal(body, &fc); err != nil {
 		return nil, err

internal/gitea/mirrors.go

@@ -0,0 +1,71 @@
+package gitea
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+)
+
+type PushMirror struct {
+	ID            int    `json:"id"`
+	RemoteName    string `json:"remote_name"`
+	RemoteAddress string `json:"remote_address"`
+	Interval      string `json:"interval"`
+	SyncOnCommit  bool   `json:"sync_on_commit"`
+}
+
+type AddPushMirrorArgs struct {
+	RemoteAddress  string `json:"remote_address"`
+	RemoteUsername string `json:"remote_username,omitempty"`
+	RemotePassword string `json:"remote_password,omitempty"`
+	Interval       string `json:"interval,omitempty"`
+	SyncOnCommit   bool   `json:"sync_on_commit,omitempty"`
+}
+
+func (c *Client) AddPushMirror(ctx context.Context, owner, repo string, args AddPushMirrorArgs) (*PushMirror, error) {
+	path := fmt.Sprintf("/api/v1/repos/%s/%s/push_mirrors", owner, repo)
+	body, err := json.Marshal(args)
+	if err != nil {
+		return nil, err
+	}
+	resp, status, err := c.PostJSON(ctx, path, body)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, resp); err != nil {
+		return nil, err
+	}
+	var m PushMirror
+	if err := json.Unmarshal(resp, &m); err != nil {
+		return nil, err
+	}
+	return &m, nil
+}
+
+func (c *Client) ListPushMirrors(ctx context.Context, owner, repo string) ([]PushMirror, error) {
+	path := fmt.Sprintf("/api/v1/repos/%s/%s/push_mirrors", owner, repo)
+	resp, status, err := c.GetJSON(ctx, path)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, resp); err != nil {
+		return nil, err
+	}
+	var mirrors []PushMirror
+	if err := json.Unmarshal(resp, &mirrors); err != nil {
+		return nil, err
+	}
+	return mirrors, nil
+}
+
+func (c *Client) DeletePushMirror(ctx context.Context, owner, repo, mirrorName string) error {
+	path := fmt.Sprintf("/api/v1/repos/%s/%s/push_mirrors/%s", owner, repo, mirrorName)
+	resp, status, err := c.DeleteJSON(ctx, path)
+	if err != nil {
+		return err
+	}
+	if status == 204 {
+		return nil
+	}
+	return MapStatus(status, resp)
+}

internal/gitea/mirrors_test.go

@@ -0,0 +1,64 @@
+package gitea_test
+
+import (
+	"context"
+	"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 TestAddPushMirror(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPost, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra/push_mirrors", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"id":1,"remote_name":"mirror-github","remote_address":"https://github.com/mathias/infra.git","interval":"8h0m0s","sync_on_commit":true}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	m, err := c.AddPushMirror(context.Background(), "mathias", "infra", gitea.AddPushMirrorArgs{
+		RemoteAddress:  "https://github.com/mathias/infra.git",
+		RemoteUsername: "mathias",
+		RemotePassword: "secret",
+		Interval:       "8h0m0s",
+		SyncOnCommit:   true,
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "mirror-github", m.RemoteName)
+	assert.Equal(t, "https://github.com/mathias/infra.git", m.RemoteAddress)
+}
+
+func TestListPushMirrors(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodGet, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra/push_mirrors", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"id":1,"remote_name":"mirror-github","remote_address":"https://github.com/mathias/infra.git","interval":"8h0m0s","sync_on_commit":true}]`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	mirrors, err := c.ListPushMirrors(context.Background(), "mathias", "infra")
+	require.NoError(t, err)
+	require.Len(t, mirrors, 1)
+	assert.Equal(t, "mirror-github", mirrors[0].RemoteName)
+}
+
+func TestDeletePushMirror(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodDelete, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra/push_mirrors/mirror-github", r.URL.Path)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	err := c.DeletePushMirror(context.Background(), "mathias", "infra", "mirror-github")
+	require.NoError(t, err)
+}

internal/gitea/repos.go

@@ -18,6 +18,56 @@ type Repo struct {
 	Template      bool   `json:"template"`
 }
 
+type TreeEntry struct {
+	Path string `json:"path"`
+	Type string `json:"type"` // "blob" or "tree"
+	SHA  string `json:"sha"`
+	Size int64  `json:"size"`
+	URL  string `json:"url"`
+}
+
+type Tree struct {
+	SHA       string      `json:"sha"`
+	URL       string      `json:"url"`
+	Tree      []TreeEntry `json:"tree"`
+	Truncated bool        `json:"truncated"`
+}
+
+func (c *Client) GetTree(ctx context.Context, owner, repo, ref string, recursive bool) (*Tree, error) {
+	path := fmt.Sprintf("/api/v1/repos/%s/%s/git/trees/%s", owner, repo, url.PathEscape(ref))
+	if recursive {
+		path += "?recursive=1"
+	}
+	body, status, err := c.GetJSON(ctx, path)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, body); err != nil {
+		return nil, err
+	}
+	var t Tree
+	if err := json.Unmarshal(body, &t); err != nil {
+		return nil, err
+	}
+	return &t, nil
+}
+
+func (c *Client) UpdateTopics(ctx context.Context, owner, repo string, topics []string) error {
+	path := fmt.Sprintf("/api/v1/repos/%s/%s/topics", owner, repo)
+	body, err := json.Marshal(map[string][]string{"topics": topics})
+	if err != nil {
+		return err
+	}
+	resp, status, err := c.PutJSON(ctx, path, body)
+	if err != nil {
+		return err
+	}
+	if status == 204 {
+		return nil
+	}
+	return MapStatus(status, resp)
+}
+
 func (c *Client) ListRepos(ctx context.Context, owner string, page, limit int) ([]Repo, error) {
 	if page < 1 {
 		page = 1
@@ -71,6 +121,70 @@ func (c *Client) SearchRepos(ctx context.Context, q, owner string, page, limit i
 	return env.Data, nil
 }
 
+type CreateRepoArgs struct {
+	Name          string `json:"name"`
+	Description   string `json:"description,omitempty"`
+	Private       bool   `json:"private,omitempty"`
+	AutoInit      bool   `json:"auto_init,omitempty"`
+	DefaultBranch string `json:"default_branch,omitempty"`
+	// Org, when non-empty, creates the repo under the named organisation.
+	// Uses POST /api/v1/orgs/{org}/repos instead of /api/v1/user/repos.
+	Org string `json:"-"`
+}
+
+func (c *Client) CreateRepo(ctx context.Context, args CreateRepoArgs) (*Repo, error) {
+	var path string
+	if args.Org != "" {
+		path = fmt.Sprintf("/api/v1/orgs/%s/repos", args.Org)
+	} else {
+		path = "/api/v1/user/repos"
+	}
+	body, err := json.Marshal(args)
+	if err != nil {
+		return nil, err
+	}
+	resp, status, err := c.PostJSON(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
+}
+
+// UpdateRepoArgs uses pointers so omitempty can distinguish "not set" from false/zero.
+type UpdateRepoArgs struct {
+	Description   *string `json:"description,omitempty"`
+	Private       *bool   `json:"private,omitempty"`
+	Website       *string `json:"website,omitempty"`
+	DefaultBranch *string `json:"default_branch,omitempty"`
+}
+
+func (c *Client) UpdateRepo(ctx context.Context, owner, name string, args UpdateRepoArgs) (*Repo, error) {
+	path := fmt.Sprintf("/api/v1/repos/%s/%s", owner, name)
+	body, err := json.Marshal(args)
+	if err != nil {
+		return nil, err
+	}
+	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
+}
+
 func (c *Client) GetRepo(ctx context.Context, owner, name string) (*Repo, error) {
 	path := fmt.Sprintf("/api/v1/repos/%s/%s", owner, name)
 	body, status, err := c.GetJSON(ctx, path)

internal/gitea/repos_test.go

@@ -47,6 +47,95 @@ func TestListRepos(t *testing.T) {
 	assert.Equal(t, "main", repos[0].DefaultBranch)
 }
 
+func TestCreateRepo_User(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPost, r.Method)
+		assert.Equal(t, "/api/v1/user/repos", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"name":"infra","full_name":"mathias/infra","default_branch":"main","private":true,"clone_url":"https://gitea.example.com/mathias/infra.git","html_url":"https://gitea.example.com/mathias/infra"}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	r, err := c.CreateRepo(context.Background(), gitea.CreateRepoArgs{
+		Name:    "infra",
+		Private: true,
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "mathias/infra", r.FullName)
+	assert.Equal(t, "main", r.DefaultBranch)
+}
+
+func TestCreateRepo_Org(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPost, r.Method)
+		assert.Equal(t, "/api/v1/orgs/hyperguild/repos", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"name":"infra","full_name":"hyperguild/infra","default_branch":"main","private":false,"clone_url":"https://gitea.example.com/hyperguild/infra.git","html_url":"https://gitea.example.com/hyperguild/infra"}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	r, err := c.CreateRepo(context.Background(), gitea.CreateRepoArgs{
+		Name:  "infra",
+		Org:   "hyperguild",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "hyperguild/infra", r.FullName)
+}
+
+func TestUpdateRepo(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPatch, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"name":"infra","full_name":"mathias/infra","default_branch":"main","description":"updated","private":false,"clone_url":"https://gitea.example.com/mathias/infra.git","html_url":"https://gitea.example.com/mathias/infra"}`))
+	}))
+	defer srv.Close()
+
+	desc := "updated"
+	c := gitea.NewClient(srv.URL, "tok")
+	r, err := c.UpdateRepo(context.Background(), "mathias", "infra", gitea.UpdateRepoArgs{
+		Description: &desc,
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "updated", r.Description)
+}
+
+func TestGetTree(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/mathias/infra/git/trees/main", r.URL.Path)
+		assert.Equal(t, "1", r.URL.Query().Get("recursive"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"sha":"abc","url":"http://x","tree":[{"path":"README.md","type":"blob","sha":"def","size":13},{"path":"internal","type":"tree","sha":"ghi"}],"truncated":false}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	tree, err := c.GetTree(context.Background(), "mathias", "infra", "main", true)
+	require.NoError(t, err)
+	assert.Equal(t, "abc", tree.SHA)
+	require.Len(t, tree.Tree, 2)
+	assert.Equal(t, "README.md", tree.Tree[0].Path)
+	assert.Equal(t, "blob", tree.Tree[0].Type)
+	assert.Equal(t, int64(13), tree.Tree[0].Size)
+}
+
+func TestUpdateTopics(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPut, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra/topics", r.URL.Path)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	err := c.UpdateTopics(context.Background(), "mathias", "infra", []string{"go", "mcp", "gitops"})
+	require.NoError(t, err)
+}
+
 func TestDefaultBranchCachesAcrossCalls(t *testing.T) {
 	var hits int32
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {

internal/mcp/server.go

@@ -56,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)
@@ -68,11 +67,12 @@ func (s *Server) handlePOST(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	sid := r.Header.Get("Mcp-Session-Id")
+	// Mcp-Session-Id is advisory: we issue one on initialize and accept it back,
-	if !s.opts.Sessions.Valid(sid) {
+	// but every tool the gitea-mcp server exposes is stateless single-shot, so
-		http.Error(w, "missing or invalid Mcp-Session-Id", http.StatusBadRequest)
+	// we do not gate non-initialize calls on it. The claude.ai connector's
-		return
+	// 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":

internal/mcp/server_test.go

@@ -57,14 +57,22 @@ func TestInitialize(t *testing.T) {
 	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) {

internal/tools/file_read_test.go

@@ -57,6 +57,21 @@ func TestFileReadToolDefaultBranchResolution(t *testing.T) {
 	assert.Equal(t, "main", result["ref"])
 }
 
+func TestFileReadOnDirReturnsDescriptiveError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Gitea returns an array when path is a directory
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"name":"README.md","path":"internal/README.md","type":"file","sha":"abc"}]`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewFileRead(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","path":"internal","ref":"main"}`))
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "directory")
+	assert.Contains(t, err.Error(), "dir_list")
+}
+
 func TestFileReadAllowlistRejects(t *testing.T) {
 	tool := tools.NewFileRead(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"infra","path":"README.md"}`))

internal/tools/repo_create.go

@@ -0,0 +1,74 @@
+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 RepoCreate struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewRepoCreate(c *gitea.Client, a *allowlist.Allowlist) *RepoCreate {
+	return &RepoCreate{c: c, a: a}
+}
+
+func (t *RepoCreate) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "repo_create",
+		Description: "Create a repository for the authenticated user or an organisation.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string","description":"Username or org name (used for allowlist check)."},
+				"name":{"type":"string","description":"Repository name."},
+				"description":{"type":"string"},
+				"private":{"type":"boolean","description":"Create as private. Default false."},
+				"auto_init":{"type":"boolean","description":"Initialise with README."},
+				"default_branch":{"type":"string","description":"Default branch name. Default 'main'."},
+				"is_org":{"type":"boolean","description":"When true, create under the organisation named in 'owner'."}
+			},
+			"required":["owner","name"]
+		}`),
+	}
+}
+
+type repoCreateArgs struct {
+	Owner         string `json:"owner"`
+	Name          string `json:"name"`
+	Description   string `json:"description"`
+	Private       bool   `json:"private"`
+	AutoInit      bool   `json:"auto_init"`
+	DefaultBranch string `json:"default_branch"`
+	IsOrg         bool   `json:"is_org"`
+}
+
+func (t *RepoCreate) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args repoCreateArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+	createArgs := gitea.CreateRepoArgs{
+		Name:          args.Name,
+		Description:   args.Description,
+		Private:       args.Private,
+		AutoInit:      args.AutoInit,
+		DefaultBranch: args.DefaultBranch,
+	}
+	if args.IsOrg {
+		createArgs.Org = args.Owner
+	}
+	r, err := t.c.CreateRepo(ctx, createArgs)
+	if err != nil {
+		return nil, err
+	}
+	return textOK(r)
+}

internal/tools/repo_create_test.go

@@ -0,0 +1,53 @@
+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 TestRepoCreateTool_User(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPost, r.Method)
+		assert.Equal(t, "/api/v1/user/repos", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"name":"infra","full_name":"mathias/infra","default_branch":"main","private":true,"clone_url":"https://gitea.example.com/mathias/infra.git","html_url":"https://gitea.example.com/mathias/infra"}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoCreate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","private":true}`))
+	require.NoError(t, err)
+	assert.Contains(t, string(out), `"full_name":"mathias/infra"`)
+	assert.Contains(t, string(out), `"clone_url"`)
+}
+
+func TestRepoCreateTool_Org(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/orgs/hyperguild/repos", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"name":"infra","full_name":"hyperguild/infra","default_branch":"main","private":false,"clone_url":"https://gitea.example.com/hyperguild/infra.git","html_url":"https://gitea.example.com/hyperguild/infra"}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoCreate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"hyperguild"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"hyperguild","name":"infra","is_org":true}`))
+	require.NoError(t, err)
+	assert.Contains(t, string(out), `"full_name":"hyperguild/infra"`)
+}
+
+func TestRepoCreateAllowlistRejects(t *testing.T) {
+	tool := tools.NewRepoCreate(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x"}`))
+	require.Error(t, err)
+}

internal/tools/repo_mirror_push.go

@@ -0,0 +1,117 @@
+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 RepoMirrorPush struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewRepoMirrorPush(c *gitea.Client, a *allowlist.Allowlist) *RepoMirrorPush {
+	return &RepoMirrorPush{c: c, a: a}
+}
+
+func (t *RepoMirrorPush) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "repo_mirror_push",
+		Description: "Manage push mirrors for a repository: add, list, or delete.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"action":{"type":"string","enum":["add","list","delete"]},
+				"remote_address":{"type":"string","description":"Mirror target URL (required for add)."},
+				"remote_username":{"type":"string"},
+				"remote_password":{"type":"string","description":"Never logged or returned."},
+				"interval":{"type":"string","description":"Sync interval, e.g. '8h0m0s'."},
+				"sync_on_commit":{"type":"boolean"},
+				"mirror_name":{"type":"string","description":"Remote name to delete (required for delete)."}
+			},
+			"required":["owner","name","action"]
+		}`),
+	}
+}
+
+type repoMirrorPushArgs struct {
+	Owner          string `json:"owner"`
+	Name           string `json:"name"`
+	Action         string `json:"action"`
+	RemoteAddress  string `json:"remote_address"`
+	RemoteUsername string `json:"remote_username"`
+	RemotePassword string `json:"remote_password"`
+	Interval       string `json:"interval"`
+	SyncOnCommit   bool   `json:"sync_on_commit"`
+	MirrorName     string `json:"mirror_name"`
+}
+
+// safeMirror omits remote_password so it is never returned to the caller.
+type safeMirror struct {
+	ID            int    `json:"id"`
+	RemoteName    string `json:"remote_name"`
+	RemoteAddress string `json:"remote_address"`
+	Interval      string `json:"interval"`
+	SyncOnCommit  bool   `json:"sync_on_commit"`
+}
+
+func toSafeMirror(m *gitea.PushMirror) safeMirror {
+	return safeMirror{
+		ID:            m.ID,
+		RemoteName:    m.RemoteName,
+		RemoteAddress: m.RemoteAddress,
+		Interval:      m.Interval,
+		SyncOnCommit:  m.SyncOnCommit,
+	}
+}
+
+func (t *RepoMirrorPush) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args repoMirrorPushArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+	switch args.Action {
+	case "add":
+		m, err := t.c.AddPushMirror(ctx, args.Owner, args.Name, gitea.AddPushMirrorArgs{
+			RemoteAddress:  args.RemoteAddress,
+			RemoteUsername: args.RemoteUsername,
+			RemotePassword: args.RemotePassword,
+			Interval:       args.Interval,
+			SyncOnCommit:   args.SyncOnCommit,
+		})
+		if err != nil {
+			return nil, err
+		}
+		return textOK(toSafeMirror(m))
+	case "list":
+		mirrors, err := t.c.ListPushMirrors(ctx, args.Owner, args.Name)
+		if err != nil {
+			return nil, err
+		}
+		safe := make([]safeMirror, len(mirrors))
+		for i := range mirrors {
+			safe[i] = toSafeMirror(&mirrors[i])
+		}
+		return textOK(safe)
+	case "delete":
+		if args.MirrorName == "" {
+			return nil, fmt.Errorf("mirror_name is required for action=delete")
+		}
+		if err := t.c.DeletePushMirror(ctx, args.Owner, args.Name, args.MirrorName); err != nil {
+			return nil, err
+		}
+		return textOK(map[string]string{"status": "deleted", "mirror_name": args.MirrorName})
+	default:
+		return nil, fmt.Errorf("unknown action %q: must be add, list, or delete", args.Action)
+	}
+}

internal/tools/repo_mirror_push_test.go

@@ -0,0 +1,80 @@
+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 TestRepoMirrorPushTool_Add(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPost, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra/push_mirrors", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"id":1,"remote_name":"mirror-github","remote_address":"https://github.com/mathias/infra.git","interval":"8h0m0s","sync_on_commit":true}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoMirrorPush(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{
+		"owner":"mathias","name":"infra","action":"add",
+		"remote_address":"https://github.com/mathias/infra.git",
+		"remote_username":"mathias","remote_password":"secret",
+		"interval":"8h0m0s","sync_on_commit":true
+	}`))
+	require.NoError(t, err)
+	// password must never appear in output
+	assert.NotContains(t, string(out), "secret")
+	assert.Contains(t, string(out), `"remote_name":"mirror-github"`)
+}
+
+func TestRepoMirrorPushTool_List(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodGet, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra/push_mirrors", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"id":1,"remote_name":"mirror-github","remote_address":"https://github.com/mathias/infra.git","interval":"8h0m0s","sync_on_commit":true}]`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoMirrorPush(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","action":"list"}`))
+	require.NoError(t, err)
+	assert.Contains(t, string(out), `"remote_name":"mirror-github"`)
+}
+
+func TestRepoMirrorPushTool_Delete(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodDelete, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra/push_mirrors/mirror-github", r.URL.Path)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoMirrorPush(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","action":"delete","mirror_name":"mirror-github"}`))
+	require.NoError(t, err)
+	assert.Contains(t, string(out), "deleted")
+}
+
+func TestRepoMirrorPushTool_DeleteRequiresMirrorName(t *testing.T) {
+	tool := tools.NewRepoMirrorPush(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","action":"delete"}`))
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "mirror_name")
+}
+
+func TestRepoMirrorPushTool_AllowlistRejects(t *testing.T) {
+	tool := tools.NewRepoMirrorPush(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","action":"list"}`))
+	require.Error(t, err)
+}

internal/tools/repo_topics_update.go

@@ -0,0 +1,55 @@
+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 RepoTopicsUpdate struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewRepoTopicsUpdate(c *gitea.Client, a *allowlist.Allowlist) *RepoTopicsUpdate {
+	return &RepoTopicsUpdate{c: c, a: a}
+}
+
+func (t *RepoTopicsUpdate) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "repo_topics_update",
+		Description: "Replace the topic list for a repository.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"topics":{"type":"array","items":{"type":"string"},"description":"Full replacement list. Send [] to clear all topics."}
+			},
+			"required":["owner","name","topics"]
+		}`),
+	}
+}
+
+type repoTopicsUpdateArgs struct {
+	Owner  string   `json:"owner"`
+	Name   string   `json:"name"`
+	Topics []string `json:"topics"`
+}
+
+func (t *RepoTopicsUpdate) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args repoTopicsUpdateArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+	if err := t.c.UpdateTopics(ctx, args.Owner, args.Name, args.Topics); err != nil {
+		return nil, err
+	}
+	return textOK(map[string]any{"status": "updated", "topics": args.Topics})
+}

internal/tools/repo_topics_update_test.go

@@ -0,0 +1,35 @@
+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 TestRepoTopicsUpdateTool(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPut, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra/topics", r.URL.Path)
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoTopicsUpdate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","topics":["go","mcp","gitops"]}`))
+	require.NoError(t, err)
+	assert.Contains(t, string(out), "updated")
+}
+
+func TestRepoTopicsUpdateAllowlistRejects(t *testing.T) {
+	tool := tools.NewRepoTopicsUpdate(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","topics":[]}`))
+	require.Error(t, err)
+}

internal/tools/repo_tree.go

@@ -0,0 +1,56 @@
+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 RepoTree struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewRepoTree(c *gitea.Client, a *allowlist.Allowlist) *RepoTree {
+	return &RepoTree{c: c, a: a}
+}
+
+func (t *RepoTree) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "repo_tree",
+		Description: "Get the full recursive file tree for a repo ref (branch, tag, or SHA).",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"ref":{"type":"string","description":"Branch, tag, or commit SHA."}
+			},
+			"required":["owner","name","ref"]
+		}`),
+	}
+}
+
+type repoTreeArgs struct {
+	Owner string `json:"owner"`
+	Name  string `json:"name"`
+	Ref   string `json:"ref"`
+}
+
+func (t *RepoTree) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args repoTreeArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+	tree, err := t.c.GetTree(ctx, args.Owner, args.Name, args.Ref, true)
+	if err != nil {
+		return nil, err
+	}
+	return textOK(tree)
+}

internal/tools/repo_tree_test.go

@@ -0,0 +1,50 @@
+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 TestRepoTreeTool(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/mathias/infra/git/trees/main", r.URL.Path)
+		assert.Equal(t, "1", r.URL.Query().Get("recursive"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"sha":"abc","url":"http://x","tree":[{"path":"README.md","type":"blob","sha":"def","size":13},{"path":"internal","type":"tree","sha":"ghi","size":0}],"truncated":false}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoTree(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","ref":"main"}`))
+	require.NoError(t, err)
+	assert.Contains(t, string(out), `"sha":"abc"`)
+	assert.Contains(t, string(out), `"path":"README.md"`)
+}
+
+func TestRepoTreeTool_DefaultsToRecursive(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "1", r.URL.Query().Get("recursive"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"sha":"abc","tree":[],"truncated":false}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoTree(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","ref":"main"}`))
+	require.NoError(t, err)
+}
+
+func TestRepoTreeAllowlistRejects(t *testing.T) {
+	tool := tools.NewRepoTree(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","ref":"main"}`))
+	require.Error(t, err)
+}

internal/tools/repo_update.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 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).",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"description":{"type":"string"},
+				"private":{"type":"boolean"},
+				"website":{"type":"string"},
+				"default_branch":{"type":"string"},
+				"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"`
+	Private       *bool   `json:"private"`
+	Website       *string `json:"website"`
+	DefaultBranch *string `json:"default_branch"`
+	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)
+		}
+	}
+	r, err := t.c.UpdateRepo(ctx, args.Owner, args.Name, gitea.UpdateRepoArgs{
+		Description:   args.Description,
+		Private:       args.Private,
+		Website:       args.Website,
+		DefaultBranch: args.DefaultBranch,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return textOK(r)
+}

internal/tools/repo_update_test.go

@@ -0,0 +1,56 @@
+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 TestRepoUpdateTool(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPatch, r.Method)
+		assert.Equal(t, "/api/v1/repos/mathias/infra", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"name":"infra","full_name":"mathias/infra","default_branch":"main","description":"updated","private":true,"clone_url":"https://gitea.example.com/mathias/infra.git","html_url":"https://gitea.example.com/mathias/infra"}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoUpdate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","description":"updated"}`))
+	require.NoError(t, err)
+	assert.Contains(t, string(out), `"description":"updated"`)
+}
+
+func TestRepoUpdateTool_MakePublicRequiresConfirm(t *testing.T) {
+	tool := tools.NewRepoUpdate(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","private":false}`))
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "confirm")
+}
+
+func TestRepoUpdateTool_MakePublicWithConfirm(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":"infra","full_name":"mathias/infra","default_branch":"main","private":false,"clone_url":"","html_url":""}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewRepoUpdate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","private":false,"confirm":"infra"}`))
+	require.NoError(t, err)
+	assert.Contains(t, string(out), `"full_name":"mathias/infra"`)
+}
+
+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":"x"}`))
+	require.Error(t, err)
+}

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."