docs: document Redis as a required dependency

[vineetvora-scale]

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 Summary

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.

Confidence Score: 5/5

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.

Important Files Changed

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.

Flowchart

%%{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

Loading

%%{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

Loading

_{Reviews (2): Last reviewed commit: "Merge branch 'main' into docs/redis-loca..." | Re-trigger Greptile}

[danielmillerp]

awesome looks great !!!