[docs] Refresh console class references (#123) (#124)

* [docs] Refresh console class references (#123)

* [docs] Refresh console class references (#123)

* Update wiki submodule pointer for PR #124

* [docs] Refresh architecture and sync guidance (#123)

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/wiki

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Document required GitHub Actions permissions for changelog release automation (#118)
 - Add the project mascot image to README and documentation (#121)
 - Upgrade the packaged phpDocumentor bootstrap template to v2.0.0 (#121)
+- Refresh outdated console bootstrap, sync, and dependency-injection documentation (#123)
 
 ## [1.12.0] - 2026-04-19
 

CHANGELOG.md

@@ -216,11 +216,21 @@ so agents can discover the packaged skills shipped with this repository.
 
 ## 🏗️ Architecture
 
-Each command is self-contained and receives its dependencies through constructor injection, following the :abbr:`DI` pattern. The ``ProcessBuilder`` and ``ProcessQueue`` classes provide a fluent API for constructing and executing system processes in sequence.
-
-- ``ProcessBuilderInterface`` - Builds process commands with arguments
-- ``ProcessQueueInterface`` - Manages and executes process queues
-- ``FilesystemInterface`` - Abstracts filesystem operations
+- `Composer Plugin` - `FastForward\DevTools\Composer\Plugin` exposes the
+  packaged command set to Composer and runs `dev-tools:sync` after install and
+  update.
+- `DevTools Container` - `FastForward\DevTools\Console\DevTools::create()`
+  builds a shared container from `DevToolsServiceProvider`, which wires
+  process execution, filesystem access, changelog services, Git helpers,
+  diffing, reporting, and template loading.
+- `Lazy Command Loading` - `DevToolsCommandLoader` discovers `#[AsCommand]`
+  classes and resolves most commands only when they are invoked, while
+  orchestration commands such as `standards` dispatch other commands through
+  the console application itself.
+- `Consumer Sync Pipeline` - `dev-tools:sync` refreshes `composer.json`,
+  funding metadata, workflow stubs, repository defaults, git metadata files,
+  packaged Git hooks, and, in normal mode, the wiki submodule plus packaged
+  skills.
 
 ## 🤝 Contributing
 

README.md

@@ -1,9 +1,13 @@
 Command Classes
 ===============
 
-All public CLI commands extend ``Composer\Command\BaseCommand`` and receive
-dependencies through constructor injection. The architecture uses
-``ProcessBuilder`` and ``ProcessQueue`` for fluent process management.
+All public CLI commands extend ``Composer\Command\BaseCommand``. Most command
+classes are resolved lazily through ``DevToolsCommandLoader`` and receive
+their collaborators from the shared ``DevToolsServiceProvider`` container,
+while orchestration commands such as ``standards`` dispatch other commands
+through the console application itself. The architecture also relies on
+``ProcessBuilder`` and ``ProcessQueue`` for fluent process management where
+subprocess execution is needed.
 
 .. list-table::
    :header-rows: 1

docs/api/commands.rst

@@ -10,11 +10,14 @@ Startup Chain
 1. ``bin/dev-tools`` loads ``bin/dev-tools.php``.
 2. ``bin/dev-tools.php`` prefers the consumer project's
    ``vendor/autoload.php`` and falls back to the package autoloader.
-3. ``bin/dev-tools.php`` starts ``FastForward\DevTools\DevTools`` and appends
+3. ``bin/dev-tools.php`` starts ``FastForward\DevTools\Console\DevTools`` and appends
    ``--no-plugins``.
-4. ``FastForward\DevTools\DevTools`` sets ``standards`` as the default command
-   and loads commands from
-   ``FastForward\DevTools\Composer\Capability\DevToolsCommandProvider``.
+4. ``FastForward\DevTools\Console\DevTools::create()`` builds the shared
+   container from ``FastForward\DevTools\ServiceProvider\DevToolsServiceProvider``.
+5. ``FastForward\DevTools\Console\CommandLoader\DevToolsCommandLoader``
+   lazily discovers ``#[AsCommand]`` classes from the command namespace.
+6. ``FastForward\DevTools\Composer\Capability\DevToolsCommandProvider`` later
+   exposes that same command set to Composer.
 
 Composer Plugin Classes
 -----------------------
@@ -29,7 +32,7 @@ Composer Plugin Classes
        Composer install and update.
    * - ``FastForward\DevTools\Composer\Capability\DevToolsCommandProvider``
      - Instantiates and returns the available command classes.
-   * - ``FastForward\DevTools\DevTools``
+   * - ``FastForward\DevTools\Console\DevTools``
      - Console application used by the local binary.
 
 Why ``--no-plugins`` Is Appended

docs/api/composer-integration.rst

@@ -32,15 +32,18 @@ following steps:
    update.
 4. ``dev-tools:sync`` adds or refreshes the ``dev-tools`` and
    ``dev-tools:fix`` scripts in the consumer ``composer.json``.
-5. ``dev-tools:sync`` updates ``extra.grumphp.config-default-path`` and copies
-   missing automation assets such as workflow stubs, ``.editorconfig``, and
-   ``.github/dependabot.yml``.
+5. ``dev-tools:sync`` updates ``extra.grumphp.config-default-path``,
+   synchronizes funding metadata, copies automation assets such as workflow
+   stubs, ``.editorconfig``, and ``.github/dependabot.yml``, and refreshes
+   ``.gitignore``, ``.gitattributes``, the project license, and packaged Git
+   hooks.
 6. If ``.github/wiki`` is missing, ``dev-tools:sync`` adds it as a Git
    submodule that points to the repository wiki.
 7. ``dev-tools:sync`` runs ``gitignore`` to merge canonical ignore rules into
    the consumer project.
 8. ``dev-tools:sync`` runs ``skills`` to create or repair packaged skill links
-   inside ``.agents/skills``.
+   inside ``.agents/skills`` when sync runs in normal mode rather than
+   preview/check mode.
 
 First commands to try
 ---------------------

docs/getting-started/installation.rst

@@ -10,12 +10,15 @@ Local Command Lifecycle
 1. ``bin/dev-tools`` loads ``bin/dev-tools.php``.
 2. ``bin/dev-tools.php`` prefers the consumer ``vendor/autoload.php`` and
    falls back to the package autoloader.
-3. ``FastForward\DevTools\DevTools`` boots the command registry from
-   ``FastForward\DevTools\Composer\Capability\DevToolsCommandProvider``.
-4. ``standards`` is used as the default command when no explicit command name
+3. ``FastForward\DevTools\Console\DevTools::create()`` builds a shared
+   container from ``FastForward\DevTools\ServiceProvider\DevToolsServiceProvider``.
+4. ``FastForward\DevTools\Console\CommandLoader\DevToolsCommandLoader``
+   lazily discovers ``#[AsCommand]`` classes and resolves them from that
+   container.
+5. ``standards`` is used as the default command when no explicit command name
    is given.
-5. Commands receive dependencies through constructor injection from
-   ``DevToolsServiceProvider``.
+6. ``FastForward\DevTools\Composer\Capability\DevToolsCommandProvider`` only
+   adapts the same application command set for Composer plugin integration.
 
 Consumer Synchronization Lifecycle
 ----------------------------------
@@ -26,12 +29,17 @@ Consumer Synchronization Lifecycle
    ``FastForward\DevTools\Composer\Capability\DevToolsCommandProvider``.
 4. After ``composer install`` or ``composer update``, the plugin runs
    ``vendor/bin/dev-tools dev-tools:sync``.
-5. ``FastForward\DevTools\Console\Command\SyncCommand`` updates scripts, GitHub
-   workflow stubs, ``.editorconfig``, ``dependabot.yml``, ``.gitignore``, and
-   the wiki submodule in the consumer repository.
-6. ``FastForward\DevTools\Console\Command\SkillsCommand`` synchronizes packaged skill
-   links into the consumer ``.agents/skills`` directory.
-7. ``FastForward\DevTools\Agent\Skills\SkillsSynchronizer`` creates missing
+5. ``FastForward\DevTools\Console\Command\SyncCommand`` updates
+   ``composer.json`` scripts, funding metadata, workflow stubs,
+   ``.editorconfig``, ``dependabot.yml``, ``.gitignore``,
+   ``.gitattributes``, the project license, and packaged Git hooks.
+6. In normal mode, ``dev-tools:sync`` also runs ``wiki --init`` and
+   ``skills`` to initialize the wiki submodule and synchronize packaged skill
+   links into ``.agents/skills``.
+7. In ``--dry-run``, ``--check``, and ``--interactive`` modes, ``wiki`` and
+   ``skills`` are skipped because they do not yet expose non-destructive
+   verification paths.
+8. ``FastForward\DevTools\Agent\Skills\SkillsSynchronizer`` creates missing
    links, repairs broken ones, and preserves consumer-owned directories.
 
 Documentation Pipeline
@@ -50,21 +58,37 @@ Documentation Pipeline
 Dependency Injection
 --------------------
 
-Commands receive their dependencies through constructor injection provided by
-``DevToolsServiceProvider``.
+``DevToolsServiceProvider`` builds the shared application container used by
+``DevTools::create()``. Most commands receive collaborators through
+constructor injection once resolved by that container, while command discovery
+itself stays lazy through ``DevToolsCommandLoader``.
+
+The provider wires the command runtime by concern rather than by one flat
+command list:
 
 .. list-table::
    :header-rows: 1
 
-   * - Interface
-     - Purpose
+   * - Concern
+     - Services
    * - ``FastForward\DevTools\Process\ProcessBuilderInterface``
-     - Builds process commands with a fluent API for arguments.
-   * - ``FastForward\DevTools\Process\ProcessQueueInterface``
-     - Queues and executes multiple processes in sequence.
-   * - ``FastForward\DevTools\Filesystem\FilesystemInterface``
-     - Abstracts filesystem operations.
-   * - ``FastForward\DevTools\Composer\Json\ComposerJsonInterface``
-     - Reads and validates ``composer.json`` metadata.
-   * - ``Symfony\Component\Config\FileLocatorInterface``
-     - Locates configuration files.
+     - ``ProcessBuilderInterface`` and ``ProcessQueueInterface`` build and
+       execute subprocess pipelines.
+   * - ``Filesystem and metadata``
+     - ``FilesystemInterface``, ``ComposerJsonInterface``, and
+       ``FileLocatorInterface`` resolve local files, project metadata, and
+       packaged resources.
+   * - ``Console bootstrapping``
+     - ``CommandLoaderInterface`` resolves lazy command loading, and
+       ``Composer\Plugin\Capability\CommandProvider`` exposes the same
+       command set to Composer.
+   * - ``Changelog and Git``
+     - The changelog manager, parser, renderer, checker, and
+       ``GitClientInterface`` support changelog authoring, verification, and
+       release-note flows.
+   * - ``Synchronization helpers``
+     - Git ignore, Git attributes, license, resource diffing, and coverage
+       summary services support consumer sync and reporting workflows.
+   * - ``Shared infrastructure``
+     - ``LoggerInterface``, ``ClockInterface``, and Twig's
+       ``LoaderInterface`` provide reusable runtime infrastructure.

docs/internals/architecture.rst

@@ -25,13 +25,13 @@ What the Command Changes
      - Updated in place.
    * - ``.github/workflows/*.yml``
      - Copies stub workflows from ``resources/github-actions``.
-     - Only when missing.
+     - Only when missing by default; replaceable with ``--overwrite``.
    * - ``.editorconfig``
      - Copies the packaged file from the repository root.
-     - Only when missing.
+     - Only when missing by default; replaceable with ``--overwrite``.
    * - ``.github/dependabot.yml``
      - Copies the packaged Dependabot template.
-     - Only when missing.
+     - Only when missing by default; replaceable with ``--overwrite``.
    * - ``.agents/skills/<skill-name>``
      - Creates or repairs symlinks to packaged agent skills.
      - Creates missing links, repairs broken symlinks, and preserves existing
@@ -61,7 +61,8 @@ What It Needs
 .. important::
 
    Workflow stubs, ``.editorconfig``, and ``dependabot.yml`` are copied only
-   when the target file does not already exist. This protects
-   consumer-specific customizations. The ``skills`` phase follows the same
-   spirit by preserving existing non-symlink directories inside
-   ``.agents/skills``.
+   when the target file does not already exist unless ``--overwrite`` is used.
+   This protects consumer-specific customizations by default while still
+   allowing explicit replacement during shared automation updates. The
+   ``skills`` phase follows the same spirit by preserving existing
+   non-symlink directories inside ``.agents/skills``.