Adds comprehensive documentation on customizing, integrating, and using the Fast Forward Framework, including new files and sections on HTTP services, compatibility, FAQs, and use cases. Updates the index and link references for improved navigation.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

docs/advanced/customization.rst

@@ -0,0 +1,82 @@
+Customization
+=============
+
+The framework package is intentionally small, so customization mostly happens by composing extra
+providers around ``FrameworkServiceProvider``.
+
+Add your own provider
+---------------------
+
+Register your application provider after the framework provider:
+
+.. code-block:: php
+
+   use App\ServiceProvider\AppServiceProvider;
+   use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+   use function FastForward\Container\container;
+
+   $container = container(
+       new FrameworkServiceProvider(),
+       new AppServiceProvider(),
+   );
+
+This keeps the framework defaults while giving your application room to add domain-specific
+services.
+
+Override an existing service identifier
+---------------------------------------
+
+``AggregateServiceProvider`` merges factory arrays in provider order. In practice, that means a
+later provider can replace an earlier factory when both use the same service identifier.
+
+This is the simplest override strategy when you want to swap a default implementation entirely.
+
+Decorate an existing service with extensions
+--------------------------------------------
+
+If you want to wrap an existing service instead of replacing it, use provider extensions:
+
+.. code-block:: php
+
+   use Interop\Container\ServiceProviderInterface;
+   use Psr\Container\ContainerInterface;
+   use Psr\Http\Client\ClientInterface;
+
+   final class DecoratorServiceProvider implements ServiceProviderInterface
+   {
+       public function getFactories(): array
+       {
+           return [];
+       }
+
+       public function getExtensions(): array
+       {
+           return [
+               ClientInterface::class => static function (
+                   ContainerInterface $container,
+                   ClientInterface $client,
+               ): ClientInterface {
+                   return new LoggingClient($client);
+               },
+           ];
+       }
+   }
+
+The aggregate provider composes extensions in order, so later decorators wrap earlier ones.
+Replace ``LoggingClient`` with your own decorator implementation.
+
+Documented limitations
+----------------------
+
+- This package does not define framework-specific aliases or facades of its own.
+- The convenience aliases and helper factories live in the downstream HTTP factory package.
+- If you need additional providers for config-driven applications, register them explicitly or
+  list them in ``FastForward\Container\ContainerInterface::class`` inside your config object.
+
+Good customization defaults for new projects
+--------------------------------------------
+
+1. Start with ``FrameworkServiceProvider`` only.
+2. Add one application provider for your own services.
+3. Reach for overrides only after you know which service identifier you need to replace.
+4. Use extensions when you want to decorate behavior instead of rewriting the original factory.

docs/advanced/index.rst

@@ -1,9 +1,11 @@
 Advanced
 ========
 
-Advanced topics for extending and integrating the Fast Forward Framework.
+Advanced topics for composing the framework with your own providers, integrating it into different
+runtime styles, and understanding how service overrides behave.
 
 .. toctree::
    :maxdepth: 1
 
    integration
+   customization

docs/advanced/integration.rst

@@ -1,4 +1,81 @@
 Integration
 ===========
 
-The Fast Forward Framework is designed to integrate seamlessly with other PSR-compliant packages and libraries. You can add or override service providers as needed to customize your application's infrastructure.
+Fast Forward Framework is intentionally small and integrates best when you treat it as a bootstrap
+layer for the rest of your application.
+
+Integrate with the Fast Forward container
+----------------------------------------
+
+The recommended integration path is the ``container()`` helper from ``fast-forward/container``.
+
+.. code-block:: php
+
+   use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+   use function FastForward\Container\container;
+
+   $container = container(new FrameworkServiceProvider());
+
+Integrate through configuration
+-------------------------------
+
+When you want your provider list to live in configuration, you can pass a config object into the
+container helper:
+
+.. code-block:: php
+
+   use App\ServiceProvider\AppServiceProvider;
+   use FastForward\Config\ArrayConfig;
+   use FastForward\Container\ContainerInterface;
+   use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+   use function FastForward\Container\container;
+
+   $config = new ArrayConfig([
+       ContainerInterface::class => [
+           FrameworkServiceProvider::class,
+           AppServiceProvider::class,
+       ],
+   ]);
+
+   $container = container($config);
+
+This keeps environment-specific providers in one place and works well with the rest of the
+configuration package.
+
+HTTP runtime versus CLI runtime
+-------------------------------
+
+The framework provider registers ``Psr\Http\Message\ServerRequestInterface`` by calling
+``fromGlobals()`` through the downstream HTTP factory provider. That is convenient in web
+contexts, but it also means you should be deliberate in CLI commands and automated tests.
+
+For CLI or tests, prefer explicit request creation:
+
+.. code-block:: php
+
+   use Psr\Http\Message\RequestFactoryInterface;
+
+   $requestFactory = $container->get(RequestFactoryInterface::class);
+   $request = $requestFactory->createRequest('GET', 'https://example.test/health');
+
+PSR-oriented application services
+---------------------------------
+
+Because the container exposes PSR interfaces, your application code can type-hint the standard
+contracts instead of framework-specific implementations:
+
+.. code-block:: php
+
+   use Psr\Http\Client\ClientInterface;
+   use Psr\Http\Message\ResponseFactoryInterface;
+
+   final readonly class StatusPageAction
+   {
+       public function __construct(
+           private ClientInterface $client,
+           private ResponseFactoryInterface $responseFactory,
+       ) {}
+   }
+
+This keeps your domain services portable even when you rely on the Fast Forward ecosystem for
+bootstrap and defaults.

docs/api/index.rst

@@ -1,9 +1,11 @@
 API Reference
 ============
 
-This section documents the main classes and interfaces provided by the Fast Forward Framework.
+This section documents the local framework service provider and the most important classes and
+functions you will touch immediately after installing the metapackage.
 
 .. toctree::
    :maxdepth: 1
 
    service-provider
+   service-map

docs/api/service-map.rst

@@ -0,0 +1,66 @@
+Service Map
+===========
+
+This page connects the single local framework class to the wider set of services and helper entry
+points installed by the metapackage.
+
+Framework-level classes and providers
+-------------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 25 35
+
+   * - Identifier or class
+     - Source
+     - Responsibility
+   * - ``FastForward\Framework\ServiceProvider\FrameworkServiceProvider``
+     - This package
+     - Main bootstrap provider for the framework metapackage
+   * - ``FastForward\Http\ServiceProvider\HttpServiceProvider``
+     - ``fast-forward/http``
+     - Aggregates HTTP message-factory and HTTP client providers
+   * - ``FastForward\Http\Message\Factory\ServiceProvider\HttpMessageFactoryServiceProvider``
+     - ``fast-forward/http-factory``
+     - Registers PSR-17 factories, convenience factories, and ``ServerRequestInterface``
+   * - ``FastForward\Http\Client\ServiceProvider\HttpClientServiceProvider``
+     - ``fast-forward/http-client``
+     - Registers the PSR-18 client and Symfony HttpClient entry point
+
+Installed entry points outside the framework provider
+-----------------------------------------------------
+
+These classes and functions are worth knowing because they are installed together with the
+framework package, even though they are not auto-registered by ``FrameworkServiceProvider``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 26 40
+
+   * - Entry point
+     - Package
+     - Typical use
+   * - ``FastForward\Container\container()``
+     - ``fast-forward/container``
+     - Build a composed container from service providers, config objects, and PSR-11 containers
+   * - ``FastForward\Config\ArrayConfig`` and ``FastForward\Config\config()``
+     - ``fast-forward/config``
+     - Store and load configuration with dot-notation access
+   * - ``FastForward\Defer\Defer`` and ``FastForward\Defer\defer()``
+     - ``fast-forward/defer``
+     - Register scope-bound cleanup callbacks
+   * - ``FastForward\Fork\Manager\ForkManager``
+     - ``fast-forward/fork``
+     - Run parallel workers in supported CLI environments
+   * - ``FastForward\Iterator\ChunkedIteratorAggregate``
+     - ``fast-forward/iterators``
+     - Process iterable data in chunks
+
+How to read this map
+--------------------
+
+- If you need container-resolved HTTP services, start with ``FrameworkServiceProvider``.
+- If you need configuration, deferred callbacks, iterators, or process tools, use those packages
+  directly through their own APIs.
+- If you want to add more services into the container, register your own service provider after the
+  framework provider.

docs/api/service-provider.rst

@@ -3,25 +3,49 @@ FrameworkServiceProvider
 
 .. php:class:: FastForward\Framework\ServiceProvider\FrameworkServiceProvider
 
-   Aggregates all core service providers required to initialize the application container.
+   Aggregates the default Fast Forward framework providers into a single container entry point.
+   In the current package, it composes the HTTP stack by delegating to
+   ``FastForward\Http\ServiceProvider\HttpServiceProvider``.
 
-   **Usage:**
+   The class extends ``FastForward\Container\ServiceProvider\AggregateServiceProvider``,
+   so it inherits the provider-merging behavior used across the ecosystem.
 
-   .. code-block:: php
+Usage
+-----
 
-      use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
-      use FastForward\Container\Container;
+.. code-block:: php
 
-      $container = new Container([
-          new FrameworkServiceProvider(),
-      ]);
+   use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
+   use function FastForward\Container\container;
 
-   **Constructor:**
+   $container = container(new FrameworkServiceProvider());
 
-   .. php:method:: __construct()
+What it aggregates
+------------------
 
-      Initializes the aggregate service provider with all essential framework service providers (e.g., HTTP, logging, caching, etc.).
+- ``FastForward\Http\ServiceProvider\HttpServiceProvider``
+- Through that provider, the HTTP message factories and HTTP client service providers
 
-   **Extends:**
+Important behavior inherited from ``AggregateServiceProvider``
+--------------------------------------------------------------
 
-   - :php:class:`FastForward\Container\ServiceProvider\AggregateServiceProvider`
+- The provider registers itself as a retrievable service under its own class name.
+- The aggregated ``HttpServiceProvider`` is also available by class name.
+- Factory arrays are merged in provider order, so later providers can replace earlier service identifiers.
+- Extension callables are composed in order, so later extensions wrap earlier ones.
+
+Constructor
+-----------
+
+.. php:method:: __construct()
+
+   Initializes the provider by passing the framework's default provider list to the parent
+   aggregate provider.
+
+Current scope
+-------------
+
+Although the metapackage installs multiple libraries, this local service provider currently wires
+the HTTP stack only. Packages such as ``fast-forward/config``, ``fast-forward/defer``,
+``fast-forward/fork``, and ``fast-forward/iterators`` remain available through Composer autoloading
+and can be introduced into your application as needed.

docs/compatibility.rst

@@ -0,0 +1,35 @@
+Compatibility
+=============
+
+The table below reflects the constraints declared in this repository's ``composer.json`` on
+April 5, 2026.
+
+Runtime compatibility summary
+-----------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 72
+
+   * - Topic
+     - Current expectation
+   * - PHP
+     - ``^8.3``
+   * - Composer
+     - Composer 2 is the expected installation workflow
+   * - Container contract
+     - PSR-11 through ``fast-forward/container``
+   * - HTTP message and factories
+     - PSR-7 and PSR-17 through the aggregated HTTP packages
+   * - HTTP client
+     - PSR-18 through the aggregated HTTP client package
+   * - Fork support
+     - Unix-like CLI runtime with ``pcntl`` and ``posix`` support when using ``fast-forward/fork``
+
+Practical compatibility notes
+-----------------------------
+
+- ``ServerRequestInterface`` is created from globals, so it is most natural in web runtimes.
+- CLI tools and tests should build requests explicitly with ``RequestFactoryInterface``.
+- The package is safe to install even if you never use ``fast-forward/fork``; the runtime caveat
+  only matters when you choose to use that library.