docs: Add Claude Code configuration persistence guides

[akurinnoy]

What does this pull request change?

Adds a new "AI coding tools in workspaces" section to the User Guide with documentation on persisting Claude Code configuration across workspaces.

New pages:

1. AI coding tools in workspaces - top-level section, extensible for other tools later
2. Persisting Claude Code configuration - overview of config file locations (~/.claude/, ~/.claude.json), comparison of available approaches, file reference table
3. Sharing configuration with a dedicated PVC - step-by-step guide with two options: direct mount (Option A) and full /tmp copy (Option B)
4. Sharing configuration with GitOps - concept page describing the Git-based approach using DWO's project-clone init container
5. Troubleshooting Claude Code configuration persistence - 7 known issues with symptoms, causes, and solutions

What issues does this pull request fix or reference?

resolves eclipse-che/che#23846

Specify the version of the product this pull request applies to

Pull Request checklist

The author and the reviewers validate the content of this pull request with the following checklist, in addition to the automated tests.

• Any procedure:
  • Successfully tested.
• Any page or link rename:
  • The page contains a redirection for the previous URL.
  • Propagate the URL change in:
    • Dashboard default branding data
• Builds on Eclipse Che hosted by Red Hat.
• the Validate language on files added or modified step reports no vale warnings.

[github-actions]

Click here to review and test in web IDE:

[github-actions]

⚡️ Deploying pull request preview...

[rohanKanojia]

Suggested change

	Claude Code stores configuration in two separate locations in the user home directory:
	Claude Code stores configuration in two separate locations in the user's home directory:

[gtrivedi88]

CQA P3/P5 — Content type mismatch. This page is labeled :_content-type: ASSEMBLY but contains no include:: directives. The content (tables, explanations, admonitions) is conceptual/overview. Consider changing to :_content-type: CONCEPT.

In modular docs, an assembly aggregates topic modules via include::. This page is a standalone overview that links to child pages via xref:, which is valid for Antora but is not an assembly in the modular docs sense.

[gtrivedi88]

CQA P11 / JTBD — WHY-first abstract. The abstract starts with the problem ("New workspaces start without..."), which is a pain-point opener. CQA 2.1 and JTBD recommend leading with the user's goal/purpose.

Suggested rewrite:

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.

[gtrivedi88]

CQA Q10 — Admonition clustering. Two admonitions ([IMPORTANT] + [NOTE]) appear back-to-back (lines 28–36). CQA 2.1 recommends avoiding adjacent admonitions because they reduce scannability and suggest the surrounding prose needs restructuring.

Consider merging these into a single [IMPORTANT] that covers both points (both paths must be persisted AND both must be writable), or folding the NOTE content into the preceding paragraph.

[gtrivedi88]

CQA Q20 / Style — Inconsistent path notation. The "Claude Code file reference" table uses bare ~/ paths (e.g., ~/.claude/settings.json) while the earlier "Claude Code configuration files" table uses {prod-home} (e.g., {prod-home}/.claude/).

Use {prod-home} consistently throughout the page for portability and downstream attribute resolution. The ~/ notation resolves differently across platforms.

Also, consider whether this detailed file reference table belongs in a separate reference module, keeping this overview page focused on decision guidance between the two approaches.

[gtrivedi88]

CQA P10 — Procedure title convention. Procedure titles should use an imperative verb, not a gerund. "Sharing" → "Share".

Suggested: = Share Claude Code configuration across workspaces with a dedicated PVC

Update the [id], :navtitle:, and the filename to match. The IBM Style Guide and Red Hat SSG both prescribe imperative titles for task-based content.

[gtrivedi88]

CQA P12 / Structure — Two procedures in one module. This page contains two distinct procedures (Option A: Direct mount, Option B: Full /tmp copy), each with their own numbered steps. CQA 2.1 recommends one procedure per module.

Consider splitting into two separate procedure modules:

• sharing-claude-code-configuration-pvc-direct-mount.adoc
• sharing-claude-code-configuration-pvc-tmp-copy.adoc

Alternatively, keep as-is but restructure this page as an ASSEMBLY that includes both procedure modules. The comparison table at the top is good decision-guidance content for an assembly.

[gtrivedi88]

Technical clarity — tail -f /dev/null in init pod. This command keeps the init pod running indefinitely after initialization. Users may not understand why, and if they run {orch-cli} apply and walk away, the pod stays running forever consuming resources. The next step says to delete it, but the gap in the flow could cause confusion.

Consider:

1. Adding a YAML comment explaining why the pod stays running (so users can inspect logs before deleting)
2. Or replacing with sleep 30 so the pod auto-terminates
3. Or using restartPolicy: Never and removing the tail command entirely

At minimum, add a NOTE warning users that the init pod must be manually deleted after verification.

[gtrivedi88]

CQA Q14 — Multiple commands per step. This step packs 4 commands (apply, wait, logs, delete) into a single numbered step. CQA 2.1 recommends one action per step for clarity, error recovery, and troubleshooting.

Split into separate steps:

1. Apply the init pod
2. Wait for the pod to reach Ready state
3. Verify the initialization (under .Verification heading)
4. Delete the init pod

This also makes the logs command clearly a verification step rather than a procedural one.

[gtrivedi88]

CQA Q5 — Limitations section accuracy. The bullet "Can be combined with persistUserHome" is not a limitation — it is a compatibility note describing positive coexistence. Limitations should describe constraints and restrictions.

Move this bullet to the assembly overview page as a NOTE about compatibility, or to a separate "Compatibility" section. Keep only actual constraints in the Limitations list.

[gtrivedi88]

JTBD — Critical gap: No actionable procedure. This page describes the GitOps approach conceptually ("How it works", "Advantages", "Limitations") but provides zero procedure steps. A user who chooses this approach based on the assembly's comparison table has no implementation guidance.

The nav.adoc places this at the same level as the PVC procedure, implying equivalent actionability. This breaks the user journey.

Recommendation: Either:

1. Add a .Procedure section with a concrete devfile example showing the projects entry and postStart command for copying config files, or
2. Add a NOTE at the top: This page describes the GitOps approach conceptually. A step-by-step procedure is in progress. and remove the nav entry until the procedure exists, or
3. At minimum, provide a devfile snippet showing the essential configuration.

A concept page that a user cannot act on creates frustration and support burden.

[gtrivedi88]

CQA P10 — Title convention. Same as the PVC page: gerund → imperative.

Suggested: = Share Claude Code configuration across workspaces with GitOps

Update :navtitle:, [id], and filename accordingly.

[gtrivedi88]

CQA Q4/Q5 — Self-referential language. "This section describes known issues..." is self-referential. CQA 2.1 recommends customer-centric abstracts that state what the user can DO, not what the documentation contains.

Suggested rewrite:

If you encounter issues with Claude Code configuration persistence in {prod-short} workspaces, use the following symptoms and solutions to diagnose and resolve them.

[gtrivedi88]

CQA structure — Section does not follow troubleshooting pattern. "Dedicated PVC and persistent user home interaction" is an informational note, not a troubleshooting entry. It lacks the Symptom/Cause/Solution structure used by all other sections on this page.

Consider:

1. Moving this content to the assembly overview page or the PVC procedure's compatibility section, or
2. Reformatting as a troubleshooting entry if there IS a common user confusion to address (e.g., Symptom: "User expects conflict between dedicated PVC and persistUserHome" / Cause: / Solution: "No action needed").

[gtrivedi88]

CQA P3/P12 — Modularization suggestion. This 262-line page mixes concept content (comparison tables, architectural explanations), two separate procedures (Option A and Option B), shared configuration options, and a limitations reference. CQA 2.1 recommends one content type per module.

Consider splitting into separate pages:

• Concept: con_claude-code-configuration-files.adoc — config file locations, the IMPORTANT/NOTE about .claude.json, and the file reference table
• Procedure (Option A): proc_sharing-claude-code-configuration-pvc-direct-mount.adoc — create PVC, run init pod, verify
• Procedure (Option B): proc_sharing-claude-code-configuration-pvc-tmp-copy.adoc — create PVC, add postStart, sync, verify
• Reference: ref_claude-code-file-reference.adoc — the detailed file reference table (path, purpose, size, regeneratable)
• Snippet: snip_prerequisite-oc-session-with-pvc-permissions.adoc — shared PVC prerequisites (identical for both options)

The comparison table (Option A vs Option B) can stay in the assembly/overview page as decision guidance.

This way each module has exactly one content type, users aren't forced to read through an option they didn't choose, and the file reference table lives in one place instead of being partially duplicated.

Upstream Antora doesn't require con_/proc_/ref_ prefixes or include:: assemblies — separate Antora pages linked via xref: achieve the same modularity.