feat: bundle template consumer skill and validate examples

.changelog/consumer-template-skill.md

@@ -0,0 +1,6 @@
+---
+category: added
+type: minor
+---
+
+Bundle a portable consumer skill with checked phpDocumentor examples, DevTools reports guidance and optional llm/skills discovery metadata.

.github/workflows/tests.yml

@@ -30,11 +30,14 @@ jobs:
       - run: composer install --no-scripts --no-interaction --prefer-dist --no-progress
       - name: Validate rendered checkout
         run: php tests/generate-fixture.php
+      - name: Validate bundled consumer example
+        run: php tests/verify-consumer-skill.php
       - name: Validate rendered release archive
         run: |
           mkdir -p "$RUNNER_TEMP/template-archive"
           git archive HEAD | tar -x -C "$RUNNER_TEMP/template-archive"
           php tests/generate-fixture.php "$RUNNER_TEMP/template-archive"
+          php tests/verify-consumer-skill.php "$RUNNER_TEMP/template-archive"
 
   actions:
     name: Analyze (actions)

AGENTS.md

@@ -0,0 +1,27 @@
+# Template maintenance
+
+This repository owns a phpDocumentor Twig/Bootstrap template, not a PHP service
+library. Preserve the Composer type `phpdocumentor-template` and existing public
+template path. Follow `CONTRIBUTING.md` for change fragments and `DESIGN.md` for
+visual identity. Merge, release and deployment require maintainer authorization.
+
+## Bundled consumer skill
+
+Read [the consumer skill](resources/skills/fast-forward-phpdoc-bootstrap-template/SKILL.md)
+when changing consumer configuration, integration examples, guides or the skill.
+Keep its version contract, references and checked examples aligned with public
+template behavior. Its canonical distributable source is `resources/skills`;
+do not add a second copy or host aliases. Package procedures belong in `SKILL.md`.
+
+## Validation
+
+Run `composer validate --strict`, `php tests/generate-fixture.php` and
+`php tests/verify-consumer-skill.php` after installing development dependencies.
+Check the archive too: `.gitattributes` excludes `/docs/`, so consumer skill
+references and examples must remain inside their package. The CI workflow owns
+the PHP matrix and archive rendering checks. Keep unrelated worktree changes.
+
+## Child DOX Index
+
+No child instruction contracts. The consumer package owns its procedure through
+its linked `SKILL.md`; ordinary template and test folders share this root contract.

README.md

@@ -103,6 +103,18 @@ Typical customization points include:
 - cards and content sections
 - Bootstrap styling
 
+## Consumer agent skill
+
+The package bundles [fast-forward-phpdoc-bootstrap-template](resources/skills/fast-forward-phpdoc-bootstrap-template/SKILL.md)
+for agents configuring guide homepages, API generation and output checks. It
+supports template `^2.1.1`, PHP `^8.3` and phpDocumentor shim `^3.9`, and includes
+an [existing DevTools reports route](resources/skills/fast-forward-phpdoc-bootstrap-template/references/dev-tools.md).
+The template itself does not install phpDocumentor or activate an agent skill.
+
+See [skill installation and lifecycle](resources/skills/fast-forward-phpdoc-bootstrap-template/references/installation.md)
+for optional project synchronization with `llm/skills ^1.15`, guarded manual
+project/global copies and a pinned Skills CLI alternative.
+
 ## Contributing
 
 Contributions are welcome. Please open an issue or submit a pull request.

composer.json

@@ -31,6 +31,14 @@
     "require": {
         "php": "^8.3"
     },
+    "suggest": {
+        "llm/skills": "Optionally synchronize the bundled consumer skill in your project."
+    },
+    "extra": {
+        "skills": {
+            "source": "resources/skills"
+        }
+    },
     "minimum-stability": "stable",
     "prefer-stable": true,
     "config": {

resources/skills/fast-forward-phpdoc-bootstrap-template/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Felipe Sayão Lobato Abreu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

resources/skills/fast-forward-phpdoc-bootstrap-template/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: fast-forward-phpdoc-bootstrap-template
+description: Configure and generate PHP API documentation and guides with the Fast Forward phpDocumentor Bootstrap template. Use for phpdoc.xml setup, guide homepages, template assets, output verification, or an existing Fast Forward DevTools reports integration.
+license: MIT; see LICENSE
+compatibility: Supports fast-forward/phpdoc-bootstrap-template ^2.1.1, PHP ^8.3 and phpDocumentor shim ^3.9. Requires Composer and phpDocumentor extensions; the verification example also uses DOM. Earlier template releases are outside this contract.
+metadata:
+  author: Fast Forward
+  api-baseline: fast-forward/phpdoc-bootstrap-template ^2.1.1
+---
+
+# Generate Fast Forward documentation
+
+Use this skill in a PHP project consuming `fast-forward/phpdoc-bootstrap-template
+^2.1.1`. Inspect `composer.json`, `composer.lock`, existing documentation commands
+and CI before editing. Run `composer show fast-forward/phpdoc-bootstrap-template`
+and `composer show phpdocumentor/shim` to check installed versions. If they fall
+outside this contract, inspect the matching version's documentation; do not
+upgrade dependencies just to use this skill. The template has no PHP namespace,
+container registration or application autoloader requirement: phpDocumentor
+loads its `template.xml` and Twig files.
+
+## Configure a guide homepage and API
+
+Prefer an existing DevTools route if the project already uses it; load
+[DevTools integration](references/dev-tools.md) for that case. Otherwise use the
+direct route below. Preserve existing source exclusions and project conventions.
+
+Prerequisites: PHP ^8.3, Composer, phpDocumentor's required extensions (including
+DOM/XML, mbstring and intl), and trusted project sources. Graphviz `dot` is needed
+for class diagrams. The template package alone does not install the generator.
+With authority to install the project's development tooling, review/merge the
+specific shim plugin approval and install:
+
+```sh
+composer config allow-plugins.phpdocumentor/shim true
+composer require --dev 'fast-forward/phpdoc-bootstrap-template:^2.1.1' 'phpdocumentor/shim:^3.9'
+```
+
+From the project root, create `phpdoc.xml`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<phpdocumentor configVersion="3">
+    <title>Example documentation</title>
+    <paths>
+        <output>build/docs</output>
+        <cache>build/phpdoc-cache</cache>
+    </paths>
+    <version number="latest">
+        <api>
+            <include-source>true</include-source>
+            <source dsn="."><path>src</path></source>
+        </api>
+        <guide format="rst">
+            <source dsn="."><path>docs</path></source>
+            <output>.</output>
+        </guide>
+    </version>
+    <template name="vendor/fast-forward/phpdoc-bootstrap-template" />
+</phpdocumentor>
+```
+
+Use the real PHP source directory in `<api>`. `include-source` exposes source
+code in the generated public documentation; remove it if that is inappropriate.
+Never scan private configuration, credentials, `vendor/` or test data as sources.
+The example's single explicit `src` path bounds the scan.
+
+Create `docs/index.rst`:
+
+```rst
+Example documentation
+=====================
+
+Welcome to the project documentation.
+
+.. toctree::
+   :maxdepth: 2
+
+   guides/installation
+```
+
+Create `docs/guides/installation.rst`:
+
+```rst
+Installation
+============
+
+Install the project dependencies with Composer.
+
+.. code-block:: shell
+
+   composer install
+```
+
+Add a documented public PHP class in `src/` (one same-named class per file), or
+use the project's existing classes. A complete minimal class and these exact
+configuration/guide files are bundled under [examples](examples/phpdoc.xml).
+No application bootstrap is executed to render this example; phpDocumentor
+parses PHP sources. Use the existing Composer autoload configuration if the
+application itself needs to execute those classes.
+
+Generate from the project root:
+
+```sh
+vendor/bin/phpdoc --config phpdoc.xml
+test -f build/docs/index.html
+test -f build/docs/guides/installation.html
+test -f build/docs/css/base.css
+test -f build/docs/js/searchIndex.js
+test -f build/docs/images/fast-forward-logo-dark.svg
+test -f build/docs/images/dash-reading.png
+```
+
+`docs/index.rst` becomes `build/docs/index.html` because the guide output is `.`.
+Keep this guide index: the template's transformations do not generate an API-only
+root homepage. For an API-only project, provide a small landing guide or verify
+and configure a separate landing-page strategy. Do not promise an automatic
+fallback from the unused `index.html.twig` file.
+
+## Check the generated site
+
+Serve `build/docs` with the project's static preview tooling, or temporarily use
+`php -S 127.0.0.1:8080 -t build/docs`. Check the homepage, nested guide, API class,
+navigation, search, light/navy theme, narrow viewport and source links. Stop the
+preview server after use. Publish the entire output tree so relative links,
+search data and identity images survive nested hosting paths. Generation does
+not authorize a Pages deployment.
+
+For the bundled example, also run:
+
+```sh
+php /path/to/fast-forward-phpdoc-bootstrap-template/examples/verify.php build/docs
+```
+
+This verifier expects the bundled `Example` class and guide text. For a real
+project adapt checks to its API names; a passing command with no generated HTML
+is insufficient. It checks files/content, not browser behavior.
+
+## Diagnose and customize
+
+- Missing homepage: check the guide source, `docs/index.rst` and `<output>.</output>`.
+- Missing API: inspect the `<api>` source path, PHP extensions/exclusions and
+  phpDocumentor diagnostics; the template does not discover application sources.
+- Missing template/assets: confirm the installed package and actual vendor path.
+  For custom Composer `vendor-dir`, change both binary and template paths.
+- Stale output: use a new disposable cache/output directory to compare; do not
+  delete an existing public site or unrelated caches as a diagnostic step.
+- Invalid XML or generator failure: retain diagnostics, correct inputs and check
+  output again. For diagrams, inspect Graphviz availability separately.
+- Markdown guides: the minimal route uses reStructuredText. Markdown requires a
+  compatible phpDocumentor guide renderer; do not treat the template as a parser.
+- Styling: inspect the installed Twig inheritance and `css/base.css.twig`. Make
+  deliberate overrides in a project-owned complete template or maintained fork;
+  pass its path as the template. Editing `vendor/` is overwritten by Composer.
+  Copy runtime `data/` assets and `template.xml` transformations together. There
+  is no promised configuration key for arbitrary Twig overrides.
+
+For optional copying/synchronization of this skill, load
+[installation and lifecycle](references/installation.md). Installing the template,
+copying this skill and having an agent load it are separate steps.

resources/skills/fast-forward-phpdoc-bootstrap-template/examples/docs/guides/installation.rst

@@ -0,0 +1,8 @@
+Installation
+============
+
+Install the project dependencies with Composer.
+
+.. code-block:: shell
+
+   composer install

resources/skills/fast-forward-phpdoc-bootstrap-template/examples/docs/index.rst

@@ -0,0 +1,9 @@
+Example documentation
+=====================
+
+Welcome to the project documentation.
+
+.. toctree::
+   :maxdepth: 2
+
+   guides/installation

resources/skills/fast-forward-phpdoc-bootstrap-template/examples/phpdoc.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpdocumentor configVersion="3">
+    <title>Example documentation</title>
+    <paths>
+        <output>build/docs</output>
+        <cache>build/phpdoc-cache</cache>
+    </paths>
+    <version number="latest">
+        <api>
+            <include-source>true</include-source>
+            <source dsn="."><path>src</path></source>
+        </api>
+        <guide format="rst">
+            <source dsn="."><path>docs</path></source>
+            <output>.</output>
+        </guide>
+    </version>
+    <template name="vendor/fast-forward/phpdoc-bootstrap-template" />
+</phpdocumentor>

resources/skills/fast-forward-phpdoc-bootstrap-template/examples/src/Example.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Example\Documentation;
+
+/** Provides a greeting for the documentation example. */
+final class Example
+{
+    /** Return a greeting addressed to the reader. */
+    public function greet(string $name): string
+    {
+        return 'Hello, ' . $name . '!';
+    }
+}

resources/skills/fast-forward-phpdoc-bootstrap-template/examples/verify.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+// Run against the output of examples/phpdoc.xml, from any working directory.
+if ($argc !== 2 || !is_dir($argv[1])) {
+    fwrite(STDERR, "Usage: php verify.php /path/to/generated/docs\n");
+    exit(1);
+}
+
+$output = rtrim($argv[1], '/');
+foreach ([
+    'index.html' => 'Welcome to the project documentation.',
+    'guides/installation.html' => 'composer install',
+    'classes/Example-Documentation-Example.html' => 'greet',
+    'css/base.css' => '#6d28d9',
+    'js/searchIndex.js' => 'Example',
+    'js/template.js' => 'fast-forward-documentation-theme',
+    'images/fast-forward-logo-dark.svg' => '<svg',
+    'images/dash-reading.png' => "\x89PNG",
+] as $path => $expected) {
+    $file = $output . '/' . $path;
+    $contents = is_file($file) ? file_get_contents($file) : false;
+    if ($contents === false || !str_contains($contents, $expected)) {
+        fwrite(STDERR, "Missing or invalid generated artifact: {$path}\n");
+        exit(1);
+    }
+}
+echo "PASS: consumer homepage, nested guide, API, search and theme assets\n";