b03511f99b
Update AGENT.md to reflect current project structure and philosophy Add comprehensive architecture documentation covering: - Directory layout - Stable contracts - Request flow - Module dependencies - Page vs list detection - Deployment models - Demo fallback Remove outdated plugin system documentation Add new content system documentation Add configuration documentation Add context API documentation Add hooks and plugins documentation Add templates documentation Add rendering documentation Add development environment documentation
2.5 KiB
2.5 KiB
FolderWeb
Minimal file-based CMS. Folders = URLs. PHP 8.4+, no JS, no frameworks, no build tools.
Philosophy
Decade-scale maintainability. Only essential tech. Readable, simple, future-proof. No volatile dependencies.
Two Modes of Work
- Building on top (
custom/): Create sites using the framework. Never modifyapp/. In this mode,app/is typically symlinked or submoduled from the framework repo into a separate site repo. - Framework development (
app/): Evolve the core. Preserve all stable contracts (see architecture doc).custom/may be symlinked in from a site repo for testing.
Core Constraints
- Stack: HTML5, PHP 8.4+, CSS. Nothing else.
- Frontend: Classless semantic HTML, modern CSS (nesting,
oklch(), grid,clamp(), logical props) - Security: Path traversal protection, document root restriction, strict MIME types, escape all UGC
Code Style
- PHP: Arrow functions, null coalescing, match expressions. Type hints where practical. Single-purpose functions. Comments only for major sections.
- CSS: Variables, native nesting, grid.
clamp()over@media. Relative units. - Templates:
<?= htmlspecialchars($var) ?>for UGC.<?= $content ?>for pre-rendered HTML.
Knowledge Base
Read these docs on-demand when working on related areas. Do not load all at once.
| Skill | File | Read When |
|---|---|---|
| Architecture | docs/04-development/01-architecture.md |
Understanding project structure, request flow, module dependencies, stable contracts |
| Content System | docs/04-development/02-content-system.md |
Working with routing, URL resolution, metadata, content discovery, navigation |
| Configuration | docs/04-development/03-configuration.md |
Config loading, the custom/ override system, static asset routing |
| Context API | docs/04-development/04-context-api.md |
The Context class, Templates class, built-in context keys |
| Hooks & Plugins | docs/04-development/05-hooks-plugins.md |
Hook system, plugin manager, writing plugins, the language plugin |
| Templates | docs/04-development/06-templates.md |
Template hierarchy, resolution, variables, list item schema, partials |
| Rendering | docs/04-development/07-rendering.md |
Rendering pipeline, Markdown caching, static file serving, Parsedown |
| Dev Environment | docs/04-development/08-dev-environment.md |
Container setup, Apache config, performance profiling, test data generation |
Human-facing docs (tutorials, reference) are in docs/01-getting-started/, docs/02-tutorial/, docs/03-reference/.