docs: consolidate Claude Code deployment docs and fix settings.json mount

agents/claude-code/deployment/deployment-ogx-vllm.yaml

@@ -182,6 +182,31 @@ spec:
             - name: ANTHROPIC_DEFAULT_OPUS_MODEL
               value: "vllm/YOUR_MODEL_ID"
             # ===========================================
+            # MLflow Tracing (Optional)
+            # ===========================================
+            # Uncomment and configure to enable.
+            # See the MLflow Tracing section in ../README.md for details.
+            # - name: MLFLOW_TRACKING_URI
+            #   value: "https://mlflow.<rhoai-namespace>.svc:8443/mlflow"
+            # - name: MLFLOW_TRACKING_AUTH
+            #   value: "kubernetes-namespaced"
+            # - name: MLFLOW_WORKSPACE
+            #   value: "<your-namespace>"
+            # - name: MLFLOW_EXPERIMENT_NAME
+            #   value: "claude-code-traces"
+            # - name: MLFLOW_TRACKING_INSECURE_TLS
+            #   value: "true"
+            # ===========================================
+            # Context Window Configuration (Optional)
+            # ===========================================
+            # Uncomment and adjust if your model's context window differs from defaults.
+            # - name: CLAUDE_CODE_AUTO_COMPACT_WINDOW
+            #   value: "32768"
+            # - name: CLAUDE_CODE_MAX_OUTPUT_TOKENS
+            #   value: "4000"
+            # - name: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
+            #   value: "85"
+            # ===========================================
             # Claude Code Configuration
             # ===========================================
             - name: MCP_CONFIG_FILE
@@ -202,9 +227,10 @@ spec:
             - name: mcp-config
               mountPath: /etc/mcp
               readOnly: true
-            # Mount settings.json to set default model
+            # Stage settings.json at a read-only path; the entrypoint copies it
+            # to the writable PVC so mlflow autolog can update it at runtime
             - name: claude-settings
-              mountPath: /workspace/.claude/settings.json
+              mountPath: /etc/claude-config/settings.json
               subPath: settings.json
           resources:
             requests:

agents/claude-code/deployment/deployment-vertex.yaml

@@ -201,6 +201,21 @@ spec:
             - name: GOOGLE_APPLICATION_CREDENTIALS
               value: "/var/secrets/google/key.json"
             # ===========================================
+            # MLflow Tracing (Optional)
+            # ===========================================
+            # Uncomment and configure to enable.
+            # See the MLflow Tracing section in ../README.md for details.
+            # - name: MLFLOW_TRACKING_URI
+            #   value: "https://mlflow.<rhoai-namespace>.svc:8443/mlflow"
+            # - name: MLFLOW_TRACKING_AUTH
+            #   value: "kubernetes-namespaced"
+            # - name: MLFLOW_WORKSPACE
+            #   value: "<your-namespace>"
+            # - name: MLFLOW_EXPERIMENT_NAME
+            #   value: "claude-code-traces"
+            # - name: MLFLOW_TRACKING_INSECURE_TLS
+            #   value: "true"
+            # ===========================================
             # Claude Code Configuration
             # ===========================================
             - name: MCP_CONFIG_FILE
@@ -226,7 +241,7 @@ spec:
               mountPath: /var/secrets/google
               readOnly: true
             - name: claude-settings
-              mountPath: /workspace/.claude/settings.json
+              mountPath: /etc/claude-config/settings.json
               subPath: settings.json
           resources:
             requests:

agents/claude-code/deployment/deployment-vllm.yaml

@@ -154,7 +154,7 @@ spec:
             # For internal service: http://vllm-service.namespace.svc.cluster.local
             # For external route: https://vllm-route.apps.cluster.domain
             - name: ANTHROPIC_BASE_URL
-              value: YOUR_VLLM_URL
+              value: "http://YOUR_VLLM_SERVICE.namespace.svc.cluster.local"
             # vLLM doesn't validate API keys, but Claude Code requires one
             - name: ANTHROPIC_API_KEY
               value: "fake"
@@ -174,6 +174,31 @@ spec:
             - name: ANTHROPIC_DEFAULT_OPUS_MODEL
               value: "YOUR_MODEL_ID"
             # ===========================================
+            # MLflow Tracing (Optional)
+            # ===========================================
+            # Uncomment and configure to enable.
+            # See the MLflow Tracing section in ../README.md for details.
+            # - name: MLFLOW_TRACKING_URI
+            #   value: "https://mlflow.<rhoai-namespace>.svc:8443/mlflow"
+            # - name: MLFLOW_TRACKING_AUTH
+            #   value: "kubernetes-namespaced"
+            # - name: MLFLOW_WORKSPACE
+            #   value: "<your-namespace>"
+            # - name: MLFLOW_EXPERIMENT_NAME
+            #   value: "claude-code-traces"
+            # - name: MLFLOW_TRACKING_INSECURE_TLS
+            #   value: "true"
+            # ===========================================
+            # Context Window Configuration (Optional)
+            # ===========================================
+            # Uncomment and adjust if your model's context window differs from defaults.
+            # - name: CLAUDE_CODE_AUTO_COMPACT_WINDOW
+            #   value: "32768"
+            # - name: CLAUDE_CODE_MAX_OUTPUT_TOKENS
+            #   value: "4000"
+            # - name: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
+            #   value: "85"
+            # ===========================================
             # Claude Code Configuration
             # ===========================================
             - name: MCP_CONFIG_FILE
@@ -194,9 +219,10 @@ spec:
             - name: mcp-config
               mountPath: /etc/mcp
               readOnly: true
-            # Mount settings.json to set default model
+            # Stage settings.json at a read-only path; the entrypoint copies it
+            # to the writable PVC so mlflow autolog can update it at runtime
             - name: claude-settings
-              mountPath: /workspace/.claude/settings.json
+              mountPath: /etc/claude-config/settings.json
               subPath: settings.json
           resources:
             requests:

agents/claude-code/deployment/deployment.yaml

@@ -166,6 +166,21 @@ spec:
             #   value: "https://your-endpoint/v1"
             # - name: CLAUDE_MODEL
             #   value: "your-model"
+            # ===========================================
+            # MLflow Tracing (Optional)
+            # ===========================================
+            # Uncomment and configure to enable.
+            # See the MLflow Tracing section in ../README.md for details.
+            # - name: MLFLOW_TRACKING_URI
+            #   value: "https://mlflow.<rhoai-namespace>.svc:8443/mlflow"
+            # - name: MLFLOW_TRACKING_AUTH
+            #   value: "kubernetes-namespaced"
+            # - name: MLFLOW_WORKSPACE
+            #   value: "<your-namespace>"
+            # - name: MLFLOW_EXPERIMENT_NAME
+            #   value: "claude-code-traces"
+            # - name: MLFLOW_TRACKING_INSECURE_TLS
+            #   value: "true"
             - name: MCP_CONFIG_FILE
               value: "/etc/mcp/config.json"
             # WARNING: Setting SKIP_PERMISSIONS=true disables all Claude permission checks.
@@ -185,7 +200,7 @@ spec:
               mountPath: /etc/mcp
               readOnly: true
             - name: claude-settings
-              mountPath: /workspace/.claude/settings.json
+              mountPath: /etc/claude-config/settings.json
               subPath: settings.json
           resources:
             requests:

agents/claude-code/deployment/entrypoint.sh

@@ -184,6 +184,17 @@ setup_config_dir() {
         ln -sfn "${CLAUDE_CONFIG_DIR}" "${home_claude_dir}"
     fi
 
+    # Copy staged settings.json from ConfigMap mount to writable PVC location.
+    # ConfigMap subPath mounts are read-only, but mlflow autolog needs to write
+    # hook configuration into settings.json. Staging at /etc/claude-config/ and
+    # copying here makes the file writable.
+    local staged_settings="/etc/claude-config/settings.json"
+    local target_settings="${CLAUDE_CONFIG_DIR}/settings.json"
+    if [[ -f "${staged_settings}" ]]; then
+        cp "${staged_settings}" "${target_settings}"
+        log_info "Copied settings from ${staged_settings} to ${target_settings}"
+    fi
+
     log_info "Claude config directory: ${CLAUDE_CONFIG_DIR}"
     log_info "Symlink: ${home_claude_dir} -> ${CLAUDE_CONFIG_DIR}"
 }