[docs] Standardize repository README and docs conventions

AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS - Fast Forward Framework
+
+This repository is a PHP metapackage (`fast-forward/framework`) that aggregates and wires core
+Fast Forward components through a single provider entry point.
+
+## Repository surfaces
+
+- Primary package entrypoint: [`src/`](src/)
+- Container/service-provider behavior: [`src/ConfigProvider/`](src/ConfigProvider/)
+- Tests: [`tests/`](tests/)
+- Docs: [`docs/`](docs/)
+- CI configuration: [`.github/workflows/`](.github/workflows/)
+- Release history: [`CHANGELOG.md`](CHANGELOG.md)
+- Project README: [`README.md`](README.md)
+
+## Setup and local workflow
+
+- Run `composer install` before making any code changes.
+- Keep local runtime aligned to PHP 8.3 (project minimum).
+- Run full local validation with:
+  - `composer dev-tools`
+- Apply auto-fixes and generated file synchronization with:
+  - `composer dev-tools:fix`
+- Validate changelog discipline on PR branches with:
+  - `composer dev-tools changelog:check -- --against=refs/remotes/origin/main`
+
+## Testing and quality gates
+
+- Primary test command: `composer dev-tools` (includes PHPUnit and report generation).
+- Focused test command used by the dev-tools pipeline: `vendor/bin/phpunit`.
+- Relevant changelog and release workflow checks are in
+  [`.github/workflows/changelog.yml`](.github/workflows/changelog.yml) and
+  [`.github/workflows/tests.yml`](.github/workflows/tests.yml).
+
+## Documentation conventions
+
+- Keep docs consistent with metapackage usage snippets and avoid instantiating providers directly
+  when the `::class` shorthand is the canonical documented pattern.
+- Use `FrameworkServiceProvider::class` in documented bootstrap examples per current standards.
+
+## PR and review expectations
+
+- When making user-visible changes, add an entry under `## [Unreleased]` in [`CHANGELOG.md`](CHANGELOG.md).
+- Prefer concise entry wording and include the current PR reference when known.

CHANGELOG.md

@@ -11,6 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add changelog history for releases v1.0.0-v1.3.0 during dev-tools asset synchronization. (#3)
 - Sync latest Fast Forward dev-tools managed assets (workflow templates, governance metadata, agents, and skills) into this repository. (#3)
+- Add repository AGENTS.md for agent task orchestration and local onboarding flow.
+
+### Changed
+
+- Prefer FrameworkServiceProvider::class in framework README/docs bootstrap snippets instead of instantiating provider objects.
 
 ## [1.3.0] - 2026-03-29
 

README.md

@@ -1,8 +1,12 @@
 # Fast Forward Framework
 
+![Fast Forward mascot](docs/_static/mascot.png)
+
 [![PHP Version](https://img.shields.io/badge/php-^8.3-777BB4?logo=php&logoColor=white)](https://www.php.net/releases/)
+[![Composer Package](https://img.shields.io/badge/composer-fast--forward%2Fframework-F28D1A.svg?logo=composer&logoColor=white)](https://packagist.org/packages/fast-forward/framework)
 [![Tests](https://img.shields.io/github/actions/workflow/status/php-fast-forward/framework/tests.yml?logo=githubactions&logoColor=white&label=tests&color=22C55E)](https://github.com/php-fast-forward/framework/actions/workflows/tests.yml)
 [![Coverage](https://img.shields.io/badge/coverage-phpunit-4ADE80?logo=php&logoColor=white)](https://php-fast-forward.github.io/framework/coverage/index.html)
+[![Metrics](https://img.shields.io/badge/metrics-phpmetrics-8B5CF6?logo=php&logoColor=white)](https://php-fast-forward.github.io/framework/metrics/index.html)
 [![Docs](https://img.shields.io/github/deployments/php-fast-forward/framework/github-pages?logo=readthedocs&logoColor=white&label=docs&labelColor=1E293B&color=38BDF8&style=flat)](https://php-fast-forward.github.io/framework/index.html)
 [![License](https://img.shields.io/github/license/php-fast-forward/framework?color=64748B)](LICENSE)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/php-fast-forward?logo=githubsponsors&logoColor=white&color=EC4899)](https://github.com/sponsors/php-fast-forward)
@@ -14,68 +18,81 @@
 [![PSR-18](https://img.shields.io/badge/PSR--18-http--client-777BB4?logo=php&logoColor=white)](https://www.php-fig.org/psr/psr-18/)
 [![PSR-20](https://img.shields.io/badge/PSR--20-clock-777BB4?logo=php&logoColor=white)](https://www.php-fig.org/psr/psr-20/)
 
-**Fast Forward Framework** is a lightweight and fast PHP framework designed for building modern web
-and event-driven applications.
-This package serves as an **aggregate metapackage**, bundling all core components of the Fast Forward ecosystem for easier installation and management.
+**Fast Forward Framework** is a lightweight aggregate metapackage that installs the core
+Fast Forward stack through a single dependency and a single service-provider bootstrap.
+
+## ✨ Features
 
----
+- 🎯 One-command installation of core Fast Forward packages
+- 🧩 Aggregates HTTP and event-dispatcher infrastructure with container integration
+- 🚀 Compatible with modern PHP standards (PSR-7, PSR-11, PSR-14, PSR-17, PSR-18, PSR-20)
+- 🧱 Built as the foundation layer for Fast Forward applications
 
-## Features
+## 📦 Installation
 
-- 🚀 **Modern PHP 8.3+ syntax**
-- 📦 Simplifies installation of all core packages in one step
-- 🔌 Registers the Fast Forward HTTP and event-dispatcher stacks through a single framework provider
-- 🧱 Provides a solid foundation for building scalable PHP applications
+```bash
+composer require fast-forward/framework
+```
 
-## Usage
+Requirements:
+
+- PHP 8.3 or higher
+
+## 🛠️ Usage
 
 ```php
 <?php
 
 declare(strict_types=1);
 
 use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
-use function FastForward\Container\container;
 use Psr\Clock\ClockInterface;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Http\Message\ResponseFactoryInterface;
 
-require_once __DIR__ . '/vendor/autoload.php';
+use function FastForward\Container\container;
+
+require __DIR__ . '/vendor/autoload.php';
 
-$container = container(new FrameworkServiceProvider());
+$container = container([FrameworkServiceProvider::class]);
 
 $responseFactory = $container->get(ResponseFactoryInterface::class);
 $dispatcher = $container->get(EventDispatcherInterface::class);
 $clock = $container->get(ClockInterface::class);
 ```
 
----
+## 🔌 Package Surface
 
-## Installation
+- `FastForward\Framework\ServiceProvider\FrameworkServiceProvider`
+- Core HTTP and event-dispatcher service provider orchestration
+- Shared configuration and lifecycle defaults for core packages in the ecosystem
 
-Install via [Composer](https://getcomposer.org):
-
-```bash
-composer require fast-forward/framework
-```
+## 📚 Documentation
 
-This command will automatically pull in all the required dependencies of the framework.
+- [GitHub Repository](https://github.com/php-fast-forward/framework)
+- [Packagist](https://packagist.org/packages/fast-forward/framework)
+- [Issue Tracker](https://github.com/php-fast-forward/framework/issues)
+- [Coverage](https://php-fast-forward.github.io/framework/coverage/index.html)
+- [Metrics](https://php-fast-forward.github.io/framework/metrics/index.html)
+- [Docs](https://php-fast-forward.github.io/framework/index.html)
 
----
+## 🧪 Quality and Observability
 
-## Requirements
+- Test suite: [GitHub Actions](https://github.com/php-fast-forward/framework/actions/workflows/tests.yml)
+- Coverage: `coverage/index.html`
+- Testdox: `coverage/testdox.html`
+- Metrics: `metrics/index.html`
 
-- PHP 8.3 or higher
+## 🤝 Contributing
 
----
+Contributions, issues, and feature requests are welcome. Keep changes focused and aligned
+with the repository's existing documentation and contribution flow.
 
-## License
+## 🛡 License
 
 Fast Forward Framework is licensed under the [MIT license](LICENSE).
 
----
-
-## Author
+## 👤 Author
 
-Developed with ❤️ by **Felipe Sayão Lobato Abreu**  
-📧 [github@mentordosnerds.com](mailto:github@mentordosnerds.com)
+Developed by **Felipe Sayão Lobato Abreu**
+- 📧 [github@mentordosnerds.com](mailto:github@mentordosnerds.com)

docs/advanced/customization.rst

@@ -13,11 +13,12 @@ Register your application provider after the framework provider:
 
    use App\ServiceProvider\AppServiceProvider;
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+
    use function FastForward\Container\container;
 
    $container = container(
-       new FrameworkServiceProvider(),
-       new AppServiceProvider(),
+       FrameworkServiceProvider::class,
+       AppServiceProvider::class,
    );
 
 This keeps the framework defaults while giving your application room to add domain-specific
@@ -86,6 +87,7 @@ You can extend the framework's event behavior without replacing the framework pr
    use FastForward\Container\ContainerInterface;
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
    use Psr\EventDispatcher\ListenerProviderInterface;
+
    use function FastForward\Container\container;
 
    $config = new ArrayConfig([

docs/advanced/integration.rst

@@ -12,9 +12,10 @@ The recommended integration path is the ``container()`` helper from ``fast-forwa
 .. code-block:: php
 
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+
    use function FastForward\Container\container;
 
-   $container = container(new FrameworkServiceProvider());
+   $container = container(FrameworkServiceProvider::class);
 
 Integrate through configuration
 -------------------------------
@@ -29,6 +30,7 @@ container helper:
    use FastForward\Container\ContainerInterface;
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
    use Psr\EventDispatcher\ListenerProviderInterface;
+
    use function FastForward\Container\container;
 
    $config = new ArrayConfig([

docs/api/service-provider.rst

@@ -18,9 +18,10 @@ Usage
 .. code-block:: php
 
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+
    use function FastForward\Container\container;
 
-   $container = container(new FrameworkServiceProvider());
+   $container = container(FrameworkServiceProvider::class);
 
 What it aggregates
 ------------------

docs/faq.rst

@@ -49,9 +49,10 @@ Use the helper function from ``fast-forward/container``:
 .. code-block:: php
 
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+
    use function FastForward\Container\container;
 
-   $container = container(new FrameworkServiceProvider());
+   $container = container(FrameworkServiceProvider::class);
 
 How do I access the current request?
 ------------------------------------

docs/getting-started/index.rst

@@ -14,3 +14,6 @@ If you are evaluating the package for the first time, read the pages in this ord
 
    installation
    quickstart
+
+Learn more in the main links section for dependency and report references before you
+start production wiring.

docs/getting-started/quickstart.rst

@@ -15,14 +15,15 @@ Minimal bootstrap
 
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
    use FastForward\Http\Message\Factory\ResponseFactoryInterface;
-   use function FastForward\Container\container;
    use Psr\EventDispatcher\EventDispatcherInterface;
    use Psr\Http\Client\ClientInterface;
    use Psr\Http\Message\ServerRequestInterface;
 
+   use function FastForward\Container\container;
+
    require_once __DIR__ . '/../vendor/autoload.php';
 
-   $container = container(new FrameworkServiceProvider());
+   $container = container(FrameworkServiceProvider::class);
 
    $request = $container->get(ServerRequestInterface::class);
    $responseFactory = $container->get(ResponseFactoryInterface::class);
@@ -55,9 +56,10 @@ function:
 .. code-block:: php
 
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+
    use function FastForward\Container\container;
 
-   $container = container(new FrameworkServiceProvider());
+   $container = container(FrameworkServiceProvider::class);
 
 This is the preferred documented bootstrap for this repository because the installed container
 package exposes the helper function and ``ContainerInterface``, not a ``Container`` class.

docs/index.rst

@@ -4,16 +4,33 @@
 Documentation
 =============
 
-**Fast Forward Framework** is the metapackage entry point for the Fast Forward ecosystem.
-It installs the core libraries you are most likely to need first and exposes a single
-``FrameworkServiceProvider`` that bootstraps the HTTP and event-dispatcher stacks inside a
-Fast Forward container.
+.. container:: row align-items-center gy-4 my-4
 
-This package is especially useful when you want one Composer dependency that gives you:
+   .. container:: col-lg-7
 
-- a PSR-11 friendly container workflow
-- the Fast Forward HTTP and event-dispatcher service-provider stacks
-- access to supporting packages such as configuration, deferred callbacks, iterators, and process tools
+      **Fast Forward Framework** is the metapackage entry point for the Fast Forward ecosystem.
+      It installs the core libraries you are most likely to need first and exposes a single
+      ``FrameworkServiceProvider`` that bootstraps the HTTP and event-dispatcher stacks inside a
+      Fast Forward container.
+
+      If you are new to the package, start with
+      :doc:`getting-started/installation` and :doc:`getting-started/quickstart`.
+
+      If you are maintaining a consumer application, read
+      :doc:`advanced/integration`, :doc:`usage/index`, and
+      :doc:`links/dependencies`.
+
+      This package is especially useful when you want one Composer dependency that gives you:
+
+      - a PSR-11 friendly container workflow
+      - the Fast Forward HTTP and event-dispatcher service-provider stacks
+      - access to supporting packages such as configuration, deferred callbacks, iterators, and process tools
+
+   .. container:: col-lg-5 text-center
+
+      .. image:: _static/mascot.png
+         :alt: Fast Forward Framework mascot
+         :class: img-fluid w-100 rounded-4 shadow-sm border border-light-subtle bg-body-tertiary p-2
 
 What this package does
 ----------------------
@@ -41,6 +58,7 @@ Useful Links
 - `Packagist <https://packagist.org/packages/fast-forward/framework>`_
 - `Issue Tracker <https://github.com/php-fast-forward/framework/issues>`_
 - `Coverage Report <https://php-fast-forward.github.io/framework/coverage/index.html>`_
+- `Metrics Report <https://php-fast-forward.github.io/framework/metrics/index.html>`_
 - `Testdox Report <https://php-fast-forward.github.io/framework/coverage/testdox.html>`_
 
 .. toctree::

docs/links/index.rst

@@ -6,6 +6,7 @@ This section centralizes external references, dependency docs, and quality repor
 - `GitHub Repository <https://github.com/php-fast-forward/framework>`_
 - `Packagist <https://packagist.org/packages/fast-forward/framework>`_
 - `Coverage Report <https://php-fast-forward.github.io/framework/coverage/index.html>`_
+- `Metrics Report <https://php-fast-forward.github.io/framework/metrics/index.html>`_
 - `Testdox Report <https://php-fast-forward.github.io/framework/coverage/testdox.html>`_
 - `API Reference (README) <https://github.com/php-fast-forward/framework#readme>`_
 

docs/usage/event-dispatching.rst

@@ -34,6 +34,7 @@ The most practical way to add listeners is to provide them under the
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
    use Psr\EventDispatcher\EventDispatcherInterface;
    use Psr\EventDispatcher\ListenerProviderInterface;
+
    use function FastForward\Container\container;
 
    final readonly class UserRegistered
@@ -77,6 +78,7 @@ If your project uses Symfony subscribers or ``#[AsEventListener]`` attributes, a
    use Psr\EventDispatcher\ListenerProviderInterface;
    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
    use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
+
    use function FastForward\Container\container;
 
    final readonly class PaymentReceived