docs(changelog,agents): document agent onboarding and standardize provider bootstrap snippets

Author: coisa

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

@@ -46,14 +46,15 @@ Requirements:
 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;
 
+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);

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/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/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

docs/usage/use-cases.rst

@@ -13,9 +13,10 @@ Bootstrap an application container
 .. code-block:: php
 
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+
    use function FastForward\Container\container;
 
-   $container = container(new FrameworkServiceProvider());
+   $container = container(FrameworkServiceProvider::class);
 
 This is the default starting point for web applications and small prototypes.
 
@@ -29,6 +30,7 @@ Build an event-driven application workflow
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
    use Psr\EventDispatcher\EventDispatcherInterface;
    use Psr\EventDispatcher\ListenerProviderInterface;
+
    use function FastForward\Container\container;
 
    final readonly class UserRegistered
@@ -68,11 +70,12 @@ Register your application services next to the framework
 
    use App\ServiceProvider\AppServiceProvider;
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+
    use function FastForward\Container\container;
 
    $container = container(
-       new FrameworkServiceProvider(),
-       new AppServiceProvider(),
+       FrameworkServiceProvider::class,
+       AppServiceProvider::class,
    );
 
 The later provider can add new services or override existing ones when it uses the same
@@ -87,6 +90,7 @@ Drive container setup from configuration
    use FastForward\Config\ArrayConfig;
    use FastForward\Container\ContainerInterface;
    use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+
    use function FastForward\Container\container;
 
    $config = new ArrayConfig([