Document the private-skills credential contract of the kagent API v2 line: the tenant's Secret in the `kagent` namespace, no Harness credential, where the token is visible; verify the pinned kagent-crds serve `credentialRef` (D8/D17)

[teemow]

Part of epic giantswarm/giantswarm#37705 (kagent API v2 migration); the consequence of the spike giantswarm/giantswarm#37321 for this chart. Siblings: giantswarm/agent (the chart value), giantswarm/agent-manager, giantswarm/backstage.

Problem

The spike decided the credential for private skill repositories under kagent API v2: a per-source credential on the AgentTemplate (skills[].source.git.credentialRef, carried in the kagent line — giantswarm/kagent-upstream#13), not an ambient credential on the platform Harness. That settles what this chart does and does not do, and nothing says it yet:

• the connectivity chart's Harness values (Connectivity 4.0: one platform Harness per managed namespace — kagent type on the line's Go ADK digest, KAGENT_PROPAGATE_TOKEN in its environment, the meta chart's default WorkerPool, the snapshot location from values, admission by the label agent-platform.giantswarm.io/harness: kagent; WorkerPool replicas and pod template as values with lab-measured defaults (bumblebee-plans#51 D5) #344) carry no credential — by design, not by omission;
• the credential is the tenant's Secret in the kagent namespace (the templates compile in the Harness namespace, which is where this chart renders the platform Harnesses), key token, label ui.giantswarm.io/agent-skills-git-auth: "true"; the platform never provisions it;
• the token is a literal in the compiled ActorTemplate environment (Substrate accepts literal env only): visible to ate-api's callers and cluster admins, present in the actor's process environment and in the golden and FULL snapshots in the snapshot store until GC — an operator sizing access to ate-api and the snapshot bucket should know; the egress-side alternative (Substrate header injection) is on the upstream queue (giantswarm/giantswarm#37742 row 26);
• the kagent pin has to carry the patch: the field is served only from the line's release that includes feat(api): a per-source credential for private git skill and plugin sources kagent-upstream#13 (the re-pin itself is giantswarm/giantswarm#37010's).

Proposed solution

Documentation and a guard, no rendering change:

• README (the kagent API v2 section): "Private skill repositories" — who provisions the Secret, where (kagent), its shape and label, rotation (contents, never the name), what a missing Secret and a wrong token look like on the AgentTemplate (ResolvedRefs=False vs Ready=False ActorTemplatePending), and where the token is visible.
• A comment on the connectivity Harness values (kagent.harness) saying the Harness carries no credential and why.
• tests/verify-kagent-crds.py (or its successor) asserts the pinned kagent-crds serve skills[].source.git.credentialRef once the pin moves to the release that carries it, so a re-pin below it fails the verify instead of pruning the field silently.

Acceptance criteria

• README documents the credential contract and the Harness's non-involvement.
• The CRD verify asserts credentialRef on the pinned kagent-crds (added with the re-pin that first carries it).
• No change to the rendered Harness objects (make verify-kagent-harness unchanged).