feat: image refactor

docs/content/Deploying/DocsGPT-Settings.mdx

@@ -217,6 +217,17 @@ STT_ENABLE_DIARIZATION=false
 
 `faster_whisper` is an optional backend dependency. Install it in the Python environment used by the DocsGPT API and worker before selecting this provider.
 
+## Agent Image Settings
+
+Agent avatars uploaded to DocsGPT must be valid PNG, JPEG, GIF, or WebP files.
+The decoded image and its file extension must agree; SVG and other formats are
+rejected. These limits apply before the image is written to local or S3 storage.
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `AGENT_IMAGE_MAX_BYTES` | `5000000` | Maximum encoded avatar file size in bytes. |
+| `AGENT_IMAGE_MAX_PIXELS` | `16777216` | Maximum decoded width × height, limiting decompression-bomb images. |
+
 ## Authentication Settings
 
 DocsGPT includes a JWT (JSON Web Token) based authentication feature for managing sessions or securing local deployments while allowing access.
@@ -237,27 +248,28 @@ The `AUTH_TYPE` setting in your `.env` file or `settings.py` determines the auth
 Add the following to your `.env` file (or set in `settings.py`):
 
 ```env
+# Shared signing key (required in production for every authentication mode)
+JWT_SECRET_KEY=<long-random-value>
+
 # No authentication (default)
 AUTH_TYPE=None
 
 # OR: Simple JWT (shared token)
 AUTH_TYPE=simple_jwt
-JWT_SECRET_KEY=your_secret_key_here
 
 # OR: Session JWT (per-user/session tokens)
 AUTH_TYPE=session_jwt
-JWT_SECRET_KEY=your_secret_key_here
 
 # OR: SSO via an OpenID Connect provider (Authentik, Keycloak, Okta, ...)
 AUTH_TYPE=oidc
 OIDC_ISSUER=https://auth.example.com/application/o/docsgpt/
 OIDC_CLIENT_ID=your_client_id
 OIDC_FRONTEND_URL=https://docsgpt.example.com
-JWT_SECRET_KEY=your_secret_key_here
 ```
 
-- If `AUTH_TYPE` is set to `simple_jwt` or `session_jwt`, a `JWT_SECRET_KEY` is required.
-- If `JWT_SECRET_KEY` is not set, DocsGPT will generate one and store it in `.jwt_secret_key` in the project root.
+- `JWT_SECRET_KEY` signs authentication tokens where applicable and opaque agent-avatar capabilities in every authentication mode, including no-auth mode.
+- Cloud and production deployments must set a strong `JWT_SECRET_KEY`, shared unchanged by every API and worker replica. Startup fails rather than creating replica-local keys when it is missing.
+- Local development may omit it. DocsGPT atomically generates an owner-readable `.jwt_secret_key` in the project root and reuses it on later starts.
 
 #### How Each Method Works
 
@@ -283,7 +295,7 @@ JWT_SECRET_KEY=your_secret_key_here
 
 - Always keep your `JWT_SECRET_KEY` secure and private.
 - If you set it manually, use a strong, random string.
-- If not set, DocsGPT will generate a secure key and persist it in `.jwt_secret_key`.
+- Keep the value stable. Rotating it invalidates active JWTs and previously generated agent-avatar URLs.
 
 #### Checking Current Auth Type
 
@@ -317,7 +329,7 @@ By default DocsGPT stores files locally. Set `STORAGE_TYPE=s3` to use Amazon S3
 | `S3_REGION` | Region (use `auto` for Cloudflare R2) | — |
 | `S3_ENDPOINT_URL` | Custom endpoint for S3-compatible services; leave unset for AWS S3 | — |
 | `S3_PATH_STYLE` | Use path-style addressing (required by most non-AWS services) | `false` |
-| `URL_STRATEGY` | `backend` (proxy through API) or `s3` (direct object URLs) | `backend` |
+| `URL_STRATEGY` | Artifact-download delivery: `backend` proxies bytes through the API; `s3` returns short-lived presigned object URLs. Agent avatars always use capability URLs and, with S3 storage, redirect to a size-checked presigned URL. | `backend` |
 
 ### AWS S3
 

docs/content/Deploying/Kubernetes-Deploying.mdx

@@ -33,9 +33,11 @@ The `deployment/k8s` folder contains the necessary deployment and service config
    cd docsgpt/deployment/k8s
    ```
 
-2. **Configure Secrets (optional)**
+2. **Configure Secrets**
 
-   Ensure that you have all the necessary secrets in `docsgpt-secrets.yaml`. Update it with your secrets before applying if you want. By default we will use qdrant as a vectorstore and public docsgpt llm as llm for inference.
+   Add a strong, base64-encoded `JWT_SECRET_KEY` to `docsgpt-secrets.yaml` before applying it. The API and worker deployments share this value so authentication tokens and agent-avatar capability URLs remain valid across pod restarts and replicas. You can generate a value with `openssl rand -hex 32 | base64`.
+
+   Configure any additional provider secrets you need. By default, the manifests use Qdrant as the vector store and the public DocsGPT LLM for inference.
    
    Alternatively, you can use [Neon](https://get.neon.com/docsgpt) as an easy way to set up your vector store with pgvector, which is highly recommended for quick deployments.
 
@@ -106,4 +108,4 @@ If you encounter any issues, you can check the logs of the pods for more details
 kubectl logs <pod-name>
 ```
 
-Replace `<pod-name>` with the actual name of your DocsGPT pod.
+Replace `<pod-name>` with the actual name of your DocsGPT pod.

docs/content/Deploying/OIDC-SSO.mdx

@@ -45,7 +45,7 @@ Sessions last `OIDC_SESSION_LIFETIME_SECONDS` (8 hours by default) and renew wit
 | `OIDC_ALLOWED_GROUPS` | no | — | Comma-separated group allowlist. Unset, any authenticated IdP user may sign in — see [Restricting sign-in by group](#restricting-sign-in-by-group). |
 | `OIDC_ADMIN_GROUPS` | no | — | Comma-separated groups whose members are granted the global `admin` role. Re-checked at every login and renewal — see [Granting admin via groups](#granting-admin-via-groups). |
 | `OIDC_GROUPS_CLAIM` | no | `groups` | ID-token/userinfo claim carrying the user's group membership. |
-| `JWT_SECRET_KEY` | recommended | auto-generated | Signs DocsGPT session tokens. Set it explicitly in production — required when running multiple API replicas. |
+| `JWT_SECRET_KEY` | required in production | auto-generated for local development | Signs DocsGPT session tokens and agent-avatar capabilities. Every API and worker replica must use the same value. |
 
 `SCIM_ENABLED` and `SCIM_TOKEN` are listed in the [SCIM section](#scim-user-provisioning).