feat(create_project): add dispatch_allow to inject .dispatch-allow (#43 )

Optional dispatch_allow bool (default false). When true, inject a .dispatch-allow file at repo root on the resolved default branch after substitution, marking the new project dispatch-eligible (dispatch#3) without a manual follow-up commit. Rides the existing upsertRetry path so injection inherits the infra#179 branch-readiness / partial_failure handling; a stalled injection degrades exactly like substitution. Reported in files_substituted. false/omitted is byte-for-byte unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
fix(create_project): fast raw create + honest partial_failure (#42 , infra#179)
2026-07-03 20:57:39 +02:00 · 2026-07-01 23:38:13 +02:00 · 2026-07-01 23:17:11 +02:00 · 2026-07-01 23:11:49 +02:00 · 2026-07-01 23:06:35 +02:00 · 2026-07-01 22:53:15 +02:00
54 changed files with 3380 additions and 971 deletions
@@ -27,6 +27,14 @@ and climate/sustainability tech.
 These rules apply to every task across every project, regardless of harness.
 0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line:
   - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours.
   - **Load the relevant skill** — see trigger table in *Engineering Skills* below.
   - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test.
   - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done?
   **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it.
 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
@@ -36,9 +44,34 @@ These rules apply to every task across every project, regardless of harness.
 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
+5. **Trunk-Based Development — commit directly to main.** Every commit is one
-   the same repo, create a branch (`agent/<description>`), commit there, and open a
+   logical change (one tool, one fix, one test) with passing tests. Main is always
-   PR. Do not merge without explicit instruction from Mathias.
+   deployable. Never create long-lived feature branches.
   **Exception — parallel agents on same repo:** If another agent is known to be
   actively working on the same repo simultaneously, create a short-lived branch
   (`agent/<description>`), finish the task, and merge to main within the same
   session. Do not leave agent branches open between sessions.
   **Exception — external contributor or client four-eyes requirement:** Use
   PR flow only when a human reviewer outside the project is required. Document
   the reason in PROJECT.md.
 6. **Close the loop — every substantive task ends with the same ritual.** Shipping
   the code is not the end of the task; capturing it is. Run this unprompted:
   - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or
     new/changed ADR, patch for a fix; docs in the same commit). Check the repo's
     actual last tag — stated versions in docs drift stale.
   - **Push** main and the tag (CI is the gate).
   - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) —
     the reusable patterns and the footguns that would bite anyone again, never
     project status. See *Knowledge base — when to write* below.
   - **File discovered-but-deferred work as tracker issues** on the project's own
     repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let
     "out of scope, recorded" rot in a commit message; make it a ticket with a
     source pointer.
   - Surface the brain entries and issue numbers in the closing summary so the
     trail is auditable.
 ## Default stack
@@ -62,10 +95,33 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
 - **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*
+- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
  one logical change per commit, CI is the quality gate
 - **Never**: long-lived feature branches, PRs for solo work, direct push without
  passing `task check` locally first
 - **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
 ## Secret handling (every harness, every command)
 Tool output is persisted: terminal → `~/.claude/projects` transcripts →
 claudewatcher → brain/wiki → gitea history. A secret printed once is
 searchable forever, and clearing it means rotating the key. So:
 1. **Never print, echo, log, or transform a secret to inspect it.** No
   `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform
   to defeat `op run`'s output masking (it masks raw values; base64 hides them
   from the mask — that exact trick leaked a key on 2026-06-11).
 2. **Secrets stay in the subprocess.** Reference them only as env vars consumed
   *inside* `op run --env-file ~/.op-env -- <cmd>`. Never place a literal secret
   in a command's argv (it lands in the tool call and the transcript).
 3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` —
   never `${X:-...}` (returns the value when set) and never echo a substring of it.
 4. **Cross-host secrets:** run the secret-consuming command on the host that has
   the secret; do not forward a raw key over ssh argv/stdout.
 5. If a secret does leak into output, say so immediately and flag it for rotation —
   don't bury it.
 ## Infrastructure
 Three machines on Tailscale:
@@ -104,18 +160,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
 - **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
 - **klimatkollen** (`XT/`) — Swedish municipal climate data platform
-## Knowledge base
+## Knowledge base — actively use it
-When available, agents can query the shared knowledge base:
+A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
 hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
 Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
 reference material — query it actively, not just when explicitly told.**
- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
+### When to query (treat as a reflex)
 - **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
-<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
+- **Before** starting a non-trivial task — search for prior art with the symptom
-     name once hyperguild is deployed. Until then, agents that try to
+  AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
-     reach the knowledge service on a host where it isn't running will
+- **When debugging** — search for the error string, the stack frame, the affected
-     get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
+  service. Past you may have already paid this tax.
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
+- **Before adopting** a pattern, library, framework, or model name — check if it
  was tried and rejected, or what the integration footguns are.
 - **When making architectural decisions** — search for the domain + "ADR" or
  "decision" to find prior reasoning before re-deriving it.
 - **When a recommendation feels novel** — challenge yourself: "has this been
  documented?" The brain often has it.
 ### When to write
 After you discover something that **future-you would forget** and that **isn't
 recoverable from the code, git log, or PR description alone**:
 - Bugs whose root cause is non-obvious and generalisable beyond this project.
 - Framework / library / model-name quirks that bit you and would bite anyone.
 - Design principles validated under fire (e.g. "every `_get` needs a `_list`").
 - Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
 DON'T write project status, sprint progress, PR summaries, or "what I did this
 session" — those rot fast and the originals are in git/gitea anyway. Brain
 entries that age well are about *why*, *how to avoid*, and *what to do when*.
 ### How to access (per harness)
 | Harness | Query | Write |
 |---------|-------|-------|
 | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
 | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
 | **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
 | **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
 - **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
 - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
  fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
  on the koala k3s cluster; don't hardcode local-only model names into the
  berget URL (see knowledge entry on namespace mismatches).
 ### Quick reflex checks
 If you find yourself about to say any of these out loud, you owe yourself a brain query first:
 - "I think the issue might be..."
 - "Let me try X and see..."
 - "I'll just write a script to..."
 - "This is probably a new bug..."
 - "Has anyone done this before?" — *yes, probably, go check.*
 ## Client work rules
@@ -161,15 +263,17 @@ unconditionally on every host, every harness.
 ## Engineering Skills
-Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list.
-See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+**Skill trigger table — load before starting, not after getting stuck:**
-Key skills:
+| Task type | Load |
- **TDD**: always write tests first — load `tdd` skill
+|-----------|------|
- **Code Review**: load `code-review` skill before any review
+| Any feature or bug fix | `tdd` |
- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
+| Refactor or design | `clean-code` or `solid` |
- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+| Debug | `problem-analysis` |
 | Review code or PRs | `code-review` |
 | Frame a problem before coding | `problem-analysis` |
 ---
@@ -212,8 +316,11 @@ Key skills:
 ### Git
 - Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
- Branch naming: `feat/short-description`, `fix/short-description`
+- **Trunk-Based Development:** commit directly to main. One logical change per commit.
- PRs: one concern per PR, description explains *why* not *what*
+- Run `task check` locally before every push. CI is the quality gate, not branch protection.
 - No feature branches, no PRs for solo/agent work.
 - Exception: if a parallel agent session is active on this repo, use a short-lived
  `agent/<description>` branch and merge within the same session.
 ### Security
 - No secrets in code, ever — use env vars or SOPS-encrypted files
@@ -251,68 +358,29 @@ When acting as a coding agent on this project:
 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
+6. Commit directly to main. Run `task check` before every push. Never create
   feature branches unless a parallel agent is simultaneously active on this repo.
 7. 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)
+## Current state — v0.2.5 (2026-05-17)
-### Context
+All v0.2 work is complete and deployed. No active sprint.
 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)
+### What shipped
-**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+| Tag | PR | Tools / fixes |
 |-----|----|---------------|
 | v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
 | v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
 | v0.2.4 | #23 | issue_get, release_create, repo_delete |
 | v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
-| Issue | Tool | Gitea API |
+Current main: `e31fd3f`. CI green. Deployed via Flux.
 |-------|------|-----------|
 | #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`)**
+### Next up
-| Issue | Tool | Gitea API |
+1. **`hyperguild new-project` v1** — primary next target.
-|-------|------|-----------|
+   See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
 | #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**
+2. **Issue #19** — end-to-end mirror flow verification.
-
+   `repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
 | 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
@@ -37,8 +37,11 @@
 ### Git
 - Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
- Branch naming: `feat/short-description`, `fix/short-description`
+- **Trunk-Based Development:** commit directly to main. One logical change per commit.
- PRs: one concern per PR, description explains *why* not *what*
+- Run `task check` locally before every push. CI is the quality gate, not branch protection.
 - No feature branches, no PRs for solo/agent work.
 - Exception: if a parallel agent session is active on this repo, use a short-lived
  `agent/<description>` branch and merge within the same session.
 ### Security
 - No secrets in code, ever — use env vars or SOPS-encrypted files
@@ -76,68 +79,29 @@ When acting as a coding agent on this project:
 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
+6. Commit directly to main. Run `task check` before every push. Never create
   feature branches unless a parallel agent is simultaneously active on this repo.
 7. 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)
+## Current state — v0.2.5 (2026-05-17)
-### Context
+All v0.2 work is complete and deployed. No active sprint.
 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)
+### What shipped
-**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+| Tag | PR | Tools / fixes |
 |-----|----|---------------|
 | v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
 | v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
 | v0.2.4 | #23 | issue_get, release_create, repo_delete |
 | v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
-| Issue | Tool | Gitea API |
+Current main: `e31fd3f`. CI green. Deployed via Flux.
 |-------|------|-----------|
 | #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`)**
+### Next up
-| Issue | Tool | Gitea API |
+1. **`hyperguild new-project` v1** — primary next target.
-|-------|------|-----------|
+   See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
 | #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**
+2. **Issue #19** — end-to-end mirror flow verification.
-
+   `repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
 | 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
@@ -32,6 +32,14 @@ and climate/sustainability tech.
 These rules apply to every task across every project, regardless of harness.
 0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line:
   - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours.
   - **Load the relevant skill** — see trigger table in *Engineering Skills* below.
   - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test.
   - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done?
   **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it.
 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
@@ -41,9 +49,34 @@ These rules apply to every task across every project, regardless of harness.
 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
+5. **Trunk-Based Development — commit directly to main.** Every commit is one
-   the same repo, create a branch (`agent/<description>`), commit there, and open a
+   logical change (one tool, one fix, one test) with passing tests. Main is always
-   PR. Do not merge without explicit instruction from Mathias.
+   deployable. Never create long-lived feature branches.
   **Exception — parallel agents on same repo:** If another agent is known to be
   actively working on the same repo simultaneously, create a short-lived branch
   (`agent/<description>`), finish the task, and merge to main within the same
   session. Do not leave agent branches open between sessions.
   **Exception — external contributor or client four-eyes requirement:** Use
   PR flow only when a human reviewer outside the project is required. Document
   the reason in PROJECT.md.
 6. **Close the loop — every substantive task ends with the same ritual.** Shipping
   the code is not the end of the task; capturing it is. Run this unprompted:
   - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or
     new/changed ADR, patch for a fix; docs in the same commit). Check the repo's
     actual last tag — stated versions in docs drift stale.
   - **Push** main and the tag (CI is the gate).
   - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) —
     the reusable patterns and the footguns that would bite anyone again, never
     project status. See *Knowledge base — when to write* below.
   - **File discovered-but-deferred work as tracker issues** on the project's own
     repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let
     "out of scope, recorded" rot in a commit message; make it a ticket with a
     source pointer.
   - Surface the brain entries and issue numbers in the closing summary so the
     trail is auditable.
 ## Default stack
@@ -67,10 +100,33 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
 - **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*
+- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
  one logical change per commit, CI is the quality gate
 - **Never**: long-lived feature branches, PRs for solo work, direct push without
  passing `task check` locally first
 - **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
 ## Secret handling (every harness, every command)
 Tool output is persisted: terminal → `~/.claude/projects` transcripts →
 claudewatcher → brain/wiki → gitea history. A secret printed once is
 searchable forever, and clearing it means rotating the key. So:
 1. **Never print, echo, log, or transform a secret to inspect it.** No
   `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform
   to defeat `op run`'s output masking (it masks raw values; base64 hides them
   from the mask — that exact trick leaked a key on 2026-06-11).
 2. **Secrets stay in the subprocess.** Reference them only as env vars consumed
   *inside* `op run --env-file ~/.op-env -- <cmd>`. Never place a literal secret
   in a command's argv (it lands in the tool call and the transcript).
 3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` —
   never `${X:-...}` (returns the value when set) and never echo a substring of it.
 4. **Cross-host secrets:** run the secret-consuming command on the host that has
   the secret; do not forward a raw key over ssh argv/stdout.
 5. If a secret does leak into output, say so immediately and flag it for rotation —
   don't bury it.
 ## Infrastructure
 Three machines on Tailscale:
@@ -109,18 +165,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
 - **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
 - **klimatkollen** (`XT/`) — Swedish municipal climate data platform
-## Knowledge base
+## Knowledge base — actively use it
-When available, agents can query the shared knowledge base:
+A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
 hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
 Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
 reference material — query it actively, not just when explicitly told.**
- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
+### When to query (treat as a reflex)
 - **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
-<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
+- **Before** starting a non-trivial task — search for prior art with the symptom
-     name once hyperguild is deployed. Until then, agents that try to
+  AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
-     reach the knowledge service on a host where it isn't running will
+- **When debugging** — search for the error string, the stack frame, the affected
-     get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
+  service. Past you may have already paid this tax.
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
+- **Before adopting** a pattern, library, framework, or model name — check if it
  was tried and rejected, or what the integration footguns are.
 - **When making architectural decisions** — search for the domain + "ADR" or
  "decision" to find prior reasoning before re-deriving it.
 - **When a recommendation feels novel** — challenge yourself: "has this been
  documented?" The brain often has it.
 ### When to write
 After you discover something that **future-you would forget** and that **isn't
 recoverable from the code, git log, or PR description alone**:
 - Bugs whose root cause is non-obvious and generalisable beyond this project.
 - Framework / library / model-name quirks that bit you and would bite anyone.
 - Design principles validated under fire (e.g. "every `_get` needs a `_list`").
 - Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
 DON'T write project status, sprint progress, PR summaries, or "what I did this
 session" — those rot fast and the originals are in git/gitea anyway. Brain
 entries that age well are about *why*, *how to avoid*, and *what to do when*.
 ### How to access (per harness)
 | Harness | Query | Write |
 |---------|-------|-------|
 | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
 | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
 | **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
 | **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
 - **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
 - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
  fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
  on the koala k3s cluster; don't hardcode local-only model names into the
  berget URL (see knowledge entry on namespace mismatches).
 ### Quick reflex checks
 If you find yourself about to say any of these out loud, you owe yourself a brain query first:
 - "I think the issue might be..."
 - "Let me try X and see..."
 - "I'll just write a script to..."
 - "This is probably a new bug..."
 - "Has anyone done this before?" — *yes, probably, go check.*
 ## Client work rules
@@ -166,15 +268,17 @@ unconditionally on every host, every harness.
 ## Engineering Skills
-Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list.
-See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+**Skill trigger table — load before starting, not after getting stuck:**
-Key skills:
+| Task type | Load |
- **TDD**: always write tests first — load `tdd` skill
+|-----------|------|
- **Code Review**: load `code-review` skill before any review
+| Any feature or bug fix | `tdd` |
- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
+| Refactor or design | `clean-code` or `solid` |
- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+| Debug | `problem-analysis` |
 | Review code or PRs | `code-review` |
 | Frame a problem before coding | `problem-analysis` |
 ---
@@ -217,8 +321,11 @@ Key skills:
 ### Git
 - Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
- Branch naming: `feat/short-description`, `fix/short-description`
+- **Trunk-Based Development:** commit directly to main. One logical change per commit.
- PRs: one concern per PR, description explains *why* not *what*
+- Run `task check` locally before every push. CI is the quality gate, not branch protection.
 - No feature branches, no PRs for solo/agent work.
 - Exception: if a parallel agent session is active on this repo, use a short-lived
  `agent/<description>` branch and merge within the same session.
 ### Security
 - No secrets in code, ever — use env vars or SOPS-encrypted files
@@ -256,70 +363,31 @@ When acting as a coding agent on this project:
 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
+6. Commit directly to main. Run `task check` before every push. Never create
   feature branches unless a parallel agent is simultaneously active on this repo.
 7. 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)
+## Current state — v0.2.5 (2026-05-17)
-### Context
+All v0.2 work is complete and deployed. No active sprint.
 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)
+### What shipped
-**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+| Tag | PR | Tools / fixes |
 |-----|----|---------------|
 | v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
 | v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
 | v0.2.4 | #23 | issue_get, release_create, repo_delete |
 | v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
-| Issue | Tool | Gitea API |
+Current main: `e31fd3f`. CI green. Deployed via Flux.
 |-------|------|-----------|
 | #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`)**
+### Next up
-| Issue | Tool | Gitea API |
+1. **`hyperguild new-project` v1** — primary next target.
-|-------|------|-----------|
+   See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
 | #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**
+2. **Issue #19** — end-to-end mirror flow verification.
-
+   `repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
 | 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
 ---
@@ -30,6 +30,14 @@ and climate/sustainability tech.
 These rules apply to every task across every project, regardless of harness.
 0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line:
   - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours.
   - **Load the relevant skill** — see trigger table in *Engineering Skills* below.
   - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test.
   - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done?
   **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it.
 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
@@ -39,9 +47,34 @@ These rules apply to every task across every project, regardless of harness.
 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
+5. **Trunk-Based Development — commit directly to main.** Every commit is one
-   the same repo, create a branch (`agent/<description>`), commit there, and open a
+   logical change (one tool, one fix, one test) with passing tests. Main is always
-   PR. Do not merge without explicit instruction from Mathias.
+   deployable. Never create long-lived feature branches.
   **Exception — parallel agents on same repo:** If another agent is known to be
   actively working on the same repo simultaneously, create a short-lived branch
   (`agent/<description>`), finish the task, and merge to main within the same
   session. Do not leave agent branches open between sessions.
   **Exception — external contributor or client four-eyes requirement:** Use
   PR flow only when a human reviewer outside the project is required. Document
   the reason in PROJECT.md.
 6. **Close the loop — every substantive task ends with the same ritual.** Shipping
   the code is not the end of the task; capturing it is. Run this unprompted:
   - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or
     new/changed ADR, patch for a fix; docs in the same commit). Check the repo's
     actual last tag — stated versions in docs drift stale.
   - **Push** main and the tag (CI is the gate).
   - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) —
     the reusable patterns and the footguns that would bite anyone again, never
     project status. See *Knowledge base — when to write* below.
   - **File discovered-but-deferred work as tracker issues** on the project's own
     repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let
     "out of scope, recorded" rot in a commit message; make it a ticket with a
     source pointer.
   - Surface the brain entries and issue numbers in the closing summary so the
     trail is auditable.
 ## Default stack
@@ -65,10 +98,33 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
 - **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*
+- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
  one logical change per commit, CI is the quality gate
 - **Never**: long-lived feature branches, PRs for solo work, direct push without
  passing `task check` locally first
 - **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
 ## Secret handling (every harness, every command)
 Tool output is persisted: terminal → `~/.claude/projects` transcripts →
 claudewatcher → brain/wiki → gitea history. A secret printed once is
 searchable forever, and clearing it means rotating the key. So:
 1. **Never print, echo, log, or transform a secret to inspect it.** No
   `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform
   to defeat `op run`'s output masking (it masks raw values; base64 hides them
   from the mask — that exact trick leaked a key on 2026-06-11).
 2. **Secrets stay in the subprocess.** Reference them only as env vars consumed
   *inside* `op run --env-file ~/.op-env -- <cmd>`. Never place a literal secret
   in a command's argv (it lands in the tool call and the transcript).
 3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` —
   never `${X:-...}` (returns the value when set) and never echo a substring of it.
 4. **Cross-host secrets:** run the secret-consuming command on the host that has
   the secret; do not forward a raw key over ssh argv/stdout.
 5. If a secret does leak into output, say so immediately and flag it for rotation —
   don't bury it.
 ## Infrastructure
 Three machines on Tailscale:
@@ -107,18 +163,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
 - **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
 - **klimatkollen** (`XT/`) — Swedish municipal climate data platform
-## Knowledge base
+## Knowledge base — actively use it
-When available, agents can query the shared knowledge base:
+A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
 hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
 Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
 reference material — query it actively, not just when explicitly told.**
- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
+### When to query (treat as a reflex)
 - **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
-<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
+- **Before** starting a non-trivial task — search for prior art with the symptom
-     name once hyperguild is deployed. Until then, agents that try to
+  AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
-     reach the knowledge service on a host where it isn't running will
+- **When debugging** — search for the error string, the stack frame, the affected
-     get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
+  service. Past you may have already paid this tax.
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
+- **Before adopting** a pattern, library, framework, or model name — check if it
  was tried and rejected, or what the integration footguns are.
 - **When making architectural decisions** — search for the domain + "ADR" or
  "decision" to find prior reasoning before re-deriving it.
 - **When a recommendation feels novel** — challenge yourself: "has this been
  documented?" The brain often has it.
 ### When to write
 After you discover something that **future-you would forget** and that **isn't
 recoverable from the code, git log, or PR description alone**:
 - Bugs whose root cause is non-obvious and generalisable beyond this project.
 - Framework / library / model-name quirks that bit you and would bite anyone.
 - Design principles validated under fire (e.g. "every `_get` needs a `_list`").
 - Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
 DON'T write project status, sprint progress, PR summaries, or "what I did this
 session" — those rot fast and the originals are in git/gitea anyway. Brain
 entries that age well are about *why*, *how to avoid*, and *what to do when*.
 ### How to access (per harness)
 | Harness | Query | Write |
 |---------|-------|-------|
 | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
 | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
 | **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
 | **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
 - **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
 - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
  fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
  on the koala k3s cluster; don't hardcode local-only model names into the
  berget URL (see knowledge entry on namespace mismatches).
 ### Quick reflex checks
 If you find yourself about to say any of these out loud, you owe yourself a brain query first:
 - "I think the issue might be..."
 - "Let me try X and see..."
 - "I'll just write a script to..."
 - "This is probably a new bug..."
 - "Has anyone done this before?" — *yes, probably, go check.*
 ## Client work rules
@@ -164,15 +266,17 @@ unconditionally on every host, every harness.
 ## Engineering Skills
-Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list.
-See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+**Skill trigger table — load before starting, not after getting stuck:**
-Key skills:
+| Task type | Load |
- **TDD**: always write tests first — load `tdd` skill
+|-----------|------|
- **Code Review**: load `code-review` skill before any review
+| Any feature or bug fix | `tdd` |
- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
+| Refactor or design | `clean-code` or `solid` |
- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+| Debug | `problem-analysis` |
 | Review code or PRs | `code-review` |
 | Frame a problem before coding | `problem-analysis` |
 ---
@@ -215,8 +319,11 @@ Key skills:
 ### Git
 - Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
- Branch naming: `feat/short-description`, `fix/short-description`
+- **Trunk-Based Development:** commit directly to main. One logical change per commit.
- PRs: one concern per PR, description explains *why* not *what*
+- Run `task check` locally before every push. CI is the quality gate, not branch protection.
 - No feature branches, no PRs for solo/agent work.
 - Exception: if a parallel agent session is active on this repo, use a short-lived
  `agent/<description>` branch and merge within the same session.
 ### Security
 - No secrets in code, ever — use env vars or SOPS-encrypted files
@@ -254,68 +361,29 @@ When acting as a coding agent on this project:
 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
+6. Commit directly to main. Run `task check` before every push. Never create
   feature branches unless a parallel agent is simultaneously active on this repo.
 7. 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)
+## Current state — v0.2.5 (2026-05-17)
-### Context
+All v0.2 work is complete and deployed. No active sprint.
 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)
+### What shipped
-**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+| Tag | PR | Tools / fixes |
 |-----|----|---------------|
 | v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
 | v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
 | v0.2.4 | #23 | issue_get, release_create, repo_delete |
 | v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
-| Issue | Tool | Gitea API |
+Current main: `e31fd3f`. CI green. Deployed via Flux.
 |-------|------|-----------|
 | #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`)**
+### Next up
-| Issue | Tool | Gitea API |
+1. **`hyperguild new-project` v1** — primary next target.
-|-------|------|-----------|
+   See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
 | #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**
+2. **Issue #19** — end-to-end mirror flow verification.
-
+   `repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
 | 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
@@ -1,11 +1,9 @@
 name: CD
-on:
+"on":
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    branches: [main]
 env:
  IMAGE: gitea-mcp
@@ -43,7 +41,6 @@ jobs:
    name: Build & Import
    needs: check
    runs-on: self-hosted
    if: github.event_name != 'pull_request'
    outputs:
      image-tag: ${{ steps.meta.outputs.sha-tag }}
    steps:
@@ -0,0 +1,5 @@
 #!/usr/bin/env bash
 set -euo pipefail
 echo "→ Running task check before push..."
 task check
 echo "✓ pre-push check passed"
@@ -27,6 +27,14 @@ and climate/sustainability tech.
 These rules apply to every task across every project, regardless of harness.
 0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line:
   - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours.
   - **Load the relevant skill** — see trigger table in *Engineering Skills* below.
   - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test.
   - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done?
   **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it.
 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
@@ -36,9 +44,34 @@ These rules apply to every task across every project, regardless of harness.
 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
+5. **Trunk-Based Development — commit directly to main.** Every commit is one
-   the same repo, create a branch (`agent/<description>`), commit there, and open a
+   logical change (one tool, one fix, one test) with passing tests. Main is always
-   PR. Do not merge without explicit instruction from Mathias.
+   deployable. Never create long-lived feature branches.
   **Exception — parallel agents on same repo:** If another agent is known to be
   actively working on the same repo simultaneously, create a short-lived branch
   (`agent/<description>`), finish the task, and merge to main within the same
   session. Do not leave agent branches open between sessions.
   **Exception — external contributor or client four-eyes requirement:** Use
   PR flow only when a human reviewer outside the project is required. Document
   the reason in PROJECT.md.
 6. **Close the loop — every substantive task ends with the same ritual.** Shipping
   the code is not the end of the task; capturing it is. Run this unprompted:
   - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or
     new/changed ADR, patch for a fix; docs in the same commit). Check the repo's
     actual last tag — stated versions in docs drift stale.
   - **Push** main and the tag (CI is the gate).
   - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) —
     the reusable patterns and the footguns that would bite anyone again, never
     project status. See *Knowledge base — when to write* below.
   - **File discovered-but-deferred work as tracker issues** on the project's own
     repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let
     "out of scope, recorded" rot in a commit message; make it a ticket with a
     source pointer.
   - Surface the brain entries and issue numbers in the closing summary so the
     trail is auditable.
 ## Default stack
@@ -62,10 +95,33 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
 - **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*
+- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
  one logical change per commit, CI is the quality gate
 - **Never**: long-lived feature branches, PRs for solo work, direct push without
  passing `task check` locally first
 - **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
 ## Secret handling (every harness, every command)
 Tool output is persisted: terminal → `~/.claude/projects` transcripts →
 claudewatcher → brain/wiki → gitea history. A secret printed once is
 searchable forever, and clearing it means rotating the key. So:
 1. **Never print, echo, log, or transform a secret to inspect it.** No
   `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform
   to defeat `op run`'s output masking (it masks raw values; base64 hides them
   from the mask — that exact trick leaked a key on 2026-06-11).
 2. **Secrets stay in the subprocess.** Reference them only as env vars consumed
   *inside* `op run --env-file ~/.op-env -- <cmd>`. Never place a literal secret
   in a command's argv (it lands in the tool call and the transcript).
 3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` —
   never `${X:-...}` (returns the value when set) and never echo a substring of it.
 4. **Cross-host secrets:** run the secret-consuming command on the host that has
   the secret; do not forward a raw key over ssh argv/stdout.
 5. If a secret does leak into output, say so immediately and flag it for rotation —
   don't bury it.
 ## Infrastructure
 Three machines on Tailscale:
@@ -104,18 +160,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
 - **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
 - **klimatkollen** (`XT/`) — Swedish municipal climate data platform
-## Knowledge base
+## Knowledge base — actively use it
-When available, agents can query the shared knowledge base:
+A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
 hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
 Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
 reference material — query it actively, not just when explicitly told.**
- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
+### When to query (treat as a reflex)
 - **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
-<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
+- **Before** starting a non-trivial task — search for prior art with the symptom
-     name once hyperguild is deployed. Until then, agents that try to
+  AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
-     reach the knowledge service on a host where it isn't running will
+- **When debugging** — search for the error string, the stack frame, the affected
-     get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
+  service. Past you may have already paid this tax.
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
+- **Before adopting** a pattern, library, framework, or model name — check if it
  was tried and rejected, or what the integration footguns are.
 - **When making architectural decisions** — search for the domain + "ADR" or
  "decision" to find prior reasoning before re-deriving it.
 - **When a recommendation feels novel** — challenge yourself: "has this been
  documented?" The brain often has it.
 ### When to write
 After you discover something that **future-you would forget** and that **isn't
 recoverable from the code, git log, or PR description alone**:
 - Bugs whose root cause is non-obvious and generalisable beyond this project.
 - Framework / library / model-name quirks that bit you and would bite anyone.
 - Design principles validated under fire (e.g. "every `_get` needs a `_list`").
 - Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
 DON'T write project status, sprint progress, PR summaries, or "what I did this
 session" — those rot fast and the originals are in git/gitea anyway. Brain
 entries that age well are about *why*, *how to avoid*, and *what to do when*.
 ### How to access (per harness)
 | Harness | Query | Write |
 |---------|-------|-------|
 | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
 | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
 | **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
 | **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
 - **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
 - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
  fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
  on the koala k3s cluster; don't hardcode local-only model names into the
  berget URL (see knowledge entry on namespace mismatches).
 ### Quick reflex checks
 If you find yourself about to say any of these out loud, you owe yourself a brain query first:
 - "I think the issue might be..."
 - "Let me try X and see..."
 - "I'll just write a script to..."
 - "This is probably a new bug..."
 - "Has anyone done this before?" — *yes, probably, go check.*
 ## Client work rules
@@ -161,15 +263,17 @@ unconditionally on every host, every harness.
 ## Engineering Skills
-Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list.
-See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+**Skill trigger table — load before starting, not after getting stuck:**
-Key skills:
+| Task type | Load |
- **TDD**: always write tests first — load `tdd` skill
+|-----------|------|
- **Code Review**: load `code-review` skill before any review
+| Any feature or bug fix | `tdd` |
- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
+| Refactor or design | `clean-code` or `solid` |
- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+| Debug | `problem-analysis` |
 | Review code or PRs | `code-review` |
 | Frame a problem before coding | `problem-analysis` |
 ---
@@ -212,8 +316,11 @@ Key skills:
 ### Git
 - Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
- Branch naming: `feat/short-description`, `fix/short-description`
+- **Trunk-Based Development:** commit directly to main. One logical change per commit.
- PRs: one concern per PR, description explains *why* not *what*
+- Run `task check` locally before every push. CI is the quality gate, not branch protection.
 - No feature branches, no PRs for solo/agent work.
 - Exception: if a parallel agent session is active on this repo, use a short-lived
  `agent/<description>` branch and merge within the same session.
 ### Security
 - No secrets in code, ever — use env vars or SOPS-encrypted files
@@ -251,68 +358,29 @@ When acting as a coding agent on this project:
 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
+6. Commit directly to main. Run `task check` before every push. Never create
   feature branches unless a parallel agent is simultaneously active on this repo.
 7. 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)
+## Current state — v0.2.5 (2026-05-17)
-### Context
+All v0.2 work is complete and deployed. No active sprint.
 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)
+### What shipped
-**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+| Tag | PR | Tools / fixes |
 |-----|----|---------------|
 | v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
 | v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
 | v0.2.4 | #23 | issue_get, release_create, repo_delete |
 | v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
-| Issue | Tool | Gitea API |
+Current main: `e31fd3f`. CI green. Deployed via Flux.
 |-------|------|-----------|
 | #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`)**
+### Next up
-| Issue | Tool | Gitea API |
+1. **`hyperguild new-project` v1** — primary next target.
-|-------|------|-----------|
+   See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
 | #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**
+2. **Issue #19** — end-to-end mirror flow verification.
-
+   `repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
 | 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
@@ -37,8 +37,11 @@
 ### Git
 - Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
- Branch naming: `feat/short-description`, `fix/short-description`
+- **Trunk-Based Development:** commit directly to main. One logical change per commit.
- PRs: one concern per PR, description explains *why* not *what*
+- Run `task check` locally before every push. CI is the quality gate, not branch protection.
 - No feature branches, no PRs for solo/agent work.
 - Exception: if a parallel agent session is active on this repo, use a short-lived
  `agent/<description>` branch and merge within the same session.
 ### Security
 - No secrets in code, ever — use env vars or SOPS-encrypted files
@@ -76,68 +79,29 @@ When acting as a coding agent on this project:
 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
+6. Commit directly to main. Run `task check` before every push. Never create
   feature branches unless a parallel agent is simultaneously active on this repo.
 7. 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)
+## Current state — v0.2.5 (2026-05-17)
-### Context
+All v0.2 work is complete and deployed. No active sprint.
 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)
+### What shipped
-**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
+| Tag | PR | Tools / fixes |
 |-----|----|---------------|
 | v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
 | v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
 | v0.2.4 | #23 | issue_get, release_create, repo_delete |
 | v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
-| Issue | Tool | Gitea API |
+Current main: `e31fd3f`. CI green. Deployed via Flux.
 |-------|------|-----------|
 | #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`)**
+### Next up
-| Issue | Tool | Gitea API |
+1. **`hyperguild new-project` v1** — primary next target.
-|-------|------|-----------|
+   See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
 | #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**
+2. **Issue #19** — end-to-end mirror flow verification.
-
+   `repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
 | 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
@@ -1,5 +1,16 @@
 FROM golang:1.26-alpine AS build
 WORKDIR /src
 # Fetch internal gitea-hosted Go modules (e.g. mcp-chassis) without going
 # through proxy.golang.org and without HTTP→HTTPS surprises. Gitea returns
 # http:// in its go-import meta tag, so rewrite to https here and bypass
 # the module proxy + sumdb.
 RUN apk add --no-cache git && \
    git config --global url."https://gitea.d-ma.be/".insteadOf "http://gitea.d-ma.be/"
 ENV GOPRIVATE=gitea.d-ma.be
 ENV GOPROXY=direct
 ENV GOSUMDB=off
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
@@ -2,3 +2,14 @@
 Streamable HTTP MCP service exposing Gitea repo operations to Claude apps.
 See `~/dev/AI/infra/docs/superpowers/specs/2026-05-04-gitea-mcp-gitops-workflow-design.md`.
 ## Quickstart
 ```bash
 task setup:hooks   # installs .githooks/pre-push — runs task check before every push
 task check         # context sync + lint + test + vet
 task build         # produces bin/gitea-mcp
 ```
 This repo uses Trunk-Based Development. Commit directly to `main`. The pre-push
 hook enforces the quality gate locally; CI re-runs `task check` on every push.
@@ -47,6 +47,13 @@ tasks:
    cmds:
      - bash scripts/context-sync.sh
  setup:hooks:
    desc: Install git hooks (.githooks/pre-push)
    cmds:
      - git config core.hooksPath .githooks
      - chmod +x .githooks/pre-push
      - echo "✓ git hooks installed (pre-push runs task check)"
  context:sync:claude:
    cmds: [bash scripts/context-sync.sh claude]
  context:sync:agents:
@@ -0,0 +1,46 @@
 package main
 import (
 	"encoding/json"
 	"net/http"
 )
 type healthStatus struct {
 	OK  bool      `json:"ok"`
 	JWT jwtStatus `json:"jwt"`
 }
 // jwtStatus surfaces the runtime state of the Dex JWT validator so ops
 // can distinguish "Dex unreachable at startup" from "JWT auth not
 // configured" — both previously degraded silently to static-token-only
 // (refs hyperguild/gitea-mcp#6).
 type jwtStatus struct {
 	// Status is one of: "disabled" (DEX_ISSUER_URL not set),
 	// "enabled" (validator initialized), "degraded" (configured but
 	// init failed; only static-token auth currently accepted).
 	Status    string `json:"status"`
 	LastError string `json:"last_error,omitempty"`
 }
 func newHealthzHandler(dexConfigured, validatorReady bool, initErr error) http.HandlerFunc {
 	status := healthStatus{OK: true, JWT: jwtStatus{Status: jwtStatusFor(dexConfigured, validatorReady)}}
 	if initErr != nil {
 		status.JWT.LastError = initErr.Error()
 	}
 	body, _ := json.Marshal(status)
 	return func(w http.ResponseWriter, _ *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write(body)
 	}
 }
 func jwtStatusFor(dexConfigured, validatorReady bool) string {
 	switch {
 	case !dexConfigured:
 		return "disabled"
 	case validatorReady:
 		return "enabled"
 	default:
 		return "degraded"
 	}
 }
@@ -0,0 +1,60 @@
 package main
 import (
 	"encoding/json"
 	"errors"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 func TestHealthzHandler(t *testing.T) {
 	tests := []struct {
 		name           string
 		dexConfigured  bool
 		validatorReady bool
 		initErr        error
 		wantStatus     string
 		wantLastError  string
 	}{
 		{
 			name:          "disabled when DEX_ISSUER_URL unset",
 			wantStatus:    "disabled",
 			wantLastError: "",
 		},
 		{
 			name:           "enabled when validator initialized",
 			dexConfigured:  true,
 			validatorReady: true,
 			wantStatus:     "enabled",
 			wantLastError:  "",
 		},
 		{
 			name:          "degraded when Dex configured but init failed",
 			dexConfigured: true,
 			initErr:       errors.New("fetch oidc discovery: dial tcp: connection refused"),
 			wantStatus:    "degraded",
 			wantLastError: "fetch oidc discovery: dial tcp: connection refused",
 		},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
 			h := newHealthzHandler(tc.dexConfigured, tc.validatorReady, tc.initErr)
 			rec := httptest.NewRecorder()
 			h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
 			require.Equal(t, http.StatusOK, rec.Code)
 			assert.Equal(t, "application/json", rec.Header().Get("Content-Type"))
 			var got healthStatus
 			require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
 			assert.True(t, got.OK)
 			assert.Equal(t, tc.wantStatus, got.JWT.Status)
 			assert.Equal(t, tc.wantLastError, got.JWT.LastError)
 		})
 	}
 }
@@ -2,10 +2,12 @@ package main
 import (
 	"context"
 	"encoding/json"
 	"log/slog"
 	"net/http"
 	"os"
 	"strings"
 	chassisauth "git.d-ma.be/mathias/mcp-chassis/auth"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/auth"
@@ -27,75 +29,41 @@ func main() {
 	ctx := context.Background()
-	jwtValidator, err := auth.NewJWTValidator(ctx, cfg.DexIssuerURL, cfg.MCPAudience)
+	jwtValidator, jwtInitErr := chassisauth.NewJWTValidator(ctx, cfg.DexIssuerURL, cfg.MCPAudience)
-	if err != nil {
+	if jwtInitErr != nil {
-		logger.Warn("jwt validator init failed; JWT auth disabled", "err", err)
+		logger.Warn("jwt validator init failed; JWT auth degraded", "err", jwtInitErr)
 	}
 	giteaClient := gitea.NewClient(cfg.GiteaBaseURL, cfg.DefaultToken)
 	ownerAllow := allowlist.New(cfg.AllowedOwners)
 	reg := registry.New()
-	reg.Register(tools.NewRepoList(giteaClient, ownerAllow))
+	tools.RegisterAll(reg, giteaClient, ownerAllow, cfg.GiteaBaseURL, "mathias", "template-go-web")
 	reg.Register(tools.NewRepoGet(giteaClient, ownerAllow))
 	reg.Register(tools.NewRepoSearch(giteaClient, ownerAllow))
 	reg.Register(tools.NewRepoStatus(giteaClient, ownerAllow))
 	reg.Register(tools.NewFileRead(giteaClient, ownerAllow))
 	reg.Register(tools.NewFileWriteBranch(giteaClient, ownerAllow))
 	reg.Register(tools.NewFileDelete(giteaClient, ownerAllow))
 	reg.Register(tools.NewDirList(giteaClient, ownerAllow))
 	reg.Register(tools.NewBranchList(giteaClient, ownerAllow))
 	reg.Register(tools.NewBranchDelete(giteaClient, ownerAllow))
 	reg.Register(tools.NewBranchProtectionGet(giteaClient, ownerAllow))
 	reg.Register(tools.NewPRCreate(giteaClient, ownerAllow))
 	reg.Register(tools.NewPRGet(giteaClient, ownerAllow))
 	reg.Register(tools.NewPRList(giteaClient, ownerAllow))
 	reg.Register(tools.NewPRMerge(giteaClient, ownerAllow))
 	reg.Register(tools.NewPRComment(giteaClient, ownerAllow))
 	reg.Register(tools.NewPRFilesDiff(giteaClient, ownerAllow))
 	reg.Register(tools.NewWorkflowRunTrigger(giteaClient, ownerAllow, cfg.GiteaBaseURL))
 	reg.Register(tools.NewWorkflowRunStatus(giteaClient, ownerAllow))
 	reg.Register(tools.NewCodeSearch(giteaClient, ownerAllow))
 	reg.Register(tools.NewIssueCreate(giteaClient, ownerAllow))
 	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,
 		Sessions: mcp.NewSessionStore(),
 	})
 	// resourceMetadataURL is only emitted in the WWW-Authenticate challenge
 	// when both MCPResourceURL and a Dex issuer are wired; empty disables
 	// the challenge so static-only clients aren't pushed into OAuth discovery.
 	var resourceMetadataURL string
 	if cfg.MCPResourceURL != "" && cfg.DexIssuerURL != "" {
 		resourceMetadataURL = strings.TrimRight(cfg.MCPResourceURL, "/") + "/.well-known/oauth-protected-resource"
 	}
 	mux := http.NewServeMux()
 	mux.Handle("/mcp", mcp.OriginAllowlist(cfg.OriginAllowlist)(
-		auth.BearerMiddleware(jwtValidator, cfg.StaticToken,
+		chassisauth.BearerMiddleware(cfg.StaticToken, jwtValidator, "gitea", resourceMetadataURL,
 			auth.CallerMiddleware(mcpSrv),
 		),
 	))
-	mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
+	mux.Handle("/healthz", newHealthzHandler(cfg.DexIssuerURL != "", jwtValidator != nil, jwtInitErr))
 		w.WriteHeader(http.StatusOK)
 		_, _ = w.Write([]byte("ok"))
 	})
 	mux.HandleFunc("/.well-known/oauth-protected-resource", func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodGet {
 			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 			return
 		}
 		w.Header().Set("Content-Type", "application/json")
 		payload := map[string]any{
 			"resource":             cfg.MCPResourceURL,
 			"authorization_servers": []string{},
 		}
 	if cfg.DexIssuerURL != "" {
-			payload["authorization_servers"] = []string{cfg.DexIssuerURL}
+		mux.HandleFunc("GET /.well-known/oauth-protected-resource",
 			chassisauth.ProtectedResourceHandler(cfg.MCPResourceURL, cfg.DexIssuerURL))
 	}
 		_ = json.NewEncoder(w).Encode(payload)
 	})
 	addr := ":" + cfg.Port
 	logger.Info("gitea-mcp starting", "addr", addr, "version", "0.1.0")
@@ -3,8 +3,8 @@ module gitea.d-ma.be/mathias/gitea-mcp
 go 1.26.2
 require (
 	git.d-ma.be/mathias/mcp-chassis v0.2.0
 	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
 )
@@ -16,6 +16,7 @@ require (
 	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/jwx/v2 v2.1.6 // indirect
 	github.com/lestrrat-go/option v1.0.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/segmentio/asm v1.2.0 // indirect
@@ -1,3 +1,5 @@
 git.d-ma.be/mathias/mcp-chassis v0.2.0 h1:6fLmb7xqRa2nNVWsHaUbbfbArgDXJw/gDhb09clBIjo=
 git.d-ma.be/mathias/mcp-chassis v0.2.0/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
 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=
@@ -1,42 +0,0 @@
 package auth
 import (
 	"crypto/subtle"
 	"net/http"
 	"strings"
 )
 // BearerMiddleware authenticates requests via the Authorization header.
 //
 // A request is allowed when:
 //
 //  1. The Bearer token is a valid JWT issued by the configured Dex OIDC server, or
 //  2. The Bearer token matches staticToken (constant-time compare).
 //
 // Any other case — including missing or empty Authorization header — returns 401.
 //
 // The Gitea service PAT is intentionally NOT used to authenticate the caller:
 // it is only used by the Gitea client for upstream API calls. Decoupling the
 // two prevents the MCP endpoint from being reachable anonymously when a service
 // PAT happens to be configured.
 func BearerMiddleware(jwtValidator *JWTValidator, staticToken string, next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		bearer, hasBearer := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
 		if !hasBearer || bearer == "" {
 			http.Error(w, "unauthorized", http.StatusUnauthorized)
 			return
 		}
 		if jwtValidator.Validate(r.Context(), bearer) {
 			next.ServeHTTP(w, r)
 			return
 		}
 		if staticToken != "" && subtle.ConstantTimeCompare([]byte(bearer), []byte(staticToken)) == 1 {
 			next.ServeHTTP(w, r)
 			return
 		}
 		http.Error(w, "unauthorized", http.StatusUnauthorized)
 	})
 }
@@ -1,92 +0,0 @@
 package auth_test
 import (
 	"net/http"
 	"net/http/httptest"
 	"testing"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/auth"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 func okHandler(called *bool) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		if called != nil {
 			*called = true
 		}
 		w.WriteHeader(http.StatusOK)
 	})
 }
 func TestBearerMiddleware_NoAuthHeader(t *testing.T) {
 	srv := httptest.NewServer(auth.BearerMiddleware(nil, "", okHandler(nil)))
 	defer srv.Close()
 	resp, err := http.Post(srv.URL+"/mcp", "application/json", nil)
 	require.NoError(t, err)
 	defer func() { _ = resp.Body.Close() }()
 	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
 }
 func TestBearerMiddleware_NoAuthHeader_RejectsEvenWhenStaticConfigured(t *testing.T) {
 	// A configured staticToken must not allow unauthenticated callers through.
 	srv := httptest.NewServer(auth.BearerMiddleware(nil, "any-static", okHandler(nil)))
 	defer srv.Close()
 	resp, err := http.Post(srv.URL+"/mcp", "application/json", nil)
 	require.NoError(t, err)
 	defer func() { _ = resp.Body.Close() }()
 	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
 }
 func TestBearerMiddleware_EmptyBearer(t *testing.T) {
 	srv := httptest.NewServer(auth.BearerMiddleware(nil, "static", okHandler(nil)))
 	defer srv.Close()
 	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/mcp", nil)
 	req.Header.Set("Authorization", "Bearer ")
 	resp, err := http.DefaultClient.Do(req)
 	require.NoError(t, err)
 	defer func() { _ = resp.Body.Close() }()
 	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
 }
 func TestBearerMiddleware_StaticToken_Valid(t *testing.T) {
 	const staticToken = "my-static-token"
 	called := false
 	srv := httptest.NewServer(auth.BearerMiddleware(nil, staticToken, okHandler(&called)))
 	defer srv.Close()
 	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/mcp", nil)
 	req.Header.Set("Authorization", "Bearer "+staticToken)
 	resp, err := http.DefaultClient.Do(req)
 	require.NoError(t, err)
 	defer func() { _ = resp.Body.Close() }()
 	assert.Equal(t, http.StatusOK, resp.StatusCode)
 	assert.True(t, called)
 }
 func TestBearerMiddleware_StaticToken_Invalid(t *testing.T) {
 	srv := httptest.NewServer(auth.BearerMiddleware(nil, "correct-token", okHandler(nil)))
 	defer srv.Close()
 	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/mcp", nil)
 	req.Header.Set("Authorization", "Bearer wrong-token")
 	resp, err := http.DefaultClient.Do(req)
 	require.NoError(t, err)
 	defer func() { _ = resp.Body.Close() }()
 	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
 }
 func TestBearerMiddleware_UnknownBearer_NoStatic_NoJWT(t *testing.T) {
 	srv := httptest.NewServer(auth.BearerMiddleware(nil, "", okHandler(nil)))
 	defer srv.Close()
 	req, _ := http.NewRequest(http.MethodPost, srv.URL+"/mcp", nil)
 	req.Header.Set("Authorization", "Bearer random-unknown-token")
 	resp, err := http.DefaultClient.Do(req)
 	require.NoError(t, err)
 	defer func() { _ = resp.Body.Close() }()
 	assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
 }
@@ -1,79 +0,0 @@
 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
 }
@@ -3,8 +3,10 @@ package gitea
 import (
 	"bytes"
 	"context"
 	"fmt"
 	"io"
 	"net/http"
 	"strings"
 	"time"
 	"github.com/hashicorp/golang-lru/v2/expirable"
@@ -40,7 +42,21 @@ func (c *Client) DefaultBranch(ctx context.Context, owner, name string) (string,
 	return repo.DefaultBranch, nil
 }
 // hasEmptySegment reports whether the path portion (before any query string)
 // contains an empty segment ("//"), which means an owner or repo path
 // parameter was empty. Forwarding it upstream yields gitea's opaque
 // /api/swagger 404 (#36), so callers reject it locally instead.
 func hasEmptySegment(path string) bool {
 	if i := strings.IndexByte(path, '?'); i >= 0 {
 		path = path[:i]
 	}
 	return strings.Contains(path, "//")
 }
 func (c *Client) doOnce(ctx context.Context, method, path string, body []byte) ([]byte, int, error) {
 	if hasEmptySegment(path) {
 		return nil, 0, fmt.Errorf("%w: upstream path %q has an empty owner or repo segment", ErrValidation, path)
 	}
 	var reader io.Reader
 	if body != nil {
 		reader = bytes.NewReader(body)
@@ -107,6 +123,9 @@ type rawResponse struct {
 }
 func (c *Client) doRaw(ctx context.Context, method, path string, body []byte) (*rawResponse, error) {
 	if hasEmptySegment(path) {
 		return nil, fmt.Errorf("%w: upstream path %q has an empty owner or repo segment", ErrValidation, path)
 	}
 	var reader io.Reader
 	if body != nil {
 		reader = bytes.NewReader(body)
@@ -0,0 +1,54 @@
 package gitea_test
 import (
 	"context"
 	"net/http"
 	"net/http/httptest"
 	"sync/atomic"
 	"testing"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 // #36 second line of defence: when owner or repo is empty the path contains an
 // empty segment ("//"). Rather than forward it upstream — where gitea answers
 // with its opaque /api/swagger 404 — the client must reject it locally with a
 // validation error and never touch the network.
 func TestEmptyPathSegmentRejectedBeforeNetwork(t *testing.T) {
 	var hits int32
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		atomic.AddInt32(&hits, 1)
 		w.WriteHeader(http.StatusOK)
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	paths := []string{
 		"/api/v1/repos/mathias//issues",        // empty repo
 		"/api/v1/repos//gitea-mcp/contents/",    // empty owner
 		"/api/v1/repos/mathias//issues?state=open", // empty repo before query
 	}
 	for _, p := range paths {
 		_, _, err := c.GetJSON(context.Background(), p)
 		require.Error(t, err, "path %q should be rejected", p)
 		assert.ErrorIs(t, err, gitea.ErrValidation)
 	}
 	assert.Equal(t, int32(0), atomic.LoadInt32(&hits), "guard must short-circuit before any HTTP call")
 }
 // A well-formed path with a query string must still pass the guard.
 func TestWellFormedPathPasses(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(`[]`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	_, status, err := c.GetJSON(context.Background(), "/api/v1/repos/mathias/gitea-mcp/issues?state=open")
 	require.NoError(t, err)
 	assert.Equal(t, 200, status)
 }
@@ -4,6 +4,8 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
 	"net/url"
 	"strconv"
 )
 type Issue struct {
@@ -12,6 +14,20 @@ type Issue struct {
 	Body      string  `json:"body"`
 	HTMLURL   string  `json:"html_url"`
 	State     string  `json:"state"`
 	CreatedAt string  `json:"created_at"`
 	UpdatedAt string  `json:"updated_at"`
 	Labels    []Label `json:"labels"`
 	Assignees []User  `json:"assignees"`
 	Comments  int     `json:"comments"`
 }
 type Label struct {
 	ID   int64  `json:"id"`
 	Name string `json:"name"`
 }
 type User struct {
 	Login string `json:"login"`
 }
 type CreateIssueArgs struct {
@@ -22,6 +38,22 @@ type CreateIssueArgs struct {
 	Milestone int64    `json:"milestone,omitempty"`
 }
 func (c *Client) GetIssue(ctx context.Context, owner, repo string, number int) (*Issue, error) {
 	p := fmt.Sprintf("/api/v1/repos/%s/%s/issues/%d", owner, repo, number)
 	body, status, err := c.GetJSON(ctx, p)
 	if err != nil {
 		return nil, err
 	}
 	if err := MapStatus(status, body); err != nil {
 		return nil, err
 	}
 	var iss Issue
 	if err := json.Unmarshal(body, &iss); err != nil {
 		return nil, err
 	}
 	return &iss, nil
 }
 func (c *Client) CreateIssue(ctx context.Context, owner, repo string, args CreateIssueArgs) (*Issue, error) {
 	p := fmt.Sprintf("/api/v1/repos/%s/%s/issues", owner, repo)
 	payload, err := json.Marshal(args)
@@ -42,10 +74,128 @@ func (c *Client) CreateIssue(ctx context.Context, owner, repo string, args Creat
 	return &iss, nil
 }
 // ListIssuesArgs captures the optional query params for ListIssues.
 type ListIssuesArgs struct {
 	State  string // "open" | "closed" | "all"
 	Labels string // comma-separated label names
 	Since  string // ISO 8601
 	Page   int
 	Limit  int
 }
 // ListIssues fetches issues for a repo. Pulls are excluded server-side
 // (type=issues) so they don't leak through the same endpoint.
 func (c *Client) ListIssues(ctx context.Context, owner, repo string, args ListIssuesArgs) ([]Issue, error) {
 	q := url.Values{}
 	q.Set("type", "issues")
 	if args.State != "" {
 		q.Set("state", args.State)
 	}
 	if args.Labels != "" {
 		q.Set("labels", args.Labels)
 	}
 	if args.Since != "" {
 		q.Set("since", args.Since)
 	}
 	if args.Page > 0 {
 		q.Set("page", strconv.Itoa(args.Page))
 	}
 	if args.Limit > 0 {
 		q.Set("limit", strconv.Itoa(args.Limit))
 	}
 	p := fmt.Sprintf("/api/v1/repos/%s/%s/issues?%s", owner, repo, q.Encode())
 	body, status, err := c.GetJSON(ctx, p)
 	if err != nil {
 		return nil, err
 	}
 	if err := MapStatus(status, body); err != nil {
 		return nil, err
 	}
 	var issues []Issue
 	if err := json.Unmarshal(body, &issues); err != nil {
 		return nil, err
 	}
 	return issues, nil
 }
 // SetIssueState flips an issue between "open" and "closed" via PATCH.
 // Gitea uses the same endpoint for both transitions.
 func (c *Client) SetIssueState(ctx context.Context, owner, repo string, number int, state string) (*Issue, error) {
 	p := fmt.Sprintf("/api/v1/repos/%s/%s/issues/%d", owner, repo, number)
 	payload, err := json.Marshal(map[string]string{"state": state})
 	if err != nil {
 		return nil, err
 	}
 	body, status, err := c.PatchJSON(ctx, p, payload)
 	if err != nil {
 		return nil, err
 	}
 	if err := MapStatus(status, body); err != nil {
 		return nil, err
 	}
 	var iss Issue
 	if err := json.Unmarshal(body, &iss); err != nil {
 		return nil, err
 	}
 	return &iss, nil
 }
 // EditIssueArgs uses pointers so omitempty distinguishes "not set" (nil,
 // left untouched) from an explicit empty string (clears the field). Maps to
 // Gitea's PATCH /repos/{owner}/{repo}/issues/{index}.
 type EditIssueArgs struct {
 	Title *string `json:"title,omitempty"`
 	Body  *string `json:"body,omitempty"`
 }
 // EditIssue patches an issue's title and/or body. Only fields set in args are
 // sent, so omitted fields are left as-is server-side. Body is sent verbatim —
 // no identity footer — so repeated edits are idempotent.
 func (c *Client) EditIssue(ctx context.Context, owner, repo string, number int, args EditIssueArgs) (*Issue, error) {
 	p := fmt.Sprintf("/api/v1/repos/%s/%s/issues/%d", owner, repo, number)
 	payload, err := json.Marshal(args)
 	if err != nil {
 		return nil, err
 	}
 	body, status, err := c.PatchJSON(ctx, p, payload)
 	if err != nil {
 		return nil, err
 	}
 	if err := MapStatus(status, body); err != nil {
 		return nil, err
 	}
 	var iss Issue
 	if err := json.Unmarshal(body, &iss); err != nil {
 		return nil, err
 	}
 	return &iss, nil
 }
 type IssueComment struct {
 	ID        int64  `json:"id"`
 	Body      string `json:"body"`
 	HTMLURL   string `json:"html_url"`
 	User      User   `json:"user,omitempty"`
 	CreatedAt string `json:"created_at,omitempty"`
 	UpdatedAt string `json:"updated_at,omitempty"`
 }
 // ListIssueComments fetches all comments on an issue or pull request.
 // Per Gitea, /issues/{index}/comments serves both since PRs share index space with issues.
 func (c *Client) ListIssueComments(ctx context.Context, owner, repo string, index int) ([]IssueComment, error) {
 	p := fmt.Sprintf("/api/v1/repos/%s/%s/issues/%d/comments", owner, repo, index)
 	body, status, err := c.GetJSON(ctx, p)
 	if err != nil {
 		return nil, err
 	}
 	if err := MapStatus(status, body); err != nil {
 		return nil, err
 	}
 	var comments []IssueComment
 	if err := json.Unmarshal(body, &comments); err != nil {
 		return nil, err
 	}
 	return comments, nil
 }
 // CreateIssueComment posts to /issues/{index}/comments. Per Gitea, this same endpoint
@@ -45,6 +45,127 @@ func TestCreateIssue(t *testing.T) {
 	assert.Equal(t, "open", iss.State)
 }
 func TestGetIssue(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/o/r/issues/42", r.URL.Path)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"number":42,"title":"fix auth","body":"details","state":"open","html_url":"http://example.com/issues/42","created_at":"2026-05-01T00:00:00Z","updated_at":"2026-05-02T00:00:00Z","comments":3}`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	iss, err := c.GetIssue(context.Background(), "o", "r", 42)
 	require.NoError(t, err)
 	assert.Equal(t, 42, iss.Number)
 	assert.Equal(t, "fix auth", iss.Title)
 	assert.Equal(t, "open", iss.State)
 	assert.Equal(t, 3, iss.Comments)
 }
 func TestGetIssue_NotFound(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 		_, _ = w.Write([]byte(`{"message":"issue not found"}`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	_, err := c.GetIssue(context.Background(), "o", "r", 999)
 	require.Error(t, err)
 	assert.ErrorIs(t, err, gitea.ErrNotFound)
 }
 func TestEditIssue(t *testing.T) {
 	var captured []byte
 	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/o/r/issues/42", r.URL.Path)
 		var err error
 		captured, err = io.ReadAll(r.Body)
 		require.NoError(t, err)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"number":42,"title":"new title","body":"new body","state":"open","html_url":"http://example.com/issues/42"}`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	title, body := "new title", "new body"
 	iss, err := c.EditIssue(context.Background(), "o", "r", 42, gitea.EditIssueArgs{Title: &title, Body: &body})
 	require.NoError(t, err)
 	var payload map[string]any
 	require.NoError(t, json.Unmarshal(captured, &payload))
 	assert.Equal(t, "new title", payload["title"])
 	assert.Equal(t, "new body", payload["body"])
 	assert.Equal(t, 42, iss.Number)
 	assert.Equal(t, "new title", iss.Title)
 }
 // EditIssue must send only the fields explicitly provided — an omitted field
 // (nil pointer) is left untouched server-side.
 func TestEditIssue_PartialPatchOmitsUnsetFields(t *testing.T) {
 	var captured []byte
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		var err error
 		captured, err = io.ReadAll(r.Body)
 		require.NoError(t, err)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"number":42,"title":"only title","state":"open"}`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	title := "only title"
 	_, err := c.EditIssue(context.Background(), "o", "r", 42, gitea.EditIssueArgs{Title: &title})
 	require.NoError(t, err)
 	var payload map[string]any
 	require.NoError(t, json.Unmarshal(captured, &payload))
 	assert.Equal(t, "only title", payload["title"])
 	_, hasBody := payload["body"]
 	assert.False(t, hasBody, "body must be omitted when not set")
 }
 // An explicit empty-string body clears the field — pointer-to-"" is sent, not omitted.
 func TestEditIssue_EmptyBodyIsSent(t *testing.T) {
 	var captured []byte
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		var err error
 		captured, err = io.ReadAll(r.Body)
 		require.NoError(t, err)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"number":42,"body":"","state":"open"}`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	body := ""
 	_, err := c.EditIssue(context.Background(), "o", "r", 42, gitea.EditIssueArgs{Body: &body})
 	require.NoError(t, err)
 	var payload map[string]any
 	require.NoError(t, json.Unmarshal(captured, &payload))
 	val, hasBody := payload["body"]
 	assert.True(t, hasBody, "explicit empty body must be sent so it can clear the field")
 	assert.Equal(t, "", val)
 }
 func TestEditIssue_NotFound(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 		_, _ = w.Write([]byte(`{"message":"issue not found"}`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	title := "x"
 	_, err := c.EditIssue(context.Background(), "o", "r", 999, gitea.EditIssueArgs{Title: &title})
 	require.Error(t, err)
 	assert.ErrorIs(t, err, gitea.ErrNotFound)
 }
 func TestCreateIssueComment(t *testing.T) {
 	var captured []byte
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -70,3 +191,51 @@ func TestCreateIssueComment(t *testing.T) {
 	assert.Equal(t, "hello", comment.Body)
 	assert.Equal(t, "http://example.com/issues/42#comment-7", comment.HTMLURL)
 }
 func TestListIssueComments(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/o/r/issues/42/comments", r.URL.Path)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`[
 			{"id":1,"body":"first","html_url":"http://example.com/issues/42#comment-1","user":{"login":"alice"},"created_at":"2026-05-01T00:00:00Z","updated_at":"2026-05-01T00:00:00Z"},
 			{"id":2,"body":"second","html_url":"http://example.com/issues/42#comment-2","user":{"login":"bob"},"created_at":"2026-05-02T00:00:00Z","updated_at":"2026-05-02T00:00:00Z"}
 		]`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	comments, err := c.ListIssueComments(context.Background(), "o", "r", 42)
 	require.NoError(t, err)
 	require.Len(t, comments, 2)
 	assert.Equal(t, int64(1), comments[0].ID)
 	assert.Equal(t, "first", comments[0].Body)
 	assert.Equal(t, "alice", comments[0].User.Login)
 	assert.Equal(t, "bob", comments[1].User.Login)
 }
 func TestListIssueComments_Empty(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(`[]`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	comments, err := c.ListIssueComments(context.Background(), "o", "r", 42)
 	require.NoError(t, err)
 	assert.Empty(t, comments)
 }
 func TestListIssueComments_NotFound(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 		_, _ = w.Write([]byte(`{"message":"issue not found"}`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	_, err := c.ListIssueComments(context.Background(), "o", "r", 999)
 	require.Error(t, err)
 	assert.ErrorIs(t, err, gitea.ErrNotFound)
 }
@@ -52,6 +52,59 @@ func (c *Client) GetTree(ctx context.Context, owner, repo, ref string, recursive
 	return &t, nil
 }
 type Release struct {
 	ID         int64  `json:"id"`
 	TagName    string `json:"tag_name"`
 	Name       string `json:"name"`
 	Body       string `json:"body"`
 	Draft      bool   `json:"draft"`
 	Prerelease bool   `json:"prerelease"`
 	HTMLURL    string `json:"html_url"`
 	CreatedAt  string `json:"created_at"`
 }
 type CreateReleaseArgs struct {
 	TagName    string `json:"tag_name"`
 	Name       string `json:"name,omitempty"`
 	Body       string `json:"body,omitempty"`
 	Draft      bool   `json:"draft,omitempty"`
 	Prerelease bool   `json:"prerelease,omitempty"`
 	// Target branch or commit SHA for tag creation. Empty = repo default branch.
 	Target string `json:"target_commitish,omitempty"`
 }
 func (c *Client) CreateRelease(ctx context.Context, owner, repo string, args CreateReleaseArgs) (*Release, error) {
 	path := fmt.Sprintf("/api/v1/repos/%s/%s/releases", 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 r Release
 	if err := json.Unmarshal(resp, &r); err != nil {
 		return nil, err
 	}
 	return &r, nil
 }
 func (c *Client) DeleteRepo(ctx context.Context, owner, repo string) error {
 	path := fmt.Sprintf("/api/v1/repos/%s/%s", owner, repo)
 	resp, status, err := c.DeleteJSON(ctx, path)
 	if err != nil {
 		return err
 	}
 	if status == 204 {
 		return nil
 	}
 	return MapStatus(status, resp)
 }
 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})
@@ -163,6 +216,8 @@ type UpdateRepoArgs struct {
 	Private       *bool   `json:"private,omitempty"`
 	Website       *string `json:"website,omitempty"`
 	DefaultBranch *string `json:"default_branch,omitempty"`
 	Archived      *bool   `json:"archived,omitempty"`
 	Template      *bool   `json:"template,omitempty"`
 }
 func (c *Client) UpdateRepo(ctx context.Context, owner, name string, args UpdateRepoArgs) (*Repo, error) {
@@ -200,3 +255,4 @@ func (c *Client) GetRepo(ctx context.Context, owner, name string) (*Repo, error)
 	}
 	return &r, nil
 }
@@ -136,6 +136,40 @@ func TestUpdateTopics(t *testing.T) {
 	require.NoError(t, err)
 }
 func TestCreateRelease(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/releases", r.URL.Path)
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusCreated)
 		_, _ = w.Write([]byte(`{"id":1,"tag_name":"v1.0.0","name":"v1.0.0","body":"first release","draft":false,"prerelease":false,"html_url":"https://gitea.example.com/mathias/infra/releases/tag/v1.0.0","created_at":"2026-05-15T00:00:00Z"}`))
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	rel, err := c.CreateRelease(context.Background(), "mathias", "infra", gitea.CreateReleaseArgs{
 		TagName: "v1.0.0",
 		Name:    "v1.0.0",
 		Body:    "first release",
 	})
 	require.NoError(t, err)
 	assert.Equal(t, "v1.0.0", rel.TagName)
 	assert.Equal(t, "first release", rel.Body)
 }
 func TestDeleteRepo(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", r.URL.Path)
 		w.WriteHeader(http.StatusNoContent)
 	}))
 	defer srv.Close()
 	c := gitea.NewClient(srv.URL, "tok")
 	err := c.DeleteRepo(context.Background(), "mathias", "infra")
 	require.NoError(t, err)
 }
 func TestDefaultBranchCachesAcrossCalls(t *testing.T) {
 	var hits int32
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
 	"net/url"
 	"strconv"
 	"strings"
 )
@@ -55,10 +56,20 @@ func (c *Client) DispatchWorkflow(ctx context.Context, owner, repo, workflow str
 // WorkflowRun represents a Gitea Actions run.
 type WorkflowRun struct {
 	ID           int64  `json:"id"`
 	DisplayTitle string `json:"display_title,omitempty"`
 	Status       string `json:"status"`     // queued | in_progress | completed
 	Conclusion   string `json:"conclusion"` // success | failure | cancelled | skipped (only when completed)
 	Event        string `json:"event,omitempty"`
 	HeadSHA      string `json:"head_sha,omitempty"`
 	HeadBranch   string `json:"head_branch,omitempty"`
 	WorkflowID   string `json:"workflow_id,omitempty"`
 	RunNumber    int64  `json:"run_number,omitempty"`
 	StartedAt    string `json:"started_at"`
 	UpdatedAt    string `json:"updated_at,omitempty"`
 	HTMLURL      string `json:"html_url"`
 	Actor        struct {
 		Login string `json:"login"`
 	} `json:"actor,omitempty"`
 }
 // GetWorkflowRun fetches the status of a specific Actions run.
@@ -77,3 +88,59 @@ func (c *Client) GetWorkflowRun(ctx context.Context, owner, repo string, runID i
 	}
 	return &run, nil
 }
 // ListWorkflowRunsArgs captures the optional query params for ListWorkflowRuns.
 type ListWorkflowRunsArgs struct {
 	Branch   string
 	HeadSHA  string
 	Status   string // queued | in_progress | completed | all
 	Event    string // push | pull_request | schedule | workflow_dispatch | all
 	Workflow string
 	Page     int
 	Limit    int
 }
 type workflowRunsResponse struct {
 	TotalCount   int64         `json:"total_count"`
 	WorkflowRuns []WorkflowRun `json:"workflow_runs"`
 }
 // ListWorkflowRuns fetches recent Actions runs for a repo with optional filters.
 // Status / Event of "all" or "" are treated as no-filter.
 func (c *Client) ListWorkflowRuns(ctx context.Context, owner, repo string, args ListWorkflowRunsArgs) (*workflowRunsResponse, error) {
 	q := url.Values{}
 	if args.Branch != "" {
 		q.Set("branch", args.Branch)
 	}
 	if args.HeadSHA != "" {
 		q.Set("head_sha", args.HeadSHA)
 	}
 	if args.Status != "" && args.Status != "all" {
 		q.Set("status", args.Status)
 	}
 	if args.Event != "" && args.Event != "all" {
 		q.Set("event", args.Event)
 	}
 	if args.Workflow != "" {
 		q.Set("workflow", args.Workflow)
 	}
 	if args.Page > 0 {
 		q.Set("page", strconv.Itoa(args.Page))
 	}
 	if args.Limit > 0 {
 		q.Set("limit", strconv.Itoa(args.Limit))
 	}
 	p := fmt.Sprintf("/api/v1/repos/%s/%s/actions/runs?%s", owner, repo, q.Encode())
 	body, status, err := c.GetJSON(ctx, p)
 	if err != nil {
 		return nil, err
 	}
 	if err := MapStatus(status, body); err != nil {
 		return nil, err
 	}
 	var resp workflowRunsResponse
 	if err := json.Unmarshal(body, &resp); err != nil {
 		return nil, err
 	}
 	return &resp, nil
 }
@@ -0,0 +1,49 @@
 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"
 )
 // #36: every caller (claude.ai connector, gitea's own convention) sends the
 // repo identifier as `repo` and issue/PR index as `index`, but the tools
 // declare them as `name` and `number`. Unmatched fields zero-valued the path
 // segment and produced gitea's misleading /api/swagger 404. parseArgs now
 // aliases repo->name and index->number so the idiomatic call works.
 func TestRepoAndIndexAliasesResolve(t *testing.T) {
 	tests := []struct {
 		name     string
 		args     string
 		wantPath string
 	}{
 		{"repo+index aliases", `{"owner":"mathias","repo":"infra","index":7}`, "/api/v1/repos/mathias/infra/issues/7"},
 		{"canonical name+number", `{"owner":"mathias","name":"infra","number":7}`, "/api/v1/repos/mathias/infra/issues/7"},
 		{"explicit name wins over repo", `{"owner":"mathias","name":"infra","repo":"ignored","number":7}`, "/api/v1/repos/mathias/infra/issues/7"},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
 			var gotPath string
 			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 				gotPath = r.URL.Path
 				w.Header().Set("Content-Type", "application/json")
 				_, _ = w.Write([]byte(`{"number":7,"title":"t"}`))
 			}))
 			defer srv.Close()
 			tool := tools.NewIssueGet(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 			out, err := tool.Call(context.Background(), json.RawMessage(tc.args))
 			require.NoError(t, err)
 			assert.Equal(t, tc.wantPath, gotPath)
 			assert.Contains(t, string(out), `"number":7`)
 		})
 	}
 }
@@ -2,10 +2,13 @@ package tools
 import (
 	"context"
 	"encoding/base64"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"regexp"
 	"strings"
 	"time"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
@@ -14,22 +17,22 @@ import (
 var nameRe = regexp.MustCompile(`^[a-z][a-z0-9-]{1,38}[a-z0-9]$`)
 var substitutionFiles = []string{
 	"go.mod",
 	"Taskfile.yml",
 	"Dockerfile",
 	".gitea/workflows/cd.yml",
 	"README.md",
 	".context/PROJECT.md",
 }
 func substitutions(owner, name string) map[string]string {
 	return map[string]string{
 		"__PROJECT_NAME__": name,
-		"__MODULE_PATH__":  "gitea.d-ma.be/" + owner + "/" + name,
+		// git.d-ma.be is the canonical module host (the gitea.d-ma.be → git.d-ma.be
 		// rename; a stale host breaks `go mod download` for downstream consumers).
 		"__MODULE_PATH__": "git.d-ma.be/" + owner + "/" + name,
 	}
 }
 func applyReplacements(s string, repls map[string]string) string {
 	for k, v := range repls {
 		s = strings.ReplaceAll(s, k, v)
 	}
 	return s
 }
 // CreateProjectFromTemplate is the exported type so tests can reference it.
 type CreateProjectFromTemplate struct {
 	c             *gitea.Client
@@ -45,14 +48,16 @@ func NewCreateProjectFromTemplate(c *gitea.Client, a *allowlist.Allowlist, tmplO
 func (t *CreateProjectFromTemplate) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "create_project_from_template",
-		Description: "Create a new project repo from the template, applying placeholder substitutions to known files.",
+		Description: "Create a new project repo from a template. Best-effort substitution of placeholders (__PROJECT_NAME__, __MODULE_PATH__) in every file's content AND path (e.g. renaming cmd/__PROJECT_NAME__/): it completes only if the generated branch is promptly writable. If gitea's async generate is slow (infra#179) the repo is still created and partial_failure explains how to finalize locally (`hyperguild new-project`). Check files_substituted and partial_failure. Defaults to the server-configured template; pass template_name to override (e.g. template-go-agent). Pass dispatch_allow=true to also inject a .dispatch-allow file so the project is immediately dispatch-eligible (dispatch#3).",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,38}[a-z0-9]$"},
 				"description":{"type":"string"},
-				"private":{"type":"boolean"}
+				"private":{"type":"boolean"},
 				"template_name":{"type":"string","description":"Template repo name to generate from. Defaults to the server-configured template."},
 				"dispatch_allow":{"type":"boolean","description":"When true, inject a .dispatch-allow file so the new project is immediately opt-in for headless dispatch (dispatch#3). Default false."}
 			},
 			"required":["owner","name"]
 		}`),
@@ -64,8 +69,16 @@ type createProjectArgs struct {
 	Name          string `json:"name"`
 	Description   string `json:"description"`
 	Private       bool   `json:"private"`
 	TemplateName  string `json:"template_name"`
 	DispatchAllow bool   `json:"dispatch_allow"`
 }
 // dispatchAllowContent is the body injected when dispatch_allow=true. Mirrors the
 // sandbox convention: presence of the file (not its content) marks the repo
 // dispatch-eligible; the comment exists only to explain that to a human reader.
 const dispatchAllowContent = "# Presence of this file marks this repo as opt-in for headless dispatch.\n" +
 	"# See dispatch#3.\n"
 type createProjectResult struct {
 	FullName         string   `json:"full_name"`
 	HTMLURL          string   `json:"html_url"`
@@ -91,13 +104,20 @@ func (t *CreateProjectFromTemplate) Call(ctx context.Context, raw json.RawMessag
 		return nil, fmt.Errorf("name %q does not match pattern %s: %w", args.Name, nameRe.String(), gitea.ErrValidation)
 	}
 	// Resolve template: per-call override takes precedence over the
 	// server-configured default. Owner stays server-configured.
 	tmplName := args.TemplateName
 	if tmplName == "" {
 		tmplName = t.templateName
 	}
 	// Verify template exists and is marked as a template repo.
-	tmpl, err := t.c.GetRepo(ctx, t.templateOwner, t.templateName)
+	tmpl, err := t.c.GetRepo(ctx, t.templateOwner, tmplName)
 	if err != nil {
 		return nil, fmt.Errorf("template lookup: %w", err)
 	}
 	if !tmpl.Template {
-		return nil, fmt.Errorf("repo %s/%s is not marked as template: %w", t.templateOwner, t.templateName, gitea.ErrValidation)
+		return nil, fmt.Errorf("repo %s/%s is not marked as template: %w", t.templateOwner, tmplName, gitea.ErrValidation)
 	}
 	// Verify destination doesn't already exist.
@@ -108,7 +128,7 @@ func (t *CreateProjectFromTemplate) Call(ctx context.Context, raw json.RawMessag
 	}
 	// Generate repo from template.
-	newRepo, err := t.c.GenerateFromTemplate(ctx, t.templateOwner, t.templateName, gitea.GenerateFromTemplateArgs{
+	newRepo, err := t.c.GenerateFromTemplate(ctx, t.templateOwner, tmplName, gitea.GenerateFromTemplateArgs{
 		Owner:       args.Owner,
 		Name:        args.Name,
 		Description: args.Description,
@@ -126,21 +146,167 @@ func (t *CreateProjectFromTemplate) Call(ctx context.Context, raw json.RawMessag
 		DefaultBranch: newRepo.DefaultBranch,
 	}
-	// Substitute placeholders in known files (best-effort).
+	// The /generate response often omits default_branch — resolve it explicitly,
-	repls := substitutions(args.Owner, args.Name)
+	// otherwise every file read below hits an empty ref and nothing substitutes
 	// (the silent-null bug: gitea-mcp#42).
 	branch := newRepo.DefaultBranch
-	for _, path := range substitutionFiles {
+	if branch == "" {
-		if err := t.c.SubstituteFile(ctx, args.Owner, args.Name, branch, path, repls); err != nil {
+		if r, gerr := t.c.GetRepo(ctx, args.Owner, args.Name); gerr == nil && r.DefaultBranch != "" {
-			// Files that don't exist in this template are silently skipped.
+			branch = r.DefaultBranch
-			if errors.Is(err, gitea.ErrNotFound) {
+		} else {
 			branch = "main"
 		}
 	}
 	result.DefaultBranch = branch
 	// Substitute across the WHOLE tree: content in every blob, plus a path rename
 	// for any file whose path carries a placeholder (e.g. cmd/__PROJECT_NAME__/main.go).
 	// A fixed known-files list can't rename directories or cover every templated
 	// file, which is why the old scaffold didn't build.
 	repls := substitutions(args.Owner, args.Name)
 	tree, err := t.c.GetTree(ctx, args.Owner, args.Name, branch, true)
 	if err != nil {
 		result.PartialFailure = fmt.Sprintf("tree walk (%s@%s): %v", args.Name, branch, err)
 		return textOK(result)
 	}
 	for _, e := range tree.Tree {
 		if e.Type != "blob" {
 			continue
 		}
-			// Any other error halts the substitution pass with partial_failure recorded.
+		substituted, fail := t.substituteEntry(ctx, args.Owner, args.Name, branch, e.Path, repls)
-			result.PartialFailure = fmt.Sprintf("%s: %v", path, err)
+		if fail != "" {
 			result.PartialFailure = fail
 			break
 		}
-		result.FilesSubstituted = append(result.FilesSubstituted, path)
+		if substituted != "" {
 			result.FilesSubstituted = append(result.FilesSubstituted, substituted)
 		}
 	}
 	// Opt the new project into headless dispatch if asked: presence of a
 	// .dispatch-allow file on the default branch marks it dispatch-eligible
 	// (dispatch#3). Ride the same upsertRetry path as substitution so it inherits
 	// the infra#179 branch-readiness / partial-failure handling below. Skip if the
 	// loop already stalled — a failed injection then degrades identically.
 	if args.DispatchAllow && result.PartialFailure == "" {
 		const dispatchAllowPath = ".dispatch-allow"
 		if err := t.upsertRetry(ctx, args.Owner, args.Name, dispatchAllowPath, gitea.UpsertFileArgs{
 			Branch:  branch,
 			Content: base64.StdEncoding.EncodeToString([]byte(dispatchAllowContent)),
 			Message: "dispatch: mark project dispatch-eligible (dispatch#3)",
 		}); err != nil {
 			result.PartialFailure = fmt.Sprintf("write %s: %v", dispatchAllowPath, err)
 		} else {
 			result.FilesSubstituted = append(result.FilesSubstituted, dispatchAllowPath)
 		}
 	}
 	// If substitution stalled because the generated branch wasn't writable in time,
 	// the repo IS created — say so clearly and point to the local finalize step,
 	// rather than leaking the raw "branch does not exist" (infra#179: gitea's
 	// template-generate is slow-async on this instance, so tool-side substitution
 	// is best-effort).
 	if strings.Contains(result.PartialFailure, "branch does not exist") ||
 		strings.Contains(result.PartialFailure, "not found") {
 		result.PartialFailure = fmt.Sprintf(
 			"repo created, but its branch (%s) was not writable within %ds — gitea's "+
 				"template-generate is slow-async on this instance (infra#179), so substitution "+
 				"is incomplete (%d file(s) done). Finalize locally with `hyperguild new-project` "+
 				"(clone + substitute, no API race). Underlying: %s",
 			branch, substitutionBudget, len(result.FilesSubstituted), result.PartialFailure)
 	}
 	// Fail loud: a scaffold that still holds placeholders does not build. Nothing
 	// substituted (with no explicit failure) means the walk found no placeholders —
 	// suspicious for a real template. Surface it instead of returning silent success.
 	if result.PartialFailure == "" && len(result.FilesSubstituted) == 0 {
 		result.PartialFailure = fmt.Sprintf("no placeholders substituted in %s@%s — verify the scaffold is not left templated", args.Name, branch)
 	}
 	return textOK(result)
 }
 // substitutionBudget bounds how long we retry the first write while the freshly
 // generated branch becomes writable. gitea's /generate returns (and serves reads)
 // before the branch ref is committed, so writes 404 "branch does not exist" for a
 // window. We keep the budget SHORT so the MCP call stays responsive: a healthy
 // gitea commits in ~1s and this catches it; a slow one (infra#179, observed >40s)
 // fails fast and we defer substitution with clear guidance rather than hang.
 const substitutionBudget = 5
 // upsertRetry retries UpsertFile on the transient post-generate "branch does not
 // exist" not-found, up to substitutionBudget. The write itself is the readiness
 // probe — BranchExists reports the branch present before writes succeed.
 func (t *CreateProjectFromTemplate) upsertRetry(ctx context.Context, owner, name, path string, args gitea.UpsertFileArgs) error {
 	var err error
 	for i := 0; i < substitutionBudget; i++ {
 		if _, err = t.c.UpsertFile(ctx, owner, name, path, args); err == nil {
 			return nil
 		}
 		if !errors.Is(err, gitea.ErrNotFound) {
 			return err
 		}
 		select {
 		case <-ctx.Done():
 			return err
 		case <-time.After(time.Second):
 		}
 	}
 	return err
 }
 // substituteEntry substitutes placeholders in one blob. If the path carries a
 // placeholder it renames the file (write new + delete old); otherwise it rewrites
 // content in place when changed. Returns a human-readable description of what was
 // substituted ("" if nothing), and a non-empty partial-failure string on error.
 func (t *CreateProjectFromTemplate) substituteEntry(ctx context.Context, owner, name, branch, path string, repls map[string]string) (substituted, failure string) {
 	newPath := applyReplacements(path, repls)
 	fc, err := t.c.GetFileContents(ctx, owner, name, path, branch)
 	if err != nil {
 		if errors.Is(err, gitea.ErrNotFound) {
 			return "", "" // vanished between tree walk and read; skip
 		}
 		return "", fmt.Sprintf("read %s: %v", path, err)
 	}
 	decoded, err := base64.StdEncoding.DecodeString(fc.Content)
 	if err != nil {
 		return "", fmt.Sprintf("decode %s: %v", path, err)
 	}
 	newContent := applyReplacements(string(decoded), repls)
 	renamed := newPath != path
 	changed := newContent != string(decoded)
 	if !renamed && !changed {
 		return "", "" // nothing to do
 	}
 	enc := base64.StdEncoding.EncodeToString([]byte(newContent))
 	if renamed {
 		if err := t.upsertRetry(ctx, owner, name, newPath, gitea.UpsertFileArgs{
 			Branch:  branch,
 			Content: enc,
 			Message: fmt.Sprintf("template: substitute + rename %s -> %s", path, newPath),
 		}); err != nil {
 			return "", fmt.Sprintf("write %s: %v", newPath, err)
 		}
 		if _, err := t.c.DeleteFile(ctx, owner, name, path, gitea.DeleteFileArgs{
 			Branch:  branch,
 			Sha:     fc.Sha,
 			Message: fmt.Sprintf("template: drop placeholder path %s", path),
 		}); err != nil {
 			return "", fmt.Sprintf("delete %s: %v", path, err)
 		}
 		return path + " -> " + newPath, ""
 	}
 	if err := t.upsertRetry(ctx, owner, name, path, gitea.UpsertFileArgs{
 		Branch:  branch,
 		Content: enc,
 		Message: "template: substitute placeholders",
 		Sha:     fc.Sha,
 	}); err != nil {
 		return "", fmt.Sprintf("write %s: %v", path, err)
 	}
 	return path, ""
 }
@@ -5,9 +5,11 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"sync"
 	"testing"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
@@ -17,250 +19,294 @@ import (
 	"github.com/stretchr/testify/require"
 )
-// substitutionFileList matches the tool's internal list — used to drive fake server routing.
+func encb64(s string) string { return base64.StdEncoding.EncodeToString([]byte(s)) }
 var substitutionFileList = []string{
 	"go.mod",
 	"Taskfile.yml",
 	"Dockerfile",
 	".gitea/workflows/cd.yml",
 	"README.md",
 	".context/PROJECT.md",
 }
-// contentWithPlaceholder is a template file body that contains the placeholder.
+func templateRepoJSON(name string, isTemplate bool) string {
-const contentWithPlaceholder = "# __PROJECT_NAME__\nmodule __MODULE_PATH__\n"
+	return fmt.Sprintf(`{"name":%q,"full_name":"mathias/%s","default_branch":"main","clone_url":"http://gitea.example.com/mathias/%s.git","html_url":"http://gitea.example.com/mathias/%s","template":%v}`,
 func encodedContent(s string) string {
 	return base64.StdEncoding.EncodeToString([]byte(s))
 }
 // fileContentsJSON returns a JSON FileContents object for the given path.
 func fileContentsJSON(path string) string {
 	enc := encodedContent(contentWithPlaceholder)
 	return fmt.Sprintf(`{"path":%q,"sha":"sha-%s","size":40,"content":%q,"encoding":"base64"}`,
 		path, strings.ReplaceAll(path, "/", "-"), enc)
 }
 // fileWriteResultJSON returns a minimal FileWriteResult JSON.
 func fileWriteResultJSON(path string) string {
 	return fmt.Sprintf(`{"content":{"path":%q,"sha":"newsha","html_url":""},"commit":{"sha":"c","html_url":""}}`, path)
 }
 // newTemplateRepoJSON returns a JSON Repo marked as template.
 func newTemplateRepoJSON(name string, isTemplate bool) string {
 	return fmt.Sprintf(`{"name":%q,"full_name":"mathias/%s","default_branch":"main","description":"","private":false,"clone_url":"http://gitea.example.com/mathias/%s.git","html_url":"http://gitea.example.com/mathias/%s","template":%v}`,
 		name, name, name, name, isTemplate)
 }
-// newGeneratedRepoJSON returns the JSON for the newly generated repo.
+// fakeTemplateServer serves the whole create-from-template flow off an in-memory
-func newGeneratedRepoJSON(name string) string {
+// file map, driving the tool's tree-walk. Records writes/deletes/put-bodies.
-	return fmt.Sprintf(`{"name":%q,"full_name":"mathias/%s","default_branch":"main","description":"","private":false,"clone_url":"http://gitea.example.com/mathias/%s.git","html_url":"http://gitea.example.com/mathias/%s","template":false}`,
+type fakeTemplateServer struct {
-		name, name, name, name)
+	mu           sync.Mutex
 	files        map[string]string // path -> raw (un-substituted) content
 	genBranch    string            // default_branch returned by /generate ("" to force fallback)
 	generated    bool
 	puts         []string
 	deletes      []string
 	putBodies    map[string]string // path -> decoded written content
 	repoGetsPost int               // GET dest after generate (branch fallback)
 }
-func newCreateProjectTool(srvURL string) *tools.CreateProjectFromTemplate {
+func newFakeTemplateServer(files map[string]string, genBranch string) *fakeTemplateServer {
-	c := gitea.NewClient(srvURL, "tok")
+	return &fakeTemplateServer{files: files, genBranch: genBranch, putBodies: map[string]string{}}
 	a := allowlist.New([]string{"mathias"})
 	return tools.NewCreateProjectFromTemplate(c, a, "mathias", "template-go-web")
 }
-// TestCreateProjectHappyPath: all 6 files served and substituted.
+func (f *fakeTemplateServer) handler(t *testing.T, tmpl, dest string) http.HandlerFunc {
-func TestCreateProjectHappyPath(t *testing.T) {
+	return func(w http.ResponseWriter, r *http.Request) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
 		defer f.mu.Unlock()
 		w.Header().Set("Content-Type", "application/json")
-		switch {
+		p := r.URL.Path
 		// Template repo lookup
 		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/template-go-web":
 			_, _ = w.Write([]byte(newTemplateRepoJSON("template-go-web", true)))
-		// Destination repo lookup — 404 means it doesn't exist yet
+		switch {
-		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/new-svc":
+		case r.Method == http.MethodGet && p == "/api/v1/repos/mathias/"+tmpl:
 			_, _ = w.Write([]byte(templateRepoJSON(tmpl, true)))
 		case r.Method == http.MethodGet && p == "/api/v1/repos/mathias/"+dest:
 			if !f.generated {
 				w.WriteHeader(http.StatusNotFound)
 				_, _ = w.Write([]byte(`{"message":"not found"}`))
 				return
 			}
 			f.repoGetsPost++
 			_, _ = fmt.Fprintf(w, `{"name":%q,"full_name":"mathias/%s","default_branch":"main","clone_url":"c","html_url":"h","template":false}`, dest, dest)
-		// Generate
+		case r.Method == http.MethodPost && p == "/api/v1/repos/mathias/"+tmpl+"/generate":
-		case r.Method == http.MethodPost && r.URL.Path == "/api/v1/repos/mathias/template-go-web/generate":
+			f.generated = true
 			w.WriteHeader(http.StatusCreated)
-			_, _ = w.Write([]byte(newGeneratedRepoJSON("new-svc")))
+			_, _ = fmt.Fprintf(w, `{"name":%q,"full_name":"mathias/%s","default_branch":%q,"clone_url":"http://gitea.example.com/mathias/%s.git","html_url":"http://gitea.example.com/mathias/%s","template":false}`,
 				dest, dest, f.genBranch, dest, dest)
-		// File contents GET — handle all 6 substitution files
+		case r.Method == http.MethodGet && strings.HasPrefix(p, "/api/v1/repos/mathias/"+dest+"/git/trees/"):
-		case r.Method == http.MethodGet && strings.HasPrefix(r.URL.Path, "/api/v1/repos/mathias/new-svc/contents/"):
+			var entries []string
-			filePath := strings.TrimPrefix(r.URL.Path, "/api/v1/repos/mathias/new-svc/contents/")
+			for path := range f.files {
-			_, _ = w.Write([]byte(fileContentsJSON(filePath)))
+				entries = append(entries, fmt.Sprintf(`{"path":%q,"type":"blob","sha":"sha-%s"}`, path, strings.ReplaceAll(path, "/", "-")))
 			}
 			// include a tree (directory) entry to exercise the blob filter
 			entries = append(entries, `{"path":"cmd","type":"tree","sha":"treesha"}`)
 			_, _ = fmt.Fprintf(w, `{"sha":"root","tree":[%s],"truncated":false}`, strings.Join(entries, ","))
-		// File contents PUT — handle all 6 substitution files
+		case r.Method == http.MethodGet && strings.HasPrefix(p, "/api/v1/repos/mathias/"+dest+"/contents/"):
-		case r.Method == http.MethodPut && strings.HasPrefix(r.URL.Path, "/api/v1/repos/mathias/new-svc/contents/"):
+			path := strings.TrimPrefix(p, "/api/v1/repos/mathias/"+dest+"/contents/")
-			filePath := strings.TrimPrefix(r.URL.Path, "/api/v1/repos/mathias/new-svc/contents/")
+			body, ok := f.files[path]
 			if !ok {
 				w.WriteHeader(http.StatusNotFound)
 				_, _ = w.Write([]byte(`{"message":"not found"}`))
 				return
 			}
 			_, _ = fmt.Fprintf(w, `{"path":%q,"sha":"sha-%s","size":1,"content":%q,"encoding":"base64"}`,
 				path, strings.ReplaceAll(path, "/", "-"), encb64(body))
 		// POST = create (new/renamed file, no sha), PUT = update (existing, with sha).
 		case (r.Method == http.MethodPost || r.Method == http.MethodPut) && strings.HasPrefix(p, "/api/v1/repos/mathias/"+dest+"/contents/"):
 			path := strings.TrimPrefix(p, "/api/v1/repos/mathias/"+dest+"/contents/")
 			raw, _ := io.ReadAll(r.Body)
 			var args struct {
 				Content string `json:"content"`
 			}
 			_ = json.Unmarshal(raw, &args)
 			dec, _ := base64.StdEncoding.DecodeString(args.Content)
 			f.puts = append(f.puts, path)
 			f.putBodies[path] = string(dec)
 			if r.Method == http.MethodPost {
 				w.WriteHeader(http.StatusCreated)
 			} else {
 				w.WriteHeader(http.StatusOK)
-			_, _ = w.Write([]byte(fileWriteResultJSON(filePath)))
+			}
 			_, _ = w.Write([]byte(`{"content":{"path":"x","sha":"n"},"commit":{"sha":"c"}}`))
 		case r.Method == http.MethodDelete && strings.HasPrefix(p, "/api/v1/repos/mathias/"+dest+"/contents/"):
 			path := strings.TrimPrefix(p, "/api/v1/repos/mathias/"+dest+"/contents/")
 			f.deletes = append(f.deletes, path)
 			w.WriteHeader(http.StatusOK)
 			_, _ = w.Write([]byte(`{"content":null,"commit":{"sha":"c"}}`))
 		default:
-			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+			t.Errorf("unexpected request: %s %s", r.Method, p)
 			w.WriteHeader(http.StatusNotFound)
 		}
-	}))
+	}
-	defer srv.Close()
+}
-	tool := newCreateProjectTool(srv.URL)
+func newTool(srvURL, tmpl string) *tools.CreateProjectFromTemplate {
-	result, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"new-svc","description":"A new service"}`))
+	return tools.NewCreateProjectFromTemplate(
 		gitea.NewClient(srvURL, "tok"), allowlist.New([]string{"mathias"}), "mathias", tmpl)
 }
 func callTool(t *testing.T, srvURL, tmpl, argsJSON string) createOut {
 	t.Helper()
 	res, err := newTool(srvURL, tmpl).Call(context.Background(), json.RawMessage(argsJSON))
 	require.NoError(t, err)
 	var out createOut
 	require.NoError(t, json.Unmarshal(res, &out))
 	return out
 }
-	var out struct {
+type createOut struct {
 	FullName         string   `json:"full_name"`
 		HTMLURL          string   `json:"html_url"`
 		CloneURL         string   `json:"clone_url"`
 	DefaultBranch    string   `json:"default_branch"`
 	FilesSubstituted []string `json:"files_substituted"`
 	PartialFailure   string   `json:"partial_failure,omitempty"`
 }
 // Happy path: whole-tree substitution, content + path rename, correct module host.
 func TestCreateProject_TreeWalk_SubstitutesAndRenames(t *testing.T) {
 	files := map[string]string{
 		"go.mod":                       "module __MODULE_PATH__\n\ngo 1.26\n",
 		"README.md":                    "# __PROJECT_NAME__\n",
 		"cmd/__PROJECT_NAME__/main.go": "package main\nimport \"__MODULE_PATH__/pkg/litellm\"\nconst n = \"__PROJECT_NAME__\"\n",
 		"pkg/litellm/x.go":             "package litellm\n", // no placeholder → untouched
 	}
-	require.NoError(t, json.Unmarshal(result, &out))
+	f := newFakeTemplateServer(files, "main")
 	srv := httptest.NewServer(f.handler(t, "template-go-agent", "new-svc"))
 	defer srv.Close()
 	out := callTool(t, srv.URL, "template-go-agent", `{"owner":"mathias","name":"new-svc"}`)
 	assert.Equal(t, "mathias/new-svc", out.FullName)
 	assert.Equal(t, "http://gitea.example.com/mathias/new-svc", out.HTMLURL)
 	assert.Equal(t, "main", out.DefaultBranch)
-	assert.ElementsMatch(t, substitutionFileList, out.FilesSubstituted)
+	assert.Empty(t, out.PartialFailure)
 	// content-substituted files present; untouched file absent
 	assert.Contains(t, out.FilesSubstituted, "go.mod")
 	assert.Contains(t, out.FilesSubstituted, "README.md")
 	assert.NotContains(t, out.FilesSubstituted, "pkg/litellm/x.go")
 	// path rename recorded as "old -> new"
 	assert.Contains(t, out.FilesSubstituted, "cmd/__PROJECT_NAME__/main.go -> cmd/new-svc/main.go")
 	// module host substituted correctly (git.d-ma.be, not gitea.d-ma.be)
 	assert.Equal(t, "module git.d-ma.be/mathias/new-svc\n\ngo 1.26\n", f.putBodies["go.mod"])
 	// rename: new path written, old path deleted
 	assert.Contains(t, f.puts, "cmd/new-svc/main.go")
 	assert.Contains(t, f.deletes, "cmd/__PROJECT_NAME__/main.go")
 	assert.Equal(t, "package main\nimport \"git.d-ma.be/mathias/new-svc/pkg/litellm\"\nconst n = \"new-svc\"\n",
 		f.putBodies["cmd/new-svc/main.go"])
 	// the untouched file was never written
 	assert.NotContains(t, f.puts, "pkg/litellm/x.go")
 }
 // The /generate response omits default_branch (the live gitea behavior the old
 // mock hid) → tool must re-fetch the repo and still substitute.
 func TestCreateProject_EmptyGenerateBranch_FallsBack(t *testing.T) {
 	files := map[string]string{"go.mod": "module __MODULE_PATH__\n"}
 	f := newFakeTemplateServer(files, "") // generate returns default_branch:""
 	srv := httptest.NewServer(f.handler(t, "template-go-agent", "new-svc"))
 	defer srv.Close()
 	out := callTool(t, srv.URL, "template-go-agent", `{"owner":"mathias","name":"new-svc"}`)
 	assert.Equal(t, "main", out.DefaultBranch, "must resolve branch via GetRepo fallback")
 	assert.GreaterOrEqual(t, f.repoGetsPost, 1, "must re-fetch repo to resolve empty default_branch")
 	assert.Contains(t, out.FilesSubstituted, "go.mod")
 	assert.Equal(t, "module git.d-ma.be/mathias/new-svc\n", f.putBodies["go.mod"])
 	assert.Empty(t, out.PartialFailure)
 }
-// TestCreateProjectNameRegexFailure: invalid name returns ErrValidation without hitting network.
+// Fail loud: a template whose files carry no placeholders yields nothing
-func TestCreateProjectNameRegexFailure(t *testing.T) {
+// substituted — surface it rather than returning silent success.
-	tool := tools.NewCreateProjectFromTemplate(
+func TestCreateProject_NothingSubstituted_IsLoud(t *testing.T) {
-		gitea.NewClient("http://unused", ""),
+	files := map[string]string{"README.md": "# static, no placeholders\n"}
-		allowlist.New([]string{"mathias"}),
+	f := newFakeTemplateServer(files, "main")
-		"mathias", "template-go-web",
+	srv := httptest.NewServer(f.handler(t, "template-go-agent", "new-svc"))
-	)
+	defer srv.Close()
-	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"INVALID_NAME"}`))
+
 	out := callTool(t, srv.URL, "template-go-agent", `{"owner":"mathias","name":"new-svc"}`)
 	assert.Empty(t, out.FilesSubstituted)
 	assert.NotEmpty(t, out.PartialFailure, "nothing substituted must not be silent success")
 }
 // Write failure mid-pass → partial_failure populated, no Go error.
 func TestCreateProject_WriteFailure_PartialFailure(t *testing.T) {
 	files := map[string]string{"go.mod": "module __MODULE_PATH__\n"}
 	f := newFakeTemplateServer(files, "main")
 	base := f.handler(t, "template-go-agent", "new-svc")
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.Method == http.MethodPut && strings.Contains(r.URL.Path, "/contents/go.mod") {
 			w.WriteHeader(http.StatusInternalServerError)
 			_, _ = w.Write([]byte(`{"message":"boom"}`))
 			return
 		}
 		base(w, r)
 	}))
 	defer srv.Close()
 	out := callTool(t, srv.URL, "template-go-agent", `{"owner":"mathias","name":"new-svc"}`)
 	assert.NotEmpty(t, out.PartialFailure)
 	assert.Contains(t, out.PartialFailure, "go.mod")
 }
 // dispatch_allow injects a .dispatch-allow file (dispatch#3) only when true.
 func TestCreateProject_DispatchAllow(t *testing.T) {
 	tests := []struct {
 		name     string
 		argsJSON string
 		wantFile bool
 	}{
 		{"true injects .dispatch-allow", `{"owner":"mathias","name":"new-svc","dispatch_allow":true}`, true},
 		{"false does not inject", `{"owner":"mathias","name":"new-svc","dispatch_allow":false}`, false},
 		{"omitted does not inject", `{"owner":"mathias","name":"new-svc"}`, false},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
 			files := map[string]string{"go.mod": "module __MODULE_PATH__\n"}
 			f := newFakeTemplateServer(files, "main")
 			srv := httptest.NewServer(f.handler(t, "template-go-agent", "new-svc"))
 			defer srv.Close()
 			out := callTool(t, srv.URL, "template-go-agent", tc.argsJSON)
 			require.Empty(t, out.PartialFailure)
 			if tc.wantFile {
 				assert.Contains(t, out.FilesSubstituted, ".dispatch-allow")
 				assert.Contains(t, f.puts, ".dispatch-allow")
 				assert.Contains(t, f.putBodies[".dispatch-allow"], "dispatch#3")
 			} else {
 				assert.NotContains(t, out.FilesSubstituted, ".dispatch-allow")
 				assert.NotContains(t, f.puts, ".dispatch-allow")
 			}
 		})
 	}
 }
 // ── guardrails unchanged by the rewrite ──────────────────────────────────────
 func TestCreateProject_NameRegexFailure(t *testing.T) {
 	_, err := tools.NewCreateProjectFromTemplate(
 		gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}), "mathias", "template-go-agent",
 	).Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"INVALID_NAME"}`))
 	require.Error(t, err)
 	assert.ErrorIs(t, err, gitea.ErrValidation)
 }
-// TestCreateProjectAllowlistRejects: owner not in allowlist returns error.
+func TestCreateProject_AllowlistRejects(t *testing.T) {
-func TestCreateProjectAllowlistRejects(t *testing.T) {
+	_, err := tools.NewCreateProjectFromTemplate(
-	tool := tools.NewCreateProjectFromTemplate(
+		gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}), "mathias", "template-go-agent",
-		gitea.NewClient("http://unused", ""),
+	).Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"new-svc"}`))
 		allowlist.New([]string{"mathias"}),
 		"mathias", "template-go-web",
 	)
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"new-svc"}`))
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "allowlist")
 }
-// TestCreateProjectTemplateNotTemplate: template repo exists but is not marked as template.
+func TestCreateProject_NotTemplate(t *testing.T) {
 func TestCreateProjectTemplateNotTemplate(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
-		// Template lookup returns a non-template repo.
+		if r.URL.Path == "/api/v1/repos/mathias/template-go-agent" {
-		if r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/template-go-web" {
+			_, _ = w.Write([]byte(templateRepoJSON("template-go-agent", false)))
 			_, _ = w.Write([]byte(newTemplateRepoJSON("template-go-web", false)))
 			return
 		}
 		t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
 		w.WriteHeader(http.StatusNotFound)
 	}))
 	defer srv.Close()
-
+	_, err := newTool(srv.URL, "template-go-agent").Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"new-svc"}`))
 	tool := newCreateProjectTool(srv.URL)
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"new-svc"}`))
 	require.Error(t, err)
 	assert.ErrorIs(t, err, gitea.ErrValidation)
 }
-// TestCreateProjectDestinationExists: destination repo already exists.
+func TestCreateProject_DestinationExists(t *testing.T) {
 func TestCreateProjectDestinationExists(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
-		switch {
+		switch r.URL.Path {
-		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/template-go-web":
+		case "/api/v1/repos/mathias/template-go-agent":
-			_, _ = w.Write([]byte(newTemplateRepoJSON("template-go-web", true)))
+			_, _ = w.Write([]byte(templateRepoJSON("template-go-agent", true)))
-		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/new-svc":
+		case "/api/v1/repos/mathias/new-svc":
-			// Destination exists — return 200.
+			_, _ = w.Write([]byte(templateRepoJSON("new-svc", false)))
 			_, _ = w.Write([]byte(newTemplateRepoJSON("new-svc", false)))
 		default:
 			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
 			w.WriteHeader(http.StatusNotFound)
 		}
 	}))
 	defer srv.Close()
-
+	_, err := newTool(srv.URL, "template-go-agent").Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"new-svc"}`))
 	tool := newCreateProjectTool(srv.URL)
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"new-svc"}`))
 	require.Error(t, err)
 	assert.ErrorIs(t, err, gitea.ErrConflict)
 }
 // TestCreateProjectMidPassSubstitutionFailure: the 4th file (.gitea/workflows/cd.yml) PUT fails;
 // the first 3 are substituted, partial_failure is populated, no Go error is returned.
 func TestCreateProjectMidPassSubstitutionFailure(t *testing.T) {
 	// Files that should succeed (index 0-2 in substitutionFileList).
 	successFiles := map[string]bool{
 		"go.mod":       true,
 		"Taskfile.yml": true,
 		"Dockerfile":   true,
 	}
 	// The 4th file (index 3) is .gitea/workflows/cd.yml — its PUT returns 500.
 	failFile := ".gitea/workflows/cd.yml"
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		switch {
 		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/template-go-web":
 			_, _ = w.Write([]byte(newTemplateRepoJSON("template-go-web", true)))
 		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/new-svc":
 			w.WriteHeader(http.StatusNotFound)
 			_, _ = w.Write([]byte(`{"message":"not found"}`))
 		case r.Method == http.MethodPost && r.URL.Path == "/api/v1/repos/mathias/template-go-web/generate":
 			w.WriteHeader(http.StatusCreated)
 			_, _ = w.Write([]byte(newGeneratedRepoJSON("new-svc")))
 		case r.Method == http.MethodGet && strings.HasPrefix(r.URL.Path, "/api/v1/repos/mathias/new-svc/contents/"):
 			filePath := strings.TrimPrefix(r.URL.Path, "/api/v1/repos/mathias/new-svc/contents/")
 			_, _ = w.Write([]byte(fileContentsJSON(filePath)))
 		case r.Method == http.MethodPut && strings.HasPrefix(r.URL.Path, "/api/v1/repos/mathias/new-svc/contents/"):
 			filePath := strings.TrimPrefix(r.URL.Path, "/api/v1/repos/mathias/new-svc/contents/")
 			if filePath == failFile {
 				// Simulate upstream 500.
 				w.WriteHeader(http.StatusInternalServerError)
 				_, _ = w.Write([]byte(`{"message":"internal server error"}`))
 				return
 			}
 			if !successFiles[filePath] {
 				t.Errorf("unexpected PUT for file: %s", filePath)
 				w.WriteHeader(http.StatusNotFound)
 				return
 			}
 			w.WriteHeader(http.StatusOK)
 			_, _ = w.Write([]byte(fileWriteResultJSON(filePath)))
 		default:
 			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
 			w.WriteHeader(http.StatusNotFound)
 		}
 	}))
 	defer srv.Close()
 	tool := newCreateProjectTool(srv.URL)
 	result, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"new-svc"}`))
 	// Best-effort: no Go error returned, partial state in result.
 	require.NoError(t, err)
 	var out struct {
 		FullName         string   `json:"full_name"`
 		FilesSubstituted []string `json:"files_substituted"`
 		PartialFailure   string   `json:"partial_failure,omitempty"`
 	}
 	require.NoError(t, json.Unmarshal(result, &out))
 	// First 3 files should be in FilesSubstituted.
 	assert.Len(t, out.FilesSubstituted, 3)
 	assert.Contains(t, out.FilesSubstituted, "go.mod")
 	assert.Contains(t, out.FilesSubstituted, "Taskfile.yml")
 	assert.Contains(t, out.FilesSubstituted, "Dockerfile")
 	assert.NotContains(t, out.FilesSubstituted, failFile)
 	// partial_failure should be non-empty.
 	assert.NotEmpty(t, out.PartialFailure, "partial_failure should be populated on mid-pass failure")
 }
@@ -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 IssueClose struct {
 	c *gitea.Client
 	a *allowlist.Allowlist
 }
 func NewIssueClose(c *gitea.Client, a *allowlist.Allowlist) *IssueClose {
 	return &IssueClose{c: c, a: a}
 }
 func (t *IssueClose) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "issue_close",
 		Description: "Close an open issue. Reversible via issue_reopen.",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"number":{"type":"integer","minimum":1}
 			},
 			"required":["owner","name","number"]
 		}`),
 	}
 }
 type issueCloseArgs struct {
 	Owner  string `json:"owner"`
 	Name   string `json:"name"`
 	Number int    `json:"number"`
 }
 func (t *IssueClose) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
 	var args issueCloseArgs
 	if err := parseArgs(raw, &args); err != nil {
 		return nil, err
 	}
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	iss, err := t.c.SetIssueState(ctx, args.Owner, args.Name, args.Number, "closed")
 	if err != nil {
 		return nil, err
 	}
 	return textOK(iss)
 }
@@ -0,0 +1,52 @@
 package tools_test
 import (
 	"context"
 	"encoding/json"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 func TestIssueCloseTool(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/issues/26", r.URL.Path)
 		b, _ := io.ReadAll(r.Body)
 		assert.JSONEq(t, `{"state":"closed"}`, string(b))
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"number":26,"title":"feat: ntfy via NPM","state":"closed","html_url":"http://gitea.example.com/mathias/infra/issues/26"}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueClose(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":26}`))
 	require.NoError(t, err)
 	assert.Contains(t, string(out), `"number":26`)
 	assert.Contains(t, string(out), `"state":"closed"`)
 }
 func TestIssueCloseTool_NotFound(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 		_, _ = w.Write([]byte(`{"message":"issue not found"}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueClose(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":999}`))
 	require.Error(t, err)
 }
 func TestIssueCloseAllowlistRejects(t *testing.T) {
 	tool := tools.NewIssueClose(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","number":1}`))
 	require.Error(t, err)
 }
@@ -0,0 +1,80 @@
 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 IssueEdit struct {
 	c *gitea.Client
 	a *allowlist.Allowlist
 }
 func NewIssueEdit(c *gitea.Client, a *allowlist.Allowlist) *IssueEdit {
 	return &IssueEdit{c: c, a: a}
 }
 func (t *IssueEdit) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name: "issue_edit",
 		Description: "Edit an existing issue's title and/or body. Only fields explicitly set are patched; " +
 			"omitted fields are left untouched. Body is replaced verbatim (no identity footer) so edits are idempotent. " +
 			"WARNING: body is a full replacement — to amend rather than clobber, read-modify-write " +
 			"(fetch with issue_get, edit the text, send it back).",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"number":{"type":"integer","minimum":1},
 				"title":{"type":"string","description":"New title. Omit to leave unchanged."},
 				"body":{"type":"string","description":"New body, full replacement. Omit to leave unchanged."}
 			},
 			"required":["owner","name","number"]
 		}`),
 	}
 }
 type issueEditArgs struct {
 	Owner  string  `json:"owner"`
 	Name   string  `json:"name"`
 	Number int     `json:"number"`
 	Title  *string `json:"title,omitempty"`
 	Body   *string `json:"body,omitempty"`
 }
 func (t *IssueEdit) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
 	var args issueEditArgs
 	if err := parseArgs(raw, &args); err != nil {
 		return nil, err
 	}
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	if args.Number < 1 {
 		return nil, fmt.Errorf("number is required: %w", gitea.ErrValidation)
 	}
 	if args.Title == nil && args.Body == nil {
 		return nil, fmt.Errorf("at least one of title or body must be set: %w", gitea.ErrValidation)
 	}
 	iss, err := t.c.EditIssue(ctx, args.Owner, args.Name, args.Number, gitea.EditIssueArgs{
 		Title: args.Title,
 		Body:  args.Body,
 	})
 	if err != nil {
 		return nil, err
 	}
 	return textOK(map[string]any{
 		"number":   iss.Number,
 		"title":    iss.Title,
 		"html_url": iss.HTMLURL,
 		"state":    iss.State,
 	})
 }
@@ -0,0 +1,91 @@
 package tools_test
 import (
 	"context"
 	"encoding/json"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 func TestIssueEditTool(t *testing.T) {
 	var captured []byte
 	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/issues/26", r.URL.Path)
 		var err error
 		captured, err = io.ReadAll(r.Body)
 		require.NoError(t, err)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"number":26,"title":"new","state":"open","html_url":"http://gitea.example.com/mathias/infra/issues/26"}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueEdit(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":26,"title":"new","body":"updated body"}`))
 	require.NoError(t, err)
 	var payload map[string]any
 	require.NoError(t, json.Unmarshal(captured, &payload))
 	assert.Equal(t, "new", payload["title"])
 	assert.Equal(t, "updated body", payload["body"])
 	assert.Contains(t, string(out), `"number":26`)
 }
 // Body must be sent verbatim — no identity footer appended (keeps edits idempotent).
 func TestIssueEditTool_BodyVerbatim(t *testing.T) {
 	var captured []byte
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		var err error
 		captured, err = io.ReadAll(r.Body)
 		require.NoError(t, err)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"number":26,"state":"open"}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueEdit(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":26,"body":"exact text"}`))
 	require.NoError(t, err)
 	var payload map[string]any
 	require.NoError(t, json.Unmarshal(captured, &payload))
 	assert.Equal(t, "exact text", payload["body"], "body must be unchanged — no footer")
 	_, hasTitle := payload["title"]
 	assert.False(t, hasTitle, "title must be omitted when not provided")
 }
 func TestIssueEditTool_RequiresAField(t *testing.T) {
 	tool := tools.NewIssueEdit(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":26}`))
 	require.Error(t, err)
 	assert.ErrorIs(t, err, gitea.ErrValidation)
 }
 func TestIssueEditTool_NotFound(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 		_, _ = w.Write([]byte(`{"message":"issue not found"}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueEdit(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	title := "x"
 	body, _ := json.Marshal(map[string]any{"owner": "mathias", "name": "infra", "number": 999, "title": title})
 	_, err := tool.Call(context.Background(), body)
 	require.Error(t, err)
 }
 func TestIssueEditAllowlistRejects(t *testing.T) {
 	tool := tools.NewIssueEdit(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","number":1,"title":"y"}`))
 	require.Error(t, err)
 }
@@ -0,0 +1,54 @@
 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 IssueGet struct {
 	c *gitea.Client
 	a *allowlist.Allowlist
 }
 func NewIssueGet(c *gitea.Client, a *allowlist.Allowlist) *IssueGet { return &IssueGet{c: c, a: a} }
 func (t *IssueGet) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "issue_get",
 		Description: "Get a single issue by number, including body, state, labels, assignees, and comment count.",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"number":{"type":"integer","minimum":1}
 			},
 			"required":["owner","name","number"]
 		}`),
 	}
 }
 type issueGetArgs struct {
 	Owner  string `json:"owner"`
 	Name   string `json:"name"`
 	Number int    `json:"number"`
 }
 func (t *IssueGet) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
 	var args issueGetArgs
 	if err := parseArgs(raw, &args); err != nil {
 		return nil, err
 	}
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	iss, err := t.c.GetIssue(ctx, args.Owner, args.Name, args.Number)
 	if err != nil {
 		return nil, err
 	}
 	return textOK(iss)
 }
@@ -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 TestIssueGetTool(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/issues/42", r.URL.Path)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"number":42,"title":"fix auth","body":"details","state":"open","html_url":"http://gitea.example.com/mathias/infra/issues/42","created_at":"2026-05-01T00:00:00Z","updated_at":"2026-05-02T00:00:00Z","comments":3}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueGet(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":42}`))
 	require.NoError(t, err)
 	assert.Contains(t, string(out), `"number":42`)
 	assert.Contains(t, string(out), `"title":"fix auth"`)
 	assert.Contains(t, string(out), `"comments":3`)
 }
 func TestIssueGetTool_NotFound(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 		_, _ = w.Write([]byte(`{"message":"issue not found"}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueGet(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":999}`))
 	require.Error(t, err)
 }
 func TestIssueGetAllowlistRejects(t *testing.T) {
 	tool := tools.NewIssueGet(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","number":1}`))
 	require.Error(t, err)
 }
@@ -0,0 +1,83 @@
 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 IssueList struct {
 	c *gitea.Client
 	a *allowlist.Allowlist
 }
 func NewIssueList(c *gitea.Client, a *allowlist.Allowlist) *IssueList {
 	return &IssueList{c: c, a: a}
 }
 func (t *IssueList) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "issue_list",
 		Description: "List issues in a repo with optional filters. PRs are excluded (use pr_list for those).",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"state":{"type":"string","enum":["open","closed","all"]},
 				"labels":{"type":"string"},
 				"since":{"type":"string"},
 				"page":{"type":"integer","minimum":1},
 				"limit":{"type":"integer","minimum":1,"maximum":50}
 			},
 			"required":["owner","name"]
 		}`),
 	}
 }
 type issueListArgs struct {
 	Owner  string `json:"owner"`
 	Name   string `json:"name"`
 	State  string `json:"state"`
 	Labels string `json:"labels"`
 	Since  string `json:"since"`
 	Page   int    `json:"page"`
 	Limit  int    `json:"limit"`
 }
 func (t *IssueList) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
 	var args issueListArgs
 	if err := parseArgs(raw, &args); err != nil {
 		return nil, err
 	}
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	if args.State == "" {
 		args.State = "open"
 	}
 	args.Limit = capLimit(args.Limit, 30)
 	if args.Page < 1 {
 		args.Page = 1
 	}
 	issues, err := t.c.ListIssues(ctx, args.Owner, args.Name, gitea.ListIssuesArgs{
 		State:  args.State,
 		Labels: args.Labels,
 		Since:  args.Since,
 		Page:   args.Page,
 		Limit:  args.Limit,
 	})
 	if err != nil {
 		return nil, err
 	}
 	out := map[string]any{
 		"issues": issues,
 	}
 	if len(issues) == args.Limit {
 		out["next_page"] = args.Page + 1
 	}
 	return textOK(out)
 }
@@ -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 IssueListComments struct {
 	c *gitea.Client
 	a *allowlist.Allowlist
 }
 func NewIssueListComments(c *gitea.Client, a *allowlist.Allowlist) *IssueListComments {
 	return &IssueListComments{c: c, a: a}
 }
 func (t *IssueListComments) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "issue_list_comments",
 		Description: "List all comments on an issue or pull request. Returns id, body, author, html_url, and timestamps for each comment.",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"number":{"type":"integer","minimum":1}
 			},
 			"required":["owner","name","number"]
 		}`),
 	}
 }
 type issueListCommentsArgs struct {
 	Owner  string `json:"owner"`
 	Name   string `json:"name"`
 	Number int    `json:"number"`
 }
 func (t *IssueListComments) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
 	var args issueListCommentsArgs
 	if err := parseArgs(raw, &args); err != nil {
 		return nil, err
 	}
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	comments, err := t.c.ListIssueComments(ctx, args.Owner, args.Name, args.Number)
 	if err != nil {
 		return nil, err
 	}
 	return textOK(comments)
 }
@@ -0,0 +1,67 @@
 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 TestIssueListCommentsTool(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/issues/42/comments", r.URL.Path)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`[
 			{"id":1,"body":"first","html_url":"http://gitea.example.com/mathias/infra/issues/42#comment-1","user":{"login":"alice"},"created_at":"2026-05-01T00:00:00Z","updated_at":"2026-05-01T00:00:00Z"},
 			{"id":2,"body":"second","html_url":"http://gitea.example.com/mathias/infra/issues/42#comment-2","user":{"login":"bob"},"created_at":"2026-05-02T00:00:00Z","updated_at":"2026-05-02T00:00:00Z"}
 		]`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueListComments(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":42}`))
 	require.NoError(t, err)
 	assert.Contains(t, string(out), `"id":1`)
 	assert.Contains(t, string(out), `"body":"first"`)
 	assert.Contains(t, string(out), `"login":"alice"`)
 	assert.Contains(t, string(out), `"login":"bob"`)
 }
 func TestIssueListCommentsTool_Empty(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(`[]`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueListComments(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":42}`))
 	require.NoError(t, err)
 	assert.Contains(t, string(out), `[]`)
 }
 func TestIssueListCommentsTool_NotFound(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 		_, _ = w.Write([]byte(`{"message":"issue not found"}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueListComments(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":999}`))
 	require.Error(t, err)
 }
 func TestIssueListCommentsAllowlistRejects(t *testing.T) {
 	tool := tools.NewIssueListComments(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","number":1}`))
 	require.Error(t, err)
 }
@@ -0,0 +1,88 @@
 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 TestIssueListTool(t *testing.T) {
 	tests := []struct {
 		name      string
 		input     string
 		wantQuery map[string]string
 		respBody  string
 		assert    func(t *testing.T, out string)
 	}{
 		{
 			name:      "happy path defaults",
 			input:     `{"owner":"mathias","name":"infra"}`,
 			wantQuery: map[string]string{"type": "issues", "state": "open", "page": "1", "limit": "30"},
 			respBody:  `[{"number":42,"title":"fix auth","state":"open","html_url":"http://gitea.example/m/infra/issues/42"},{"number":41,"title":"add tests","state":"open"}]`,
 			assert: func(t *testing.T, out string) {
 				assert.Contains(t, out, `"number":42`)
 				assert.Contains(t, out, `"number":41`)
 			},
 		},
 		{
 			name:      "state filter",
 			input:     `{"owner":"mathias","name":"infra","state":"closed"}`,
 			wantQuery: map[string]string{"type": "issues", "state": "closed"},
 			respBody:  `[]`,
 			assert: func(t *testing.T, out string) {
 				assert.Contains(t, out, `"issues":[]`)
 			},
 		},
 		{
 			name:      "label + since filter",
 			input:     `{"owner":"mathias","name":"infra","labels":"bug,critical","since":"2026-05-01T00:00:00Z"}`,
 			wantQuery: map[string]string{"labels": "bug,critical", "since": "2026-05-01T00:00:00Z"},
 			respBody:  `[]`,
 			assert:    func(t *testing.T, out string) {},
 		},
 		{
 			name:      "empty result",
 			input:     `{"owner":"mathias","name":"infra"}`,
 			wantQuery: map[string]string{"state": "open"},
 			respBody:  `[]`,
 			assert: func(t *testing.T, out string) {
 				assert.Contains(t, out, `"issues":[]`)
 				assert.NotContains(t, out, `next_page`)
 			},
 		},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(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/issues", r.URL.Path)
 				q := r.URL.Query()
 				for k, v := range tc.wantQuery {
 					assert.Equal(t, v, q.Get(k), "query param %q", k)
 				}
 				w.Header().Set("Content-Type", "application/json")
 				_, _ = w.Write([]byte(tc.respBody))
 			}))
 			defer srv.Close()
 			tool := tools.NewIssueList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 			out, err := tool.Call(context.Background(), json.RawMessage(tc.input))
 			require.NoError(t, err)
 			tc.assert(t, string(out))
 		})
 	}
 }
 func TestIssueListAllowlistRejects(t *testing.T) {
 	tool := tools.NewIssueList(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x"}`))
 	require.Error(t, err)
 }
@@ -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 IssueReopen struct {
 	c *gitea.Client
 	a *allowlist.Allowlist
 }
 func NewIssueReopen(c *gitea.Client, a *allowlist.Allowlist) *IssueReopen {
 	return &IssueReopen{c: c, a: a}
 }
 func (t *IssueReopen) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "issue_reopen",
 		Description: "Reopen a closed issue. Reversible via issue_close.",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"number":{"type":"integer","minimum":1}
 			},
 			"required":["owner","name","number"]
 		}`),
 	}
 }
 type issueReopenArgs struct {
 	Owner  string `json:"owner"`
 	Name   string `json:"name"`
 	Number int    `json:"number"`
 }
 func (t *IssueReopen) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
 	var args issueReopenArgs
 	if err := parseArgs(raw, &args); err != nil {
 		return nil, err
 	}
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	iss, err := t.c.SetIssueState(ctx, args.Owner, args.Name, args.Number, "open")
 	if err != nil {
 		return nil, err
 	}
 	return textOK(iss)
 }
@@ -0,0 +1,40 @@
 package tools_test
 import (
 	"context"
 	"encoding/json"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 func TestIssueReopenTool(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/issues/26", r.URL.Path)
 		b, _ := io.ReadAll(r.Body)
 		assert.JSONEq(t, `{"state":"open"}`, string(b))
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"number":26,"title":"feat: ntfy via NPM","state":"open","html_url":"http://gitea.example.com/mathias/infra/issues/26"}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewIssueReopen(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":26}`))
 	require.NoError(t, err)
 	assert.Contains(t, string(out), `"number":26`)
 	assert.Contains(t, string(out), `"state":"open"`)
 }
 func TestIssueReopenAllowlistRejects(t *testing.T) {
 	tool := tools.NewIssueReopen(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","number":1}`))
 	require.Error(t, err)
 }
@@ -143,7 +143,13 @@ func splitUnifiedDiff(d []byte) map[string][]byte {
 	flush := func() {
 		if currentFile != "" {
-			m[currentFile] = current.Bytes()
+			// Copy: bytes.Buffer.Bytes() returns the internal slice,
 			// which Reset() then reuses. Without the copy, every map
 			// entry ends up aliased to the last file's data.
 			b := current.Bytes()
 			cp := make([]byte, len(b))
 			copy(cp, b)
 			m[currentFile] = cp
 			current.Reset()
 		}
 	}
@@ -97,6 +97,47 @@ func TestPRFilesDiffSmall(t *testing.T) {
 	assert.ElementsMatch(t, fileNames, paths)
 }
 // Regression for issue #25: every file's diff entry must contain its OWN diff,
 // not a shared buffer pointing at the last file. Prior bug: splitUnifiedDiff
 // flushed bytes.Buffer.Bytes() into the map without copying, so every entry
 // aliased the buffer's backing array and showed the last file's content.
 func TestPRFilesDiffPerFileIsolation(t *testing.T) {
 	fileNames := []string{"alpha.go", "beta.go", "gamma.go", "delta.go"}
 	rawDiff := buildDiff(fileNames, 5)
 	filesJSON := buildFilesJSON(fileNames, 5)
 	srv := newPRFilesDiffServer(t, filesJSON, rawDiff)
 	defer srv.Close()
 	tool := tools.NewPRFilesDiff(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"o"}))
 	result, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"o","name":"r","number":1}`))
 	require.NoError(t, err)
 	var out struct {
 		Files []struct {
 			Path string `json:"path"`
 			Diff string `json:"diff"`
 		} `json:"files"`
 	}
 	require.NoError(t, json.Unmarshal(result, &out))
 	require.Len(t, out.Files, len(fileNames))
 	for _, f := range out.Files {
 		expected := fmt.Sprintf("diff --git a/%s b/%s", f.Path, f.Path)
 		assert.Contains(t, f.Diff, expected,
 			"file %s diff must contain its own header, got: %.80q", f.Path, f.Diff)
 		// No other file's header should leak in.
 		for _, other := range fileNames {
 			if other == f.Path {
 				continue
 			}
 			otherHeader := fmt.Sprintf("diff --git a/%s b/%s", other, other)
 			assert.NotContains(t, f.Diff, otherHeader,
 				"file %s diff must NOT contain %s's header", f.Path, other)
 		}
 	}
 }
 func TestPRFilesDiffPerFileTruncated(t *testing.T) {
 	// One file with a 30KB diff (each "+abcdefghij\n" = 12 bytes; 30KB / 12 ≈ 2560 lines).
 	fileNames := []string{"bigfile.go"}
@@ -0,0 +1,59 @@
 package tools
 import (
 	"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"
 )
 // RegisterAll registers every gitea-mcp tool on reg. main.go and the
 // dispatch round-trip test share this single list so a newly added tool
 // cannot be wired in one place but missing from the other.
 //
 // giteaBaseURL is needed by workflow_run_trigger; tmplOwner/tmplRepo seed
 // create_project_from_template's default source template.
 func RegisterAll(
 	reg *registry.Registry,
 	c *gitea.Client,
 	a *allowlist.Allowlist,
 	giteaBaseURL, tmplOwner, tmplRepo string,
 ) {
 	reg.Register(NewRepoList(c, a))
 	reg.Register(NewRepoGet(c, a))
 	reg.Register(NewRepoSearch(c, a))
 	reg.Register(NewRepoStatus(c, a))
 	reg.Register(NewFileRead(c, a))
 	reg.Register(NewFileWriteBranch(c, a))
 	reg.Register(NewFileDelete(c, a))
 	reg.Register(NewDirList(c, a))
 	reg.Register(NewBranchList(c, a))
 	reg.Register(NewBranchDelete(c, a))
 	reg.Register(NewBranchProtectionGet(c, a))
 	reg.Register(NewPRCreate(c, a))
 	reg.Register(NewPRGet(c, a))
 	reg.Register(NewPRList(c, a))
 	reg.Register(NewPRMerge(c, a))
 	reg.Register(NewPRComment(c, a))
 	reg.Register(NewPRFilesDiff(c, a))
 	reg.Register(NewWorkflowRunTrigger(c, a, giteaBaseURL))
 	reg.Register(NewWorkflowRunStatus(c, a))
 	reg.Register(NewCodeSearch(c, a))
 	reg.Register(NewIssueCreate(c, a))
 	reg.Register(NewIssueEdit(c, a))
 	reg.Register(NewIssueComment(c, a))
 	reg.Register(NewCreateProjectFromTemplate(c, a, tmplOwner, tmplRepo))
 	reg.Register(NewTagCreate(c, a))
 	reg.Register(NewRepoCreate(c, a))
 	reg.Register(NewRepoUpdate(c, a))
 	reg.Register(NewRepoMirrorPush(c, a))
 	reg.Register(NewRepoTree(c, a))
 	reg.Register(NewRepoTopicsUpdate(c, a))
 	reg.Register(NewIssueGet(c, a))
 	reg.Register(NewIssueList(c, a))
 	reg.Register(NewIssueListComments(c, a))
 	reg.Register(NewIssueClose(c, a))
 	reg.Register(NewIssueReopen(c, a))
 	reg.Register(NewWorkflowRunList(c, a))
 	reg.Register(NewReleaseCreate(c, a))
 	reg.Register(NewRepoDelete(c, a))
 }
@@ -0,0 +1,58 @@
 package tools_test
 import (
 	"context"
 	"encoding/json"
 	"errors"
 	"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/registry"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 // buildRegistry wires the full tool set exactly as main.go does, against an
 // unroutable gitea base URL so any handler that reaches the network fails fast
 // (connection refused) rather than hanging.
 func buildRegistry() *registry.Registry {
 	reg := registry.New()
 	c := gitea.NewClient("http://127.0.0.1:1", "")
 	a := allowlist.New([]string{"mathias"})
 	tools.RegisterAll(reg, c, a, "http://127.0.0.1:1", "mathias", "template-go-web")
 	return reg
 }
 // Every registered tool must be dispatchable and advertise a parseable input
 // schema. This is the regression guard for #36's whole class: a tool that is
 // wired up but unroutable (or ships a malformed schema) fails CI here instead
 // of 404ing a live caller.
 func TestEveryRegisteredToolIsDispatchable(t *testing.T) {
 	reg := buildRegistry()
 	descs := reg.Tools()
 	require.NotEmpty(t, descs)
 	for _, d := range descs {
 		t.Run(d.Name, func(t *testing.T) {
 			require.NotEmpty(t, d.Name, "tool has empty name")
 			assert.True(t, json.Valid(d.InputSchema),
 				"tool %q ships invalid JSON input schema", d.Name)
 			// Dispatch with empty args. We do not care whether the call
 			// succeeds (most fail allowlist/validation/network) — only that
 			// the name resolves to a handler. ErrToolNotFound here means the
 			// tool advertised a name the dispatcher cannot route.
 			_, err := reg.Dispatch(context.Background(), d.Name, json.RawMessage(`{}`))
 			assert.False(t, errors.Is(err, registry.ErrToolNotFound),
 				"registered tool %q does not dispatch", d.Name)
 		})
 	}
 }
 // Lock the tool count so an accidental drop of a registration in RegisterAll
 // (the single source main.go and this test share) fails loudly.
 func TestRegisteredToolCount(t *testing.T) {
 	assert.Len(t, buildRegistry().Tools(), 38)
 }
@@ -0,0 +1,73 @@
 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 ReleaseCreate struct {
 	c *gitea.Client
 	a *allowlist.Allowlist
 }
 func NewReleaseCreate(c *gitea.Client, a *allowlist.Allowlist) *ReleaseCreate {
 	return &ReleaseCreate{c: c, a: a}
 }
 func (t *ReleaseCreate) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "release_create",
 		Description: "Create a release (and tag if it doesn't exist) for a repository.",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"tag_name":{"type":"string","description":"Tag to create or use, e.g. 'v1.0.0'."},
 				"release_name":{"type":"string","description":"Display name for the release."},
 				"body":{"type":"string","description":"Release notes / changelog."},
 				"draft":{"type":"boolean"},
 				"prerelease":{"type":"boolean"},
 				"target":{"type":"string","description":"Branch or commit SHA to tag. Defaults to repo default branch."}
 			},
 			"required":["owner","name","tag_name"]
 		}`),
 	}
 }
 type releaseCreateArgs struct {
 	Owner       string `json:"owner"`
 	Name        string `json:"name"`
 	TagName     string `json:"tag_name"`
 	ReleaseName string `json:"release_name"`
 	Body        string `json:"body"`
 	Draft       bool   `json:"draft"`
 	Prerelease  bool   `json:"prerelease"`
 	Target      string `json:"target"`
 }
 func (t *ReleaseCreate) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
 	var args releaseCreateArgs
 	if err := parseArgs(raw, &args); err != nil {
 		return nil, err
 	}
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	rel, err := t.c.CreateRelease(ctx, args.Owner, args.Name, gitea.CreateReleaseArgs{
 		TagName:    args.TagName,
 		Name:       args.ReleaseName,
 		Body:       args.Body,
 		Draft:      args.Draft,
 		Prerelease: args.Prerelease,
 		Target:     args.Target,
 	})
 	if err != nil {
 		return nil, err
 	}
 	return textOK(rel)
 }
@@ -0,0 +1,38 @@
 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 TestReleaseCreateTool(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/releases", r.URL.Path)
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusCreated)
 		_, _ = w.Write([]byte(`{"id":1,"tag_name":"v1.0.0","name":"v1.0.0","body":"changelog","draft":false,"prerelease":false,"html_url":"https://gitea.example.com/mathias/infra/releases/tag/v1.0.0","created_at":"2026-05-15T00:00:00Z"}`))
 	}))
 	defer srv.Close()
 	tool := tools.NewReleaseCreate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","tag_name":"v1.0.0","release_name":"v1.0.0","body":"changelog"}`))
 	require.NoError(t, err)
 	assert.Contains(t, string(out), `"tag_name":"v1.0.0"`)
 	assert.Contains(t, string(out), `"html_url"`)
 }
 func TestReleaseCreateAllowlistRejects(t *testing.T) {
 	tool := tools.NewReleaseCreate(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","tag_name":"v1.0.0"}`))
 	require.Error(t, err)
 }
@@ -0,0 +1,59 @@
 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 RepoDelete struct {
 	c *gitea.Client
 	a *allowlist.Allowlist
 }
 func NewRepoDelete(c *gitea.Client, a *allowlist.Allowlist) *RepoDelete {
 	return &RepoDelete{c: c, a: a}
 }
 func (t *RepoDelete) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "repo_delete",
 		Description: "Permanently delete a repository. Requires confirm=<repo name> to prevent accidents.",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"confirm":{"type":"string","description":"Must equal the repo name exactly to proceed."}
 			},
 			"required":["owner","name","confirm"]
 		}`),
 	}
 }
 type repoDeleteArgs struct {
 	Owner   string `json:"owner"`
 	Name    string `json:"name"`
 	Confirm string `json:"confirm"`
 }
 func (t *RepoDelete) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
 	var args repoDeleteArgs
 	if err := parseArgs(raw, &args); err != nil {
 		return nil, err
 	}
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	if args.Confirm != args.Name {
 		return nil, fmt.Errorf("repo_delete requires confirm=%q to match the repo name — got %q", args.Name, args.Confirm)
 	}
 	if err := t.c.DeleteRepo(ctx, args.Owner, args.Name); err != nil {
 		return nil, err
 	}
 	return textOK(map[string]string{"status": "deleted", "repo": args.Owner + "/" + args.Name})
 }
@@ -0,0 +1,52 @@
 package tools_test
 import (
 	"context"
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 func TestRepoDeleteTool_WithCorrectConfirm(t *testing.T) {
 	deleted := false
 	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", r.URL.Path)
 		deleted = true
 		w.WriteHeader(http.StatusNoContent)
 	}))
 	defer srv.Close()
 	tool := tools.NewRepoDelete(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","confirm":"infra"}`))
 	require.NoError(t, err)
 	assert.True(t, deleted, "DELETE request must have been sent")
 	assert.Contains(t, string(out), "deleted")
 }
 func TestRepoDeleteTool_WrongConfirmBlocked(t *testing.T) {
 	tool := tools.NewRepoDelete(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","confirm":"wrong"}`))
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "confirm")
 }
 func TestRepoDeleteTool_MissingConfirmBlocked(t *testing.T) {
 	tool := tools.NewRepoDelete(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra"}`))
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "confirm")
 }
 func TestRepoDeleteAllowlistRejects(t *testing.T) {
 	tool := tools.NewRepoDelete(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","confirm":"x"}`))
 	require.Error(t, err)
 }
@@ -22,16 +22,20 @@ func NewRepoUpdate(c *gitea.Client, a *allowlist.Allowlist) *RepoUpdate {
 func (t *RepoUpdate) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name: "repo_update",
-		Description: "Update repository metadata (description, visibility, default branch, website).",
+		Description: "Update repository metadata (description, visibility, default branch, website, archived, template). " +
 			"Only fields explicitly set in the call are patched. " +
 			"WARNING: private=false exposes the repo publicly — verify intent before calling.",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"description":{"type":"string"},
-				"private":{"type":"boolean"},
+				"private":{"type":"boolean","description":"Toggle visibility. false makes the repo public."},
-				"website":{"type":"string"},
+				"website":{"type":"string","description":"Homepage URL"},
-				"default_branch":{"type":"string"},
+				"default_branch":{"type":"string","description":"Rename the default branch"},
 				"archived":{"type":"boolean","description":"Mark repo as archived (read-only)."},
 				"template":{"type":"boolean","description":"Toggle template-repo flag"},
 				"confirm":{"type":"string","description":"Required when setting private=false. Must equal the repo name."}
 			},
 			"required":["owner","name"]
@@ -42,10 +46,12 @@ func (t *RepoUpdate) Descriptor() registry.ToolDescriptor {
 type repoUpdateArgs struct {
 	Owner         string  `json:"owner"`
 	Name          string  `json:"name"`
-	Description   *string `json:"description"`
+	Description   *string `json:"description,omitempty"`
-	Private       *bool   `json:"private"`
+	Private       *bool   `json:"private,omitempty"`
-	Website       *string `json:"website"`
+	Website       *string `json:"website,omitempty"`
-	DefaultBranch *string `json:"default_branch"`
+	DefaultBranch *string `json:"default_branch,omitempty"`
 	Archived      *bool   `json:"archived,omitempty"`
 	Template      *bool   `json:"template,omitempty"`
 	Confirm       string  `json:"confirm"`
 }
@@ -57,17 +63,26 @@ func (t *RepoUpdate) Call(ctx context.Context, raw json.RawMessage) (json.RawMes
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	// Making a repo public is a significant action — require explicit confirmation.
 	if args.Private != nil && !*args.Private {
 		if args.Confirm != args.Name {
 			return nil, fmt.Errorf("setting private=false makes the repo public: set confirm=%q to proceed", args.Name)
 		}
 	}
 	if args.Description == nil && args.Private == nil && args.Website == nil &&
 		args.DefaultBranch == nil && args.Archived == nil && args.Template == nil {
 		return nil, fmt.Errorf("at least one updatable field must be set: %w", gitea.ErrValidation)
 	}
 	r, err := t.c.UpdateRepo(ctx, args.Owner, args.Name, gitea.UpdateRepoArgs{
 		Description:   args.Description,
 		Private:       args.Private,
 		Website:       args.Website,
 		DefaultBranch: args.DefaultBranch,
 		Archived:      args.Archived,
 		Template:      args.Template,
 	})
 	if err != nil {
 		return nil, err
@@ -3,6 +3,7 @@ package tools_test
 import (
 	"context"
 	"encoding/json"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -14,43 +15,139 @@ import (
 	"github.com/stretchr/testify/require"
 )
-func TestRepoUpdateTool(t *testing.T) {
+func newRepoUpdateTool(srvURL string) *tools.RepoUpdate {
 	return tools.NewRepoUpdate(gitea.NewClient(srvURL, "tok"), allowlist.New([]string{"mathias"}))
 }
 // TestRepoUpdateArchive: happy path — set archived=true.
 func TestRepoUpdateArchive(t *testing.T) {
 	var patchedBody []byte
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		assert.Equal(t, http.MethodPatch, r.Method)
+		require.Equal(t, http.MethodPatch, r.Method)
-		assert.Equal(t, "/api/v1/repos/mathias/infra", r.URL.Path)
+		require.Equal(t, "/api/v1/repos/mathias/old-svc", r.URL.Path)
 		patchedBody, _ = io.ReadAll(r.Body)
 		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write([]byte(`{"name":"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"}`))
+		_, _ = w.Write([]byte(`{"name":"old-svc","full_name":"mathias/old-svc","default_branch":"main","template":false,"private":false}`))
 	}))
 	defer srv.Close()
-	tool := tools.NewRepoUpdate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	tool := newRepoUpdateTool(srv.URL)
-	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","description":"updated"}`))
+	result, err := tool.Call(context.Background(), json.RawMessage(
 		`{"owner":"mathias","name":"old-svc","archived":true}`,
 	))
 	require.NoError(t, err)
-	assert.Contains(t, string(out), `"description":"updated"`)
+
 	// Wire payload only contains the field that was actually set.
 	var sent map[string]any
 	require.NoError(t, json.Unmarshal(patchedBody, &sent))
 	assert.Equal(t, true, sent["archived"])
 	assert.NotContains(t, sent, "description")
 	assert.NotContains(t, sent, "private")
 	assert.NotContains(t, sent, "website")
 	assert.NotContains(t, sent, "template")
 	var repo gitea.Repo
 	require.NoError(t, json.Unmarshal(result, &repo))
 	assert.Equal(t, "mathias/old-svc", repo.FullName)
 }
-func TestRepoUpdateTool_MakePublicRequiresConfirm(t *testing.T) {
+// TestRepoUpdateMultipleFields: set description + template flag in one call.
-	tool := tools.NewRepoUpdate(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
+func TestRepoUpdateMultipleFields(t *testing.T) {
-	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","private":false}`))
+	var patchedBody []byte
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		patchedBody, _ = io.ReadAll(r.Body)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"name":"template-go-agent","full_name":"mathias/template-go-agent","description":"Go agent template","template":true}`))
 	}))
 	defer srv.Close()
 	tool := newRepoUpdateTool(srv.URL)
 	_, err := tool.Call(context.Background(), json.RawMessage(
 		`{"owner":"mathias","name":"template-go-agent","description":"Go agent template","template":true}`,
 	))
 	require.NoError(t, err)
 	var sent map[string]any
 	require.NoError(t, json.Unmarshal(patchedBody, &sent))
 	assert.Equal(t, "Go agent template", sent["description"])
 	assert.Equal(t, true, sent["template"])
 	assert.NotContains(t, sent, "archived")
 	assert.NotContains(t, sent, "private")
 }
 // TestRepoUpdateNoFieldsRejected: zero updatable fields → validation error before network.
 func TestRepoUpdateNoFieldsRejected(t *testing.T) {
 	tool := tools.NewRepoUpdate(
 		gitea.NewClient("http://unused", ""),
 		allowlist.New([]string{"mathias"}),
 	)
 	_, err := tool.Call(context.Background(), json.RawMessage(
 		`{"owner":"mathias","name":"some-repo"}`,
 	))
 	require.Error(t, err)
 	assert.ErrorIs(t, err, gitea.ErrValidation)
 }
 // TestRepoUpdateMakePublic: private=false requires confirm=<repo name> as a safety
 // gate (kept from main #21 during the v02-patch merge). With confirm matching, the
 // patch goes through.
 func TestRepoUpdateMakePublic(t *testing.T) {
 	var patchedBody []byte
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		patchedBody, _ = io.ReadAll(r.Body)
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"name":"open-repo","full_name":"mathias/open-repo","private":false}`))
 	}))
 	defer srv.Close()
 	tool := newRepoUpdateTool(srv.URL)
 	_, err := tool.Call(context.Background(), json.RawMessage(
 		`{"owner":"mathias","name":"open-repo","private":false,"confirm":"open-repo"}`,
 	))
 	require.NoError(t, err)
 	var sent map[string]any
 	require.NoError(t, json.Unmarshal(patchedBody, &sent))
 	assert.Equal(t, false, sent["private"])
 }
 // TestRepoUpdateMakePublicWithoutConfirm: confirm gate blocks private=false without confirmation.
 func TestRepoUpdateMakePublicWithoutConfirm(t *testing.T) {
 	tool := tools.NewRepoUpdate(
 		gitea.NewClient("http://unused", ""),
 		allowlist.New([]string{"mathias"}),
 	)
 	_, err := tool.Call(context.Background(), json.RawMessage(
 		`{"owner":"mathias","name":"open-repo","private":false}`,
 	))
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "confirm")
 }
-func TestRepoUpdateTool_MakePublicWithConfirm(t *testing.T) {
+// TestRepoUpdateAllowlistRejects: owner outside allowlist denied without network call.
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+func TestRepoUpdateAllowlistRejects(t *testing.T) {
-		w.Header().Set("Content-Type", "application/json")
+	tool := tools.NewRepoUpdate(
-		_, _ = w.Write([]byte(`{"name":"infra","full_name":"mathias/infra","default_branch":"main","private":false,"clone_url":"","html_url":""}`))
+		gitea.NewClient("http://unused", ""),
 		allowlist.New([]string{"mathias"}),
 	)
 	_, err := tool.Call(context.Background(), json.RawMessage(
 		`{"owner":"evil","name":"some-repo","archived":true}`,
 	))
 	require.Error(t, err)
 }
 // TestRepoUpdateUpstreamError: server 500 propagates as ErrUpstream.
 func TestRepoUpdateUpstreamError(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		w.WriteHeader(http.StatusInternalServerError)
 		_, _ = w.Write([]byte(`{"message":"internal"}`))
 	}))
 	defer srv.Close()
-	tool := tools.NewRepoUpdate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
+	tool := newRepoUpdateTool(srv.URL)
-	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","private":false,"confirm":"infra"}`))
+	_, err := tool.Call(context.Background(), json.RawMessage(
-	require.NoError(t, err)
+		`{"owner":"mathias","name":"some-repo","archived":true}`,
-	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)
 	assert.ErrorIs(t, err, gitea.ErrUpstream)
 }
@@ -2,6 +2,7 @@ package tools
 import (
 	"encoding/json"
 	"strings"
 	"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
 )
@@ -17,7 +18,54 @@ func parseArgs(raw json.RawMessage, dst any) error {
 	if len(raw) == 0 {
 		return json.Unmarshal([]byte("{}"), dst)
 	}
-	return json.Unmarshal(raw, dst)
+	return json.Unmarshal(normalizeAliases(raw), dst)
 }
 // normalizeAliases maps the near-universal gitea/GitHub argument names onto the
 // idiosyncratic ones these tools declare: `repo` -> `name`, `index` -> `number`.
 // Every MCP caller (the claude.ai connector, LLMs primed on gitea's own API)
 // reaches for `repo`/`index`; without this the unmatched fields zero-valued the
 // upstream path segment and produced gitea's misleading /api/swagger 404 (#36).
 // The alias key is left intact so a tool whose real field IS `index`
 // (e.g. pr_merge) is unaffected.
 func normalizeAliases(raw json.RawMessage) json.RawMessage {
 	var m map[string]json.RawMessage
 	if err := json.Unmarshal(raw, &m); err != nil {
 		return raw // not a JSON object — leave untouched
 	}
 	changed := aliasInto(m, "name", "repo")
 	changed = aliasInto(m, "number", "index") || changed
 	if !changed {
 		return raw
 	}
 	if patched, err := json.Marshal(m); err == nil {
 		return patched
 	}
 	return raw
 }
 // aliasInto copies m[alias] into m[canonical] when canonical is absent or an
 // empty/zero JSON value and alias carries a usable one. An explicit canonical
 // value always wins. Returns true if it wrote canonical.
 func aliasInto(m map[string]json.RawMessage, canonical, alias string) bool {
 	av, ok := m[alias]
 	if !ok || isEmptyJSON(av) {
 		return false
 	}
 	if cv, ok := m[canonical]; ok && !isEmptyJSON(cv) {
 		return false
 	}
 	m[canonical] = av
 	return true
 }
 func isEmptyJSON(v json.RawMessage) bool {
 	switch strings.TrimSpace(string(v)) {
 	case "", `""`, "null", "0":
 		return true
 	default:
 		return false
 	}
 }
 // capLimit returns a sane page size: 0 or negative → def, > 50 → 50.
@@ -0,0 +1,87 @@
 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 WorkflowRunList struct {
 	c *gitea.Client
 	a *allowlist.Allowlist
 }
 func NewWorkflowRunList(c *gitea.Client, a *allowlist.Allowlist) *WorkflowRunList {
 	return &WorkflowRunList{c: c, a: a}
 }
 func (t *WorkflowRunList) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "workflow_run_list",
 		Description: "List recent Gitea Actions workflow runs with optional filters (branch, head_sha, status, event, workflow).",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"owner":{"type":"string"},
 				"name":{"type":"string"},
 				"branch":{"type":"string"},
 				"head_sha":{"type":"string"},
 				"status":{"type":"string","enum":["queued","in_progress","completed","all"]},
 				"event":{"type":"string","enum":["push","pull_request","schedule","workflow_dispatch","all"]},
 				"workflow":{"type":"string"},
 				"page":{"type":"integer","minimum":1},
 				"limit":{"type":"integer","minimum":1,"maximum":50}
 			},
 			"required":["owner","name"]
 		}`),
 	}
 }
 type workflowRunListArgs struct {
 	Owner    string `json:"owner"`
 	Name     string `json:"name"`
 	Branch   string `json:"branch"`
 	HeadSHA  string `json:"head_sha"`
 	Status   string `json:"status"`
 	Event    string `json:"event"`
 	Workflow string `json:"workflow"`
 	Page     int    `json:"page"`
 	Limit    int    `json:"limit"`
 }
 func (t *WorkflowRunList) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
 	var args workflowRunListArgs
 	if err := parseArgs(raw, &args); err != nil {
 		return nil, err
 	}
 	if err := t.a.Check(args.Owner); err != nil {
 		return nil, err
 	}
 	args.Limit = capLimit(args.Limit, 10)
 	if args.Page < 1 {
 		args.Page = 1
 	}
 	resp, err := t.c.ListWorkflowRuns(ctx, args.Owner, args.Name, gitea.ListWorkflowRunsArgs{
 		Branch:   args.Branch,
 		HeadSHA:  args.HeadSHA,
 		Status:   args.Status,
 		Event:    args.Event,
 		Workflow: args.Workflow,
 		Page:     args.Page,
 		Limit:    args.Limit,
 	})
 	if err != nil {
 		return nil, err
 	}
 	out := map[string]any{
 		"runs":  resp.WorkflowRuns,
 		"total": resp.TotalCount,
 	}
 	if len(resp.WorkflowRuns) == args.Limit {
 		out["next_page"] = args.Page + 1
 	}
 	return textOK(out)
 }
@@ -0,0 +1,98 @@
 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 TestWorkflowRunListTool(t *testing.T) {
 	tests := []struct {
 		name      string
 		input     string
 		wantQuery map[string]string
 		notQuery  []string
 		respBody  string
 		assert    func(t *testing.T, out string)
 	}{
 		{
 			name:      "happy path defaults",
 			input:     `{"owner":"mathias","name":"gitea-mcp"}`,
 			wantQuery: map[string]string{"page": "1", "limit": "10"},
 			respBody:  `{"total_count":2,"workflow_runs":[{"id":823,"status":"completed","conclusion":"success","head_sha":"dc907fb"},{"id":822,"status":"completed","conclusion":"success","head_sha":"c4bd339"}]}`,
 			assert: func(t *testing.T, out string) {
 				assert.Contains(t, out, `"id":823`)
 				assert.Contains(t, out, `"total":2`)
 			},
 		},
 		{
 			name:      "head_sha short filter",
 			input:     `{"owner":"mathias","name":"gitea-mcp","head_sha":"dc907fb"}`,
 			wantQuery: map[string]string{"head_sha": "dc907fb"},
 			respBody:  `{"total_count":1,"workflow_runs":[{"id":823,"status":"completed","conclusion":"success","head_sha":"dc907fb"}]}`,
 			assert: func(t *testing.T, out string) {
 				assert.Contains(t, out, `"id":823`)
 			},
 		},
 		{
 			name:      "status filter",
 			input:     `{"owner":"mathias","name":"gitea-mcp","status":"in_progress"}`,
 			wantQuery: map[string]string{"status": "in_progress"},
 			respBody:  `{"total_count":0,"workflow_runs":[]}`,
 			assert: func(t *testing.T, out string) {
 				assert.Contains(t, out, `"runs":[]`)
 			},
 		},
 		{
 			name:      "status=all is no-op",
 			input:     `{"owner":"mathias","name":"gitea-mcp","status":"all"}`,
 			notQuery:  []string{"status"},
 			respBody:  `{"total_count":0,"workflow_runs":[]}`,
 			assert:    func(t *testing.T, out string) {},
 		},
 		{
 			name:      "branch filter",
 			input:     `{"owner":"mathias","name":"gitea-mcp","branch":"main"}`,
 			wantQuery: map[string]string{"branch": "main"},
 			respBody:  `{"total_count":0,"workflow_runs":[]}`,
 			assert:    func(t *testing.T, out string) {},
 		},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(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/gitea-mcp/actions/runs", r.URL.Path)
 				q := r.URL.Query()
 				for k, v := range tc.wantQuery {
 					assert.Equal(t, v, q.Get(k), "query param %q", k)
 				}
 				for _, k := range tc.notQuery {
 					assert.Equal(t, "", q.Get(k), "query param %q should be absent", k)
 				}
 				w.Header().Set("Content-Type", "application/json")
 				_, _ = w.Write([]byte(tc.respBody))
 			}))
 			defer srv.Close()
 			tool := tools.NewWorkflowRunList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
 			out, err := tool.Call(context.Background(), json.RawMessage(tc.input))
 			require.NoError(t, err)
 			tc.assert(t, string(out))
 		})
 	}
 }
 func TestWorkflowRunListAllowlistRejects(t *testing.T) {
 	tool := tools.NewWorkflowRunList(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
 	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x"}`))
 	require.Error(t, err)
 }