Create initial AGENTS.md and improve CONTRIBUTING.md

Author: codedmonkey

AGENTS.md

@@ -0,0 +1,86 @@
+# Agent guidelines for Dirigent development
+
+Dirigent is a free and open package registry for Composer, the PHP package manager. It allows users to publish private packages and mirror packages from external registries like Packagist.
+
+### Project structure
+
+```
+assets/                         # Frontend assets
+config/                         # Symfony configuration
+migrations/                     # Doctrine migrations (PostgreSQL)
+src/
+├── Attribute/                  # PHP attributes
+├── Command/                    # Symfony console commands
+├── Composer/                   # Composer integration logic
+├── Controller/                 # HTTP controllers
+│   └── Dashboard/              # EasyAdmin dashboard controllers
+├── Doctrine/
+│   ├── Entity/                 # Doctrine ORM entities
+│   ├── Repository/             # Doctrine repositories
+│   ├── Type/                   # Custom Doctrine types
+│   └── DataFixtures/           # Database fixtures
+├── Encryption/                 # Encryption utilities
+├── Entity/                     # Enums (UserRole, PackageUpdateSource)
+├── EventListener/              # Symfony event listeners
+├── Form/                       # Symfony form types
+├── Message/                    # Symfony messenger messages and handlers (async jobs)
+├── Package/                    # Package management services
+├── Routing/                    # Symfony routing logic
+├── Twig/                       # Twig extensions
+└── Validator/                  # Symfony validators
+templates/                      # Twig templates
+tests/
+├── UnitTests/                  # Unit tests
+├── FunctionalTests/            # Functional/Integration tests
+└── Docker/                     # Docker image tests
+```
+
+## Coding style
+
+### Project
+
+- Environment variables are stored in `.env.dirigent` and `.env.dirigent.*` (not `.env`).
+
+### PHP
+
+- Follow the PER coding style and the Symfony coding standards.
+- Organize services into domain-specific namespaces.
+- Always use strict comparisons (`===`, `!==`).
+- Enforce the use of DateTimeImmutable over DateTime.
+- Always use spaces in concatenation (`$a . $b`).
+- Always use imports. Use aliases when collisions occur or the imported name is unclear.
+- Don't use blank lines between import groups.
+
+## Commands
+
+### Linting & code quality
+
+```shell
+# Run all linting jobs
+symfony composer lint
+
+# Individual linters
+symfony composer lint:refactor        # Rector (automatically applies changes)
+symfony composer lint:coding-style    # PHP-CS-Fixer (automatically applies changes)
+symfony composer lint:static-analysis # PHPStan level 5
+symfony composer lint:container       # Symfony container validation
+symfony composer lint:templates       # Twig template validation
+```
+
+### Testing
+
+```shell
+# Prepare the Symfony test environment for tests (if the database schema changed)
+symfony composer tests:setup
+
+# Run all tests
+symfony composer tests
+
+# Run only PHP tests
+symfony composer tests:php
+symfony composer tests:php:unit
+symfony composer tests:php:functional
+
+# Run tests for Docker images
+symfony composer tests:docker
+```

CLAUDE.md

@@ -0,0 +1,3 @@
+# Agent guidelines for Dirigent development in Claude Code
+
+@AGENTS.md

CONTRIBUTING.md

@@ -3,46 +3,107 @@
 Dirigent is an open-source project, contributions of all kind are welcome, including
 [financial contributions][codedmonkey-sponsor].
 
+This guide contains technical information and instructions about the development process of the project that you should
+follow when contributing code.
+
+## Project information
+
+### Technology stack
+
+- **Languages & frameworks**:
+    - PHP 8.3+
+    - Symfony 7.3
+    - PostgreSQL 16.x (via Doctrine ORM 3.x)
+    - TypeScript
+- **Development requirements**:
+    - Docker
+    - Symfony CLI
+- **Package managers**:
+    - **PHP**: Composer
+    - **TypeScript**: NPM
+- **Frontend**: Twig, EasyAdmin 4.x
+- **Frontend (JavaScript)**: Webpack Encore, Stimulus
+- **Linting**: Rector, PHP-CS-Fixer, PHPStan
+- **Testing**: PHPUnit 12.x, Testcontainers
+
+### Coding style
+
+#### PHP
+
+Dirigent follows the [PER coding style][per-coding-style] and the [Symfony coding standards][symfony-coding-standards].
+
 ## Running Dirigent locally
 
-To run Dirigent locally, follow the [Running from source code][dirigent-docs-install-source] guide in the documentation,
+### Installation
+
+To run Dirigent locally, follow the [Running from source code][docs-install-source] guide in the documentation,
 up to the *Configure services* section.
 
 Additional requirements:
 
 - Symfony binary
 - Docker
 
+
 ```shell
 # Optionally, copy the example Docker Compose configuration override file
-cp compose.override.example.yaml composer.override.yaml
+cp compose.override.example.yaml compose.override.yaml
+
+# Install dependencies
+composer install
+npm install
 
-# Start Docker services
+# Build frontend assets
+npm run build # or watch for changes with: npm run watch
+
+# Run services through Docker Compose
 docker compose up -d
 
-# Start Symfony local server
+# Run the Symfony development server
 symfony server:start -d
+
+# Create & fill the development database
+symfony console doctrine:database:create --if-not-exists
+symfony console doctrine:schema:update --force
+symfony console doctrine:fixtures:load --no-interaction
 ```
 
-## Lint & test your code
+## Lint & validate the code
 
 ```shell
-# Run all linters
+# Run all linting jobs
 symfony composer lint
+
+# Individual linters
+symfony composer lint:refactor        # Rector (automatically applies changes)
+symfony composer lint:coding-style    # PHP-CS-Fixer (automatically applies changes)
+symfony composer lint:static-analysis # PHPStan level 5
+symfony composer lint:container       # Symfony container validation
+symfony composer lint:templates       # Twig template validation
 ```
 
-### Running PHPUnit tests
+### Running tests
 
 ```shell
-# Before running the tests, make sure the testing database is ready
+# Prepare the Symfony test environment (if the database schema changed)
 symfony composer tests:setup
+```
+
+```shell
+# Run all tests
+symfony composer tests
 
-# Run PHP tests
+# Run only PHP tests
 symfony composer tests:php
+symfony composer tests:php:unit
+symfony composer tests:php:functional
 
-# Run tests on Docker images
-symfony composer tests:docker 
+# Run tests for Docker images
+symfony composer tests:docker
+symfony composer tests:docker:standalone
 ```
 
 [codedmonkey-sponsor]: https://github.com/sponsors/codedmonkey
-[dirigent-docs-install-source]: https://dirigent.dev/docs/installation/source
+[docs-install-source]: ./docs/installation/source.md
+[per-coding-style]: https://www.php-fig.org/per/coding-style/
+[symfony-coding-standards]: https://symfony.com/doc/current/contributing/code/standards.html

docs/installation/docker-standalone.md

@@ -13,7 +13,7 @@ Dirigent into one, including a web server, database and a background worker. The
 
 ### Docker command
 
-```bash
+```shell
 docker volume create dirigent-data
 
 docker container run -d \

docs/installation/source.md

@@ -11,27 +11,31 @@ This page is a stub.
 
 :::
 
-Running the project from source code is not guaranteed to work on every system.
+Running the project from the source code is not guaranteed to work on every system.
 
 ## Requirements
 
-To install Dirigent on your system from source you need to following packages:
+To install Dirigent on your system from source you need to have the following packages installed on your system:
 
 - Git
 - PHP 8.3 or higher
 - Composer 2
 - Web server (like Nginx or Caddy)
 - PHP-FPM
-- PostgreSQL
-- Node
+- PostgreSQL 16
+- Node 23
 
 ## Download source code
 
+The recommended way to download Dirigent is through Git:
+
 ```shell
 git clone https://github.com/codedmonkey/dirigent.git
 cd dirigent
 ```
 
+You can also download the source code directly from the [Releases][github-releases] page on GitHub.
+
 ## Install build tools
 
 ```shell
@@ -44,4 +48,12 @@ npm install
 npm run production
 ```
 
+:::note
+
+Stop here if you're following the "Contributing to Dirigent" guide.
+
+:::
+
 ## Configure services
+
+[github-releases]: https://github.com/codedmonkey/dirigent/releases