Merge branch 'main' into feature/multi-cloud

docs/REFERENCE.md

@@ -631,6 +631,15 @@ retry:
 4. 40 seconds
 5. 80 seconds (capped at 3 minutes)
 
+### Global Settings (`argocd-cm`)
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| `application.resourceTrackingMethod` | `annotation` | Track resources via annotations |
+| `timeout.reconciliation` | `60s` | Reconciliation interval |
+| `admin.enabled` | `true` | Enable admin account |
+| `git.submodule.enabled` | `false` | Disable git submodule checkout — submodules are not needed for manifest generation |
+
 ---
 
 ## Infrastructure Components
@@ -1098,6 +1107,33 @@ kubectl get secret keycloak-client-<app> -n keycloak -o jsonpath='{.metadata.ann
 
 **See**: [Developer Guide - Adding a New Keycloak Client](DEVELOPER-GUIDE.md#adding-a-new-keycloak-client)
 
+### Karpor
+
+**Chart**: `karpor` from `https://kusionstack.github.io/charts`
+**Version**: 0.7.6 (app v0.6.4)
+**Namespace**: `karpor`
+**Sync Wave**: 1
+
+**Purpose**: Kubernetes visualization and intelligence tool. Provides cross-cluster resource search, compliance checking, and topology visualization. Gives platform engineers a unified view of all cluster resources and their relationships.
+
+**Architecture** (4 components):
+- **Server** — main Karpor API/UI (port 7443)
+- **Syncer** — syncs cluster state into the search index
+- **ElasticSearch** — search backend for resource indexing
+- **etcd** — persistent key-value store (10Gi PVC)
+
+**Configuration** (`infra/values/base/karpor-values.yaml`):
+- `namespaceEnabled: false` — ArgoCD manages namespace creation
+- Default resource limits tuned for small clusters
+- ElasticSearch: 2 CPU / 4Gi memory (the heaviest component)
+- AI features available but not enabled (requires `server.ai.authToken` + backend config)
+
+**Access**: Port-forward to reach the UI:
+```bash
+kubectl port-forward svc/karpor-release-server -n karpor 7443:7443
+# Open https://localhost:7443
+```
+
 ### Renovate
 
 **Chart**: `renovate` (OCI: `ghcr.io/renovatebot/charts`)
@@ -1545,7 +1581,23 @@ Forward to Application (localhost:3000)
 Application processes request
 ```
 
-**See**: [Developer Guide - Enabling Authentication](DEVELOPER-GUIDE.md#enabling-authentication-for-applications) for usage examples.
+#### Forwarded Headers
+
+After successful authentication, the sidecar injects user identity as HTTP headers before forwarding the request to the application container:
+
+| Header | Description | Auth Modes |
+|--------|-------------|------------|
+| `X-Auth-User` | Username or display name | Token, OIDC, MCP |
+| `X-Auth-Email` | User email address | OIDC |
+| `X-Auth-Subject` | OIDC `sub` claim (stable user ID) | OIDC, MCP |
+| `X-Auth-Groups` | Comma-separated group memberships | OIDC (if `groups` scope) |
+| `X-Auth-Token` | The validated access token | All modes |
+
+These headers are trustworthy because the auto-generated `NetworkPolicy` restricts pod ingress to the sidecar port only — external traffic cannot reach the application container directly, so headers cannot be spoofed.
+
+Applications should read these headers to obtain authenticated user information (e.g. for display, authorisation decisions, or audit logging) instead of implementing their own authentication.
+
+**See**: [Developer Guide - Accessing Authenticated User Information](DEVELOPER-GUIDE.md#accessing-authenticated-user-information) for code examples.
 
 ---