# TYPO3 Project Rules for LLM Assistance

## Project Overview
This project is a TYPO3 installation with a custom site-package extension located in [`packages/base`](packages/base), providing layout, templates, and modular ContentBlocks for pages. The LLM should dynamically determine the TYPO3 version and related dependencies by examining project files.

## Technology Stack
- PHP (version defined in [`composer.json`](composer.json))
- TYPO3 (version defined in [`composer.json`](composer.json))
- Composer ([`composer.json`](composer.json))
- Deployer ([`build/deploy.php`](build/deploy.php), [`build/servers.yaml`](build/servers.yaml))
- Webpack ([`webpack.config.js`](webpack.config.js))
- PostCSS ([`postcss.config.js`](postcss.config.js)) with Tailwind CSS (version defined in [`package.json`](package.json)) and Autoprefixer
- SCSS (`packages/base/Resources/Public/Scss/`)
- JavaScript bundling (`packages/base/Resources/Public/JavaScript/`)
- PHPStan, Rector (`phpstan.neon`, `rector.php`)
- YAML and TypoScript for configuration

## Project Structure
- [`config/`](config/): Global TYPO3 config and environment overrides  
- [`data/`](data/): Database dumps and test fixtures  
- [`packages/base/`](packages/base/): Site-package extension with design assets, Fluid templates, TypoScript, ContentBlocks  
- [`public/`](public/): Document root  
- Build files: [`webpack.config.js`](webpack.config.js), [`postcss.config.js`](postcss.config.js)  
- Dependency manifests: [`package.json`](package.json), [`composer.json`](composer.json)

## Development Guidelines
- Use DDEV for local environment management: `ddev start`, `ddev restart`, `ddev stop`, etc.
- Check versions in [`composer.json`](composer.json) and [`package.json`](package.json) before referencing dependencies; the LLM should examine these files to determine actual versions
- Manage PHP dependencies via Composer within DDEV: `ddev exec composer install`, `ddev exec composer update`
- Manage JS/CSS via npm within DDEV: `ddev exec npm install`, `ddev exec npm run dev` / `ddev exec npm run build`
- Follow TYPO3 extension conventions in [`packages/base`](packages/base): `ext_localconf.php`, `ext_tables.php`, `ext_emconf.php`
- Organize TypoScript under [`packages/base/Configuration/Sets/SitePackage/TypoScript/`](packages/base/Configuration/Sets/SitePackage/TypoScript/)
- Enforce static analysis and automated refactoring with PHPStan and Rector

## Default Workflow
When handling any task, LLMs should follow this structured approach:

1. **Information Gathering**
   - Read the necessary code from the project using available tools
   - Examine [`composer.json`](composer.json) and [`package.json`](package.json) to understand current dependencies and versions
   - Use MCP servers to read documentation about libraries that are used and should be used
   - Review relevant project files to understand the current implementation
   - Gather context about the specific area of the codebase that will be affected

2. **Planning**
   - Analyze the gathered information to understand the task requirements
   - Plan how the task should be implemented within the existing project structure
   - Consider potential impacts on other parts of the codebase
   - Identify which files need to be created, modified, or reviewed
   - Determine the best approach that follows project conventions and best practices

3. **Implementation**
   - Execute the planned task using appropriate tools
   - Follow the project's coding standards and conventions
   - Test the implementation where possible
   - Ensure all changes work within the existing project structure

4. **Documentation Updates**
   - Update project documentation (README files) if the task affects user-facing functionality
   - Update these rules ([`.roo/rules/rules.md`](.roo/rules/rules.md)) if the task introduces new patterns, conventions, or important information that future LLMs should know
   - Ensure any new features or changes are properly documented for future reference

This workflow ensures thorough understanding, proper planning, clean implementation, and maintained documentation for all project changes.

## ContentBlocks Usage
- Defined under [`packages/base/ContentBlocks/ContentElements/`](packages/base/ContentBlocks/ContentElements/)
- Element folder contains:
  - `config.yaml` (block definition)
  - `templates/frontend.html` (frontend rendering)
  - `templates/backend-preview.html` (backend preview)
  - `language/labels.xlf` (translations)
- To add a new block:
  1. Create a folder under `ContentElements/`
  2. Define `config.yaml` and labels
  3. Add Fluid templates in `templates/`
  4. Clear caches and verify in TYPO3 backend (`ddev exec vendor/bin/typo3cms cache:flush`)
- Content element restrictions:
  - ContentBlocks are automatically registered via their YAML config files
  - Availability is controlled through PageTSconfig using `TCEFORM.tt_content.CType.keepItems`
  - The `keepItems` list in [`packages/base/Configuration/Sets/SitePackage/page.tsconfig`](packages/base/Configuration/Sets/SitePackage/page.tsconfig) determines which content elements editors can use
  - To enable a new ContentBlock, add its CType to the `keepItems` list
- Clear caches after changes

## Styling Guidelines
- All design work lives in the [`packages/base`](packages/base) extension
- SCSS structure in `Resources/Public/Scss/`:
  - `abstracts/` (variables, mixins, functions)
  - `base/` (resets, global styles)
  - `components/` (UI modules: buttons, cards, nav, etc.)
  - `layouts/` (page-specific styles)
- Include Tailwind directives in `main.scss`:
  ```scss
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
  ```
- Customize Tailwind in [`tailwind.config.js`](tailwind.config.js)

## Build Process
1. Compile SCSS → PostCSS (Tailwind + Autoprefixer) → CSS in `Resources/Public/Css/` (within DDEV: `ddev exec npm run build:css`)
2. Bundle JS via Webpack → `Resources/Public/JavaScript/` (within DDEV: `ddev exec npm run build:js`)
3. Run dev mode: `ddev exec npm run dev`
4. Run production build: `ddev exec npm run build`
5. Deploy via Deployer: `ddev exec vendor/bin/dep deploy`

## File Editing Guidelines
- TypoScript: `packages/base/Configuration/Sets/SitePackage/TypoScript/`
- YAML: `packages/base/Configuration/**/*.yaml`
- Fluid templates: `packages/base/Resources/Private/**/*.html`
- SCSS: `packages/base/Resources/Public/Scss/**/*.scss`
- JavaScript: `packages/base/Resources/Public/JavaScript/**/*.js`
- Never read or commit the environment file: [`.env`](.env)

## MCP Server Usage
- Use `brave_web_search` for general web searches via `use_mcp_tool`
- Use `resolve-library-id` + `get-library-docs` for official API docs:
  - `/typo3/docs` for TYPO3 reference
  - `/tailwindcss` for Tailwind CSS docs
- For NixOS/Home Manager queries: use `nixos_search`, `home_manager_search`

## Version Management
- Always inspect [`composer.json`](composer.json) for PHP dependencies and TYPO3 version
- Always inspect [`package.json`](package.json) for frontend dependencies
- Use MCP servers (e.g., `resolve-library-id`, `get-library-docs`) to fetch documentation matching the exact versions found
- Never assume specific dependency versions in code examples; dynamically reference versions as discovered

## Common Tasks
1. **Initial Setup**
   ```bash
   ddev start
   ddev composer install
   ddev npm install
   ```
2. **Development Build**
   ```bash
   ddev npm run dev
   ```
3. **Production Build**
   ```bash
   ddev npm run build
   ```
4. **Clear TYPO3 Cache**
   ```bash
   ddev typo3cms cache:flush
   ```
5. **Add a ContentBlock**
   - Create folder, config, templates, translations
   - Add the new ContentBlock's CType to the `keepItems` list in [`packages/base/Configuration/Sets/SitePackage/page.tsconfig`](packages/base/Configuration/Sets/SitePackage/page.tsconfig)
   - Clear caches and verify in backend
6. **DDEV Environment Management**
   - Restart environment: `ddev restart`
   - Stop environment: `ddev stop`
7. **Deploy**
   ```bash
   ddev exec vendor/bin/dep deploy production
   ```

## Troubleshooting
- **Blank CSS/JS**: confirm build pipeline ran; check [`webpack.config.js`](webpack.config.js)
- **YAML Syntax Errors**: validate `config.yaml` with a linter
- **Fluid Rendering Issues**: clear caches; verify template paths
- **TypoScript Not Loading**: ensure correct path under `Configuration/Sets`
- **Cache Problems**: always flush caches after changes