[docs] Add troubleshooting guide (#71) (#79)

* Add troubleshooting guide

* Update wiki submodule pointer for PR #79

* Update wiki pointer

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

* Update wiki submodule pointer for PR #79

---------

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/wiki

@@ -24,4 +24,5 @@ fit together.
    api/index
    internals/index
    links/index
+   troubleshooting
    faq

docs/index.rst

@@ -0,0 +1,238 @@
+Troubleshooting
+===============
+
+Use this page when ``fast-forward/dev-tools`` fails locally or in GitHub
+Actions. Each entry starts with the visible symptom, then lists likely causes
+and safe recovery steps.
+
+Composer Install or Authentication Failures
+-------------------------------------------
+
+Scope: local and CI.
+
+Symptoms:
+
+- ``composer install`` cannot download a private package;
+- GitHub Actions reports an authentication or rate-limit error;
+- Composer asks for credentials in a non-interactive job.
+
+Likely causes:
+
+- the repository is missing ``COMPOSER_AUTH`` or a GitHub token secret;
+- the token does not have access to a private dependency;
+- Composer is trying to prompt in CI.
+
+Recovery:
+
+.. code-block:: bash
+
+    composer diagnose
+    composer install -vvv
+
+In CI, check that the workflow receives the expected secrets and that private
+repositories are available to the token used by Composer. Prefer repository or
+organization secrets over hard-coded credentials.
+
+Missing ``vendor/`` or Lock-File Mismatch
+-----------------------------------------
+
+Scope: local and CI.
+
+Symptoms:
+
+- ``composer dev-tools`` fails because a binary is missing;
+- CI installs a dependency set that differs from the local machine;
+- Composer reports that ``composer.lock`` is not compatible with
+  ``composer.json``.
+
+Likely causes:
+
+- ``vendor/`` was deleted or was created with a different PHP version;
+- ``composer.json`` changed without updating ``composer.lock``;
+- the local PHP version does not match the repository constraint.
+
+Recovery:
+
+.. code-block:: bash
+
+    php -v
+    composer validate
+    composer install
+
+If Composer reports a lock mismatch, update the lock file intentionally and
+review the dependency diff:
+
+.. code-block:: bash
+
+    composer update --lock
+    git diff composer.lock
+
+Branch Protection or Bot Commit Blocks
+--------------------------------------
+
+Scope: GitHub Actions.
+
+Symptoms:
+
+- a wiki or reports preview job cannot push generated updates;
+- GitHub rejects a bot commit with a protected-branch error;
+- a pull request is mergeable locally but blocked after the preview job runs.
+
+Likely causes:
+
+- ``main`` is protected and the workflow tried to push there directly;
+- the workflow token cannot update pull request branches;
+- required status checks were changed after the pull request opened.
+
+Recovery:
+
+- confirm that preview jobs write to pull request branches or PR-specific
+  preview locations;
+- keep final publishing jobs tied to merges into ``main``;
+- allow workflow-generated commits on pull request branches when the repository
+  relies on generated wiki pointers;
+- rerun the workflow after branch protection settings are corrected.
+
+``.github/wiki`` Submodule Pointer Conflicts
+--------------------------------------------
+
+Scope: local and CI.
+
+Symptoms:
+
+- Git reports a conflict on ``.github/wiki``;
+- a pull request contains an unexpected submodule pointer change;
+- the wiki preview branch exists, but the parent repository points elsewhere.
+
+Likely causes:
+
+- ``main`` moved while the pull request had a generated wiki pointer;
+- the preview workflow produced a newer wiki commit;
+- the local submodule is stale.
+
+Recovery for pull request ``123``:
+
+.. code-block:: bash
+
+    git fetch origin main
+    git rebase origin/main
+    git -C .github/wiki fetch origin master pr-123
+    git -C .github/wiki switch --detach origin/pr-123
+    git add .github/wiki
+    git rebase --continue
+    git push --force-with-lease
+
+If the preview branch no longer exists, regenerate the wiki preview before
+choosing a pointer.
+
+No-TTY Process Errors
+---------------------
+
+Scope: local scripts and CI.
+
+Symptoms:
+
+- a process fails with ``/dev/tty`` errors;
+- a command works in an interactive terminal but fails in GitHub Actions;
+- Composer or a wrapped tool waits for input forever.
+
+Likely causes:
+
+- a command expects an interactive terminal;
+- a tool is prompting for confirmation;
+- CI is missing required environment variables.
+
+Recovery:
+
+.. code-block:: bash
+
+    composer dev-tools -- --no-interaction
+
+When calling lower-level tools directly, use their non-interactive flags and
+provide required values through environment variables or workflow inputs.
+
+Coverage Threshold Failures
+---------------------------
+
+Scope: local and CI.
+
+Symptoms:
+
+- PHPUnit passes tests but fails the job because coverage is too low;
+- a new class or branch is missing coverage metadata;
+- coverage reports differ between local and CI runs.
+
+Likely causes:
+
+- new behavior was added without tests;
+- Xdebug or PCOV is not enabled consistently;
+- coverage configuration changed in ``phpunit.xml``.
+
+Recovery:
+
+.. code-block:: bash
+
+    composer dev-tools tests
+    composer dev-tools tests -- --coverage=public/coverage
+
+Add focused tests for the changed behavior before lowering thresholds. If local
+coverage differs from CI, compare PHP, Xdebug or PCOV, and PHPUnit versions.
+
+PHPDoc or Template Generation Issues
+------------------------------------
+
+Scope: local and CI.
+
+Symptoms:
+
+- ``composer dev-tools docs`` fails during API documentation generation;
+- generated docs are missing classes or links;
+- PHPDoc validation fails after a source change.
+
+Likely causes:
+
+- a class is missing required PHPDoc metadata;
+- a docblock references a renamed class or method;
+- templates or generated output from an older run are stale.
+
+Recovery:
+
+.. code-block:: bash
+
+    composer dev-tools phpdoc
+    composer dev-tools docs
+
+Fix source PHPDoc first, then regenerate docs. Avoid editing generated API
+output directly; it should reflect source files and templates.
+
+Reports or Wiki Preview Cleanup Issues
+--------------------------------------
+
+Scope: GitHub Actions.
+
+Symptoms:
+
+- closed pull requests still show old report preview links;
+- a wiki preview branch remains after merge or close;
+- a PR comment points to a missing preview.
+
+Likely causes:
+
+- the cleanup workflow did not run on the pull request close event;
+- the workflow token lacks permission to update Pages or the wiki repository;
+- a preview was removed after the comment was posted.
+
+Recovery:
+
+- rerun the cleanup workflow for the closed pull request when available;
+- remove stale preview directories or branches only after confirming the pull
+  request is closed or merged;
+- check the reports and wiki workflow logs before deleting artifacts manually.
+
+Related References
+------------------
+
+- :doc:`usage/github-actions`
+- :doc:`usage/documentation-workflows`
+- :doc:`usage/syncing-consumer-projects`
+- :doc:`running/index`