From bc6781133e7229eadea15fb47e0de0a986f79b2e Mon Sep 17 00:00:00 2001
From: Mischa <mischa@gorinskat.nl>
Date: Thu, 18 Jun 2026 00:16:47 +0200
Subject: [PATCH] Document local dev setup gotchas; fix install-plugins gpm
 path

---
 CLAUDE.md | 32 ++++++++++++++++++++++++++++++++
 Makefile  |  2 +-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 32450d9..9c51bfd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -27,3 +27,35 @@ Always use `make` commands for anything on the production server (`make remote-i
 ### User repo gitignore
 
 Only these folders are tracked in the `user/` Git repo: `pages/`, `config/`, `accounts/`, `themes/`. The `plugins/` and `data/` folders are excluded.
+
+## 1. Local development setup
+
+### First-time setup after cloning
+
+`user/plugins/` and `user/data/` are excluded from git but Grav requires them to exist. Create them once after cloning:
+
+```bash
+mkdir -p user/plugins user/data
+```
+
+Then run `make setup` (starts Docker + installs plugins).
+
+### After make install-plugins: fix cache permissions
+
+If the site returns a 500 error after plugin installation, the cache/logs/tmp directories may have wrong ownership (gpm runs as root inside the container). Fix with:
+
+```bash
+docker exec intotheeast_grav chown -R abc:users /app/www/public/cache /app/www/public/logs /app/www/public/tmp
+```
+
+### Language URL prefix
+
+If Grav redirects to `/en/...` URLs, ensure `user/config/system.yaml` contains:
+
+```yaml
+languages:
+  supported: [en]
+  include_default_lang: false
+```
+
+Without `include_default_lang: false`, Grav adds a language prefix to all URLs even for single-language sites.
diff --git a/Makefile b/Makefile
index 008f719..77dbc7c 100644
--- a/Makefile
+++ b/Makefile
@@ -17,7 +17,7 @@ stop:
 setup: start install-plugins
 
 install-plugins:
-	docker exec intotheeast_grav php /app/www/public/bin/gpm install $(shell cat plugins.txt | tr '\n' ' ') -y
+	docker exec -w /app/www/public intotheeast_grav php bin/gpm install $(shell cat plugins.txt | tr '\n' ' ') -y
 
 # ── Content sync (user repo ↔ Gitea) ──────────────────────────────────────────