Refresh README and testing docs

Author: coisa

README.md

@@ -35,6 +35,8 @@ across Fast Forward libraries.
 - Synchronizes packaged skills and project-agent prompts into consumer
   `.agents/skills` and `.agents/agents` directories using safe link-based
   updates
+- Supports guide-only and automation-only repositories by skipping PHPUnit or
+  wiki generation gracefully when no runnable PHP surface exists
 - Works both as a Composer plugin and as a local binary
 - Preserves local overrides through consumer-first configuration resolution
 
@@ -71,6 +73,8 @@ You can also run individual commands for specific development tasks:
 ```bash
 # Run PHPUnit tests
 composer dev-tools tests
+composer dev-tools tests --json
+composer dev-tools tests --pretty-json
 
 # Analyze missing, unused, misplaced, and outdated Composer dependencies
 composer dependencies
@@ -120,6 +124,7 @@ composer phpdoc
 
 # Generate HTML API documentation using phpDocumentor
 composer docs
+composer docs --source=docs/user-guide
 
 # Generate Markdown documentation for the wiki
 composer wiki
@@ -180,6 +185,14 @@ The `metrics` command ships with `phpmetrics/phpmetrics` as a direct
 dependency of `fast-forward/dev-tools`, so consumer repositories can generate
 metrics reports without extra setup.
 
+Guide-only repositories and workflow-only repositories can still use the
+packaged command surface. When no runnable PHPUnit surface exists, `tests`
+returns a controlled warning instead of failing. When a repository ships
+guides without PSR-4 source paths, `docs` builds the guide site without trying
+to synthesize API pages. When `.github/wiki` is absent and no wiki has been
+initialized yet, `wiki` now skips generation with a warning instead of failing
+the whole automation run.
+
 The changelog commands manage Keep a Changelog 1.1.0 files without requiring
 extra tooling in the consumer repository. `changelog:entry` bootstraps a
 missing changelog file on first use, `changelog:check` enforces meaningful
@@ -215,6 +228,14 @@ takes precedence over terminal-only color. Where orchestrated tools can expose
 structured subprocess results safely, DevTools prefers adding stable fields to
 the JSON context rather than coloring otherwise strict JSON output.
 
+For the `tests` command, structured runs now capture the bundled PHPUnit
+agent-reporter payload inside `context.output` while preserving the normal
+DevTools JSON envelope. That means the top-level command still emits one final
+document, and consumers can inspect stable nested keys such as
+`context.output.result`, `context.output.summary`, optional
+`context.output.details`, and `context.output.coverage` when minimum-coverage
+validation is active.
+
 Progress output is disabled by default on the commands that support transient
 rendering, and `--progress` re-enables it for human-readable terminal runs.
 When `--json` or `--pretty-json` is active on commands that orchestrate other

docs/advanced/phpunit-extension.rst

@@ -19,6 +19,9 @@ Runtime Chain
    builds a summary notification and sends it when the run finishes.
 5. ``Ergebnis\PHPUnit\AgentReporter\Extension`` replaces PHPUnit's normal
    output with a compact JSON report when an agent runtime is detected.
+6. In structured DevTools runs, ``tests`` forces the same reporter path for
+   the PHPUnit subprocess so the final nested payload remains deterministic
+   even when the surrounding process would not naturally look agent-driven.
 
 Why This Helps Consumer Projects
 --------------------------------
@@ -29,6 +32,8 @@ Why This Helps Consumer Projects
   scrollback;
 - agent-driven runs consume far less terminal context while still keeping
   failure details and PHPUnit exit semantics intact;
+- DevTools can preserve a single top-level JSON document while nesting the
+  compact PHPUnit summary under ``context.output`` for bot-friendly parsing;
 - event counts are available to the notification layer without adding ad-hoc
   test code.
 

docs/commands/docs.rst

@@ -103,9 +103,14 @@ Exit Codes
 Behavior
 ---------
 
-- ``docs/`` must exist unless you pass another ``--source`` directory.
+- The default ``docs`` source directory is optional. When it is absent, the
+  command still generates API pages if PSR-4 source paths are available.
+- A custom explicit ``--source`` path must exist; otherwise the command fails
+  fast.
 - API pages are built from the PSR-4 paths declared in ``composer.json``.
 - Guide pages are built from the selected source directory.
+- Repositories without PSR-4 source paths can still generate a guides-only
+  site from the selected source directory.
 - Cache stays enabled by default; omit both flags to keep the command default,
   pass ``--cache`` to force it on, and pass ``--no-cache`` to force it off.
 - When ``--cache-dir`` is omitted, phpDocumentor keeps its default cache

docs/commands/reports.rst

@@ -123,6 +123,9 @@ Behavior
 - When ``--json`` or ``--pretty-json`` is active, it forwards JSON mode to the
   ``docs``, ``tests``, and ``metrics`` subprocesses and suppresses transient
   progress output where those tools support it.
+- Nested ``docs`` and ``tests`` stages can now skip gracefully with warnings in
+  guide-only or automation-only repositories, while ``reports`` still returns a
+  successful aggregate result for the stages that were actually generated.
 - Passes ``--junit <coverage>/junit.xml`` to the metrics step.
 - Used by the ``standards`` command as the final phase.
 - This is the reporting stage used by GitHub Pages.

docs/commands/tests.rst

@@ -113,6 +113,13 @@ Run with minimum coverage enforcement:
 
    composer tests --min-coverage=80
 
+Run with structured JSON output:
+
+.. code-block:: bash
+
+   composer tests --json
+   composer tests --pretty-json
+
 Run without cache:
 
 .. code-block:: bash
@@ -150,6 +157,10 @@ Behavior
 ---------
 
 - Local ``phpunit.xml`` is preferred over the packaged default.
+- When the default ``tests`` path is absent and the project exposes no
+  testable PHP source files, the command exits successfully with a warning
+  instead of failing the whole automation flow.
+- A custom explicit tests path that does not exist still fails fast.
 - Coverage filters are automatically applied to all PSR-4 paths from composer.json.
 - Multiple coverage formats are generated: HTML, Testdox HTML, Clover XML, and PHP.
 - Cache stays enabled by default; omit both flags to keep the command default,
@@ -167,6 +178,9 @@ Behavior
   command stores that payload inside ``output`` while keeping the standard
   DevTools JSON envelope. ``--json`` and ``--pretty-json`` therefore expose
   the same structured result, with formatting as the only difference.
+- the command forces the bundled PHPUnit agent-reporter extension for
+  structured runs so the nested payload stays compact and stable even when the
+  surrounding runtime would not normally look like an agent.
 - in structured mode, the command suppresses intermediary ``Running...`` log
   records so the output stream contains a single final JSON document.
 - when structured capture is active but PHPUnit does not emit parseable JSON,

docs/commands/wiki.rst

@@ -90,6 +90,10 @@ Behavior
 ---------
 
 - Default output directory is ``.github/wiki``.
+- When the default target does not exist yet and ``--init`` is not requested,
+  the command skips with a controlled warning instead of failing.
+- Repositories without PHP API surface also skip wiki generation with a
+  warning, because the current wiki renderer only emits API pages.
 - Cache stays enabled by default; omit both flags to keep the command default,
   pass ``--cache`` to force it on, and pass ``--no-cache`` to force it off.
 - When ``--cache-dir`` is omitted, phpDocumentor keeps its default cache

docs/getting-started/quickstart.rst

@@ -4,16 +4,16 @@ Quickstart
 This walkthrough is the fastest way to get a new library into a healthy state.
 
 1. Install the package.
-2. Create a minimal guide directory.
+2. Create a guide directory if the repository will publish guides.
 3. Synchronize shared automation, packaged skills, and packaged agents.
 4. Run the focused commands once.
 5. Run the full suite before opening a pull request.
 
-Create the Minimum Guide
-------------------------
+Optional Guide Setup
+--------------------
 
-The ``docs`` command fails early when ``docs/`` does not exist. A tiny
-starting page is enough for the first successful run.
+If the repository will publish guides, a tiny starting page is enough for the
+first successful ``docs`` run.
 
 Create the directory:
 
@@ -30,10 +30,14 @@ Create ``docs/index.rst`` with content such as:
 
    Welcome to the project documentation.
 
+Repositories that only ship PHP code can skip this step and still generate API
+documentation. Repositories that only ship guides can also use the same
+``docs`` command even without PSR-4 source paths.
+
 Run the First Commands
 ----------------------
 
-Once the package is installed and the guide directory exists, run:
+Once the package is installed, run:
 
 .. code-block:: bash
 
@@ -57,9 +61,11 @@ What Each Command Proves
   safely into ``.agents/agents`` without copying files into the consumer
   repository.
 - ``composer tests`` proves the packaged or local PHPUnit
-  configuration can execute the current test suite.
+  configuration can execute the current test suite, or skip gracefully when
+  the repository intentionally has no runnable PHPUnit surface yet.
 - ``composer docs`` proves the PSR-4 source paths and the guide
-  directory are usable by phpDocumentor.
+  directory are usable by phpDocumentor, whichever of those surfaces the
+  repository actually provides.
 - ``composer dev-tools`` proves the complete pipeline can run in the expected
   order.
 

docs/usage/testing-and-coverage.rst

@@ -17,6 +17,8 @@ When you run ``tests``, DevTools:
   explicit force-off flag for the current run;
 - uses the selected workspace ``cache/phpunit`` directory only when caching
   stays enabled;
+- skips the command with a warning when the repository has no default
+  ``tests`` directory and no testable PHP source surface;
 - can generate HTML coverage, Testdox, Clover, and raw PHP coverage output
   when ``--coverage`` is provided.
 
@@ -29,6 +31,8 @@ Useful Examples
    composer tests -- --filter=PluginTest
    composer tests --coverage=.dev-tools/coverage
    composer tests --no-cache --bootstrap=tests/bootstrap.php
+   composer tests --json
+   composer tests --pretty-json
 
 Coverage Outputs
 ----------------
@@ -59,6 +63,10 @@ The packaged ``phpunit.xml`` registers:
   default verbose terminal output with a compact JSON summary when an agent
   runtime is detected.
 
+When ``tests`` itself runs in structured mode, DevTools also forces the
+reporter path for the PHPUnit subprocess so the nested payload remains compact
+and parseable for bots and agent workflows.
+
 Programmatic Coverage Access
 -----------------------------
 
@@ -83,7 +91,10 @@ When to Override Locally
 
 Create your own ``phpunit.xml`` in the consumer project when you need a
 different bootstrap file, extra extensions, or alternative strictness flags.
-DevTools will prefer the local file automatically.
+DevTools will prefer the local file automatically, but consumer projects that
+replace the packaged configuration must re-register both bundled extensions if
+they still want desktop notifications, BypassFinals support, and compact
+agent-oriented JSON output.
 
 .. note::