docs: update integration guide and troubleshooting sections for clarity and organization

TerrorSquad · TerrorSquad · commit 82009696bb6e · 2026-01-02T02:58:14.000+01:00
diff --git a/docs/.data/content/contents.sqlite b/docs/.data/content/contents.sqlite
diff --git a/docs/content/1.integration_guide/integration_guide.md b/docs/content/1.integration_guide/integration_guide.md
@@ -37,13 +37,11 @@ Follow these steps to integrate the PHP Development Booster into your existing P
 
 ::tip
 The integration script includes an **Interactive Mode** (`-I`) that guides you through the setup process with a wizard. This is useful for customizing the integration (selecting specific tools, configuring ticket IDs, etc.).
-::
-
-### Usage
 
 ```bash [Terminal]
 curl -sSL https://raw.githubusercontent.com/TerrorSquad/php-booster/main/booster/integrate_booster.sh | bash -s -- -I
 ```
+::
 
 ### Configuration Steps
 
diff --git a/docs/content/3.tools/8.github_actions.md b/docs/content/3.tools/8.github_actions.md
@@ -52,6 +52,7 @@ We include GitHub Actions that automatically apply code style fixes (ECS) and re
 To skip auto-fix for specific commits, include `[skip auto-fix]` in your commit message.
 ::
 
+### Security & Safety
 
 - Uses `GITHUB_TOKEN` with minimal required permissions
 - Only processes files changed in the current commit/PR
@@ -95,20 +96,25 @@ This creates a comprehensive code quality pipeline from development to productio
 
 ## Troubleshooting
 
-### Action Not Running
-- Verify PHP files were actually changed
-- Check workflow triggers match your branch names
-- Ensure [rector.php](https://github.com/TerrorSquad/php-booster/blob/main/booster/rector.php) and [ecs.php](https://github.com/TerrorSquad/php-booster/blob/main/booster/ecs.php) exist
+::accordion
+  ::item{label="Action Not Running"}
+  - Verify PHP files were actually changed
+  - Check workflow triggers match your branch names
+  - Ensure [rector.php](https://github.com/TerrorSquad/php-booster/blob/main/booster/rector.php) and [ecs.php](https://github.com/TerrorSquad/php-booster/blob/main/booster/ecs.php) exist
+  ::
 
-### No Changes Applied
-- Confirm Rector and ECS are installed via Composer
-- Validate configuration files are correct
-- Check action logs for specific error messages
+  ::item{label="No Changes Applied"}
+  - Confirm Rector and ECS are installed via Composer
+  - Validate configuration files are correct
+  - Check action logs for specific error messages
+  ::
 
-### Permission Issues
-- Ensure repository has Actions enabled
-- Verify `GITHUB_TOKEN` has write permissions
-- For protected branches, consider using a personal access token
+  ::item{label="Permission Issues"}
+  - Ensure repository has Actions enabled
+  - Verify `GITHUB_TOKEN` has write permissions
+  - For protected branches, consider using a personal access token
+  ::
+::
 
 ## Examples
 
diff --git a/docs/content/4.troubleshooting/1.troubleshooting.md b/docs/content/4.troubleshooting/1.troubleshooting.md
@@ -7,150 +7,161 @@ navigation:
 
 ## Integration Issues
 
-### Script Fails
-*   **Missing Dependencies**: Ensure `curl` is installed and DDEV is running (`ddev status`).
-*   **Verbose Mode**: Run the script with `-v` for details.
-
-### Files Not Created
-*   Run from project root.
-*   Check write permissions.
-
-### Permission Errors
-```bash [Terminal]
-chmod +x .husky/shared/runner.sh
-ddev restart
-```
-
-## Git Hooks Issues
-
-### `pre-commit` Hook Fails
-**"Could not open input file"**: Usually a DDEV path issue.
+::accordion
+  ::item{label="Script Fails"}
+  *   **Missing Dependencies**: Ensure `curl` is installed and DDEV is running (`ddev status`).
+  *   **Verbose Mode**: Run the script with `-v` for details.
+  ::
 
-::steps
-  ### Check Paths
-  Check `.husky/pre-commit` paths.
+  ::item{label="Files Not Created"}
+  *   Run from project root.
+  *   Check write permissions.
+  ::
 
-  ### Restart DDEV
-  Restart DDEV: `ddev restart`.
+  ::item{label="Permission Errors"}
+  If you encounter permission errors with the hooks:
+  ```bash [Terminal]
+  chmod +x .husky/shared/runner.sh
+  ddev restart
+  ```
+  ::
 ::
 
+## Git Hooks Issues
 
-### Branch Name Validation Fails
-*   Check config: [validate-branch-name.config.cjs](https://github.com/TerrorSquad/php-booster/blob/main/booster/validate-branch-name.config.cjs).
-*   Test manually: `node_modules/.bin/validate-branch-name -t "feature/PRJ-123-test"`.
-
-### Commit Message Rejected
-*   Use Conventional Commits: `type(scope): description`.
-*   Example: `feat: add login`.
-
-## Tool Integration Issues
+::accordion
+  ::item{label="pre-commit Hook Fails"}
+  **"Could not open input file"**: Usually a DDEV path issue.
 
-### Composer Scripts Fail
-*   Verify installation: `composer show`.
-*   Use DDEV prefix: `ddev composer ecs`.
-*   Check `composer.json` scripts.
+  1. **Check Paths**: Check `.husky/pre-commit` paths.
+  2. **Restart DDEV**: `ddev restart`.
+  ::
 
-### Path Issues (ECS/PHPStan)
+  ::item{label="Branch Name Validation Fails"}
+  *   Check config: [validate-branch-name.config.cjs](https://github.com/TerrorSquad/php-booster/blob/main/booster/validate-branch-name.config.cjs).
+  *   Test manually: `node_modules/.bin/validate-branch-name -t "feature/PRJ-123-test"`.
+  ::
 
-::note
-**DDEV**: Ensure paths in [ecs.php](https://github.com/TerrorSquad/php-booster/blob/main/booster/ecs.php) or `phpstan.neon` are relative to project root, not absolute host paths.
+  ::item{label="Commit Message Rejected"}
+  *   Use Conventional Commits: `type(scope): description`.
+  *   Example: `feat: add login`.
+  ::
 ::
 
-::steps
-  ### Use the runner script
-
-  ::code-group
-    ```bash [Recommended]
-    # Use composer scripts
-    ddev composer ecs
-    ```
+## Tool Integration Issues
 
-    ```bash [Manual]
-    # Instead of direct tool calls
-    bash tools/runner.sh vendor/bin/ecs check src/
-    ```
+::accordion
+  ::item{label="Composer Scripts Fail"}
+  *   Verify installation: `composer show`.
+  *   Use DDEV prefix: `ddev composer ecs`.
+  *   Check `composer.json` scripts.
   ::
 
-  ### Check tool configurations have correct paths
-  ```bash [Terminal]
-  # Check ECS config
-  cat ecs.php
-  
-  # Check PHPStan config  
-  cat [phpstan.neon.dist](https://github.com/TerrorSquad/php-booster/blob/main/booster/phpstan.neon.dist)
-  ```
+  ::item{label="Path Issues (ECS/PHPStan)"}
+  :::note
+  **DDEV**: Ensure paths in [ecs.php](https://github.com/TerrorSquad/php-booster/blob/main/booster/ecs.php) or `phpstan.neon` are relative to project root, not absolute host paths.
+  :::
+
+  1. **Use the runner script**
+     ::code-group
+       ```bash [Recommended]
+       # Use composer scripts
+       ddev composer ecs
+       ```
+
+       ```bash [Manual]
+       # Instead of direct tool calls
+       bash tools/runner.sh vendor/bin/ecs check src/
+       ```
+     ::
+
+  2. **Check tool configurations have correct paths**
+     ```bash [Terminal]
+     # Check ECS config
+     cat ecs.php
+     
+     # Check PHPStan config  
+     cat [phpstan.neon.dist](https://github.com/TerrorSquad/php-booster/blob/main/booster/phpstan.neon.dist)
+     ```
+  ::
 ::
 
 ## DDEV Issues
 
-### Container Not Starting
-
-**Problem**: DDEV containers fail to start or show errors.
+::accordion
+  ::item{label="Container Not Starting"}
+  **Problem**: DDEV containers fail to start or show errors.
 
-**Solution**:
+  **Solution**:
 
-::steps
-  ### Check DDEV status and logs
-  ```bash [Terminal]
-  ddev status
-  ddev logs
-  ```
-
-  ### Restart DDEV
-  ```bash [Terminal]
-  ddev restart
-  ```
-
-  ### If containers are corrupted, recreate
-  ```bash [Terminal]
-  ddev delete -y
-  ddev start
-  ```
-::
-
-### Performance Issues
-
-**Problem**: DDEV is slow or unresponsive.
+  1. **Check DDEV status and logs**
+     ```bash [Terminal]
+     ddev status
+     ddev logs
+     ```
 
-**Solution**:
+  2. **Restart DDEV**
+     ```bash [Terminal]
+     ddev restart
+     ```
 
-::steps
-  ### Configure Mutagen
-  Configure Mutagen for better file sync performance (especially on macOS):
-  ```bash [Terminal]
-  ddev config --mutagen-enabled
-  ddev restart
-  ```
+  3. **If containers are corrupted, recreate**
+     ```bash [Terminal]
+     ddev delete -y
+     ddev start
+     ```
+  ::
 
-  ### Exclude Directories
-  Exclude unnecessary directories from sync:
-  ```yaml
-  # In .ddev/config.yaml
-  upload_dirs:
-    - storage/app/uploads
-  ```
+  ::item{label="Performance Issues"}
+  **Problem**: DDEV is slow or unresponsive.
+
+  **Solution**:
+
+  1. **Configure Mutagen**
+     Configure Mutagen for better file sync performance (especially on macOS):
+     ```bash [Terminal]
+     ddev config --mutagen-enabled
+     ddev restart
+     ```
+
+  2. **Exclude Directories**
+     Exclude unnecessary directories from sync:
+     ```yaml
+     # In .ddev/config.yaml
+     upload_dirs:
+       - storage/app/uploads
+     ```
+  ::
 ::
 
 ## Testing Issues
 
-### Integration Tests Fail
-*   **Check Env**: `./tools/internal-test/test-integration.py env-check`
-*   **Clean**: `./tools/internal-test/test-integration.py clean`
-*   **Isolate**: Run `setup` or `integrate` steps individually.
+::accordion
+  ::item{label="Integration Tests Fail"}
+  *   **Check Env**: `./tools/internal-test/test-integration.py env-check`
+  *   **Clean**: `./tools/internal-test/test-integration.py clean`
+  *   **Isolate**: Run `setup` or `integrate` steps individually.
+  ::
 
-### Cleanup
-*   **Manual**: `ddev delete -y` inside test project folders.
-*   **Docker**: `docker system prune -f`.
+  ::item{label="Cleanup"}
+  *   **Manual**: `ddev delete -y` inside test project folders.
+  *   **Docker**: `docker system prune -f`.
+  ::
+::
 
 ## IDE Issues
 
-### VS Code
-*   **Extensions**: Ensure recommended extensions are installed (`code --list-extensions`).
-*   **Settings**: Check `.vscode/settings.json`.
+::accordion
+  ::item{label="VS Code"}
+  *   **Extensions**: Ensure recommended extensions are installed (`code --list-extensions`).
+  *   **Settings**: Check `.vscode/settings.json`.
+  ::
 
-### PHPStorm
-*   **Plugin**: Install DDEV Integration plugin.
-*   **Interpreter**: Configure PHP interpreter to use DDEV.
+  ::item{label="PHPStorm"}
+  *   **Plugin**: Install DDEV Integration plugin.
+  *   **Interpreter**: Configure PHP interpreter to use DDEV.
+  ::
+::
 
 ## Getting Help
 
