fix: standardize skill sources and restore documentation checks

.changelog/framework-skill-sources.md

@@ -0,0 +1,12 @@
+---
+category: changed
+type: patch
+---
+
+Trust Fast Forward Composer skill donors through `fast-forward/*` and register
+the framework's bundled consumer skill as a local source for synchronization.
+Allow Changelog contributor skill updates within the stable `0.4.x` release line.
+Load the project autoloader for PHPDoc checks when DevTools is installed as a
+dependency.
+Render the provider guide with supported reStructuredText instead of unavailable
+PHP domain directives.

.gitattributes

@@ -17,3 +17,4 @@
 /phpunit.xml       export-ignore
 /README*.md         export-ignore
 /skills.json export-ignore
+/.php-cs-fixer.dist.php export-ignore

.php-cs-fixer.dist.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Fast Forward Framework — a lightweight PHP framework for building modern web applications with a simple and elegant API.
+ *
+ * This file is part of fast-forward/framework project.
+ *
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://php-fast-forward.github.io/framework/
+ * @see      https://github.com/php-fast-forward/framework
+ * @see      https://github.com/php-fast-forward/framework/issues
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+use FastForward\DevTools\Path\WorkingProjectPathResolver;
+use PhpCsFixer\Config;
+use PhpCsFixer\Finder;
+
+require __DIR__ . '/vendor/autoload.php';
+
+$header = trim((string) preg_replace(
+    ['!^/\*\*\n!', '! \*/!', '! \* ?!', '!%year%!', '!' . date('Y-Y') . '!'],
+    ['', '', '', date('Y'), date('Y')],
+    str_replace("\r\n", "\n", (string) file_get_contents(__DIR__ . '/.docheader')),
+));
+
+return (new Config())
+    ->setRiskyAllowed(false)
+    ->setFinder(Finder::create()->in(__DIR__)->exclude(WorkingProjectPathResolver::TOOLING_EXCLUDED_DIRECTORIES))
+    ->setRules([
+        'header_comment' => [
+            'header' => $header,
+            'comment_type' => 'PHPDoc',
+            'location' => 'after_declare_strict',
+            'separate' => 'both',
+        ],
+        'phpdoc_indent' => true,
+        'phpdoc_order' => ['order' => ['param', 'return', 'throws']],
+        'phpdoc_separation' => true,
+        'phpdoc_trim' => true,
+        'phpdoc_trim_consecutive_blank_line_separation' => true,
+        'phpdoc_scalar' => true,
+        'phpdoc_types' => true,
+        'phpdoc_to_comment' => false,
+        'phpdoc_add_missing_param_annotation' => true,
+    ]);

CONTRIBUTING.md

@@ -22,14 +22,18 @@ The development-only `llm/skills` Composer plugin restores the Changelog skill
 from the reviewed GitHub source in `skills.json`; generated files are ignored by
 Git. Use `composer skills:show` to inspect it and
 `composer skills:update --from=github` for an explicit refresh within the
-configured version range. Review `skills.json` before changing that range.
+configured `^0.4.0` version range (stable `0.4.x` releases, starting at `0.4.0`).
+With `auto-sync: true`, Composer also synchronizes skills after install/update;
+`--no-scripts` suppresses this automatic step. Review `skills.json` before
+changing that range.
 
 ## Composer dependency skills
 
-The development-only manager restores the consumer skills from these explicitly
-trusted Composer donors. Their minimum versions include the bundled payload;
-trust does not extend to other installed packages. No separate GitHub source
-is used for these libraries.
+The development-only manager restores consumer skills from installed Composer
+packages matching the `fast-forward/*` trust pattern. `trusted-replace` keeps
+packages outside that namespace untrusted, including other direct dependencies.
+The following dependencies have minimum versions that include their bundled
+payload. No separate GitHub source is used for these libraries.
 
 | Composer donor | Minimum version | Dependency scope |
 | --- | --- | --- |
@@ -50,12 +54,26 @@ is used for these libraries.
 The HTTP components remain transitive dependencies; Composer conflicts exclude
 older versions without adding duplicate runtime requirements. The template has
 an explicit development requirement. Composer Installers is not part of the
-installed graph, and the framework's own skill remains in its canonical
-`resources/skills` source rather than being a trusted dependency of itself.
+installed graph. The framework's own skill is registered as an explicit `dir`
+source in `skills.json`, using its canonical `resources/skills` directory. The
+directory adapter derives the donor identity without a package override.
 
 Inspect donors with `composer skills:show` and refresh their payloads with
 `composer skills:update --from=composer`. The existing GitHub source continues
-to manage the Changelog contributor skill independently. Generated copies remain
+to manage the Changelog contributor skill independently, discovering its bundled
+skill from the remote package's Composer metadata without a skill allowlist.
+Refresh the framework's own skill with `composer skills:update --from=dir`.
+Generated copies remain
 ignored. Synchronization does not upgrade runtime dependencies; an installed
 version without a bundled skill contributes no skill. Check installed versions
 and the bundled skill's supported contract before using its instructions.
+
+## PHPDoc and documentation checks
+
+The repository's `.php-cs-fixer.dist.php` loads the consumer autoloader and
+applies the DevTools PHPDoc and file-header rules. This avoids requiring a
+nonexistent nested `vendor/autoload.php` inside the installed DevTools package.
+Run `composer dev-tools` for the complete checks and generated documentation.
+An install with `--no-plugins` skips preparation of the signed phpDocumentor
+executable. When it is missing, run `composer reinstall phpdocumentor/shim`
+with the already approved plugins enabled before building documentation.

docs/api/service-provider.rst

@@ -1,16 +1,16 @@
 FrameworkServiceProvider
 ========================
 
-.. php:class:: FastForward\Framework\ServiceProvider\FrameworkServiceProvider
+``FastForward\Framework\ServiceProvider\FrameworkServiceProvider``
 
-   Aggregates the default Fast Forward framework providers into a single container entry point.
-   In the current package, it composes the HTTP stack, the event-dispatcher stack, and the clock utilities
-   by delegating to ``FastForward\Http\ServiceProvider\HttpServiceProvider``,
-   ``FastForward\EventDispatcher\ServiceProvider\EventDispatcherServiceProvider``, and
-   ``FastForward\Clock\ServiceProvider\ClockServiceProvider``.
+Aggregates the default Fast Forward framework providers into a single container entry point.
+In the current package, it composes the HTTP stack, the event-dispatcher stack, and the clock utilities
+by delegating to ``FastForward\Http\ServiceProvider\HttpServiceProvider``,
+``FastForward\EventDispatcher\ServiceProvider\EventDispatcherServiceProvider``, and
+``FastForward\Clock\ServiceProvider\ClockServiceProvider``.
 
-   The class extends ``FastForward\Container\ServiceProvider\AggregateServiceProvider``,
-   so it inherits the provider-merging behavior used across the ecosystem.
+The class extends ``FastForward\Container\ServiceProvider\AggregateServiceProvider``,
+so it inherits the provider-merging behavior used across the ecosystem.
 
 Usage
 -----
@@ -44,10 +44,10 @@ Important behavior inherited from ``AggregateServiceProvider``
 Constructor
 -----------
 
-.. php:method:: __construct()
+``__construct()``
 
-   Initializes the provider by passing the framework's default provider list to the parent
-   aggregate provider.
+Initializes the provider by passing the framework's default provider list to the parent
+aggregate provider.
 
 Current scope
 -------------

skills.json

@@ -1,5 +1,5 @@
 {
-    "$schema": "https://raw.githubusercontent.com/roxblnfk/skills/master/resources/skills.schema.json",
+    "$schema": "https://raw.githubusercontent.com/roxblnfk/skills/1.15.0/resources/skills.schema.json",
     "target": ".agents/skills",
     "aliases": [],
     "discovery": false,
@@ -8,31 +8,20 @@
     "dependencies": {
         "composer": {
             "trusted": [
-                "fast-forward/clock",
-                "fast-forward/config",
-                "fast-forward/container",
-                "fast-forward/defer",
-                "fast-forward/enum",
-                "fast-forward/event-dispatcher",
-                "fast-forward/fork",
-                "fast-forward/http",
-                "fast-forward/http-client",
-                "fast-forward/http-factory",
-                "fast-forward/http-message",
-                "fast-forward/iterators",
-                "fast-forward/phpdoc-bootstrap-template"
+                "fast-forward/*"
             ],
             "trusted-replace": true
         }
     },
     "sources": [
+        {
+            "from": "dir",
+            "path": "resources/skills"
+        },
         {
             "from": "github",
             "package": "php-fast-forward/changelog",
-            "ref": "^0.3.0",
-            "skills": [
-                "fast-forward-changelog"
-            ]
+            "ref": "^0.4.0"
         }
     ]
 }