# AGENTS.md

api_normalization - Drupal custom module for the LLM platform

## Project Overview

api_normalization is a custom Drupal module for the BlueFly.io LLM platform. It extends Drupal functionality with platform-specific features.

## Setup Commands

```bash
# This module is part of all_drupal_custom container
# Edit source files here, then sync to demo_llm-platform

# Sync module to Drupal installation
buildkit drupal sync --modules

# Or sync all custom code
buildkit drupal sync
```

## Build & Test Commands

```bash
# Navigate to Drupal installation
cd ../demo_llm-platform

# Run PHPCS (Drupal coding standards)
ddev phpcs web/modules/custom/api_normalization

# Run PHPStan (static analysis)
ddev phpstan web/modules/custom/api_normalization

# Clear Drupal cache
ddev drush cr

# Run module tests (if available)
ddev drush test api_normalization
```

## Code Style Guidelines

- Drupal 11 coding standards (PHPCS)
- PHP 8.3+ with `declare(strict_types=1);`
- 2-space indentation (NO tabs)
- PSR-12 + Drupal standards
- All functions MUST have DocBlocks
- Use dependency injection (never `\Drupal::service()`)

## Testing Instructions

- Write kernel tests for hooks and services
- Write functional tests for forms and controllers
- Run `ddev phpcs` before committing
- Run `ddev phpstan` for static analysis
- Test coverage target: 95%+

## Security Considerations

- Use `Xss::filterAdmin()` for admin output
- Use `Html::escape()` for user output
- Use `t()` for all user-facing strings
- Never commit secrets or credentials
- Validate all inputs

## Architecture Notes

- This module is in `all_drupal_custom/modules/` (source)
- It syncs to `demo_llm-platform/web/modules/custom/` (target)
- NEVER edit files in `web/` directly - edit source and sync
- Use `buildkit drupal sync` to sync changes

## Drupal Workflow

1. Edit source files in `all_drupal_custom/modules/api_normalization/`
2. Run `buildkit drupal sync` to sync to Drupal installation
3. Test in DDEV: `cd ../demo_llm-platform && ddev drush cr`
4. Commit changes in this repository

## Resources

- **GitLab**: https://gitlab.com/blueflyio/agent-platform/llm-platform
- **Drupal**: https://www.drupal.org
- **Drupal Coding Standards**: https://www.drupal.org/docs/develop/standards
- **Wiki**: https://gitlab.com/blueflyio/agent-platform/technical-docs/-/wikis
