feat(stack-management): add scan stacks folder button (#332)

* feat(stack-management): add scan stacks folder button to detect manually-placed compose files

Users who place Docker Compose files directly into the stacks directory
(via SCP, file manager, etc.) can now click the folder-search icon next
to "Create Stack" to immediately discover and surface those stacks in
the sidebar without a full page reload.

* docs(troubleshooting): add scan stacks folder troubleshooting section

Covers common issues: compose file not in subdirectory, unrecognized
filenames, empty directories, and already-tracked stacks.

docs/features/stack-management.mdx

@@ -75,6 +75,24 @@ Right-click or use the **⋮** button on any stack in the sidebar to access:
 - **Update** - pull latest images and recreate containers
 - **Delete** - stop and remove the stack (admin only)
 
+## Scanning for stacks
+
+If you place Docker Compose files directly into the stacks directory (for example, via `scp`, a file manager, or the command line), you can import them without going through the full "Create Stack" flow.
+
+Click the **folder-search icon** next to the "Create Stack" button in the sidebar. Sencho scans the configured stacks directory and reports what it finds:
+
+<Frame>
+  <img src="/images/stack-scanning/scan-button-sidebar.png" alt="Scan stacks folder button in the sidebar" />
+</Frame>
+
+- **New stacks detected** — a success notification lists the newly discovered stack names, and they appear immediately in the sidebar
+- **Stacks removed from disk** — an informational notification lists stacks that are no longer present in the directory
+- **No changes** — a notification confirms no new stacks were found
+
+<Tip>
+  Any subdirectory inside your `COMPOSE_DIR` that contains a `compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml` file is recognized as a valid stack.
+</Tip>
+
 ## Converting a `docker run` command
 
 If you have an existing `docker run` command and want to turn it into a Compose stack, go to the **Home** tab and paste it into the "Convert Docker Run to Compose" field. Sencho converts it to YAML that you can save as a new stack.

docs/operations/troubleshooting.mdx

@@ -159,6 +159,28 @@ DELETE FROM global_settings WHERE key IN ('auth_username', 'auth_password_hash',
 
 ---
 
+## Scan stacks folder doesn't find my stacks
+
+**Symptom:** You placed Docker Compose files in the stacks directory and clicked the scan button, but "No new stacks found" appears.
+
+**Checks in order:**
+
+1. **Is the compose file in a subdirectory?** Sencho only discovers stacks inside subdirectories of `COMPOSE_DIR`. A loose `compose.yaml` sitting directly in the root of `COMPOSE_DIR` is ignored — each stack must be in its own folder (e.g. `COMPOSE_DIR/my-app/compose.yaml`).
+
+2. **Is the compose file named correctly?** Sencho recognizes these filenames only:
+   - `compose.yaml`
+   - `compose.yml`
+   - `docker-compose.yaml`
+   - `docker-compose.yml`
+
+   Other names (e.g. `docker-compose.prod.yaml`, `stack.yaml`) are not detected.
+
+3. **Is the directory empty or missing a compose file?** A subdirectory that exists but contains no recognized compose file will not appear. Add a valid compose file to the directory.
+
+4. **Is the stack already tracked?** Stacks that already appear in the sidebar are not reported again. The scan only reports *changes* since the last time the list was loaded.
+
+---
+
 ## Checking the health endpoint
 
 Sencho exposes a health endpoint for monitoring and container health checks: