From 1ae383cf5d39bb0a0706cd8ae5b924c6df12f35a Mon Sep 17 00:00:00 2001 From: Mischa Date: Thu, 18 Jun 2026 13:25:59 +0200 Subject: [PATCH] Document dev/prod mode settings and no-switching rule Adds section 1 to CLAUDE.md covering the current development mode config (twig.cache: false), the production mode values to restore at launch, and an explicit rule never to flip modes mid-development to work around bugs. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9c51bfd..3d51baf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,7 +28,37 @@ Always use `make` commands for anything on the production server (`make remote-i 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 +## 1. Environment modes + +### Rule: do not switch modes during development + +**Never toggle between development and production mode mid-session.** If a caching or config issue appears, fix it at the application level (plugin, template logic) rather than temporarily flipping a mode flag to work around it. Mode switches introduce inconsistent state and make bugs harder to reproduce. + +### Development mode (current) + +Active settings in `user/config/system.yaml`: + +| Setting | Dev value | Why | +|---|---|---| +| `twig.cache` | `false` | Theme file edits take effect immediately; no stale compile errors | + +With these settings, Grav rebuilds templates on every request. This is intentionally slower but means you never need to flush cache after editing a `.html.twig` file. + +### Production mode (not yet configured) + +Before going live, change in `user/config/system.yaml`: + +| Setting | Prod value | Why | +|---|---|---| +| `twig.cache` | `true` | Templates compiled once and reused; safe because theme files don't change at runtime | + +**Pre-launch smoke test required:** with `twig.cache: true`, submit one post via `/post` and confirm the entry appears in `/tracker` immediately. This verifies the cache-on-save plugin (BUG-001 fix) works correctly with caching enabled. + +### What the cache-on-save plugin handles + +The custom plugin at `user/plugins/cache-on-save/` clears Grav's page-tree cache on every `new-entry` form submission. This ensures new posts appear in the tracker feed immediately in both modes — it does not depend on whether Twig caching is on or off. + +## 2. Local development setup ### First-time setup after cloning