docs: document Redis as a required dependency (#343)

## Summary

Redis is required at runtime for any agent that streams or sends
messages, but the docs presented it as optional. Locally that's masked —
the Docker stack starts Redis automatically — and in deployment
`REDIS_URL` read like an optional custom secret. The result: an agent
can pass local testing, deploy successfully, and then fail the first
time it streams, with no clear signal that Redis was the missing piece.

This PR makes the docs tell the truth in every place a developer
encounters Redis or credential mapping.

## What changed

| File | Change |
|------|--------|
| `README.md` | Prerequisites: Redis is required; the Docker stack
starts it automatically (no local install); a local Redis conflicts on
port 6379 |
| `CLAUDE.md` | Backend Services: mark Redis as required and
auto-started, with the port-conflict note |
| `concepts/streaming.md` | Note that streaming and messaging are
delivered through Redis (required) |
| `configuration.md` | Credentials Mapping: `REDIS_URL` is a required
credential, not optional |
| `deployment/overview.md` | Add Redis / `REDIS_URL` to deployment
prerequisites |
| `deployment/cicd.md` | Call out `REDIS_URL` as a required baseline
secret; fix the misleading `redis://localhost/` example value |

## Scope

**Docs only — no code or template changes.** This PR documents the
existing requirement; it does not change runtime behavior.

## Follow-ups (not in this PR)

- **SDK templates label `REDIS_URL` "Optional".** The scaffolding
templates and example manifests in `scale-agentex-python` still present
`REDIS_URL` as optional (and apply it inconsistently). They should be
relabeled as required and made consistent.
- **Fail fast on unreachable Redis.** The SDK connects to Redis lazily
and without a connect timeout, so a missing/unreachable Redis surfaces
as a silent hang on first use rather than a clear startup error. A short
connect timeout + an actionable error message would make the failure
self-documenting. (Behavior change — needs SDK-owner sign-off.)
- **Provide `REDIS_URL` automatically at deploy.** Longer term, the
platform could inject `REDIS_URL` the way it already provides other
backing-service connectivity, so agent authors don't configure it by
hand.

## Verification

`make build-docs` passes; all internal doc links resolve.

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This is a docs-only PR that corrects the documentation to accurately
reflect that Redis is a required runtime dependency for any agent that
streams or sends messages, not an optional one. Previously, local
development masked this requirement because the Docker stack auto-starts
Redis, while `REDIS_URL` read as an optional custom secret in deployment
docs.

- **Six documentation files updated** across README, CLAUDE.md,
concepts, configuration, and deployment guides to consistently label
Redis as required, explain that the Docker stack provides it locally,
and warn about port 6379 conflicts.
- **A misleading `redis://localhost/` example value in `cicd.md`** is
replaced with a placeholder that makes clear a real connection string is
needed in production.

<details><summary><h3>Confidence Score: 5/5</h3></summary>

Docs-only change with no runtime behavior modifications; safe to merge.

All six files contain purely documentation edits. Internal anchor links
resolve correctly, cross-file relative paths are correct, the fixed
redis://localhost/ placeholder is a clear improvement, and the new notes
are consistent with one another. No code paths are touched.

No files require special attention.
</details>

<details><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| README.md | Adds a callout in Prerequisites making Redis required,
clarifying the Docker stack handles it, and linking to the
Troubleshooting section for port-conflict resolution. Anchor target
(#redis-port-conflict) matches the existing section heading. |
| CLAUDE.md | Annotates the port-6379 entry to mark Redis as required
and auto-started, with a link to the existing Redis Port Conflicts
section. Anchor matches the actual heading. |
| agentex/docs/docs/concepts/streaming.md | Adds a MkDocs admonition
note explaining that streaming is delivered via Redis streams and is
required, with a cross-reference to the deployment overview. Relative
path ../deployment/overview.md#prerequisites is correct. |
| agentex/docs/docs/configuration.md | Adds a note after the Credentials
Mapping YAML example clarifying that REDIS_URL is required. Note
correctly directs users to also sync it alongside their own secrets,
with a link to the deployment overview. |
| agentex/docs/docs/deployment/cicd.md | Adds a required-baseline-secret
note for REDIS_URL and fixes the misleading redis://localhost/
placeholder in the Secrets YAML example to a proper production-oriented
placeholder with TLS and non-TLS examples. |
| agentex/docs/docs/deployment/overview.md | Adds Redis as an explicit
prerequisite bullet in the deployment guide, contrasting local-dev
auto-provisioning with the need to configure it manually in production.
|

</details>

<details><summary><h3>Flowchart</h3></summary>

<a href="#gh-light-mode-only">

```mermaid
%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Dev["Developer writes agent\n(streaming / messaging)"] --> Local["Local development\n./dev.sh / make dev"]
    Dev --> Deploy["Production deployment\nKubernetes cluster"]

    Local --> DockerStack["Docker Compose stack\nauto-starts Redis\non port 6379"]
    DockerStack --> LocalRedis["Redis @ localhost:6379\n(no install needed)"]
    DockerStack -- "port conflict if" --> LocalRedisRunning["Local Redis already running\n→ stop it first"]

    Deploy --> SecretsSync["agentex secrets sync\nwith prod-secrets.yaml"]
    SecretsSync --> REDIS_URL["REDIS_URL_SECRET\n= your-redis-connection-string\n(TLS: rediss://host:6380)"]
    REDIS_URL --> ProdRedis["Reachable Redis instance\nrequired — none auto-provided"]

    LocalRedis --> AgentLocal["Agent streams & messages\n✅ work locally"]
    ProdRedis --> AgentProd["Agent streams & messages\n✅ work in production"]

    style LocalRedis fill:#4CAF50,color:#fff
    style ProdRedis fill:#4CAF50,color:#fff
    style LocalRedisRunning fill:#F44336,color:#fff
```

</a>
<a href="#gh-dark-mode-only">

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    Dev["Developer writes agent\n(streaming / messaging)"] --> Local["Local development\n./dev.sh / make dev"]
    Dev --> Deploy["Production deployment\nKubernetes cluster"]

    Local --> DockerStack["Docker Compose stack\nauto-starts Redis\non port 6379"]
    DockerStack --> LocalRedis["Redis @ localhost:6379\n(no install needed)"]
    DockerStack -- "port conflict if" --> LocalRedisRunning["Local Redis already running\n→ stop it first"]

    Deploy --> SecretsSync["agentex secrets sync\nwith prod-secrets.yaml"]
    SecretsSync --> REDIS_URL["REDIS_URL_SECRET\n= your-redis-connection-string\n(TLS: rediss://host:6380)"]
    REDIS_URL --> ProdRedis["Reachable Redis instance\nrequired — none auto-provided"]

    LocalRedis --> AgentLocal["Agent streams & messages\n✅ work locally"]
    ProdRedis --> AgentProd["Agent streams & messages\n✅ work in production"]

    style LocalRedis fill:#4CAF50,color:#fff
    style ProdRedis fill:#4CAF50,color:#fff
    style LocalRedisRunning fill:#F44336,color:#fff
```

</a>
</details>

<sub>Reviews (2): Last reviewed commit: ["Merge branch &#39;main&#39;
into
docs/redis-loca..."](25eea5f)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=40858238)</sub>

<!-- /greptile_comment -->

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vineetvora-scale

CLAUDE.md

@@ -93,7 +93,7 @@ When running `make dev` in agentex/, the following services start:
 - **Port 5003**: FastAPI backend server
 - **Port 5432**: PostgreSQL (application database)
 - **Port 5433**: PostgreSQL (Temporal database)
-- **Port 6379**: Redis (streams and caching)
+- **Port 6379**: Redis (streams and caching) — required for streaming/messaging; the Docker stack starts it automatically, and a local Redis will conflict on this port (see [Redis Port Conflicts](#redis-port-conflicts))
 - **Port 27017**: MongoDB (document storage)
 - **Port 7233**: Temporal server
 - **Port 8080**: Temporal Web UI

README.md

@@ -53,6 +53,8 @@ https://github.com/user-attachments/assets/9badad0d-f939-4243-ba39-68cafdae0078
 
 - **Install Python 3.12+ (Required)**: https://www.python.org/downloads/
 
+> **Redis is required.** Agentex uses Redis for streaming and messaging. You do **not** need to install it yourself — the Docker stack (`./dev.sh` / `make dev`) starts it for you. If you already run Redis locally it will conflict on port `6379`, so stop it first (see [Troubleshooting](#redis-port-conflict)).
+
 #### macOS/Linux
 
 ```bash

agentex/docs/docs/concepts/streaming.md

@@ -8,6 +8,9 @@ Streaming enables real-time delivery of messages as they're being generated, pro
 
 Agentex decouples streaming from LLM provider streaming. You're not limited to streaming LLM responses - you can stream any content: progress updates, status messages, multi-step workflows, or custom notifications.
 
+!!! note "Streaming requires Redis"
+    Streaming and messaging are delivered through Redis streams, so a reachable Redis is **required** for any agent that streams or sends messages. Locally, the Docker stack starts Redis for you. In deployment, the `REDIS_URL` environment variable must point at your Redis instance — see [Deploying Your Agent](../deployment/overview.md#prerequisites).
+
 
 
 ## Streaming by Agent Type

agentex/docs/docs/configuration.md

@@ -125,6 +125,9 @@ agent:
       secret_key: "connection-string"
 ```
 
+!!! note "`REDIS_URL` is a required credential for streaming/messaging"
+    The examples above are your *own* secrets, but `REDIS_URL` is required by the platform for any agent that streams or sends messages — it is not optional. Map it here so it is synced to your deployment. See [Deploying Your Agent](deployment/overview.md#prerequisites).
+
 ### Key Points:
 
 - **`name`**: Must be unique across your organization (used for task routing)

agentex/docs/docs/deployment/cicd.md

@@ -187,6 +187,9 @@ This will build and push your agent image to `your-registry-here/your-repository
 
 Agents require credentials (API keys, database URLs, etc.) that live in your secrets manager (AWS Secrets Manager, Azure Key Vault, etc.), not in code. The `agentex secrets sync` command bridges your secrets manager to Kubernetes by injecting credentials directly into the target namespace.
 
+!!! note "`REDIS_URL` is a required baseline secret"
+    `agentex secrets sync` is not only for your own custom credentials. Any agent that streams or sends messages also needs `REDIS_URL` synced as a secret (shown as `REDIS_URL_SECRET` below) — it is **required**, not optional. Without it, the agent starts up fine but fails the first time it streams. See [Deploying Your Agent](overview.md#prerequisites).
+
 **Authentication requirements**: Your CI/CD runner (e.g., GitHub Actions runner) needs access to both your secrets manager (to read secrets) and your Kubernetes cluster (to create Secret objects).
 
 **How it works**: The workflow fetches secrets from your secrets manager and constructs a YAML file containing the credentials and image pull secrets. This YAML is then passed to the sync command, which creates Kubernetes Secret objects in your namespace.
@@ -199,7 +202,7 @@ credentials:
     api-key-jdoe: abc12345
     api-key-jsmith: def6789
   REDIS_URL_SECRET:
-    redis-url-secret: redis://localhost/
+    redis-url-secret: <your-redis-connection-string>  # e.g. rediss://<host>:6380 (TLS) or redis://<host>:6379
 imagePullSecrets:
   pull-secret-1:
     registry: registry-url

agentex/docs/docs/deployment/overview.md

@@ -10,6 +10,7 @@ Before deploying, you need:
 - **Cluster access** - Contact your cluster administrators for access
 - **Namespace** - Get a namespace provisioned for your agent
 - **Permissions** - RBAC access to create deployments and secrets
+- **Redis** - A reachable Redis instance. Agents require it for streaming and messaging, so its connection string must be provided as the `REDIS_URL` secret (synced in step 2 below). Unlike local development — where the Docker stack provides Redis automatically — a deployed agent has no Redis unless you configure one.
 
 Verify your setup:
 ```bash