folderweb/AGENT.md

# 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

1. **Building on top** (`custom/`): Create sites using the framework. Never modify `app/`. In this mode, `app/` is typically symlinked or submoduled from the framework repo into a separate site repo.
2. **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/`.
Update AGENT.md and add architecture documentation 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 2026-02-05 23:30:44 +01:00			`# FolderWeb`

			`Minimal file-based CMS. Folders = URLs. PHP 8.4+, no JS, no frameworks, no build tools.`

Initial commit 2025-10-02 16:54:47 +02:00			`## Philosophy`

Update AGENT.md and add architecture documentation 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 2026-02-05 23:30:44 +01:00			`Decade-scale maintainability. Only essential tech. Readable, simple, future-proof. No volatile dependencies.`
Initial commit 2025-10-02 16:54:47 +02:00
Update AGENT.md and add architecture documentation 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 2026-02-05 23:30:44 +01:00			`## Two Modes of Work`
Initial commit 2025-10-02 16:54:47 +02:00
Update AGENT.md and add architecture documentation 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 2026-02-05 23:30:44 +01:00			1. Building on top (`custom/`): Create sites using the framework. Never modify `app/`. In this mode, `app/` is typically symlinked or submoduled from the framework repo into a separate site repo.
			2. 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`
Initial commit 2025-10-02 16:54:47 +02:00
Compress instructions 2026-01-14 14:40:30 +01:00			`## Code Style`
Initial commit 2025-10-02 16:54:47 +02:00
Update AGENT.md and add architecture documentation 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 2026-02-05 23:30:44 +01:00			`- 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 \|
Initial commit 2025-10-02 16:54:47 +02:00
Update AGENT.md and add architecture documentation 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 2026-02-05 23:30:44 +01:00			Human-facing docs (tutorials, reference) are in `docs/01-getting-started/`, `docs/02-tutorial/`, `docs/03-reference/`.