[Documentation] Adding troubleshooting sections for WP-CLI database connections (#2333)

## Motivation for the change, related issues

Issue #2332 identified a scenario where additional steps are required to
mount WP-CLI with a mounted playground. This pull request adds a guide
for the user to run `WP-CLI` command successfully with WordPress
Playground.

## Implementation details

- Adds a new troubleshooting section to
/blueprints/troubleshoot-and-debug detailing how to resolve "Error
establishing a database connection".
- Includes a corresponding Blueprint example in /blueprints/examples for
quick reference.

## Testing Instructions (or ideally a Blueprint)

- Download the branch `adding-blueprints-tips`.
- Install the node dependencies.
- Run the documentation `npm run dev:docs`

---------

Co-authored-by: Bero <[email protected]>
Co-authored-by: Adam Zieliński <[email protected]>

Author: 3 people

packages/docs/site/docs/blueprints/08-examples.md

@@ -86,6 +86,24 @@ blueprint={{
 		]
 }} />
 
+## How to work with WP-CLI from the terminal and Playground
+
+You can run WP-CLI commands on a Playground instance either from your terminal or directly within a Blueprint.
+
+To use your terminal, you must first mount the `/wordpress/` directory and ensure the SQLite database integration is configured. This is because Playground's internal database doesn't persist on a mounted site, so you must explicitly install the database plugin via a Blueprint. This allows WP-CLI to recognize the WordPress installation and connect to its database.
+
+:::note
+If you run WP-CLI commands as steps within your Blueprint file, this manual setup is not needed.
+:::
+
+The following Blueprint snippet handles this setup:
+
+<BlueprintExample blueprint={{
+    "plugins": [ "sqlite-database-integration" ]
+}} />
+
+For a detailed explanation of why this is needed, refer to the [Troubleshoot and Debug Blueprints](/blueprints/troubleshoot-and-debug#wp-cli-error-establishing-a-database-connection-on-mounted-sites) section.
+
 ## Showcase a product demo
 
 <BlueprintExample noButton blueprint={{

packages/docs/site/docs/blueprints/09-troubleshoot-and-debug-blueprints.md

@@ -11,7 +11,36 @@ When you build Blueprints, you might run into issues. Here are tips and tools to
 ## Review Common gotchas
 
 -   Require `wp-load`: to run a WordPress PHP function using the `runPHP` step, you’d need to require [wp-load.php](https://github.com/WordPress/WordPress/blob/master/wp-load.php). So, the value of the `code` key should start with `"<?php require_once('wordpress/wp-load.php'); REST_OF_YOUR_CODE"`.
--   Enable `networking`: to access wp.org assets (themes, plugins, blocks, or patterns), or load a stylesheet using [add_editor_style()](https://developer.wordpress.org/reference/functions/add_editor_style/) (say, when [creating a custom block style](https://developer.wordpress.org/news/2023/02/creating-custom-block-styles-in-wordpress-themes)), you’d need to enable the `networking` option: `"features": {"networking": true}`.
+
+## Common Issues and Solutions
+
+### WP-CLI: Error Establishing a Database Connection on Mounted Sites
+
+When using `wp-cli` with a mounted Playground site (e.g., via `--mount-before-install`), you might encounter an "Error establishing a database connection." This happens because WordPress Playground loads the SQLite database integration plugin from its internal files by default, not from the mounted directory, meaning it's not persisted for external `wp-cli` calls.
+
+To resolve this, you need to explicitly install and configure the SQLite database integration plugin within your Blueprint.
+
+**Solution:** Add the following steps to your Blueprint:
+
+```json
+{
+	"plugins": [ "sqlite-database-integration" ]
+}
+```
+
+**Example Usage:**
+
+To test this locally, combine the Blueprint with your Playground CLI command:
+
+```bash
+mkdir wordpress
+# Ensure your blueprint with the above steps is saved as, for example, './blueprint.json'
+npx @wp-playground/cli server --mount-before-install=wordpress:/wordpress --blueprint=./blueprint.json
+cd wordpress
+wp post list
+```
+
+This will ensure the SQLite plugin is installed correctly and configured within your mounted WordPress site, allowing `wp-cli` commands to function correctly.
 
 ## Blueprints Builder
 
@@ -46,7 +75,7 @@ Full list of methods we can use is available [here](/api/client/interface/Playgr
 
 ## Check for errors in the browser console
 
-If your Blueprint isn’t running as expected, open the browser developer tools to see if there are any errors.
+If your Blueprint isn’t running as expected, open the browser developer tools to check for any errors.
 
 To open the developer tools in Chrome, Firefox, Safari\*, and Edge: press `Ctrl + Shift + I` on Windows/Linux or `Cmd + Option + I` on macOS.