docs: add AI provider configuration and usage docs

modules/administration-guide/nav.adoc

@@ -93,6 +93,8 @@
 *** xref:configuring-default-editor.adoc[]
 *** xref:concealing-editors.adoc[]
 *** xref:configuring-editors-download-urls.adoc[]
+*** xref:configuring-ai-providers.adoc[]
+**** xref:ai-provider-api-key-secret-reference.adoc[]
 *** xref:customizing-openshift-che-consolelink-icon.adoc[]
 ** xref:managing-identities-and-authorizations.adoc[]
 *** xref:configuring-oauth-for-git-providers.adoc[]

modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc

@@ -0,0 +1,113 @@
+:_content-type: REFERENCE
+:description: Reference for the Kubernetes Secret schema used by the Eclipse Che AI Selector to store and auto-mount AI provider API keys into workspace containers.
+:keywords: administration, ai, api key, secret, kubernetes, devworkspace controller, environment variable, mount
+:navtitle: AI Provider API Key Secret Reference
+:page-aliases:
+
+[id="ai-provider-api-key-secret-reference"]
+= AI provider API key Secret reference
+
+The {prod-short} dashboard stores each user's AI provider API key as a Kubernetes `Opaque` Secret in the user's personal {orch-namespace}. The {devworkspace} Controller automatically mounts matching Secrets as environment variables into all workspace containers. No modification of the `{devworkspace}` spec or devfile is required.
+
+== Secret schema
+
+[source,yaml,subs="+quotes,+attributes"]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: ai-provider-gemini-api-key  <1>
+  namespace: __<user-namespace>__
+  labels:
+    controller.devfile.io/mount-to-devworkspace: 'true'  <2>
+    controller.devfile.io/watch-secret: 'true'           <3>
+    che.eclipse.org/ai-provider-id: google-gemini <4>
+  annotations:
+    controller.devfile.io/mount-as: env                  <5>
+type: Opaque
+data:
+  GEMINI_API_KEY: __<base64-encoded-api-key>__           <6>
+----
+<1> Secret name is derived as `ai-provider-` + `envVarName.toLowerCase().replace(/_/g, '-')`. For `GEMINI_API_KEY` the name is `ai-provider-gemini-api-key`.
+<2> Instructs the DevWorkspace Controller to mount this Secret into all `DevWorkspace` containers in the namespace.
+<3> Instructs the DevWorkspace Controller to watch for Secret changes and re-mount without a workspace restart.
+<4> Sanitized provider ID (slashes replaced with dashes). Identifies which AI provider this Secret belongs to. Used by the {prod-short} dashboard to detect existing keys.
+<5> Mounts the Secret data keys as environment variables (not as files).
+<6> The data key is the environment variable name. The value is base64-encoded. The variable is injected directly into all workspace containers.
+
+== Label and annotation reference
+
+[cols="1,1,2",options="header"]
+|===
+| Label / Annotation | Value | Purpose
+
+| `controller.devfile.io/mount-to-devworkspace`
+| `'true'`
+| Causes the DevWorkspace Controller to mount this Secret into every `DevWorkspace` in the namespace.
+
+| `controller.devfile.io/watch-secret`
+| `'true'`
+| The DevWorkspace Controller re-mounts the Secret when its data changes, without requiring a workspace restart.
+
+| `controller.devfile.io/mount-as`
+| `env`
+| Each data key in the Secret becomes an environment variable with the key as the variable name and the decoded value as the variable value.
+
+| `che.eclipse.org/ai-provider-id`
+| Sanitized provider ID (for example, `google-gemini`). Slashes in the provider `id` are replaced with dashes.
+| Used by the {prod-short} dashboard to identify and list AI provider key Secrets when rendering the AI Selector widget.
+|===
+
+== Secret naming convention
+
+Secret names follow the pattern:
+
+----
+ai-provider-<envVarName-lowercased-underscores-as-dashes>
+----
+
+Examples:
+
+[cols="1,1",options="header"]
+|===
+| `envVarName` | Secret name
+
+| `GEMINI_API_KEY`
+| `ai-provider-gemini-api-key`
+
+| `ANTHROPIC_API_KEY`
+| `ai-provider-anthropic-api-key`
+
+| `OPENAI_API_KEY`
+| `ai-provider-openai-api-key`
+|===
+
+== Manual Secret creation
+
+Advanced users can create AI provider key Secrets manually using `{orch-cli}` instead of the dashboard UI. Use the same labels and annotations as shown in the schema above:
+
+[subs="+quotes,+attributes"]
+----
+$ {orch-cli} apply -f - <<EOF
+apiVersion: v1
+kind: Secret
+metadata:
+  name: ai-provider-gemini-api-key
+  namespace: __<user-namespace>__
+  labels:
+    controller.devfile.io/mount-to-devworkspace: 'true'
+    controller.devfile.io/watch-secret: 'true'
+    che.eclipse.org/ai-provider-id: google-gemini
+  annotations:
+    controller.devfile.io/mount-as: env
+type: Opaque
+data:
+  GEMINI_API_KEY: __<base64-encoded-api-key>__
+EOF
+----
+
+.Additional resources
+
+* xref:configuring-ai-providers.adoc[]
+* xref:end-user-guide:mounting-secrets.adoc[Mounting Secrets (end-user guide)]
+* link:https://devfile.io/docs/2.2.0/what-is-a-devfile[DevWorkspace Operator documentation]

modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc

@@ -100,3 +100,96 @@ spec:
 ====
 
 include::example$checluster-properties/checluster-properties.adoc[leveloffset=+1]
+
+[id="ai-tool-registry-configmap-reference"]
+== AI tool registry ConfigMap
+
+AI providers and tools are configured through a {kubernetes} `ConfigMap` in the `{prod-namespace}` namespace, not through the `{prod-checluster}` custom resource. The ConfigMap must have the following labels to be discovered by the dashboard:
+
+* `app.kubernetes.io/component=ai-tool-registry`
+* `app.kubernetes.io/part-of=che.eclipse.org`
+
+The ConfigMap contains a `registry.json` key with three sections: `providers`, `tools`, and `defaultAiProviders`.
+
+=== Provider fields
+
+[cols="1,1,3",options="header"]
+|===
+| Field | Type | Description
+
+| `id`
+| `string`
+| Unique identifier for the provider (for example, `google/gemini`).
+
+| `name`
+| `string`
+| Display name shown in the dashboard (for example, `Gemini`).
+
+| `publisher`
+| `string`
+| Publisher name (for example, `Google`).
+
+| `description`
+| `string` (optional)
+| Short description shown in the provider card.
+
+| `docsUrl`
+| `string` (optional)
+| URL to the provider's API key documentation, shown as a link in the dashboard.
+
+| `icon`
+| `string` (optional)
+| URL to the provider's SVG icon.
+|===
+
+=== Tool fields
+
+[cols="1,1,3",options="header"]
+|===
+| Field | Type | Description
+
+| `providerId`
+| `string`
+| Links the tool to a provider by `id` (for example, `google/gemini`).
+
+| `tag`
+| `string`
+| Version tag (for example, `next`, `latest`, `3.21`). When multiple tools share the same `providerId`, the dashboard selects by priority: `next` > `latest` > highest semver.
+
+| `name`
+| `string`
+| Display name for the tool (for example, `Gemini CLI`).
+
+| `url`
+| `string`
+| URL to the tool's homepage.
+
+| `binary`
+| `string`
+| Binary name available in `PATH` after injection (for example, `gemini`).
+
+| `pattern`
+| `string`
+| Injection pattern: `init` (single binary copied to `/injected-tools/bin/`) or `bundle` (full runtime directory copied and symlinked).
+
+| `injectorImage`
+| `string`
+| Container image used as an init container to copy the tool binary into a shared volume.
+
+| `envVarName`
+| `string` (optional)
+| Name of the environment variable for the API key (for example, `GEMINI_API_KEY`). This is also the data key in the {kubernetes} Secret.
+
+| `setupCommand`
+| `string` (optional)
+| One-time setup command run in the editor container at postStart.
+|===
+
+=== defaultAiProviders
+
+Optional. A JSON array of provider `id` values that are pre-selected in the AI Selector widget for new workspaces.
+
+.Additional resources
+
+* xref:configuring-ai-providers.adoc[]
+* xref:ai-provider-api-key-secret-reference.adoc[]

modules/administration-guide/pages/configuring-ai-providers.adoc

@@ -0,0 +1,111 @@
+:_content-type: PROCEDURE
+:description: Enable and configure AI provider support in Eclipse Che so that users can select an AI assistant when creating workspaces.
+:keywords: administration, ai, ai provider, gemini, claude, configmap, ai-tool-registry, api key
+:navtitle: Configuring AI Providers
+:page-aliases:
+
+[id="configuring-ai-providers"]
+= Configuring AI providers
+
+Enable one or more AI providers in {prod-short} so that users can select an AI coding assistant from the *Create Workspace* page and have the tool binary injected into the workspace editor container.
+
+The AI tool registry is stored in a {kubernetes} `ConfigMap` with specific labels. When the ConfigMap exists and contains at least one provider with a matching tool, the AI Selector widget is displayed on the dashboard. When the ConfigMap is absent or empty, the widget is hidden.
+
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+* The {prod-operator} is installed and a `{prod-checluster}` custom resource exists in the `{prod-namespace}` namespace.
+
+.Procedure
+
+. Create a `registry.json` file defining providers, tools, and default selections:
++
+[source,json,subs="+quotes"]
+----
+{
+  "providers": [
+    {
+      "id": "google/gemini",
+      "name": "Gemini",
+      "publisher": "Google",
+      "description": "Google Gemini AI assistant for the terminal.",
+      "docsUrl": "https://ai.google.dev/gemini-api/docs/quickstart",
+      "icon": "https://example.com/gemini-icon.svg"
+    },
+    {
+      "id": "anthropic/claude",
+      "name": "Claude",
+      "publisher": "Anthropic",
+      "description": "Anthropic Claude AI coding assistant for terminal.",
+      "docsUrl": "https://docs.anthropic.com/claude/reference/getting-started-with-the-api",
+      "icon": "https://example.com/claude-icon.svg"
+    }
+  ],
+  "tools": [
+    {
+      "providerId": "google/gemini",  <1>
+      "tag": "next",                  <2>
+      "name": "Gemini CLI",
+      "url": "https://ai.google.dev/gemini-api/docs",
+      "binary": "gemini",             <3>
+      "pattern": "bundle",            <4>
+      "injectorImage": "quay.io/example/gemini-cli:next",  <5>
+      "envVarName": "GEMINI_API_KEY"   <6>
+    },
+    {
+      "providerId": "anthropic/claude",
+      "tag": "next",
+      "name": "Claude Code",
+      "url": "https://claude.ai/code",
+      "binary": "claude",
+      "pattern": "init",
+      "injectorImage": "quay.io/example/claude-code:next",
+      "envVarName": "ANTHROPIC_API_KEY"
+    }
+  ],
+  "defaultAiProviders": ["google/gemini"]  <7>
+}
+----
+<1> Links the tool to a provider by the provider's `id`.
+<2> Version tag. When multiple tools share the same `providerId`, the dashboard selects by tag priority: `next` > `latest` > highest semver.
+<3> Binary name available in `PATH` after injection.
+<4> Injection pattern: `init` copies a single binary; `bundle` copies a full runtime directory and creates a symlink.
+<5> Container image used as an init container to copy the tool binary into a shared volume.
+<6> Environment variable name for the API key. The dashboard creates a {kubernetes} Secret with this key.
+<7> Optional. List of provider IDs pre-selected in the AI Selector widget for new workspaces.
+
+. Create the `ConfigMap` in the `{prod-namespace}` namespace with the required labels:
++
+[subs="+quotes,+attributes"]
+----
+$ {orch-cli} create configmap ai-tool-registry \
+  --from-file=registry.json=registry.json \
+  -n {prod-namespace} \
+  --dry-run=client -o yaml | \
+  {orch-cli} label --local -f - \
+    app.kubernetes.io/component=ai-tool-registry \
+    app.kubernetes.io/part-of=che.eclipse.org \
+    -o yaml | \
+  {orch-cli} apply -f -
+----
+
+.Verification
+
+. Open the {prod-short} dashboard.
+. Navigate to *Create Workspace*.
+. Verify that an *AI Provider* section is visible, listing the providers you configured.
+
+[NOTE]
+====
+To disable the AI Selector widget, delete the `ai-tool-registry` ConfigMap. Users will no longer see the AI Provider section on the Create Workspace page. Existing API key Secrets in user namespaces are not deleted automatically.
+====
+
+[NOTE]
+====
+When an administrator updates the registry (for example, removes a tool or changes the injector image tag), existing workspaces are updated automatically before their next start. The dashboard removes stale tool injectors and replaces outdated image tags without user intervention.
+====
+
+.Additional resources
+
+* xref:ai-provider-api-key-secret-reference.adoc[]
+* xref:end-user-guide:using-ai-assistants-in-workspaces.adoc[]

modules/end-user-guide/nav.adoc

@@ -15,6 +15,7 @@
 **** xref:url-parameter-for-memory-limit.adoc[]
 **** xref:url-parameter-for-cpu-limit.adoc[]
 **** xref:url-parameter-for-the-existing-workspace-name.adoc[]
+**** xref:url-parameter-for-the-ai-provider.adoc[]
 ** xref:starting-a-workspace-from-a-raw-devfile-url.adoc[]
 ** xref:basic-actions-you-can-perform-on-a-workspace.adoc[]
 ** xref:restoring-workspaces-from-backups.adoc[]
@@ -35,6 +36,8 @@
 ** 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:using-credentials-and-configurations-in-workspaces.adoc[]
 ** xref:mounting-secrets.adoc[]
 *** xref:creating-image-pull-secrets.adoc[]