diff --git a/dev-docs/CLAUDE_DESKTOP_SETUP.md b/dev-docs/CLAUDE_DESKTOP_SETUP.md
new file mode 100644
index 00000000..6c409cbf
--- /dev/null
+++ b/dev-docs/CLAUDE_DESKTOP_SETUP.md
@@ -0,0 +1,172 @@
+# Claude Desktop setup voor Crewli
+
+Deze pagina beschrijft hoe Claude Desktop (de architect/PM-chat)
+toegang krijgt tot deze repository. Geldt voor Bert's lokale werkomgeving.
+
+Voor Claude Code (de terminal tool) is geen aparte setup nodig — die leest
+de repo direct van de filesystem waarin hij wordt gestart.
+
+## Architectuur in één regel
+
+Claude Desktop → Gitea MCP server (Docker, lokaal op Mac) → HTTPS → `https://gitea.hausmans.cloud`
+
+Project knowledge in Claude Desktop is bewust **leeg** voor dit project.
+Alle dev-docs worden live gelezen uit de `main` branch via de Gitea MCP
+connector, zodat Claude altijd met de actuele waarheid werkt en er geen
+hand-sync nodig is bij elke commit.
+
+## Wat is er geconfigureerd
+
+### 1. Gitea Personal Access Token
+
+Gegenereerd onder `bert.hausmans` in Gitea:
+- Settings → Applications → Generate New Token
+- Naam: `claude-desktop` (of vergelijkbaar)
+- Scopes: `read:repository`, `read:user`, `read:organization`, `write:repository`
+
+De token is plaintext opgeslagen in de Claude Desktop config.
+
+### 2. Docker image
+
+```bash
+docker pull docker.gitea.com/gitea-mcp-server
+```
+
+Docker Desktop moet draaien op de Mac. Als Docker Desktop niet actief is,
+werkt de MCP-connector niet en krijgt Claude een transport error in de logs.
+
+### 3. Claude Desktop config
+
+Locatie: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "gitea": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITEA_HOST",
+        "-e",
+        "GITEA_ACCESS_TOKEN",
+        "docker.gitea.com/gitea-mcp-server",
+        "/app/gitea-mcp",
+        "-t",
+        "stdio"
+      ],
+      "env": {
+        "GITEA_HOST": "https://gitea.hausmans.cloud",
+        "GITEA_ACCESS_TOKEN": "PASTE_PAT_HERE"
+      }
+    }
+  }
+}
+```
+
+**Let op de `/app/gitea-mcp` regel** — de Docker image heeft geen
+`ENTRYPOINT`, alleen een `CMD` op `/app/gitea-mcp`. Zonder dit expliciete
+pad gooit Docker een `executable file not found in $PATH` error.
+
+Na elke config-wijziging: **⌘Q om Claude Desktop volledig te sluiten**,
+daarna opnieuw starten. Het rode kruis-knopje sluit alleen het venster
+— MCP-subprocessen blijven dan op de oude config hangen.
+
+Bestandspermissies: `chmod 600` op de config-file.
+
+### 4. Project instructions in Claude Desktop
+
+Onder dit Claude project (Claude Desktop sidebar → klik op project →
+Project instructions) staat een notitie die toekomstige sessies briefst
+dat uploads leeg zijn en dev-docs via Gitea MCP opgehaald moeten worden.
+
+## Beschikbare Gitea tools in Claude
+
+De connector exposeert onder andere:
+
+- `gitea:get_me` — bevestig PAT werkt
+- `gitea:get_file_contents` — haal een specifieke file op
+- `gitea:get_dir_contents` — lijst entries in een directory
+- `gitea:get_repository_tree` — recursieve tree
+- `gitea:search_issues` — zoek issues en PRs
+- `gitea:create_or_update_file` — schrijf een file (vereist `write:repository`)
+- `gitea:issue_write` / `gitea:pull_request_write` — create/edit issues en PRs
+- En ca. 40 andere tools voor labels, milestones, releases, actions, etc.
+
+## Wat er in project knowledge NIET meer zit
+
+Bewust verwijderd uit Claude Desktop project knowledge (23 april 2026):
+
+```
+.cursorrules
+CLAUDE.md
+VUEXY_COMPONENTS.md
+VIBE_CODING_CHECKLIST.md
+UX_SPEC_FESTIVAL_HIERARCHY.md
+S3a-public-form-api.md
+TEST_SCENARIO.md
+start-guide.md
+SETUP.md
+SECURITY_AUDIT.md
+SCHEMA.md
+MASTER_PROMPT_CURSOR.md
+MASTER_PROMPT_CC.md
+form-builder-migration-playbook.md
+form-builder-getting-started.md
+dev-guide.md
+design-document.md
+COPY_CATALOGUE.md
+BACKLOG.md
+AUTH_ARCHITECTURE.md
+ARCH-FORM-BUILDER.md
+API.md
+```
+
+Al deze documenten staan in `dev-docs/` of `/.cursorrules` en worden direct
+uit Gitea gelezen. Niet opnieuw uploaden — dat leidt alleen tot twee
+waarheidsbronnen die uit sync kunnen raken.
+
+## Troubleshooting
+
+### Tool slider toont geen Gitea tools
+
+1. Check of Docker Desktop draait (whale-icoon in menubar)
+2. Validate de JSON config:
+   ```bash
+   python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json
+   ```
+3. Check logs:
+   ```bash
+   tail -f ~/Library/Logs/Claude/mcp-server-gitea.log
+   ```
+4. Manual sanity test:
+   ```bash
+   docker run -i --rm \
+     -e GITEA_HOST=https://gitea.hausmans.cloud \
+     -e GITEA_ACCESS_TOKEN=jouw_pat \
+     docker.gitea.com/gitea-mcp-server \
+     /app/gitea-mcp -t stdio
+   ```
+   Mag niks doen (wacht op stdin). Ctrl+C om te stoppen.
+5. Vergeet niet `⌘Q` op Claude Desktop na config-aanpassing.
+
+### Authenticatie-errors (401)
+
+PAT verlopen of ingetrokken. Genereer een nieuwe, update
+`GITEA_ACCESS_TOKEN` in config, ⌘Q + restart.
+
+## Updaten van de MCP server
+
+```bash
+docker pull docker.gitea.com/gitea-mcp-server
+```
+
+Claude Desktop gebruikt de laatst-gepulde image op z'n eerstvolgende
+subprocess-spawn (bij volgende tool call).
+
+## Gerelateerd
+
+- `CLAUDE.md` (repo root) — instructies voor Claude Code, niet Claude Desktop
+- `dev-docs/dev-guide.md` — ontwikkelworkflow