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.

## Framework Development Workflow

When modifying or adding code in `app/`: write tests and run them before marking work done. Read `docs/05-testing/01-testing.md` for the required workflow and test format.

## Standards

- **Stack:** HTML5, PHP 8.4+, CSS. Nothing else.
- **Security:** Path traversal protection, document root restriction, strict MIME types, escape all UGC
- **PHP:** Arrow functions, null coalescing, match expressions. Type hints where practical. Single-purpose functions, avoid side effects. Comments only for major sections.
- **HTML:** Classless, semantic markup.
- **CSS:** Variables, native nesting, relative units. Modern CSS (`oklch()`, `light-dark()`, `clamp()`, logical props). Global styles first, page-scoped when needed.
- **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 |
| Testing | `docs/05-testing/01-testing.md` | **Required before modifying `app/`** — workflow, test format, what's testable |

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.

Update framework testing infrastructure and standards - Add phpt test runner and suite for app functions - Introduce testing workflow to AGENT.md - Add tests for cache, content, context, helpers, hooks, plugins, rendering - Mount tests directory in dev container 2026-03-17 12:51:07 +01:00			`## Framework Development Workflow`
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
Update framework testing infrastructure and standards - Add phpt test runner and suite for app functions - Introduce testing workflow to AGENT.md - Add tests for cache, content, context, helpers, hooks, plugins, rendering - Mount tests directory in dev container 2026-03-17 12:51:07 +01:00			When modifying or adding code in `app/`: write tests and run them before marking work done. Read `docs/05-testing/01-testing.md` for the required workflow and test format.
Initial commit 2025-10-02 16:54:47 +02:00
Update framework testing infrastructure and standards - Add phpt test runner and suite for app functions - Introduce testing workflow to AGENT.md - Add tests for cache, content, context, helpers, hooks, plugins, rendering - Mount tests directory in dev container 2026-03-17 12:51:07 +01:00			`## Standards`
Initial commit 2025-10-02 16:54:47 +02:00
Update framework testing infrastructure and standards - Add phpt test runner and suite for app functions - Introduce testing workflow to AGENT.md - Add tests for cache, content, context, helpers, hooks, plugins, rendering - Mount tests directory in dev container 2026-03-17 12:51:07 +01:00			`- Stack: HTML5, PHP 8.4+, CSS. Nothing else.`
			`- Security: Path traversal protection, document root restriction, strict MIME types, escape all UGC`
			`- PHP: Arrow functions, null coalescing, match expressions. Type hints where practical. Single-purpose functions, avoid side effects. Comments only for major sections.`
			`- HTML: Classless, semantic markup.`
			- CSS: Variables, native nesting, relative units. Modern CSS (`oklch()`, `light-dark()`, `clamp()`, logical props). Global styles first, page-scoped when needed.
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			- 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 \|
Update framework testing infrastructure and standards - Add phpt test runner and suite for app functions - Introduce testing workflow to AGENT.md - Add tests for cache, content, context, helpers, hooks, plugins, rendering - Mount tests directory in dev container 2026-03-17 12:51:07 +01:00			\| Testing \| `docs/05-testing/01-testing.md` \| Required before modifying `app/` — workflow, test format, what's testable \|
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/`.