added AGENTS.md

Author: dg

.gitattributes

@@ -1,6 +1,7 @@
 .gitattributes  export-ignore
 .github/        export-ignore
 .gitignore      export-ignore
+AGENTS.md       export-ignore
 ncs.*           export-ignore
 phpstan*.neon   export-ignore
 src/**/*.latte  export-ignore

AGENTS.md

@@ -0,0 +1,142 @@
+# To My Agents!
+
+It is my fervent wish that this file guide every AI coding agent working with code in this repository.
+
+
+## Project Overview
+
+*Latte by Example* is a course. Each numbered directory teaches one concept of
+the [Latte](https://latte.nette.org) template engine, in order, and every
+chapter runs on its own.
+
+- **PHP**: 8.4+, **Latte**: 3.1.6+ (chapters use 3.1 features such as smart HTML attributes)
+- Code, comments and readmes are in **English**.
+
+
+## Essential Commands
+
+```shell
+php 01-hello-world/example.php   # run a chapter, HTML goes to stdout
+composer lint-templates          # latte-lint, taught about this project's own tags and filters
+composer phpstan                 # static analysis of the PHP files
+composer check-outputs           # readme Output sections match reality
+composer check                   # all three
+```
+
+There are no unit tests. A chapter is verified by running it; `check-outputs`
+then enforces that the *Output* section of its readme still matches what the
+example prints, so the two cannot drift apart unnoticed.
+
+
+## Anatomy of a Chapter
+
+```
+NN-slug/
+├── readme.md        the text of the chapter
+├── example.php      the runnable entry point
+└── templates/
+    ├── index.latte  the main template
+    └── @*.latte     templates not meant to be rendered on their own
+```
+
+`temp/` appears at runtime and holds compiled templates. It is gitignored and
+must never be edited or committed.
+
+
+## `example.php`
+
+Max ~40 lines. Guard the autoloader, create the engine, set the cache
+directory, build `$params`, render:
+
+```php
+<?php declare(strict_types=1);
+
+if (@!include __DIR__ . '/../vendor/autoload.php') {
+	echo 'Install dependencies using `composer install`';
+	exit(1);
+}
+
+$latte = new Latte\Engine;
+$latte->setCacheDirectory(__DIR__ . '/temp');
+
+$params = [ /* ... */ ];
+
+$latte->render(__DIR__ . '/templates/index.latte', $params);
+```
+
+- Use `setCacheDirectory()`, not the deprecated `setTempDirectory()`.
+- Do not call `setAutoRefresh()`; it is on by default.
+- From chapter 03 on, `$latte->setFeature(Latte\Feature::Dedent)` is standard,
+  so nesting does not push indentation into the output.
+
+
+## Templates
+
+Max ~50 lines per file; prefer two small templates over one long one. Minimal
+valid HTML5, no external assets. Nothing non-deterministic (`date('Y')`,
+`|random`): the readme quotes real output, so it must not drift.
+
+
+## Chapter `readme.md`
+
+60-140 lines, these sections in this order:
+
+```markdown
+# NN · Chapter Title
+
+One-sentence summary.
+
+**You will learn:** 3-5 bullets
+
+## Run it            fenced shell block
+## <Walkthrough>     H2 sections named after the concepts, short excerpts
+## Output            real output, copy-pasted, trimmed with `...`
+## Try it yourself   2-3 one-sentence exercises, easiest first
+## Further reading   links to latte.nette.org
+```
+
+Second person, concrete, no filler. Every claim must come from an actual run.
+
+
+## Rules
+
+- **One chapter, one concept.** If it does not fit on a screen, split it.
+- **No forward references in code.** A chapter may only use what earlier
+  chapters introduced. Referring to a later topic in prose is fine, but do it
+  by name, not by number - numbers shift while the course is being written.
+- **Comment only what the current chapter teaches.** Do not re-explain what an
+  earlier chapter already covered.
+- **Chapters are self-contained.** Data is copied into each `example.php`;
+  there is no shared include.
+- **Verify, do not remember.** Output sections, generated code shown in the
+  text and every exercise hint must be checked by running them.
+- **A chapter that registers a filter, function or tag must also register it in
+  `bin/lint-templates.php`.** The linter only knows what it has been told, and would
+  otherwise report the chapter's own vocabulary as an error.
+
+
+## The Dataset
+
+Chapters that need data use this catalogue of a fictional bookshop called
+`Bits & Books`. Omit fields you do not need, but never change the values -
+identical data across chapters keeps the outputs comparable.
+
+| title | author | price | available | tags | published | note |
+|---|---|---|---|---|---|---|
+| It Works on My Machine | Marta Novak | 24.90 | true | php, web | 2023-04-12 | Staff pick |
+| Escaping & Other Life Skills | Petr Svoboda | 31.00 | false | security | 2021-11-03 | null |
+| Zero to Website in a Weekend | Anna Kral | 18.50 | true | html, css, web | 2024-05-20 | null |
+| Refactoring Legacy Apps | Jan Dvorak | 42.00 | true | php, architecture | 2019-08-01 | Second edition |
+| Coffee & Code | Marta Novak | 12.00 | false | essays | 2022-02-14 | null |
+
+Chapters about security add their own hostile input directly in `example.php`.
+
+
+## Adding a Chapter
+
+1. Pick the single concept; check it needs nothing from later chapters.
+2. Create `NN-slug/` with the skeleton above, taking data from the dataset.
+3. Write the readme in the fixed shape; paste *Output* from a real run.
+4. Keep the limits: example.php ≤ 40 lines, template ≤ 50, readme 60-140.
+5. Run `composer lint-templates` and the example itself, twice - output must be identical.
+6. Add a row to the chapter table in the root readme.