docs(templates): one private-index doc instead of the same comment 38 times

Two problems with how the private-index wiring was documented.

TEAM-RUNBOOK is not public, so pointing generated agent Dockerfiles at it sends the
reader somewhere they cannot go. Replaced with the two references that do resolve:
SGPINF-1568, and the PRD, both linked from the new doc.

And the explanation was pasted into all 38 templates — roughly twenty comment lines
apiece, restating the named-index requirement, the percent-decode, and the UV_INDEX
pinning. That is 38 copies to keep in sync, and it buried the four lines of shell that
actually do something.

Now: PRIVATE_INDEX.md carries it once, and each Dockerfile keeps a short pointer plus
the ticket. Net 608 deletions against 190 insertions.

The pointer names the doc rather than giving a relative path, deliberately. These
Dockerfiles are copied into generated agent repos, where `templates/PRIVATE_INDEX.md`
would dangle; SGPINF-1568 resolves from anywhere and the filename is findable.

Also dropped stale `agentex-sdk[obs]` references from the template comments — that
extra does not exist; sgp-obs is the agent's own dependency.

No behaviour change: all 38 templates still render as jinja, all 138 RUN bodies still
pass `sh -n`, every template still carries the mount and the ticket reference.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: stephen-wang24

src/agentex/lib/cli/templates/PRIVATE_INDEX.md

@@ -0,0 +1,62 @@
+# The private package index in scaffold Dockerfiles
+
+Every scaffold Dockerfile mounts a build secret named `codeartifact-pip-conf`. It lets an agent
+install Scale-internal packages — `sgp-obs`, for instance — that are not on public PyPI, without the
+build holding any registry credential of its own. The control-plane broker mints a short-lived
+CodeArtifact token per build and injects it as that secret.
+
+- Design: [Private Package Access for Customer Agents (PRD)](https://app.notion.com/p/Private-Package-Access-for-Customer-Agents-PRD-3ad904d6e6cb802cb091df1c25e230bc)
+- Tracking: [SGPINF-1568](https://linear.app/scale-epd/issue/SGPINF-1568/provide-scale-internal-packages-to-agentex-agents-in-customer)
+
+## It is inert by default
+
+The mount is `required=false` and guarded by `[ -s ... ]`, so with no secret injected the build is
+byte-identical to one without any of this. That covers every local build, every CI build, and every
+agent that never opts in. An empty secret file is skipped too.
+
+## Opting in
+
+Add the index to the agent's `pyproject.toml`:
+
+```toml
+[[tool.uv.index]]
+name = "scale-pypi"
+url = "<the scale-customer-pypi URL>"
+default = true
+```
+
+The name must be exactly `scale-pypi`. uv applies `UV_INDEX_SCALE_PYPI_USERNAME` /
+`UV_INDEX_SCALE_PYPI_PASSWORD` to the index of that name, so renaming it makes the credentials
+silently stop applying. Setting `UV_INDEX_URL` instead does not authenticate a *named* index at
+all, and the resolve fails with a 401.
+
+## Three things that are easy to get wrong
+
+**The token arrives percent-encoded.** The buildspec URL-encodes it to embed it in the pip config's
+URL userinfo, so a token containing `+`, `/` or `=` arrives as `%2B`, `%2F`, `%3D`. The `uv sync`
+templates decode it before exporting it as a password. Passing it through still-encoded sends a
+different string and the resolve 401s.
+
+**The credential must not follow project-controlled configuration.** uv binds credentials by index
+*name*, and the name-to-URL mapping would otherwise come from the agent's own `pyproject.toml` — so a
+project that pointed `scale-pypi` at another host would receive the token. Verified against a local
+server: the rogue host receives `Authorization: Basic aws:<token>` and the real index is never
+contacted. The templates therefore export `UV_INDEX` to re-bind the name to the URL the *broker*
+supplied, which overrides whatever the project declared. With that in place the rogue host is never
+contacted. The pinned URL carries no userinfo; the token still travels only in
+`UV_INDEX_SCALE_PYPI_PASSWORD`.
+
+The case this defends is not a malicious agent author — they also write the Dockerfile and could read
+the mounted secret directly. It is a *contributed* change to a project file, where a one-line URL edit
+is far less conspicuous in review than an exfiltration command in a Dockerfile.
+
+**The two template variants work differently, deliberately.**
+
+| Template | Install step | How the credential is supplied |
+| --- | --- | --- |
+| `Dockerfile-uv.j2` | `uv sync` against the agent's `pyproject.toml` | Named index `scale-pypi`, pinned via `UV_INDEX`, token decoded into `UV_INDEX_SCALE_PYPI_PASSWORD` |
+| `Dockerfile.j2` | `uv pip install -r requirements.txt` | No pyproject is present, so there is no named index to bind to. The credentialed URL is used directly via `UV_DEFAULT_INDEX` |
+
+The `requirements.txt` variant does **not** decode the token, and that is the point: it stays inside
+the URL, already encoded for exactly that use. Decoding it there would corrupt it. It is also not
+exposed to the redirection problem above, because the URL comes wholly from the injected secret.

src/agentex/lib/cli/templates/default-claude-code/Dockerfile-uv.j2

@@ -34,31 +34,12 @@ WORKDIR /app/{{ project_path_from_build_root }}
 COPY {{ project_path_from_build_root }}/pyproject.toml ./
 
 # Install dependencies (without project itself, for layer caching)
-# Optional private index for `agentex-sdk[obs]` and other Scale-internal packages
-# (TEAM-RUNBOOK / SGPINF-1568). Inert unless the control-plane broker injects the
-# secret, so local builds, CI builds, and agents that never opt in are unaffected.
+# Optional private index for Scale-internal packages such as sgp-obs, injected by the
+# control-plane broker (SGPINF-1568). Inert unless the secret is present, so local
+# builds, CI builds, and agents that never opt in are unaffected.
 #
-# To opt in, add this to the agent's pyproject.toml. The index name must be exactly
-# `scale-pypi`, because that is what binds the credentials exported below; rename it
-# and they silently stop applying. Exporting UV_INDEX_URL instead does not
-# authenticate a named index at all, and the resolve 401s.
-#
-#   [[tool.uv.index]]
-#   name = "scale-pypi"
-#   url = "<scale-customer-pypi URL from TEAM-RUNBOOK>"
-#   default = true
-#
-# UV_INDEX re-binds that name to the URL the BROKER supplied, overriding whatever URL
-# the project declared for it. Without this the credential follows the name wherever
-# pyproject.toml points it: uv sends the token to any host declared under the name
-# `scale-pypi`, so a one-line edit to a project file — far less conspicuous in review
-# than a change to this Dockerfile — would exfiltrate it. Verified both ways against a
-# local server: without UV_INDEX the rogue host receives `Basic aws:<token>`; with it
-# the rogue host is never contacted. The URL carries no userinfo; the token travels
-# only in UV_INDEX_SCALE_PYPI_PASSWORD.
-#
-# The token is percent-decoded on the way out: the buildspec URL-encodes it into the
-# pip config's URL userinfo, so a token containing + / = arrives as %2B %2F %3D.
+# To opt in, and for why UV_INDEX is pinned to the broker's URL rather than trusting
+# the project's, see PRIVATE_INDEX.md in the agentex-sdk CLI templates directory.
 RUN --mount=type=cache,target=/root/.cache/uv \
     --mount=type=secret,id=codeartifact-pip-conf,required=false \
     if [ -s /run/secrets/codeartifact-pip-conf ]; then \

src/agentex/lib/cli/templates/default-claude-code/Dockerfile.j2

@@ -33,15 +33,12 @@ COPY {{ project_path_from_build_root }}/requirements.txt /app/{{ project_path_fr
 
 WORKDIR /app/{{ project_path_from_build_root }}
 
-# Optional private index for `agentex-sdk[obs]` and other Scale-internal packages
-# (TEAM-RUNBOOK / SGPINF-1568). Inert unless the control-plane broker injects the
-# secret, so local builds, CI builds, and agents that never opt in are unaffected.
+# Optional private index for Scale-internal packages such as sgp-obs, injected by the
+# control-plane broker (SGPINF-1568). Inert unless the secret is present.
 #
-# This template installs from requirements.txt, so no pyproject.toml is present for
-# uv to read a named index out of — unlike Dockerfile-uv.j2, which uses the named
-# `scale-pypi` index. The credentialed URL is taken straight from the injected pip
-# config instead. That is also why nothing is percent-decoded here: the token stays
-# inside the URL, already encoded for exactly that use.
+# This variant installs from requirements.txt, so there is no pyproject.toml for uv to
+# read a named index out of; the credentialed URL is used directly and is deliberately
+# NOT decoded. See PRIVATE_INDEX.md in the agentex-sdk CLI templates directory.
 #
 # Install the required Python packages
 RUN --mount=type=secret,id=codeartifact-pip-conf,required=false \

src/agentex/lib/cli/templates/default-codex/Dockerfile-uv.j2

@@ -34,31 +34,12 @@ WORKDIR /app/{{ project_path_from_build_root }}
 COPY {{ project_path_from_build_root }}/pyproject.toml ./
 
 # Install dependencies (without project itself, for layer caching)
-# Optional private index for `agentex-sdk[obs]` and other Scale-internal packages
-# (TEAM-RUNBOOK / SGPINF-1568). Inert unless the control-plane broker injects the
-# secret, so local builds, CI builds, and agents that never opt in are unaffected.
+# Optional private index for Scale-internal packages such as sgp-obs, injected by the
+# control-plane broker (SGPINF-1568). Inert unless the secret is present, so local
+# builds, CI builds, and agents that never opt in are unaffected.
 #
-# To opt in, add this to the agent's pyproject.toml. The index name must be exactly
-# `scale-pypi`, because that is what binds the credentials exported below; rename it
-# and they silently stop applying. Exporting UV_INDEX_URL instead does not
-# authenticate a named index at all, and the resolve 401s.
-#
-#   [[tool.uv.index]]
-#   name = "scale-pypi"
-#   url = "<scale-customer-pypi URL from TEAM-RUNBOOK>"
-#   default = true
-#
-# UV_INDEX re-binds that name to the URL the BROKER supplied, overriding whatever URL
-# the project declared for it. Without this the credential follows the name wherever
-# pyproject.toml points it: uv sends the token to any host declared under the name
-# `scale-pypi`, so a one-line edit to a project file — far less conspicuous in review
-# than a change to this Dockerfile — would exfiltrate it. Verified both ways against a
-# local server: without UV_INDEX the rogue host receives `Basic aws:<token>`; with it
-# the rogue host is never contacted. The URL carries no userinfo; the token travels
-# only in UV_INDEX_SCALE_PYPI_PASSWORD.
-#
-# The token is percent-decoded on the way out: the buildspec URL-encodes it into the
-# pip config's URL userinfo, so a token containing + / = arrives as %2B %2F %3D.
+# To opt in, and for why UV_INDEX is pinned to the broker's URL rather than trusting
+# the project's, see PRIVATE_INDEX.md in the agentex-sdk CLI templates directory.
 RUN --mount=type=cache,target=/root/.cache/uv \
     --mount=type=secret,id=codeartifact-pip-conf,required=false \
     if [ -s /run/secrets/codeartifact-pip-conf ]; then \

src/agentex/lib/cli/templates/default-codex/Dockerfile.j2

@@ -33,15 +33,12 @@ COPY {{ project_path_from_build_root }}/requirements.txt /app/{{ project_path_fr
 
 WORKDIR /app/{{ project_path_from_build_root }}
 
-# Optional private index for `agentex-sdk[obs]` and other Scale-internal packages
-# (TEAM-RUNBOOK / SGPINF-1568). Inert unless the control-plane broker injects the
-# secret, so local builds, CI builds, and agents that never opt in are unaffected.
+# Optional private index for Scale-internal packages such as sgp-obs, injected by the
+# control-plane broker (SGPINF-1568). Inert unless the secret is present.
 #
-# This template installs from requirements.txt, so no pyproject.toml is present for
-# uv to read a named index out of — unlike Dockerfile-uv.j2, which uses the named
-# `scale-pypi` index. The credentialed URL is taken straight from the injected pip
-# config instead. That is also why nothing is percent-decoded here: the token stays
-# inside the URL, already encoded for exactly that use.
+# This variant installs from requirements.txt, so there is no pyproject.toml for uv to
+# read a named index out of; the credentialed URL is used directly and is deliberately
+# NOT decoded. See PRIVATE_INDEX.md in the agentex-sdk CLI templates directory.
 #
 # Install the required Python packages
 RUN --mount=type=secret,id=codeartifact-pip-conf,required=false \

src/agentex/lib/cli/templates/default-langgraph/Dockerfile-uv.j2

@@ -30,31 +30,12 @@ WORKDIR /app/{{ project_path_from_build_root }}
 COPY {{ project_path_from_build_root }}/pyproject.toml ./
 
 # Install dependencies (without project itself, for layer caching)
-# Optional private index for `agentex-sdk[obs]` and other Scale-internal packages
-# (TEAM-RUNBOOK / SGPINF-1568). Inert unless the control-plane broker injects the
-# secret, so local builds, CI builds, and agents that never opt in are unaffected.
+# Optional private index for Scale-internal packages such as sgp-obs, injected by the
+# control-plane broker (SGPINF-1568). Inert unless the secret is present, so local
+# builds, CI builds, and agents that never opt in are unaffected.
 #
-# To opt in, add this to the agent's pyproject.toml. The index name must be exactly
-# `scale-pypi`, because that is what binds the credentials exported below; rename it
-# and they silently stop applying. Exporting UV_INDEX_URL instead does not
-# authenticate a named index at all, and the resolve 401s.
-#
-#   [[tool.uv.index]]
-#   name = "scale-pypi"
-#   url = "<scale-customer-pypi URL from TEAM-RUNBOOK>"
-#   default = true
-#
-# UV_INDEX re-binds that name to the URL the BROKER supplied, overriding whatever URL
-# the project declared for it. Without this the credential follows the name wherever
-# pyproject.toml points it: uv sends the token to any host declared under the name
-# `scale-pypi`, so a one-line edit to a project file — far less conspicuous in review
-# than a change to this Dockerfile — would exfiltrate it. Verified both ways against a
-# local server: without UV_INDEX the rogue host receives `Basic aws:<token>`; with it
-# the rogue host is never contacted. The URL carries no userinfo; the token travels
-# only in UV_INDEX_SCALE_PYPI_PASSWORD.
-#
-# The token is percent-decoded on the way out: the buildspec URL-encodes it into the
-# pip config's URL userinfo, so a token containing + / = arrives as %2B %2F %3D.
+# To opt in, and for why UV_INDEX is pinned to the broker's URL rather than trusting
+# the project's, see PRIVATE_INDEX.md in the agentex-sdk CLI templates directory.
 RUN --mount=type=cache,target=/root/.cache/uv \
     --mount=type=secret,id=codeartifact-pip-conf,required=false \
     if [ -s /run/secrets/codeartifact-pip-conf ]; then \

src/agentex/lib/cli/templates/default-langgraph/Dockerfile.j2

@@ -29,15 +29,12 @@ COPY {{ project_path_from_build_root }}/requirements.txt /app/{{ project_path_fr
 
 WORKDIR /app/{{ project_path_from_build_root }}
 
-# Optional private index for `agentex-sdk[obs]` and other Scale-internal packages
-# (TEAM-RUNBOOK / SGPINF-1568). Inert unless the control-plane broker injects the
-# secret, so local builds, CI builds, and agents that never opt in are unaffected.
+# Optional private index for Scale-internal packages such as sgp-obs, injected by the
+# control-plane broker (SGPINF-1568). Inert unless the secret is present.
 #
-# This template installs from requirements.txt, so no pyproject.toml is present for
-# uv to read a named index out of — unlike Dockerfile-uv.j2, which uses the named
-# `scale-pypi` index. The credentialed URL is taken straight from the injected pip
-# config instead. That is also why nothing is percent-decoded here: the token stays
-# inside the URL, already encoded for exactly that use.
+# This variant installs from requirements.txt, so there is no pyproject.toml for uv to
+# read a named index out of; the credentialed URL is used directly and is deliberately
+# NOT decoded. See PRIVATE_INDEX.md in the agentex-sdk CLI templates directory.
 #
 # Install the required Python packages
 RUN --mount=type=secret,id=codeartifact-pip-conf,required=false \

src/agentex/lib/cli/templates/default-openai-agents/Dockerfile-uv.j2

@@ -30,31 +30,12 @@ WORKDIR /app/{{ project_path_from_build_root }}
 COPY {{ project_path_from_build_root }}/pyproject.toml ./
 
 # Install dependencies (without project itself, for layer caching)
-# Optional private index for `agentex-sdk[obs]` and other Scale-internal packages
-# (TEAM-RUNBOOK / SGPINF-1568). Inert unless the control-plane broker injects the
-# secret, so local builds, CI builds, and agents that never opt in are unaffected.
+# Optional private index for Scale-internal packages such as sgp-obs, injected by the
+# control-plane broker (SGPINF-1568). Inert unless the secret is present, so local
+# builds, CI builds, and agents that never opt in are unaffected.
 #
-# To opt in, add this to the agent's pyproject.toml. The index name must be exactly
-# `scale-pypi`, because that is what binds the credentials exported below; rename it
-# and they silently stop applying. Exporting UV_INDEX_URL instead does not
-# authenticate a named index at all, and the resolve 401s.
-#
-#   [[tool.uv.index]]
-#   name = "scale-pypi"
-#   url = "<scale-customer-pypi URL from TEAM-RUNBOOK>"
-#   default = true
-#
-# UV_INDEX re-binds that name to the URL the BROKER supplied, overriding whatever URL
-# the project declared for it. Without this the credential follows the name wherever
-# pyproject.toml points it: uv sends the token to any host declared under the name
-# `scale-pypi`, so a one-line edit to a project file — far less conspicuous in review
-# than a change to this Dockerfile — would exfiltrate it. Verified both ways against a
-# local server: without UV_INDEX the rogue host receives `Basic aws:<token>`; with it
-# the rogue host is never contacted. The URL carries no userinfo; the token travels
-# only in UV_INDEX_SCALE_PYPI_PASSWORD.
-#
-# The token is percent-decoded on the way out: the buildspec URL-encodes it into the
-# pip config's URL userinfo, so a token containing + / = arrives as %2B %2F %3D.
+# To opt in, and for why UV_INDEX is pinned to the broker's URL rather than trusting
+# the project's, see PRIVATE_INDEX.md in the agentex-sdk CLI templates directory.
 RUN --mount=type=cache,target=/root/.cache/uv \
     --mount=type=secret,id=codeartifact-pip-conf,required=false \
     if [ -s /run/secrets/codeartifact-pip-conf ]; then \

src/agentex/lib/cli/templates/default-openai-agents/Dockerfile.j2

@@ -29,15 +29,12 @@ COPY {{ project_path_from_build_root }}/requirements.txt /app/{{ project_path_fr
 
 WORKDIR /app/{{ project_path_from_build_root }}
 
-# Optional private index for `agentex-sdk[obs]` and other Scale-internal packages
-# (TEAM-RUNBOOK / SGPINF-1568). Inert unless the control-plane broker injects the
-# secret, so local builds, CI builds, and agents that never opt in are unaffected.
+# Optional private index for Scale-internal packages such as sgp-obs, injected by the
+# control-plane broker (SGPINF-1568). Inert unless the secret is present.
 #
-# This template installs from requirements.txt, so no pyproject.toml is present for
-# uv to read a named index out of — unlike Dockerfile-uv.j2, which uses the named
-# `scale-pypi` index. The credentialed URL is taken straight from the injected pip
-# config instead. That is also why nothing is percent-decoded here: the token stays
-# inside the URL, already encoded for exactly that use.
+# This variant installs from requirements.txt, so there is no pyproject.toml for uv to
+# read a named index out of; the credentialed URL is used directly and is deliberately
+# NOT decoded. See PRIVATE_INDEX.md in the agentex-sdk CLI templates directory.
 #
 # Install the required Python packages
 RUN --mount=type=secret,id=codeartifact-pip-conf,required=false \