docs: add workspace debug mode documentation

modules/end-user-guide/nav.adoc

@@ -61,6 +61,7 @@
 *** xref:viewing-workspace-logs-in-cli.adoc[]
 *** xref:viewing-workspace-logs-in-the-openshift-console.adoc[]
 *** xref:viewing-language-servers-and-debug-adapters-logs-in-visual-studio-code.adoc[]
+** xref:debugging-a-workspace.adoc[]
 ** xref:troubleshooting-slow-workspaces.adoc[]
 ** xref:troubleshooting-network-problems.adoc[]
 ** xref:troubleshooting-webview-loading-error.adoc[]

modules/end-user-guide/pages/debugging-a-workspace.adoc

@@ -0,0 +1,75 @@
+:_content-type: PROCEDURE
+:description: Debugging a failing {prod-short} workspace by starting it in debug mode
+:keywords: user-guide, debug, workspace, troubleshooting
+:navtitle: Debugging a workspace
+:page-aliases:
+
+[id="debugging-a-workspace"]
+= Debugging a {prod-short} workspace
+
+When a workspace fails to start, {prod-short} normally scales down the workspace deployment and moves it to a `Failed` state. This makes it difficult to diagnose issues such as failing `postStart` commands or misconfigured containers.
+
+Debug mode keeps the workspace containers running after a failure so that you can inspect logs and exec into containers to diagnose the root cause.
+
+When debug mode is enabled:
+
+* If a `postStart` lifecycle command fails, the container sleeps instead of terminating, giving you time to connect and inspect the failure.
+* Logs from `postStart` commands are written to `/tmp/poststart-stdout.txt` and `/tmp/poststart-stderr.txt` inside the workspace container.
+* The workspace deployment remains available for the duration of the configured `progressTimeout` (default: 5 minutes) before scaling down.
+
+.Prerequisites
+
+* A running {prod-short} instance.
+* Access to the {prod-short} dashboard.
+
+.Procedure
+
+To start a stopped workspace in debug mode:
+
+. In the {prod-short} dashboard, go to the *Workspaces* page.
+. Click the kebab menu (*⋮*) for the workspace you want to debug.
+. Select *Open in Debug mode*.
++
+The workspace starts with the `controller.devfile.io/debug-start` annotation set to `true`, and the *Logs* tab opens.
+
+To restart a running workspace in debug mode:
+
+. In the {prod-short} dashboard, go to the *Workspaces* page.
+. Click the kebab menu (*⋮*) for the running workspace.
+. Select *Restart in Debug mode*.
++
+The workspace restarts with debug mode enabled, and the *Logs* tab opens.
+
+To inspect a failing workspace:
+
+. Wait for the workspace to report a failure in the *Logs* tab.
+. Use `{orch-cli}` to exec into the workspace container:
++
+[subs="+attributes,+quotes"]
+----
+$ {orch-cli} exec --namespace='__<workspace_namespace>__' \
+  deploy/workspace__<workspace_id>__ -- /bin/bash
+----
+
+. Review the `postStart` command logs:
++
+----
+$ cat /tmp/poststart-stderr.txt
+$ cat /tmp/poststart-stdout.txt
+----
+
+.Verification
+
+* In the *Logs* tab, verify that the workspace status conditions include the message `DevWorkspace is starting in debug mode`.
+* If a `postStart` command fails, verify that the container remains running and that `/tmp/poststart-stderr.txt` contains the failure details.
+
+[IMPORTANT]
+====
+The `controller.devfile.io/debug-start` annotation is managed by the {prod-short} dashboard. Manually patching this annotation on a DevWorkspace resource using `{orch-cli}` will not persist, because the dashboard reconciles the annotation on every start or restart operation.
+
+Always use the dashboard actions described above to enable debug mode.
+====
+
+.Additional resources
+* xref:viewing-che-workspaces-logs.adoc[]
+* xref:viewing-workspace-logs-in-cli.adoc[]

modules/end-user-guide/pages/troubleshooting-che.adoc

@@ -12,6 +12,7 @@ This section provides troubleshooting procedures for the most frequent issues a
 .Additional resources
 
 * xref:viewing-che-workspaces-logs.adoc[]
+* xref:debugging-a-workspace.adoc[]
 * xref:troubleshooting-slow-workspaces.adoc[]
 * xref:troubleshooting-network-problems.adoc[]
 * xref:troubleshooting-webview-loading-error.adoc[]