AGENTS.md git:20261022.a7e3bf4A

Immutable. This exact content never changes and is served at /api/v1/blob/a8e089c16ea6d89f.

# Cecil - Agent Instructions

Short, actionable instructions for coding agents working in this repository.

## Start Here

- Project overview and usage: [README.md](README.md)
- Contribution process: [CONTRIBUTING.md](CONTRIBUTING.md)
- Command reference: [docs/commands/index.md](docs/commands/index.md)
- Architecture: [docs/developers/3-architecture.md](docs/developers/3-architecture.md)
- If any of the linked reference files are missing or unreadable, stop and notify the user before proceeding, as the missing document may contain requirements critical to the task.

## Critical Commands

- Install dependencies: `composer install`
- Run full quality checks: `composer code`
- Static analysis: `composer code:analyse`
- Style checks: `composer code:style`
- Style fixes (PHP CS Fixer): `composer code:fix`
- Twig templates lint: `composer code:twig`
- Tests (unit + integration): `composer test`
- Unit tests only: `composer test:unit`
- Integration tests only: `composer test:integration`
- CLI tests: `composer test:cli`
- If `composer code` or `composer test` fails, stop, report the failing output to the user, and do not commit or continue until all checks pass.

## Architecture At A Glance

- Main flow: Builder -> Steps -> Generators -> Renderer -> Output
- Core entry points:
  - `src/Builder.php`
  - `src/Application.php`
- Pipeline steps live in `src/Step/`
- Page generators live in `src/Generator/` (priority-based execution)
- Rendering stack lives in `src/Renderer/`
- Unit tests live in `tests/Unit/` (`*Test.php`), integration tests in `tests/IntegrationTests.php` and `tests/IntegrationCliTests.php`, fixtures in `tests/fixtures/`
- When adding a new Generator, Step, or Command, add a corresponding test under the relevant test directory and verify it passes with `composer test`. CLI-facing behavior must also be covered by `composer test:cli`.

## Coding Conventions

- PHP 8.3+, strict types (`declare(strict_types=1);` in every PHP file), PSR-12 style
- Use 4 spaces in PHP files
- Every PHP file starts with the Cecil header (see `header_comment` in `.php-cs-fixer.php`):

  ```php
  <?php

  /**
   * This file is part of Cecil.
   *
   * (c) Arnaud Ligny <arnaud@ligny.fr>
   *
   * For the full copyright and license information, please view the LICENSE
   * file that was distributed with this source code.
   */
  ```

- Prefix only compiler-optimized native PHP functions with `\` (`\count()`, `\is_string()`, `\in_array()`, `\sprintf()`, etc.), not the others (`preg_match()`, `array_map()`, `str_starts_with()`, etc.): this is enforced by the `native_function_invocation` rule of PHP CS Fixer, so run `composer code:fix` rather than prefixing by hand.
- Use `?Type` for nullable parameters
- When modifying existing files, do not reformat unrelated lines and keep public APIs and behavior unchanged unless explicitly requested. If a touched file lacks the header or strict types, add them.
- Twig/YAML/JS use 2 spaces
- All Twig template files (*.twig) anywhere in the repository must not end with a trailing newline. Remove any trailing newline when creating or editing these files.
- Markdown trailing spaces are semantically meaningful (they produce line breaks). Never remove trailing spaces from Markdown files, even when reformatting or cleaning up content, unless the user explicitly confirms the spaces are unintentional.
- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), with a first line of 72 characters or less (see [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages)).

## Framework Conventions

- New commands should extend `AbstractCommand`
- New generators should extend `AbstractGenerator`
- New steps should extend `AbstractStep`
- Use PSR-3 `LoggerInterface` for logging
- Use PSR-16 `SimpleCacheInterface` for caching
- Exceptions should implement/extend `Cecil\Exception\ExceptionInterface`

## Pitfalls

- Generator ordering is priority-sensitive. Keep configured generator priorities coherent with expected extraction order.
- Page section assignment relies on original `filepath`, not transformed page path.
- Keep docs updated when behavior or architecture changes, especially in [docs/](docs/) and [README.md](README.md). Docs are organized in sub-sections (`docs/<section>/<n>-<name>.md`, with an `index.md` per section).
- Keep agent skills in [skills/](skills/) (`cecil`, `cecil-theme`) consistent with user-facing behavior changes.
- When editing a `.md` documentation file, apply equivalent changes to its `.fr.md` counterpart. If the `.fr.md` counterpart does not exist, notify the user before proceeding.
- When editing a documentation file with frontmatter, always update the `updated` date to reflect the change.
- When updating code in `src/`, update API documentation with `php phpdoc` command (download `phpdoc` binary with `curl -Lo phpdoc https://phpdoc.org/phpDocumentor.phar` if necessary).