CodePress/AGENTS.md

Agent Instructions for CodePress CMS

AI Model

• Huidig model: claude-opus-4-6 (OpenCode / opencode/claude-opus-4-6)
• Sessie gestart: 16 feb 2026

Build & Run

• Run Server: php -S localhost:8080 cms/router.php (router nodig voor clean URLs)
• Lint PHP: find . -name "*.php" -not -path "./vendor/*" -exec php -l {} \;
• Dependencies: Composer vereist voor CommonMark, Twig en scssphp. Geen NPM.
• Admin Console: Toegankelijk op /admin.php (standaard login: admin / admin)

Project Structuur

codepress/
├── cms/                            # Core CMS engine
│   ├── core/
│   │   ├── class/
│   │   │   ├── CodePressCMS.php    # Hoofd CMS class
│   │   │   ├── ThemeManager.php    # Thema-resolver + Twig render + SCSS compile
│   │   │   └── Logger.php          # Logging systeem
│   │   ├── plugin/
│   │   │   ├── PluginManager.php   # Plugin loader
│   │   │   └── CMSAPI.php          # API voor plugins
│   │   ├── config.php              # Config loader (leest config.json)
│   │   └── index.php               # Bootstrap (autoloader, requires)
│   └── router.php                  # PHP dev server router (serveert ook /themes/)
├── language/                       # Taalbestanden (nl/, en/, de/ — elk met site.php + admin.php)
├── themes/                         # Dynamische thema's (volledig zelfstandig)
│   ├── default/                    # Standaard thema
│   │   ├── theme.json              # { title, default_layout, layout→.twig mapping, kleuren }
│   │   ├── base.twig               # Hoofd layout (head, header, nav, footer)
│   │   ├── full_content.twig       # Layout: volledige breedte
│   │   ├── left_sidebar.twig       # Layout: sidebar links
│   │   ├── right_sidebar.twig      # Layout: sidebar rechts
│   │   ├── custom1.twig            # Layout: custom
│   │   ├── guide.twig              # Layout: handleiding
│   │   ├── partials/               # header.twig, navigation.twig, footer.twig
│   │   ├── assets/scss/theme.scss  # SCSS bron (runtime gecompileerd)
│   │   └── assets/js/              # app.js, bootstrap.bundle.min.js
│   ├── demo/                       # Demo thema (zelfde structuur, andere look)
├── admin/                          # Admin paneel
│   ├── config/
│   │   ├── app.php                # Admin app configuratie
│   │   ├── admin.json             # Gebruikers & security (file-based, gitignored)
│   │   └── admin.json.example     # Voorbeeld met placeholder-wachtwoord
│   ├── src/
│   │   └── AdminAuth.php          # Authenticatie (sessies, bcrypt, CSRF, lockout)
│   ├── theme/default/views/        # Twig templates
│   │   ├── login.twig             # Login pagina
│   │   ├── layouts/admin.twig     # Admin layout met sidebar
│   │   └── pages/                 # dashboard, content, content-edit, config, plugins, theme, users, statistics, logs, security, update, guide, media, etc.
│   └── storage/logs/              # Admin logs (gedeeld met front-end)
├── cli/                            # CLI scripts & tests
│   └── test/
│       ├── accessibility.sh        # WCAG 2.1 AA test suite
│       ├── enhanced-suite.sh       # Enhanced test suite
│       ├── functional/             # Functionele testen
│       └── pentest/                # Penetratietesten
├── plugins/                        # CMS plugins
│   ├── HTMLBlock/
│   └── Navigation/
├── public/                         # Web root
│   ├── assets/css/js/
│   ├── index.php                  # Website entry point
│   └── admin.php                  # Admin entry point + router
├── content/                        # Content bestanden
├── guide/                          # Handleidingen (nl/en)
├── docs/                           # Documentatie
├── config.json                     # Site configuratie
└── AGENTS.md                       # Dit bestand

Code Style & Conventions

• PHP Standards: Follow PSR-12. Use 4 spaces for indentation.
• Naming: Classes PascalCase (e.g., CodePressCMS), methods camelCase (e.g., renderMenu), variables camelCase, config keys snake_case.
• Architecture:
  • Core CMS logic in cms/core/class/CodePressCMS.php
  • Bootstrap/requires in cms/core/index.php
  • Configuration loaded from config.json via cms/core/config.php
  • Public website entry point: public/index.php
  • Admin entry point + routing: public/admin.php
  • Admin authenticatie: admin/src/AdminAuth.php
• 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 public/themes/<naam>/theme.css. Layout gekozen via frontmatter layout: key; onbekende layouts vallen terug op default_layout in theme.json.
• Navigation: Auto-generated from directory structure. Folders require an index file to be clickable in breadcrumbs.
• Security:
  • Always use htmlspecialchars() for outputting user/content data
  • Use realpath() + prefix-check for path traversal prevention
  • Admin forms require CSRF tokens via AdminAuth::verifyCsrf()
  • Passwords stored as bcrypt hashes in admin.json
• Git: main is the clean CMS core. development is de actieve development branch. e.noorlander bevat persoonlijke content. Niet mixen.

Admin Console

• File-based: Geen database. Gebruikers opgeslagen in admin/config/admin.json
• Routing: Via ?route= parameter in public/admin.php
• Routes: login, logout, dashboard, content, content-edit, content-new, content-delete, content-dir-create, content-dir-rename, content-dir-delete, content-move, config, plugins, plugins-new, plugins-edit, plugins-config, plugins-toggle, plugins-delete, theme, theme-new, users, security, statistics, logs, guide, media, update
• Auth: Session-based. AdminAuth class handelt login, logout, CSRF, brute-force lockout af
• Templates: Twig templates in admin/theme/default/views/. Layout in layouts/admin.twig

Important: Title vs File/Directory Name Logic

• CRITICAL: When user asks for "title" corrections, they usually mean FILE/DIRECTORY NAME WITHOUT LANGUAGE PREFIX AND EXTENSIONS, not the HTML title from content!
• Examples:
  • nl.test.md → display as "Test" (not content title)
  • nl.test/ directory → display as "Test" (not H1 content)
  • en.php-testen → display as "Php Testen" (not "ICT")
• Method: Use formatDisplayName() to process file/directory names correctly
• Priority: Directory names take precedence over file names when both exist
• Language prefixes: Dynamisch verwijderd op basis van beschikbare talen via getAvailableLanguages()

Bekende aandachtspunten

• LSP errors over "Undefined function" in PHP files zijn vals-positief (standaard PHP functies worden niet herkend door de LSP). Negeer deze.
• Zie TODO.md voor alle openstaande verbeteringen en nieuwe features.
• vendor/ map bevat Composer dependencies (CommonMark, Twig, scssphp, GeoIP2). Niet handmatig wijzigen.
• admin/config/admin.json bevat wachtwoord-hashes. Niet committen met echte productie-wachtwoorden.