Add CRITICAL sections to AGENTS.md to prevent repeated mistakes

- SCSS is sole CSS source, never edit theme.css manually - Bootstrap 5: override all CSS variables AND properties - Path references from public/admin.php: use ../ not ../../ - Twig: no dirname filter, use default() not ?? on filter expressions - CodeMirror mode load order dependencies - Plugin filename convention: <Name>.php not plugin.php - Essential plugins protection - Live server asset serving via asset.php
2026-08-11 16:51:05 +02:00
parent 3d84e61ed1
commit 8ebf11d7e4
1 changed files with 60 additions and 2 deletions
@@ -147,7 +147,7 @@ codepress/
 ├── var/                                 # Cache (twig) — .gitignore'd
 ├── config.json                          # Site configuratie — .gitignore'd
 ├── composer.json                        # PHP dependencies
-├── version.php                          # Versie informatie (huidige: 2.5.1)
+├── version.php                          # Versie informatie (huidige: 2.5.2)
 ├── .gitignore                           # Negeert: var/, config.json, admin/config/admin.json, content/
 └── AGENTS.md                            # Dit bestand
 ```
@@ -165,7 +165,7 @@ codepress/
  - Admin theme: `admin/theme/default/` (views + assets)
  - Plugin assets: `plugins/<Name>/assets/` (served via router `/plugins/<Name>/assets/`)
 - **Content**: Stored in `content/`. Supports `.md` (Markdown), `.php` (Dynamic), `.html` (Static).
- **Templating**: Twig templates in `themes/<naam>/`. `ThemeManager` rendert via Twig en compileert `assets/scss/theme.scss` runtime naar `assets/css/theme.css`. Layout gekozen via frontmatter `layout:` key; onbekende layouts vallen terug op `config.default_template` in `theme.json`.
+- **Templating**: Twig templates in `themes/<naam>/`. `ThemeManager` rendert via Twig en compileert `assets/scss/theme.scss` runtime naar `assets/css_compiled/theme.css` via scssphp. Layout gekozen via frontmatter `layout:` key; onbekende layouts vallen terug op `config.default_template` in `theme.json`.
 - **Plugin CSS**: Plugins hebben eigen `assets/scss/` en `assets/css/`. Plugin CSS wordt automatisch geladen na theme CSS (in `base.twig`), zodat thema's plugin styling kunnen overschrijven. Plugin assets worden geserveerd via `cms/router.php` op URL `/plugins/<Name>/assets/...`.
 - **Navigation**: Auto-generated from directory structure. Folders require an index file to be clickable in breadcrumbs. Breadcrumb is dynamisch: Home > [submappen] > [pagina]. Homepage toont altijd het pad.
 - **Security**: 
@@ -225,3 +225,61 @@ Gedefinieerd in `AdminAuth::ROLE_PERMISSIONS` als een mapping van rol → toeges
 - `var/` (Twig cache) staat in `.gitignore`. Kan veilig worden gewist: `rm -rf var/cache/twig/*`
 - `content/` staat in `.gitignore`. Content wordt lokaal beheerd.
 - Pad-referenties vanuit `public/admin.php`: gebruik `__DIR__ . "/../themes/..."` (één niveau omhoog), NIET `../../` (twee niveaus).
+
+## CRITICAL: SCSS is de enige CSS bron — NIET handmatig CSS aanpassen
+- **NOOIT** `themes/<naam>/assets/css/theme.css` handmatig aanpassen. Dit bestand mag niet bestaan.
+- **ALTIJD** `themes/<naam>/assets/scss/theme.scss` aanpassen. scssphp compileert dit automatisch naar `assets/css_compiled/theme.css`.
+- **ALTIJD** `themes/<naam>/assets/css_compiled/theme.css` verwijderen na SCSS wijzigingen: `rm themes/<naam>/assets/css_compiled/theme.css themes/<naam>/assets/css_compiled/.mtime`
+- **REDEN**: `ThemeManager::getCssUrl()` heeft prioriteit: 1) `assets/css/theme.css` (handmatig), 2) `assets/css_compiled/theme.css` (gecompileerd). Als `theme.css` bestaat, wordt de SCSS negeren en worden SCSS wijzigingen NIET zichtbaar.
+- **Plugin CSS**: Plugin SCSS in `plugins/<Name>/assets/scss/` wordt nog niet automatisch gecompileerd. Plugin CSS in `plugins/<Name>/assets/css/` is handmatig te onderhouden.
+- **Bootstrap CSS**: `themes/<naam>/assets/css/bootstrap.min.css` is een externe dependency. NIET aanpassen.
+
+## CRITICAL: Bootstrap 5 overrides — alle CSS variabelen EN properties overschrijven
+- Bootstrap 5 gebruikt CSS custom properties (variables) op `:root` en op component niveau. Deze overschrijven met alleen `!important` op properties is NIET voldoende.
+- **ALTIJD** zowel de Bootstrap CSS variabelen als de properties overschrijven:
+  - `.nav-tabs`: set `--bs-nav-tabs-border-width`, `--bs-nav-tabs-border-color`, `--bs-nav-tabs-border-radius` EN `border`, `border-radius`, `border-bottom`
+  - `.dropdown-menu`: set `--bs-dropdown-min-width`, `--bs-dropdown-border-width`, `--bs-dropdown-border-radius`, `--bs-dropdown-box-shadow`, `--bs-dropdown-padding-x/y` EN `border`, `border-radius`, `padding`, `margin`, `min-width`, `box-shadow`
+  - `.nav-link`: set `border`, `border-top-left-radius`, `border-top-right-radius`, `border-bottom-left-radius`, `border-bottom-right-radius` (alle vier de hoeken!)
+- **NOOIT** aannemen dat een enkele `border: none !important` voldoende is. Bootstrap zet `border-top-left-radius` en `border-top-right-radius` apart op `.nav-tabs .nav-link`.
+
+## CRITICAL: Pad-referenties vanuit public/admin.php
+- `__DIR__` in `public/admin.php` is `public/`.
+- Gebruik `__DIR__ . "/../themes/..."` (één niveau omhoog naar project root).
+- **NOOIT** `__DIR__ . "/../../themes/..."` (twee niveaus — dit gaat naar de parent van het project).
+- Dit geldt voor alle paden naar `themes/`, `plugins/`, `guide/`, `admin/`.
+
+## CRITICAL: Twig syntaxis — geen PHP functions in Twig
+- Twig heeft geen `dirname` filter. Gebruik PHP `dirname()` in de handler en geef het resultaat als aparte variabele door aan Twig.
+- Twig `??` (null coalescing) werkt NIET op filter expressies zoals `(stats.pages|length ?? 0)`. Gebruik `|default(0)` in plaats daarvan.
+- Twig `??` werkt WEL op simpele variable access zoals `(config.value ?? 'default')`.
+
+## CRITICAL: CodeMirror mode laadvolgorde
+- CodeMirror modes hebben dependencies. De laadvolgorde in `admin.twig` moet zijn:
+  1. `codemirror.min.js` (core)
+  2. `xml.min.js` (basis voor htmlmixed)
+  3. `css.min.js` (dependency van htmlmixed)
+  4. `javascript.min.js` (dependency van htmlmixed)
+  5. `htmlmixed.min.js` (dependency van php)
+  6. `php.min.js` (gebruikt htmlmixed)
+  7. `clike.min.js`
+  8. `markdown.min.js`
+- **NOOIT** `php.min.js` laden vóór `htmlmixed.min.js` — dit veroorzaakt `c.indent is not a function` errors.
+
+## CRITICAL: Plugin bestandsnaam conventie
+- Plugin PHP bestanden heten `<PluginName>.php` (bijv. `Navigation.php`, `HTMLBlock.php`), NIET `plugin.php`.
+- `PluginManager` laadt `$pluginDir . '/' . $pluginName . '.php'` (regel 46 in PluginManager.php).
+- `handlePluginsEdit` in `admin.php` moet `$pluginDir . '/' . $plugin . '.php'` gebruiken, NIET `$pluginDir . '/plugin.php'`.
+- `handlePluginsNew` moet het bestand aanmaken als `<PluginName>.php`, NIET `plugin.php`.
+
+## CRITICAL: Essentiële plugins beschermen
+- Essentiële plugins gedefinieerd in `getProtectedPlugins()` in `public/admin.php` (huidige: `Navigation`).
+- Deze plugins kunnen NIET worden: gedeactiveerd (`handlePluginsToggle`), verwijderd (`handlePluginsDelete`), bewerkt (`handlePluginsEdit`).
+- De `plugins.twig` template toont een "Essentieel" badge i.p.v. de actieknoppen.
+- **ALTIJD** de `isProtectedPlugin()` check toevoegen aan nieuwe plugin handlers.
+
+## CRITICAL: Live server (Apache) — asset serving
+- Op de live server (Apache) staan themes, plugins en admin assets buiten de webroot (`public/`).
+- `public/.htaccess` stuurt `/themes/`, `/admin/assets/`, `/plugins/` URLs door naar `public/asset.php`.
+- `public/asset.php` serveert de bestanden vanuit de juiste mappen met het juiste MIME-type.
+- **NOOIT** aannemen dat de PHP dev server router (`cms/router.php`) op de live server draait.
+- Na wijzigingen aan assets: commit EN deploy naar live server.