2026-06-18 22:41:35 +02:00
1 changed files with 31 additions and 1 deletions
@@ -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