eclipse-che · gtrivedi88 · Aug 24, 2026
@@ -9,6 +9,7 @@ nav:
   - modules/install/nav.adoc
   - modules/get-started-admin/nav.adoc
   - modules/get-started-user/nav.adoc
+  - modules/develop/nav.adoc
   - modules/troubleshoot/nav.adoc
   - modules/end-user-guide/nav.adoc
   - modules/upgrade/nav.adoc

@@ -0,0 +1,51 @@
+.Develop
+* xref:using-credentials-and-configurations-in-workspaces.adoc[]
+** xref:mounting-secrets.adoc[]
+*** xref:creating-image-pull-secrets.adoc[]
+** xref:mounting-configmaps.adoc[]
+*** xref:mounting-git-configuration.adoc[]
+*** xref:mounting-ssh-configuration.adoc[]
+* xref:using-the-fuse-overlay-storage-driver.adoc[]
+** xref:accessing-fuse.adoc[]
+** xref:enabling-overlay-with-a-configmap.adoc[]
+** xref:running-containers-with-kubedock.adoc[]
+* xref:using-che-in-team-workflow.adoc[]
+** xref:first-time-contributors.adoc[]
+** xref:benefits-of-pull-requests-review-in-che.adoc[]
+** xref:try-in-web-ide-github-action.adoc[]
+* xref:requesting-persistent-storage-for-workspaces.adoc[]
+** xref:restoring-workspaces-from-backups.adoc[]
+*** xref:proc-viewing-backups-in-the-dashboard.adoc[]
+*** xref:proc-restoring-a-workspace-from-backup.adoc[]
+* xref:proc_preventing-workspace-idling-for-long-running-commands.adoc[]
+* xref:starting-a-workspace-from-a-raw-devfile-url.adoc[]
+* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
+** xref:url-parameter-concatenation.adoc[]
+** xref:url-parameter-for-the-ide.adoc[]
+** xref:url-parameter-for-the-ide-image.adoc[]
+** xref:url-parameter-for-starting-duplicate-workspaces.adoc[]
+** xref:url-parameter-for-the-existing-workspace-name.adoc[]
+** xref:url-parameter-for-the-devfile-file-name.adoc[]
+** xref:url-parameter-for-the-devfile-file-path.adoc[]
+** xref:url-parameter-for-the-workspace-storage.adoc[]
+** xref:url-parameter-for-additional-remotes.adoc[]
+** xref:url-parameter-for-container-image.adoc[]
+** xref:url-parameter-for-memory-limit.adoc[]
+** xref:url-parameter-for-cpu-limit.adoc[]
+** xref:url-parameter-for-the-ai-provider.adoc[]
+* Set up your development tools
+** xref:customizing-workspace-components.adoc[]
+*** xref:devfile-introduction.adoc[]
+** xref:ides-in-workspaces.adoc[]
+*** xref:microsoft-visual-studio-code-open-source-ide.adoc[]
+*** xref:connect-visual-studio-code-to-che-workspace.adoc[]
+*** xref:defining-a-common-ide.adoc[]
+** xref:using-ai-assistants-in-workspaces.adoc[]
+*** xref:configuring-an-ai-provider-api-key.adoc[]
+*** xref:changing-the-ai-tool-on-a-workspace.adoc[]
+*** xref:persist-claude-code-configuration.adoc[]
+**** xref:share-claude-code-configuration-with-pvc-direct-mount.adoc[]
+**** xref:share-claude-code-configuration-with-pvc-tmp-copy.adoc[]
+**** xref:share-claude-code-configuration-with-gitops.adoc[]
+**** xref:troubleshoot-claude-code-configuration-persistence.adoc[]
+*** xref:distribute-claude-code-skills-with-lola.adoc[]
@@ -1,7 +1,7 @@
 :_content-type: PROCEDURE
 :description: {prod} workspace contains all tools you need to review pull and merge requests from start to finish.
 :keywords: user-guide, reviewing, pull request, merge request
-:navtitle: Reviewing pull and merge requests
+:navtitle: Benefits of reviewing pull and merge requests in {prod}
 :page-aliases:
 
 [id="title"]

@@ -1,7 +1,7 @@
 :_content-type: PROCEDURE
 :description: Switch or remove the AI coding assistant on a stopped workspace without recreating it, and optionally choose a specific version.
 :keywords: user-guide, ai, ai tool, ai provider, workspace, change, update, version
-:navtitle: Changing the AI tool on a workspace
+:navtitle: Change the AI tool on a workspace
 :page-aliases:
 
 [id="changing-the-ai-tool-on-a-workspace"]

@@ -1,7 +1,7 @@
 :_content-type: PROCEDURE
 :description: Store your AI provider API key so that it is automatically available as an environment variable in all your workspaces.
 :keywords: user-guide, ai, api key, ai provider, environment variable, secret
-:navtitle: Configuring an AI provider API key
+:navtitle: Configure an AI provider API key
 :page-aliases:
 
 [id="configuring-an-ai-provider-api-key"]

@@ -1,3 +1,4 @@
+:page-aliases: end-user-guide:connect-visual-studio-code-to-che-workspace.adoc
 [id="connect-visual-studio-code-to-che-workspace"]
 
 = Connecting Visual Studio Code to a {prod-short} workspace

@@ -1,3 +1,4 @@
+:page-aliases: end-user-guide:devfile-introduction.adoc
 [id="introduction-to-devfile"]
 = Introduction to devfile in {prod-short}
 

@@ -8,15 +8,13 @@
 
 Use link:https://github.com/LobsterTrap/lola[Lola] to distribute team-authored skills, commands, and agents from a central Git repository into {prod-short} workspaces. Lola supports multiple AI assistants, including Claude Code, Cursor, Copilot, Gemini CLI, and OpenCode. It translates module content into each assistant's native file structure, so developers receive a consistent set of standards and tools without manual setup.
 
+A team maintains a Lola module in a Git repository containing skills (coding standards, guardrails), commands (on-demand audit macros), and agent definitions. Developers add a `.lola-req` file to their project referencing the module. Running `lola sync` fetches the module and installs it into the target assistant's native directory structure.
+
 [NOTE]
 ====
-Lola manages skills, commands, and agents — not the full AI assistant configuration. For example, to persist Claude Code settings, MCP servers, and plugins, see xref:persist-claude-code-configuration.adoc[].
+Lola manages skills, commands, and agents only. It does not persist assistant-specific settings, MCP server configurations, or plugin caches. For full Claude Code configuration persistence, see Additional resources.
 ====
 
-== How it works
-
-A team maintains a Lola module in a Git repository containing skills (coding standards, guardrails), commands (on-demand audit macros), and agent definitions. Developers add a `.lola-req` file to their project referencing the module. Running `lola sync` fetches the module and installs it into the target assistant's native directory structure.
-
 .Prerequisites
 
 * An AI assistant (Claude Code, Cursor, Copilot, Gemini CLI, or OpenCode) installed in the workspace container image.
@@ -46,13 +44,11 @@ module/
 
 . Create a `.lola-req` file at the root of your project repository with a reference to the module:
 +
-====
 [source,text,subs="+quotes"]
 ----
 __<git_repository_url>__@main#subdirectory=module&assistant=__<assistant>__ # <1>
 ----
 <1> Replace `__<git_repository_url>__` with the URL of your Lola module repository. Replace `__<assistant>__` with the target assistant: `claude-code`, `cursor`, `copilot`, `gemini-cli`, or `opencode`. The `subdirectory` fragment points to the module root inside the repository.
-====
 
 . Run `lola sync` to fetch and install the module:
 +
@@ -65,7 +61,6 @@ Lola clones the module, extracts skills and commands, and writes them into the t
 
 . Optional: To automate the sync at workspace startup, add a `postStart` command to your devfile:
 +
-====
 [source,yaml,subs="+quotes,+attributes"]
 ----
 commands:
@@ -80,7 +75,6 @@ events:
 ----
 <1> Replace with the name of your project directory.
 <2> Replace with the name of a container component from the `components` section of your devfile.
-====
 
 .Verification
 

@@ -1,7 +1,7 @@
 :_content-type: PROCEDURE
 :description: You can enable fuse-overlayfs storage driver for Podman
 :keywords: overlay, configmap, podman, storage, driver, fuse-overlayfs
-:navtitle: Enabling fuse-overlayfs with a ConfigMap
+:navtitle: Enabling fuse-overlayfs with a Configmap
 :page-aliases:
 
 [id="enabling-fuse-overlay-with-a-configmap"]

@@ -1,7 +1,7 @@
 :_content-type: PROCEDURE
 :description: Badge for first-time contributors
 :keywords: user-guide, first-time contributor
-:navtitle: Badge for first-time contributors
+:navtitle: Using a badge with a link to enable a first-time contributor to start a workspace
 :page-aliases:
 
 [id="using-a-badge-with-a-link-to-enable-a-first-time-contributor-to-start-a-workspace"]

@@ -1,7 +1,7 @@
 :_content-type: CONCEPT
 :description: Microsoft Visual Studio Code - Open Source IDE
 :keywords: user-guide, selecting, IDE, select, selecting, editor, ide, vs-code, visual-studio, visual-studio-code, jetbrains, intellij, pycharm, theia, che-theia
-:navtitle: Microsoft Visual Studio Code - Open Source
+:navtitle: Microsoft Visual Studio Code - Open Source IDE
 :page-aliases:
 
 [id="microsoft-visual-studio-code-open-source-ide"]

@@ -5,9 +5,9 @@
 :page-aliases: persisting-claude-code-configuration.adoc
 
 [id="persist-claude-code-configuration"]
-= Persist Claude Code configuration in {prod-short} workspaces
+= Claude Code configuration persistence
 
-To reuse Claude Code skills, settings, MCP servers, and plugins across {prod-short} workspaces, persist the configuration in a shared volume or a Git repository. Without persistence, each new workspace requires a fresh setup.
+Persist Claude Code skills, settings, MCP servers, and plugins across {prod-short} workspaces by storing them in a shared volume or a Git repository. Without persistence, each new workspace requires a fresh setup.
 
 == Claude Code configuration files
 
@@ -33,21 +33,59 @@ Claude Code writes runtime state to both paths during every session, including s
 == Available approaches
 
 |===
-| Approach | Summary
+| Approach | Summary | Storage requirement
 
 | xref:share-claude-code-configuration-with-pvc-direct-mount.adoc[]
 | Both `{prod-home}/.claude/` and `{prod-home}/.claude.json` are mounted directly from a dedicated PVC. All changes persist automatically. Requires a one-time init pod to pre-create `.claude.json`.
+| RWX for concurrent workspaces
 
 | xref:share-claude-code-configuration-with-pvc-tmp-copy.adoc[]
 | A dedicated PVC is mounted at `/tmp/claude`. A `postStart` command copies everything into the home directory. No init pod is required, but changes must be synced back manually before stopping the workspace.
+| RWX for concurrent workspaces
 
 | xref:share-claude-code-configuration-with-gitops.adoc[]
 | A Git repository stores the baseline Claude Code configuration. The {devworkspace} Operator clones the repository at startup, and a `postStart` command copies the configuration into the home directory.
+| No PVC required
 |===
 
-== Distributing skills and commands
+== Distribute skills and commands
 
-To distribute team-authored skills, commands, and agents across workspaces without persisting the full configuration, see xref:distribute-claude-code-skills-with-lola.adoc[]. Lola supports Claude Code and other AI assistants.
+To distribute team-authored skills, commands, and agents across workspaces without persisting the full configuration, use Lola. Lola supports Claude Code and other AI assistants. For Lola setup instructions, see _Distribute AI assistant skills and commands across workspaces with Lola_ in Additional resources.
+
+== Filter PVC mounts by workspace name
+
+Control which workspaces mount the PVC by adding annotations to the PVC metadata:
+
+[source,yaml,subs="+quotes,+attributes"]
+----
+annotations:
+  controller.devfile.io/mount-to-devworkspace-include: '__<pattern>__'
+  controller.devfile.io/mount-to-devworkspace-exclude: '__<pattern>__'
+----
+
+`mount-to-devworkspace-include` mounts the PVC only to workspaces whose names match the pattern. `mount-to-devworkspace-exclude` mounts the PVC to all workspaces except those whose names match.
+
+Supported patterns: exact match (`name`), prefix (`name\*`), suffix (`\*name`), contains (`\*name\*`). Matching is on the {devworkspace} resource name.
+
+== Concurrent workspace access
+
+|===
+| Access mode | Behavior
+
+| ReadWriteOnce (RWO)
+| One workspace at a time. Two workspaces on different nodes cause a multi-attach error.
+
+| ReadWriteMany (RWX)
+| Concurrent workspaces on different pods work. Requires a storage class that supports RWX, such as AWS EFS or NFS. Standard block storage (gp2, gp3) does not support RWX.
+|===
+
+== Compatibility with `persistUserHome`
+
+For the direct mount approach, a dedicated PVC mounted at `{prod-home}/.claude` and the persistent home PVC mounted at `{prod-home}/` coexist correctly as nested mounts. Writes to `{prod-home}/.claude/` go to the dedicated PVC. Writes to other paths under `{prod-home}/` go to the persistent home PVC.
+
+For the tmp copy approach, the dedicated PVC mounted at `/tmp/claude` and the persistent home PVC mounted at `{prod-home}/` do not conflict because they use different mount points. If the devfile includes a `postStart` command, it copies configuration from the PVC into the home directory at workspace start. Otherwise, you must copy the configuration manually. Changes must be synced back to the PVC manually before stopping the workspace.
+
+If you only need persistence within a single workspace and not cross-workspace sharing, `persistUserHome` alone is sufficient.
 
 == Claude Code file reference
 

@@ -7,11 +7,7 @@
 [id="share-claude-code-configuration-with-gitops"]
 = Share Claude Code configuration across workspaces with GitOps
 
-Instead of using a shared PVC, you can store Claude Code configuration in a Git repository and pull it into workspaces at startup. Each workspace gets its own isolated, writable copy of the configuration.
-
-This approach eliminates multi-attach errors and last-write-wins data corruption risks that can occur with shared PVCs on clusters without RWX storage.
-
-== How it works
+Instead of using a shared PVC, you can store Claude Code configuration in a Git repository and pull it into workspaces at startup. Each workspace gets its own isolated, writable copy of the configuration, preventing multi-attach errors and last-write-wins data corruption risks that can occur with shared PVCs on clusters without RWX storage.
 
 A central Git repository stores the baseline Claude Code configuration. The repository is listed in the `projects` section of the devfile, and the {devworkspace} Operator's project-clone init container clones it automatically at workspace startup. A `postStart` command then copies the configuration files from the cloned repository into the home directory.
 
@@ -21,7 +17,7 @@ Two usage patterns are possible:
 
 * *User-specific persistence* — each developer maintains a private branch or repository with personal configuration. The repository is cloned at startup and copied into the home directory. Optionally, a `preStop` command or manual step commits and pushes changes back before the workspace stops.
 
-For a comparison with other approaches, see xref:persist-claude-code-configuration.adoc[].
+For a comparison with other approaches, see _Claude Code configuration persistence_ in Additional resources.
 
 .Prerequisites
 
@@ -44,7 +40,6 @@ For a comparison with other approaches, see xref:persist-claude-code-configurati
 
 . Add the configuration repository to the `projects` section of your devfile:
 +
-====
 [source,yaml,subs="+quotes,+attributes"]
 ----
 projects:
@@ -54,11 +49,9 @@ projects:
         origin: '__<git_repository_url>__' # <1>
 ----
 <1> Replace with the URL of your Claude Code configuration repository.
-====
 
 . Add a `postStart` command to copy the configuration from the cloned repository into the home directory:
 +
-====
 [source,yaml,subs="+quotes,+attributes"]
 ----
 commands:
@@ -73,7 +66,6 @@ events:
     - init-claude-config
 ----
 <1> Replace with the name of a container component from the `components` section of your devfile.
-====
 
 . Start the workspace.
 

@@ -16,7 +16,7 @@ The direct mount flow:
 . You configure Claude Code — install plugins, add MCP servers, change settings. All writes go directly to the PVC.
 . The second workspace starts. The same PVC mounts, and all configuration from the previous workspace is available.
 
-For a comparison with other approaches, see xref:persist-claude-code-configuration.adoc[].
+For a comparison with other approaches, see _Claude Code configuration persistence_ in Additional resources.
 
 .Prerequisites
 
@@ -32,7 +32,6 @@ For a comparison with other approaches, see xref:persist-claude-code-configurati
 
 . Create a file `claude-config-pvc.yaml` with the following PVC definition:
 +
-====
 [source,yaml,subs="+quotes,+attributes"]
 ----
 kind: PersistentVolumeClaim
@@ -52,7 +51,6 @@ spec:
     requests:
       storage: 1Gi
 ----
-====
 
 . Apply the PVC to your {orch-namespace}:
 +
@@ -67,7 +65,6 @@ The `{prod-home}/.claude.json` subPath target must exist as a *file* on the PVC
 +
 Create a file `claude-config-init-pod.yaml`:
 +
-====
 [source,yaml,subs="+quotes,+attributes"]
 ----
 apiVersion: v1
@@ -95,7 +92,6 @@ spec:
       persistentVolumeClaim:
         claimName: claude-config
 ----
-====
 
 . Apply the init pod:
 +
@@ -126,7 +122,7 @@ $ {orch-cli} delete pod claude-config-init
 ----
 
 . Start any workspace. The PVC auto-mounts into every workspace pod.
-
++
 [WARNING]
 ====
 On multi-AZ clusters using `WaitForFirstConsumer` storage classes (gp2, gp3), the init pod may bind the PV to a different availability zone than workspace pods. See xref:troubleshoot-claude-code-configuration-persistence.adoc#pvc-scheduling-failure-after-init-pod-setup[PVC scheduling failure after init pod setup].
@@ -138,39 +134,6 @@ On multi-AZ clusters using `WaitForFirstConsumer` storage classes (gp2, gp3), th
 . Stop and restart the workspace. Verify the configuration is preserved.
 . Start a different workspace. Verify the same configuration is available.
 
-== Filtering by workspace name
-
-Control which workspaces mount the PVC by adding annotations:
-
-[source,yaml,subs="+quotes,+attributes"]
-----
-annotations:
-  controller.devfile.io/mount-to-devworkspace-include: '__<pattern>__' # <1>
-  controller.devfile.io/mount-to-devworkspace-exclude: '__<pattern>__' # <2>
-----
-<1> Mount the PVC only to workspaces whose names match the pattern.
-<2> Mount the PVC to all workspaces except those whose names match the pattern.
-
-Supported patterns: exact match (`name`), prefix (`name\*`), suffix (`\*name`), contains (`\*name\*`). Matching is on the {devworkspace} resource name.
-
-== Concurrent workspaces
-
-|===
-| Access mode | Behavior
-
-| ReadWriteOnce (RWO)
-| One workspace at a time. Two workspaces on different nodes cause a multi-attach error.
-
-| ReadWriteMany (RWX)
-| Concurrent workspaces on different pods work. Requires a storage class that supports RWX, such as AWS EFS or NFS. Standard block storage (gp2, gp3) does not support RWX.
-|===
-
-== Compatibility with `persistUserHome`
-
-A dedicated PVC mounted at `{prod-home}/.claude` and the persistent home PVC mounted at `{prod-home}/` coexist correctly as nested mounts. Writes to `{prod-home}/.claude/` go to the dedicated PVC. Writes to other paths under `{prod-home}/` go to the persistent home PVC.
-
-If you only need persistence within a single workspace and not cross-workspace sharing, `persistUserHome` alone is sufficient.
-
 == Limitations
 
 * Requires manual PVC setup per user {orch-namespace}.