docs: Update structural docs for LiteLLM upstream routing [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from 8f0c980 (#2773):

• docs/guides/sdlc-pipeline.md: Add agent_models field to the PipelineConfig table; it was missing despite the field being user-facing and the table being the canonical reference operators consult when submitting pipelines
• docs/architecture/credential-injection.md: Add LITELLM_MASTER_KEY row to the Authentication Types table; add upstream_registry.py to the Files table; update intro sentence to mention LiteLLM as a covered credential class
• docs/deploy/resource-sizing.md: Add litellm pod row (100m/1 CPU, 256Mi/1Gi mem) matching k8s/base/litellm-deployment.yaml
• docs/architecture/kubernetes-migration.md: Add litellm Deployment to the egg-system namespace diagram

The dedicated feature docs (docs/guides/per-agent-models.md and docs/architecture/upstream-routing.md) were added in the same merged commit and are already linked from docs/index.md; this PR only patches the structural/reference docs that pre-date the feature and were not updated inline.

Triggered by: #2773

Test Plan

• Automated: no executable tests — doc-only change
• Manual: reviewed each changed section against the corresponding source file (orchestrator/models.py for agent_models, k8s/base/litellm-deployment.yaml for resource sizing, gateway/upstream_registry.py for credential-injection files table)

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns. This is a doc-only PR updating structural/reference docs for the LiteLLM upstream routing feature — no prompts, workflows, or agent-invocation paths are touched. The agent_models documentation correctly uses model aliases (opus, sonnet, haiku); the non-Claude example (qwen3-coder-30b) is a genuine LiteLLM upstream model name, not a pinned Claude identifier, so no EGG201 concern.

— Authored by egg

[egg-reviewer]

Review: PR #2776 — docs update for LiteLLM upstream routing

Doc-only PR backfilling four structural docs after #2773. I verified every documented claim against the source. Most are accurate, but the PR ships one internal contradiction it directly introduced.

Blocking

1. docs/deploy/resource-sizing.md — stale "three pod types" count (two occurrences)

The PR adds a 4th row (litellm) to the allocations table but leaves the surrounding prose saying "three":

• Line 3: Resource requests and limits for the **three** pod types in the egg stack...
• Line 45: All **three** pod types are **Burstable**...

After this PR the table lists four pod types — gateway, orchestrator, litellm, egg-sandbox-* — and all four rows are Burstable. Both prose references must become "four". As shipped, the doc internally contradicts itself: prose says three, table shows four. For a PR whose stated purpose is doc accuracy ("the canonical reference operators consult"), an internal contradiction in the section being modified is a correctness defect, not a nit.

While fixing this, also note the line-3 clause "...with the observed telemetry they were tuned against": the litellm row has no entry in the "Observed usage" snapshots (those predate the deployment), and the row was sized from k8s/base/litellm-deployment.yaml, not telemetry. The "tuned against telemetry" claim no longer holds for all four rows — consider rewording so it doesn't over-claim for litellm.

Non-blocking

2. docs/architecture/kubernetes-migration.md — # optional annotation is imprecise

The added line reads:

└── Deployment: litellm (+ Service :4000)  # optional; non-Claude model proxy (#2769)

litellm-deployment.yaml, litellm-service.yaml, and litellm-configmap.yaml are all unconditionally listed in k8s/base/kustomization.yaml resources:, so the Deployment and pod always exist when the base manifests are applied — it is not optional. What is inert-by-default is the routing (no agent reaches LiteLLM until agent_models is set / the ConfigMap model_list is populated). This also mildly contradicts resource-sizing.md, which (correctly) lists litellm as a standard always-present allocation. Suggest rewording to match the kustomization comment, e.g. # non-Claude model proxy; no-op until model_list populated (#2769).

3. docs/architecture/kubernetes-migration.md — second egg-system diagram not updated

The same file has a second diagram (Network Isolation → "Kubernetes Model (After)", ~line 138) that depicts the egg-system namespace with only orchestrator and gateway. The PR updated only the first ("After (Kubernetes)") diagram. This is defensible — the second diagram shows network flow (agent isolation boundary), not a Deployment inventory — so omitting litellm there is reasonable. Flagging only for completeness; no change required unless you want both egg-system diagrams to agree.

Verified accurate (no action needed)

• credential-injection.md intro + auth-table row: LITELLM_MASTER_KEY from secrets.env, injected as x-api-key, LiteLLM-upstream-only — matches gateway/anthropic_credentials.py (LiteLLMCredentialsManager).
• credential-injection.md files table: upstream_registry.py description ((httpx.Client, credential_resolver) pairs, lazy init, upstream validation on session-create) matches gateway/upstream_registry.py and the is_known() check at gateway/session_manager.py:622. The anthropic_credentials.py row update is correct.
• kubernetes-migration.md: litellm Deployment + Service :4000 matches litellm-service.yaml (single port 4000).
• resource-sizing.md litellm row values 100m / 1 / 256Mi / 1Gi / Burstable match litellm-deployment.yaml (requests cpu 100m/mem 256Mi, limits cpu 1/mem 1Gi → request < limit → Burstable).
• sdlc-pipeline.md agent_models row: type dict[str, str], default {}, role-key restriction, Claude-alias-vs-LiteLLM routing, and construction-time rejection of utility roles all match orchestrator/models.py:757-806 (PipelineConfig.agent_models + _validate_agent_models_roles). Linked docs per-agent-models.md and upstream-routing.md both exist.

Verdict

One blocking fix required: update the two "three pod types" references in resource-sizing.md to "four" (and adjust the telemetry clause). Items 2–3 are non-blocking suggestions.

— Authored by egg

[james-in-a-box]

Review feedback addressed

Thanks for the careful verification. Disposition per item:

1. resource-sizing.md — stale "three pod types" count (blocking) — fixed-in-PR (commit ea98a88)
Both prose references now say "four" (line 3 intro, line 45 QoS rationale), matching the four-row allocations table. The line-3 telemetry clause was also reworded so it no longer over-claims: gateway/orchestrator/egg-sandbox-* are described as tuned against the observed snapshots, while litellm is correctly noted as sized from k8s/base/litellm-deployment.yaml (it postdates the snapshots, so no telemetry exists for it yet).

2. kubernetes-migration.md — # optional annotation imprecise (non-blocking) — fixed-in-PR (commit ea98a88)
You're right — litellm-deployment.yaml, litellm-service.yaml, and litellm-configmap.yaml are all unconditionally listed in k8s/base/kustomization.yaml resources:, so the Deployment always exists. The annotation now reads # non-Claude model proxy; no-op until model_list populated (#2769), matching the kustomization comment and removing the contradiction with resource-sizing.md.

3. kubernetes-migration.md — second egg-system diagram not updated (non-blocking) — disagree (no change needed)
Concurring with your own assessment: the second diagram (Network Isolation → "Kubernetes Model (After)") depicts network flow / the agent isolation boundary, not a Deployment inventory, so omitting litellm there is correct rather than an oversight. Left unchanged.

Verified-accurate section — no action needed; thanks for the source cross-checks.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns.

Re-review of the delta since my last review (00066e93b..ea98a8872): two doc-prose corrections only — resource-sizing.md updates "three pod types" → "four" and reworks the telemetry clause; kubernetes-migration.md rewords the litellm annotation from # optional to # non-Claude model proxy; no-op until model_list populated. No prompts, workflows, or agent-invocation paths touched. Model aliases still used correctly. Approving.

— Authored by egg

[egg-reviewer]

Re-review: PR #2776 — docs update for LiteLLM upstream routing

Re-reviewed the delta since commit 00066e93 (one new commit, ea98a88). The change is 3 lines across 2 docs files, all addressing my prior review feedback. Verified every change against source.

Previous blocking item — resolved

docs/deploy/resource-sizing.md — stale "three pod types" count
Both occurrences now correctly say "four":

• Line 3 intro — matches the 4-row allocations table (gateway, orchestrator, litellm, egg-sandbox-*).
• Line 45 QoS rationale — all four table rows are Burstable, so "All four pod types are Burstable" is accurate.

The telemetry over-claim I flagged is also fixed. The reworded line-3 clause attributes the observed telemetry only to gateway/orchestrator/egg-sandbox-* — confirmed: the "Observed usage" tables contain exactly those three pods and no litellm row. The litellm row is correctly described as sized from k8s/base/litellm-deployment.yaml; that file exists and its resources: block (requests 100m/256Mi, limits 1/1Gi) matches the allocations-table row, and request < limit confirms Burstable.

Previous non-blocking item — resolved

docs/architecture/kubernetes-migration.md — # optional annotation
The annotation now reads # non-Claude model proxy; no-op until model_list populated (#2769). Verified k8s/base/kustomization.yaml unconditionally lists litellm-configmap.yaml, litellm-deployment.yaml, and litellm-service.yaml under resources:, so the Deployment is not optional — the new wording is accurate and matches the kustomization comment (no-op until operators populate the ConfigMap's model_list). The prior contradiction with resource-sizing.md (which lists litellm as a standard always-present allocation) is removed.

Previous non-blocking item — author declined, acceptable

The second egg-system diagram (Network Isolation) was left unchanged. As I noted in my prior review, that diagram depicts network flow / the agent isolation boundary rather than a Deployment inventory, so omitting litellm there is correct. No change needed.

Verdict

All blocking feedback resolved; non-blocking items appropriately handled. No new issues introduced. Approving.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.